HQ Management API

The HQ Management API gives you programmatic control of the HQ. Desktop uses the same API to deploy agents, connect Telegram and WhatsApp channels, store credentials and install plugins. The API listens on 127.0.0.1, port 9300 by default. To change the port, use --management-port.

This page documents the administrative routes. Phones, tablets and the web app never get administrative access. They use the mobile namespace /mobile/v1. The HQ Mobile API page documents this namespace.

OverviewCopy Anchor Link

The HQ runs two HTTP listeners. Both listen on the loopback address only:

The HQ has no LAN listener. The HQ accepts the old --lan-port flag, but it ignores the flag and logs a warning. Remote clients connect through the hosted relay. The relay forwards only HTTP requests for /mobile/v1, and the /ws/chat WebSocket. Thus, only a process on the HQ machine can reach the administrative routes.

Each route section has one of these marks:

Some mobile variants accept fewer fields. Each section gives the differences.

AuthenticationCopy Anchor Link

Send the management bearer in the Authorization header with each request:

Authorization: Bearer <your-management-token>

The HQ reads its tokens from environment variables when it starts:

The old --token and --chat-token flags still work in this release, but the HQ writes a warning. If you set a variable and its flag, the variable wins.

The two scopes do not overlap. The HQ rejects the management bearer under the mobile namespace. It rejects the mobile bearer on all other paths. If the two tokens have the same value, the HQ does not start. Relay mode needs the two tokens.

Two paths have no bearer check:

If the bearer is missing or wrong, the HQ returns HTTP 401:

{ "code": "unauthorized", "error": "Unauthorized", "retryable": false }

Error shapesCopy Anchor Link

Route groups use one of three error shapes. Each section tells you which shape it uses.

Request checksCopy Anchor Link

The HQ checks each request before the route handler gets it. These checks apply to all routes:

The management API sets no global body-size limit. The speech routes have their own limits. Administrative routes send no CORS headers. CORS applies only to the mobile namespace. See the HQ Mobile API.

Route indexCopy Anchor Link

The routes from /agents/:id/autonomy to /needs-you exist only while /health lists long-horizon-v1. The HQ Mobile API page documents them. Both listeners use the same handlers and the same error shape.

The HQ also serves conversation routes on this listener with the management bearer. The HQ Mobile API documents them. See Conversations and chat.

Health and statusCopy Anchor Link

GET /healthCopy Anchor Link

Returns the HQ status, the mobile contract version and the runtime capabilities. This route needs no authentication. Also under /mobile/v1, as GET /mobile/v1/health.

Only loopback /health adds version, the HQ software version captured at startup. /mobile/v1/health keeps its existing fields and does not include version. The software version is separate from apiVersion and contractVersion.

curl http://127.0.0.1:9300/health

{
  "status": "healthy",
  "startedAt": "2026-07-12T00:00:00.000Z",
  "pid": 12345,
  "agents": 2,
  "channels": 1,
  "apiVersion": 1,
  "contractVersion": 1,
  "version": "0.9.0",
  "capabilities": [
    "providers-v1",
    "speech-v1",
    "long-horizon-v1",
    "provider-recovery-v1",
    "chat-archive-v1",
    "cancel-step-v1",
    "agent-rename-v1",
    "chat-tools-v1"
  ]
}

Capabilities:

Ignore capability values that you do not know. Some values also change the shape of responses. The HQ Mobile API page tells how a client declares the capabilities that it can read.

GET /infoCopy Anchor Link

Returns a short summary of the agents. Loopback only.

{
  "agents": [
    { "name": "assistant", "model": "anthropic/claude-sonnet-4-20250514", "tools": ["bash"] }
  ]
}

GET /runtime/statusCopy Anchor Link

Returns a snapshot of the current HQ state. Loopback only.

curl http://127.0.0.1:9300/runtime/status \
  -H "Authorization: Bearer $DASH_TOKEN"

{
  "execution": {
    "accepting": true,
    "activeCanonicalTurns": 2,
    "activeLegacyTurns": 1,
    "quiescingAgents": 0
  },
  "pool": { "size": 3, "maxSize": 64, "pinned": 3, "agents": { "a1": 3 } },
  "channels": [{ "name": "telegram", "health": "connected" }],
  "relay": { "connection": "disabled", "activeStreams": 0 }
}

Use GET /health as the liveness check. The status route reports the process state only. It does not test the providers, and it does not tell you that queued work is complete. It contains no credentials, conversation text or queued message text.

POST /lifecycle/shutdownCopy Anchor Link

Stops the HQ cleanly. Loopback only. Desktop calls this route before it sends a stop signal to the process. The request needs no body.

The HQ sends the reply first. Then it closes its servers and stops:

{ "ok": true }

If the HQ cannot start the shutdown, it returns 500 with the structured gateway_offline error.

GET /identityCopy Anchor Link

Returns the stable ID and the Ed25519 public key of the HQ. Also under /mobile/v1, where native clients call it with the mobile bearer.

{
  "gatewayId": "gateway-01",
  "publicKey": "<base64-public-key>"
}

The public key identifies the HQ. You can share it safely. The private key stays on the HQ machine.

AgentsCopy Anchor Link

Create and manage agents. The HQ saves agents in ~/.dash/gateway/agents.json. All agent routes are also under /mobile/v1. The mobile create and update routes accept fewer fields (see below).

Agent routes use the structured error shape. Responses never include providerApiKeys.

Agent objectCopy Anchor Link

