Hono API Specification — LumiBase

For AI agents: This page is also available as clean Markdown. Append /index.md to any LumiBase docs URL.

Base URL: https://api.<your-site>.lumibase.dev (or http://localhost:1989 in local dev)

All endpoints are versioned under /api/v1. Every request must include:

• Authorization: Bearer <token> — login token, or an API key (lbk_…)
• X-Lumi-Site: <siteId> — site identifier (or resolved via subdomain routing)

Response envelope

All responses follow this structure:

{
  "data": <T>,
  "meta": {
    "total": 123,
    "page": 1,
    "pageSize": 50,
    "filter_count": 50
  }
}

Error response:

{
  "errors": [
    {
      "code": "PERMISSION_DENIED",
      "message": "You don't have permission to read field 'secret'.",
      "path": ["fields", "secret"],
      "extensions": { "reason": "field_policy" }
    }
  ]
}

Error codes

Standard query parameters (list endpoints)

Full-text search is a separate endpoint, GET /api/v1/search (MeiliSearch), not a list-endpoint parameter. It supports single-collection and cross-collection (omit collection) queries and is diacritics-insensitive for Vietnamese. See features/search.md.

Filter operators

Searching inside JSON. A filter field key may be a dotted path into a nested JSON/JSONB field — e.g. filter={"metadata.author.country":{"_eq":"VN"}} compiles to a data #>> '{metadata,author,country}' lookup. Path segments are restricted to [A-Za-z0-9_] and bound as parameters (injection-safe); depth is capped at 8. The _json_contains / _has_* operators run against the JSONB and use the existing GIN index. Top-level keys and structural fields behave exactly as before.

Filter forms

List endpoints accept the filter query parameter in two equivalent forms — use whichever is more convenient. Both produce the same filter object server-side.

1. Bracket form — ergonomic for hand-written URLs and HTML forms:

GET /api/v1/items/articles?filter[status][_eq]=published&filter[views][_gte]=100

• Nesting maps directly: filter[field][_op]=value.
• Values are coerced: true/false → boolean, null → null, clean integers/decimals → number (leading-zero strings like 007 stay strings), everything else → string.
• Array operators (_in, _nin, _between) accept comma-separated values: filter[status][_in]=published,scheduled.
• Logical groups use an index segment: filter[_and][0][status][_eq]=published.

2. JSON form — better for complex/programmatic filters and the SDK:

GET /api/v1/items/articles?filter={"status":{"_eq":"published"}}

If both are supplied on the same request, the JSON form wins. A malformed JSON filter returns 400 VALIDATION; a malformed bracket key is ignored rather than failing the whole request.

1. Auth

Cookie-sourced /auth/refresh + /auth/logout require the X-LumiBase-Refresh header (CSRF brake). Refresh tokens are delivered both as an httpOnly cookie and in the response body; see docs/en/security/user-management.md §4d for per-realm TTLs and the cross-domain cookie env (REFRESH_COOKIE_SAMESITE/_DOMAIN/_SECURE).

Account erasure (GDPR Art. 17) and Subject Access Requests are served by the regulated-content-readiness feature at /api/v1/admin/erasure and /api/v1/admin/sar.

Consent management (:type ∈ marketing · analytics · personalization · functional · sale_share):

// PUT /api/v1/me/consents/marketing
{ "granted": true, "source": "preference_center", "version": "v1" }

// Response
{ "data": { "consentType": "marketing", "granted": true,
            "grantedAt": "2026-06-24T10:00:00.000Z", "withdrawnAt": null,
            "source": "preference_center", "version": "v1",
            "updatedAt": "2026-06-24T10:00:00.000Z" } }

Each change writes a consent_granted / consent_withdrawn audit event. Only user principals (not API keys) can manage consent. Current state is stored per (site_id, user_id, consent_type) in user_consents; full history lives in the audit log.

Email unsubscribe & suppression (CAN-SPAM):

The unsubscribe token is a stateless HS256 JWT ({ siteId, email }, no expiry) signed with JWT_SECRET. Marketing sends (EmailModuleService.send({ category: 'marketing' })) filter recipients against email_suppressions before dispatch. Unsubscribe/suppression changes audit email_unsubscribed / email_suppressed / email_unsuppressed.

