> 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 your [environment base URL](/developers/environments). 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, 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.

**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, so 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, and treat unknown codes as generic failures.

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

Verify the signature, acknowledge fast, and ignore event types you don't consume.