API Deprecation Policy

AINative versions its API by URL path (/api/v1/, /v1/, and future /api/v2/). This page states, in plain terms, how we signal that a version or endpoint is going away, and what you can rely on as an integrator or agent.

How deprecation is signaled

1. Advance notice published in these docs. Before any API version or endpoint is deprecated, we publish notice on this page (and on the specific endpoint's reference page, e.g. the Model Catalog for model-level deprecations). We do not silently remove or change the behavior of a versioned endpoint without a published notice first. AINative does not yet run a single cross-platform changelog feed — this docs site is the source of truth for deprecation notices today.
2. Deprecation and Sunset HTTP headers on the endpoint itself. Once an endpoint is in its deprecation window, responses from that endpoint carry standard headers (see below) so your client or agent can detect the deprecation programmatically — you don't have to watch the changelog to find out.
3. A named replacement, every time. A deprecation notice always names the endpoint or version you should migrate to. AINative does not retire an endpoint without pointing you to what replaces it. This mirrors the model-deprecation policy already in place for the model catalog (see Deprecated Model IDs): a deprecated model returns an honest model_deprecated error naming a live alternative rather than silently substituting a different model. The same honesty principle applies to endpoints — you get a clear signal and a real alternative, never a silent behavior change.

Notice period

We aim for a minimum 30-day notice period between publishing a deprecation and the endpoint's sunset date, and longer for anything with broad integration surface. This number is deliberately conservative and matches our real operating history: recent internal deprecations in this codebase (admin-path consolidation, legacy database paths) have used 30-day windows, and model deprecations have typically been resolved within weeks of a provider announcing end-of-life. We are not committing to a longer SLA than we've actually run in practice — if a specific deprecation needs a longer runway (for example, a full API major version like a future /api/v2/), we'll say so explicitly in that deprecation's notice.

During the notice period, the deprecated endpoint continues to work as before — you get warned, not broken.

Deprecation / Sunset headers

This mechanism already exists in the API today for endpoints in an active deprecation window. A request to a deprecated path returns:

Header	Meaning
Deprecation	true — this endpoint is deprecated
Sunset	The date the endpoint stops working (RFC 8594), e.g. 2026-04-01
Link	<replacement-path>; rel="alternate" — the endpoint to migrate to
Warning	Human-readable deprecation message and migration guidance

Example:

HTTP/1.1 200 OK
Deprecation: true
Sunset: 2026-04-01
Link: </api/v1/users/>; rel="alternate"; title="Replacement endpoint"
Warning: 299 - "Deprecated: Admin-specific user endpoints are deprecated. Use /api/v1/users/ with role-based access. Sunset date: 2026-04-01."

Check for the Deprecation header on any response as a matter of course — an agent or client that does this will always find out about a retiring endpoint before the sunset date arrives, even if it never reads a changelog.

What happens at sunset: once the sunset date passes, the endpoint is removed and returns 410 Gone with a JSON body naming the replacement path — it does not start returning wrong or substituted data.

What this policy does not promise

This is a small, honest policy, not an elaborate versioning framework:

• We are not committing to supporting every API version indefinitely.
• We are not promising a fixed cadence of version releases.
• We are promising that you will always get advance notice, a named replacement, and machine-readable headers during the transition — never a silent break or a silent substitution.

If you're building an agent or integration against this API, the reliable pattern is: check for the Deprecation response header, and treat its presence as "this still works today, but migrate before the Sunset date."