Conventions

These are the rules every /v0 endpoint shares, specified once so the per-area reference pages can stay short. Read this page once and the rest of the API is predictable: a JSON body in, a JSON body out, a stable error.code on failure, a performance block on every response, and the monotonic $seq as the cursor.

Base URL & versioning

http://{host}:{port}/v0/...

The API version is the first path segment (/v0). The default bind is 127.0.0.1:4000, so a local server is http://localhost:4000/v0/.... There is no region or tenant in the host — topics is single-machine. Examples across these docs use $TOPICS for the base URL — set it with export TOPICS=http://localhost:4000 (or your server’s address).

Breaking changes would ship as a new prefix (/v1) that may run concurrently. Within a version, all changes are additive: new optional request fields, new response fields, new endpoints. Clients must ignore unknown response fields — that is the forward-compat contract.

Auth

Authorization: Bearer <API_KEY>

A plain bearer token. Keys are supplied at startup via TOPICS_API_KEYS (comma-separated). A missing or unknown key returns 401 unauthorized. If the server starts with no keys configured, auth is disabled (single-tenant dev mode) and the header is ignored — logged loudly at boot. The default loopback bind keeps that dev mode safe; a non-loopback bind with no keys refuses to start unless you set TOPICS_ALLOW_INSECURE_NO_AUTH=1.

Keys are hashed at rest (SHA-256) — only the digest is kept in memory, never the plaintext, which is zeroized after parse and never logged. The comparison is constant-time, so it leaks neither which key nor how many leading bytes matched. A key may additionally carry a scope set (read / write / delete / admin) and a topic-name prefix allowlist; a request that authenticates but lacks the required scope, or names a topic outside its allowlist, returns 403 forbidden.

Content types & encoding

• Request bodies require Content-Type: application/json; charset=utf-8 on every POST/PUT with a body. A wrong or missing type returns 415 unsupported_media_type.
• Response bodies are application/json, except the SSE stream, which is text/event-stream.
• data payloads are arbitrary JSON (object, array, string, number, bool, null), stored and returned verbatim — never parsed, indexed, or validated for shape. For binary, put a base64 string in data and a hint in meta.
• Compression is honored both ways (Accept-Encoding: gzip / Content-Encoding: gzip) but off by default — on a local-NVMe single-machine deployment the bottleneck is CPU, not bandwidth. Enable it only for large bulk writes over a slow link.
• Timestamps and durations are integer milliseconds ($ts, *_ms). There are no string dates anywhere.
• $seq is a u64 rendered as a JSON number. It fits in an IEEE-754 double well beyond any single topic’s lifetime; clients SHOULD still parse as a 64-bit integer.

The $-prefixed metadata convention

Server-computed, per-record metadata is returned under $-prefixed keys so it can never collide with your content. data and meta are your namespaces (pure passthrough, same key in both directions). On write, you set node/tag as plain top-level keys; on read, the server echoes them as $node/$tag to signal they are now server-canonical and immutable.

$node, $tag, and meta are omitted from a response object when absent — absence, not null. data is always present (and may be JSON null).

The canonical error body

Every non-2xx response (except in-stream SSE errors) carries this exact shape:

{
  "error": {
    "code": "topic_not_found",
    "message": "topic \"orders\" does not exist",
    "detail": { "topic": "orders" }
  }
}

Success responses carry bare data — there is no {"status":"ok"} envelope. The presence of a top-level error key is the only success/failure discriminator.

Status codes

429 throttled carries a Retry-After header. A CPU-pressure throttle adds error.detail.retry_after_ms; a resource-cap rejection adds error.detail.limit. 503 also carries Retry-After. The full list lives on Errors.

Pagination & cursors

Three cursor styles for three read shapes — do not mix them up:

1. Topic reads are seq-cursored, not opaque. The cursor is from_seq. POST .../diff returns next_from_seq; you pass it back. When fully caught up, next_from_seq == head_seq and "caught_up": true. The server always returns next_from_seq; caught_up is the “done for now” flag — for a live log, “done for now” is not “done forever”.
2. List endpoints use opaque cursors. GET /v0/topics and GET /v0/routers return next_cursor (opaque base64), present only when more pages exist — its absence means the last page. Pass it back as ?cursor=. page_size defaults to 100, max 1000.
3. SSE uses a composite cursor. The multiplex watch encodes the per-topic (topic → seq) positions as a base64url-encoded JSON map, usable as both Last-Event-ID and the request cursor field. See Watch.

Idempotency

Two complementary mechanisms; there is no global idempotency-token service.

1. The control plane is idempotent by construction. Create / configure is PUT and upsertable: an identical PUT is a no-op 200; a changed PUT applies the diff. A DELETE of an absent resource returns 200 with "deleted": false.
2. Writes use an optional idempotency_key. If supplied, the server remembers (topic, idempotency_key) → assigned seqs for idempotency_window_ms (default 120000, per topic). A retried write with the same key in-window returns the original seqs with "deduped": true and does not append again. The key may also be sent as the Idempotency-Key: header (the body field wins).

The performance block

Every JSON response (and most errors) includes a performance object, so latency observability lives in the response, not a side channel:

"performance": {
  "server_total_ms": 0.41,
  "wal_append_ms": 0.12,
  "fsync_ms": 0.0,
  "records_scanned": 128,
  "throttle_wait_ms": 0.0
}

Fields are best-effort and additive; clients must tolerate any subset. See Performance for how these numbers are produced.

The Topic config object

This object appears in topic-create requests and topic-state responses. All fields are optional on create; an omitted field takes the documented default. An empty {} creates an all-default topic.

{
  "type": "log",
  "ttl_ms": 0,
  "cap_records": 0,
  "cap_bytes": 0,
  "discard": "old",
  "durable": false,
  "durability": "disk",
  "priority": null,
  "auto_priority": true,
  "auto_create": true,
  "idempotency_window_ms": 120000,
  "dedupe_node": true,
  "lease_ms": 30000,
  "claim_jitter_ms": 0,
  "max_deliveries": 0,
  "dead_letter": null,
  "leases_durable": false
}

See also

• API Reference overview — the full endpoint index.
• Topics — the topic lifecycle endpoints that use this config object.
• Errors — the complete error.code → HTTP-status catalog.
• Security — auth, scopes, and the prefix allowlist in full.
• Durability — the ephemeral/memory/disk/fsync commit classes.