# OpenAPI Specification

> Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: `chengflow/openapi.yaml`, `chengflow/Makefile`, `crates/cheng-api/src/rest/routes.rs`

`chengflow/openapi.yaml` is an OpenAPI 3.0.3 specification of the REST API, and the Makefile
turns it into Swagger UI, Redoc, a Postman collection, generated SDKs, Markdown reference, and
contract tests.

**Read this first: the spec is a curated subset, not the whole API.** It documents 28 paths —
auth, workspaces, files, conversations, workflows, executions, nodes, system endpoints, and
workflow-template sync — while the running server exposes considerably more, including channels,
documents, tables, skills, schedules, artifacts, and code index. For anything outside those
tags, [the REST API overview](/docs/api-rest-overview) and `rest/routes.rs` are authoritative.

## What the spec declares

```yaml
openapi: 3.0.3
info:
  title: Cheng-Workflow API
  version: 1.0.0
servers:
  - url: http://localhost:19225        # local development
  - url: https://api-staging…         # staging
  - url: https://api…                 # production
security:
  - BearerAuth: []                    # http bearer, JWT
```

`BearerAuth` applies globally, so every generated client sends the Authorization header by
default. See [Authentication](/docs/api-authentication).

Tags: `auth`, `workspaces`, `files`, `conversations`, `workflows`, `executions`, `nodes`,
`system`.

The described quickstart is the real one:

```text
1. POST /api/v1/auth/login       → token
2. POST /api/v1/workflows        → create
3. POST /api/v1/executions       → run
4. WS   /ws/executions/{id}      → subscribe
```

Shared parameters `Offset` and `Limit` are defined once and reused, so pagination is consistent
across the documented endpoints.

## Generating

```bash
make openapi        # regenerate openapi.yaml from code
make docs           # openapi + swagger + redoc + postman + sdk + markdown
make docs-validate  # lint the spec
make docs-serve     # browse at :8000
make docs-clean     # remove generated output, including openapi.yaml
```

`make check-deps` verifies `cargo`, `npm`, and `docker` are present; `make install-tools`
installs `utoipa-cli`, `@redocly/cli`, `openapi-to-postmanv2`, and `widdershins`.

**`make docs-clean` deletes `openapi.yaml` itself**, not only the rendered output. If you have
hand-edited the spec, that removes your edits.

Generation uses `utoipa-cli` over `crates/cheng-api/src/lib.rs`, so annotated handlers are the
source. Handlers without annotations do not appear — which is the mechanical reason the spec is
partial.

## What you can generate from it

| Target | Produces |
|---|---|
| `make swagger` | Swagger UI in `docs/swagger-ui/` |
| `make redoc` | A single-page Redoc HTML in `docs/redoc/` |
| `make postman` | `docs/postman/collection.json` plus a local environment file pointing at `http://localhost:19225` |
| `make sdk` | TypeScript (`typescript-axios`), Python, and Rust clients under `docs/sdk/` |
| `make markdown` | `docs/API_REFERENCE_AUTO.md` via widdershins |

Swagger UI, Redoc, and the SDK generators run in Docker, so they need a working Docker daemon,
not just Node.

The generated TypeScript client is `@cheng/workflow-client`, Python is `cheng_workflow`, Rust is
`cheng-workflow-client`.

For a browser chat or gateway integration, prefer the hand-written
[SDK](/docs/sdk-api-reference) over a generated client: it also handles the WebSocket protocol,
session mapping, and token refresh, none of which an OpenAPI generator can produce.

## Contract testing

```bash
make test-api       # schemathesis against a running server
make test-postman   # newman over the generated collection
```

`test-api` runs `schemathesis` with all checks against `http://localhost:19225`, 20 generated
examples per operation. It is property-based: it derives requests from the schema and checks the
responses conform, so it finds the mismatches between spec and implementation that a hand-written
test suite would not think to try.

Both need a running server. `test-api` will exercise real endpoints, so **point it at a
development instance, not production**.

## Using the spec elsewhere

```bash
# Any OpenAPI-aware client
curl -s http://localhost:19225/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"…","password":"…"}'
```

Import `openapi.yaml` into Insomnia, Bruno, or your API gateway; generate a mock server;
validate requests at the edge. The spec is a plain file with no ChengOS-specific extensions.

## Keeping it honest

The spec is checked in, which means it can drift from the code. Three habits keep it useful:

1. **Regenerate rather than hand-edit.** `make openapi` reads the annotated handlers; a manual
   edit is lost on the next regeneration and, worse, may not match reality in the meantime.
2. **Run `make docs-validate`** after regenerating — the Redocly linter catches structural
   problems before a client generator turns them into broken code.
3. **Run `make test-api` against a development server** when you change a documented handler.
   That is the only step that compares the spec with the running system.

## Next steps

- [REST API Overview](/docs/api-rest-overview) — the full endpoint surface.
- [Authentication](/docs/api-authentication) — the `BearerAuth` scheme in practice.
- [WebSocket API](/docs/api-websocket) — the half OpenAPI cannot describe.