Versioning and stability#

What /v1 promises#

• Fields are added, never renamed or removed.
• An endpoint's meaning does not change under you.
• Enum values may gain members - verdict, reject_reason, event names and error codes are all append-only.

So: ignore fields you do not recognise, and handle unknown enum values gracefully. Clients that parse strictly break on additive changes that are not breaking changes.

A genuinely breaking change would ship as /v2 alongside /v1, not in place.

Deprecation#

If something must be retired:

1. It is announced in the changelog and marked deprecated in the schema.
2. It keeps working for at least 12 months.
3. Responses carry a Deprecation header with the sunset date.

Nothing on /v1 is currently deprecated except POST /v1/debates/{id}/upload-youtube, which is an alias of upload-media and works identically.

The retired /api alias#

Older integrations may still call unversioned /api/... paths. That alias has been removed: every endpoint now lives under /v1 only, and /api/... is no longer served - an authenticated request there returns 404.

Migrating is a prefix change and nothing more - /api/debates became /v1/debates, with the same method, parameters and behaviour. The one response difference to expect is that a handful of list endpoints used to return a bare JSON array on /api and now return the standard {items, total, limit, offset} envelope described in Pagination.

New code should use /v1.

Not covered by the promise#

The diagnostics endpoints - /v1/queue, /v1/claims/pipeline, /v1/diagnose/{claim_id}, /v1/diagnose/dropped-claims - are documented so you can debug why a claim produced nothing, but they expose the internal pipeline's shape and may change without notice.

Use them to investigate. Do not build a dashboard on them; build that on /v1/claims/{id}/results.