Skip to content

/v1 API versioning & stability policy

How the DocGen Platform API evolves, and what integrators can rely on.

The version

The public REST surface is versioned in the URL path: every endpoint lives under /v1. The OpenAPI document (openapi-v1.json) carries a semantic info.version (currently 1.0.0) describing the contract revision within v1.

  • Path version (/v1) — changes only on a breaking redesign, which ships as a new prefix (/v2) running alongside /v1 for a deprecation window.
  • Contract version (info.version) — bumped as the /v1 surface evolves compatibly. Read it from the committed openapi-v1.json, which is the authoritative contract. (The live service's /docs renders the full running app — /v1 plus internal /bridge, /health, and dev-login routes, under docgen.server's own default metadata — so it does not serve this /v1-only contract or its info.version.)

What counts as breaking

A change is breaking (and will not land inside /v1) if it:

  • removes or renames an endpoint, path parameter, or query parameter;
  • removes a response field, or changes its type;
  • adds a newly required request field, or tightens validation on an existing one;
  • changes an HTTP status code or error shape for an existing condition;
  • changes the meaning of an existing progress SSE event.

A change is compatible (may land inside /v1, bumping the minor/patch of info.version) if it:

  • adds a new endpoint;
  • adds an optional request field, or a new response field;
  • adds a new progress SSE event type (clients must ignore unknown events);
  • relaxes validation, or fixes a bug so behaviour matches this documentation.

Integrator rule: ignore unknown JSON fields and unknown SSE event values. New ones will appear within v1 without a breaking bump.

Deprecation

When an endpoint or field is slated for removal, it is:

  1. marked deprecated: true in the OpenAPI schema and noted in the changelog;
  2. kept working for a deprecation window of at least one minor release;
  3. removed only in a new path version (/v2), never mid-v1.

The committed contract is the source of truth

docs/reference/openapi-v1.json is generated from the code by docgen/scripts/export_openapi.py and guarded by a drift test (docgen/tests/unit/test_openapi_export.py): any change to a /v1 route, request/response model, or summary that isn't re-exported fails CI. So the committed schema can never silently diverge from what the service serves.

Response-schema coverage (current limitation). Paths, request bodies, status codes, and the bearer security scheme are fully typed in the artifact. Response payloads are concretely modeled only for an initial set of endpoints (GET /whoami, POST …/generate); the rest export as an open object, so the drift test guards their routes, request models, and summaries — not every response field. Full response-schema coverage is tracked in #362.

To regenerate after an intended change:

cd docgen && uv run python scripts/export_openapi.py

Then bump API_VERSION in scripts/export_openapi.py per the rules above, add a changelog entry, and commit.

Known follow-ups

  • Machine-to-machine (M2M) auth — not yet available on /v1; tracked as issue #352. See v1-api.md.
  • Full response-schema coverage — most /v1 responses currently export as an open object; concrete response models for the rest are tracked as issue #362.