---
title: "API Deprecation Policy"
description: "How AINative signals API version and endpoint deprecation, notice periods, and the Deprecation/Sunset HTTP headers used during the transition period."
canonical: "https://docs.ainative.studio/docs/api/deprecations"
last-updated: "2026-10-28T06:34:16.301Z"
---

# API Deprecation Policy

Source: https://docs.ainative.studio/docs/api/deprecations

> How AINative signals API version and endpoint deprecation, notice periods, and the Deprecation/Sunset HTTP headers used during the transition period.

# 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](/docs/api/models#deprecated-model-ids) 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](/docs/api/models#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."