HQ Mobile API

The Mobile API is the versioned HTTP surface that native and browser clients use to talk to an HQ. All routes are under /mobile/v1. It covers HQ health and identity, agents, conversations and their history, sub-agents, AI provider keys, speech, and a Server-Sent Events stream of cache invalidations. Live chat uses a separate WebSocket. See HQ Chat WebSocket.

Desktop uses the administrative routes on the loopback interface. The Management API page describes them. Those routes use a different bearer, and the relay never forwards them.

OverviewCopy Anchor Link

Listeners and base URLsCopy Anchor Link

Clients reach the HQ through the hosted relay. The relay sends each request through the outbound tunnel of the HQ to the loopback management server. Both paths run the same authentication and return the same bodies.

The HQ has no LAN listener. The HQ ignores the old --lan-port flag and writes a warning to its log.

Pairing payloadCopy Anchor Link

A device pairs with a relay pairing payload, version 2. Desktop shows it as a QR code. The payload carries the relay host, the mobile bearer, and a per-device relay credential:

{
  "v": 2,
  "host": "gateway-01.relay.dash.example",
  "secure": true,
  "mgmtToken": "mobile-test-token",
  "chatToken": "mobile-test-token",
  "relayCredential": "relay-device-credential"
}

The payload can carry other non-secret fields. Clients ignore them.

AuthenticationCopy Anchor Link

All routes need the mobile bearer of the HQ, except GET /mobile/v1/health:

Authorization: Bearer <mobile-token>

• The mobile bearer is the phone-scoped token of the HQ. You set it with the DASHSQUAD_HQ_CHAT_TOKEN environment variable of the HQ. It is different from the management token (DASHSQUAD_HQ_TOKEN).
• The HQ does not start if the two tokens are equal after a trim. In relay mode the HQ also does not start if one of the two tokens is blank.
• The HQ does not accept the management token on /mobile/v1. The HQ does not accept the mobile token on an administrative route.
• The header must be exactly Bearer and then the token. The HQ does not trim the header and does not change its case.
• Desktop writes the bearer into the pairing QR code. Clients that pair through a dashsquad account get it as chatToken from the control plane. See Relay Control Plane API.
• If the HQ has a management token but no mobile token, all mobile routes except /health return 401. If the HQ has no token at all, authentication is off. That is possible only for an HQ without a relay.

A missing or wrong bearer gets this response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

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

Through the relay, also send the per-device relay credential on each request:

curl "https://$GATEWAY_ID.$RELAY_ZONE/mobile/v1/identity" \
  -H "x-dash-relay-credential: $RELAY_CREDENTIAL" \
  -H "Authorization: Bearer $MOBILE_TOKEN"

The relay checks the credential and removes it, so the HQ never sees it. The relay forwards the bearer without a change, and the HQ checks it. If the relay rejects a request, the body is text/plain from the relay, not the JSON envelope. See Relay API.

CORS and browser originsCopy Anchor Link

Cross-origin access is off until the HQ has a web-origin allowlist. The HQ resolves the allowlist when it starts:

If the allowlist is not empty, the HQ applies these CORS rules to /mobile/v1 only:

The HQ answers a preflight OPTIONS request before it checks authentication. Browsers never attach a bearer to a preflight. The relay removes x-dash-relay-credential before the request gets to the HQ. The header is in the list because the browser must get approval for it before it sends the real request.

Error envelopeCopy Anchor Link

Errors use one JSON envelope, MobileApiError:

{
  "code": "validation_failed",
  "error": "Request body contains unknown fields",
  "retryable": false
}

Two rules apply to each request that changes data (each method except GET, HEAD, and OPTIONS):

The three memory routes do not use the envelope. They return a bare { "error": "<message>" } body, with no code and no retryable. Map their errors by HTTP status. See Memory.

Compatibility rulesCopy Anchor Link

• The HQ always sends a nullable field as an explicit JSON null. A missing field and a null field do not have the same meaning. The HQ can omit an optional field, for example deletedAt.
• Cursors are opaque strings. Send them back without a change. Do not get an order from them.
• Agent IDs are opaque strings that are not empty. A user conversation ID is a UUID. A sub-agent conversation ID is sub_ and then a 26-character ULID. All routes that take a conversation ID accept both forms.
• The fixed request bodies (agents, conversations, sub-agent definitions, provider keys, speech configuration) reject unknown fields.
• Ignore unknown agent event types and properties, capability strings, and SSE event names. Do not reject the message that contains them.

Client capabilitiesCopy Anchor Link

Some response shapes are new. Older clients reject keys and values that they do not know. Thus the HQ sends a new shape only to a client that says that it can read it. A client declares its capabilities in one of two places:

• On REST requests (to /mobile/v1 and to the loopback API): the header X-Dashsquad-Capabilities, a comma-separated list. The HQ ignores values that it does not know.
• On the chat WebSocket: capabilities in the hello frame. See HQ Chat WebSocket.

X-Dashsquad-Capabilities: long-horizon-v1, provider-recovery-v1, chat-archive-v1, chat-tools-v1

Send a value only when GET /health lists the same value. An HQ that does not know a value in hello closes the socket with 1002 invalid_frame. A capability changes what the HQ sends to the client. It does not change what the client can do.

cancel-step-v1 and agent-rename-v1 are only on /health. A client does not send them.

Route indexCopy Anchor Link

Paths in this table and in the sections below are relative to /mobile/v1. For example, GET /conversations means GET /mobile/v1/conversations.

HQ health and identityCopy Anchor Link

GET /healthCopy Anchor Link

Returns the HQ's health, the Mobile API version, the contract version, and the runtime capabilities. This is the only unauthenticated route. Call it first to check that the HQ speaks this API.

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

Ignore capability strings that you do not know. A client that rejects an unknown capability fails when the HQ adds one. Some values also need the client to declare them. See Client capabilities.

GET /identityCopy Anchor Link

Returns the HQ's stable identity: its relay gateway ID and its Ed25519 public key.

