> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dexi.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Deprecation

> How Dexi's API is versioned, how deprecations are announced, and how to self-throttle with rate-limit headers

## Versioning

The API is versioned in the URL path: `/api/v1/…` and `/api/v2/…`. The version prefix is part of the contract — endpoints documented on this site are stable within their major version:

* **No breaking changes within a version.** Fields may be *added* to responses; existing fields keep their names and types. Treat unknown response fields as forward-compatible additions.
* **Breaking changes ship as a new path version.** The old version keeps working through its deprecation window.
* Undocumented `/api/*` endpoints belong to the Dexi app's own session-authenticated API and carry **no stability promise** — build only against what's documented here and in the [OpenAPI spec](https://dexi.net/openapi.json).

## Deprecation policy

When a documented endpoint is scheduled for removal:

1. Its responses gain a `Deprecation` header, and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the removal date — **at least 6 months out**.
2. This page lists the deprecation, its replacement, and a migration note.
3. After the sunset date the endpoint returns `410 Gone` with a JSON `detail` pointing at the replacement.

Nothing is currently deprecated.

## Rate limits

Rate-limited endpoints return the draft-RFC rate-limit headers ([draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)) on **every** response, so clients can self-throttle instead of discovering limits by hitting them:

| Header                | Meaning                                                           |
| --------------------- | ----------------------------------------------------------------- |
| `RateLimit-Limit`     | Requests allowed in the current window                            |
| `RateLimit-Remaining` | Requests left in the current window                               |
| `RateLimit-Reset`     | Seconds until the window resets                                   |
| `RateLimit-Policy`    | The policy, e.g. `"120;w=60"` — 120 requests per 60-second window |

Exceeding a limit returns `429` with a `Retry-After` header (seconds) and a JSON body:

```json theme={null}
{
  "detail": {
    "code": "rate_limited",
    "message": "Too many requests — slow down and try again shortly.",
    "retry_after": 12
  }
}
```

Wait `Retry-After` seconds before retrying; don't retry in a tight loop.

## Errors

All errors are JSON with a top-level `detail` — a plain string on simple errors, or a structured object with a machine-readable `code`, human-readable `message`, and context fields:

```json theme={null}
{
  "detail": {
    "code": "not_found",
    "message": "No such API endpoint.",
    "hint": "The public REST surface is documented at https://docs.dexi.net …"
  }
}
```

Known codes: `not_found`, `rate_limited`, and `note_limit` (see [Save a bookmark](/api/save-bookmark) for the `note_limit` shape). Validation failures return `422` with FastAPI's standard `detail` array. The full error model is typed in the [OpenAPI spec](https://dexi.net/openapi.json).