# Versioning (/docs/api/versioning)

The public API is the datafile (`GET /config/**`), the analytics endpoint (`POST /api/log`) and the [agent API](/docs/api/agents) (`/api/agent/*`). It is version `1`. Every response from it carries the version in a header:

```http
Api-Version: 1
```

To pin the version your client was written against, send the same header on the request. It's optional: without it, a request gets the version of its path. A version the API doesn't serve is refused with a `400` [`unsupported_api_version`](/docs/api/errors#unsupported_api_version) problem rather than answered with another version.

```http
GET /config/org_01H8XYZ/production HTTP/1.1
Api-Version: 1
token: <environment API token>
```

`Api-Version` isn't a CORS-safelisted header, so browsers that send it cross-origin trigger a preflight. `POST /api/log` allows it; the datafile answers no preflight, so don't send it to the datafile from a browser.

The other `/api/*` routes belong to the dashboard. They are not versioned and can change at any time, so don't integrate against them.

## Stable paths [#stable-paths]

The current paths have no version prefix, and they are version 1. A breaking change ships under a new path prefix (`/v2/config/...`) next to the current paths, never in place. Both run side by side until the old version's sunset date.

## What can change without notice [#what-can-change-without-notice]

Additive changes can ship at any time and are not breaking:

- new endpoints
- new optional request fields
- new response fields, headers or error codes
- new values for `params` and other open-ended fields

Clients should ignore fields and headers they don't recognize, and treat an unknown error `code` like its HTTP status.

## What counts as breaking [#what-counts-as-breaking]

Removing or renaming an endpoint, a field or a header, making an optional field required, or changing the meaning or type of an existing field. These only ship in a new version.

## Deprecation [#deprecation]

When an endpoint is going away, its responses start sending two headers, and its operation is marked `deprecated` in the [OpenAPI spec](/openapi.json):

| Header        | Standard                                           | Value                                                       |
| ------------- | -------------------------------------------------- | ----------------------------------------------------------- |
| `Deprecation` | [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | When the endpoint was deprecated, e.g. `@1767225600`        |
| `Sunset`      | [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | When it stops working, e.g. `Thu, 01 Jul 2027 00:00:00 GMT` |
| `Link`        | [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) | `rel="deprecation"` pointing at the migration guide         |

The sunset date is at least 6 months after the deprecation date. Deprecations are also listed in the [change log](/docs/change-log).

Browser clients can read all of these cross-origin: they are listed in `Access-Control-Expose-Headers`.

## Rate limit headers [#rate-limit-headers]

Rate limits follow the IETF [RateLimit header fields draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/).

### Datafile [#datafile]

The datafile's browser (Origin) path sends:

```http
RateLimit-Policy: "browser";q=600;w=60
```

Every browser response says the quota (`q`, requests) per window (`w`, seconds) per IP. A `429` adds the current state and when to retry:

```http
RateLimit: "browser";r=0;t=60
Retry-After: 60
```

Successful responses don't carry `RateLimit`: they are cached at the edge for 30 seconds and shared between clients, so a per-IP count on them would be wrong for most readers. Server requests with a valid `token` header are not held to this policy and get no rate limit headers. The edge limit of 100 requests per 10 seconds per IP ([Datafile](/docs/api/datafile#rate-limiting)) applies to every request and answers its `429` without these headers.

### Agent account endpoints [#agent-account-endpoints]

The [agent API](/docs/api/agents)'s account endpoints limit attempts per email address, reset token or user, and state the policy on every response. The `/api/agent/auth/*` ones are served by `www.obelism.studio` (Improve redirects them there) with the same policies:

| Endpoint                               | Policy                         | Counted per |
| -------------------------------------- | ------------------------------ | ----------- |
| `POST /api/agent/apply`                | `"apply";q=3;w=3600`           | email       |
| `POST /api/agent/auth/sign-up`         | `"sign-up";q=3;w=3600`         | email       |
| `POST /api/agent/auth/sign-in`         | `"sign-in";q=5;w=60`           | email       |
| `POST /api/agent/auth/forgot-password` | `"forgot-password";q=3;w=3600` | email       |
| `POST /api/agent/auth/reset-password`  | `"reset-password";q=5;w=300`   | reset token |
| `POST /api/agent/auth/verify-email`    | `"verify-email";q=5;w=900`     | user        |

Every attempt restarts the window, so a `429` always resets in the full window:

```http
RateLimit-Policy: "sign-in";q=5;w=60
RateLimit: "sign-in";r=0;t=60
Retry-After: 60
```

Other responses carry the policy only, not a remaining count.