Preferences & save action. PATCH /api/v1/me/preferences shallow-merges a validated patch into users.preferences (other sections like language / keybindings are preserved). Send { "saveAction": "stay" | "return" | "create_new" } to set the Studio editor's post-save navigation; send { "saveAction": null } to fall back to the site default (sites.default_save_action, set via PATCH /api/v1/site). Invalid enum → 400.

External JWT authentication

A site can trust JWTs issued by an external IdP (Okta, Entra, Auth0, Logto, Keycloak, Cloudflare Access…). Present the token as Authorization: Bearer <jwt> with X-Lumi-Site. The auth chain verifies it against the issuer's public JWKS (between the API-key and internal-JWT branches): it matches the token's iss to a trusted issuer registered for that site, verifies the signature + aud/exp/nbf with the issuer's allowed (asymmetric-only) algorithms, maps role claims to LumiBase roles (default-deny — no mapping means 403, never implicit admin), enforces that any siteId claim equals the request site, and optionally JIT-provisions the user. A token whose iss isn't trusted is ignored (falls through to internal auth); once an issuer matches, verification is fail-closed.

Admin CRUD for trusted issuers (admin-only):

Issuer config: { issuer, jwksUri | discoveryUrl, audience, algorithms (RS*/ES* only), claimMapping: { email, roles, siteId?, externalId? }, roleMapping: { "<claim role>": { roleId | systemKey } }, defaultRoleId?, jitProvisioning, clockSkewSeconds (≤300), enabled }. Errors: VALIDATION_FAILED (422, incl. an HS*/none algorithm), ISSUER_ALREADY_EXISTS (409), NOT_FOUND (404).

Login request:

{
  "email": "admin@example.com",
  "password": "your-password"
}

Login response: a single bearer token plus the user profile. Send the token as Authorization: Bearer <token> on subsequent requests.

{
  "data": {
    "token": "eyJ...",
    "user": {
      "id": "usr_abc123",
      "email": "admin@example.com",
      "firstName": "Admin",
      "lastName": "User",
      "avatar": null
    }
  }
}

For long-lived server-to-server access, create an API key (POST /api/v1/api-keys, token prefix lbk_) instead of using a login token.

2. Schema Admin

Collections

Create collection request:

{
  "name": "articles",
  "displayName": "Articles",
  "icon": "article",
  "note": "Blog articles",
  "singleton": false,
  "status_field": "status",
  "sort_field": "sort"
}

Fields

Create field request:

{
  "field": "title",
  "type": "string",
  "interface": "input",
  "display": "raw",
  "options": { "placeholder": "Article title" },
  "required": true,
  "sort": 1
}

Relations

Code-First Configuration (Config Manifest)

Export / diff / apply a site's schema configuration — collections, fields, relations, settings and webhooks — as a single declarative, version-controllable JSON manifest (lumibase.config@v1). Built for CI/CD and environment sync (à la Directus schema snapshot/apply). Admin-only. Does not include content items, secrets, or access control (use /api/v1/access/* for the latter).

mode ∈ merge (create/update only — never deletes), replace-managed (also deletes resources within the manifest's managedScopes), replace-all (full sync — deletes anything absent from the manifest). High-risk destructive changes (dropping a collection/field with data, changing a field type, widening a relation's onDelete to cascade) are rejected unless allowDestructive=true.

Export response ({ data: ConfigManifest }):

{
  "data": {
    "version": "lumibase.config@v1",
    "exportedAt": "2026-06-22T00:00:00.000Z",
    "collections": [{ "name": "articles", "label": "Articles", "versioning": true }],
    "fields": [{ "collection": "articles", "field": "title", "type": "string", "interface": "input" }],
    "relations": [],
    "webhooks": [],
    "settings": [{ "key": "login_security_policy", "value": { } }],
    "managedScopes": ["articles"]
  }
}

Dry-run / apply response ({ data: { valid, errors, diff, applied? } }): the diff lists per-resource create | update | unchanged | delete counts and a top-level risk (low | medium | high). On apply, applied reports { created, updated, deleted }. Validation errors use codes UNSUPPORTED_MANIFEST_VERSION, DANGLING_REFERENCE, DUPLICATE_KEY; a blocked destructive apply returns HTTP 409 DESTRUCTIVE_BLOCKED.

CLI: pnpm --filter @lumibase/cms config export|diff|apply — see docs/en/contributing/code-first-config.md.

3. Items (Generic CRUD)