{
  "id": "3f9c2a1b",
  "name": "assistant",
  "config": {
    "name": "assistant",
    "model": "anthropic/claude-sonnet-4-20250514",
    "systemPrompt": "You are a helpful assistant.",
    "tools": ["bash", "browser"],
    "workspace": "/Users/you/.dash/workspaces/3f9c2a1b"
  },
  "status": "registered",
  "registeredAt": "2026-07-12T00:00:00.000Z",
  "effortLevels": ["low", "medium", "high"]
}

status is registered, active or disabled. config holds each configuration field that you set, but not providerApiKeys. effortLevels lists the effort levels that the current model supports. It is empty when the model does not think, or when no level reaches the provider. See Extended thinking.

Configuration fieldsCopy Anchor Link

The HQ returns 400 for all other keys. Numeric limits must be positive integers. Two limits, swarm.maxSteersPerWorker and subagents.maxDepth, also accept 0. modelAliases maps a short alias (no /) to a model ID. Memory settings have their own routes. See Memory.

GET /agentsCopy Anchor Link

Lists all agents as an array of agent objects.

curl http://127.0.0.1:9300/agents \
  -H "Authorization: Bearer $DASH_TOKEN"

POST /agentsCopy Anchor Link

Creates an agent and returns it with HTTP 201. name, model and systemPrompt are necessary. The mobile namespace accepts only these three fields.

curl -X POST http://127.0.0.1:9300/agents \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assistant",
    "model": "anthropic/claude-sonnet-4-20250514",
    "systemPrompt": "You are a helpful assistant.",
    "tools": ["bash"]
  }'

GET /agents/:idCopy Anchor Link

Returns one agent object.

PUT /agents/:idCopy Anchor Link

Updates the configuration of an agent and returns the updated agent. Send only the fields to change. The body must not be empty. The mobile namespace accepts only name, model and systemPrompt. It also accepts messaging while /health lists long-horizon-v1.

Send name to rename the agent. The agent keeps its ID and its folders. The HQ removes spaces at the start and end of the name. Then it checks these rules:

Each of these errors has code: "validation_failed" and details.field: "name". If the HQ refuses the name, it changes no other field. After a rename, the HQ adds an agent_renamed notice to the newest chat of the agent, if it has one.

curl -X PUT http://127.0.0.1:9300/agents/3f9c2a1b \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-opus-4-5"}'

A change to swarm or subagents restarts the warm runtimes of the agent. Thus, the next turn uses the new settings. The HQ reads other changes on the next turn.

DELETE /agents/:idCopy Anchor Link

Deletes an agent and returns {"ok": true}. The HQ cancels the active turns and swarm runs of the agent. It removes the agent from channel routing and deletes its browser sessions. The HQ archives the conversations of the agent and does not delete them. You can still read their messages through the conversation routes.

POST /agents/:id/disableCopy Anchor Link

Disables an agent but does not delete it, and returns {"ok": true}. The HQ stops new turns for the agent. It cancels the active turns and swarm runs of the agent and releases its runtimes.

POST /agents/:id/enableCopy Anchor Link

Enables a disabled agent again and returns {"ok": true}.

POST /agents/:agentId/conversation-titleCopy Anchor Link

Makes a short title for a conversation from its first message. Loopback only. The HQ makes the title with one small completion on the model of the agent.

{ "title": "Release planning" }

Errors use the plain shape:

MemoryCopy Anchor Link

Read and edit the facts that an agent keeps from one conversation to the next. See Memory. The list, read and delete routes are also under /mobile/v1. The write route and the settings routes are loopback only.

Memory routes use the plain error shape, also in the mobile namespace:

GET /agents/:id/memoryCopy Anchor Link

Lists the memories of an agent without their bodies. The list shows the memories on disk, also when memory is off for the agent.

[
  {
    "name": "preferred-editor",
    "description": "User edits code in Neovim",
    "type": "user",
    "source": "agent",
    "createdAt": "2026-07-12",
    "updatedAt": "2026-07-12",
    "size": 58
  }
]

type is user, feedback, project or reference. source tells you which writer made the memory: agent, sweep, user or import. size is the body length in characters.

GET /agents/:id/memory/:nameCopy Anchor Link

Returns one memory with its content. It has the same fields as the list, but not size.

PUT /agents/:id/memory/:nameCopy Anchor Link

Creates or replaces a memory. The name comes from the path. The HQ records memories from this route with source: "user".

The name has lowercase letters, digits and hyphens. It starts with a letter or digit and has a maximum of 64 characters.

curl -X PUT http://127.0.0.1:9300/agents/3f9c2a1b/memory/preferred-editor \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "User edits code in Neovim", "type": "user", "content": "Prefers Neovim."}'

{
  "record": {
    "name": "preferred-editor",
    "description": "User edits code in Neovim",
    "type": "user",
    "source": "user",
    "createdAt": "2026-07-12",
    "updatedAt": "2026-07-12",
    "content": "Prefers Neovim."
  },
  "action": "created"
}

action is created or updated.

DELETE /agents/:id/memory/:nameCopy Anchor Link

Deletes a memory and returns its name. This route also works when memory is off.

{ "name": "preferred-editor" }

GET /agents/:id/memory/configCopy Anchor Link

Returns the memory settings of the agent. If an agent has no memory settings, the route returns enabled: true with sweep: "auto".

{ "enabled": true, "sweep": "auto" }

PATCH /agents/:id/memory/configCopy Anchor Link

Changes memory settings and returns the merged result. Fields that you omit keep their current values.

A change to enabled restarts the warm runtimes of the agent. Thus, the next turn gets or loses the memory tools. A change to sweep applies on the next turn.

