121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# API byan_web — Reference Compacte
|
|
|
|
## 1. Base URL
|
|
|
|
Base URL dans `$BYAN_API_URL` env. Dev par defaut : `http://localhost:3737`. Prod exemple : `https://byan-api.stark.a3n.fr`. Ne pas inclure `/api` dans `$BYAN_API_URL` — les endpoints le contiennent deja.
|
|
|
|
## 2. Authentification
|
|
|
|
| Scheme | Quand | Exemple |
|
|
|--------|-------|---------|
|
|
| `ApiKey <key>` | Token commence par `byan_` | `Authorization: ApiKey byan_xxx` |
|
|
| `Bearer <jwt>` | JWT recu via /api/auth/login | `Authorization: Bearer eyJ...` |
|
|
|
|
## 3. Format reponse
|
|
|
|
```json
|
|
{ "data": "<payload>", "total": "<optionnel>", "error": "<si echec>", "code": "ERR_CODE" }
|
|
```
|
|
|
|
## 4. Codes d'erreur critiques
|
|
|
|
| HTTP | Code | Cause |
|
|
|------|------|-------|
|
|
| 401 | AUTH_REQUIRED | Token absent ou invalide |
|
|
| 403 | FORBIDDEN | Action non autorisee |
|
|
| 403 | FORBIDDEN_RBAC | Role insuffisant |
|
|
| 404 | NOT_FOUND | Ressource introuvable |
|
|
| 409 | SLUG_EXISTS | Slug de projet deja utilise |
|
|
| 409 | USERNAME_EXISTS | Username deja pris |
|
|
|
|
## 5. MCP tools disponibles (PREFERER ces tools au curl)
|
|
|
|
### Tools de base
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_ping` | Verifier que l'API repond | Non |
|
|
| `byan_list_projects` | Lister les projets de l'utilisateur | Oui |
|
|
| `byan_import_project` | Importer un dossier local. Args : `path` (requis), `projectId` (attache au projet existant) OU `name` + `type` (cree un nouveau projet), `autoCreateNodes` optional | Oui |
|
|
|
|
### Projets
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_projects_get` | Obtenir le detail d'un projet par ID/slug | Oui |
|
|
| `byan_api_projects_create` | Creer un nouveau projet | Oui |
|
|
|
|
### Workflows
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_workflows_list` | Lister les workflows d'un projet | Oui |
|
|
| `byan_api_workflows_get` | Detail d'un workflow par ID | Oui |
|
|
| `byan_api_workflows_run` | Declencher l'execution d'un workflow | Oui |
|
|
| `byan_api_workflow_runs_list` | Lister les executions d'un workflow | Oui |
|
|
| `byan_api_workflow_runs_get` | Detail d'une execution par ID | Oui |
|
|
|
|
### Knowledge
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_knowledge_list` | Lister les articles de la base de connaissance | Oui |
|
|
| `byan_api_knowledge_get` | Obtenir un article par ID | Oui |
|
|
|
|
### Memoire
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_memory_list` | Lister les entrees memoire d'un agent | Oui |
|
|
| `byan_api_memory_search` | Recherche semantique dans la memoire | Oui |
|
|
|
|
### Agents personnalises
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_custom_agents_list` | Lister les agents custom du projet | Oui |
|
|
| `byan_api_custom_agents_get` | Detail d'un agent custom par ID | Oui |
|
|
| `byan_api_custom_agents_clone_system` | Cloner un agent systeme en agent custom | Oui |
|
|
|
|
### Sessions
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_sessions_list` | Lister les sessions actives | Oui |
|
|
| `byan_api_sessions_get` | Detail d'une session par ID | Oui |
|
|
| `byan_api_sessions_history` | Historique des messages d'une session | Oui |
|
|
|
|
### Chat
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_chat_conversations_list` | Lister les conversations | Oui |
|
|
| `byan_api_chat_messages_list` | Lister les messages d'une conversation | Oui |
|
|
| `byan_api_chat_send` | Envoyer un message dans une conversation | Oui |
|
|
|
|
### Recherche et import
|
|
|
|
| Tool | Usage | Auth requise |
|
|
|------|-------|--------------|
|
|
| `byan_api_search` | Recherche globale (projets, agents, knowledge) | Oui |
|
|
| `byan_api_import_scan` | Scanner un dossier local avant import | Non |
|
|
| `byan_api_import_dry_run` | Simuler un import sans l'executer | Oui |
|
|
|
|
## 6. Fallback curl (si un tool MCP manque)
|
|
|
|
```bash
|
|
curl -H "Authorization: ApiKey $BYAN_API_TOKEN" "$BYAN_API_URL/api/projects"
|
|
|
|
curl -X POST -H "Authorization: ApiKey $BYAN_API_TOKEN" -H "Content-Type: application/json" \
|
|
-d '{"trigger":"..."}' "$BYAN_API_URL/api/workflows/<id>/run"
|
|
```
|
|
|
|
## 7. Patterns courants
|
|
|
|
| Je veux... | Tool MCP a appeler |
|
|
|------------|--------------------|
|
|
| Lister mes projets | `byan_list_projects` |
|
|
| Detail d'un projet | `byan_api_projects_get` |
|
|
| Lancer un workflow | `byan_api_workflows_run` |
|
|
| Chercher dans la memoire | `byan_api_memory_search` |
|
|
| Importer un projet local | `byan_import_project` |
|