Desktop endpoints
REST reference for the public /v1/desktops/* surface: read, lifecycle, control, and chat. Bearer auth on every call.
All desktop routes live under /v1/desktops/* and require Authorization: Bearer sk_live_... on every request. Each route also requires a specific capability on the calling key. If the key is valid but missing the capability, the response is 403 Forbidden. See API capabilities for the full mapping and how to scope a key.
Read
| Route | Capability | Purpose |
|---|---|---|
GET /v1/desktops | desktop:read | List desktops you own. Destroyed desktops are excluded. |
GET /v1/desktops/:id | desktop:read | Fetch one desktop with status, tier, IP, agent readiness. |
Lifecycle
| Route | Capability | Purpose |
|---|---|---|
POST /v1/desktops/:id/start | desktop:lifecycle | Boot a stopped desktop. Returns once the boot is queued; poll /v1/desktops/:id for status and agentReady to know when it is callable. |
POST /v1/desktops/:id/stop | desktop:lifecycle | Shut the desktop down. |
POST /v1/desktops/:id/restart | desktop:lifecycle | Stop then start. |
Control
These routes drive the desktop directly. They require the desktop to be running with agentReady: true; otherwise the response is 503.
| Route | Capability | Purpose |
|---|---|---|
POST /v1/desktops/:id/click | desktop:control | Mouse click at given coordinates. |
POST /v1/desktops/:id/drag | desktop:control | Mouse drag from a start to an end point. |
POST /v1/desktops/:id/scroll | desktop:control | Scroll the desktop viewport. |
POST /v1/desktops/:id/type | desktop:control | Type a string of text. |
POST /v1/desktops/:id/key | desktop:control | Send a single key or key combination. |
POST /v1/desktops/:id/bash | desktop:control | Run a multi-line bash script. |
POST /v1/desktops/:id/exec | desktop:control | Run a single shell command. Response includes stdout, stderr, exitCode. |
GET /v1/desktops/:id/screenshot | desktop:control | Return a PNG of the current display. |
Chat
| Route | Capability | Purpose |
|---|---|---|
POST /v1/desktops/:id/chat | desktop:chat | Send a message to the on-desktop AI agent and wait for the full response. |
Example
curl https://lebureau.talentai.fr/v1/desktops \
-H "Authorization: Bearer sk_live_..."
A request with no Authorization header returns 401. A request with a key missing the route's capability returns 403 with required and held in the body.
What is not exposed yet
The public API in this release does not cover desktop creation or deletion, file management, resource metrics, or real-time streams (status, activity, chat token streaming). Manage these from the dashboard for now. A larger public surface is planned but is not yet committed to a date.
Related docs
API authentication
How to authenticate against the public REST API: session cookies for the dashboard, Bearer API keys for programmatic access.
API capabilities
How API key capabilities work and the seven user scopes you can put on a key.
MCP tools reference
The 18 tools shipped in @lebureau/mcp v0.1.0, grouped by area, with the API key capability each one requires.