API Reference
Interactive reference for the Coven daemon HTTP-over-Unix-socket API. Per-endpoint schemas, code samples in four languages, and Try It panels that target your local daemon.
1 min read
The Coven daemon serves a small HTTP/1.1 API over a Unix domain socket. This section is the per-endpoint interactive reference, generated from openapi/coven.daemon.v1.yaml. For the narrative reference (concepts, error model, versioning rules), see Coven local socket API.
Start a daemon
The Try It panels on each endpoint page bridge browser requests through a Next.js route handler to your local $COVEN_HOME/coven.sock. They only work when this docs site is running on the same machine as a live daemon.
coven daemon start
coven daemon status # verify pid + socketSanity-check from the terminal
Without leaving the shell:
curl --unix-socket "$HOME/.coven/coven.sock" http://localhost/api/v1/healthA healthy daemon returns {"ok":true,"apiVersion":"coven.daemon.v1",...}.
Transport and trust model
| Property | Value |
|---|---|
| Protocol | HTTP/1.1 over Unix domain socket |
| Default socket | ~/.coven/coven.sock (override via $COVEN_HOME) |
| Auth | File-system permissions on the socket — no Bearer / JWT / API-key / cookie |
| Contract | coven.daemon.v1 served under /api/v1 |
Anyone with read/write permission on the socket can act as a client. Keep $COVEN_HOME private to the owning user. See Authentication and local access for the full hardening posture.
Client handshake
GET /api/v1/health— confirmapiVersion === "coven.daemon.v1".GET /api/v1/capabilities— discover available adapters and action ids.- Use versioned
/api/v1/*routes only. - Branch on
error.code, not message text — see the error envelope and code table.
Additive fields are allowed inside v1; breaking changes require a new route-prefix version. See API compatibility rules.
Endpoint groups
Meta
Handshake, capability discovery, version metadata. Start here.
Sessions
Launch, inspect, and control harness sessions (codex, claude).
Events
Append-only event log for a single session. Crash-safe resume via afterSeq.
Actions
Control-plane action router. Only known action ids are accepted.
Code samples
Every endpoint includes runnable samples in curl (with --unix-socket), TypeScript (undici Agent({ connect: { socketPath } })), Python (httpx.HTTPTransport(uds=...)), and Rust (hyperlocal::UnixConnector). Each sample reads $COVEN_HOME with a ~/.coven fallback, so they work as-is once a daemon is running.
Last updated on