# Dashboard API > The local HTTP API behind raw dashboard, covering authentication, errors, sessions, turns, streaming events, approvals, panels, configuration, and packages. `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: ```json { "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=` 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](https://raw.tlelabs.com/docs/reference/tool-contract/#interaction-requests). ## 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](https://raw.tlelabs.com/docs/extend/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](https://raw.tlelabs.com/docs/extend/packages/).