Socket API
Operating the versioned local API boundary.
2 min read
The daemon serves /api/v1 over same-user local IPC, not a TCP port by default. Unix-like hosts use $COVEN_HOME/coven.sock; Windows uses an owner-only named pipe reported by health and coven daemon status. This keeps the default boundary local to the operating-system user that owns the daemon state.
Health handshake
Every client should call GET /api/v1/health before using another route. The response identifies the API version and available capabilities. A newer client must not assume that an older daemon supports a route simply because its own code knows about it.
The public session flow is health → capabilities → sessions → events → validated actions. For schemas, error codes, and local examples, use the local API reference.
GET /api/v1/api-version remains a legacy route-family diagnostic. Use the named apiVersion from health plus the advertised capabilities for compatibility decisions.
When the local IPC endpoint is missing or stale, use:
coven daemon status
coven daemon restartFor the local access posture, see Daemon security.
Claude scoped-write negotiation
A newer owner-local daemon can advertise sessionClaudeWriteScope: true for the separate Claude writeScope launch document. TCP reports false and refuses the field. This flag describes parsing availability, not local runtime qualification or an authority grant; missing means unavailable. The document and execution profile are described under Claude scoped writes.
Mission scopes are optional project-read declarations that are validated and stored without enabling M0 dispatch. See Familiar missions for bounds and the unchanged unavailable outcome.
Internal mobile connection diagnostics
In source builds with mobile transport, first-party clients use the owner-local internal diagnostic POST /api/v1/internal/mobile/connections. {} selects relay for compatibility; {"transport":"direct"} and {"transport":"relay"} select an ingress explicitly. The response contains exactly state (offline, connecting, authenticating or online) and transport. Unknown fields, malformed bodies and unknown transports return 400; other methods return 405. TCP and mobile ingress cannot dispatch this diagnostic.
The result aggregates live channels, with online taking precedence over authenticating, connecting and offline. It does not enroll devices, change authority or authorize application actions; an online channel can still have its next request refused by current policy. This internal diagnostic is outside the stable OpenAPI subset. For operator output and unavailable-state semantics, see Doctor.
Last updated on