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 /api alias#

You may see unversioned /api/... paths in older integrations. They are the same endpoints and they are permanent - nothing is being taken away.

Two differences worth knowing:

• Some /api list endpoints return a bare array rather than the

{items, total, limit, offset} envelope, frozen for compatibility.

• /api is not documented here and is not covered by the stability promise above.

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.