API Reference
Itervox exposes a REST + Server-Sent Events (SSE) API on the dashboard port (default :8090). The web dashboard, TUI, and any custom integrations talk to the same endpoints.
Base URL
Section titled “Base URL”http://localhost:8090/api/v1The host and port are configured in WORKFLOW.md under server.host and server.port.
Authentication
Section titled “Authentication”When the ITERVOX_API_TOKEN environment variable is set, all /api/v1/* routes (except /health) require a bearer token:
curl -H "Authorization: Bearer $ITERVOX_API_TOKEN" \ http://localhost:8090/api/v1/stateWithout the env var, the API is open. Strongly recommended when binding the server to a non-loopback address (server.host: 0.0.0.0).
Health & State
Section titled “Health & State”GET /health
Section titled “GET /health”Liveness probe for load balancers and container orchestrators. Always returns 200 with no body. Bypasses bearer-token auth.
GET /state
Section titled “GET /state”Returns the current orchestrator snapshot as JSON. One-shot equivalent of the SSE stream.
Response: StateSnapshot — running sessions, history, retry queue, paused issues, profiles, models, rate limits, configuration.
curl http://localhost:8090/api/v1/state | jqGET /events
Section titled “GET /events”SSE stream of StateSnapshot events. Each data: frame is a full JSON snapshot. The web dashboard uses this for real-time updates with a 25s keep-alive.
curl -N http://localhost:8090/api/v1/eventsPOST /refresh
Section titled “POST /refresh”Triggers an immediate orchestrator poll cycle. Useful after manual issue state changes when you don’t want to wait for the next scheduled tick.
Issues
Section titled “Issues”GET /issues
Section titled “GET /issues”Returns the full list of tracker issues enriched with orchestrator state (running/retrying/paused/idle).
GET /issues/{identifier}
Section titled “GET /issues/{identifier}”Returns details for a single issue, including title, description, comments, labels, priority, and orchestrator state.
POST /issues/{identifier}/cancel (or DELETE /issues/{identifier})
Section titled “POST /issues/{identifier}/cancel (or DELETE /issues/{identifier})”Pauses a running agent. The agent process is killed, the issue is marked paused, and it will not be re-dispatched until resumed. Returns 200 on success, 404 if the issue is not running.
POST /issues/{identifier}/resume
Section titled “POST /issues/{identifier}/resume”Resumes a paused issue. The issue becomes eligible for dispatch on the next tick.
POST /issues/{identifier}/terminate
Section titled “POST /issues/{identifier}/terminate”Hard-stops a running or paused agent without pausing it. Releases the claim and moves the issue back to the active state, allowing immediate re-dispatch.
POST /issues/{identifier}/reanalyze
Section titled “POST /issues/{identifier}/reanalyze”Re-dispatches an issue, bypassing the open-PR auto-pause guard. Use this when you’ve made changes to an existing PR and want the agent to re-analyze it.
POST /issues/{identifier}/ai-review
Section titled “POST /issues/{identifier}/ai-review”Dispatches a reviewer agent for the issue. The reviewer runs the configured reviewer profile against the open PR for that issue.
POST /issues/{identifier}/profile
Section titled “POST /issues/{identifier}/profile”Sets or clears the per-issue agent profile override. Body: {"profile": "frontend"} to set, {"profile": ""} to clear.
POST /issues/{identifier}/backend
Section titled “POST /issues/{identifier}/backend”Sets the per-issue backend override (claude or codex). Body: {"backend": "claude"}.
POST /issues/{identifier}/provide-input
Section titled “POST /issues/{identifier}/provide-input”Replies to an issue waiting in input-required state. Body: {"message": "..."}. The agent session resumes with the provided message injected into the prompt.
POST /issues/{identifier}/dismiss-input
Section titled “POST /issues/{identifier}/dismiss-input”Dismisses an input-required issue without providing input. Moves it to paused state.
GET /issues/{identifier}/logs
Section titled “GET /issues/{identifier}/logs”Returns the full per-issue log buffer as a JSON array of structured IssueLogEntry objects.
GET /issues/{identifier}/log-stream
Section titled “GET /issues/{identifier}/log-stream”SSE stream of new log entries for an issue. Each event: log frame carries one parsed IssueLogEntry. The dashboard uses this for live log following.
curl -N http://localhost:8090/api/v1/issues/PROJ-42/log-streamGET /issues/{identifier}/sublogs
Section titled “GET /issues/{identifier}/sublogs”Returns full session logs written by Claude Code to CLAUDE_CODE_LOG_DIR. Covers all subagents spawned during the session, not just the orchestrator-buffered top-level events.
DELETE /issues/{identifier}/logs
Section titled “DELETE /issues/{identifier}/logs”Clears the in-memory log buffer for an issue.
DELETE /issues/{identifier}/sublogs
Section titled “DELETE /issues/{identifier}/sublogs”Clears all subagent session logs for an issue.
DELETE /issues/{identifier}/sublogs/{sessionId}
Section titled “DELETE /issues/{identifier}/sublogs/{sessionId}”Clears a specific subagent session log.
GET /logs/identifiers
Section titled “GET /logs/identifiers”Returns the list of issue identifiers that currently have log data on the server.
GET /logs
Section titled “GET /logs”Tails the global rotating log file (the daemon log, not per-issue logs).
DELETE /logs
Section titled “DELETE /logs”Clears all in-memory log buffers across all issues.
Settings — Runtime Configuration
Section titled “Settings — Runtime Configuration”All settings endpoints persist changes to WORKFLOW.md so they survive restarts.
POST /settings/workers
Section titled “POST /settings/workers”Scale the maximum concurrent agent count. Body: {"workers": 5} (absolute) or {"delta": 1} (relative).
POST /settings/agent-mode
Section titled “POST /settings/agent-mode”Switch agent collaboration mode. Body: {"mode": "solo"}, {"mode": "subagents"}, or {"mode": "teams"}.
PUT /settings/tracker/states
Section titled “PUT /settings/tracker/states”Update the active, terminal, completion, and backlog state lists. Body matches the tracker block in WORKFLOW.md.
POST /settings/ssh-hosts
Section titled “POST /settings/ssh-hosts”Add a remote worker host. Body: {"host": "ssh.example.com", "description": "..."}.
DELETE /settings/ssh-hosts/{host}
Section titled “DELETE /settings/ssh-hosts/{host}”Remove an SSH worker host.
PUT /settings/dispatch-strategy
Section titled “PUT /settings/dispatch-strategy”Change SSH host dispatch strategy. Body: {"strategy": "round-robin"} or {"strategy": "least-loaded"}.
POST /settings/workspace/auto-clear
Section titled “POST /settings/workspace/auto-clear”Toggle automatic workspace cleanup on completion. Body: {"enabled": true}.
POST /settings/inline-input
Section titled “POST /settings/inline-input”Toggle inline input mode (input-required prompts in the dashboard vs tracker comments). Body: {"enabled": true}.
GET /settings/models
Section titled “GET /settings/models”Returns the list of available models per backend (discovered at init time, stored in WORKFLOW.md).
Settings — Profiles & Reviewer
Section titled “Settings — Profiles & Reviewer”GET /settings/profiles
Section titled “GET /settings/profiles”Returns the full map of named agent profiles from WORKFLOW.md.
PUT /settings/profiles/{name}
Section titled “PUT /settings/profiles/{name}”Create or update a named agent profile. Body: {"command": "...", "prompt": "...", "backend": "claude"}.
DELETE /settings/profiles/{name}
Section titled “DELETE /settings/profiles/{name}”Remove a profile.
GET /settings/reviewer
Section titled “GET /settings/reviewer”Returns the reviewer profile configuration and auto_review flag.
PUT /settings/reviewer
Section titled “PUT /settings/reviewer”Update reviewer config. Body: {"profile": "...", "auto_review": true}.
Projects (Linear only)
Section titled “Projects (Linear only)”These endpoints return 501 Not Implemented for the GitHub tracker.
GET /projects
Section titled “GET /projects”Returns the list of accessible projects from the tracker.
GET /projects/filter
Section titled “GET /projects/filter”Returns the active project filter (array of project slugs, or null for default, or [] for all).
PUT /projects/filter
Section titled “PUT /projects/filter”Sets the active project filter. Body: {"slugs": ["alpha", "beta"]}.
Workspaces
Section titled “Workspaces”DELETE /workspaces
Section titled “DELETE /workspaces”Removes all worktrees managed by Itervox. Use with caution — agents currently running will fail their next git operation.
SSE Event Reference
Section titled “SSE Event Reference”Snapshot stream (GET /events)
Section titled “Snapshot stream (GET /events)”data: {"running":[...],"history":[...],"retrying":[...],"paused":[...],...}Each frame is a complete StateSnapshot. Keep-alive ping every 25 seconds.
Log stream (GET /issues/{id}/log-stream)
Section titled “Log stream (GET /issues/{id}/log-stream)”event: logdata: {"event":"action","tool":"bash","message":"grep -r ...","sessionId":"..."}event is one of: text, action, subagent, pr, turn, error, warn, info.
Environment Variables
Section titled “Environment Variables”| Variable | Purpose |
|---|---|
ITERVOX_API_TOKEN | Bearer token for API authentication. When set, all routes except /health require Authorization: Bearer <token>. |
LINEAR_API_KEY | Linear API token (referenced from WORKFLOW.md as $LINEAR_API_KEY). |
GITHUB_TOKEN | GitHub Personal Access Token (referenced as $GITHUB_TOKEN). |
ITERVOX_DRY_RUN | Set to 1 to run the orchestrator without dispatching actual agent workers. |
Note:
ITERVOX_*env var names are legacy from the previous project name and remain supported for backwards compatibility. They will be aliased toITERVOX_*in a future release.