Append event

POST

/logs/{log_id}/append

Appends a single event to a log. The service does not return until the event is durably stored. Returns the assigned sequence number for read-after-write consistency.

Idempotency: The optional Idempotency-Key header enables exactly-once delivery within the stream’s deduplication window (configurable via nats.duplicate_window_secs, default: 1 hour in production). Outside that window, the same key may append again. If a client reuses the same key with a different payload inside the window, the original payload wins (no error is returned).

Authorizations

• bearer_auth

Parameters

Path Parameters

log_id

required

string format: uuid

Log ID (UUID)

Header Parameters

Idempotency-Key

string | null

Optional idempotency key for deduplication. Duplicate requests with the same key within the deduplication window return the original sequence number. Note: reusing a key with a different payload still deduplicates (first payload wins).

Expected-Sequence

integer | null format: int64

Optional expected last sequence number for optimistic concurrency. If the log’s current last sequence doesn’t match, the append is rejected with 409 Conflict. Use 0 to assert the log is empty.

Request Body ^required

Raw event payload bytes. Must not exceed 1 MB.

Array<integer>

Responses

200

Event stored

Response after appending an event. Returned only after the event is durably stored.

object

sequence

Assigned sequence number. Monotonically increasing. Use for read-after-write consistency.

integer | null format: int64

success

required

True when the event was durably stored.

boolean

Example

{
  "sequence": 42,
  "success": true
}

400

Invalid header value

401

Unauthorized

404

Log not found

409

Sequence mismatch — another event was appended since the expected sequence

Unified error response body for all endpoints.

object

code

Optional machine-readable error code.

string | null

error

required

Human-readable error message.

string

500

Server error