Google Analytics, Vercel Web Analytics, Leadsy and the TikTok Pixel stay off until you accept. The help chat starts once you have chosen. The scheduling button starts once you have chosen. Read our Privacy Policy.
The public StellarFirm API uses header versioning. This policy covers the five operations in the OpenAPI document, rather than the private routes used by the workspace.
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.
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.
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), and Sunset as an HTTP date (RFC 8594). 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.
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 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, 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.