server/backend/src/cq_server/app.py already exposes the FastAPI-generated OpenAPI document at /api/v1/openapi.json. There is no committed, versioned API contract artifact in the repo — first-party clients (CLI, MCP server, SDK) read URLs and shapes from code rather than from a single source of truth.
Add a checked-in OpenAPI 3.x JSON file covering the public API surface so consumers can pin against a stable contract and reviewers can see API changes in diffs.
Goals
- One OpenAPI JSON file in this repo, covering the public API surface
- Diffs of that file land in PRs whenever a route or schema changes — visible in code review
- CLI/MCP/SDK tooling could codegen against it
Scope of "public API surface"
Include:
- Knowledge operations (
/knowledge, /knowledge/{id}/confirmations, /knowledge/{id}/flags, /knowledge/stats)
- Users (
/users/me)
- API keys (
/users/me/api-keys/...)
- Auth (
/auth/login, /auth/refresh, /auth/logout — refresh/logout once they exist)
- OAuth (
/oauth/... — once they exist)
- Health (
/health)
Exclude:
- Admin/moderation routes (
/review/*) — currently internal to platform implementations
Path shapes assume the redesign in the sibling REST conventions issue has landed.
Approach
- Add a script (
scripts/generate-openapi.py or similar) that boots the FastAPI app in test mode, fetches the OpenAPI document, filters by router tag (knowledge, users, api-keys, auth, oauth, default for /health), and writes the result to a fixed path
- Commit the generated artifact at
schema/openapi.json (or docs/openapi.json — pick one and stick to it)
- CI step: regenerate and compare to the committed file; fail the build if they differ. Forces contributors to commit the regenerated spec when they change routes or schemas
- Optional follow-up: publish the artifact alongside each release tag
Open questions
- Filename location:
schema/openapi.json (matches the existing schema/ JSON convention) or docs/openapi.json?
- Filter mechanism: by router tag (cleanest if tags are kept current) or by explicit path allow-list (more brittle but unambiguous)?
- Versioning: one file per major version, or a single file that tracks current? Single file works while we're on
v1; revisit when v2 arrives.
Depends on
REST redesign issue (sibling). Sequencing the OpenAPI work after that lands keeps the first committed spec from being stale on day one.
server/backend/src/cq_server/app.pyalready exposes the FastAPI-generated OpenAPI document at/api/v1/openapi.json. There is no committed, versioned API contract artifact in the repo — first-party clients (CLI, MCP server, SDK) read URLs and shapes from code rather than from a single source of truth.Add a checked-in OpenAPI 3.x JSON file covering the public API surface so consumers can pin against a stable contract and reviewers can see API changes in diffs.
Goals
Scope of "public API surface"
Include:
/knowledge,/knowledge/{id}/confirmations,/knowledge/{id}/flags,/knowledge/stats)/users/me)/users/me/api-keys/...)/auth/login,/auth/refresh,/auth/logout— refresh/logout once they exist)/oauth/...— once they exist)/health)Exclude:
/review/*) — currently internal to platform implementationsPath shapes assume the redesign in the sibling REST conventions issue has landed.
Approach
scripts/generate-openapi.pyor similar) that boots the FastAPI app in test mode, fetches the OpenAPI document, filters by router tag (knowledge,users,api-keys,auth,oauth, default for/health), and writes the result to a fixed pathschema/openapi.json(ordocs/openapi.json— pick one and stick to it)Open questions
schema/openapi.json(matches the existingschema/JSON convention) ordocs/openapi.json?v1; revisit whenv2arrives.Depends on
REST redesign issue (sibling). Sequencing the OpenAPI work after that lands keeps the first committed spec from being stale on day one.