SkillsCopy Anchor Link

Manage the skills that an agent can load. See Skills. Only GET /agents/:id/skills is also under /mobile/v1, as a read-only view. All other skill routes are loopback only.

Skill routes use the plain error shape:

GET /agents/:id/skillsCopy Anchor Link

Lists all skills that the agent can use, from plugins and from the agent.

[
  {
    "name": "release-notes",
    "description": "Write release notes from merged PRs",
    "trigger": "when asked for release notes",
    "location": "/Users/you/.dash/gateway/skills/assistant/release-notes/SKILL.md",
    "content": "...",
    "editable": true,
    "source": "managed"
  }
]

source is managed, agent (the agent learned it), remote or plugin. Under /mobile/v1, each entry has only name, description, trigger, source and content.

POST /agents/:id/skillsCopy Anchor Link

Creates a skill and returns HTTP 201 with its name and file location.

{ "name": "release-notes", "location": "/Users/you/.dash/gateway/skills/assistant/release-notes/SKILL.md" }

GET /agents/:id/skills/:nameCopy Anchor Link

Returns one skill with the same fields as the list.

PUT /agents/:id/skills/:nameCopy Anchor Link

Replaces the body of a skill and keeps its frontmatter. Send {"content": "..."}. Returns the name and location of the skill.

DELETE /agents/:id/skills/:nameCopy Anchor Link

Removes a skill and returns {"name": "..."}. You cannot remove plugin skills with this route.

POST /agents/:id/skills/installCopy Anchor Link

Installs a skill from a git repository, a URL or a local path. The HQ scans the skill before it installs it. If the scan fails, the HQ does not install the skill.

{
  "name": "release-notes",
  "location": "/Users/you/.dash/gateway/skills/assistant/release-notes/SKILL.md",
  "verdict": { "verdict": "safe", "reasons": [] }
}

verdict.verdict is safe or suspicious. The HQ rejects a dangerous skill with 422.

GET /agents/:id/skills/configCopy Anchor Link

Returns the skills configuration of the agent, or {} if it has none.

{ "paths": ["/opt/skills"], "learning": "auto", "minToolCalls": 3 }

PATCH /agents/:id/skills/configCopy Anchor Link

Merges fields into the skills configuration of the agent and returns the result. The HQ returns 400 for other keys.

GET /agents/:id/skills/:name/lessonsCopy Anchor Link

Returns the lesson book of a skill that the agent learned. If the skill has no lesson book, the route returns 404.

{
  "version": 1,
  "skill": "deploy-checks",
  "description": "Checks to run before deploying",
  "augments": [],
  "bullets": [
    {
      "id": "l1",
      "text": "Run the migration dry-run before deploying.",
      "helpful": 2,
      "harmful": 0,
      "createdAt": "2026-07-12T00:00:00.000Z",
      "lastTouchedAt": "2026-07-14T00:00:00.000Z"
    }
  ],
  "retired": []
}

augments gives the names of other skills that this book goes with. retired holds the lessons that the HQ removed from the active list. Each retired lesson has retiredAt and retiredReason (harmful or capacity).

DELETE /agents/:id/skills/:name/lessons/:lessonIdCopy Anchor Link

Retires one lesson and returns the updated lesson book. The lesson moves to retired. The HQ does not delete it, and a later review does not propose it again.

Sub-agentsCopy Anchor Link

Manage the helper agents that an agent can start, and the sub-agents that are active now. All routes in this section are also under /mobile/v1.

Definitions. The five definition routes read and write the sub-agent types of one agent. On the loopback API, they use the plain error shape. Under /mobile/v1, they use the structured shape. A definition :name has lowercase letters, digits and hyphens, and starts with a letter or digit. The HQ returns 400 for all other names, and 404 for an unknown agent.

GET /agents/:id/subagent-typesCopy Anchor Link

Returns the resolved roster of the agent: built-in types, plus workspace, plugin and per-agent definitions.

{
  "types": [
    {
      "name": "reviewer",
      "description": "Reviews a diff for correctness",
      "source": "agent",
      "tools": ["read", "grep"],
      "model": "anthropic/claude-sonnet-4-20250514",
      "background": false
    }
  ],
  "unknownAllowedTypes": ["reveiwer"]
}

Each type can also have location, disallowedTools, skills, maxTurns, isolation (worktree) and shadowedBy. The roster does not include the system prompt. Read it from the definition route. unknownAllowedTypes lists the names in subagents.allowedTypes that match no type. Usually, the name is not correct.

GET /agents/:id/subagent-definitionsCopy Anchor Link

Lists the definition files in the writable directory of the agent. Workspace and plugin definitions show only in the roster.

{ "definitions": [{ "name": "reviewer", "file": "reviewer.md" }] }

GET /agents/:id/subagent-definitions/:nameCopy Anchor Link

Returns the raw Markdown of one definition.

{ "name": "reviewer", "raw": "---\nname: reviewer\ndescription: Reviews a diff\n---\nYou review diffs." }

PUT /agents/:id/subagent-definitions/:nameCopy Anchor Link

Writes a definition and returns {"ok": true, "name": "reviewer"}. Send {"raw": "..."} with the full Markdown file and its frontmatter.

The HQ validates the definition before it writes it. The agent uses the change on its next model turn.

DELETE /agents/:id/subagent-definitions/:nameCopy Anchor Link

Deletes a definition file and returns {"ok": true, "name": "reviewer"}. If the file does not exist, the route returns 404.

