Writing Records

Append records to a topic. A single POST /v0/topics/:topic carries one or many records, the server assigns each a monotonic $seq and a $ts, and the whole batch commits atomically — all of it or none of it. The same endpoint can lazily create the topic and carry an idempotency key, so the common write path needs no separate calls.

This page covers the write request body, atomicity, full-topic behavior, the response shape, the hard batching limits, and the errors. For how durable a write actually is, see Durability; for retry-safe writes, see Idempotency.

POST /v0/topics/:topic — append records

Append one or many records. The server assigns the seqs and returns them. Inline config (applied only on a lazy create) means the common case needs no separate PUT.

Path — :topic, name ^[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$ (1–255 chars, starts alphanumeric, allows . _ : -). Case-sensitive, byte-exact.

Request body

curl -X POST $TOPICS/v0/topics/orders \
  -H 'content-type: application/json' \
  -d '{
        "node": "checkout-1",
        "idempotency_key": "client-batch-7f3a",
        "records": [
          { "data": { "sku": "AEROPRESS-GO", "qty": 1, "total": 3499 },
            "tag": "order-7731", "meta": { "trace": "abc123" } },
          { "data": "raw-opaque-or-base64", "tag": "order-7732" }
        ]
      }'

# → 200 OK (or 201 if this write created the topic)
{
  "topic": "orders",
  "first_seq": 480232, "last_seq": 480233,
  "seqs": [480232, 480233],
  "head_seq": 480233, "count": 2,
  "created": false, "deduped": false,
  "performance": { "server_total_ms": 0.62, "wal_append_ms": 0.10, "fsync_ms": 0.39 }
}

Atomicity

A write is all-or-nothing. All N records in records commit with contiguous seqs, or none do — there is no partial append. first_seq and last_seq bound the assigned range, and seqs[i] is the seq of records[i].

For a durable topic the response is held until the write is committed per the topic’s durability class: an fsync topic holds the ack until the WAL frame is durably synced; a disk topic acks on group-commit enqueue; a memory topic acks the same way as disk (on WAL-frame enqueue) but is best-effort — not fsync-gated and with no durability guarantee. A non-fsync topic never blocks on fsync.

Full-topic behavior

When the topic is at its cap_records / cap_bytes limit, the discard policy decides what happens to the incoming write:

discard:"reject" is the durable-queue choice: unconsumed work fails the producer loudly rather than being silently dropped. discard:"old" is the pub/sub choice: the newest data always lands, and any consumer that fell below the eviction floor gets an explicit tombstone on its next read.

Response

{
  "topic": "orders",
  "first_seq": 480232, "last_seq": 480234,
  "seqs": [480232, 480233, 480234],
  "head_seq": 480234, "count": 3,
  "created": false, "deduped": false,
  "performance": { "server_total_ms": 0.62, "wal_append_ms": 0.10, "fsync_ms": 0.39 }
}

Batching limits

Hard, documented limits. Design your batches within them; exceeding one is a 400 (batch_too_large / record_too_large) or, for the raw body, a 413. These are fixed protocol limits — only the raw request-body cap is tunable, via TOPICS_MAX_BODY_BYTES (default 64 MiB); see Configuration.

Errors

See also

• Reading (diff) — consume what you wrote with POST /v0/topics/:topic/diff.
• Durability — what an acknowledged write survives, per class.
• Idempotency — idempotency_key, the dedupe window, and deduped.
• Topics — create and configure a topic with PUT, and the full config object.