Public API — overview

The Cavaridge™ public API is a versioned REST surface. Every customer-facing product exposes the same conventions.

Versioning

• URL path version — /v1/.... Breaking changes cut a new version; v1 lives until at least 12 months past v2 GA.
• Tenant-pinned at server side — your tenant’s effective API version is read from tenantConfig.api_version, falling back to URL.
• Per-page front-matter versions: { since, until } documents when the page was accurate.

Auth

• Bearer token in Authorization: Bearer <token>.
• Tokens are scoped to a tenant. To act in a child tenant (MSP→client), use X-Tenant-Id: <child_tenant_id> if your role permits.
• All requests over TLS. Plain HTTP returns 426 Upgrade Required.

Idempotency

POST / PATCH requests accept Idempotency-Key: <uuid>. Re-sending the same key within 24 hours returns the cached response — even if the original request errored at the network layer. Required for write operations triggered by webhooks.

Errors

Errors return a typed envelope:

{
  "error": {
    "code": "tenant_not_found",
    "message": "No tenant matches that ID for the current bearer token.",
    "request_id": "req_01HX...",
    "doc_url": "https://docs.cavaridge.app/api/errors/tenant-not-found/"
  }
}

request_id is the only thing we need from a support ticket.

Rate limits

• Standard: 600 req/min per tenant.
• Bulk endpoints: 60 req/min.
• AI gateway: per-tenant cap configured via tenantConfig.

429 responses include Retry-After (seconds) and X-RateLimit-Reset (Unix timestamp).

Conventions

• IDs — typed prefixes (ten_, usr_, scn_). Opaque to clients.
• Timestamps — ISO 8601 UTC.
• Pagination — cursor-based (cursor + limit, max 100), never offset.
• Field names — snake_case in JSON.

Coming next

Per-product reference pages land as each surface stabilizes its v1. See Reference for the current map.