0xmrpeter e8af143c87 docs: update gitbook for recent specs (03-29 to 04-01)
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>
2026-04-01 21:24:26 +07:00

804 lines
15 KiB
Markdown

# 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:
1. **Secret token** — from `~/.openacp/api-secret` (full admin access)
2. **JWT access token** — scoped, revokable tokens issued by the auth system
```bash
# 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**
```json
{
"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`.
```bash
curl http://localhost:21420/api/health
```
---
### GET /api/version
Returns daemon version string. No auth required.
**Response**
```json
{ "version": "0.6.7" }
```
```bash
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**
```json
{ "ok": true, "message": "Restarting..." }
```
Returns `501` if restart is not available in the current run mode.
```bash
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/restart
```
---
### GET /api/adapters
Lists registered channel adapters.
**Response**
```json
{
"adapters": [
{ "name": "telegram", "type": "built-in" }
]
}
```
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/adapters
```
---
## Sessions
### GET /api/sessions
Lists all sessions (active, finished, cancelled, error).
**Response**
```json
{
"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`.
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/sessions
```
---
### GET /api/sessions/:id
Returns details for a single session.
**Response**
```json
{
"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.
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/sessions/sess_abc123
```
---
### POST /api/sessions
Creates a new session.
**Request body** (all fields optional)
```json
{
"agent": "claude",
"workspace": "/path/to/project"
}
```
`agent` defaults to `defaultAgent` from config. `workspace` defaults to `workspace.baseDir`.
**Response**
```json
{
"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.
```bash
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**
```json
{ "ok": true }
```
Returns `404` if not found.
```bash
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**
```json
{ "prompt": "Refactor the authentication module" }
```
**Response**
```json
{ "ok": true, "sessionId": "sess_abc123", "queueDepth": 1 }
```
Returns `400` if the session is `cancelled`, `finished`, or `error`. Returns `404` if not found.
```bash
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**
```json
{ "enabled": true }
```
**Response**
```json
{ "ok": true, "bypassPermissions": true }
```
```bash
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**
```json
{ "permissionId": "perm_xyz", "optionId": "allow" }
```
**Response**
```json
{ "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**
```json
{ "ok": true, "name": "Refactor auth module" }
```
---
### POST /api/sessions/:id/archive
Archives a session.
**Response**
```json
{ "ok": true }
```
---
### POST /api/sessions/adopt
Adopts an existing external agent session and surfaces it as a messaging thread.
**Request body**
```json
{
"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**
```json
{ "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**
```json
{
"agents": [
{
"name": "claude",
"command": "claude-agent-acp",
"args": [],
"capabilities": { "integration": "claude" }
}
],
"default": "claude"
}
```
```bash
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**
```json
{ "config": { "defaultAgent": "claude", "channels": { ... }, ... } }
```
```bash
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**
```json
{ "path": "security.maxConcurrentSessions", "value": 10 }
```
`value` can be any JSON type. String values that parse as JSON are used as-is.
**Response**
```json
{
"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.
```bash
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**
```json
{
"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).
```bash
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**
```json
{ "ok": true, "topicId": 42 }
```
```bash
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)
```json
{ "statuses": ["finished", "error"] }
```
**Response**
```json
{ "deleted": ["sess_abc123", "sess_def456"], "failed": [] }
```
---
## Tunnel
### GET /api/tunnel
Returns tunnel status for the primary tunnel service.
**Response** (when enabled)
```json
{ "enabled": true, "url": "https://abc.trycloudflare.com", "provider": "cloudflare" }
```
**Response** (when disabled)
```json
{ "enabled": false }
```
```bash
curl -H "Authorization: Bearer $TOKEN" http://localhost:21420/api/tunnel
```
---
### GET /api/tunnel/list
Lists all active user tunnels.
**Response**
```json
[
{ "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**
```json
{ "port": 3000, "label": "dev server", "sessionId": "sess_abc123" }
```
`port` is required. `label` and `sessionId` are optional.
**Response**
```json
{ "port": 3000, "publicUrl": "https://xyz.trycloudflare.com", "label": "dev server", "status": "active" }
```
Returns `400` if the tunnel service is not enabled.
```bash
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**
```json
{ "ok": true }
```
```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
http://localhost:21420/api/tunnel/3000
```
---
### DELETE /api/tunnel
Stops all user tunnels.
**Response**
```json
{ "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**
```json
{ "message": "Deployment complete" }
```
**Response**
```json
{ "ok": true }
```
```bash
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**
```json
{
"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**
```json
{ "value": "architect" }
```
**Response**
```json
{ "ok": true, "configId": "mode", "value": "architect" }
```
---
## Authentication
### POST /api/v1/auth/tokens
Creates a new JWT access token. Requires secret token authentication.
**Request body**
```json
{ "name": "my-app", "role": "operator" }
```
**Response**
```json
{
"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**
```json
{
"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**
```json
{ "ok": true }
```
---
### GET /api/v1/auth/me
Returns information about the current token (works with both secret and JWT).
**Response**
```json
{
"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**
```json
{
"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**
```json
{ "code": "abc123def456" }
```
**Response**
```json
{
"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`.