HTTP API Reference

All Cacophony services expose their APIs under /api/v1/. Default content type is application/json; SSE endpoints use text/event-stream.

Authentication

Prefer first-party caco CLI commands for local inspection because they read the node token without placing it in shell history or process arguments.

caco status --json true
caco node show --json true

If you must use raw HTTP on a trusted single-user machine, keep the token file private and avoid pasting bearer values into shared logs. Shell-expanded curl bearer-header examples can expose the token through process inspection while the command runs.

Discovery

Cluster stats

The /api/v1/stats response is { generated_at, scope{project?, node?, window_hours, bucket}, compute, per_node[], throughput, tokens }. compute is the cluster ClusterComputeRollup (nodes_counted, cpu_cores, mem_total_bytes, mem_used_bytes, disk_total_bytes, disk_used_bytes, nodes_with_disk) and each per_node[] row carries node, platform, load_avg_1, cpu_cores, and the same mem/disk byte fields, sourced from local live telemetry plus peer snapshots. tokens is the fleet token-usage rollup by project ({ by_project, grand_total }) summed across the local node and peers. throughput is the bead-lifecycle throughput summary by project: totals aggregates closed_last_24h/closed_last_7d and throughput_beads_per_hour, and each by_project[] entry adds throughput_window_hours, average_time_to_close_secs, and a series object — the dense closed-bead time-series for charts (window_hours, bucket, buckets, total_closed), driven by the request window/bucket. The whole field is null only when no beads data is reachable (for example when the beads primary is unavailable). Read-only; available on both the local and cluster listeners.

Feed

Browser caco-web treats HTTP 5xx snapshot/bootstrap failures and SSE/network failures that outlast the bounded 15s transient-error grace after the last healthy SSE open or UI event as Backend unavailable, even if the dashboard web service and local /health endpoint are still healthy during daemon restart convergence.

• Snapshot timeouts: The GET /api/v1/ui/snapshot proxy hop is bounded at 8 seconds and the browser-side snapshot fetch budget is 12 seconds; timeout returns a 200 OK JSON sentinel with ok: false, error: "daemon_proxy_timeout", backend_unavailable: true, upstream_status: 504, and X-Caco-Upstream-Status: 504. caco-web maps that timeout sentinel to Snapshot delayed / snapshot_degraded while it retries; if it arrives before any usable bulk snapshot data, the hero/freshness copy says the snapshot proxy timed out and avoids healthy-looking zero-count cluster metrics.
• Upstream errors: Upstream snapshot server errors such as 500/502/504 are also translated into console-clean 200 OK JSON sentinels with ok:false, error:"daemon_proxy_upstream_error", backend_unavailable:true, upstream_status:<original status>, and X-Caco-Upstream-Status:<original status>; those map to Backend unavailable rather than Snapshot delayed.
• Quiet reconnects: Any background mesh/full-state refresh completion stays in daemon logs/feed diagnostics instead of a toast. Short-lived EventSource errors during the SSE grace keep the connection pill Connected while the browser reconnects. If the upstream SSE body is interrupted after headers have been sent, the proxy emits a handled SSE event: error payload with error:"daemon_proxy_stream_error", backend_unavailable:true, and reconnecting copy instead of surfacing Chromium net::ERR_INCOMPLETE_CHUNKED_ENCODING as the primary operator signal.
• Recovery: After a real disconnect or unavailable/proxy-timeout snapshot state, SSE reconnect queues a full snapshot refresh and preserves the queued reconnect reason when another snapshot request is already in flight, so state missed during the gap is repaired without a manual Refresh. Sustained SSE failures keep last-known dashboard rows visible as cached/reconnecting when usable data exists; only pages with no usable state fall back to disconnected/backend-unavailable copy.

Daemon automation

Managed-agent Heartbeats

Heartbeat APIs are authenticated mesh-routed controls for a selected agent: the ingress daemon resolves the authoritative owner and forwards over mTLS without requiring callers to know a node. Selector-free calls remain local-node bulk operations, and explicit CLI routing (caco @node heartbeat ... or caco @all heartbeat ...) remains available for deliberate node/fleet scopes. Status is readable by authenticated agent scopes; mutation requires operator/node or cluster-controller authority. JSON rows distinguish owner node, config defaults, runtime overrides, effective enabled state and reason, interval, last/next timestamps, delivery health, and transition provenance.

Feed Event Schema

{
  "id": "evt-01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "ts": "2026-03-16T12:00:00Z",
  "origin_node": "localhost",
  "project": "cacophony",
  "type": "agent_status",
  "sender": "localhost:cacophony:sunny-owl",
  "target": null,
  "payload": {
    "status": "running tests"
  }
}

Standard Event Types

Agents

The project-scoped agent endpoints validate project membership and are the preferred create/message surface. The global /api/v1/agents/... family is the cross-node read/lifecycle surface used by CLI, TUI, web, and companion clients. Do not call a non-existent /api/v1/agents/<id>/reintegrate; reintegration remains a lifecycle/CLI surface unless a future daemon endpoint is explicitly added.

