Add new pages: output modes, workspaces (multi-instance), app connectivity. Update 16 existing pages to reflect: tunnel auto-start/keepalive, JWT auth system, SSE streaming, session config options, one-liner install, startup UX, lazy session resume, new CLI commands (attach, remote), and new chat commands (/mode, /model, /thought, /dangerous). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
15 KiB
REST API
The OpenACP daemon exposes a local HTTP API used by the CLI and the web dashboard.
Base URL: http://127.0.0.1:21420 (configurable via api.host and api.port)
Auth: Two-tier authentication:
- Secret token — from
~/.openacp/api-secret(full admin access) - JWT access token — scoped, revokable tokens issued by the auth system
# Using secret token
TOKEN=$(cat ~/.openacp/api-secret)
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/sessions
# Using JWT token
curl -H "Authorization: Bearer $JWT" http://localhost:21420/api/sessions
The secret file is created automatically with mode 0600 on first start. Protect it like an SSH private key.
Exempt from auth: GET /api/health, GET /api/version.
Body size limit: 1 MB.
API documentation: Swagger UI is available at /docs when the server is running.
Health & System
GET /api/health
Returns daemon health. No auth required.
Response
{
"status": "ok",
"uptime": 123456,
"version": "0.6.7",
"memory": {
"rss": 52428800,
"heapUsed": 30000000,
"heapTotal": 45000000
},
"sessions": {
"active": 2,
"total": 5
},
"adapters": ["telegram"],
"tunnel": { "enabled": true, "url": "https://abc.trycloudflare.com" }
}
uptime is milliseconds since daemon start. sessions.active counts sessions with status active or initializing.
curl http://localhost:21420/api/health
GET /api/version
Returns daemon version string. No auth required.
Response
{ "version": "0.6.7" }
curl http://localhost:21420/api/version
POST /api/restart
Sends a restart signal to the daemon. The daemon exits cleanly and the process manager (or openacp start) restarts it.
Response
{ "ok": true, "message": "Restarting..." }
Returns 501 if restart is not available in the current run mode.
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/restart
GET /api/adapters
Lists registered channel adapters.
Response
{
"adapters": [
{ "name": "telegram", "type": "built-in" }
]
}
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/adapters
Sessions
GET /api/sessions
Lists all sessions (active, finished, cancelled, error).
Response
{
"sessions": [
{
"id": "sess_abc123",
"agent": "claude",
"status": "active",
"name": "Fix login bug",
"workspace": "/home/user/myproject",
"createdAt": "2026-03-25T10:00:00.000Z",
"bypassPermissions": false,
"queueDepth": 0,
"promptRunning": true,
"lastActiveAt": "2026-03-25T10:05:00.000Z"
}
]
}
Session status values: initializing, active, finished, cancelled, error.
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/sessions
GET /api/sessions/:id
Returns details for a single session.
Response
{
"session": {
"id": "sess_abc123",
"agent": "claude",
"status": "active",
"name": "Fix login bug",
"workspace": "/home/user/myproject",
"createdAt": "2026-03-25T10:00:00.000Z",
"bypassPermissions": false,
"queueDepth": 1,
"promptRunning": false,
"threadId": "12345",
"channelId": "telegram",
"agentSessionId": "agent-internal-id"
}
}
Returns 404 if not found.
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/sessions/sess_abc123
POST /api/sessions
Creates a new session.
Request body (all fields optional)
{
"agent": "claude",
"workspace": "/path/to/project"
}
agent defaults to defaultAgent from config. workspace defaults to workspace.baseDir.
Response
{
"sessionId": "sess_abc123",
"agent": "claude",
"status": "initializing",
"workspace": "/home/user/openacp-workspace"
}
Returns 429 if maxConcurrentSessions is reached.
Permissions are auto-approved for sessions created via the API when no channel adapter is attached.
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent":"claude","workspace":"/path/to/project"}' \
http://localhost:21420/api/sessions
DELETE /api/sessions/:id
Cancels a session.
Response
{ "ok": true }
Returns 404 if not found.
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:21420/api/sessions/sess_abc123
POST /api/sessions/:id/prompt
Enqueues a prompt for a session. The session processes prompts serially; queueDepth indicates how many are waiting.
Request body
{ "prompt": "Refactor the authentication module" }
Response
{ "ok": true, "sessionId": "sess_abc123", "queueDepth": 1 }
Returns 400 if the session is cancelled, finished, or error. Returns 404 if not found.
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt":"Fix the login bug"}' \
http://localhost:21420/api/sessions/sess_abc123/prompt
PATCH /api/sessions/:id/bypass
Enables or disables bypass permissions for a session.
Request body
{ "enabled": true }
Response
{ "ok": true, "bypassPermissions": true }
curl -X PATCH \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled":true}' \
http://localhost:21420/api/sessions/sess_abc123/bypass
POST /api/sessions/:id/permission
Resolves a pending permission request for a session.
Request body
{ "permissionId": "perm_xyz", "optionId": "allow" }
Response
{ "ok": true }
Returns 400 if there is no matching pending request.
POST /api/sessions/:id/summary
Requests the agent to generate a summary name for the session.
Response
{ "ok": true, "name": "Refactor auth module" }
POST /api/sessions/:id/archive
Archives a session.
Response
{ "ok": true }
POST /api/sessions/adopt
Adopts an existing external agent session and surfaces it as a messaging thread.
Request body
{
"agent": "claude",
"agentSessionId": "external-session-id",
"cwd": "/path/to/project",
"channel": "telegram"
}
agent and agentSessionId are required. cwd defaults to the daemon's working directory. channel defaults to the first registered adapter.
Response
{ "ok": true, "sessionId": "sess_abc123", "threadId": "12345", "status": "new" }
status is "existing" if the session was already active (topic is pinged instead of created). Returns 429 on session limit, 400 for unsupported agent.
Agents
GET /api/agents
Lists agents configured in the daemon.
Response
{
"agents": [
{
"name": "claude",
"command": "claude-agent-acp",
"args": [],
"capabilities": { "integration": "claude" }
}
],
"default": "claude"
}
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/agents
Configuration
GET /api/config
Returns the full runtime config. Sensitive fields (botToken, token, apiKey, secret, password, webhookSecret) are redacted to "***".
Response
{ "config": { "defaultAgent": "claude", "channels": { ... }, ... } }
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/config
PATCH /api/config
Updates a single config value by dot-notation path. Only fields marked as safe in the config registry can be modified via the API.
Request body
{ "path": "security.maxConcurrentSessions", "value": 10 }
value can be any JSON type. String values that parse as JSON are used as-is.
Response
{
"ok": true,
"needsRestart": false,
"config": { ... }
}
needsRestart: true means the change requires a daemon restart to take effect. Returns 403 for fields not in the safe-fields scope.
curl -X PATCH \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"path":"security.maxConcurrentSessions","value":10}' \
http://localhost:21420/api/config
GET /api/config/editable
Returns metadata about editable config fields (used by the web dashboard). Includes path, displayName, group, type, options, value, and hotReload.
Topics
Topics represent channel adapter threads (Telegram forum topics, Discord threads, etc.).
GET /api/topics
Lists all topics. Optionally filter by status.
Query params
| Param | Description |
|---|---|
status |
Comma-separated status filter, e.g. active,finished |
Response
{
"topics": [
{
"sessionId": "sess_abc123",
"topicId": 42,
"name": "Fix login bug",
"status": "active",
"agentName": "claude",
"lastActiveAt": "2026-03-25T10:05:00.000Z"
}
]
}
Returns 501 if topic management is not available (no adapter with topic support).
curl -H "Authorization: Bearer $TOKEN" \
"http://localhost:21420/api/topics?status=active,finished"
DELETE /api/topics/:sessionId
Deletes the topic for a session. Returns 409 if the session is active and --force is not set. Returns 403 for system topics.
Query params
| Param | Description |
|---|---|
force |
Set to true to delete even if the session is active |
Response
{ "ok": true, "topicId": 42 }
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
"http://localhost:21420/api/topics/sess_abc123?force=true"
POST /api/topics/cleanup
Deletes all topics matching the given statuses. Returns counts of deleted and failed topics.
Request body (optional)
{ "statuses": ["finished", "error"] }
Response
{ "deleted": ["sess_abc123", "sess_def456"], "failed": [] }
Tunnel
GET /api/tunnel
Returns tunnel status for the primary tunnel service.
Response (when enabled)
{ "enabled": true, "url": "https://abc.trycloudflare.com", "provider": "cloudflare" }
Response (when disabled)
{ "enabled": false }
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/tunnel
GET /api/tunnel/list
Lists all active user tunnels.
Response
[
{ "port": 3000, "label": "dev server", "status": "active", "publicUrl": "https://xyz.trycloudflare.com" }
]
POST /api/tunnel
Creates a new tunnel to a local port.
Request body
{ "port": 3000, "label": "dev server", "sessionId": "sess_abc123" }
port is required. label and sessionId are optional.
Response
{ "port": 3000, "publicUrl": "https://xyz.trycloudflare.com", "label": "dev server", "status": "active" }
Returns 400 if the tunnel service is not enabled.
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"port":3000,"label":"dev server"}' \
http://localhost:21420/api/tunnel
DELETE /api/tunnel/:port
Stops the tunnel for a specific local port.
Response
{ "ok": true }
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:21420/api/tunnel/3000
DELETE /api/tunnel
Stops all user tunnels.
Response
{ "ok": true, "stopped": 3 }
Notifications
POST /api/notify
Sends a notification message to all registered channel adapters (e.g. to the Notifications topic in Telegram).
Request body
{ "message": "Deployment complete" }
Response
{ "ok": true }
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Deployment complete"}' \
http://localhost:21420/api/notify
Session Config
GET /api/sessions/:id/config
Returns the agent-declared config options for a session (modes, models, toggles).
Response
{
"configOptions": [
{
"id": "mode",
"name": "Mode",
"type": "select",
"category": "general",
"currentValue": "code",
"options": [
{ "value": "code", "label": "Code" },
{ "value": "architect", "label": "Architect" }
]
}
]
}
PUT /api/sessions/:id/config/:configId
Updates a config option value for a session.
Request body
{ "value": "architect" }
Response
{ "ok": true, "configId": "mode", "value": "architect" }
Authentication
POST /api/v1/auth/tokens
Creates a new JWT access token. Requires secret token authentication.
Request body
{ "name": "my-app", "role": "operator" }
Response
{
"token": "eyJhbG...",
"id": "tok_abc123",
"name": "my-app",
"role": "operator",
"expiresAt": "2026-04-08T10:00:00.000Z"
}
GET /api/v1/auth/tokens
Lists all active tokens (secret token auth required).
Response
{
"tokens": [
{
"id": "tok_abc123",
"name": "my-app",
"role": "operator",
"createdAt": "2026-04-01T10:00:00.000Z",
"lastUsedAt": "2026-04-01T12:00:00.000Z"
}
]
}
DELETE /api/v1/auth/tokens/:id
Revokes a token by ID. Requires secret token authentication.
Response
{ "ok": true }
GET /api/v1/auth/me
Returns information about the current token (works with both secret and JWT).
Response
{
"type": "jwt",
"role": "operator",
"scopes": ["sessions:read", "sessions:write", "agents:read"],
"tokenId": "tok_abc123"
}
POST /api/v1/auth/codes
Generates a one-time access code (for app connectivity). Requires secret token auth.
Response
{
"code": "abc123def456",
"expiresAt": "2026-04-01T10:30:00.000Z"
}
The code is valid for 30 minutes and can be used exactly once.
POST /api/v1/auth/exchange
Exchanges a one-time code for a JWT token. No prior authentication required.
Request body
{ "code": "abc123def456" }
Response
{
"token": "eyJhbG...",
"role": "operator",
"expiresAt": "2026-04-08T10:00:00.000Z"
}
Returns 401 if the code is expired or already used.
Server-Sent Events
GET /api/events
SSE stream of real-time daemon events. Auth via query parameter (EventSource cannot set headers).
GET /api/events?token=<api-secret>
Returns a persistent SSE connection. Events include session lifecycle changes, agent output, and health pings (every 30 seconds).
GET /api/v1/sse/sessions/:id/stream
Per-session SSE stream. Requires JWT authentication via query parameter.
GET /api/v1/sse/sessions/:id/stream?token=<jwt>
Streams only events for the specified session. Supports reconnect replay — if fewer than 100 events were missed, they are replayed on reconnection. Multiple clients can connect to the same session stream simultaneously.
Event types: agent:event, session:updated, permission:request, health.