Use the daemon HTTP API
Use the bearer token and address from local discovery. The canonical
OpenAPI document defines requests, responses, and bounds.
Generated references group operations for clients,
extensions, and
daemon transfers. These groups do not change
access control. Regenerate them with go -C cli generate ./internal/daemon.
On this page: Create, submit, and watch, Edit observed configuration, and Recover an uncertain input or action.
Create, submit, and watch
- Generate a current UUIDv7 for the session. Send
PUT /sessions/{session_id}withIf-None-Match: *and akind: "new"request. Retain that identity and intent until creation is resolved. - Generate a separate UUIDv7 for the input. Send
PUT /sessions/{session_id}/inputs/{input_id}withkind: "message"andtext. Acceptance does not mean the turn finished. - Read
GET /sessions/{session_id}/eventswithAccept: text/event-stream. Apply a complete reset snapshot before later events. On reconnect, send the last delivered generation and sequence asafter_generationandafter_seq. A reset replaces the old cursor. Never advance a cursor past a rejected batch.
The ordinary HTTP scenario in
http_consumer_test.py exercises creation,
identified input recovery, stream reconnection, and history reconciliation.
Edit observed configuration
- Read
GET /sessions/{session_id}/configuration, retaining its ETag alongside the values shown to the user. - Send
PATCHto that URL withContent-Type: application/merge-patch+jsonandIf-Matchset to the observed ETag. Omit unchanged fields. Send null only for nullable fields that the edit clears. - Consume the returned
resource.valueandresource.etag. Readapplicationto determine whether the desired composition differs from the loaded one. Editing does not reload the session. - On 412, show that the observation changed and refresh it. Do not silently reapply the edit with a newer validator.
Move a workspace separately with POST /sessions/{session_id}/workspace, the
observed configuration validator, and the observed family revision.
Recover an uncertain input or action
Retain the original ID and immutable intent when a connection fails. Read the identified resource before creating another operation. If no receipt is found and the identity remains admissible, repeat the identical PUT with the same ID. A conflict means that ID belongs to a different intent. An expired identity must not be silently replaced to replay uncertain work.
Inputs use GET /sessions/{session_id}/inputs/{input_id}. Compactions use
GET /sessions/{session_id}/compactions/{action_id}. A running compaction needs
another receipt read. A completed receipt carries the domain result, which may
be failed even though HTTP admission succeeded. An interrupted compaction has
uncertain effects and is never automatically replayed. Inspect configuration and
context before explicitly requesting new work.
The compaction receipt scenarios cover identity conflicts, retained selection on failure, and restart interruption. HTTP API behavior defines retention and the limits of recovery. Reload and kernel operations have no durable action receipt and must not be automatically replayed.
Previous client api Next http api design