Skip to content
AASC
中文
Documentation pages

API Reference

A curated reference for AASC's REST API and WebSocket protocol.

This page lists the endpoints you are most likely to use. It is not complete. Every path was checked against the server, but request and response details can change between versions.

Base URL

http://localhost:3333/api

Use your own port if you changed it.

Authentication

  • No password set. Requests from your own computer work with no sign-in. Requests from any other device are refused with HTTP 403.
  • Password set. Every request needs a sign-in, from your own computer too. Sign in with POST /api/auth/login. The server answers with an auth_token cookie. A token lasts one hour.
# Sign in and keep the cookie
curl -c cookies.txt -X POST http://localhost:3333/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

# Use it
curl -b cookies.txt http://localhost:3333/api/sessions
  • GET /api/auth/status: whether a password is required, and whether you are signed in.
  • POST /api/auth/login: sign in with {"password": "..."}. Wrong password is 401. After 5 wrong attempts from one address, sign-in is blocked for up to 15 minutes, and the answer is 429.
  • POST /api/auth/refresh: swap your token for a fresh one.
  • POST /api/auth/logout: sign out.

Session Endpoints

  • GET /api/sessions: list all in-memory sessions, keyed by session id.
  • PUT /api/sessions/:id/title: set the title, with {"title": "..."}.
  • PUT /api/sessions/:id/remark: set the one-line progress remark, with {"remark": "..."}. An empty string clears it.
  • PUT /api/sessions/:id/accent-color: set the accent colour.
  • PUT /api/sessions/:id/remote-visible: share or hide the session on other devices. Your own computer only.
  • POST /api/sessions/:id/resume: resume an ended session.
  • POST /api/sessions/:id/restart-terminal: quit the agent and reconnect the same session in a fresh terminal. It needs the body {"confirm": true}.
  • POST /api/sessions/:id/fork: start a new session that branches from this one.
  • POST /api/sessions/:id/clone: start a new session with the same command, folder and config.
  • POST /api/sessions/:id/kill: kill the session. It needs the body {"confirm": true}.
  • POST /api/sessions/:id/summarize: write an AI summary.
  • GET /api/sessions/:id/transcript: the full conversation. Claude Code sessions only.
  • DELETE /api/sessions/:id: remove the session and close its terminals.

Kill Session

curl -X POST http://localhost:3333/api/sessions/SESSION_ID/kill \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

AASC sends SIGTERM to the agent's process group, and SIGKILL if it has not exited after about 2 seconds. It then closes the terminal. A kill also unpins the session.

Summarize Session

curl -X POST http://localhost:3333/api/sessions/SESSION_ID/summarize \
  -H "Content-Type: application/json" \
  -d '{"context": "...", "promptTemplate": "..."}'

context is required. promptTemplate and custom_prompt are optional. AASC runs claude -p --model haiku with no tools. At most 2 summaries run at once.

Prompt Queue Endpoints

  • GET /api/sessions/:id/queue: the session's queue.
  • PUT /api/sessions/:id/queue: replace the session's queue.
  • POST /api/sessions/:id/queue/items: add a paused prompt to the end of the queue.
  • POST /api/sessions/:id/queue/resume: release a queue that is held after you stopped a turn.

Terminal Endpoints

  • POST /api/terminals: create a terminal. It answers {"ok": true, "terminalId": "..."}.
  • GET /api/terminals: list active terminals.
  • DELETE /api/terminals/:id: close a terminal.
  • GET /api/terminals/:id/output: the terminal's replay buffer.
  • POST /api/terminals/:id/write: type into a terminal, with {"data": "..."}.

At most 50 sessions and 130 terminals can exist at once. Past that, POST /api/terminals answers 429.

Create Terminal

curl -X POST http://localhost:3333/api/terminals \
  -H "Content-Type: application/json" \
  -d '{
    "workingDir": "/home/dev/my-project",
    "command": "claude"
  }'

The body can also set sessionTitle, model, effortLevel, apiKey, enableOpsTerminal and more. For SSH it takes host, port, username, authMethod and privateKeyPath. For tmux it takes tmuxSession or useTmux.

History

  • GET /api/db/sessions: search sessions, with paging.
  • GET /api/db/sessions/:id: one session with all its records.
  • GET /api/db/search: search prompts and responses. It takes query, type (all, prompts or responses), page and pageSize.
  • GET /api/db/projects: the distinct projects.
  • GET /api/db/prompts: the prompts you typed. kind is mine (the default), cmd, agent or all.

Search Sessions

GET /api/db/sessions?query=auth&project=/home/dev/my-project&status=ended&page=1&pageSize=50
  • query: text to find in prompts.
  • project: the exact project path.
  • status: a status such as ended.
  • dateFrom and dateTo: start time bounds, in milliseconds.
  • archived: true for archived sessions only, or all for both. The default is not archived.
  • sortBy: started_at (the default), last_activity_at, project_name, status, total_prompts or total_tool_calls.
  • sortDir: asc or desc (the default).
  • page: the page number, starting at 1.
  • pageSize: results per page. The default is 50 and the largest is 200.

WebSocket Protocol

Connect to ws://localhost:3333. The connection follows the same sign-in rules as the REST API. A browser on the dashboard sends its cookie on its own. Other clients can send the cookie, an Authorization: Bearer header, or ?token= in the URL.

The server closes a connection with code 4001 for a missing or bad sign-in, 4003 when the origin does not match or a remote device has no password, and 4004 after more than 100 messages in a second. A message can be at most 512 KB.

Server to Client

  • snapshot, {sessions, teams, seq, hiddenCount}: sent on connection.
  • session_update, {session, team?}: a session changed.
  • session_removed, {sessionId}: a session was removed.
  • team_update, {team}: a team changed.
  • terminal_ready, {terminalId}: the terminal is ready. The replay buffer follows.
  • terminal_output, {terminalId, data}: terminal output, base64 encoded.
  • terminal_closed, {terminalId, reason}: the terminal exited or is unavailable.
  • terminal_geometry, {terminalId, cols, rows}: the terminal's real size.
  • terminal_cleared, {terminalId}: the terminal was cleared.
  • terminal_error, {terminalId, error}: a terminal request failed.
  • queue_update: a session's queue changed. It carries the whole queue.
  • hook_stats, {stats}: hook performance data.

Client to Server

  • terminal_subscribe, {terminalId}: start receiving a terminal's output.
  • terminal_disconnect, {terminalId}: stop receiving it. The terminal keeps running.
  • terminal_input, {terminalId, data}: type into a terminal. You must be subscribed. Any device that can see the session can type into it, and the last one to type is shown as its driver. A device on another computer must be signed in, and the session must be shared with it.
  • terminal_resize, {terminalId, cols, rows}: resize the terminal. The same rules as input apply, but a resize does not count as typing.
  • terminal_clear, {terminalId}: clear the terminal on every device.
  • replay, {sinceSeq}: ask for events you missed.

Reconnect

The dashboard reconnects with a growing delay, from 1 second up to 10 seconds. After a reconnect, send { "type": "replay", "sinceSeq": lastSeq } to get the events you missed. The server keeps the last 500 events.

Hook Ingestion

POST /api/hooks
Content-Type: application/json

{"session_id": "...", "hook_event_name": "SessionStart", ...}

This endpoint needs no sign-in, but it only accepts requests from your own computer. It is rate limited to 100 requests per second per address. It is the HTTP fallback. The main route is the file queue.

Hook Management

The status, install and uninstall routes under /api/hooks only accept requests from your own computer, like hook ingestion. They follow the usual sign-in rules when a password is set.

  • GET /api/hooks/status: the installed density and events, per CLI.
  • POST /api/hooks/install: install hooks, with {"density": "medium"}. You can add "enabledClis": ["claude", "codex"].
  • POST /api/hooks/uninstall: remove all dashboard hooks.
  • GET /api/hook-stats: delivery latency and processing metrics.
  • POST /api/hook-stats/reset: clear the metrics.
  • GET /api/mq-stats: message queue health.

Central Session Endpoints

These routes are for the dashboard on your own computer. Every other caller gets 404, and so does any caller while central sessions are off. A central's own calls get 403. See Central Sessions.

  • GET /api/mcp/centrals: the live central sessions.
  • GET /api/mcp/activity: the activity log, newest first. Filter with central and limit. The default limit is 100 and the largest is 500.
  • GET /api/mcp/tasks: the tasks centrals handed out that have not ended.
  • GET /api/mcp/confirms: the confirm cards that wait for you.
  • POST /api/mcp/confirm/:cardId: answer a card, with {"decision": "allow"} or {"decision": "deny"}.
  • PUT /api/mcp/sessions/:id/hands-off: turn Hands off on or off, with {"on": true} or {"on": false}.

A central itself talks to /mcp, which is the MCP endpoint. It accepts only your computer, with a central's token.