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: Bearer token from ~/.openacp/api-secret

TOKEN=$(cat ~/.openacp/api-secret)
curl -H "Authorization: Bearer $TOKEN" 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, GET /api/events (SSE uses query param ?token=).

Body size limit: 1 MB.

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",
      "dangerousMode": 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",
    "dangerousMode": 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/dangerous

Enables or disables dangerous mode for a session.

Request body

{ "enabled": true }

Response

{ "ok": true, "dangerousMode": true }

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}' \
  http://localhost:21420/api/sessions/sess_abc123/dangerous

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

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.

PreviousCLI Commands NextConfiguration Schema

Last updated 1 day ago

Was this helpful?

Good morning

hashtagHealth & System

hashtagGET /api/health

hashtagGET /api/version

hashtagPOST /api/restart

hashtagGET /api/adapters

hashtagSessions

hashtagGET /api/sessions

hashtagGET /api/sessions/:id

hashtagPOST /api/sessions

hashtagDELETE /api/sessions/:id

hashtagPOST /api/sessions/:id/prompt

hashtagPATCH /api/sessions/:id/dangerous

hashtagPOST /api/sessions/:id/permission

hashtagPOST /api/sessions/:id/summary

hashtagPOST /api/sessions/:id/archive

hashtagPOST /api/sessions/adopt

hashtagAgents

hashtagGET /api/agents

hashtagConfiguration

hashtagGET /api/config

hashtagPATCH /api/config

hashtagGET /api/config/editable

hashtagTopics

hashtagGET /api/topics

hashtagDELETE /api/topics/:sessionId

hashtagPOST /api/topics/cleanup

hashtagTunnel

hashtagGET /api/tunnel

hashtagGET /api/tunnel/list

hashtagPOST /api/tunnel

hashtagDELETE /api/tunnel/:port

hashtagDELETE /api/tunnel

hashtagNotifications

hashtagPOST /api/notify

hashtagServer-Sent Events

hashtagGET /api/events

Health & System

GET /api/health

GET /api/version

POST /api/restart

GET /api/adapters

Sessions

GET /api/sessions

GET /api/sessions/:id

POST /api/sessions

DELETE /api/sessions/:id

POST /api/sessions/:id/prompt

PATCH /api/sessions/:id/dangerous

POST /api/sessions/:id/permission

POST /api/sessions/:id/summary

POST /api/sessions/:id/archive

POST /api/sessions/adopt

Agents

GET /api/agents

Configuration

GET /api/config

PATCH /api/config

GET /api/config/editable

Topics

GET /api/topics

DELETE /api/topics/:sessionId

POST /api/topics/cleanup

Tunnel

GET /api/tunnel

GET /api/tunnel/list

POST /api/tunnel

DELETE /api/tunnel/:port

DELETE /api/tunnel

Notifications

POST /api/notify

Server-Sent Events

GET /api/events