{
  "gatewayId": "gateway-01",
  "publicKey": "dash-test-public-key"
}

Errors: 401.

AgentsCopy Anchor Link

The agent routes return the stored record of the agent without its provider API keys. A mobile client can create an agent, rename it, and change its model and system prompt. Desktop manages all other settings.

The agent object:

config always has name, model (a provider/model string), and systemPrompt. It can also have these optional blocks:

The HQ never returns providerApiKeys. Only the loopback API sets memory, subagents, skills.learning, and skills.minToolCalls. No API sets location. Show other configuration keys as information only.

The agent routes use the envelope. A 404 is { "code": "not_found", "error": "Agent not found", "retryable": false }. An unexpected failure is 500 with code: "gateway_offline" and retryable: true.

GET /agentsCopy Anchor Link

Lists all registered agents.

[
  {
    "id": "agent-01",
    "name": "Mobile Helper",
    "config": {
      "name": "Mobile Helper",
      "model": "anthropic/claude-sonnet-4-5",
      "systemPrompt": "Help from anywhere.",
      "fallbackModels": ["openai/gpt-5-mini"],
      "tools": ["read_file"],
      "skills": {
        "paths": ["skills/mobile"],
        "urls": ["https://skills.dash.example/mobile.md"]
      },
      "workspace": "/tmp/dash-mobile-helper",
      "maxTokens": 4096,
      "mcpServers": ["linear"],
      "plugins": ["dash-core-providers"],
      "providers": ["anthropic", "openai"],
      "subagents": {
        "enabled": true,
        "maxConcurrent": 2,
        "maxDepth": 1
      }
    },
    "status": "active",
    "registeredAt": "2026-07-12T00:00:00.000Z",
    "effortLevels": ["low", "medium", "high"]
  }
]

Errors: 401.

POST /agentsCopy Anchor Link

Creates an agent. The body accepts exactly these three fields. All three are necessary:

{
  "name": "Mobile Helper",
  "model": "anthropic/claude-sonnet-4-5",
  "systemPrompt": "Help from anywhere."
}

Returns 201 with the new agent object.

GET /agents/:idCopy Anchor Link

Returns one agent object.

Errors: 401, 404.

PUT /agents/:idCopy Anchor Link

Changes an agent. Send one or more of name, model, and systemPrompt. While /health lists long-horizon-v1, the HQ also accepts messaging (send, receive). A switch that you omit keeps its value. The HQ accepts no other field.

{
  "name": "Travel Helper",
  "model": "openai/gpt-5-mini",
  "systemPrompt": "Help concisely from anywhere."
}

Returns 200 with the changed agent object. After a model change, effortLevels shows the levels of the new model.

name renames the agent, and the agent keeps its ID. The HQ removes spaces at the start and end of the name. A name has 1 to 64 characters, no line break and no control character. It must be unique, and the HQ compares names without case. If the HQ refuses the name, it changes no other field.

After a rename, the newest chat of the agent gets an agent_renamed notice, if the agent has a chat.

DELETE /agents/:idCopy Anchor Link

Deletes an agent. The HQ cancels its active work and archives its conversations. Each conversation goes to status: "archived", and the HQ sends a conversation:changed event for it. You can still read an archived conversation. You cannot change it, delete it, or start a new turn in it.

{ "ok": true }

If the delete does not complete, you can send the same request again. When the HQ starts, it also finishes deletes that did not complete.

Errors: 401, 404, 500.

POST /agents/:id/enableCopy Anchor Link

POST /agents/:id/disableCopy Anchor Link

These routes enable or disable an agent. Both take no body and return { "ok": true }.

Errors: 401, 404, 409 (enable of an agent that the HQ is about to delete), 500.

GET /agents/:id/skillsCopy Anchor Link

A read-only list of the skills that the agent can load. The list also contains the skills that the agent learned by itself. A mobile client cannot create, install, edit, or remove skills.

[
  {
    "name": "write-files",
    "description": "Use when writing files in this project",
    "source": "agent",
    "content": "---\nname: write-files\ndescription: Use when writing files in this project\n---\nThese lessons were learned automatically from previous sessions.\n\n## Lessons\n\n- Always use printf instead of echo when writing files.\n"
  },
  {
    "name": "deep-research",
    "description": "Use for multi-source research tasks",
    "trigger": "research",
    "source": "plugin"
  }
]

Errors: 401, 404 (not_found, Agent not found).

MemoryCopy Anchor Link

These routes show the saved memories of an agent. A mobile client can list, read, and delete memories. Only Desktop can write memories and change memory settings.

GET /agents/:id/memoryCopy Anchor Link

Lists the memories of the agent. If the agent has no memory directory, the list is empty.

[
  {
    "name": "user-timezone",
    "description": "Gerry is in Singapore (UTC+8)",
    "type": "user",
    "source": "agent",
    "createdAt": "2026-09-05",
    "updatedAt": "2026-09-05",
    "size": 24
  },
  {
    "name": "repo-pnpm",
    "description": "The repo uses pnpm",
    "type": "project",
    "source": "sweep",
    "createdAt": "2026-09-05",
    "updatedAt": "2026-09-05",
    "size": 18
  }
]

Errors: 401, 404 (unknown agent).

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

Returns one memory. The record has the same fields as a list entry, but it has content (the full text) in place of size.

Errors: 401, 404 (unknown agent or memory).

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

Deletes one memory and returns its name:

{ "name": "user-timezone" }

Sub-agent definitionsCopy Anchor Link

These routes show the sub-agent types that an agent can start, and the definition files that the agent owns. They use the MobileApiError envelope. A missing agent or definition is 404 not_found. The HQ adds these routes only when it has a sub-agent definition registry. Without the registry, they return 404.

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

Returns the full list of sub-agent types that this agent can start. The HQ merges the built-in types, plugin definitions, the definition directory of the agent, and the workspace directories, by precedence. Then it removes the types that are not in subagents.allowedTypes of the agent.