Active sub-agents. The conversation, stop and resume routes use the structured error shape on the two mounts.

GET /conversations/:id/subagentsCopy Anchor Link

Lists the sub-agents that a conversation started. The HQ reads the list from saved state. Thus, the list is correct after an HQ restart.

{
  "subagents": [
    {
      "id": "sub_01J...",
      "name": "reviewer-1",
      "type": "reviewer",
      "description": "Review the auth diff",
      "status": "done",
      "background": true,
      "depth": 1,
      "startedAt": "2026-07-12T00:00:00.000Z",
      "endedAt": "2026-07-12T00:02:10.000Z",
      "usage": { "inputTokens": 12000, "outputTokens": 900 },
      "toolCallCount": 7,
      "report": "No blocking issues found.",
      "oneShot": false
    }
  ]
}

status is running, waiting_input, done, failed, cancelled, interrupted or max_turns. The HQ scans report before it returns it. You cannot resume a oneShot type, for example Explore or Plan. For an unknown conversation, the route returns 404 not_found.

POST /subagents/:id/stopCopy Anchor Link

Stops a sub-agent and all the sub-agents that it started. The request needs no body.

{ "ok": true, "status": "cancelled" }

If :id is not a sub-agent, the route returns 404 not_found. If the sub-agent is already complete, it returns 409.

POST /subagents/:id/resumeCopy Anchor Link

Sends a follow-up message to a sub-agent. The result is the same as when its parent uses the send_message tool.

{ "ok": true, "status": "running", "mode": "resumed" }

mode is resumed when the message starts a new turn. It is queued when the HQ gives the message to an active sub-agent. The route returns 400 for an incorrect body and 404 for an unknown sub-agent. It returns 409 when the sub-agent cannot accept the message. Causes are a one-shot type, no steer messages left, or no parent conversation.

Swarm panelCopy Anchor Link

Examine and control the swarm runs of an agent. A run is the set of sub-agents that one parent turn started. All routes here are loopback only and use the plain error shape. For an unknown agent or run, the routes return 404.

GET /agents/:id/swarm/runsCopy Anchor Link

Lists the recent runs of the agent. The list includes runs from before the last HQ restart.

{
  "runs": [
    {
      "runId": "run_01J...",
      "agentId": "3f9c2a1b",
      "conversationId": "018f0f4a-...",
      "startedAt": 1752278400000,
      "endedAt": 1752278530000,
      "finalized": true,
      "workerCount": 2,
      "activeCount": 0
    }
  ]
}

startedAt and endedAt are epoch milliseconds.

GET /agents/:id/swarm/runs/:runIdCopy Anchor Link

Returns one run with the same fields, plus a workers array with a snapshot of each worker.

POST /agents/:id/swarm/runs/:runId/workers/:workerId/cancelCopy Anchor Link

Cancels one worker. Returns {"ok": true}. If the HQ cannot cancel the worker, it returns 409 with {"ok": false, "reason": "..."}. This route also works for a background worker after the turn that started it is complete.

POST /agents/:id/swarm/runs/:runId/workers/:workerId/sendCopy Anchor Link

Sends a message to one worker. Send {"message": "..."}. For an empty message, the route returns 400. Returns {"ok": true}. If the worker cannot accept the message, the route returns 409 with {"ok": false, "reason": "..."}.

POST /agents/:id/conversations/:conversationId/swarm/cancelCopy Anchor Link

Cancels all workers that are not complete in the live swarm turn of the conversation. Workers continue after the chat stream stops. Thus, the stop button uses this route to stop them.

{ "cancelled": true }

cancelled is false when there was no live turn. You can call the route again safely.

BrowserCopy Anchor Link

Manage the browser that agents use, and the saved logins in their browser profiles. See Browser. All routes here are loopback only.

Browser routes use the plain error shape. For an incorrect profile name, they return 400. For a profile that an open browser uses, they return 409. For an unknown agent, they return 404 with {"error":"Agent not found"}.

GET /browser/statusCopy Anchor Link

Returns the browser that the HQ starts, the progress of the managed download, and the number of live browser sessions.

{
  "source": "chrome",
  "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  "install": { "state": "idle", "done": 0, "total": 0 },
  "liveSessions": 1,
  "sizes": { "downloadMb": 190, "diskMb": 370 }
}

POST /browser/installCopy Anchor Link

Starts the download of the managed browser. The route returns HTTP 202 immediately with the current progress. To follow the progress, poll GET /browser/status. If a download is in progress, the route returns the same 202 and does not start a second download. When a download fails, the status shows install.state: "failed".

{ "install": { "state": "downloading", "done": 0, "total": 199229440 } }

GET /agents/:id/browser/profilesCopy Anchor Link

Lists the saved browser profiles of the agent.

{
  "profiles": [
    { "name": "work", "lastUsedAt": "2026-07-12T00:00:00.000Z", "sizeBytes": 41943040, "inUse": false }
  ]
}

DELETE /agents/:id/browser/profiles/:nameCopy Anchor Link

Deletes a saved profile with its cookies and logins, and returns {"name": "work"}. While an open browser uses the profile, the route returns 409.

ChannelsCopy Anchor Link

Connect and manage channels for Telegram and WhatsApp. See the Telegram and WhatsApp page. The HQ saves channels in ~/.dash/gateway/channels.json. All routes here are loopback only and use the plain error shape.

Channel objectCopy Anchor Link