Dependent records. Because item references live in JSONB (not physical FK columns), a relation's onDelete is enforced in the application layer. On DELETE, if a relation declared restrict still has records pointing at the item, the delete is blocked with 409 DEPENDENT_RECORDS_EXIST and a dependents array. (set null/cascade are not auto-applied on soft-delete — that would break soft-delete's recoverability; the editor clears them explicitly.) GET …/dependents returns { data: { blocking, dependents: [{ relation, collection, field, onDelete, count, sample }] } }. POST …/resolve-dependents takes { action: "set_null"|"delete"|"reassign", relation, newTargetId?, hard? } and runs transactionally (delete delegates to the normal item-delete path). Errors: DEPENDENT_RECORDS_EXIST (409), FIELD_REQUIRED (409, set_null on a required field), INVALID_TARGET (422, reassign), NOT_FOUND (404).

List pagination & totals. GET /items/:collection accepts limit (1–200, default 25), offset, and meta:

• meta=total_count (default) — response is { data, meta: { total, limit, offset } }.
• meta=none — skips the count(*) aggregate for a cheaper query; response is { data, meta: { limit, offset } } (no total). Use for infinite-scroll / feed views that never render a total page count.

The default is unchanged, so existing clients keep receiving meta.total. The @lumibase/sdk readItems accepts the same meta option.

Optional headers:

• X-Lumi-Draft: true — fetch draft version
• X-Lumi-Locale: vi — apply translation server-side

Create item:

{ "title": "Hello World", "status": "draft", "author": "usr_abc123" }

Bulk create (array body):

[
  { "title": "Article 1", "status": "published" },
  { "title": "Article 2", "status": "draft" }
]

3b. Content Releases

A Release collates specific item revisions across collections into a named bundle that publishes all at once — manually or scheduled for a date/time (à la Directus Releases). Publish delegates to the item update path, so the editorial gate, validation, permissions and hooks all apply.

Create / patch body:

{
  "name": "Spring launch",
  "atomicityMode": "all_or_nothing",
  "publishAt": "2026-07-01T09:00:00Z",
  "maintenanceWindow": { "windows": [{ "dow": 1, "start": "09:00", "end": "17:00" }] },
  "addItems": [
    { "collection": "articles", "itemId": "itm_1", "targetStatus": "published", "revisionId": "rev_3" }
  ]
}

atomicityMode: all_or_nothing (pre-flight checks every item is publishable — exists, not deleted, editorial gate satisfiable — and publishes nothing if any is blocked) or best_effort (publishes each independently, recording a per-item outcome). revisionId pins a specific revision's snapshot; omit it to publish the item's live state at publish time.

Publish response ({ data: { release, status, outcomes } }): status is published | partially_failed | failed; each outcome is { collection, itemId, outcome: 'published'|'skipped'|'failed', reason? }. A partial/failed publish still returns HTTP 200 with the outcomes.

