POST /v1/capture

Idempotent ingestion of a batch of events. Responds 202 as soon as the write is done; consolidation runs as a background job (pending, processed by POST /v1/consolidate — see Consolidator).

Request body

EventIn[]

required

One or more events (min_length=1).

Show EventIn fields

string

required

1 to 128 characters.

string

required

1 to 128 characters.

string

default:"user"

Max 64 characters.

string

Max 128 characters. Not marked required by Pydantic but validated by the Ledger (missing_scope if empty) — so the error can carry the exact index of the offending event in the batch.

string

Max 64 characters.

string

Max 128 characters.

string

Max 128 characters.

string

Max 128 characters.

string

Max 128 characters.

string

required

1 to 128 characters. Free-form — e.g. conversation.message, conversation.turn, agent.observation.

datetime

required

ISO 8601.

object

required

Free-form content.

object

Free-form provenance, e.g. {"tool": "mcp", "server": "haki"}.

string[]

default:"[]"

Free-form tags.

string

Max 128 characters.

string

Max 256 characters. Per-event key (see Memory Ledger for the priority order against the batch key).

string

Max 256 characters. Batch key: namespaced by each event’s content hash, so several events in the same batch never collide with each other.

Response — `202 Accepted`

string

default:"accepted"

CapturedEvent[]

required

Show fields

uuid

required

boolean

required

true if this event already existed (same idempotency key) — the row returned is the original, no new write happened.

uuid | null

null if the whole batch was deduplicated — nothing new to consolidate.

string

The applied policy (HAKI_DEFAULT_POLICY, "default" locally).

curl -X POST http://localhost:8100/v1/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hk_..." \
  -d '{
    "idempotency_key": "demo-1",
    "events": [{
      "org_id": "org_acme", "project_id": "prj_support",
      "subject_type": "user", "subject_id": "usr_42",
      "kind": "conversation.message",
      "occurred_at": "2026-08-01T10:00:00Z",
      "payload": {"role": "user", "content": "I prefer my invoices in French."},
      "classification": ["customer-data"]
    }]
  }'

client.capture(
    events=[{
        "org_id": "org_acme", "project_id": "prj_support",
        "subject_type": "user", "subject_id": "usr_42",
        "kind": "conversation.message",
        "occurred_at": "2026-08-01T10:00:00Z",
        "payload": {"role": "user", "content": "I prefer my invoices in French."},
    }],
    idempotency_key="demo-1",
)

{
  "status": "accepted",
  "events": [{"id": "7c21e4c2-...", "deduplicated": false}],
  "consolidation_job_id": "9b0f1a3e-...",
  "policy": "default"
}

Possible errors

missing_scope (an event’s subject_id is empty — 422), forbidden_scope (an event’s project_id ≠ the key’s — 403), invalid_payload (malformed body — 422).

Getting started

Memory

Quality and correction

Administration

Gateway and health

POST /v1/capture

Request body

Response — `202 Accepted`

Possible errors

​Request body

​Response — 202 Accepted

​Possible errors

Request body

Response — `202 Accepted`

Possible errors