API and errors

One contract across every interface

HTTP, CLI, MCP, the TypeScript client and the official Skill share the same invocation, policy and result semantics.

Authentication boundaries

Owner session: A browser session or CLI management session administers devices, authorizations, approvals and account settings. State-changing requests require the deployment origin.
Agent connection: A revocable Bearer credential can inspect only its bound authorization and invoke only the tools, folders and devices in that grant.
Device identity: Connector routes use an Ed25519 signature, timestamp and one-time nonce. Device credentials are not accepted by owner or Agent routes.

Core HTTP surface

The browser console and official clients use the same versioned API. The table highlights stable integration points; management clients should prefer the typed client rather than reconstructing response types.

Method	Path	Identity	Purpose
`GET`	`/api/v1/me`	Owner or Agent	Inspect the current identity and scope.
`GET`	`/api/v1/nodes`	Owner	List paired devices and effective capabilities.
`GET`	`/api/v1/overview`	Owner	Read bounded console counts and recent activity.
`GET`	`/api/v1/projects?include=roots`	Owner	List projects and their roots in one request.
`POST`	`/api/v1/pairing-codes`	Owner	Create a short-lived, one-time pairing code.
`GET · POST`	`/api/v1/grants`	Owner	List or create Agent authorizations.
`PATCH · DELETE`	`/api/v1/grants/:grantId`	Owner	Update with a revision or delete an authorization.
`POST`	`/api/v1/invocations`	Agent	Submit a typed tool invocation.
`GET`	`/api/v1/invocations/:invocationId`	Owner or Agent	Resume an invocation across approval and dispatch.
`GET`	`/api/v1/tasks/:jobId`	Agent	Read the current task state or terminal result.
`POST`	`/api/v1/tasks/:jobId/cancel`	Agent	Request cancellation for an active task.
`GET`	`/api/v1/approvals`	Owner	Page pending or resolved approvals with a cursor.
`GET`	`/api/v1/audit`	Owner	Page and filter account-scoped activity records.

Invocation envelope

Identity fields are derived from the Agent connection by official clients. Targets and absolute paths must remain inside the current grant. Side-effecting tools also require an idempotency key.

JSON

{
  "schemaVersion": "0.1",
  "invocationId": "inv_example001",
  "attemptId": "att_example001",
  "accountId": "acct_example001",
  "actor": { "type": "agent", "id": "actor_example001" },
  "target": { "nodeId": "node_example001" },
  "authorization": {
    "grantId": "grant_example001",
    "rootIds": ["root_workspace001"]
  },
  "tool": "file.read",
  "args": { "path": "/Users/me/work/README.md" },
  "issuedAt": "2026-09-29T10:00:00.000Z",
  "expiresAt": "2026-09-29T10:05:00.000Z",
  "metadata": { "source": "sdk" }
}

Results and task state

A successful HTTP response can still carry a domain status such as denied, approval_required or offline. Track approval_required by invocationId; queued and running results include a jobId for task polling.

JSON

{
  "schemaVersion": "0.1",
  "invocationId": "inv_example001",
  "attemptId": "att_example001",
  "status": "offline",
  "error": {
    "code": "offline",
    "message": "No authorized device is online.",
    "retryable": true
  }
}

Stable error semantics

Code	Retry	Required action
`invalid_request`	No	Fix the request schema or arguments.
`expired`	No	Create a new invocation with a new deadline.
`denied`	No	Review the grant, device policy and local scope.
`approval_required`	After approval	Resolve the pending approval before it expires.
`offline`	Yes	Wait for device presence, then retry.
`conflict`	Conditionally	Refresh state; never overwrite a newer revision.
`lease_expired`	Conditionally	Read task state before creating more work.
`unknown_outcome`	No automatic retry	Reconcile the device effect and receipt first.
`internal`	When retryable	Use bounded backoff and retain the same request identity.

Never turn unknown_outcome into an automatic retry. Reusing the exact idempotency key can recover a durable receipt; inventing a new key can repeat the side effect.