Endpoints desktop
Reference REST de la surface publique /v1/desktops/* : lecture, cycle de vie, controle et chat. Auth Bearer sur chaque appel.
Toutes les routes desktop vivent sous /v1/desktops/* et exigent Authorization: Bearer sk_live_... sur chaque requete. Chaque route requiert aussi une capability specifique sur la cle appelante. Si la cle est valide mais qu'il lui manque la capability, la reponse est 403 Forbidden. Voir Capabilities API pour la table complete et comment cadrer une cle.
Lecture
| Route | Capability | Objet |
|---|---|---|
GET /v1/desktops | desktop:read | Liste les bureaux que vous possedez. Les bureaux detruits sont exclus. |
GET /v1/desktops/:id | desktop:read | Recupere un bureau avec statut, tier, IP, etat de l'agent. |
Cycle de vie
| Route | Capability | Objet |
|---|---|---|
POST /v1/desktops/:id/start | desktop:lifecycle | Demarre un bureau arrete. Repond une fois le boot mis en file ; sondez /v1/desktops/:id pour status et agentReady afin de savoir quand il est appelable. |
POST /v1/desktops/:id/stop | desktop:lifecycle | Arrete le bureau. |
POST /v1/desktops/:id/restart | desktop:lifecycle | Stop puis start. |
Controle
Ces routes pilotent le bureau directement. Elles exigent que le bureau soit running avec agentReady: true ; sinon la reponse est 503.
| Route | Capability | Objet |
|---|---|---|
POST /v1/desktops/:id/click | desktop:control | Clic souris aux coordonnees donnees. |
POST /v1/desktops/:id/drag | desktop:control | Glisser souris d'un point de depart a un point d'arrivee. |
POST /v1/desktops/:id/scroll | desktop:control | Defiler la vue du bureau. |
POST /v1/desktops/:id/type | desktop:control | Saisir une chaine de texte. |
POST /v1/desktops/:id/key | desktop:control | Envoyer une touche ou combinaison de touches. |
POST /v1/desktops/:id/bash | desktop:control | Executer un script bash multi-lignes. |
POST /v1/desktops/:id/exec | desktop:control | Executer une seule commande shell. La reponse contient stdout, stderr, exitCode. |
GET /v1/desktops/:id/screenshot | desktop:control | Renvoie un PNG de l'affichage courant. |
Chat
| Route | Capability | Objet |
|---|---|---|
POST /v1/desktops/:id/chat | desktop:chat | Envoie un message a l'agent IA du bureau et attend la reponse complete. |
Exemple
curl https://lebureau.talentai.fr/v1/desktops \
-H "Authorization: Bearer sk_live_..."
Une requete sans header Authorization renvoie 401. Une requete avec une cle a laquelle manque la capability requise renvoie 403 avec required et held dans le corps.
Ce qui n'est pas encore expose
L'API publique de cette version ne couvre pas la creation ni la suppression de bureaux, la gestion de fichiers, les metriques de ressources, ni les flux temps reel (statut, activite, streaming de tokens chat). Gerez tout cela depuis le tableau de bord pour le moment. Une surface publique plus large est prevue mais sans date engagee.
Articles connexes
Authentification API
Comment s'authentifier sur l'API REST publique : cookies de session pour le tableau de bord, cles API en Bearer pour l'acces programmatique.
Capabilities API
Comment fonctionnent les capabilities des cles API et les sept scopes utilisateur que vous pouvez attacher a une cle.
Reference des outils MCP
Les 18 outils livres dans @lebureau/mcp v0.1.0, groupes par domaine, avec la capability requise sur la cle API.