Versioning

Every endpoint lives under a /v1 base path (for example, POST /v1/projects). The /v1 is a promise: we'll keep it working. This reference documents API v1.0 — the version string the API publishes as info.version in its OpenAPI document. This page explains what that promise covers and how to write a client that keeps working as the API grows.

/v1 is additive-only

The rule is simple: inside /v1, we only ever make backward-compatible changes — things that add, never things that break. That's what lets a generated agent or a mobile client you shipped last year keep running without a surprise.

Allowed (additive) — these can show up in /v1 at any time:

• new endpoints;
• new optional response fields;
• a new value appended to a closed enum only when every documented consumer already treats the enum as open / has a default branch;
• new optional request parameters with safe defaults.

Breaking — these require a brand-new version (like /v2), never an edit to /v1:

• removing or renaming a field or endpoint;
• changing a field's type, or making an optional field required;
• removing an enum value, or changing what an existing one means.

If we ever need to make a breaking change, it ships as a new versioned surface alongside /v1 — we never change /v1 out from under you.

Build a forward-compatible client

Because new fields, endpoints, and error codes can appear at any time, write your client to shrug those off:

• Ignore response fields you don't recognize — don't error out on a field you weren't expecting.
• Keep a default branch whenever you switch on an enum value or an error code, so a new value degrades gracefully instead of crashing.
• Pin to /v1 in your base URL. A future /v2, if one ever ships, is something you opt into on your own schedule — never a surprise upgrade.

We back this up: the enum values in the docs come straight from the server's own constants and are checked in CI. So an accidental breaking change — deleting an enum value the API still sends, or renaming one — fails our build instead of reaching you.

Back-compat path rewrite

For older clients, a narrow server-side rewrite still accepts the old unversioned paths: /projects works as an alias for /v1/projects, so integrations written before /v1 existed keep running. For anything new, always use the explicit /v1 prefix.

The OpenAPI document is the source

This whole reference is generated from a committed snapshot of the live GET /openapi/v1.json document — the API's own machine-readable description of itself. When the API gains an endpoint or a field and the snapshot is refreshed, the pages, schemas, auth badges, and code samples all update themselves; nothing here is hand-edited per endpoint. You can confirm the version a server is running any time with GET /v1/meta (its apiVersion).

Source of truth: the versioning rule is single-sourced in the repo at docs/api-contract.md §4; this page renders it for developers.