Complete REST API and WebSocket documentation for Agent Dashboard.
- Overview
- Authentication
- Base URL
- REST API
- WebSocket API
- Error Handling
- Rate Limiting
- Pagination
- Examples
The Agent Dashboard API provides programmatic access to Claude Code session monitoring data.
graph LR
Client[API Client] -->|HTTP/HTTPS| REST[REST API<br/>:4820/api/*]
Client -->|WebSocket| WS[WebSocket<br/>:4820/ws]
REST --> DB[(SQLite)]
WS --> Broadcast[Real-time<br/>Broadcasts]
style REST fill:#10B981
style WS fill:#F59E0B
style DB fill:#003B57,color:#fff
Protocols:
- REST API - HTTP/JSON for queries and mutations
- WebSocket - Real-time event streaming
The server is local-first and is hardened to keep the dashboard off the network by default (see GHSA-gr74-4xfh-6jw9). The trust boundary is the loopback bind, layered with origin and host checks:
- Loopback bind by default — the server binds
127.0.0.1, so it is not network-reachable out of the box. Operators opt into a wider bind withDASHBOARD_HOST(e.g.DASHBOARD_HOST=0.0.0.0for LAN access), which logs a startup warning. - CORS restricted to loopback origins — cross-origin web pages cannot read API responses. Requests with no
Origin(curl, server-to-server) still work. - Host-header allowlist — both HTTP requests and WebSocket upgrades are checked against an allowlist to block DNS-rebinding. Add extra LAN names (when you bind beyond loopback) via
DASHBOARD_ALLOWED_HOSTS(comma-separated).
For deliberate LAN exposure, set DASHBOARD_HOST to a non-loopback address and list the names clients use in DASHBOARD_ALLOWED_HOSTS.
Authentication is off by default (the loopback bind is the trust boundary). When DASHBOARD_TOKEN is set, every /api/* request and the WebSocket must present the token. It is strongly recommended whenever you bind beyond loopback. Pass it any of these ways:
Authorization: Bearer <token>headerx-dashboard-token: <token>header?token=<token>query parameter
These paths stay exempt even when a token is configured: /api/health, /api/openapi.json, /api/docs, and /api/hooks (local Claude Code and Codex hook ingestion, plus the optional DASHBOARD_HOOK_TOKEN when set). Requests that fail the check get 401 with error code EUNAUTHORIZED. The remote-push exceptions inside that namespace are POST /api/hooks/ingest-batch and POST /api/hooks/ingest-transcript. Both carry their own mandatory REMOTE_PUSH_TOKEN and stay disabled until it is configured.
GET /api/settings/info includes server.version (the running dashboard release). Pair with ccam version or the Settings About panel to confirm client and server builds match after deploy.
sequenceDiagram
participant Client
participant API
participant Auth
participant Resource
Client->>API: Request + DASHBOARD_TOKEN
API->>Auth: Validate token (if configured)
Auth-->>API: Valid
API->>Resource: Fetch Data
Resource-->>API: Return Data
API-->>Client: 200 OK + Data
- Prefer the
Authorization: Bearer <token>header for regular integrations. The query parameter is supported for constrained clients, but URLs are more likely to end up in shell history, browser history, and access logs. - Keep
DASHBOARD_TOKENin a secret store or environment variable; do not place it in a checked-in client bundle or example URL. - Treat
/api/healthas a liveness probe only. It is intentionally exempt from token checks and cannot verify that a client is authorized for protected API routes. - When exposing the dashboard beyond loopback, terminate TLS before the API, configure
DASHBOARD_ALLOWED_HOSTSwith the hostname clients use, and test both an authenticated REST request and WebSocket connection from the intended origin.
http://localhost:4820
For production, use HTTPS:
https://dashboard.example.com
GET /api/sessionsReturns all sessions, ordered by most recent activity. Each list row includes the boolean
has_token_usage: true means at least one durable token_usage bucket exists, even if every
counter is zero or the model is unpriced. It does not indicate whether all usage is priced.
Rows with no buckets, including transient Codex process-overlay rows, report false.
Do not infer coverage from cost, which can be zero in either case. This flag is computed
for the list response; it is not a stored session column or a guaranteed field on detail or
WebSocket responses.
repo_remote_url is optional collector-supplied metadata, not an automatically discovered Git
remote. The first non-empty sanitized value wins, including when supplied after session creation;
later hooks or batches cannot replace it. URL/SCP userinfo, query strings, and fragments are
removed, and malformed URL-style values are discarded before session or hook-event storage.
For example, git@example.internal:team/project.git becomes example.internal:team/project.git.
Consumers may canonicalize the retained value to match a repository across machine-local cwd
paths; it is an identity hint, not a clone credential. Each row may include an optional
prompt_preview for compact cards: the two newest distinct real human prompts, oldest to
newest and newline-separated. Claude Code persists this bounded summary from the local JSONL
cache during hooks, imports, and watchdog sweeps; Codex derives it from durable
codex_user_message records. Historical rows fall back to the main-agent task. The detail route
returns the same optional field.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 50 | Maximum durable sessions to return (up to 10000) |
offset |
integer | 0 | Pagination offset |
status |
string | - | Filter by persisted status: active, completed, error, abandoned. The UI Waiting state is derived from the awaiting_input_since column and is not a queryable enum — filter status=active and inspect awaiting_input_since (non-null = Waiting) |
q |
string | - | Case-insensitive search across id, name, and cwd |
cwd |
string (repeatable) | - | Exact working directory filter. Repeat it to include multiple projects, for example cwd=/work/a&cwd=/work/b |
sort_by |
string | time |
Ordering dimension: time, duration, or price |
sort_desc |
boolean | true |
Use descending order; set to false for ascending order |
sources |
string | - | Comma-separated data-source ids to include (the built-in local history is local; remote SSH machines use their remote_sources.id). Omit for all sources. Also accepted on /api/events, /api/agents, /api/stats, /api/analytics, and /api/pricing/cost. See Remote Data Sources |
providers |
string | - | Comma-separated stored providers: claude, cursor, and/or codex. Requesting claude also includes Cursor for the Claude-compatible product scope; requesting cursor directly isolates Cursor sessions. It composes with sources and is accepted by the scoped list, aggregate, facet, per-session detail, cost, and workflow routes. Codex workflow responses include its recorded response_item tool calls, token/model totals, and context_compacted events; only Claude Code's Workflow-tool run journals are unavailable for Codex. |
provider |
string | - | Exact stored provider for this Sessions list: claude, cursor, or codex. It intersects the broader providers product scope, so a page-level selection cannot escape the product scope chosen in onboarding or Settings. |
include_transient |
boolean | false |
Opt in to local, in-memory Codex startup cards before Codex exposes a stable session ID. On /api/sessions, this is honored only on the first page when status is absent or active; on /api/agents, only on the first status=waiting page without session_id. These cards are prepended without changing durable total, pagination, analytics, pricing, workflows, alerts, or history. |
include_task_progress |
boolean | false |
Attach nullable todo_summary values for the latest top-level work item to at most the first 100 returned rows. A new Claude human turn or Codex task that emits no tracker clears older state; a turn/task ending without a final update drops unfinished state. Fully completed history remains available. Each transcript is read 32 MiB deep on first contact and incrementally after that, starting over with a fresh 32 MiB scan if it grew by more than that since the last read (state covers its newest 32 MiB), and each summary includes at most five preview tasks. Rows after the enrichment cap omit the field. |
Example Request:
curl "http://localhost:4820/api/sessions?limit=10&status=active&include_task_progress=true"last_activity in every list row is the timestamp of the latest durable session event. It does not reuse the mutable updated_at bookkeeping timestamp, so a title, card-context, or watchdog repair cannot make an idle session appear newly active. Eventless historical rows fall back to their lifecycle timestamp.
Example Response:
{
"sessions": [
{
"id": "sess_abc123",
"name": "Implement task progress",
"model": "claude-sonnet-4",
"status": "active",
"cost": 1.23,
"has_token_usage": true,
"repo_remote_url": "ssh://example.internal:2222/team/project.git",
"agent_count": 3,
"started_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T14:30:00Z",
"todo_summary": {
"total": 2,
"completed": 1,
"inProgress": 1,
"pending": 0,
"cancelled": 0,
"unknown": 0,
"percentComplete": 50,
"activeText": "Implement tracker",
"sourceTool": "TaskList",
"updatedAt": "2024-03-18T14:29:00Z",
"previewItems": [
{
"id": "task-2",
"text": "Implement tracker",
"status": "in_progress",
"sourceStatus": "in_progress",
"order": 1,
"agentId": "sess_abc123-main",
"agentType": "main",
"description": null
}
],
"overflowCount": 1,
"ownerBreakdown": [
{
"agentId": "sess_abc123-main",
"agentType": "main",
"completed": 1,
"total": 2
}
]
}
}
],
"total": 42,
"limit": 10,
"offset": 0
}Response Schema:
classDiagram
class SessionListResponse {
+Session[] sessions
+number total
+number limit
+number offset
}
class Session {
+string id
+string name
+string status "active|completed|error|abandoned"
+string cwd
+string repo_remote_url "nullable opaque repository identity"
+string model
+boolean has_token_usage "durable token buckets exist"
+string prompt_preview "nullable card context"
+string started_at
+string ended_at
+string updated_at
+string last_activity "latest durable event; lifecycle fallback"
+string awaiting_input_since "null unless Waiting"
+string awaiting_reason "notification|stop|session_start|interrupted; null unless Waiting"
+number cost
+number agent_count
}
SessionListResponse --> Session
GET /api/sessions/:idReturns single session details. The session.todo_snapshot field contains the latest observable,
owner-attributed task state when Claude emitted TaskCreate / TaskGet / TaskUpdate /
TaskList, legacy TodoWrite, task lifecycle events, or Codex emitted update_plan; otherwise
it is null. State is scoped to the latest top-level work boundary: a real Claude human turn or
Codex task_started clears all prior owners, and a subagent's next assigned turn clears only that
owner. If no fresh task state follows, older trackers stay removed. Harness task notifications do
not count as human turns. Claude turn-end records and Codex task_complete / turn_aborted also
discard owner snapshots that still contain unfinished work, while fully completed/cancelled snapshots
remain as history. Persisted Claude prompt/stop/session lifecycle events apply those boundaries even
when the corresponding transcript marker has not flushed yet, so an immediate live refetch returns
the latest state. The parser reads the newest 32 MiB of each transcript on first contact, then only what was appended since the last complete line, starting over if more than 32 MiB arrived since the last read (state covers the newest 32 MiB), at a complete-line
boundary, and the full snapshot contains at most 200 task rows.
GET /api/sessions?include_task_progress=true exposes the nullable todo_summary counterpart
for list rows, including at most five preview tasks and enriching at most 100 returned rows.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Session ID (e.g., sess_abc123) |
Example Request:
curl http://localhost:4820/api/sessions/sess_abc123Example Response:
{
"session": {
"id": "sess_abc123",
"name": "Implement task progress",
"model": "claude-sonnet-4",
"status": "active",
"started_at": "2026-08-07T10:00:00.000Z",
"updated_at": "2026-08-07T10:15:00.000Z",
"todo_snapshot": {
"provider": "claude",
"source": "transcript",
"sourceTool": "TaskList",
"sourceLine": 42,
"updatedAt": "2026-08-07T10:14:00.000Z",
"explanation": null,
"confidence": "full",
"items": [
{
"id": "task-1",
"text": "Implement task progress",
"status": "in_progress",
"sourceStatus": "in_progress",
"order": 0,
"agentId": "sess_abc123-main",
"agentType": "main",
"description": null
}
],
"total": 1,
"completed": 0,
"inProgress": 1,
"pending": 0,
"cancelled": 0,
"unknown": 0,
"percentComplete": 0,
"activeText": "Implement task progress",
"includesSubagents": false,
"ownerBreakdown": [
{
"agentId": "sess_abc123-main",
"agentType": "main",
"completed": 0,
"total": 1
}
]
}
},
"agents": [],
"events": [],
"workflows": []
}Error Responses:
| Code | Description |
|---|---|
| 404 | Session not found |
| 500 | Internal server error |
GET /api/sessions/:id/transcriptReturns a cursor-paginated transcript page. Pass limit (up to 200), after to
read newer JSONL lines, or before to load the preceding page; responses include
first_line, last_line, and has_more for the next request. Claude Code
responses include its normal conversation and local command records. Codex
responses include human turns, legacy function_call records, and the primary
custom_tool_call stream (including exec input and paired output), so clients
can render the actual command flow rather than only wait calls. Both providers
also expose persisted PNG/JPEG/GIF/WebP user attachments as image content blocks;
missing or expired files are simply omitted, and Codex's duplicated response/event
user records are returned as one human turn. Cursor main sessions merge the
ordered native store.db conversation, including tool calls/results and the
concrete response model, with any replies available only in JSONL.
prompt_history.json fills submitted prompts that neither durable source has
recorded yet. JSONL sources are snapshotted directly; native stores are reduced
to a verified store.compact.db that reconciles the current root with
legacy-only references and preserves every selected raw blob byte-for-byte.
Repeated and parser-opaque references remain intact. Sources attach through
read-only, non-creating SQLite URIs, and a per-session lock serializes live and
worker installs. Legacy-only stores migrate in isolated batches of at most four
per sync; an empty scheduled scan waits five minutes before checking again.
Stores are removed only after root containment and raw verification; an unchanged
source stops retrying after five failures in one process and remains on disk. Prompt
history is read from the live Cursor chat directory only. Messages carry stable id values, and an
incremental result with refresh: true is a latest window that clients merge by
id. A Cursor /resume shell ID is also accepted here and resolves to the
canonical conversation before the transcript is read. The response does not
include the canonical ID; the old ID remains accepted.
GET /api/sessions/:id/transcript-image?line={line}&index={index}Streams a same-origin image referenced by one persisted Claude transcript line. The
transcript response provides this opaque URL rather than its local path. Codex inline
attachments are already returned as validated data:image/... block sources. Only bounded
PNG, JPEG, GIF, and WebP images are served; unavailable files return 404.
GET /api/sessions/:id/statsReturns aggregated counts powering the Session Detail overview panel. All aggregation runs in SQL — the response is cheap to compute even for sessions with tens of thousands of events.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Session ID |
Example Request:
curl http://localhost:4820/api/sessions/sess_abc123/statsExample Response:
{
"session_id": "sess_abc123",
"total_events": 14082,
"events_by_type": [
{ "event_type": "PreToolUse", "count": 5210 },
{ "event_type": "PostToolUse", "count": 5208 }
],
"tools_used": [
{ "tool_name": "Bash", "count": 1842 },
{ "tool_name": "Read", "count": 1340 }
],
"error_count": 12,
"first_event_at": "2026-04-26T18:59:00.000Z",
"last_event_at": "2026-04-29T21:30:14.000Z",
"agents": {
"total": 12,
"main": 1,
"subagent": 11,
"compaction": 5,
"by_status": { "completed": 11, "working": 1 }
},
"subagent_types": [
{ "subagent_type": "Explore", "count": 4 }
],
"tokens": {
"input_tokens": 1376,
"output_tokens": 760304,
"cache_read_tokens": 337641891,
"cache_write_tokens": 5126047
}
}Error Responses:
| Code | Description |
|---|---|
| 404 | Session not found |
| 500 | Internal server error |
GET /api/sessions/:id/agentsReturns all agents for a session.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Session ID |
Example Request:
curl http://localhost:4820/api/sessions/sess_abc123/agentsExample Response:
{
"agents": [
{
"id": "sess_abc123-main",
"session_id": "sess_abc123",
"name": "Main Agent - my-project",
"type": "main",
"subagent_type": null,
"status": "idle",
"current_tool": null,
"task": null,
"started_at": "2024-03-18T12:00:00Z",
"ended_at": null,
"updated_at": "2024-03-18T12:05:00Z",
"parent_agent_id": null,
"awaiting_input_since": "2024-03-18T12:05:00Z",
"awaiting_reason": "stop",
"cost": 0
}
]
}Note on
cost—/api/agentsand/api/sessions/:id/agentsattach acost(USD) to each agent: the agent's own cost, computed server-side from the per-agent token buckets stored inagents.metadata.tokensand priced at the current pricing rules (at the agent's start date, so promo/standard cutovers apply — see Pricing). It is0for main agents (whose cost is the session total, reported by/api/pricing/cost/:sessionId), for compaction pseudo-agents, and for any subagent whose transcript is unavailable. This lets a subagent card show only what that subagent spent instead of the whole session's total.
Note on real activity time — agent list/detail reads include
last_activity, derived from the latest durable event attributed to that agent. Use it for user-facing time labels instead of mutableupdated_at, which can change during status or metadata maintenance without new CLI activity.
Note on
statusvs Waiting — agents are persisted with one ofidle | connected | working | completed | error. The yellow Waiting badge surfaced in the dashboard is a UI overlay derived fromawaiting_input_sincebeing non-null on a non-terminal agent (typicallyidleafter aStop, orconnectedright afterSessionStart). Filter?status=idleon/api/agentsand inspectawaiting_input_sinceto enumerate currently-waiting main agents.
GET /api/agents/:idReturns single agent details.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Agent ID (e.g., agent_xyz789) |
Example Request:
curl http://localhost:4820/api/agents/agent_xyz789Example Response:
{
"agent": {
"id": 1,
"agent_id": "agent_xyz789",
"session_id": "sess_abc123",
"agent_type": "explore",
"status": "completed",
"current_tool": null,
"input_tokens": 1500,
"output_tokens": 800,
"cost": 0.45,
"created_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T12:05:00Z"
}
}GET /api/agents/:id/toolsReturns tool executions for an agent.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Agent ID |
Example Request:
curl http://localhost:4820/api/agents/agent_xyz789/toolsExample Response:
{
"tools": [
{
"id": 1,
"agent_id": "agent_xyz789",
"tool_name": "bash",
"duration_ms": 1234,
"success": 1,
"error_message": null,
"created_at": "2024-03-18T12:01:00Z"
},
{
"id": 2,
"agent_id": "agent_xyz789",
"tool_name": "view",
"duration_ms": 45,
"success": 1,
"error_message": null,
"created_at": "2024-03-18T12:02:00Z"
}
]
}Tool Execution Flow:
sequenceDiagram
participant Agent
participant PreHook as PreToolUse Hook
participant Tool as Tool Execution
participant PostHook as PostToolUse Hook
participant DB as Database
Agent->>PreHook: Tool about to execute
PreHook->>DB: Set current_tool
Agent->>Tool: Execute (bash, view, etc.)
Tool-->>Agent: Result
Agent->>PostHook: Tool completed
PostHook->>DB: Create tool_execution record
PostHook->>DB: Clear current_tool
PostHook->>DB: Update token counts + cost
GET /api/toolsReturns all tool executions across all sessions.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 100 | Max tools to return |
tool_name |
string | - | Filter by tool name |
success |
boolean | - | Filter by success status |
Example Request:
curl http://localhost:4820/api/tools?limit=50&tool_name=bashExample Response:
{
"tools": [
{
"id": 1,
"agent_id": "agent_xyz789",
"tool_name": "bash",
"duration_ms": 1234,
"success": 1,
"error_message": null,
"created_at": "2024-03-18T12:01:00Z"
}
],
"total": 156
}GET /api/metrics
Exposes the dashboard's live counters in the Prometheus text-exposition format (v0.0.4) so this monitoring dashboard can itself be scraped into Prometheus / Grafana. Read-only. Values are read from the same prepared statements the REST API uses, so they match the UI.
Response Content-Type: text/plain; version=0.0.4; charset=utf-8.
| Metric | Type | Labels | Meaning |
|---|---|---|---|
ccam_up |
gauge | — | 1 when the API served the scrape |
ccam_build_info |
gauge | version |
Always 1; dashboard version rides on the label |
ccam_process_uptime_seconds |
gauge | — | Server process uptime |
ccam_process_resident_memory_bytes |
gauge | — | Server process RSS |
ccam_sessions |
gauge | status (active/completed/error/abandoned) |
Sessions by status |
ccam_agents |
gauge | status (working/waiting/completed/error) |
Agents by status |
ccam_events_total |
counter | — | Total events recorded |
ccam_websocket_clients |
gauge | — | Connected realtime clients |
ccam_remote_sources |
gauge | enabled (true/false) |
Configured Remote Data Sources |
ccam_tokens_total |
counter | kind (input/output/cache_read/cache_write) |
Cumulative token usage |
Status series are always emitted (even at 0) so a series never disappears from the exposition. The endpoint is mounted under /api, so it sits behind the same two guards as every other route: the Host-header (DNS-rebinding) guard and the optional DASHBOARD_TOKEN guard. A scraper that reaches the server as anything other than loopback (e.g. Prometheus in Docker hitting host.docker.internal) must be allowlisted with DASHBOARD_ALLOWED_HOSTS, or the scrape returns 403 EBADHOST; if a token is set, the scrape must also send it.
Example scrape config (start the server with DASHBOARD_ALLOWED_HOSTS=host.docker.internal):
scrape_configs:
- job_name: ccam
metrics_path: /api/metrics
static_configs:
- targets: ["host.docker.internal:4820"]
# authorization: # only if DASHBOARD_TOKEN is set
# credentials: "<DASHBOARD_TOKEN>"A ready-to-run Prometheus + Grafana stack (four auto-provisioned dashboards; default home CCAM — Overview) lives in monitoring/. npm path (no Docker): npm run monitoring:install then npm run monitoring:up (binaries are pulled via the monitoring package's postinstall — there is no official grafana/prometheus server package on npm). Docker path: npm run monitoring:docker:up or npm run docker:full:up (set DASHBOARD_ALLOWED_HOSTS=host.docker.internal on the dashboard when Prometheus runs in a container). Pre-built Prometheus console: http://localhost:9090/consoles/index.html.
GET /api/pricingReturns all pricing rules (default + custom).
Example Request:
curl http://localhost:4820/api/pricingExample Response:
{
"rules": [
{
"id": 1,
"pattern": "claude-sonnet-4",
"input_cost_per_1m": 3.0,
"output_cost_per_1m": 15.0,
"is_default": true,
"created_at": "2024-03-18T12:00:00Z"
},
{
"id": 10,
"pattern": "gpt-5.1-codex",
"input_cost_per_1m": 2.5,
"output_cost_per_1m": 10.0,
"is_default": false,
"created_at": "2024-03-18T14:30:00Z"
}
]
}Pricing Rule Matching:
graph TB
Model[Model Name<br/>e.g., claude-sonnet-4] --> Match{Match Pattern?}
Match -->|Exact Match| Custom[Use Custom Rule]
Match -->|Substring Match| Default[Use Default Rule]
Match -->|No Match| Fallback[Use Generic Fallback]
Custom --> Calculate[Calculate Cost]
Default --> Calculate
Fallback --> Calculate
Calculate --> Result[input_cost + output_cost]
style Calculate fill:#10B981
PUT /api/pricingUpsert a pricing rule, keyed by model_pattern. The same call creates a new rule or updates an existing one (matched on model_pattern). Rates are per million tokens.
Request Body:
{
"model_pattern": "claude-sonnet-5%",
"display_name": "Claude Sonnet 5",
"input_per_mtok": 2,
"output_per_mtok": 10,
"cache_read_per_mtok": 0.2,
"cache_write_per_mtok": 2.5,
"cache_write_1h_per_mtok": 4,
"fast_input_per_mtok": 0,
"fast_output_per_mtok": 0,
"intro_until": "2026-08-31",
"intro_input_per_mtok": 2,
"intro_output_per_mtok": 10,
"intro_cache_read_per_mtok": 0.2,
"intro_cache_write_per_mtok": 2.5,
"intro_cache_write_1h_per_mtok": 4
}Fields:
| Field | Type | Constraints |
|---|---|---|
model_pattern |
string | Required. SQL-style glob; % matches any characters (e.g. claude-opus-4-7%) |
display_name |
string | Required |
input_per_mtok / output_per_mtok |
number | Standard per-MTok rates (default 0) |
cache_read_per_mtok / cache_write_per_mtok / cache_write_1h_per_mtok |
number | Cache rates (default 0) |
fast_input_per_mtok / fast_output_per_mtok |
number | Fast-mode premium rates (default 0) |
intro_until |
string | null | Optional promo cutoff YYYY-MM-DD. Usage on or before this date is priced at the intro_* rates, after it at the standard rates. Empty/null clears the promo (and zeroes the intro rates) |
intro_*_per_mtok |
number | Optional introductory (promo) rates, mirroring the standard fields |
The intro block is optional and backward-compatible: a request that omits every intro_*/intro_until field leaves any existing promo untouched, so older clients that send only the standard rates never clobber a promo.
Validation: every *_per_mtok rate present in the body must be a non-negative finite number (numeric strings are coerced); a NaN, non-numeric, or negative value is rejected with 400 INVALID_INPUT naming the offending field, and nothing is written. intro_until must be a YYYY-MM-DD date (or empty/null to clear the promo).
Example Request:
curl -X PUT http://localhost:4820/api/pricing \
-H "Content-Type: application/json" \
-d '{
"model_pattern": "gpt-5.1-codex",
"display_name": "GPT-5.1 Codex",
"input_per_mtok": 2.5,
"output_per_mtok": 10.0
}'Example Response:
{
"pricing": {
"model_pattern": "gpt-5.1-codex",
"display_name": "GPT-5.1 Codex",
"input_per_mtok": 2.5,
"output_per_mtok": 10.0,
"intro_until": null,
"updated_at": "2026-07-01T14:30:00Z"
}
}Error Responses:
| Code | Description |
|---|---|
| 400 | Missing model_pattern/display_name, or intro_until not a YYYY-MM-DD date |
| 500 | Database error |
GET /api/pricing/cursor
PUT /api/pricing/cursor
DELETE /api/pricing/cursor/:patternCursor sessions are priced only against this independent four-column rate card. Each row contains model_pattern, display_name, input_per_mtok, cache_write_per_mtok, cache_read_per_mtok, and output_per_mtok. Rates are USD per million tokens; every supplied rate must be finite and non-negative. Longest/more-specific patterns win, so Cursor Fast entries override their base family. A zero cache-write column represents Cursor's unavailable (-) value and is displayed as an em dash in Settings.
{
"model_pattern": "grok-4.6-fast%",
"display_name": "Cursor Grok 4.6 (Fast)",
"input_per_mtok": 4,
"cache_write_per_mtok": 0,
"cache_read_per_mtok": 1,
"output_per_mtok": 12
}POST /api/settings/reset-pricing accepts provider: "cursor" in addition to claude and codex. Omitting the body resets all three tables. The response includes pricing, cursor_pricing, and gpt_pricing.
GET /api/pricing/gpt
PUT /api/pricing/gpt
DELETE /api/pricing/gpt/:patternThese endpoints manage the separate GPT rate card used only for Codex sessions. Each row has four USD-per-million-token rates for each of four groups: short_* for standard requests at or below 272K input tokens, long_* for larger standard requests, fast_* for short Fast requests, and fast_long_* for Fast requests above 272K. Older API clients that omit fast_long_* retain the existing values on update. The four rates are input, cached input, cache writes, and output. Every present rate must be a finite non-negative number. A published but unavailable tier is stored as an all-zero group and surfaced in cost responses as unpriced, rather than silently guessing a price.
Upgrade behavior: startup corrects only exact obsolete default Astra/Sol rates. When the Fast long columns are first added, untouched defaults receive the published Astra and GPT-5.6 Fast long rates; customized rules inherit their existing Fast rates in the new band. Subsequent restarts preserve edits, including an explicit zero rate. Cost estimates are calculated on read, so corrected defaults also reprice existing sessions. No token re-import is required. Sol uses the currently configured rate for historical estimates too; the dashboard neither fetches live prices nor schedules an assumed promotional price increase. Reset Defaults deliberately replaces the selected provider's custom prices.
POST /api/settings/reset-pricing accepts an optional provider body to reset only one table; see the Cursor section above. Omitting the body preserves compatibility and resets all provider tables.
{
"model_pattern": "gpt-5.6-terra%",
"display_name": "GPT-5.6 Terra",
"short_input_per_mtok": 2,
"short_cached_input_per_mtok": 0.2,
"short_cache_write_per_mtok": 2.5,
"short_output_per_mtok": 12,
"long_input_per_mtok": 4,
"long_cached_input_per_mtok": 0.4,
"long_cache_write_per_mtok": 5,
"long_output_per_mtok": 18,
"fast_input_per_mtok": 4,
"fast_cached_input_per_mtok": 0.4,
"fast_cache_write_per_mtok": 5,
"fast_output_per_mtok": 24,
"fast_long_input_per_mtok": 8,
"fast_long_cached_input_per_mtok": 0.8,
"fast_long_cache_write_per_mtok": 10,
"fast_long_output_per_mtok": 36
}DELETE /api/pricing/:patternDelete custom pricing rule (default rules cannot be deleted).
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
pattern |
string | Pattern to delete (URL-encoded) |
Example Request:
# Pattern must be URL-encoded
curl -X DELETE http://localhost:4820/api/pricing/gpt-5.1-codexExample Response:
{
"deleted": true
}Error Responses:
| Code | Description |
|---|---|
| 404 | Pattern not found |
| 403 | Cannot delete default rule |
| 500 | Database error |
GET /api/pricing/cost
GET /api/pricing/cost/:sessionIdThe response contains total_cost, breakdown, daily_costs, feature surcharges, and
unpriced_models. Each unpriced entry includes provider (claude, cursor, or codex) so a
client can link the missing rate to the correct Settings editor; its tokens contribute $0 until a
matching rule exists.
GET /api/workflows?status=active&sources=local&providers=codexReturns the 11 workflow datasets used by the Workflows page. status, sources, and providers compose to scope every aggregate. For Codex, tool flow and the per-session timeline come from persisted response_item calls, while compaction counts come from context_compacted rollout events; the API never invents Claude-style subagents or Workflow-tool runs for Codex.
GET /api/workflows/session/:id?sources=local&providers=codexReturns the scoped session row, agent tree, recorded tool timeline, swim lanes, and chronological events. It returns 404 when the session is absent or falls outside the requested provider/source scope.
GET /api/sessions/:id/notificationsReturns notifications for a session.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id |
string | Session ID |
Example Request:
curl http://localhost:4820/api/sessions/sess_abc123/notificationsExample Response:
{
"notifications": [
{
"id": 1,
"session_id": "sess_abc123",
"notification_type": "backgroundTaskComplete",
"message": "Explore agent completed",
"created_at": "2024-03-18T12:05:00Z"
}
]
}The /api/webhooks/* namespace manages alert-delivery targets and their audit log.
GET /api/webhooks/providers
GET /api/webhooks
POST /api/webhooks
PATCH /api/webhooks/:id
DELETE /api/webhooks/:id
POST /api/webhooks/:id/test
GET /api/webhooks/:id/deliveriesHosted provider URLs require HTTPS. The generic and n8n types may use HTTP for local or self-hosted receivers. Delivery rejects redirects, so provider credentials, custom headers, and HMAC signatures are never forwarded to a second destination. List and mutation responses mask URLs and redact secrets.
The /api/remote-sources/* namespace configures remote SSH machines the dashboard pulls Claude Code, Codex, or both histories from, so one dashboard can consolidate sessions from several machines. Each provider is mirrored and imported independently; a source succeeds when either provider is present. Codex additionally mirrors its lightweight session_index.jsonl so native renamed titles survive import. No secrets are stored — SSH authentication defers entirely to the host's SSH stack (ssh-agent, ~/.ssh/config, key files). Every imported session is tagged with the source's id in the sessions.source column (the built-in local history uses the id local), which powers the sources filter below.
RemoteSource shape:
{
"id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11",
"label": "Work laptop",
"host": "son@studio.local",
"ssh_port": 22,
"identity_file": "~/.ssh/id_ed25519",
"remote_home": "~/.claude",
"remote_codex_home": "~/.codex",
"enabled": true,
"status": "ok",
"claude_status": "ok",
"codex_status": "ok",
"last_error": null,
"last_sync_at": "2026-07-22T18:41:55.117Z",
"last_sync_counts": {
"imported": 9,
"skipped": 41,
"backfilled": 0,
"errors": 0,
"sessions_seen": 50,
"sessions_tagged": 50,
"providers": {
"claude": { "status": "ok", "sessions_tagged": 32 },
"codex": { "status": "ok", "sessions_tagged": 18 }
}
},
"created_at": "2026-07-20T09:15:00.000Z",
"updated_at": "2026-07-22T18:41:55.117Z"
}ssh_port, identity_file, remote_home, remote_codex_home, claude_status, codex_status, last_error, last_sync_at, and last_sync_counts are nullable. remote_home and remote_codex_home are the optional Remote Claude home and Remote Codex home overrides; send null on PATCH to return either provider to its default remote home. status is one of idle, syncing, ok, error; provider statuses additionally use unavailable when that CLI's history directory is absent.
During syncing, last_error (and the WebSocket error field) retains the most recent failure, so automatic retries do not hide the diagnostic. A completed failure replaces it; a successful sync clears it. Last successful import counts and timestamp remain unchanged on failure.
GET /api/remote-sourcesReturns all configured remote sources. Response: { "sources": RemoteSource[] }.
POST /api/remote-sourcesRequest Body:
| Field | Type | Required | Description |
|---|---|---|---|
label |
string | Yes | Human-readable name |
host |
string | Yes | SSH destination (user@host) or a ~/.ssh/config alias |
ssh_port |
integer | No | SSH port (defers to SSH default / config when omitted) |
identity_file |
string | No | Private-key path passed to ssh (-i) |
remote_home |
string | No | Remote Claude home (defaults to remote ~/.claude) |
remote_codex_home |
string | No | Remote Codex home (defaults to remote ~/.codex) |
enabled |
boolean | No | Whether the source is eligible for syncs (default true) |
Cursor boundary: Remote SSH sources currently mirror Claude Code and Codex homes only. Local Cursor history is discovered independently from
DASHBOARD_CURSOR_HOME(default~/.cursor); a remote Cursor home must be mounted or otherwise exposed locally before CCAM can ingest it.
Returns { "source": RemoteSource } with HTTP 201.
Error Responses (400): { "error": { "code", "message" } } with one of:
| Code | Meaning |
|---|---|
INVALID_LABEL |
Missing/blank label |
INVALID_HOST |
Missing/invalid host |
INVALID_PORT |
ssh_port out of range |
INVALID_IDENTITY_FILE |
Invalid identity_file value |
INVALID_REMOTE_HOME |
Invalid remote_home or remote_codex_home value |
PATCH /api/remote-sources/:idPartial update — only the keys present in the body change. Same fields (and the same validation codes) as create; both label and host are optional here. Returns { "source": RemoteSource }, or 404 if the id is unknown.
DELETE /api/remote-sources/:idQuery Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
purge |
boolean | false |
When true, also delete this source's imported sessions. When omitted/false, those sessions are detached — reassigned to the local source so history is preserved |
Returns { "ok": true, "purged": <bool> } (purged is true only when ?purge=true deleted the sessions). 404 if the id is unknown.
POST /api/remote-sources/:id/testRuns an SSH connectivity probe. Returns { "ok", "message", "remoteProjects", "remoteCodexSessions", "providers" }; providers.claude and providers.codex each report the checked path, message, and ok / unavailable / error status. A source passes when either provider is available. Does not import anything. 404 if the id is unknown.
POST /api/remote-sources/:id/syncPulls Claude Code and Codex history from the remote over SSH now, through the same provider-specific idempotent import pipelines used locally. The Codex stage includes the native title index when available; each imported session is tagged with this source's id. A source succeeds when either provider is available and returns provider-specific counters. Progress/completion is also broadcast over the WebSocket as remote_source.status frames.
Example Response:
{
"ok": true,
"imported": 9,
"skipped": 41,
"backfilled": 0,
"errors": 0,
"sessions_seen": 50,
"sessions_tagged": 50,
"providers": {
"claude": { "status": "ok", "imported": 6, "sessions_tagged": 31 },
"codex": { "status": "ok", "imported": 3, "sessions_tagged": 19 }
}
}404 if the id is unknown; 500 with { error: { code: "SYNC_FAILED", message } } on SSH/import failure.
POST /api/remote-sources/sync-allPulls history from every enabled source sequentially (one SSH connection at a time). Per-source failures are isolated — one unreachable machine never aborts the others — and each outcome is returned in results. Always 200.
Example Response:
{ "ok": true, "synced": 2, "results": [{ "id": "src_a", "ok": true }, { "id": "src_b", "ok": false, "error": "ssh exited with code 255" }] }GET /api/sessions, /api/events, /api/agents, /api/stats, and /api/analytics accept an optional sources query parameter: a comma-separated list of source ids to include (omit for all). GET /api/sessions/facets correspondingly returns a sources: string[] array (alongside cwds) listing the distinct sessions.source values so the UI can build the filter dropdown.
curl "http://localhost:4820/api/sessions?sources=local,4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11"POST /api/hooks/ingest-batch and POST /api/hooks/ingest-transcript form the
third session-data ingestion path, alongside local hooks and the SSH pull of
Remote Data Sources. They exist for a machine the
dashboard can never reach to pull from — a roaming laptop behind NAT or a
CGNAT'd home connection — which pushes session metadata and transcript JSONL
instead.
Unlike the local hook routes, these endpoints are meant to be reachable from the public internet behind a reverse proxy such as Traefik. They are disabled by default and gated by their own token:
REMOTE_PUSH_TOKEN= # or REMOTE_PUSH_TOKEN_FILE=/path/to/token
That token is deliberately not DASHBOARD_HOOK_TOKEN — that one protects the
loopback-only hook routes, and an operator who sets it to harden those must not
thereby also open an internet-writable endpoint as a side effect.
| Condition | Response |
|---|---|
REMOTE_PUSH_TOKEN unset |
503 REMOTE_PUSH_NOT_CONFIGURED |
| Token missing or mismatched | 401 EUNAUTHORIZED |
tokens + tool_events + turns over 1000 |
413 BATCH_TOO_LARGE |
Send the token as Authorization: Bearer <token> or X-Dashboard-Token: <token>.
?token= is deliberately rejected here, unlike the dashboard/WebSocket token,
because a query-string credential on a public-internet route ends up in access
and proxy logs. ingest-transcript verifies this header before reading its larger
8 MiB JSON body, so unauthenticated requests never reach that parser.
Request Body:
{
"schema_version": 1,
"session_id": "abc-123",
"provider": "claude",
"session_name": "optional display name (defaults to Session <first 8 chars of id>)",
"cwd": "optional working directory",
"repo_remote_url": "optional opaque Git remote URL",
"model": "optional model id",
"tokens": [
{
"model": "claude-opus-4",
"speed": "1x",
"inference_geo": "us",
"service_tier": "standard",
"input": 100,
"output": 50,
"cacheRead": 0,
"cacheWrite": 0,
"cacheWrite1h": 0,
"webSearch": 0,
"webFetch": 0,
"codeExec": 0
}
],
"tool_events": [
{ "uuid": "evt-1", "agent_id": "optional, defaults to this session's main agent", "tool_name": "Bash", "status": "success", "timestamp": "optional ISO-8601, defaults to server now" }
],
"turns": [
{ "uuid": "turn-1", "agent_id": "optional", "duration_ms": 1500, "timestamp": "optional ISO-8601" }
]
}| Field | Type | Required | Description |
|---|---|---|---|
schema_version |
integer | Yes | Payload version; currently 1 |
session_id |
string | Yes | Identity of the pushed session |
provider |
string | Yes | claude or codex |
session_name |
string | No | Display name; defaults to Session <id8> |
cwd |
string | No | Working directory on the pushing machine |
repo_remote_url |
string | No | Optional collector Git remote; URL/SCP userinfo, query strings, and fragments are removed, malformed URL-style values are discarded, and the first non-empty sanitized value wins |
model |
string | No | Model id for the session |
tokens |
array | No | Each entry is that bucket's full current total (like a transcript re-parse), not a delta |
tool_events |
array | No | Tool calls, stored as RemoteToolEvent events |
turns |
array | No | Turn durations, stored as RemoteTurn events |
tool_events[] and turns[] are deduped by (session_id, event_type, uuid)
both against previously-committed rows and within the same batch, so resending a
batch is safe. A session_id already owned by a local or SSH-pulled session is
refused per item (SESSION_LOCALLY_OWNED) rather than allowed to hijack it — a
pushed session can only ever create a new session or append to one it created
itself.
Example Response (200, even when individual items were skipped or rejected —
check errors[] and skipped for partial-failure detail):
{ "ok": true, "written": 2, "skipped": 1, "errors": [{ "item": "tokens[0]", "code": "INVALID_NUMERIC", "message": "..." }] }WebSocket broadcasts for a batch are flushed after the transaction commits, never during it, so a client never sees an event that a rolled-back batch never persisted.
This companion endpoint appends Claude main or subagent JSONL in offset-checked
chunks. The session must first exist as source = 'remote_push', normally through
ingest-batch. An unregistered session returns 409 SESSION_NOT_REGISTERED, and
a locally or SSH-owned session returns 409 SESSION_LOCALLY_OWNED.
{
"provider": "claude",
"session_id": "abc-123",
"rel_path": "-home-user-project/abc-123.jsonl",
"offset": 0,
"content_b64": "eyJ0eXBlIjoidXNlciJ9Cg==",
"sync": true,
"cwd": "/home/user/project",
"session_name": "[laptop] project"
}rel_path accepts Claude's main transcript layout
<project>/<session_id>.jsonl, flat subagents under
<project>/<session_id>/subagents/, and workflow subagents under
.../subagents/workflows/<run_id>/. Existing path components are resolved
canonically against the projects root, dangling or escaping symlinks are
rejected, the final file is opened without following symlinks where supported,
and the containment check runs again immediately before append.
offset must equal the current stored byte size. A mismatch returns
409 OFFSET_MISMATCH with that size so the client can resume without duplicating
data. content_b64 must be canonical base64 and decode to at most 4 MiB. Each
stored file defaults to a 256 MiB ceiling, configurable with
REMOTE_TRANSCRIPT_MAX_FILE_MB; exceeding either limit returns 413.
Set sync: true on the last chunk of a pass to re-derive tokens, titles, prompt
previews, compactions, turn timings, API errors, and subagents once. This
metadata-only pass creates no RemoteSync feed event and restores the session's
original updated_at, so it does not reset inactivity alerts or reactivate a
terminal session.
| Method | Path | Description |
|---|---|---|
GET |
/api/settings/info |
Database, hook, server, process, and transcript-cache status |
GET |
/api/settings/export |
Download a versioned full-dashboard JSON bundle |
POST |
/api/settings/import |
Restore an export by multipart file or JSON { "path": "/absolute/file" }; idempotent and non-destructive |
POST |
/api/settings/install-hooks |
Install the selected claude and/or codex hook sets |
POST |
/api/settings/cleanup |
Abandon stale sessions and/or purge old terminal sessions; purged sessions' transcript snapshots are deleted too |
GET |
/api/settings/snapshots |
Transcript snapshot storage per provider and the retention policy |
POST |
/api/settings/snapshots/compress |
Losslessly compress snapshots whose original transcript is gone |
POST |
/api/settings/snapshots/prune |
Plan (dry run, default) or apply a snapshot prune |
POST |
/api/settings/clear-data |
Delete captured sessions, agents, events, token usage, fired alerts, and webhook delivery history |
GET / PUT |
/api/settings/claude-home |
Read or update the Claude Code transcript/configuration root |
GET / PUT |
/api/settings/codex-home |
Read or update the Codex rollout/hooks root; saving re-arms the live watcher and schedules an immediate session scan |
Both home updates accept { "path": "/absolute/path" } (a leading ~/ is expanded). The resolved path must exist and be a directory; invalid input returns 400 INVALID_PATH. Codex changes are persisted as DASHBOARD_CODEX_HOME and notify the background synchronizer after the response so a large history cannot delay the Settings action.
Claude Code, Codex, and Cursor delete their own transcripts after a TTL, so the
dashboard keeps durable copies under its data directory (transcripts/,
codex-transcripts/, cursor-transcripts/) and the Conversation endpoints serve
whichever of the live file and the snapshot is more complete.
GET /api/settings/snapshots (also embedded in /api/settings/info as
snapshots, cached for 5 min):
{
"total_bytes": 734003200,
"total_files": 1840,
"roots": {
"claude": { "path": "/Users/me/.claude/agent-dashboard/transcripts", "files": 1702, "bytes": 692060160, "transcript_files": 1702, "compressed_files": 1210, "compressed_bytes": 211812352, "database_files": 0, "database_bytes": 0, "compact_database_files": 0, "compression_supported": true, "sessions": 512 },
"codex": { "path": "/Users/me/.claude/agent-dashboard/codex-transcripts", "files": 96, "bytes": 31457280, "transcript_files": 96, "compressed_files": 0, "compressed_bytes": 0, "database_files": 0, "database_bytes": 0, "compact_database_files": 0, "compression_supported": false, "sessions": 96 },
"cursor": { "path": "/Users/me/.claude/agent-dashboard/cursor-transcripts", "files": 42, "bytes": 10485760, "transcript_files": 21, "compressed_files": 18, "compressed_bytes": 2097152, "database_files": 21, "database_bytes": 3145728, "compact_database_files": 21, "compression_supported": true, "sessions": 21 }
},
"policy": { "compress": true, "max_age_days": null, "max_bytes": null }
}POST /api/settings/snapshots/compress gzips every Claude/Cursor snapshot whose
original is gone and that has been idle for 24 h — the same lossless pass the
server runs every 6 h. Each archive is decompressed and matched (SHA-256 +
length) before the plain file is removed; a provider whose source tree is
missing or unreadable is reported in skipped_roots and left untouched.
compressed_files is therefore a share of transcript_files, not every file
in a provider root. Cursor database_files are compact current-root stores;
compact_database_files < database_files means a verified legacy migration is
still pending.
POST /api/settings/snapshots/prune takes at least one of max_age_days,
max_bytes (bytes or a size such as "5GB"), and orphans: true. It selects
whole finished sessions (never active ones; the size cap also spares sessions active in the last 24 h), oldest first, and is a dry
run unless the body also has "dry_run": false and
"confirm": "PRUNE_SNAPSHOTS"; anything else returns 400 INVALID_PRUNE_REQUEST. The response lists up to 500 candidates (kind,
session_id, reason: max_age / max_bytes / orphan, files, bytes,
last_activity) with candidate_bytes, remaining_bytes, over_cap_bytes, and
— when applied — removed_files, removed_bytes, and failed_files (locked
files left for a later pass). Cap removals are tombstoned so a re-import does
not recreate them.
# Preview, then apply, a 5 GB cap
curl -s -X POST localhost:4820/api/settings/snapshots/prune \
-H 'Content-Type: application/json' -d '{"max_bytes":"5GB"}'
curl -s -X POST localhost:4820/api/settings/snapshots/prune \
-H 'Content-Type: application/json' \
-d '{"max_bytes":"5GB","dry_run":false,"confirm":"PRUNE_SNAPSHOTS"}'POST /api/settings/import accepts one export file up to 25 MiB. Multipart
callers use field file; CLI/MCP callers may send an absolute server-side
path. The restore skips existing sessions as a whole and inserts independent
run, alert-rule, and pricing rows only when absent. It never overwrites existing
rows. Malformed JSON returns 400 INVALID_JSON, an invalid bundle returns
400 INVALID_FORMAT, and an oversized file returns 413 IMPORT_TOO_LARGE.
The /api/cc-config/* namespace powers the Claude Config Explorer page. Claude home resolves as CLAUDE_HOME || CLAUDE_CONFIG_DIR || ~/.claude; the separate global state file is $CLAUDE_CONFIG_DIR/.claude.json when that variable is set, otherwise ~/.claude.json. All read endpoints are pure file reads under the resolved Claude home and the project's .claude/ dir; requested files and allowed roots are canonicalized with realpath, so a symlink cannot escape those roots. Mutations are limited to low-risk text-file artifacts (skills, subagents, slash commands, output styles, memory) and always create a timestamped backup before writing. Plugins, MCP servers, hooks-in-settings, and live settings.json files stay read-only because they are written concurrently by the running Claude Code CLI.
GET /api/cc-config/overview
GET /api/cc-config/skills?scope=user|project|all
GET /api/cc-config/agents
GET /api/cc-config/commands
GET /api/cc-config/output-styles
GET /api/cc-config/plugins
GET /api/cc-config/marketplaces
GET /api/cc-config/mcp
GET /api/cc-config/hooks
GET /api/cc-config/hook-scripts
GET /api/cc-config/keybindings
PUT /api/cc-config/keybindings Body: { groups: [{ context, bindings: [{ key, action }] }] }
GET /api/cc-config/statusline
GET /api/cc-config/settings
GET /api/cc-config/memory
GET /api/cc-config/file?path=<absolute-path>
GET /api/cc-config/backups[?scope=&type=]
PUT /api/cc-config/file Body: { scope, type, name?, content }
DELETE /api/cc-config/file Body: { scope, type, name? }scope is "user", "project", or "auto-memory". type is one of skills, agents, commands, output-styles, memory, auto-memory. name is required for everything except memory (which is CLAUDE.md itself). On PUT, name is validated against ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ (for auto-memory it must instead be a flat *.md filename). Settings are returned with secret-like keys (matching /token|secret|password|api[_-]?key|auth/i) replaced by "<redacted>".
GET /api/cc-config/memory also surfaces the per-project file-based memory store — every *.md under ~/.claude/projects/<slug>/memory/ (the common pattern of a MEMORY.md index plus one file per remembered fact). Those items have scope: "auto-memory" and carry project (the projects/<slug> dir name), name (filename), isIndex (true for MEMORY.md / INDEX-*.md, which sort first), and parsed frontmatter. They are editable: PUT/DELETE /api/cc-config/file accept { scope: "auto-memory", type: "auto-memory", project, name, content? } and create a timestamped backup under <memory-dir>/.cc-config-backups/auto-memory/ before mutating (an invalid project slug returns EBADPROJECT). GET /api/cc-config/backups lists these with scope: "auto-memory" and project set. Bodies are also readable via GET /api/cc-config/file (they live under CLAUDE_HOME).
PUT /api/cc-config/keybindings edits ~/.claude/keybindings.json from a structured list of context groups ({ groups: [{ context, bindings: [{ key, action }] }] }). The server backs the file up first (under <CLAUDE_HOME>/cc-config-backups/keybindings/), preserves any top-level metadata ($schema/$docs), and replaces only the bindings array; duplicate contexts or duplicate keys within a context return EBADCONTENT. Unlike settings.json (which the live CLI rewrites mid-session and is therefore read-only here), keybindings.json is safe to edit from the dashboard.
Backup paths look like <root>/cc-config-backups/<type>/<base>.<ISO>.bak[.dir] — outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. The Backups modal in the UI auto-builds mv restore commands.
The Codex half of Agent Config discovers configuration defaults, account-visible model catalog entries, profiles, MCP servers, projects, skills, rules, hooks, installed plugins, and instruction files beneath the configured Codex home. The account model cache is read with a dedicated 4 MiB metadata cap rather than the 256 KiB preview cap, so large model instructions cannot make the Models tab falsely report zero models; base and profile model overrides are also included. Profiles are Codex-native top-level overlays named <name>.config.toml (letters, numbers, hyphens, and underscores only) and apply only when the CLI starts with codex --profile <name>; their cards expose that exact command with a one-click copy action. Normal inspection is redacted server-side for secret-like TOML or JSON values. Installed plugins come from codex plugin list, then use manifest metadata for names and descriptions—cache directories are never reported as plugins.
GET /api/codex-config/overview
GET /api/codex-config/file?path=<absolute-path-under-codex-home>
GET /api/codex-config/edit-file?path=<allowlisted-configuration-path>
PUT /api/codex-config/file
DELETE /api/codex-config/file
Content-Type: application/json
{ "path": "<allowlisted-configuration-path>", "content": "..." }
POST /api/codex-config/profiles
Content-Type: application/json
{ "name": "deep-review" }The normal file endpoint also accepts this repository's AGENTS.md, rejects every other path, canonicalizes the target before checking containment, and caps returned bodies at 256 KiB. The editor endpoint is stricter: only config.toml, named profile overlays, hooks.json, user *.rules, user skills/**/SKILL.md, and the Codex or current-project AGENTS.md are editable. Reads and writes reject symlinked path components beneath the trusted root, and writes also verify the canonical parent remains contained. The editor returns unredacted local text so a user can edit without turning secret placeholders into real file contents. POST /profiles creates a commented, non-overwriting profile template, then the UI opens it in that editor. The UI also exposes a one-click Copy path control for every managed artifact. DELETE /file is narrower still: it can back up then remove a named profile, hooks.json, a user rule, a whole user skill directory, or a Codex/project instruction file. config.toml is edit-only and always rejected for deletion. The dashboard does not validate TOML, JSON, hook, rule, skill, or instruction syntax. Every overwrite and allowed deletion receives a timestamped backup; writes are capped at 256 KiB and atomic. A write containing the preview marker [redacted] is rejected so a copied redacted preview cannot overwrite real secrets. codex_config_changed is emitted over WebSocket when relevant configuration, skill, rule, or plugin files change.
The Import History endpoints accept a provider of "claude" (default) or
"codex". Claude Code reads project transcripts; Codex reads rollout JSONL
through its live incremental ingestor, retaining token cursors, response-item
tools, lifecycle events, and an optional native title from session_index.jsonl.
External and browser-uploaded Codex files are copied into dashboard-owned
storage before temporary extraction directories are removed.
GET /api/import/guide?provider=codex
POST /api/import/rescan
Content-Type: application/json
{ "provider": "codex" }
POST /api/import/scan-path
Content-Type: application/json
{ "path": "/absolute/path/to/codex-history", "provider": "codex" }
POST /api/import/upload
Content-Type: multipart/form-data
files=@rollout-…jsonl&provider=codexEvery success response includes { ok, provider, source, imported, skipped, backfilled, errors }; path scans also return the resolved path and scan
counts. Provider-tagged import.progress WebSocket messages report live
start, scan, extract, parse, complete, and error phases. Invalid
providers return 400 INVALID_PROVIDER.
The /api/run/* namespace spawns and supervises Claude Code subprocesses and native interactive Codex app-server threads from the dashboard. Every route enforces a same-origin / loopback-Origin guard; browser requests must come from localhost, 127.0.0.1, ::1, or 0.0.0.0. CLI / curl requests with no Origin header pass through. When DASHBOARD_TOKEN is set, a valid token is also required here (like the rest of /api/* — see Authentication). A supplied cwd must be an existing absolute directory and is canonicalized with realpath. It intentionally may be outside the repository so Run Agent can operate from the user's home or any recent project.
GET /api/run List all handles + concurrency state
GET /api/run/binary?provider=… { found, path, provider } for `claude` or `codex`
GET /api/run/models?provider=… Dynamic provider model choices
GET /api/run/cwds Suggested cwds (dashboard, home, recent)
GET /api/run/files?cwd=&q= Fuzzy file search inside cwd for the @-file autocomplete
(skips node_modules, .git, dist, build, .next, .cache, coverage, vendor)
POST /api/run Spawn — Body: { provider?, prompt, mode?, cwd?, model?, permissionMode?, sandbox?, resumeSessionId?, effort? }
POST /api/run/:id/message Send follow-up turn — Body: { text, provider? }
GET /api/run/:id[?envelopes=1] Handle state; ?envelopes=1 includes the in-memory envelope log
DELETE /api/run/:id Stop (SIGTERM → SIGKILL after 5 s)provider defaults to "claude". Claude keeps "headless" (single-shot, prompt in argv via -p) and "conversation" modes, including resumeSessionId support. Codex always uses a real multi-turn app-server thread; its permissionMode is an approval policy ("untrusted", "on-request", or "never") and its sandbox is "read-only", "workspace-write", or "danger-full-access". Codex's model list is retrieved from the signed-in local app server, while Claude returns its supported aliases plus locally observed models because the Claude CLI has no model-list command. run_stream carries parsed Claude stream-json envelopes or normalized Codex app-server events; run_status and run_input_ack cover both providers. Concurrency is effectively uncapped (default ceiling 10000, override with RUN_MAX_CONCURRENT) — the ceiling exists only to prevent fork-bomb footguns from a buggy client.
Spawned claude processes fire the dashboard's hooks like any other CLI session, so they show up in /api/sessions, the analytics, the Kanban board, and the Workflows page automatically — the Run page itself just owns the live streaming UX.
const ws = new WebSocket('ws://localhost:4820/ws');
ws.onopen = () => {
console.log('Connected to Agent Dashboard');
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
console.log('Received:', message);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};
ws.onclose = () => {
console.log('Disconnected');
};When DASHBOARD_TOKEN is configured, pass the token as ?token=<token> on the /ws upgrade (an x-dashboard-token header also works):
const ws = new WebSocket('ws://localhost:4820/ws?token=YOUR_DASHBOARD_TOKEN');stateDiagram-v2
[*] --> Connecting: new WebSocket()
Connecting --> Connected: onopen
Connecting --> Disconnected: onerror
Connected --> Connected: onmessage
Connected --> Disconnected: onclose
Connected --> Disconnected: onerror
Disconnected --> Connecting: Reconnect
Disconnected --> [*]
note right of Connected
Heartbeat: ping every 30s
Broadcast: Real-time events
end note
Server broadcasts JSON messages to all connected clients:
Sent when a new session is created.
{
"type": "session.created",
"data": {
"id": 1,
"session_id": "sess_abc123",
"model": "claude-sonnet-4",
"status": "active",
"total_cost": 0,
"created_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T12:00:00Z"
}
}Sent when session data changes (status, cost, etc.).
{
"type": "session.updated",
"data": {
"id": 1,
"session_id": "sess_abc123",
"model": "claude-sonnet-4",
"status": "completed",
"total_cost": 1.23,
"created_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T14:30:00Z"
}
}Sent when a new agent starts.
{
"type": "agent.created",
"data": {
"id": 1,
"agent_id": "agent_xyz789",
"session_id": "sess_abc123",
"agent_type": "explore",
"status": "running",
"current_tool": null,
"input_tokens": 0,
"output_tokens": 0,
"cost": 0,
"created_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T12:00:00Z"
}
}Sent when agent data changes (tokens, status, current_tool).
{
"type": "agent.updated",
"data": {
"id": 1,
"agent_id": "agent_xyz789",
"session_id": "sess_abc123",
"agent_type": "explore",
"status": "completed",
"current_tool": null,
"input_tokens": 1500,
"output_tokens": 800,
"cost": 0.45,
"created_at": "2024-03-18T12:00:00Z",
"updated_at": "2024-03-18T12:05:00Z"
}
}Sent when a tool execution completes.
{
"type": "tool.executed",
"data": {
"id": 1,
"agent_id": "agent_xyz789",
"tool_name": "bash",
"duration_ms": 1234,
"success": 1,
"error_message": null,
"created_at": "2024-03-18T12:01:00Z"
}
}Sent when a notification is created.
{
"type": "notification.received",
"data": {
"id": 1,
"session_id": "sess_abc123",
"notification_type": "backgroundTaskComplete",
"message": "Explore agent completed",
"created_at": "2024-03-18T12:05:00Z"
}
}Broadcast by routes/run.js and lib/run-spawner.js for /run page subprocesses. run_stream.data.envelope is a parsed stream-json envelope; the spawner runs claude with --include-partial-messages so this includes stream_event deltas (message_start, content_block_delta text/thinking deltas, message_stop, etc.) for character-level streaming.
{ "type": "run_stream", "data": { "id": "<run-id>", "envelope": { "type": "stream_event", "event": { "type": "content_block_delta", "index": 0, "delta": { "type": "text_delta", "text": "Hello" } } } } }
{ "type": "run_status", "data": { "id": "<run-id>", "status": "running", "at": 1700000000000 } }
{ "type": "run_input_ack", "data": { "id": "<run-id>", "messageId": "<uuid>", "at": 1700000000000 } }Broadcast whenever Claude Code configuration changes — either by dashboard mutations on PUT/DELETE /api/cc-config/file (source: "dashboard") or by lib/cc-watcher.js picking up external fs.watch events on ~/.claude/ and ~/.claude.json (source: "fs", debounced at 500 ms). The Config Explorer page subscribes and refetches automatically.
{ "type": "cc_config_changed", "data": { "source": "dashboard", "action": "write", "scope": "user", "type": "skill", "name": "my-skill" } }
{ "type": "cc_config_changed", "data": { "source": "fs", "paths": ["/Users/foo/.claude/settings.json"] } }Broadcast once per successful remote sync (background poller, manual Sync now, or immediate pull after add/re-enable). providers preserves separate Claude/Codex results, so clients can show an unavailable provider without hiding successfully refreshed sibling data. Clients use this — and the per-session session_created / session_updated frames emitted in the same pass — to refetch sessions, costs, and analytics without polling.
{
"type": "remote_data.updated",
"data": {
"sourceId": "src_a1b2c3",
"source": "src_a1b2c3",
"label": "dev-box",
"counters": {
"imported": 1,
"skipped": 0,
"sessions_tagged": 3,
"providers": { "claude": { "status": "unavailable" }, "codex": { "status": "ok", "sessions_tagged": 3 } }
},
"providers": { "claude": "unavailable", "codex": "ok" },
"last_sync_at": "2026-07-26T21:15:00.000Z"
}
}Broadcast when a remote data source changes sync state (during/after POST /api/remote-sources/:id/sync) or is deleted. status is one of idle, syncing, ok, error, or deleted; when present, providers gives the independent Claude/Codex state (idle, syncing, ok, unavailable, or error). error and last_sync_at are optional and present when relevant. See Remote Data Sources.
{ "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "syncing" } }
{ "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "ok", "providers": { "claude": "unavailable", "codex": "ok" }, "last_sync_at": "2026-07-22T18:41:55.117Z" } }
{ "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "error", "error": "ssh exited with code 255" } }
{ "type": "remote_source.status", "data": { "id": "4d1f0e2a-7b9c-4c33-8a21-9e0f7b6d4c11", "status": "deleted" } }sequenceDiagram
participant Hook as Hook Handler
participant Server as Express Server
participant DB as SQLite
participant WS as WebSocket Server
participant Client1 as Client 1
participant Client2 as Client 2
Hook->>Server: POST /hooks/post-tool-use
Server->>DB: Create tool_execution
DB-->>Server: Inserted row
Server->>WS: broadcast({ type: 'tool.executed', data })
par Broadcast to all clients
WS->>Client1: { type: 'tool.executed', ... }
WS->>Client2: { type: 'tool.executed', ... }
end
Server-->>Hook: 200 OK
All error responses follow this structure:
{
"error": "Human-readable error message",
"code": "ERROR_CODE",
"details": {
"field": "Additional context"
}
}| Code | Meaning | Example |
|---|---|---|
| 200 | Success | Resource retrieved |
| 201 | Created | Resource created |
| 400 | Bad Request | Invalid JSON, missing fields |
| 404 | Not Found | Session/agent not found |
| 409 | Conflict | Duplicate pattern |
| 500 | Server Error | Database error |
400 Bad Request:
{
"error": "Missing required field: pattern",
"code": "VALIDATION_ERROR",
"details": {
"field": "pattern",
"message": "Pattern is required"
}
}404 Not Found:
{
"error": "Session not found",
"code": "NOT_FOUND",
"details": {
"session_id": "sess_invalid"
}
}409 Conflict:
{
"error": "Pricing rule already exists",
"code": "DUPLICATE_PATTERN",
"details": {
"pattern": "claude-sonnet-4"
}
}Currently, no rate limiting is enforced. For production deployments, implement rate limiting:
// Using express-rate-limit
import rateLimit from 'express-rate-limit';
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100, // Limit each IP to 100 requests per windowMs
message: 'Too many requests, please try again later.'
});
app.use('/api/', limiter);For endpoints returning lists, use limit and offset:
GET /api/sessions?limit=20&offset=40Pagination Pattern:
graph LR
Page1[Page 1<br/>offset=0<br/>limit=20] --> Page2[Page 2<br/>offset=20<br/>limit=20]
Page2 --> Page3[Page 3<br/>offset=40<br/>limit=20]
Page3 --> PageN[Page N<br/>offset=N*20<br/>limit=20]
style Page1 fill:#3B82F6
Response includes pagination metadata:
{
"sessions": [...],
"total": 156,
"limit": 20,
"offset": 40,
"has_more": true
}// 1. List sessions
const sessions = await fetch('http://localhost:4820/api/sessions');
const { sessions: sessionList } = await sessions.json();
// 2. Get specific session
const sessionId = sessionList[0].session_id;
const session = await fetch(`http://localhost:4820/api/sessions/${sessionId}`);
const sessionData = await session.json();
// 3. Get session agents
const agents = await fetch(`http://localhost:4820/api/sessions/${sessionId}/agents`);
const { agents: agentList } = await agents.json();
// 4. Get agent tools
const agentId = agentList[0].agent_id;
const tools = await fetch(`http://localhost:4820/api/agents/${agentId}/tools`);
const { tools: toolList } = await tools.json();
console.log('Session:', sessionData);
console.log('Agents:', agentList);
console.log('Tools:', toolList);// Connect to WebSocket
const ws = new WebSocket('ws://localhost:4820/ws');
ws.onopen = () => {
console.log('Connected to real-time stream');
};
ws.onmessage = (event) => {
const message = JSON.parse(event.data);
switch (message.type) {
case 'session.created':
console.log('New session:', message.data.session_id);
break;
case 'agent.updated':
console.log('Agent updated:', message.data.agent_id);
console.log('Cost:', message.data.cost);
break;
case 'tool.executed':
console.log('Tool executed:', message.data.tool_name);
console.log('Duration:', message.data.duration_ms, 'ms');
break;
}
};// Create custom rule
const response = await fetch('http://localhost:4820/api/pricing', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
pattern: 'my-custom-model',
input_cost_per_1m: 5.0,
output_cost_per_1m: 20.0
})
});
const { rule } = await response.json();
console.log('Created rule:', rule);
// List all rules
const rules = await fetch('http://localhost:4820/api/pricing');
const { rules: ruleList } = await rules.json();
console.log('All rules:', ruleList);
// Delete rule
await fetch('http://localhost:4820/api/pricing/my-custom-model', {
method: 'DELETE'
});Successful POST /api/remote-sources/:id/sync responses and successful entries in POST /api/remote-sources/sync-all include sessions_excluded (unique conflicting native IDs), subagent_files_excluded, and excluded_ids (at most 50 IDs), alongside the existing import counters. Successful provider-specific results carry the same counters; skipped, unavailable, and failed results report their status/reason or error instead. Sessions belonging to another source or provider are excluded from snapshots, events, tokens, and source tagging; a copied local session remains local and cannot be purged through the remote source. Ownership is checked again when writing after asynchronous transcript or workflow parsing. The local periodic Claude sweep also rechecks after its synchronous import before snapshotting or publishing a change. Failed Claude session transactions do not publish snapshots or workflow journals. Codex imports reject conflicting filename, metadata or cursor identities before ingesting; metadata-free legacy transcripts retain their filename identity fallback. Local Claude directory imports also exclude other providers before publishing snapshots or workflows. New remote rows record source and metadata.origin_host atomically. The collector-v2 origin mark hashes the configured SSH destination, port, identity-file path and both provider history roots. After source deletion without purge, only an exact mark permits re-adoption. Legacy host-only marks are retained but do not authorize re-adoption; an existing registered owner can refresh its mark during a normal import. Cached rows with missing or empty metadata receive an object containing the mark during tagging. Nonempty malformed or nonobject metadata is preserved and cannot authorize local history imports. The sessions metadata PATCH replaces metadata; explicit replacement can remove a provenance mark, so this guarantee applies to normal import and source deletion flows. Destination case and an unspecified port are preserved because SSH usernames are case-sensitive and SSH configuration can supply a port. This identifies the configured collector, not key contents, resolved SSH configuration or the machine where a copied session originally ran. Existing timer and SSH transport behavior are unchanged.
The Agent Dashboard API provides:
- ✅ RESTful endpoints for querying sessions, agents, tools, pricing
- ✅ WebSocket streaming for real-time updates
- ✅ Type-safe responses with consistent JSON structure
- ✅ Error handling with descriptive error codes
- ✅ Pagination for large datasets
- ✅ Pricing management with custom rule support
For interactive API exploration with live request/response examples, see the built-in Swagger UI at /api/docs and ReDoc at /api/redoc. For MCP integration, see MCP.md.