If two definitions have the same name, the definition that lost comes directly after the winner, with shadowedBy set. The list does not contain the full definition text. Get it from the definition route.

Each type has name, description, and source (builtin, workspace, agent, or plugin). It can also have location, tools, disallowedTools, model, skills, maxTurns, background, isolation ("worktree"), and shadowedBy. shadowedBy is the file path of the winner, or its source if it has no file.

Errors: 401, 404.

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

Lists the .md files in the definition directory of the agent, sorted by file name. You can write only this layer. Workspace and plugin definitions are read-only, and only the type list shows them. If the directory does not exist, the list is empty.

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

Errors: 401, 404.

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

Returns the raw Markdown of a definition, byte for byte:

{ "name": "code-reviewer", "raw": "---\nname: code-reviewer\n..." }

:name is the file name without .md. It must match ^[a-z0-9][a-z0-9-]*$.

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

Creates or replaces <name>.md in the definition directory of the agent.

{ "raw": "---\nname: code-reviewer\ndescription: Review a diff\n---\nYou review diffs." }

The HQ parses the body before it writes the file. The frontmatter name must be equal to :name. If the write is successful, the HQ refreshes the type list of the agent and returns:

{ "ok": true, "name": "code-reviewer" }

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

Deletes the definition file and refreshes the type list. Returns { "ok": true, "name": "<name>" }.

Errors: 400 (bad :name), 401, 404 (no such agent or definition).

ModelsCopy Anchor Link

GET /modelsCopy Anchor Link

Lists the models that you can set on an agent. The list comes from the model cache of the HQ. When the cache is old, the HQ gets a new list from the providers.

{
  "models": [
    {
      "value": "anthropic/claude-sonnet-4-5",
      "label": "Claude Sonnet 4.5",
      "provider": "anthropic"
    },
    {
      "value": "openai/gpt-5-mini",
      "label": "GPT-5 mini",
      "provider": "openai"
    }
  ],
  "source": "live",
  "errors": {},
  "fetchedAt": "2026-07-12T00:00:00.000Z",
  "supportedModelsReviewedAt": "2026-07-05"
}

This route takes no query parameters. A query string returns 400 validation_failed (Unknown models query parameter).

Errors: 400, 401.

ConversationsCopy Anchor Link

A conversation belongs to one agent. The HQ stores its metadata, its messages, and an append-only event log, and every paired client sees the same state. Live turns stream over HQ Chat WebSocket. These routes read and manage the stored state.

The conversation objectCopy Anchor Link

{
  "id": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
  "agentId": "agent-01",
  "agentName": "Mobile Helper",
  "title": "Mobile launch check",
  "revision": 2,
  "status": "idle",
  "activeTurnId": null,
  "lastSeq": 7,
  "lastMessagePreview": "Ready from the gateway.",
  "createdAt": "2026-07-12T00:00:00.000Z",
  "updatedAt": "2026-07-12T00:00:05.000Z",
  "kind": "user",
  "queuePaused": false,
  "queueRevision": 0,
  "pendingFollowUpCount": 0,
  "effort": null
}

A client compares title against New Conversation to tell whether a conversation is still untitled.

ETag and If-MatchCopy Anchor Link

POST, GET, PATCH, and DELETE on a single conversation return its revision as a quoted ETag:

ETag: "2"

PATCH and DELETE require an If-Match header with the revision you last saw, in the same quoted form. The header must match ^"(0|[1-9][0-9]*)"$. A missing or malformed header is 400 validation_failed. If the revision is stale, the HQ returns 409 revision_conflict with the current conversation in details.current, so you can merge and retry without another read:

{
  "code": "revision_conflict",
  "error": "Conversation revision 1 is stale",
  "retryable": false,
  "details": {
    "current": {
      "id": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
      "agentId": "agent-01",
      "agentName": "Mobile Helper",
      "title": "Mobile launch check",
      "revision": 2,
      "status": "idle",
      "activeTurnId": null,
      "lastMessagePreview": "Ready from the gateway.",
      "createdAt": "2026-07-12T00:00:00.000Z",
      "updatedAt": "2026-07-12T00:00:05.000Z",
      "kind": "user",
      "queuePaused": false,
      "queueRevision": 0,
      "pendingFollowUpCount": 0,
      "lastSeq": 7,
      "effort": null
    }
  }
}

Delete and archiveCopy Anchor Link

When you delete a conversation, the HQ removes its messages, event log, pending inputs, and queued notifications. The HQ keeps the row as a tombstone with status: "deleted", a new revision, and deletedAt. The HQ also makes a tombstone of each sub-agent conversation below it, even an active one.

GET /conversations/:id still returns the tombstone. A new PATCH or DELETE returns 410 with code not_found and retryable: false.

The HQ archives a conversation in two cases: when you archive it with POST /conversations/:id/archive, and when you delete its agent. The conversation goes to status: "archived", and you can still read it. PATCH and DELETE return 409 validation_failed, and the HQ refuses new turns. The list routes still return archived conversations, with status and archivedAt. A routine run never posts into an archived conversation.

To tell the two cases apart, read archivedAt. It is set only when the user archived the conversation. You can restore only such a conversation.

POST /conversations/:id/archiveCopy Anchor Link

Archives one conversation. Needs chat-archive-v1 in /health. Takes no body and no If-Match. Returns 200 with the conversation object: status: "archived" and archivedAt set. The HQ sends conversation:changed on /events when the conversation changes.

The route is idempotent. If the user archived the conversation before, the HQ returns it again.

POST /conversations/:id/restoreCopy Anchor Link

Restores a conversation that the user archived. Needs chat-archive-v1 in /health. Takes no body. Returns 200 with the conversation object and archivedAt: null. The HQ sends conversation:changed when the conversation changes.

The route is idempotent. A conversation that is not archived comes back with no change.

Query parameter rulesCopy Anchor Link

Three read routes have strict query rules: GET /conversations, /messages, and /bootstrap. Each of them returns 400 validation_failed for these errors:

