API capabilities

What capabilities are#

Every API key carries an explicit list of capabilities. A capability is a server-side allowlist entry naming which /v1/* operations the key may perform. A key with desktop:read can list and inspect your desktops but cannot start one. A key with desktop:lifecycle can start and stop desktops but cannot run Python on them. A key with kb:read can search your knowledge base and read nothing else.

Narrow scoping reduces blast radius. If a key leaks -- accidentally committed, copied to a shared notebook, paste-bombed into a chat -- the attacker can only do what the capabilities on that key allow. Default to the smallest set you need.

Capabilities are static#

Capabilities are fixed when the key is created. There is no edit-key flow. To change scopes, revoke the existing key and generate a new one with the right set. This is intentional: it prevents silent privilege escalation on a key that has already been distributed and audited.

The default selection#

The create-key form pre-selects a narrow default of desktop:read and desktop:chat. This is enough for an assistant to inspect your desktops and chat with the agent on them, with no ability to control or modify anything. Add other scopes only when you actually need them for the integration you are wiring up.

The user scopes#

desktop:read#

List your desktops and read their details: status, specs, agent info. No control, no chat, no lifecycle.

desktop:lifecycle#

Start, stop, and restart your desktops. Cannot create new desktops or destroy existing ones -- those operations are not exposed in this release.

desktop:control#

Send mouse, keyboard, and scroll input to a desktop. Run Python on the agent runtime. Take screenshots. This is the broadest control scope; treat it like a remote-desktop credential.

desktop:chat#

Send messages to the AI agent running on a desktop and receive its response. Does not include screen control or lifecycle.

scheduled_jobs:read#

List the scheduled jobs in your workspace, optionally filtered by workspace or by desktop.

scheduled_jobs:write#

Create scheduled jobs and trigger immediate runs. Job deletion is not exposed in this release.

kb:read#

Full-text search and read notes from your workspace's knowledge base.

Reserved scopes#

Admin scopes (read and write) are reserved for future admin-only tools and cannot be selected when creating a key on a non-admin account. Desktop creation and deletion are not exposed via API in this release; they will be a separate scope when introduced.

Error shape on missing capability#

When a tool is called with insufficient scope, the response is 403 Forbidden with a body that names the missing capability and the capabilities the key does hold:

{
  "error": "Missing required capability: desktop:lifecycle",
  "required": "desktop:lifecycle",
  "held": ["desktop:read", "desktop:chat"]
}

Use held to decide whether to retry with a different tool or to mint a new key with a wider scope.

For the full per-tool capability map, see MCP tools.