Reference
Versioning & deprecation
/v1 is a stable public contract. Every response shape documented in JSON schemas is versioned by that V1 suffix (GenerateResponseV1, JobV1, UsageResponseV1, ErrorResponseV1, WebhookPayloadV1) — the suffix is the version, not just a naming convention.
What counts as non-breaking
These changes can ship to /v1 at any time without a version bump:
- Adding a new optional request field.
- Adding a new optional response field.
- Adding a new error code for a genuinely new failure mode.
- Loosening a validation constraint (e.g. raising a length limit).
- Adding a new endpoint.
What counts as breaking
These require a new version (/v2) rather than an in-place change to /v1:
- Removing or renaming a request or response field.
- Changing a field’s type or meaning.
- Making a previously-optional field required.
- Changing an error code’s HTTP status mapping.
- Changing the webhook signature scheme or payload shape.
- Tightening a validation constraint in a way that would reject previously-valid requests.
Deprecation & sunset
When a field or endpoint is deprecated, it keeps working — deprecation is an announcement, not an immediate removal. A deprecated field is documented as such here and continues to be populated/accepted for a minimum communicated notice period before removal in a subsequent major version. Sunset timelines and migration guidance for any deprecated surface are published on this page and, where practical, surfaced via response headers on the affected endpoint.
Today
There is currently no /v2 and nothing on /v1 is deprecated. This page exists so that changes, when they do happen, have a clear, pre-established policy to follow rather than being decided ad hoc.