• A query parameter that the route does not define
• A parameter that is in the query more than one time
• An empty value
• A limit that is not a positive integer, or that is more than the maximum of the route

A cursor that the HQ cannot decode is 400 Invalid pagination cursor.

GET /conversationsCopy Anchor Link

Lists conversations, most recently updated first. Deleted conversations and sub-agent conversations are left out. Archived conversations are included.

{
  "items": [
    {
      "id": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
      "agentId": "agent-01",
      "agentName": "Mobile Helper",
      "title": "Mobile launch check",
      "revision": 2,
      "status": "idle",
      "activeTurnId": null,
      "lastMessagePreview": "Ready from the gateway.",
      "createdAt": "2026-07-12T00:00:00.000Z",
      "updatedAt": "2026-07-12T00:00:05.000Z",
      "kind": "user",
      "queuePaused": false,
      "queueRevision": 0,
      "pendingFollowUpCount": 0,
      "lastSeq": 7,
      "effort": null
    }
  ],
  "nextCursor": "opaque:conversation:cursor:1"
}

nextCursor is null on the last page.

Errors: 400, 401.

POST /conversationsCopy Anchor Link

Creates a conversation. requestId makes the call idempotent. If you send a request again with the same requestId, the HQ returns the conversation that the first request made. It does not make a new one.

{
  "agentId": "agent-01",
  "requestId": "request-01",
  "title": "Mobile launch check"
}

Every string must not be blank. The HQ trims each string. The route returns 201 with the conversation object and its ETag. It also returns 201 when an earlier request with the same requestId made the conversation. A conversation:changed event is sent on /events.

GET /conversations/:idCopy Anchor Link

Returns the conversation object and its ETag. Deleted conversations are returned as tombstones. Sub-agent conversations can be read here by their sub_ ID.

Errors: 401, 404.

PATCH /conversations/:idCopy Anchor Link

Updates the title or the effort. Requires If-Match. Send one key or both.

{
  "title": "Mobile launch verified",
  "effort": "high"
}

Returns the updated conversation and its new ETag, and sends conversation:changed. You can change the effort while a turn runs. The turn in progress keeps its level.

DELETE /conversations/:idCopy Anchor Link

Deletes the conversation's content and returns the tombstone with its new ETag. Requires If-Match. Sends conversation:deleted on /events.

The tombstone is the conversation object with status: "deleted", activeTurnId: null, a revision one higher than before, and deletedAt set.

The HQ checks these conditions in order and returns the first that applies:

A 401 is returned before any of these when the bearer is wrong.

GET /conversations/:id/messagesCopy Anchor Link

Pages through the stored messages of the conversation. The first page has the newest messages. The items in a page are in time order, from the lowest ordinal to the highest. Pass nextCursor as before to get the page of older messages.

{
  "items": [
    {
      "id": "018f0f4a-5c42-7a8b-9c01-3234567890ab",
      "conversationId": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
      "turnId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "ordinal": 1,
      "role": "user",
      "status": "completed",
      "content": {
        "type": "user",
        "text": "Is the mobile connection ready?"
      },
      "createdAt": "2026-07-12T00:00:01.000Z",
      "updatedAt": "2026-07-12T00:00:01.000Z",
      "runId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "segmentIndex": 0,
      "deliveryKind": "normal",
      "origin": "user"
    },
    {
      "id": "018f0f4a-5c42-7a8b-9c01-4234567890ab",
      "conversationId": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
      "turnId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "ordinal": 2,
      "role": "assistant",
      "status": "completed",
      "content": {
        "type": "assistant",
        "events": [
          {
            "type": "text_delta",
            "text": "Ready from the gateway."
          }
        ]
      },
      "createdAt": "2026-07-12T00:00:02.000Z",
      "updatedAt": "2026-07-12T00:00:05.000Z",
      "runId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "segmentIndex": 0,
      "deliveryKind": "normal",
      "origin": "user"
    }
  ],
  "nextCursor": null,
  "throughSeq": 5
}

Status rules for a client:

• A user row shows the delivery of its prompt, not the result of the run. When the run ends, each delivered user row of the run changes from accepted to completed, also when the run fails or is cancelled.
• The assistant row of the run shows the result of the run: completed, cancelled, failed, or interrupted.
• If the HQ does not deliver a Steer message, its user row changes to failed, with deliveryStatus: "not_delivered".

Message origins:

Only user is the person. No other origin answers a question card or runs a command. Show a message with an origin that you do not know as a system row, not as a user message.

Message content:

Notice kinds:

Errors: 400, 401, 404. A deleted conversation returns 404 here.

GET /conversations/:id/bootstrapCopy Anchor Link

Returns all the data that a client needs to open a conversation. The HQ reads it in one transaction. The data is the conversation, a page of messages, the queued inputs, and the replay position. Takes the same query parameters as /messages.

{
  "conversation": {
    "id": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
    "agentId": "agent-01",
    "agentName": "Mobile Helper",
    "title": "Mobile launch check",
    "revision": 3,
    "status": "running",
    "activeTurnId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
    "lastMessagePreview": "Ready from the gateway.",
    "createdAt": "2026-07-12T00:00:00.000Z",
    "updatedAt": "2026-07-12T00:00:05.000Z",
    "kind": "user",
    "queuePaused": false,
    "queueRevision": 4,
    "pendingFollowUpCount": 1,
    "lastSeq": 7,
    "effort": "high"
  },
  "messages": [],
  "nextCursor": null,
  "pendingInputs": [
    {
      "inputId": "818f0f4a-5c42-7a8b-9c01-1234567890ab",
      "kind": "follow_up",
      "text": "Also compare the migration cost.",
      "state": "queued",
      "revision": 1,
      "enqueueOrder": 1,
      "createdAt": "2026-09-15T05:00:00.000Z",
      "updatedAt": "2026-09-15T05:00:00.000Z"
    }
  ],
  "queuePaused": false,
  "queueRevision": 4,
  "throughSeq": 7
}

