wiki: HTTP-API page

2026-04-27 08:46:46 +00:00
parent a50967abbf
commit ffe4655dc2
1 changed files with 109 additions and 0 deletions
--- a/HTTP-API.-.md
+++ b/HTTP-API.-.md
@@ -0,0 +1,109 @@
+# API HTTP — référence
+
+Le serveur (`internal/api/server.go`) écoute sur localhost. CORS restreint aux origines locales (`localhost`, `127.0.0.1`, `[::1]`) en HTTP/HTTPS.
+
+## Headers
+
+- `Content-Type: application/json` par défaut
+- `Access-Control-Allow-Origin: <origin>` si origine dans l'allowlist (sinon header omis)
+- `Vary: Origin` quand l'origine est validée
+
+## Endpoints principaux
+
+### Système & info
+| Méthode | Chemin | Description |
+|---|---|---|
+| GET | `/api/info` | nom + version + auteur + sudo bypass |
+| GET | `/api/system` | infos système (OS, OS name, arch, WSL, shell…) |
+| GET | `/api/tools` | outils CLI scannés (crush, claude, git…) |
+| GET | `/api/scan` / POST | rescan le système |
+| GET | `/api/system/metrics` | CPU/RAM/Net live |
+| GET | `/api/dashboard/status` | dashboard combiné |
+
+### Configuration
+| Méthode | Chemin | Description |
+|---|---|---|
+| GET | `/api/config` | profile + terminal + bmad |
+| GET | `/api/providers` | providers AI (api_key masqué `"***"`) |
+| PUT | `/api/config/profile` | merge profile |
+| PUT | `/api/config/provider` | crée/met à jour un provider (skip si `api_key == "***"`) |
+| POST | `/api/config/reset` | reset config |
+| POST | `/api/providers/validate` | teste une clé API |
+| GET | `/api/providers/quota` | quotas Minimax / Z.AI / MiMo |
+| GET | `/api/providers/consumption` | tokens consommés cumulés |
+
+### Chat (Studio)
+| Méthode | Chemin | Description |
+|---|---|---|
+| POST | `/api/chat` | message au provider actif (SSE si `stream: true`). Champ `advanced_reflection: bool` pour activer la double passe. Body limité à 50 MB. |
+| GET | `/api/chat/history` | historique + tokens utilisés |
+| POST | `/api/chat/clear` | clear conversation |
+| POST | `/api/chat/summarize` | résumer la conversation |
+| GET | `/api/conversations` | lister les conversations |
+| GET | `/api/conversations/search?q=` | recherche full-text |
+| GET | `/api/conversations/export?id=` | export JSON |
+| DELETE | `/api/conversations/{id}` | supprime |
+
+### Outils & images
+| Méthode | Chemin | Description |
+|---|---|---|
+| POST | `/api/tool/call` | exécute un outil (terminal, read_file, ...) |
+| GET | `/api/tools/list` | liste des outils disponibles |
+| GET | `/api/images/{id}` | sert une image attachée à un message (max 10 MB par image) |
+
+### Terminal
+| Méthode | Chemin | Description |
+|---|---|---|
+| WS | `/api/ws/terminal` | WebSocket PTY (init message JSON `{type, data}`) |
+| GET | `/api/terminal/sessions` | connexions SSH (password masqué `"***"`) + terminaux système (incluant distros WSL sur Windows) |
+| POST | `/api/terminal/sessions` | crée/update connexion SSH |
+| DELETE | `/api/terminal/sessions/{name}` | supprime |
+| GET | `/api/terminal/themes` | thèmes xterm |
+| PUT | `/api/terminal/settings` | save font/theme (font_size ≤ 72) |
+
+### Workflows
+| Méthode | Chemin | Description |
+|---|---|---|
+| POST | `/api/workflow` | crée |
+| GET | `/api/workflow/list` | liste |
+| GET | `/api/workflow/{id}` | détail |
+| POST | `/api/workflow/plan` | génère un plan via le planner LLM |
+| POST | `/api/workflow/execute/{id}` | exécute (`?stream=true` pour SSE) |
+| POST | `/api/workflow/approve/{id}` | approuve une étape `awaiting_approval` |
+
+### LSP / MCP / Skills
+| Méthode | Chemin | Description |
+|---|---|---|
+| GET | `/api/lsp` | scan serveurs LSP |
+| GET | `/api/lsp/health` | check santé |
+| POST | `/api/lsp/auto-install` | install pour un projet (`project_dir` doit être dans `~`) |
+| POST | `/api/lsp/editor-config` | génère config éditeur |
+| POST | `/api/lsp/install` | install d'un LSP |
+| GET | `/api/mcp/status` | statut |
+| GET | `/api/mcp/registry` | registre des MCP servers |
+| POST | `/api/mcp/configure` | configure pour un éditeur |
+| GET | `/api/skills` | liste |
+| POST | `/api/skills/{deploy,undeploy,validate,test,export,import}` | gestion |
+
+## Format SSE
+
+Les endpoints streamants envoient des lignes `data: <json>\n\n`. Types d'événements :
+
+```jsonc
+{ "content": "..." }                      // chunk de texte
+{ "thinking": "..." } / { "thinking_end": true }
+{ "tool_call":   { "tool_call_id", "name", "args" } }
+{ "tool_result": { "tool_call_id", "content", "is_error", "sudo_blocked"? } }
+{ "error":       "..." }
+{ "done":        "true" }
+```
+
+## Limites
+
+- Body POST `/api/chat` : 50 MB
+- Image individuelle : 10 MB
+- Max images par message : 3
+- Max iterations boucle tool-call : 15
+- Agents simultanés : 2 crush + 2 claude
+- Timeout terminal tool : 300s (max), 60s (défaut)
+- Timeout `crush_run`/`claude_run` : 1800s (max et défaut, depuis v0.6.0)