{
  "name": "family-telegram",
  "adapter": "telegram",
  "globalDenyList": [],
  "allowedUsers": ["123456789"],
  "routing": [
    {
      "condition": { "type": "default" },
      "agentId": "3f9c2a1b",
      "allowList": [],
      "denyList": []
    }
  ],
  "registeredAt": "2026-07-12T00:00:00.000Z"
}

adapter is telegram or whatsapp. A routing condition is {"type": "default"}, {"type": "sender", "ids": [...]} or {"type": "group", "ids": [...]}.

GET /channelsCopy Anchor Link

Lists all channels as an array of channel objects.

POST /channelsCopy Anchor Link

Creates a channel, starts its adapter, and returns HTTP 201 with {"ok": true}.

Store the credential of the channel first with POST /credentials. For Telegram, store the bot token under channel:<name>:token. For WhatsApp, store the auth JSON under channel:<name>:whatsapp-auth. If the credential is missing, the route returns 400.

curl -X POST http://127.0.0.1:9300/channels \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "family-telegram",
    "adapter": "telegram",
    "routing": [{"condition": {"type": "default"}, "agentId": "3f9c2a1b", "allowList": [], "denyList": []}]
  }'

GET /channels/:nameCopy Anchor Link

Returns one channel object. URL-encode the name.

PUT /channels/:nameCopy Anchor Link

Updates a channel and returns the updated channel object. Send one or more of routing, globalDenyList and allowedUsers. Fields that you omit do not change. Each field must be an array.

DELETE /channels/:nameCopy Anchor Link

Stops the adapter of the channel, removes the channel, and returns {"ok": true}.

CredentialsCopy Anchor Link

Store provider API keys and channel tokens in the encrypted store of the HQ (~/.dash/gateway/credentials.enc). See Secrets. All routes here are loopback only and use the plain error shape.

Some key formats have a special meaning:

GET /credentialsCopy Anchor Link

Lists the stored credential keys. The route never returns values.

["anthropic-api-key:default", "anthropic-key-meta:default", "channel:family-telegram:token"]

POST /credentialsCopy Anchor Link

Sets one credential and returns HTTP 201 with {"ok": true}. key and value are necessary, and must not be empty.

curl -X POST http://127.0.0.1:9300/credentials \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "anthropic-api-key:default", "value": "sk-ant-..."}'

Active agents use the new value on their next turn.

DELETE /credentials/:keyCopy Anchor Link

Deletes a credential and returns {"ok": true}. URL-encode the key.

For a provider API key, this also deletes its saved refresh token, expiry and metadata. If you set that key again, the HQ treats it as a pasted API key.

POST /credentials/provider-oauthCopy Anchor Link

Saves a complete provider subscription credential in one update. Returns HTTP 201 with {"ok": true}.

Do not send other fields. Invalid fields return HTTP 400 with {"error": "Invalid provider OAuth credentials"}. The HQ refreshes its provider caches after the update.

PUT /credentials/provider/:provider/:nameCopy Anchor Link

Replaces the provider credential with a pasted API key. URL-encode the provider ID and key name. Their rules are the same as above.

Send {"value": "<api-key>"}. The value must be nonempty, contain no whitespace and have at most 8,192 characters. Do not send other fields.

The HQ removes the saved refresh token and expiry, and resets the key metadata. Returns HTTP 201 with {"ok": true}. Invalid fields return HTTP 400 with {"error": "Invalid provider API key"}.

DELETE /credentials/provider/:provider/:nameCopy Anchor Link

Removes the provider key, refresh token, expiry and metadata in one update. URL-encode both path values. Returns {"ok": true}.

An invalid provider ID or key name returns HTTP 400 with {"error": "Invalid provider credential name"}.

Phones and the web app use the AI providers routes of the Mobile API. These routes manage provider API keys and the sign-in with a Claude or ChatGPT subscription.

ModelsCopy Anchor Link

List the models that agents can use. See AI Providers. GET /models is also under /mobile/v1 as a read-only view. POST /models/refresh is loopback only.

The HQ gets the model list of each configured provider and filters it through the bundled provider catalogs. It keeps the result for six hours. If a provider fails, the HQ tries it again after five minutes. Until then, it keeps the last good models of that provider. When you set or delete a provider API key, the HQ clears the stored list. If no provider key exists, the response lists the built-in models of each catalog with source: "bootstrap".

GET /modelsCopy Anchor Link

curl http://127.0.0.1:9300/models \
  -H "Authorization: Bearer $DASH_TOKEN"

{
  "models": [
    { "value": "anthropic/claude-opus-4-5", "label": "Claude Opus 4.5", "provider": "anthropic" }
  ],
  "source": "live",
  "errors": {},
  "fetchedAt": "2026-07-12T00:00:00.000Z",
  "supportedModelsReviewedAt": "2026-07-01"
}

On the loopback API, ?debug=true adds bootstrap (the built-in models of the catalogs), patterns, providersConfigured and providersAvailable. In the mobile namespace, all query parameters cause 400 with the structured validation_failed error.

POST /models/refreshCopy Anchor Link

Gets the model list again without the stored result, and returns the same shape as GET /models.

SpeechCopy Anchor Link

Dictation and read-aloud. All speech routes are also under /mobile/v1, with the same handler. Hands-free voice mode uses the chat WebSocket. See HQ Chat WebSocket.

Speech errors use the structured error shape:

For GET /speech/config and PATCH /speech/config, this configuration error identifies a problem with speech.json. Repair the file or its permissions before you retry. See Configuration recovery.

GET /speech/configCopy Anchor Link

Returns the current speech configuration and the status of each provider.

