API
Versioning
How the Improve API is versioned, what counts as a breaking change, and how a deprecation is announced.
The public API is the datafile (GET /config/**), the analytics endpoint (POST /api/log) and the agent API (/api/agent/*). It is version 1. Every response from it carries the version in a header:
Api-Version: 1To 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 problem rather than answered with another version.
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
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
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
paramsand 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
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
When an endpoint is going away, its responses start sending two headers, and its operation is marked deprecated in the OpenAPI spec:
| Header | Standard | Value |
|---|---|---|
Deprecation | RFC 9745 | When the endpoint was deprecated, e.g. @1767225600 |
Sunset | RFC 8594 | When it stops working, e.g. Thu, 01 Jul 2027 00:00:00 GMT |
Link | RFC 8288 | 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.
Browser clients can read all of these cross-origin: they are listed in Access-Control-Expose-Headers.
Rate limit headers
Rate limits follow the IETF RateLimit header fields draft.
Datafile
The datafile's browser (Origin) path sends:
RateLimit-Policy: "browser";q=600;w=60Every browser response says the quota (q, requests) per window (w, seconds) per IP. A 429 adds the current state and when to retry:
RateLimit: "browser";r=0;t=60
Retry-After: 60Successful 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) applies to every request and answers its 429 without these headers.
Agent account endpoints
The agent API'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 | |
POST /api/agent/auth/sign-up | "sign-up";q=3;w=3600 | |
POST /api/agent/auth/sign-in | "sign-in";q=5;w=60 | |
POST /api/agent/auth/forgot-password | "forgot-password";q=3;w=3600 | |
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:
RateLimit-Policy: "sign-in";q=5;w=60
RateLimit: "sign-in";r=0;t=60
Retry-After: 60Other responses carry the policy only, not a remaining count.