# StellarFirm API versioning and limits

> The StellarFirm API version header, compatibility and deprecation policy, request limits, and how agents should retry.

The public [StellarFirm API](/docs/api) uses header versioning. This policy covers the five operations in the [OpenAPI document](https://stellarfirm.ai/openapi.json), rather than the private routes used by the workspace.

## Selecting a version

Send `API-Version: 1`. The header is optional; an omitted header selects version 1 for existing clients. Each documented operation confirms `API-Version: 1` on its response. An unsupported version returns `400` with `error.code: invalid_request` before the operation runs.

```sh
curl -i https://stellarfirm.ai/api/health -H 'API-Version: 1'
```

The OpenAPI document's `info.version` versions the description itself. `API-Version` selects the API's major version. Additive fields and new operations can arrive within a major version. Clients should ignore fields they do not know. Removing a field, changing its type, or changing a route's meaning requires a new major version. The default stays at version 1 until its published retirement date.

## Deprecation and retirement

No public operation is currently deprecated. Responses link this policy with `Link: <https://stellarfirm.ai/docs/api/policy>; rel="deprecation"; type="text/html"`.

Before retiring a version or operation, StellarFirm will publish a migration guide here and announce its retirement at least 90 days ahead. Affected responses will carry `Deprecation` as a structured date (an `@` followed by Unix seconds, [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)), and `Sunset` as an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)). The sunset date will be at least 90 days after the announcement and no earlier than the deprecation date. Existing behavior continues through that window. Urgent security fixes may restrict unsafe behavior immediately.

## Request limits and retries

`GET /api/health` allows 120 requests per 60 seconds per client address. It uses a sliding counter shared across server instances when the shared store is configured. On local development without that store, the counter is per process. Addresses are hashed before storage. If the counter store is unavailable, health checks continue; reported remaining quota is zero until the counter recovers.

The public [MCP server](/docs/getting-started/mcp-server) separately allows 60 JSON POST requests per 60 seconds per address, shared between `/mcp` and `/api/mcp`. The other documented REST operations have no additional application quota under this policy. Infrastructure and account safeguards may still apply.

Both limited surfaces return these fields on counted responses, including a `429`:

| Header | Meaning |
| --- | --- |
| `RateLimit-Policy` | A quoted policy name with `q` requests and `w` seconds, such as `"health";q=120;w=60`. |
| `RateLimit` | The same quoted name and remaining quota, such as `"health";r=119`. On refusal, `t` gives seconds before retrying. |
| `RateLimit-Limit` | Compatibility field: the request allowance for the window. |
| `RateLimit-Remaining` | Compatibility field: requests still available for this caller. |
| `Retry-After` | On `429`, a positive integer number of seconds to wait before retrying. |

`RateLimit` and `RateLimit-Policy` follow the work in progress [IETF quota-header draft](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-11), `draft-ietf-httpapi-ratelimit-headers-11`; they are not a published RFC. `Retry-After` follows HTTP semantics. Successful sliding-counter responses omit `t` because the counter does not expose a reset time. Quota responses are not cached. The MCP server exposes these headers to browser clients through CORS.

Wait at least `Retry-After` seconds on a `429`, add a small random delay, and reduce polling. Remaining quota is a snapshot, not a reservation. Do not assume every response carries quota headers or that another request is guaranteed to succeed.

---

Source: https://stellarfirm.ai/docs/api/policy