{
  "config": {
    "stt": { "provider": "openrouter", "model": "openai/whisper-large-v3" },
    "tts": { "provider": "openrouter", "model": "minimax/speech-2.8-turbo", "voice": "English_expressive_narrator" },
    "realtime": { "provider": null }
  },
  "providers": [
    {
      "id": "openrouter",
      "capabilities": { "transcription": true, "speech": true, "realtime": false },
      "available": true
    },
    {
      "id": "realtime",
      "capabilities": { "transcription": false, "speech": false, "realtime": true },
      "available": false,
      "reason": "no_provider_offers_realtime"
    }
  ]
}

A provider that is not available has a reason: no_credential or no_provider_offers_realtime. By default, stt.language is the language of the HQ computer, for example en. It is absent after you set it to null (automatic detection). tts.speed is present only when you set it.

PATCH /speech/configCopy Anchor Link

Merges a partial configuration, saves it, and returns the same shape as GET /speech/config. Keys that you omit keep their current values. For an unknown key in the body, the route returns 400.

curl -X PATCH http://127.0.0.1:9300/speech/config \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stt": {"language": null}}'

If the declared Content-Length is more than 64 KiB, the route returns 413 too_large. It does not read the body.

GET /speech/modelsCopy Anchor Link

Lists the models of one kind that the configured provider has.

{
  "models": [
    { "id": "minimax/speech-2.8-turbo", "name": "MiniMax Speech 2.8 Turbo", "kind": "speech", "voices": ["English_expressive_narrator"] }
  ]
}

POST /speech/transcriptionsCopy Anchor Link

Transcribes one recorded clip. Send the audio inline as base64 in JSON. The route does not accept multipart data.

curl -X POST http://127.0.0.1:9300/speech/transcriptions \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audio": "<base64>", "format": "m4a"}'

{ "text": "Hello from dashsquad.", "durationSeconds": 1.8 }

durationSeconds is present only when the provider gives it. If the declared Content-Length is more than 12 MiB, the route returns 413 too_large. It does not read the body.

POST /speech/speechCopy Anchor Link

Makes speech from text. Send {"text": "..."} with 1 to 4,000 characters.

curl -X POST http://127.0.0.1:9300/speech/speech \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from dashsquad."}' \
  --output reply.mp3

The success body is audio, not JSON. The HQ streams it as audio/mpeg. A model that gives only PCM audio, for example Google Gemini TTS, returns a full audio/wav file. An error before the first audio chunk is still JSON. Thus, accept audio/mpeg, audio/wav and application/json. If the declared Content-Length is more than 64 KiB, the route returns 413 too_large.

Message routingCopy Anchor Link

Configure the automatic Steer and Follow Up routing. When a user sends a message during an active turn, a small classifier model decides how the HQ uses the message. Both routes are loopback only and use the structured error shape.

If the HQ cannot safely read or preserve message-routing.json, these routes return 500 configuration_unavailable with retryable: false. Repair the file or its permissions before you retry. See Configuration recovery.

GET /message-routing/configCopy Anchor Link

Returns the saved settings and the mode that the HQ uses now.

{
  "config": {
    "mode": "auto",
    "model": "typesafe/jev-1.13",
    "steerMinConfidence": 0.8,
    "followUpMinConfidence": 0.5,
    "timeoutMs": 1500
  },
  "effectiveMode": "auto"
}

PATCH /message-routing/configCopy Anchor Link

Merges fields into the settings, saves them, and returns the same shape as GET /message-routing/config.

curl -X PATCH http://127.0.0.1:9300/message-routing/config \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "ask"}'

For invalid JSON, a body that is not an object, an unknown key or an incorrect value, the route returns 400 validation_failed.

MCP serversCopy Anchor Link

Connect Model Context Protocol servers. Agents can then use the tools of these servers. All routes here are loopback only and use the plain error shape. The name of a server tool is <server>__<tool>. To give an agent a server, add the server name to the mcpServers list of the agent.

MCP server objectCopy Anchor Link

{
  "name": "github",
  "transport": { "type": "streamable-http", "url": "https://mcp.example.com/github" },
  "status": "connected",
  "tools": ["github__search_issues", "github__create_issue"]
}

transport is one of these:

status is connected, disconnected, reconnecting, error, needs_reauth or awaiting_authorization.

While authorization is pending, authUrl contains the browser authorization link. An optional error field gives the authorization failure message. The tools are available after the status becomes connected.

GET /runtime/mcp/serversCopy Anchor Link

Lists all saved MCP servers as an array of MCP server objects.

POST /runtime/mcp/serversCopy Anchor Link

Saves and connects a new MCP server. A connected server returns HTTP 201. If browser authorization is necessary, the route returns HTTP 202 with status, authUrl and serverName.

curl -X POST http://127.0.0.1:9300/runtime/mcp/servers \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "files", "transport": {"type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}}'

{ "status": "connected", "serverName": "files", "tools": ["files__read_file", "files__list_directory"] }

For HTTP 202, open authUrl on the computer that runs the HQ. Complete sign-in within five minutes. Poll GET /runtime/mcp/servers/:name for the result.

{ "status": "awaiting_authorization", "authUrl": "https://auth.example.com/authorize", "serverName": "files" }

GET /runtime/mcp/servers/:nameCopy Anchor Link

Returns one MCP server object.

DELETE /runtime/mcp/servers/:nameCopy Anchor Link

Disconnects and removes a server. The HQ also removes the server from the mcpServers list of each agent. It also clears the saved OAuth tokens and registration for that connector. If the connector asks you to sign in after you add it again, complete that sign-in. Returns {"ok": true}.

