API conventions

Every block’s HTTP API shares the conventions on this page. A block’s own API reference documents what is specific to it — its routes, bodies and error codes — and assumes everything here.

Paths are not versioned

Runtime HTTP paths carry no version segment. There is no /v1/, and a documentation URL under /1.1.6/ does not imply one on the service.

/data/rest/...        not  /data/v1/rest/...
/config/...           not  /config/v1/...

Versioning is a property of the release you deployed, not of the URL. See version applicability on any API page for the release it describes.

Exceptions

The AI blocks are the exception: ai-bot, ai-memory and ai-eval carry /v1/ on their tenant routes and /admin/v1/ on their control plane. That is a path prefix separating audiences, not a contract version — /v1/ there does not promise a /v2/ will follow, and it is not the release number.

Read each block’s API page rather than inferring a rule from one of them.

Tenancy

Every request is scoped by a CPET — customer, product, environment, tenant. It is carried in four headers:

Header	Names
X-Customer	The customer
X-Product	The product
X-Env	The environment
X-Tenant	The tenant

A service runs in one of three tenancy modes, which decides whether those headers are required:

Mode	Behaviour
multi	All four are required. This is the normal deployment
single	The service is pinned to one CPET; the headers are not read
none	The service is not tenant-scoped

A bearer token also establishes the CPET, so a request carrying one may not need to send the headers separately — which of the two applies is per service, and each block’s API page says so.

Caution

Tenancy is resolved before your handler runs. A missing or malformed tenant fails the request in middleware, and middleware failures are plain text, not the JSON envelope below. A client that unconditionally JSON-decodes error bodies breaks on exactly these cases.

Authentication

Most routes require a bearer token:

Authorization: Bearer <token>

Some services additionally accept API keys, and some expose deliberately anonymous routes. Both are per service — the block’s API page lists which of its routes are anonymous, authenticated, administrative or superadmin-only.

Tokens come from IAM. See IAM for how to obtain and refresh one.

Not every service uses bearer tokens. vault.svc authenticates workloads by mTLS client certificate and config.svc accepts an API key, a bearer token or mTLS. Check the block’s own API page rather than assuming.

The error envelope

Handler and service errors use one shape:

{
  "error": {
    "code": "config-key-not-found",
    "message": "the requested key does not exist",
    "context": null,
    "meta": null
  }
}

Field	Meaning
code	A stable string to branch on. Empty on many errors — see the caution below
message	Human-readable. Not stable; do not match on it
context	Internal detail. Often {} or null
meta	Extra structured detail when the handler supplies it

When tracing is enabled, trace_id, span_id, request_id and correlation_id appear alongside them, and those are the handles to quote in a support request.

Caution

Branch on status first, then on code, and only then parse. Three things break naive clients: code is empty on many errors; middleware failures (auth, tenancy, timeout) return plain text rather than this envelope; and an unmatched path returns no body at all.

Where a service has no stable code for a failure, its API page marks that surface as unsafe for deterministic automation.

Health and readiness

Every service exposes two unauthenticated probes:

Route	Answers
GET /<service>/health	Whether the process is alive, with dependency status
GET /<service>/ready	Whether it is ready to serve

{
  "healthy": true,
  "dependencies": {},
  "version": ""
}

Note

The health response also carries a memstats object — Alloc, HeapAlloc, NumGC and friends, in megabytes. That is runtime diagnostics, not a contract. It reflects the process’s memory allocator, its field set follows the runtime rather than any API promise, and nothing should be built on it. Read healthy and dependencies.

version is whatever the service set at startup. Most set nothing, so it is usually the empty string — do not use it to detect a release.

/ready reporting true does not always mean the service can do useful work — a service may register its routes before it has loaded the configuration or rule sets it serves. Where that gap exists, the block’s operations page says so.

Rate limiting

Rate-limited responses carry their own shape rather than the envelope above:

{"error": "rate_limited", "profile": "<profile>", "retry_after_seconds": 30}

Honour retry_after_seconds.

See also

• Blocks — the capability map
• IAM — tokens, API keys, roles
• Data API — the most fully specified example of these conventions
• Glossary — CPET, tenant, product and the rest of the vocabulary