---
title: Developer docs, OpenAPI operation ids and machine-readable twins
description: New /docs site generated from the OpenAPI spec, operationIds on every operation, x-scopes and x-webhooks in the spec, markdown twins and llms.txt.
canonical_url: "https://cascades.crscreditapi.com/docs/changelog/2026-09-09-docs-platform"
doc_version: "1.0.0"
last_updated: "2026-09-23T19:55:02Z"
source: docs/changelog/2026-09-09-docs-platform.md
---

# Developer docs, OpenAPI operation ids and machine-readable twins

## What changed

- **A docs site at `/docs`.** Concepts, guides, compliance notes and a reference page per endpoint, all rendered from `docs/**` and the OpenAPI spec. Signed-in readers see their own sandbox key in every sample and can run requests from the page.
- **Every operation has an `operationId`** (`triggerWorkflow`, `getExecution`, …). The id is the slug of the operation's reference page and the name the MCP manifest and code samples use.
- **Scopes, idempotency and polling are declared in the spec** as `x-scopes`, `x-idempotent` and `x-async`, and rendered as badges. The nine operations the MCP server wraps carry `x-mcp` with the tool definition.
- **Webhook events are in the spec** under a root `x-webhooks` key shaped like OpenAPI 3.1 `webhooks`, one entry per event with its payload schema and an example. They render under [/docs/api/webhooks](/docs/api/webhooks).
- **The spec documents what the API does today**: the previously missing `POST /workflows`, `PATCH`/`DELETE /workflows/{id}`, `POST /workflows/generate` and `GET /workflows/{id}/test_cases`; `422 missing_idempotency_key`; `429` with the JSON envelope and `Retry-After`; `adverse_action.retry_scheduled`; the split between `Execution` and `ExecutionFull`.
- **Machine-readable twins.** Append `.md` to any docs URL or send `Accept: text/markdown` for clean markdown; `/openapi.json` and `/openapi.yaml` serve the spec; `/llms.txt` indexes the site for agents.
- **Error responses carry `doc_url`** pointing at `/docs/api/errors/<code>`.

## What you may need to do

Nothing changes in request or response bodies. If you generate a client from the spec, regenerate it to pick up the operation ids — method names will change from generated defaults to the documented ids.

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.