While removal is in progress, a second removal, add, reconnect or reauthorization for the same name can return HTTP 409. Wait for removal to finish before you add a replacement.

POST /runtime/mcp/servers/:name/reconnectCopy Anchor Link

Disconnects a saved server and connects it again.

{ "ok": true, "status": "connected", "serverName": "files" }

If browser authorization is necessary, returns HTTP 202 with status: "awaiting_authorization", authUrl and serverName. Poll the server object for the result.

POST /runtime/mcp/servers/:name/reauthorizeCopy Anchor Link

Starts authorization again for a server with the status needs_reauth. If browser authorization is necessary, returns HTTP 202 with status: "awaiting_authorization", authUrl and serverName. Otherwise, returns {"ok": true, "status": "...", "serverName": "..."}. Poll the server object for the result.

For an unknown server, the route returns 404. For a server in a different state, it returns 500. A server whose removal is in progress returns 409.

POST /runtime/mcp/servers/:name/cancel-authorizationCopy Anchor Link

Cancels a pending HQ authorization request and closes its callback listener. Returns {"ok": true, "status": "needs_reauth"}. The saved connector configuration remains. Use the reauthorize route to start a new request.

For an unknown server, returns 404. If no authorization is pending, or removal is in progress, returns 409. Closing the Desktop dialog does not call this route.

GET /runtime/mcp/allowlistCopy Anchor Link

Returns the URL patterns that remote MCP servers must match, as an array of strings. If the list is empty, the HQ accepts all URLs. The HQ does not check stdio servers.

PUT /runtime/mcp/allowlistCopy Anchor Link

Replaces the allowlist. Send a JSON array of strings. In a pattern, * matches a sequence of any characters.

curl -X PUT http://127.0.0.1:9300/runtime/mcp/allowlist \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["https://mcp.example.com/*"]'

{ "ok": true, "count": 1 }

PluginsCopy Anchor Link

Install and manage plugins. See Plugins. All routes here are loopback only and use the plain error shape. The HQ saves each change first. Then it loads all plugins again to apply the change.

GET /pluginsCopy Anchor Link

Lists all plugins in name order. The list includes disabled plugins and plugins that failed.

{
  "records": [
    {
      "name": "demo",
      "displayName": "Demo",
      "version": "1.0.0",
      "description": "A demo plugin",
      "status": "loaded",
      "dir": "/Users/you/.dash/gateway/plugins/demo",
      "skillDirs": ["/Users/you/.dash/gateway/plugins/demo/skills"],
      "activated": ["skills"],
      "noop": ["bin", "mcp"]
    }
  ]
}

status is loaded, disabled or error. activated lists the component kinds that the HQ uses. noop lists the kinds that are present but not active, for example the code components of a plugin that you do not trust. A built-in plugin has builtin: true. A plugin that failed has failure with phase (discovery, manifest or route), error and failedAt.

POST /plugins/installCopy Anchor Link

Gets, scans and installs a plugin, then loads all plugins again. The HQ enables the plugin but does not trust it. Its code components stay off until you trust it with PUT /plugins/:name.

curl -X POST http://127.0.0.1:9300/plugins/install \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source": "git:owner/repo"}'

Returns HTTP 201:

{
  "name": "demo",
  "version": "1.0.0",
  "description": "A demo plugin",
  "location": "/Users/you/.dash/gateway/plugins/demo",
  "scanVerdict": "safe",
  "scanReasons": [],
  "source": "git:owner/repo"
}

If the install succeeds but the reload fails, the plugin stays installed. The HQ returns HTTP 200 with {"ok": true, "installed": {...}, "note": "...", "error": "..."}. The next reload loads the plugin.

PUT /plugins/:nameCopy Anchor Link

Enables, disables, trusts or untrusts a plugin. Then the HQ loads all plugins again and returns the updated record.

curl -X PUT http://127.0.0.1:9300/plugins/demo \
  -H "Authorization: Bearer $DASH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trusted": true}'

For a field that is not a boolean, the route returns 400. For an unknown plugin, it returns 404. If the reload fails, or the plugin is missing after the reload, the route returns 409 with error, plugin and note. In that case, the HQ saved the setting, but the active plugins did not change.

DELETE /plugins/:nameCopy Anchor Link

Removes the saved settings of a plugin. If you installed the plugin through this API, the HQ also deletes its directory. Then the HQ loads all plugins again.

{ "ok": true, "path": "/Users/you/.dash/gateway/plugins/demo" }

path is present only when the HQ deleted a directory. For a built-in plugin, the route returns 400. Disable a built-in plugin instead. For an unknown plugin, the route returns 404. If the reload fails after the removal, the route returns 409 with ok: true, removed: true, error and note. The removal is complete.

POST /plugins/reloadCopy Anchor Link

Finds all plugins again. This route does not change settings.

{ "ok": true, "reloadedAt": "2026-07-12T00:00:00.000Z" }

If the reload fails, the route returns 500 with {"error": "..."}.

GET /runtime/pluginsCopy Anchor Link

Returns a short view for the model and credential pickers. It lists the providers that plugins add, and all plugins that are not disabled.

{
  "providers": [
    { "id": "myllm", "label": "MyLLM", "credentialPrefix": "myllm-api-key", "pluginName": "myllm-provider", "ui": {} }
  ],
  "plugins": [{ "name": "demo", "displayName": "Demo", "version": "1.0.0" }]
}

EventsCopy Anchor Link

GET /eventsCopy Anchor Link

Streams HQ changes as server-sent events. Also under /mobile/v1, with the same events. Clients use the stream to know when to get cached data again.

