Operations

Writes are asynchronous. memory.store, memory.delete and collections.delete return 202 with an OperationAccepted:

{
  "operation_id": "018f3c2a-8d55-7a21-88bf-6e0d43c9a115",
  "resource_type": "memory",
  "resource_id": "018f3c2a-7e19-7f04-b3d6-2a9c5e81f742",
  "state": "queued",
  "status_url": "/v2/collections/018f3c2a-6b41-7d8e-9a52-4c1e77b0d3aa/operations/018f3c2a-8d55-7a21-88bf-6e0d43c9a115",
  "events_url": "/v2/collections/018f3c2a-6b41-7d8e-9a52-4c1e77b0d3aa/operations/018f3c2a-8d55-7a21-88bf-6e0d43c9a115/events"
}

Follow it by polling status_url or streaming events_url.

The operation

Field	Meaning
`state`	`queued`, `running`, `succeeded`, `failed`, `cancelled`
`stage`	`queued`, `parsing`, `extracting`, `publishing`, `searchable`, `complete`
`progress`	`0`–`1`
`search_ready`	Whether search can observe the result yet
`failure`	Populated when `state` is `failed`
`kind`	`memory_store`, `memory_store_file`, `memory_delete`, `collection_delete`

search_ready is the field to wait on, not state. An operation reaching succeeded means the write is durable; search_ready means search can return it. There is no separate search-ready endpoint.

stage and kind are open enumerations — keep a default branch.

Streaming

GET {events_url} is a text/event-stream. Each data: payload is one OperationEvent — a snapshot, progress or terminal event.

A fresh connection opens with one snapshot of the current state, then zero or more progress events, then one terminal event — unless the snapshot already carries a terminal state, in which case it is the only event and the stream closes.

Every event's SSE id is a resume cursor. Reconnect with Last-Event-ID and the server resumes after that cursor: it does not replay the snapshot, and it closes having sent nothing when the operation was already finished at that point. So stop on any event whose state is terminal, rather than waiting for a terminal event that may never arrive.

Resuming an operation that has been terminal for more than 24 hours returns event_history_expired — reconnect without the header for a fresh snapshot.

Cancelling

operations.cancel requests cancellation. Work already published is not rolled back; cancelling an operation that has finished fails with cancellation_conflict.