POST /v1/experience

curl -X POST "https://example.com/v1/experience" \  -H "Content-Type: application/json" \  -d '{    "scope": "string",    "modality": "string",    "content": {}  }'

curl -X POST "https://example.com/v1/experience/bulk" \  -H "Content-Type: application/json" \  -d '{}'

curl -X GET "https://example.com/v1/experience/status"

Required fields

Wait semantics

Wait deadline and 408 WAIT_TIMEOUT

A waiting capture has one budget (v0.10.2). When it runs out the server answers 408 WAIT_TIMEOUT (retriable: true). The event is already captured and durable, and indexing carries on in the background.

• Single capture (?wait=indexed or consolidated): about 30 s, shared by the wait for the indexer to reach the event and the wait for the requested stage after it. Before v0.10.2 each wait had its own 30 s, so the 408 came after about 60 s. details says what it waited for:

  {
    "error_code": "WAIT_TIMEOUT",
    "retriable": true,
    "details": {
      "event_id": "evt_01a0e9fbdebf7d50bbacdfa90dcab9fc",
      "status_url": "/v1/experience/status?event_id=evt_01a0e9fbdebf7d50bbacdfa90dcab9fc",
      "target_stage": "indexed",
      "waited_ms": 30004,
      "waiting_on": "indexer"
    }
  }

  waiting_on is indexer (the indexer had not reached the event) or stage (indexed, but not yet at the requested stage).

• Bulk (/v1/experience/bulk?wait=indexed|consolidated): min(30 s + 1 s per item, 600 s), and it now covers the batch's own inline indexing as well (before v0.10.2 that indexing had no time limit, so a batch behind a slow embedding provider waited, then answered 200). A two-item batch answers after 32 s with details { batch_id, target_stage, waited_ms, waiting_on: "indexing", items, event_ids }; waiting_on: "stage" carries accepted instead of items. event_ids lists the batch's events in item order, the same list a 200 returns.

• After a 408, poll status_url, or GET /v1/experience/status?event_id= for each id in event_ids. Don't re-send blindly: a re-send replays (never duplicates) only a capture or bulk item that carried its own idempotency_key. One sent without a key gets a key the server mints and never returns, so re-sending it writes it again. Send an idempotency_key on every capture that waits, bulk items included.

• A bulk sent with no wait has no deadline, as before: it still indexes its batch before it answers 202, so a slow embedding provider delays that answer by as long as its calls take.

Source descriptor

An optional source object (schema version 2) records the authoritative source and exact fragments the envelope represents: source_id, content_kind, a sha256:/blake3: fingerprint of the bytes, and per-fragment locators (document page, conversation turn, code file and lines, and so on). It is stored verbatim and echoed on reads. source.modality must equal the envelope modality or the write is 422 INVALID_ENVELOPE; unknown locator fields are 422 INVALID_BODY. Field reference and example: Experience Envelope.

Content kinds

content.kind is one of message, text, json, blob_ref, triple. A triple is nested under content.triple (a flat subject/predicate/object directly in content → 422 "missing field triple"), and its object is a full struct — type + datatype + value:

{
  "kind": "triple",
  "triple": {
    "subject": { "type": "entity", "id": "ent_acme" },
    "predicate": "seats",
    "object": { "type": "literal", "datatype": "string", "value": "200" }
  }
}

Omitting datatype → 422 "missing field datatype".

A triple capture writes its fact directly, with no enrichment and no LLM call: the extraction model never sees it, whatever directives.extract says. With ?wait=indexed the fact is on GET /v1/facts as soon as the write returns, with or without enrichment.

Language, time zone and referenced times

Three optional hints (v0.10.1), each gated on a capability in GET /v1/admin/version capabilities[]:

• language (BCP-47, e.g. hi-Latn) and scripts[] (ISO 15924, at most 8), capability capture_language_v1. Values are canonicalized (HI-latn is stored as hi-Latn, latn as Latn). A malformed tag or more than 8 scripts → 422 INVALID_ENVELOPE.
• Every event gets one language tag. Your language wins, then a lang:<tag> label in context.labels, then detection: Devanagari text is stored as und-Deva, and Latin-script Hinglish as hi-Latn. Event reads and recall items return language, scripts and language_source (hint, source, label or detected). An event that is English by default stores no tag, so it reads back exactly as before; an explicit "language": "en" is stored.
• context.timezone: an exact IANA zone name. Asia/Kolkata and the older alias Asia/Calcutta work; IST, +05:30 and Asia/Mumbai → 422 INVALID_ENVELOPE.
• context.refers_to[] (capability refers_to_v1): the dates or times the memory talks about, as local dates (YYYY-MM-DD) or date-times without an offset, in from, to or candidates[], with an optional zone and precision. Recall can boost them with temporal.refers_during. A phrase such as "next friday" → 422 INVALID_ENVELOPE.

None of these is part of the write identity. A retry with the same idempotency_key and body but different hints replays the first write (the first write's hints win) and adds warnings: ["conflicting_hint_on_replay: …"] to both the 202 and a waited 200.

Text blobs

A blob_ref capture of a text blob decodes the bytes by byte-order mark, a declared charset=, or strict UTF-8 (capability blob_text_decode_v1). Bytes that are none of these fail the write with 422 BLOB_TEXT_ENCODING_UNKNOWN (retriable: false; details { blob_id, content_type, reason, charset }, e.g. reason: "undeclared_non_utf8"). Declare the charset on upload (Content-Type: text/plain; charset=windows-1252) and the same bytes decode correctly. In /v1/experience/bulk one such blob fails the whole batch, and none of its items is stored. The event records the blob it came from in source_blob_ids; forgetting or erasing the event deletes the blob unless another live event still uses it (see Blobs).

Errors

Notes

• Idempotency keys are scoped to the scope, actor and key, with /v1/experience and /v1/experience/bulk sharing one bucket (a bulk item replays a single write with the same key and body). The same key and body sent to another scope, or by another actor, writes a new event. Keys are at most 64 characters (a longer one → 422 INVALID_ENVELOPE) and expire after 24 hours; a repeat within the window with the same body replays (replayed_from_idempotency: true).
• An unknown modality is stored verbatim (202) — the field is a free string, not an enum.
• Bulk ingest: POST /v1/experience/bulk (in the spec above) and its alias POST /v1/experiences share one handler, with identical validation and response. The body takes items (or the alias experiences), an array of the same envelopes, plus an optional ordering string (strict_temporal | batch_throughput); a non-string value → 422. An empty array → 422; the only accepted top-level fields are experiences, items, and ordering (anything else → 422). The response is a batch envelope: { batch_id, accepted, lifecycle_stream, event_ids, results: [{ index, event_id, replayed_from_idempotency }] }; with ?wait=indexed it is a 200 that adds stage: "indexed", or a 408 WAIT_TIMEOUT listing the batch's event_ids.
• Facts/Beliefs/Understanding extracted from text are derived asynchronously and require enrichment — on a content-only self-host they stay empty (triple captures, above, are the exception). See Self-hosting defaults.
• Send directives.extract through /v1/experience/bulk (a one-item bulk request works): the bulk route applies it, while a single POST /v1/experience runs enrichment as if it were unset. Since v0.10.1 extract: ["beliefs"] or ["understanding"] run enrichment (they used to switch it off); extract: [] still turns it off for the event. directives.embed is validated but doesn't change how the event is embedded.