curl -N http://127.0.0.1:9300/events \
  -H "Authorization: Bearer $DASH_TOKEN"

The name of each event is its type. Its data is the JSON event:

event: agent:config-changed
data: {"type":"agent:config-changed","agent":"assistant","fields":["model"]}

: keepalive

The HQ sends a : keepalive comment each 30 seconds.

Ignore event types that you do not know.

GET /agents/:agentId/conversations/:conversationId/eventsCopy Anchor Link

Replays the durable chat events of a conversation after a sequence number. Thus, a client can get the events that it lost when its WebSocket disconnected. It does not have to send the prompt again. Also under /mobile/v1. Errors use the structured shape.

{
  "entries": [
    {
      "seq": 42,
      "msgId": "00000000-0000-4000-8000-000000000002",
      "agentId": "3f9c2a1b",
      "conversationId": "018f0f4a-...",
      "timestamp": "2026-07-12T00:00:00.000Z",
      "payload": { "type": "event", "event": { "type": "text_delta", "text": "Hi" } }
    }
  ]
}

For a deleted conversation, the route returns {"entries": []}. For a query parameter other than one sinceSeq, it returns 400 validation_failed. For an unknown agent, it returns 404 not_found. It also returns 404 not_found for a conversation of a different agent. See HQ Chat WebSocket for the event payloads and for how to resume a turn.

Conversations and chatCopy Anchor Link

Other pages document conversations, messages and chat:

• HQ Mobile API documents the conversation lists, messages, titles, deletion, archive and restore, and POST /mobile/v1/ws-ticket.
• HQ Chat WebSocket documents /ws/chat. This includes messages, runs, answers, cancel, voice mode and the browser live view.

This listener also serves these conversation routes with the management bearer. They use the same handlers as the mobile routes:

On this listener, archive and restore return the management form of the conversation. It has pendingCount and pendingScheduling (running or paused) in place of pendingFollowUpCount and queuePaused.

Conversation decisionsCopy Anchor Link

These routes are loopback only. Send the management bearer. They are not mobile routes. They expose the latest recorded question card for one conversation. They do not add a decision screen to Desktop, the web app or the mobile apps.

GET /agents/:agentId/conversations/:conversationId/decisionCopy Anchor Link

Returns { agentId, conversationId, decision }. decision is null if no decision is recorded. A decision has these fields:

The route accepts no query parameters. Read it again before you answer a changed decision.

POST /agents/:agentId/conversations/:conversationId/decision/answerCopy Anchor Link

Send the decision ID and revision from the read response. Use a new commandId for a new command.

{
  "commandId": "answer-01",
  "decisionId": "<decision.id>",
  "expectedRevision": 12,
  "answers": [
    { "question": "Which format?", "selected": ["Markdown"] }
  ]
}

Answer every recorded question once. Copy each question and selected option label exactly. For a single-select question, select at most one option. To give a free-text answer, use other with nonblank text. Each answer needs a selected option or nonblank other text.

The HQ records the answer and submits one Follow Up. A response contains commandId, replayed and decision. Here, decision is the full snapshot with agentId, conversationId and decision. Its continuation state describes the Follow Up; an accepted answer does not mean the work is complete.

Retry an unchanged command with the same commandId to get its recorded result with replayed: true. Do not reuse that ID for a different request. This returns 409 validation_failed.

A stale revision or a decision that is no longer pending returns 409 revision_conflict with details.currentDecision. Read the current decision before you submit a new command. Malformed answer structures return 400 validation_failed. Answers that do not match the recorded questions return 422 validation_failed.

POST /agents/:agentId/conversations/:conversationId/decision/deferCopy Anchor Link

Send commandId, decisionId and expectedRevision, without answers. This records the command receipt but keeps the decision pending. It does not submit a Follow Up. The reply and unchanged-command retry rules are the same as for the answer route.

Both POST routes reject unknown body fields and query parameters. If decision execution is unavailable, they return 503 gateway_offline with retryable: true.

Saved conversation draftsCopy Anchor Link

These read-only routes are loopback only and need the management bearer. They return Markdown drafts saved in a conversation. They do not publish or send a draft. A saved draft does not prove that its source run or task is complete. These routes do not add a draft viewer to the client apps.

GET /agents/:agentId/conversations/:conversationId/artifactsCopy Anchor Link

Returns { artifacts, nextCursor }. Each item contains metadata for the latest version of one draft. The list is ordered by artifactId.

A null cursor means there is no next page. Metadata includes agentId, conversationId, artifactId, version, title, contentType, sha256, byteLength, createdAt and source. contentType is text/markdown. source identifies the runId, segmentTurnId and toolCallId. The list does not include draft content.

GET /agents/:agentId/conversations/:conversationId/artifacts/:artifactIdCopy Anchor Link

Returns the metadata and content for one saved version. Omit the version query parameter to read the latest version. Set version to a positive integer to read an earlier version. A saved version does not change when a later version is saved. An unknown artifact or version returns 404 not_found.

Artifact IDs contain 1–100 letters, digits, underscores or hyphens and start with a letter or digit. Both routes reject unknown query parameters.

There is no draft-write HTTP route. The HQ save_draft tool saves drafts for a restricted agent profile. That profile sets tools to ["save_draft"], with memory and sub-agents disabled. The agent can also ask question cards. A new draft uses expectedVersion: 0; a revision uses the latest saved version.

Draft content must be nonempty UTF-8 text of at most 256 KiB. After an unacknowledged save, read the artifact before you retry.