Versioning and compatibility

The API version lives in the URL path: the version marker is the /v1 prefix, appended to your environment base URL. Endpoints documented without a version prefix are unversioned and keep working unchanged — the compatibility rules on this page apply to them too.

Changes we make without a new version

The following are non-breaking by definition. They can ship at any time, and a well-behaved client must not break on them:

• New fields in responses. Ignore fields you don’t recognise; never fail on an unexpected key.
• New event types on webhooks. Ignore events you don’t handle, and keep returning 2xx so delivery isn’t retried.
• New values in an enum — status values, kinds, error codes. Handle an unknown value as “something new”, never as a fatal error. Prefer a default branch over an exhaustive switch.
• New id prefixes, and changes to existing id prefixes. See below.
• New endpoints, new optional request fields, new optional query parameters.

Anything that removes or renames a field, changes a field’s type, removes an endpoint, or makes a previously optional request field required is breaking, and ships under a new version — never in place.

Ids are opaque

Every id the API returns — files, runs, actions, webhooks, spaces, records — is an opaque string of at most 255 characters.

• Never parse an id. Don’t split it, don’t read a prefix, don’t infer a type, a tenant, or a timestamp from it.
• Prefixes may change. Many ids carry a short type prefix (for example exr_…). Prefixes are a readability aid for humans reading logs, not a contract — they can be added to ids that had none and changed on ids that had one.
• Store the whole string. Give id columns room for 255 characters and compare them byte for byte.

Building a client that lasts