Skip to Content

API

Versioning

How the Improve API is versioned, what counts as a breaking change, and how a deprecation is announced.

3 min read

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: 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 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 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

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:

HeaderStandardValue
DeprecationRFC 9745When the endpoint was deprecated, e.g. @1767225600
SunsetRFC 8594When it stops working, e.g. Thu, 01 Jul 2027 00:00:00 GMT
LinkRFC 8288rel="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=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:

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) 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:

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

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: 60

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

On this page

Marks in the margin

  • Note
  • Watch out
  • Updated

Scribes marked doubtful lines in the margin. That practice is called obelism.