Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencoven.ai/llms.txt

Use this file to discover all available pages before exploring further.

Coven exposes a small versioned HTTP API over a Unix socket. The current public contract is coven.daemon.v1 served under the /api/v1 prefix. The daemon does not use OAuth, JWTs, bearer tokens, API keys, or browser cookies. Trust is same-user local access to the Unix socket at <covenHome>/coven.sock. See Auth posture before adding a new client, dashboard, remote bridge, or browser-facing transport.

​
Handshake

Always start with: 
GET /api/v1/health

{
  "ok": true,
  "apiVersion": "coven.daemon.v1",
  "capabilities": {
    "sessions": true,
    "events": true,
    "actions": true,
    "harnesses": ["codex", "claude"]
  },
  "daemon": {
    "pid": 31415,
    "uptime": 4823,
    "startedAt": "2026-05-15T19:31:02Z"
  }
}
Negotiate against apiVersion and capabilities before depending on session or event response shapes.

​
Endpoints

EndpointPurpose
GET /api/v1/api-versionRead the active API version and supported versions.
GET /api/v1/healthCheck daemon health and metadata.
GET /api/v1/capabilitiesDiscover routable capabilities and owning adapters.
POST /api/v1/actionsSend a known intent through the control plane.
GET /api/v1/sessionsList sessions.
POST /api/v1/sessionsLaunch a session.
GET /api/v1/sessions/:idFetch one session.
GET /api/v1/events?sessionId=...Read session events.
POST /api/v1/sessions/:id/inputForward input to a live session.
POST /api/v1/sessions/:id/killKill a live session.
Detailed shapes live in the API reference.

​
Error envelope

All error responses use: 
{
  "error": {
    "code": "session.cwd_outside_root",
    "message": "cwd must canonicalize inside project root",
    "details": {
      "projectRoot": "/Users/me/work/proj",
      "cwd": "/tmp/wander"
    }
  }
}
See Error envelope for the full code list.

​
Versioning

The apiVersion field is the contract clients pin against. Coven follows additive compatibility: new fields and new capabilities are added under existing versions; breaking changes require a new version. See API versioning.

​
Calling the socket

curl --unix-socket "$HOME/.coven/coven.sock" \
  http://localhost/api/v1/health