Inputs are added, edited, and removed with chat commands on the WebSocket. See HQ Chat WebSocket.

Errors: 400, 401, 404.

Sub-agentsCopy Anchor Link

A sub-agent is a child agent that the agent of a conversation starts. Each child has its own conversation, with kind: "subagent" and an ID of the form sub_<ulid>. The routes below use that ID as the sub-agent ID. These routes use the MobileApiError envelope. The HQ adds them only when it runs the sub-agent coordinator. Without it, they return 404.

The subagent field of a sub-agent conversation describes the child:

{
  "type": "code-reviewer",
  "name": "reviewer",
  "status": "running",
  "description": "Review the diff",
  "prompt": "Review the diff and report findings",
  "model": "anthropic/claude-opus-4",
  "background": true,
  "isolation": "worktree",
  "depth": 1,
  "startedAt": "2026-07-12T00:01:00.000Z",
  "usage": {
    "inputTokens": 1204,
    "outputTokens": 318
  },
  "toolCallCount": 7,
  "oneShot": false
}

status is one of running, waiting_input, done, failed, cancelled, interrupted, or max_turns. The last five are terminal. After the HQ starts again, it sets each child that did not finish to interrupted. The object can also have endedAt, report, and workspace. workspace is the directory where the child ran.

GET /conversations/:id/subagentsCopy Anchor Link

Lists the sub-agents of a conversation, oldest first. Each entry has the data for a tasks panel, so you do not have to open each child. The HQ scans report before it sends it, because clients show it directly. The scan makes control tags safe and escapes role prefixes.

{
  "subagents": [
    {
      "id": "sub_01JQ8Z3K7M2N4P6R8T0V2W4X6Y",
      "name": "scout",
      "type": "Explore",
      "description": "Survey the repo",
      "status": "done",
      "background": false,
      "depth": 1,
      "startedAt": "2026-09-06T09:00:00.000Z",
      "endedAt": "2026-09-06T09:02:31.000Z",
      "usage": { "inputTokens": 4821, "outputTokens": 903 },
      "toolCallCount": 12,
      "report": "The auth flow lives in apps/hq/src/auth.ts.",
      "oneShot": true
    },
    {
      "id": "sub_01JQ8Z3K7M2N4P6R8T0V2W4X71",
      "name": "reviewer",
      "type": "general-purpose",
      "description": "Review the diff",
      "status": "running",
      "background": true,
      "depth": 2,
      "startedAt": "2026-09-06T09:05:00.000Z",
      "toolCallCount": 0,
      "oneShot": false
    }
  ]
}

The list does not contain prompt, model, isolation, or workspace. To get them, read the child conversation. The route returns a maximum of the 100 newest children.

Errors: 401, 404 (no such conversation).

POST /subagents/:id/stopCopy Anchor Link

Cancels the sub-agent and each descendant below it. The HQ stops the deepest children first. Takes no body.

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

status is the terminal status of the child after the stop. It is not always cancelled, because the child can finish by itself during the stop.

POST /subagents/:id/resumeCopy Anchor Link

Sends a message to the sub-agent from its parent. This has the same effect as the send_message tool of the agent. An active child puts the message in its queue as its next turn. If the child finished, the HQ resumes it on its own conversation. This also applies to a child that an HQ restart interrupted.

{ "message": "Also check the migrations.", "requestId": "req-42" }

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

The requestId here is not the idempotency key of POST /conversations. The HQ does not store it, and it does not prevent duplicates. If you send the same request again, the HQ starts a second turn.

Replay and eventsCopy Anchor Link

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

Returns the conversation's replayable chat frames with seq greater than sinceSeq, in order. Use it to catch up after the chat connection stops. Start from the last seq that you applied, or from throughSeq on a bootstrap.

{
  "frames": [
    {
      "type": "accepted",
      "id": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "conversationId": "018f0f4a-5c42-7a8b-9c01-1234567890ab",
      "runId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "segmentTurnId": "018f0f4a-5c42-7a8b-9c01-2234567890ab",
      "seq": 6,
      "userMessageId": "018f0f4a-5c42-7a8b-9c01-3234567890ab",
      "assistantMessageId": "018f0f4a-5c42-7a8b-9c01-4234567890ab",
      "revision": 2
    }
  ],
  "throughSeq": 7
}

Each frame has the same shape as a sequenced frame on the chat WebSocket. The frames are accepted, event, done, error, input_accepted, input_updated, input_removed, input_delivered, input_failed, queue_paused, or queue_resumed. See HQ Chat WebSocket. Replayed accepted frames leave out origin, kind, and requestId. Read the durable origin and kind from the message and the conversation instead.

GET /eventsCopy Anchor Link

A Server-Sent Events stream that tells clients when to refresh. Keep it open and re-read a conversation when its revision is newer than the one you hold.

GET /mobile/v1/events HTTP/1.1
Authorization: Bearer <mobile-token>
Accept: text/event-stream

The response has Content-Type: text/event-stream and Cache-Control: no-cache. Each event has an event: name equal to the payload's type, and a JSON data: line:

event: conversation:changed
data: {"type":"conversation:changed","conversationId":"018f0f4a-5c42-7a8b-9c01-1234567890ab","revision":2}

event: conversation:deleted
data: {"type":"conversation:deleted","conversationId":"018f0f4a-5c42-7a8b-9c01-1234567890ab","revision":3}

The same stream also has the other change events of the HQ, for example agent, channel, plugin, and swarm changes. Ignore each event name that you do not use.

The HQ sends a : keepalive comment line each 30 seconds. Events have no id: field, so you cannot resume the stream with Last-Event-ID. After you connect again, get the conversation list again and compare revisions.

Through the relay, an open stream counts against the HQ's concurrent-stream cap. See Relay API.

Errors: 401.

AI providersCopy Anchor Link

These routes let a phone or the web app manage the AI provider keys of the HQ. Before you call them, look for the providers-v1 capability in GET /health.

