Append an event to a run.

Errors return a { message, code } body — see the error reference for the code → SDK exception map.

POST/v1/events

Appends an event to the run's append-only log and enqueues an extraction job in the same database transaction. Returns the created event id and its server-assigned, per-run sequence number.

Authorization

bearerAuth

AuthorizationBearer <token>

API key sent as a bearer token: Authorization: Bearer <key>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

run_id*string

Formatuuid

agent_id*string

Length1 <= length

payload*

Opaque event body. As a convention, an event with kind: "state" carries one hot coordination fact for working memory and is written through to the low-latency stripe so a same-run reader sees it immediately: {"kind":"state","entity":"<subject>","predicate":"<attr>","value":<any JSON>}. entity and predicate are required, non-empty, at most 256 bytes, and free of control characters; value is bounded by the server's configured limit. A malformed state fact is rejected with 400 invalid_state_fact. Any other payload is stored and distilled by the normal extraction path.

Response Body

`application/json`

curl -X POST "https://example.com/v1/events" \  -H "Content-Type: application/json" \  -d '{    "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",    "agent_id": "researcher",    "payload": {      "kind": "state",      "entity": "auth-service",      "predicate": "status",      "value": "up"    }  }'

{  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",  "seq": 1}

{  "message": "string",  "code": "string"}

{  "message": "string",  "code": "string"}

{  "message": "string",  "code": "string"}

Append an event to a run.

Authorization

Request Body

Response Body

202application/json

400application/json

401application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`