> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Versioning and compatibility

The API version lives in the URL path. The version marker is the **`/v1`** prefix, appended to the [base URL](/paperwork/developers/overview#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 `2xx` so 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 `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.**

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.

## Building a client that lasts

#### [Errors](/developers/errors)

Branch on the HTTP status first, the error code second. Treat unknown codes as generic failures.

#### [Webhooks](/developers/webhooks)

Verify the signature, acknowledge fast, and ignore event types you do not consume.