The routes are the relay-reachable form of the /credentials routes that only Desktop uses, limited to provider API keys. They use the same credential slots, so Desktop shows a key that you write here.

GET /providersCopy Anchor Link

{
  "providers": [
    {
      "id": "anthropic",
      "label": "Anthropic",
      "pluginName": "dash-core-providers",
      "description": "Claude models from Anthropic.",
      "keyPlaceholder": "sk-ant-...",
      "keyConsoleUrl": "https://console.anthropic.com/settings/keys",
      "docsUrl": "https://docs.anthropic.com",
      "keys": [
        {
          "name": "claude-login",
          "kind": "oauth",
          "addedAt": "2026-09-26T03:00:00.000Z",
          "account": { "email": "user@example.com", "plan": null }
        },
        {
          "name": "default",
          "kind": "api_key",
          "addedAt": "2026-09-20T08:30:00.000Z",
          "account": null
        }
      ],
      "signIn": { "kind": "code", "label": "Sign in with Claude" }
    }
  ]
}

KeysCopy Anchor Link

curl -i -X PUT "$MOBILE_URL/mobile/v1/providers/anthropic/keys/default" \
  -H "Authorization: Bearer $MOBILE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"sk-ant-..."}'

The HQ trims the value before it checks it. If you replace an OAuth sign-in with a pasted key, the key becomes a plain API key. After each write, the HQ refreshes the model list and the speech status on the next request.

Subscription sign-inCopy Anchor Link

If the signIn field of a provider is not null, the provider also supports a subscription sign-in. The HQ runs the full sign-in. It keeps the PKCE verifier, the state, and the tokens. A sign-in object never contains a token.

{
  "attemptId": "b2d4e6f8-1a3c-4e5f-9b7d-2c4e6a8b0d12",
  "providerId": "openai",
  "keyName": "chatgpt",
  "kind": "device_code",
  "status": "pending",
  "expiresAt": "2026-09-24T12:15:00.000Z",
  "authorizeUrl": null,
  "verificationUrl": "https://auth.openai.com/codex/device",
  "userCode": "ABCD-1234",
  "error": null
}

• A code from a different sign-in, or a code that the provider rejects, gets 400 validation_failed. A rejected code also makes the sign-in fail, because each code works one time only.
• A failed sign-in has the reason in error.
• The HQ keeps sign-ins in memory. A code sign-in expires after 10 minutes. A device_code sign-in expires at the time that the provider sets, or after 15 minutes.
• After a sign-in ends, you can read it for 10 more minutes. After that, it is 404.
• A new sign-in for the same key cancels a pending one.
• If the provider has no sign-in, the sign-in routes return 404 not_found.

If a Claude or ChatGPT sign-in is successful, the HQ stores the key with kind: "oauth" and refreshes it when necessary. An OpenRouter sign-in gives a usual API key. The HQ stores it with kind: "api_key", and the key does not expire.

SpeechCopy Anchor Link

These routes transcribe audio and make speech through the speech provider of the HQ. Before you call them, look for the speech-v1 capability in GET /health. If the HQ has no speech service, it does not add the /speech routes, and they return 404.

The speech routes use the MobileApiError envelope. Provider failures keep their own codes:

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.

Each speech route with a body checks Content-Length before it reads the body. If the length is more than the limit, the route returns 413 too_large (request body too large). The limit is 12 MB for POST /speech/transcriptions. It is 64 KiB for PATCH /speech/config and POST /speech/speech.

GET /speech/configCopy Anchor Link

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

{
  "config": {
    "stt": {
      "provider": "openrouter",
      "model": "openai/whisper-large-v3",
      "language": "en"
    },
    "tts": {
      "provider": "openrouter",
      "model": "minimax/speech-2.8-turbo",
      "voice": "English_expressive_narrator",
      "speed": 1
    },
    "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"
    }
  ]
}

Errors: 401, 500 configuration_unavailable.

PATCH /speech/configCopy Anchor Link

Merges a part of the configuration and returns the result in the same shape as GET /speech/config. The merge is shallow for each section. A key that you do not send keeps its current value.

{
  "stt": {
    "model": "openai/whisper-large-v3",
    "language": "en"
  },
  "tts": {
    "voice": "nova",
    "speed": 1.25
  },
  "realtime": {
    "provider": null
  }
}

• stt accepts provider, model, and language. To go back to the language detection of the provider, set language to null: { "stt": { "language": null } }.
• tts accepts provider, model, voice, and speed.
• If you send realtime, it must contain provider, which can be null. A realtime object without provider is a 400.
• An unknown key at any level is a 400. The HQ does not ignore it.

Errors: 400, 401, 413, 500 configuration_unavailable.

GET /speech/modelsCopy Anchor Link

Lists the models of the configured provider for one kind of speech. The HQ keeps the results in a cache for one hour for each provider.

{
  "models": [
    {
      "id": "openai/whisper-large-v3",
      "name": "Whisper Large v3",
      "kind": "transcription"
    },
    {
      "id": "minimax/speech-2.8-turbo",
      "name": "MiniMax: Speech 2.8 Turbo",
      "kind": "speech",
      "voices": ["English_expressive_narrator", "English_radiant_girl"]
    }
  ]
}

voices is present only on speech models that have named voices.

Errors: 400, 401, 502, 503.

POST /speech/transcriptionsCopy Anchor Link

Transcribes one recorded clip. Send the audio as base64 in JSON, not as multipart.

{
  "audio": "UklGRiwAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQgAAAAAAAAAAAAAAA==",
  "format": "wav",
  "language": "en"
}

The provider also limits the clip to 60 seconds.

{
  "text": "Ship the speech routes.",
  "durationSeconds": 2.5
}

durationSeconds is present only when the provider reports it.

Errors: 400, 401, 413, 502, 503.

POST /speech/speechCopy Anchor Link

Makes speech from text. This is the only Mobile API route with a success body that is not JSON.

{ "text": "Ship the speech routes." }

Send Accept: audio/mpeg, audio/wav. The response is one of these:

• Content-Type: audio/mpeg. The HQ streams the audio as the provider makes it.
• Content-Type: audio/wav, sent as one body, when the configured model makes only raw PCM.

If an error occurs before the first audio chunk, the HQ returns a JSON MobileApiError. Be ready to decode JSON on this route too.

Errors: 400, 401, 413, 502, 503.

Long-horizon workCopy Anchor Link

These routes serve squad messages between agents, goals, routines, wake-ups, the daily limit of unattended work, and the Needs you list. They exist only while /health lists long-horizon-v1. Without it, each route returns 404 not_found, and a client hides these surfaces. With it, a 404 means that the agent, goal, routine, or thread does not exist.

The same routes are on the loopback API with the management bearer. All of them use the error envelope. Each schema is closed: the HQ adds a new response key only with a new capability. Treat an unknown value of pausedReason, endedReason, verifiedBy, or waitingReason like a missing key.

GET /agents/:id/autonomyCopy Anchor Link

Returns the daily limit and today's unattended usage of an agent. Unattended work is work that the user did not start: goal iterations, routine runs, wake-ups, and squad messages. A turn that the user starts is never blocked.

{
  "dailyLimitUsd": 5,
  "dailyLimitTokens": 3000000,
  "day": "2026-11-01",
  "usage": { "usdEstimate": 1.25, "tokens": 420000, "noCostTokens": 0, "turns": 6 },
  "limitReached": false,
  "resetsAt": "2026-11-01T16:00:00.000Z"
}

Errors: 401, 404.

PATCH /agents/:id/autonomyCopy Anchor Link

Changes the limits. Send dailyLimitUsd (a number, 0 or more), dailyLimitTokens (an integer, 0 or more), or both. Returns the same body as GET.

Errors: 400 (invalid JSON, an empty object, an unknown field, or a value that is not valid), 401, 404.

GoalsCopy Anchor Link

A goal makes the agent continue to work in one conversation until the goal is complete, or until it stops at a limit. Each conversation has at most one goal that is not finished.

The goal record has these main fields:

A user goal has these default limits: 20 iterations, 2 hours, and 400 provider requests. The record also has evidence, lastEvaluation, scopeRevision, currentTurnId, pursuingDurationMs, and times. See GoalRecord in the contract for these fields.

A goal command has this body:

{
  "agentId": "agent-01",
  "requestId": "goal-command-01",
  "goalId": null,
  "expectedControlRevision": null,
  "operation": { "type": "create", "objective": "Ship the release notes" }
}

For each operation except create, send the goalId and the controlRevision that you saw. requestId is unique in the conversation. If you send the same requestId and operation again, the HQ returns the first result with outcome: "replayed". outcome is applied, unchanged, or replayed.

A refused command has code: "validation_failed" and details.reason. details.snapshot can hold the current goal, so you can refresh without another read.

A goal change also sends conversation:changed on /events.

Routines and wake-upsCopy Anchor Link

A routine is a scheduled task of an agent. A wake-up (purpose: "wake") is a one-time run that an agent sets for itself, in its own chat. Only agents create wake-ups.

The create body has title (1 to 80 characters), instructions (1 to 8192 characters), and schedule. Optional fields are destination (main_chat or new_chat_each_run) and notify (always or with_updates). PATCH accepts the same fields, all optional, and state (active or paused).

The routine object has id, agentId, purpose, title, instructions, schedule, destination, notify, and createdBy. It also has state, expiresAt, nextRunAt, lastRun, runCount, missedCount, createdAt, and updatedAt. A wake-up has destination: "conversation" and a conversationId.

A run has id, routineId, scheduledFor, startedAt, finishedAt, status, optional conversationId, summary (the first 280 characters of the reply), tokens, and usdEstimate.

Refusals have code: "validation_failed" and details.reason:

Squad message threadsCopy Anchor Link

Agents send messages to each other in threads.

A thread has id, startedByAgentId, participants, messageCount, maxHop, state, pausedReason, createdAt, and lastMessageAt. Each participant has agentId, agentName, and an optional conversationId. state is open, paused, or closed. pausedReason is message_limit, hop_limit, user, or null. A participant keeps its agentName after the agent is deleted.

A message has id, threadId, fromAgentId, fromAgentName, toAgentId, toAgentName, body, hop, status (delivered, queued, or refused), reason (the refusal code, else null), createdAt, and deliveredAt. fromConversationId is absent when the message came from a messaging-app chat. toConversationId is absent until the message has a chat on the receiver side.

Errors: 401, 404. A pause, resume, or close of a closed thread returns 400 validation_failed, The thread is closed.

GET /needs-youCopy Anchor Link

Returns each item that waits for the user, for all agents, oldest first. The HQ makes the list. Do not build it from other reads.

{
  "items": [
    {
      "id": "limit:agent-01:2026-11-01",
      "kind": "limit",
      "agentId": "agent-01",
      "agentName": "Writer",
      "title": "Writer reached today's limit of USD 5.",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "ref": {}
    }
  ]
}

title is one sentence that the HQ writes. conversationId is absent when the item has no chat. For a kind that you do not know, show the agent, title, and an action to open the chat when conversationId is set. ref is open: ignore keys that you do not know.

Errors: 401, 404.

Chat WebSocketCopy Anchor Link

Live turns, Steer, Follow Up, and voice use the chat WebSocket at /ws/chat, on the relay hostname. HQ Chat WebSocket describes the frame protocol. This section covers only the connection.

The socket uses the same mobile bearer. The HQ checks these items in this order:

1. If the upgrade has an Authorization header that is not empty, the header must be Bearer <mobile-token>. The HQ looks at nothing else.
2. If not, the HQ accepts a ?token=<mobile-token> query parameter or a ?ticket=<ticket> from POST /ws-ticket.

If the check fails, the upgrade completes, and then the HQ closes the socket with code 4001 Unauthorized.

