Versioning and compatibility
The API version lives in the URL path. The version marker is the /v1 prefix, appended to the base URL. Endpoints documented without a version prefix are unversioned and keep working unchanged. The compatibility rules on this page apply to them too.
The header x-cloudraker-version is reserved. It is not active today. Sending it changes nothing. It is held for a future dated, per-account API version scheme. When that arrives, a request without the header keeps the behaviour your account is pinned to.
Changes we make without a new version
The following are non-breaking by definition. They can ship at any time. A well-behaved client must not break on them:
- New fields in responses. Ignore fields you do not recognise. Never fail on an unexpected key.
- New event types on webhooks. Ignore events you do not handle. Keep returning
2xxso delivery is not 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
defaultbranch over an exhaustiveswitch. - New id prefixes, and changes to existing id prefixes. See below.
- New endpoints, new optional request fields, new optional query parameters.
A change that removes or renames a field is breaking. So is a change to a field’s type, the removal of an endpoint, or making an optional request field required. Breaking changes ship 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. Do not split it. Do not read a prefix or infer a type, a tenant, or a timestamp from it.
- Prefixes may change. Many ids carry a short type prefix (for example
exr_…). Prefixes help humans read logs. They are not a contract. We can add them to ids that had none and change them on ids that had one. - Store the whole string. Give id columns room for 255 characters and compare them byte for byte.
Installed actions accept an id or a slug. Anywhere the API takes an installed-action id, its per-organization slug (for example medical-notes) works identically. Slugs are chosen per organization and can be renamed. Store the id if you need a stable handle.