Error codes: EMPTY_RELEASE (422), ALREADY_PUBLISHED (409), RELEASE_IMMUTABLE (409, editing a published release's items), ITEM_NOT_FOUND (404), REVISION_STAGED (409, pinning an uncommitted revision), VALIDATION_FAILED (422, incl. publishAt in the past). Per-item publish blockers surface as outcome reasons EDITORIAL_GATE_REQUIRED / ITEM_DELETED.

Scheduled releases publish via the shared content-scheduler tick (sweepDueReleases) — idempotent and maintenanceWindow-aware.

4. Permissions, Roles & Policies

Permission rule shape:

{
  "collection": "articles",
  "action": "read",
  "fields": ["id", "title", "status"],
  "conditions": { "status": { "_eq": "published" } }
}

5. Users & Teams

6. Files & Assets

Image transform DSL (/api/v1/media/:key and /api/v1/assets/:id):

?width=800&height=600&format=webp&quality=80&fit=cover&focal=0.5,0.5
?preset=thumbnail

On /media/:key, transform params are validated against transformDslSchema (@lumibase/shared; MAX_DIM=5000) and the request 302-redirects to the runtime image URL (CF Image Resizing / Imgproxy). No params → the original bytes. ?preset=<key> resolves a saved transform_presets row for the site. See .kiro/specs/image-transform-dsl.

Upload policy (/api/v1/uploads/config). Enforced by the file-upload-policy guard on every upload surface (POST /api/v1/files, PUT /api/v1/files/upload/:key, POST /api/v1/media/:key): a public role cannot upload; the body is size-capped on its true byte length; the declared MIME must be in the allowlist and match the filename extension; raw bytes are content-sniffed (magic bytes) and executables / active-content SVGs are rejected; raster images are scanned for an embedded script/executable payload (polyglot) and rejected. The allowlist + cap resolve per-site DB (settings key upload_policy) → env (FILE_UPLOAD_*) → default. See the feature spec .kiro/specs/upload-file-controls/ and docs/en/security/runtime-security-guards-plan.md §3 for the full guarantees.

GET  /api/v1/uploads/config
→ { data: { maxBytes, allowedMimeTypes[], allowedExtensions[], catalogue[] } }

PUT  /api/v1/uploads/config           # site admin only
{ "maxBytes": 5242880, "allowedMimeTypes": ["image/png","image/jpeg"] }

6b. View presets (collection views + bookmarks)

Scope is derived from ownership columns: userId set → user, roleId set → role, neither → global. Role presets inherit down the roles.parentId chain. See .kiro/specs/presets-inheritance.

6c. Translation memory

TM_DEFAULT_THRESHOLD = 75 (@lumibase/shared). Learn-TM (Studio) upserts human translations on save when translations.learnTm is enabled. See .kiro/specs/translation-memory-ui.

7. Flows / Automation

Save-time gates: an active flow must pass the shared graph validation — 400 with GRAPH_DANGLING_EDGE / GRAPH_CYCLE / GRAPH_NO_ENTRY / GRAPH_UNKNOWN_OPERATION (+ nodeId) otherwise; drafts may hold invalid work-in-progress. Schedule flows validate triggerOptions.cron (5-field, UTC): 400 CRON_INVALID on a malformed expression, 400 CRON_REQUIRED when activating without one; next_run_at is computed on save and advanced by the scheduler sweep before each enqueued run (idempotent).

Triggers: event flows fire on item create/update/delete via the flow-events queue (triggerOptions.collection / .action filter, string or array, missing = all); schedule flows are swept every scheduler tick; webhook flows use the endpoint above; manual runs inline via /run.

Trigger a flow:

POST /api/v1/flows/flw_abc123/run
Content-Type: application/json
Authorization: Bearer <token>

{ "userId": "usr_xyz", "action": "welcome" }

Response:

{
  "data": {
    "runId": "run_def456",
    "status": "running",
    "startedAt": "2026-06-07T00:00:00Z"
  }
}

8. AI Copilot

Chat request:

{ "message": "Create a collection called 'products' with title, price, and status fields" }

Safe skill response:

{
  "data": {
    "status": "executed",
    "data": { "collectionName": "products", "fieldsCreated": 3 }
  }
}

HITL required (dangerous skill) response:

{
  "data": {
    "status": "pending_approval",
    "approvalId": "apr_ghi789",
    "message": "Creating a collection requires admin approval."
  }
}

Decide on an approval:

{ "decision": "approved" }

Agent API (Content OS)

All routes mount under the authenticated chain; the token's roles are the capability set.

9. Realtime (WebSocket)

Endpoint: wss://api.<your-site>.lumibase.dev/api/v1/realtime

Auth (ticket exchange): browsers cannot send Authorization on the WS handshake, so exchange the session for a short-lived (1 min) ticket first: POST /api/v1/realtime/ticket (studio) or POST /api/v1/realtime/audience-ticket (end-user), then connect:

wss://...realtime?ticket=<ticket>

The studio ticket embeds the collections the principal can read; the hub rejects any other subscribe with { "type": "error", "code": "SUBSCRIBE_FORBIDDEN" }.

Subscribe to collection (optional Directus-style filter, evaluated server-side over the event envelope collection/action/itemId):

{ "type": "subscribe", "collection": "articles", "filter": { "action": { "_eq": "delete" } } }

Server event — signal-only: no row data on the wire (clients re-fetch via /items, which enforces RBAC + field masking):

{ "type": "event", "collection": "articles", "action": "update", "itemId": "art_001", "payload": null }

Server notification frame (push-noti feature) — broadcast to every session for the site (not collection-scoped):

{ "type": "notification", "notification": { "id": "…", "kind": "approval", "severity": "info", "title": "…", "body": "…", "deepLink": "/mission-control/inbox?entry=approval:…", "entityId": "…", "ts": "2026-06-23T01:00:00Z" } }

See features/websockets-realtime.md for full protocol reference.

9b. Push notifications

Web Push (VAPID) + in-app realtime for agent events. Tenant-scoped; the VAPID key is a shared deployment resource. See features/push-notifications.md.

10. Settings

Site configuration

The active site's identity, branding and theme defaults live on the sites row (not the key/value settings table). Scoped to the active tenant via the X-Lumi-Site header.

PATCH /api/v1/site accepts any subset of: name, displayTitle, siteUrl, descriptor, domain, defaultLanguage, defaultAppearance (auto|light|dark), defaultSaveAction (stay|return|create_new — the site-wide default save action a user's personal preference overrides), branding ({ logoUrl, faviconUrl, brandColor }), themeOverrides ({ light, dark } maps of whitelisted CSS tokens → H S% L% values), and customCss. An empty string clears a nullable field. A duplicate domain returns 409 { errors: [{ code: 'DOMAIN_TAKEN' }] }.

Theme model: the site holds the global defaults; per-user appearance/theme/ language overrides (resolved client-side) take precedence.

10b. Regulated / sensitive content (admin)

Opt-in capability set (spec: regulated-content-readiness). All admin routes require the admin role; field-level decryption additionally requires the read_decrypted permission. Sensitive pii/phi field reads are recorded in field_access_log; decrypt failures fail closed (500 DECRYPTION_FAILED) and are audited — never a placeholder.

Encryption — keys & envelope mode

Key material lives only in the runtime KeyProvider (Workers Secrets / env: ENCRYPTION_KEY_<id> + ENCRYPTION_ACTIVE_KEY_ID); these surfaces record metadata + audit and drive migrations.

Editorial review → publish

Mounted at /api/v1/editorial. Per-collection toggle via collection meta.editorialWorkflow; meta.requireSeparateReviewer enforces a different reviewer than the author. Transitions audit editorial_transition.

GDPR erasure (dual-control)

Mounted at /api/v1/admin/erasure. Crypto-shreds (drops per-record DEK) or hard-deletes items + revisions while preserving the tamper-evident data_erased audit (no cascade). Dual-control via erasureDualControl setting.

Field access log & Subject Access Request

11. Extensions

Signing & official extensions. Every install/load path (marketplace install, generic CRUD POST /extensions, the dynamic endpoint mount, and hook dispatch) routes through a shared verifier. Detached Ed25519 signatures are checked against publisher keys resolved from MARKETPLACE_PUBLIC_KEYS (env) merged with the lumibase_publisher_keys table (DB overrides env for official/revoked). isOfficial is derived server-side (name in the lumibase- namespace and a signature by an official key) — never from a manifest claim. Official extensions are fail-closed: an unverifiable bundle never loads. Third-party enforcement follows LUMIBASE_EXT_SIGNATURE_POLICY (require default, or warn). The lumibase- namespace is reserved: community /marketplace/submit rejects it, and official extensions with autoInstall/enabledByDefault are installed during setup / on site-create by the reconciler. Sign bundles with the @lumibase/extension-cli (lumibase-ext keygen|sign|verify).

11a. Pageviews (visitor counting)

Public beacon + authenticated read for the built-in pageview module. Per-site config lives in the pageviews settings key (scope: 'module'): strategy (db-rollup default | hot-counter | cdc | hll), userTable, respectConsent, botFilter, hashSalt, flushIntervalS. Authenticated hits are attributed to a user only with analytics consent; anonymous hits use a salted hash (never a raw IP). Counters flush to lumibase_pageview_daily every 5 minutes.

11b. Email (templates, layouts, send)

Site-admin scope (requireSiteAdmin). Backed by the shared EmailService (SMTP / MailChannels) + a site-scoped template/layout store. Full guide: docs/en/features/email-service.md.

POST /api/v1/email/send body: { to[], cc?, replyTo?, variables?, and exactly one of templateKey or inline: { subject, html?, text? } }. Returns 502 DELIVERY_FAILED, 404 NOT_FOUND (template), or 503 EMAIL_NOT_CONFIGURED (degraded mode).

12. Firebase Sync

Sync content (items) to a Firebase target — Cloud Firestore or Realtime Database — in real time. All endpoints require site-scoped admin. Firebase credentials are write-only (supplied on create/update, encrypted at rest with ENCRYPTION_KEY, never returned). See features/firebase-sync.md.

Create a pipeline (Firestore):

POST /api/v1/firebase-sync/pipelines
Content-Type: application/json
Authorization: Bearer <token>
X-Lumi-Site: <siteId>

{
  "name": "blog-to-firestore",
  "target": "firestore",
  "projectId": "my-firebase-project",
  "credentials": {
    "project_id": "my-firebase-project",
    "client_email": "svc@my-firebase-project.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  },
  "collections": ["articles", "authors"],
  "targetPath": "content/{collection}",
  "syncOnCreate": true,
  "syncOnUpdate": true,
  "syncOnDelete": true
}

For target: "rtdb", credentials is { "databaseUrl": "https://<project>.firebaseio.com", "secret": "<rtdb-secret>" }.

Response (201):

{
  "data": {
    "id": "V1StGXR8_Z5jdHi6B-myT",
    "name": "blog-to-firestore",
    "target": "firestore",
    "status": "active",
    "projectId": "my-firebase-project",
    "collections": ["articles", "authors"],
    "targetPath": "content/{collection}",
    "syncOnCreate": true,
    "syncOnUpdate": true,
    "syncOnDelete": true,
    "lastSyncAt": null,
    "lastSyncItemCount": null,
    "createdAt": "2026-06-17T00:00:00Z",
    "updatedAt": "2026-06-17T00:00:00Z"
  }
}

Backfill response:

{ "data": { "scanned": 120, "pushed": 118, "failed": 2, "truncated": false } }

Error codes specific to this section: ENCRYPTION_KEY_REQUIRED (400 — ENCRYPTION_KEY not configured, cannot encrypt credentials), VALIDATION_ERROR (400 — body / credential shape does not match the selected target).

12a. Translation Memory

Reusable translations feeding the MT pipeline (TM → glossary → provider).

12b. Insights (Dashboards)

User-built dashboards of aggregate panels over collections. Panel queries are executed safely: every referenced field must be in the collection's field whitelist and the query is scoped to the active site — no user input reaches SQL identifiers.

PanelQuery (shared contract @lumibase/shared): { collection, aggregate (count|sum|avg|min|max), field?, groupBy?, filter? (condition rule), dateRange?, limit? }. field is required for non-count aggregates. A field outside the collection whitelist returns 400 { errors: [{ code: 'INVALID_FIELD' }] }.

12c. Git Integration (GitHub / GitLab)

Per-site connections to source repositories: track pull requests + CI, view/store CI logs, post a content-validation status back, reconcile declarative intents (GitOps), and run auto preview environments. Authenticated routes require site admin and ENCRYPTION_KEY (tokens are stored encrypted, never returned).

Public (no session; signature-verified or single-use state):

Preview environments are opt-in per integration (sync_config.preview = true): on PR open/sync LumiBase seeds an ephemeral site (${siteId}__pr-${number}) served at /api/v1/deliver/page/${ephemeralSiteId}/...; on close/merge it is torn down. CI failure records an agent_incident (role git-sync) + a git_ci_failed audit entry.

13. Delivery (Public)

No Authorization header needed. Permission applied via public role.

HTTP caching (GET /deliver/page/:site_id/:slug): responses without credentials are shared-cacheable so any CDN/proxy can absorb repeat reads.

Conditional requests: send If-None-Match with the last ETag; a match returns 304 Not Modified with an empty body and skips section hydration entirely. The ETag is a site-level content fingerprint — any item write (or a scheduled publish/unpublish taking effect) rotates it, so a stale 304 is never served at the cost of a lower revalidation hit-rate.

Tunables (env): LUMIBASE_DELIVER_SMAXAGE (seconds, default 60, 0 disables public caching), LUMIBASE_DELIVER_SWR (seconds, default 300).

14. Utility endpoints

Health response:

{
  "data": {
    "status": "healthy",
    "checks": {
      "database": "ok",
      "cache": "ok",
      "storage": "ok",
      "search": "ok",
      "queue": "ok"
    },
    "version": "1.0.0",
    "runtime": "cloudflare"
  }
}

15. Rate limits

Rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1749254460

16. Versioning

Breaking changes get a new path prefix (/api/v2). The previous version is maintained for at least 12 months.

Send X-Lumi-API-Version: 1 to pin to a specific API version. Default is the latest stable.

Change Feed (/api/v1/cdc — spec cdc-extension-integration)

Mounted on the authenticated api app BEFORE the ClickHouse CDC control-plane router. Frontend-realm tokens are rejected on every route (ADR-011).

Webhook deliveries are signed: X-Lumibase-Signature: t=<unix>,v1=<hmac_sha256_hex> over `${t}.${rawBody}` — see docs/en/features/cdc-change-feed.md for the verify snippet and envelope reference.