Native clients must send the Authorization header. Browsers cannot set headers on a WebSocket upgrade. A browser gets a ticket over HTTP and puts it in the URL, so the long-lived bearer stays out of URLs and logs. Through the relay, a browser sends the relay credential as a WebSocket subprotocol. See Relay API.

POST /ws-ticketCopy Anchor Link

Makes a single-use ticket for one WebSocket upgrade. Takes no body.

{ "ticket": "0123456789abcdef0123456789abcdef", "expiresAt": "2026-08-29T12:00:30Z" }

Use it immediately:

wss://<gatewayId>.<zone>/ws/chat?ticket=<ticket>

• A ticket works one time. When the HQ redeems it, the HQ removes it, also if it expired.
• The HQ uses the ticket only when the upgrade has no Authorization header. If a header is present, only the header counts, and the HQ does not use the ticket.
• One ticket store serves the full HQ, so a ticket from one namespace works with each socket.

Errors: 401.

Steer and Follow UpCopy Anchor Link

Before a client opens a conversation, it does these steps:

1. Call GET /mobile/v1/health. Make sure that it has contractVersion: 1.
2. Call GET /mobile/v1/identity with the mobile bearer. Make sure that the HQ is the one you paired with.

You can always send behavior: "auto". See Commands and durable acknowledgements.

Through the relay, /mobile/v1 also needs the per-device relay credential. The HQ does not accept the management bearer.

If GET /mobile/v1/health is not available or does not have contractVersion: 1, the HQ is older than the client. Tell the user to update the HQ. The client has no older protocol to use.

Snapshot and replayCopy Anchor Link

Paths in this table are relative to /mobile/v1. All of them need the mobile bearer.

The loopback management server has the same reads with the management bearer: /conversations/:id/bootstrap, /conversations/:id/messages, and /agents/:agentId/conversations/:conversationId/events?sinceSeq=N.

GET /agents/:agentId/conversations/:conversationId/events needs sinceSeq. If it is absent or not a non-negative integer, the route returns 400 validation_failed. The route accepts no other query parameter.

{
  "frames": [
    {
      "type": "accepted",
      "id": "turn-01",
      "conversationId": "00000000-0000-4000-8000-000000000101",
      "runId": "turn-01",
      "segmentTurnId": "turn-01",
      "seq": 8,
      "userMessageId": "00000000-0000-4000-8000-000000000111",
      "assistantMessageId": "00000000-0000-4000-8000-000000000114",
      "revision": 3
    },
    {
      "type": "event",
      "id": "turn-01",
      "conversationId": "00000000-0000-4000-8000-000000000101",
      "runId": "turn-01",
      "segmentTurnId": "turn-01",
      "seq": 10,
      "event": { "type": "text_delta", "text": "Working." }
    }
  ],
  "throughSeq": 10
}

frames contains the sequenced frames: accepted, event, done, error, input_accepted, input_updated, input_removed, input_failed, input_delivered, queue_paused, and queue_resumed. HQ Chat WebSocket describes each frame.

seq is a dense sequence for each conversation. Store a cursor only after you apply its frame. After a compaction, read a new bootstrap, and keep the history that you already have by message ID.

Subscribe before you sendCopy Anchor Link

Connect to /ws/chat with the native Authorization header or a single-use ticket. The first frame must be hello. It names the contract version and nothing else:

{"type":"hello","contractVersion":1}

hello_ack has the same two fields:

{"type":"hello_ack","contractVersion":1}

Wait for hello_ack. Then subscribe from the watermark of the bootstrap:

{"type":"subscribe_conversation","id":"00000000-0000-4000-8000-000000000002","agentId":"agent-01","conversationId":"00000000-0000-4000-8000-000000000001","sinceSeq":0}

• conversation_subscribed contains the replay watermark (throughSeq).
• The subscription stays open across runs. A terminal frame does not close it.
• To connect again, send the last seq that you applied.
• A first frame other than hello closes the socket with 1002 hello_required.
• The HQ closes the socket with 1002 after a bad negotiation frame or protocol frame.
• If the HQ rejects a command, it sends command_rejected and keeps the subscription open.

Commands and durable acknowledgementsCopy Anchor Link

Each command has an id that the client makes. An enqueued input also has a different inputId. If you are not sure that a command arrived, send it again with the same two IDs and exactly the same payload. The HQ rejects an ID that you use again for a different payload. A normal message.id stays the outer run ID.

A Steer also needs expectedActiveTurnId, so it cannot go to a different run by accident. An auto enqueue also needs expectedActiveTurnId, because the HQ can make it a Steer.

The HQ answers with these frames:

If an item revision is old, read the item again before the next edit or removal.

If the HQ cannot choose a route for an auto enqueue, it sends command_rejected with code: "delivery_choice_required", retryable: false, and details: { suggested?: "steer" | "followUp", confidence?: number }. The HQ sends this code only for an auto command. Do these steps:

1. Show the Steer and Follow Up choice, with details.suggested selected.
2. Send the choice of the user as a new enqueue_input with an explicit behavior.
3. Use a new id and a new inputId. The rejected command made no pending row.
4. Keep the text and images in the composer until the HQ accepts a command.

Pending inputs and stored messages have routedBy: "auto" when the HQ chose the delivery. Show these entries as automatic, for example Auto-steered and Auto-queued. Use the same Steer and Follow Up display for all other parts.

Delivery rulesCopy Anchor Link

• The HQ delivers a Steer only at a safe agent boundary.
• The user row of a Steer records pending, delivered, or not_delivered. Show delivered rows as Steered.
• Each delivered Steer starts a new assistant segment in the same outer run.
• A late Steer never becomes a Follow Up.
• Follow Ups run in order, one at a time. A failure pauses the queue until the user clicks Resume Follow Ups.
• cancel stops the active run. If Follow Ups wait, the HQ also pauses the queue and sends queue_paused. No Follow Up starts until the client sends resume_follow_ups.

LimitsCopy Anchor Link

The HQ rejects a send or an edit that goes over these limits.