Remote agent inspection and lifecycle forwards should not leak peer-side 502 Bad Gateway responses as recurring local daemon 502s. For common operator endpoints such as agent detail/status, restart, and diff, the local daemon classifies a forwarded unavailable target as remote_agent_unavailable with degraded/unavailable local status, remote node, endpoint, forwarded status, remote error code/message, and retryable metadata when available. Remote status forwarding is also bounded as an authority/health probe, so a settling or half-reachable peer returns structured retryable failure quickly instead of consuming an entire controller sweep.

Spawn Request Body

{
  "node": "localhost",
  "type": "codex",
  "profile": "worker",
  "goal": "Implement ready work",
  "id": null,
  "env": {},
  "hooks": {
    "on_start": [],
    "before_tool": [],
    "after_tool": [],
    "on_complete": []
  },
  "reintegration": {
    "mode": "direct"
  }
}

Session summaries

Summary APIs return the union of state-branch .cacophony/agent/.../summary records and legacy default-branch summaries, de-duplicating by project, agent, and index with the state-branch copy preferred. For state-branch reads, the daemon prefers a warmed read-only checkout under $CACOPHONY_DIR/state-branches/<project>/ and falls back to the canonical project checkout's remote-tracking state ref when that cache is unavailable.

Beads

Messaging

Actions

Release Queue

Notifications

Suggestions

File cache

Links

Audio

TTS Request

{
  "model": "gpt-4o-mini-tts",
  "voice": "sage",
  "text": "Build completed successfully",
  "format": "wav"
}

Supported TTS models: gpt-4o-mini-tts, azure/speech/azure-tts, gemini-3.1-flash-tts-preview. Gemini TTS uses the generateContent API with response_modalities: ["AUDIO"] and requires a Google API key.

• Timeouts: Provider-backed speech synthesis uses a longer bounded daemon timeout than ordinary control-plane endpoints (default 90s, override CACO_AUDIO_SPEECH_REQUEST_TIMEOUT_SECS) so transient provider latency does not fail as a generic 30-second request timeout; the headless TTS daemon uses a matching client budget just below that endpoint timeout (default 85s, override CACO_TTS_AUDIO_TIMEOUT_SECS).
• Expected skips: If the local daemon API is unavailable during an expected restart window, or a quick local daemon-port probe shows the listener is unavailable during a transport failure, the headless TTS daemon classifies speech and acknowledgement connection failures as bounded daemon-unavailable skips rather than provider synthesis failures. Intentional mute policy is also a non-error path: a speech response with audio_muted is treated as skipped playback, traced as audio-muted, and not reported as a daemon exception.
• Caller identity: For feed-originated speech, the headless TTS daemon forwards the originating sender as x-caco-caller before calling this API, so mute-policy evaluation, traces, tts status --explain, and audit output identify the real source agent when known; node-token is only an auth fallback and should not be the displayed agent for agent-authored speech.
• Spoken names: Bead spoken-name refresh is best-effort: failed refreshes back off quietly, use the lightweight GET /api/v1/beads/spoken-names?limit=5000 ID/name projection with a short timeout instead of the full UI snapshot path or broad all-beads payload during daemon startup/backpressure, fall back to /api/v1/beads/all?limit=5000 during mixed-version rollouts, periodically retry after the cooldown when the feed is connected but quiet, including while SSE keepalive chunks are arriving without bead-bearing events, include source endpoint, transport class, error-chain detail, stale-cache versus no-cache failure classification, and a bounded /api/v1/node local-daemon probe in lookup-health diagnostics, and resume normally after a successful refresh.

TTS failures use classified provider error envelopes instead of a generic timeout. Error codes include upstream_provider_5xx, upstream_provider_4xx, upstream_provider_timeout, upstream_provider_unreachable, upstream_provider_transport_error, and upstream_response_read_failed. Where available, details includes upstream_error_class, provider host/endpoint, and HTTP status so callers can distinguish provider outage, bad request, timeout, and transport failures.

Config

Choices & Operator Inbox

Active unresolved choices are treated as urgent operator-decision blockers across first-party clients. TUI, caco-web, Android, macOS, and speech/readout surfaces derive their pending-choice counts from these choices/inbox APIs, route the operator to a resolution surface, and clear the urgent state once the shared choice status becomes terminal. Replicated choice_presented and choice_resolved feed events also materialize or update the durable local operator-inbox choice row so remote choice reads and operator surfaces do not wait for a slower full-state inbox pass before showing or clearing urgent decisions.

Restart

The restart endpoint responds immediately with accepted: true before spawning the restart subprocess. Since the restart tears down the current daemon process, the actual outcome cannot be reported synchronously. The caller should poll daemon health to determine success. Available on both local and cluster listeners.

Logs

Sidecar Endpoints

Each long-running service exposes a sidecar with uniform endpoints:

Cluster-Only Endpoints

These endpoints are available only on the cluster (HTTPS/mTLS) listener: