Dashboard API

raw dashboard serves a browser app and a small local JSON API. The API is intended for the bundled app. You can use it for scripts on the same machine, but its shape can change between releases.

Access and security

• The server binds to 127.0.0.1. The port defaults to 8787. Port 0 picks a free port.
• Every /api route requires Authorization: Bearer TOKEN. The token is printed in the launch URL.
• The Host header must match the listener’s address and port. A browser Origin must match the dashboard’s origin exactly.
• Query-string tokens are not accepted.
• Responses cannot be read or embedded from another origin.
• JSON request bodies are limited to 1 MiB. Uploads have their own limits.

Caution

The dashboard runs with your full account permissions. The token protects the API from other websites and other users, not from software you run locally.

Errors

Errors use one shape:

{ "error": { "code": "invalid_input", "message": "...", "details": {} } }

Status	Meaning
400	Malformed input.
401	Missing or invalid token.
403	Host or origin not allowed.
404	Resource not found.
409	Conflict. A state changed, or a revision is stale.
413	Body or upload too large.
415	Unsupported media type.
422	Input is well-formed but invalid, such as an unknown agent.
500	Internal error.
503	A required capability is unavailable.

Bootstrap

GET /api/bootstrap returns the server version, the working directory, the config path, the default agent, and whether the config is valid. It returns no credentials, no config body, and no conversation text.

Workspaces

Method and path	Description
GET /api/workspaces	Lists recently used directories, with session and running counts. Add include=<path> to pin directories.
POST /api/workspaces/validate	Body { "cwd": "..." }. Checks that the directory exists and returns its canonical path.
GET /api/workspaces/browse?path=&hidden=&q=	Lists sub-directories for a folder picker. Lists directory names only.

Choosing a workspace changes the working directory for relative paths. It does not change file permissions.

Sessions and turns

Method and path	Description
GET /api/sessions?cwd=&title=&before=&limit=	Lists sessions, 20 per page by default and 100 at most. Uses opaque cursors.
POST /api/sessions	Body { "cwd", "agent"? }. Creates an empty session without a model request.
GET /api/sessions/:id	Returns the session, its latest history page, metrics, recent operations, and ownership (idle, here, or elsewhere).
GET /api/sessions/:id/history?before=&limit=	Loads older history.
PATCH /api/sessions/:id	Body { "title" }. Renames the session.
DELETE /api/sessions/:id	Deletes the session. Refused while a writer is active.
POST /api/sessions/:id/operations	Starts a turn or a compaction. Body { "clientRequestId", "kind": "turn" or "compact", "agent", "input"?, "attachments"?, "files"?, "request"? }. Returns 202 with a receipt.
GET /api/sessions/:id/operations?clientRequestId=	Finds a receipt after a lost response.
GET /api/operations/:id	Reads one receipt.
POST /api/operations/:id/cancel	Cancels work that this server owns.
GET /api/sessions/:id/metrics	Returns metrics and whether they are stale. Missing values are null, never zero.

Rules for turns:

• The server uses the agent’s config as currently saved. The browser cannot supply a config.
• A repeated clientRequestId with the same intent returns the original receipt. Reusing it for a different intent returns 409.
• Nothing submits work on a GET, a refresh, or a reconnect.

Attachments and files

Method and path	Description
POST /api/sessions/:id/attachments	Uploads one PNG or JPEG. The body is the raw file, with Content-Type set. Returns 201 with an id.
DELETE /api/sessions/:id/attachments/:attachmentId	Removes a staged attachment.
GET /api/sessions/:id/files?q=&limit=	Searches workspace files for references. Skips .git, node_modules, dot entries, and symlinks.
GET /api/sessions/:id/history/:sequence/attachments/:index	Returns the stored bytes of one attachment in a user message.

Turns can refer to up to 8 staged attachments and up to 20 workspace files. A file path must stay inside the workspace. Attachments are not accepted on compaction.

Images are sent to the model only when the model has vision: true. Otherwise the model receives a text placeholder, and the saved session keeps the original image.

Agent composer

Method and path	Description
GET /api/agents/:name/composer	Returns the agent’s selected skills, its vision setting, the attachment kinds it accepts, and any request controls the provider supports. Needs no credentials.

A turn can carry request: { effort?, serviceTier? } to change those controls for one operation. The change is never written to the config.

Streams and approvals

GET /api/sessions/:id/events is a Server-Sent Events stream. Send Last-Event-ID to replay retained events. A client that cannot replay receives a fresh snapshot.

Each event has an instanceId, a sessionId, a sequence, a type, and data. Event types include snapshots, committed history, text and reasoning, tool state, operation state, compaction, metrics, approvals, panels, interactions, commands, and host errors.

The server keeps up to 4096 events and 4 MiB per session for replay. Large live output is paged separately with GET /api/sessions/:id/output?operationId=&segmentId=&offset=.

Method and path	Description
POST /api/permissions/:approvalId	Body { "operationId", "callId", "allow" }. The first valid answer wins. Later answers return 409. Expired requests are denied.
GET /api/activity	Lists active and recent operations and pending approvals, without bodies.

Approvals are created only for matching ask rules.

Panels

Method and path	Description
GET /api/sessions/:id/panels?agent=NAME	Lists the panels for the session’s agent.
GET /api/sessions/:id/panels/:panel	Returns one panel, or 404 unknown_panel.
POST /api/sessions/:id/panels/:panel/actions	Runs a tool action. Body { "action", "agent", "block"?, "item"?, "clientRequestId" }. Returns 202 with an operationId.
GET /api/sessions/:id/views/:instanceId	Returns one saved chat view.

Panel IDs in paths are the full owner#panel form, URL-encoded. A panel action goes through the tool’s normal rules, approval, and hooks. Errors include 409 session_busy, 409 stale_panel, 403 action_denied, and 422 invalid_action.

Interactions

Method and path	Description
GET /api/sessions/:id/interactions/:requestId	Returns one request and its state.
POST /api/sessions/:id/interactions/:requestId/responses	Body { "requestId", "expectedRevision", "idempotencyKey", "response": "submit", "answers" } or { ..., "response": "cancel" }.

A stale or conflicting response returns 409. An invalid answer returns 422 and leaves the request pending. A repeat with the same key returns the original result. See Tool contract.

Commands

Commands are foreground Bash runs and background processes, shown together.

Method and path	Description
GET /api/sessions/:session/commands	Lists commands.
GET /api/sessions/:session/commands/:id/output?cursor=0&maxBytes=65536	Returns a page of output with absolute cursors.
POST /api/sessions/:session/commands/:id/stop	Body { "clientRequestId" }. Stops a background process through its policy and approval checks. Returns 202 with a control receipt.
GET /api/sessions/:session/commands/:id/controls/:controlId	Reads a control receipt.

See Background processes.

Configuration

Write requests use the revision from the matching read. A stale revision returns 409 conflict and never overwrites the file. Invalid candidates return 422 and leave the file unchanged.

Method and path	Description
GET /api/config	Returns the config path, revision, validity, and summaries of agents, variables, providers, and MCP servers. Never returns credentials, literal values, commands, or URLs.
POST /api/config/initialize	Creates the starter config. Fails if the file exists.
GET /api/config/document	Returns the full config for the advanced editor.
PUT /api/config/document	Body { "revision", "source" }. Saves the full config after validation.
POST /api/config/validate	Body { "source" }. Validates without saving.
PATCH /api/config	Body { "revision", "patch" }. Replaces top-level fields. null removes a field.
GET /api/agents/:name, GET /api/models/:name	Reads one agent or model with its revision.
POST /api/agents, POST /api/models	Creates, edits, duplicates, renames, or deletes an agent or model.
GET /api/components/:kind	Lists tools, skills, or hooks, with where each is used.
GET /api/components/:kind/:id	Returns one component.
POST /api/components/:kind	Creates a component from files, or forks one with cloneFrom.
GET and PUT /api/components/:kind/:id/file?path=	Reads or saves one text file inside a component.
POST /api/components/:kind/:id/selection	Attaches or detaches a component on an agent.
DELETE /api/components/:kind/:id	Deletes a component. Refused while it is in use or read-only.
POST /api/policy/test	Shows the effect a rule set would give for a tool identity and arguments. Does not run the tool.
POST /api/checks	Starts an explicit variable or MCP check. Returns 202.
GET /api/checks/:id	Reads a check’s state and result.
POST /api/checks/:id/cancel	Cancels a check.
GET /api/diagnostics	Returns version, platform, and count information. No transcripts, credentials, or variable values.

Checks have a 30-second deadline and run at most eight at a time. An MCP check lists the server’s tools and never calls one.

Model credentials use explicit edits: { "mode": "keep" }, { "mode": "clear" }, or { "mode": "set", "value": "..." } or { "mode": "set", "env": "ENV_NAME" }.

Packages

Method and path	Description
GET /api/packages	Lists installed aliases, their digests, and any diagnostics.
GET /api/packages/:alias	Returns the package report, input schema, and where it is used.
POST /api/packages/inspect	Body { "path" }. Stages a local folder or .rawpkg for review.
POST /api/packages/upload	Uploads a .rawpkg as the raw request body.
GET /api/packages/stages	Lists staged packages.
DELETE /api/packages/stages/:id	Discards a staged package.
GET /api/packages/stages/:id/download	Downloads a staged .rawpkg.
POST /api/packages/install	Body { "stageId", "alias", "action": "install" or "update" or "link" }.
POST /api/packages/:alias/agent	Creates an agent bound to a package agent, with your model. Does not change the default agent.
POST /api/packages/:alias/component	Adds a package tool or skill to an agent, or binds a variable, provider, or MCP server.
POST /api/packages/export	Exports an agent as a package and packs it.
POST /api/packages/:alias/fork	Copies an installed package into an editable folder.
DELETE /api/packages/:alias	Removes an alias. Refused while agents depend on it.

Staged packages are kept for 30 minutes, up to four at a time. Installing uses the staged snapshot, even if the source changes afterward. A failed update keeps the last working version.

See Packages.