# Référence : API workspace

> Description neutre et exhaustive des endpoints derrière le panneau workspace et les sélecteurs du composer : l'API fichiers, l'endpoint des skills et le WebSocket du terminal. Les chemins relatifs se résolvent contre le `--cwd` du serveur ; les chemins absolus sont utilisés tels quels (accès volontairement non restreint — ori vise des sandboxes déjà isolées).

## GET /api/files

Liste un répertoire.

| Paramètre de requête | Type | Défaut | Description |
| --- | --- | --- | --- |
| `path` | chaîne | la racine du workspace | Répertoire à lister. |

Réponse `200` :

```json
{ "path": "/travail", "entries": [ { "name": "src", "path": "/travail/src", "isDir": true, "size": 0 } ] }
```

Les entrées sont triées répertoires d'abord, puis fichiers, chaque groupe par ordre alphabétique.

## GET /api/files/search

Recherche des fichiers récursivement sous la racine du workspace, pour le sélecteur `@` du composer.

| Paramètre de requête | Type | Défaut | Description |
| --- | --- | --- | --- |
| `q` | chaîne | `""` | Sous-chaîne, insensible à la casse, cherchée dans le chemin relatif à la racine. Vide renvoie les premiers fichiers. |
| `limit` | entier | 50 | Nombre maximal de résultats ; plafonné à 500. |

Réponse `200` :

```json
{ "root": "/travail", "files": [ { "name": "main.go", "path": "/travail/src/main.go", "relPath": "src/main.go" } ] }
```

`path` est absolu (utilisable dans les autres endpoints), `relPath` utilise des barres obliques. Les résultats sont classés : d'abord les fichiers dont le nom de base contient la requête, puis les chemins relatifs les plus courts, puis l'ordre alphabétique. Le parcours n'entre jamais dans `.git` ni `node_modules`, ignore les entrées illisibles et s'arrête après 50 000 entrées de répertoire. `files` est toujours un tableau (`[]` sans correspondance). Une racine absente donne un `404`.

## GET /api/file

Lit un fichier texte.

| Paramètre de requête | Type | Défaut | Description |
| --- | --- | --- | --- |
| `path` | chaîne | — | Fichier à lire. |

Réponse `200` : `{ "path": "/travail/README.md", "content": "…" }`

## PUT /api/file

Écrit un fichier texte, en créant les répertoires parents si besoin.

| Paramètre de requête | Type | Défaut | Description |
| --- | --- | --- | --- |
| `path` | chaîne | — (requis) | Fichier à écrire. |

Corps : `{ "content": "…" }` — réponse `200` : `{ "path": "…", "status": "saved" }`

## GET /api/raw

Diffuse les octets d'un fichier tels quels — c'est ainsi que la preview affiche les images. Pas de plafond de taille, pas d'exigence de texte ; les requêtes `Range` sont honorées (`http.ServeContent`).

| Paramètre de requête | Type | Défaut | Description |
| --- | --- | --- | --- |
| `path` | chaîne | — (requis) | Fichier à diffuser. |

Réponse `200` avec les octets du fichier, `X-Content-Type-Options: nosniff`, et un `Content-Type` choisi dans cet ordre :

| Extension | Content-Type |
| --- | --- |
| `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` `.bmp` `.ico` `.avif` | types image figés (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/svg+xml`, `image/bmp`, `image/x-icon`, `image/avif`) |
| toute autre extension connue | la table mime de l'hôte (p. ex. `text/markdown; charset=utf-8`) |
| inconnue | détecté sur les 512 premiers octets |

## GET /api/skills

Liste les skills Claude Code disponibles pour la session, pour le sélecteur `/` du composer.

Réponse `200` :

```json
{ "skills": [ { "name": "quality", "description": "Audit code quality with qlty.", "path": "/travail/.claude/skills/quality/SKILL.md", "source": "project" } ] }
```

Un skill est un répertoire contenant un `SKILL.md`, cherché dans `<cwd>/.claude/skills/*/` (`source: "project"`) et `~/.claude/skills/*/` (`source: "user"`). `name` et `description` viennent du frontmatter YAML du fichier (`clé: valeur`, valeurs entre guillemets et scalaires bloc `>` / `|` compris) ; un nom absent est remplacé par le nom du répertoire, une description absente par `""`. Un skill projet masque un skill utilisateur du même nom. Résultats triés par nom ; `skills` est toujours un tableau.

## Erreurs de l'API fichiers

Toutes les erreurs sont en JSON : `{ "error": "message" }`.

| Statut | Cause |
| --- | --- |
| 400 | `path` manquant sur PUT ou `GET /api/raw`, corps JSON invalide, ou lecture d'un répertoire. |
| 403 | Permission refusée par le système de fichiers. |
| 404 | Le chemin (ou la racine du workspace, pour la recherche) n'existe pas. |
| 413 | Fichier de plus de 5 Mio (`GET /api/file` seulement ; `/api/raw` n'a pas de plafond). |
| 415 | Le fichier n'est pas du texte UTF-8 valide (`GET /api/file` seulement). |

## GET /ws/terminal

Bascule en WebSocket et démarre un shell (depuis `$SHELL`, repli sur `bash` puis `sh`, avec `TERM=xterm-256color`) dans un pseudo-terminal, dans le `--cwd` du serveur.

| Direction | Type de trame | Contenu |
| --- | --- | --- |
| serveur → client | binaire | Octets bruts de la sortie du terminal. |
| client → serveur | texte | `{"type":"input","data":"…"}` — frappes écrites dans le pty. |
| client → serveur | texte | `{"type":"resize","cols":N,"rows":N}` — changement de taille. |

Le socket se ferme avec un statut de fermeture normale quand le shell se termine ; fermer le socket tue le shell. Les trames texte malformées sont ignorées.