[camerontarget14]

Summary

Makes the backend API usable by someone outside the project (e.g. a ShotGrid or AYON tooling developer) without reading the source. The OpenAPI document now documents itself, and the docs site gets hand-written guide pages around the generated reference.

Backend (spec is self-documenting; /docs, /redoc and the site all benefit)

• New dna/openapi_schema.py layers onto the generated spec:
  • x-tagGroups splitting endpoints into Production Tracking (proxy the provider; DNA stores nothing) and DNA (DNA's own storage).
  • A description on every opaque-ID parameter (project_id, version_id, user_email, ...), injected centrally.
  • A uniform 401 on every authenticated operation, and an error_responses() helper so routes declare the 4xx/5xx they raise. All error bodies reference a new ErrorResponse model ({"detail": ...}).
• main.py: API description and every tag description rewritten to say what proxies the tracking provider vs. what DNA stores. New Publishing and Project Glossary tags; glossary/publish routes retagged. Longer descriptions on publish-notes, draft PUT, find, generate-note, run-qc-checks.
• json_schema_extra examples on ~50 schemas, all using one fictional production (project 124, version mk020_0010_comp_v003, sam.reviewer@studio.example) so examples agree across endpoints.
• test_openapi_spec.py now asserts: every tag is in exactly one group, every secured op has a 401, every parameter is described, every documented error body is ErrorResponse. These fail if a route is added without documenting it, which is the point.

Docs site

• Spec copy was three weeks stale (integer IDs, missing endpoint). npm run build:full now runs fetch-openapi first so it cannot drift again.
• Hand-written Authentication, Concepts, Errors and Real-time pages (the last covers the /ws and extension-ingest WebSockets, which are not in OpenAPI). Landing page rewritten as a first-request walkthrough.
• Reference sidebar grouped by tag group.
• API explorer code samples trimmed to cURL, Python, JavaScript, C, Rust, Go; bash Prism grammar loaded so shell blocks highlight.

Caught up with main (merged in twice; one README conflict resolved in favour of the fetch-openapi build step)

• Add Zoom support for Vexa transcription bots #224 Zoom: second DispatchBotRequest example; bot route notes Zoom needs meeting_url and the passcode only works as the link's pwd.
• Link published notes to their transcript in ShotGrid #233 transcript links: publish-notes and the Concepts walkthrough say the Note is linked to the version's newest transcript row (best effort), and the walkthrough publishes the transcript before the notes.
• feat(transcription): per-user language setting for the Vexa bot #236 transcription language: transcription_language in the user-settings examples; DispatchBotRequest.language documented as an ISO 639-1 code from GET /transcription/languages; that route gets an example and its 400.
• Docs/GitHub pages #240 GitHub Pages: no changes needed; the workflow already calls build:full.

Testing

• I have tested these changes locally
• I have run all relevant automated tests
• I have verified this does not break existing workflows
• For changes that can be tested in UI, I have included screenshots or gif animations of the changes.

How I Tested

1. cd backend && .venv/bin/python scripts/export_openapi.py — regenerated docs/openapi.json from the merged code (41 paths, 58 schemas).
2. .venv/bin/python -m pytest tests/test_openapi_spec.py tests/test_user_settings.py tests/test_transcription_languages_endpoint.py — 39 passed, including the new spec guards and the drift test.
3. cd dna-docs && npm run build:full — fetch, regenerate and build succeed with onBrokenLinks: 'throw'.
4. The API explorer renders examples client-side, so I decoded the zlib+base64 api: front matter of the generated api/reference/*.api.mdx for publish-notes, transcription/bot, transcription/languages and user-settings PUT, and confirmed the new descriptions, examples (language: "en", transcription_language: "en", Zoom second example) and error statuses are present.

🤖 Generated with Claude Code