Endpoints desktop
Référence REST de la surface publique /v1/desktops/* : lecture, cycle de vie, contrôle et chat. Auth Bearer sur chaque appel.
Toutes les routes desktop vivent sous /v1/desktops/* et exigent Authorization: Bearer sk_live_... sur chaque requête. Chaque route requiert aussi une capability spécifique sur la clé appelante. Si la clé est valide mais qu'il lui manque la capability, la réponse est 403 Forbidden. Voir Capabilities API pour la table complète et comment cadrer une clé.
Lecture
| Route | Capability | Objet |
|---|---|---|
GET /v1/desktops | desktop:read | Liste les bureaux que vous possédez. Les bureaux détruits sont exclus. |
GET /v1/desktops/:id | desktop:read | Récupère un bureau avec statut, tier, IP, état de l'agent. |
Cycle de vie
| Route | Capability | Objet |
|---|---|---|
POST /v1/desktops/:id/start | desktop:lifecycle | Démarre un bureau arrêté. Répond 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 | Arrête un bureau. |
POST /v1/desktops/:id/restart | desktop:lifecycle | Stop puis start. |
Contrôle
Ces routes pilotent un bureau directement. Elles exigent que ce bureau soit running avec agentReady: true ; sinon la réponse est 503.
| Route | Capability | Objet |
|---|---|---|
POST /v1/desktops/:id/click | desktop:control | Clic souris aux coordonnées données. |
POST /v1/desktops/:id/drag | desktop:control | Glisser souris d'un point de départ à un point d'arrivée. |
POST /v1/desktops/:id/scroll | desktop:control | Défiler la vue du bureau. |
POST /v1/desktops/:id/type | desktop:control | Saisir une chaîne de texte. |
POST /v1/desktops/:id/key | desktop:control | Envoyer une touche ou combinaison de touches. |
POST /v1/desktops/:id/bash | desktop:control | Exécuter un script bash multi-lignes. |
POST /v1/desktops/:id/exec | desktop:control | Exécuter une seule commande shell. La réponse 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 à l'agent IA du bureau et attend la réponse complète. |
Exemple
curl https://www.spinestudio.dev/v1/desktops \
-H "Authorization: Bearer sk_live_..."
Une requête sans header Authorization renvoie 401. Une requête avec une clé à laquelle manque la capability requise renvoie 403 avec required et held dans le corps.
Ce qui n'est pas encore exposé
L'API publique de cette version ne couvre pas la création ni la suppression de bureaux, la gestion de fichiers, les métriques de ressources, ni les flux temps réel (statut, activité, streaming de tokens chat). Gérez tout cela depuis le tableau de bord pour le moment. Une surface publique plus large est prévue mais sans date engagée.
Articles connexes
Authentification API
Comment s'authentifier sur l'API REST publique : cookies de session pour Mission Control, clés API en Bearer pour l'accès programmatique.
Capabilities API
Comment fonctionnent les capabilities des clés API et les sept scopes utilisateur que vous pouvez attacher à une clé.
Référence des outils MCP
Les 18 outils livrés dans @spineos/mcp v0.1.0, groupés par domaine, avec la capability requise sur la clé API.