API - Orchestration
L'API Orchestration permet d'exécuter des workflows NeuraFlow et des crews NeuraCrew de manière programmatique.
Scopes Requis
orchestration:read— Lister et consulter les workflows et crewsorchestration:write— Exécuter des workflows et crews
Workflows (NeuraFlow)
Lister les Workflows
GET /api/v1/orchestration/workflows
Réponse :
{
"success": true,
"data": [
{
"id": 1,
"name": "presentation_nodes",
"nodes_count": 27,
"status": "active",
"created_at": "2025-11-04T10:30:00Z"
}
]
}
Détails d'un Workflow
GET /api/v1/orchestration/workflows/{id}
Retourne la définition complète du workflow : nœuds, connexions, paramètres.
Exécuter un Workflow
POST /api/v1/orchestration/workflows/{id}/execute
Corps de la requête :
{
"input": {
"text": "Votre texte d'entrée",
"parameters": {
"key": "value"
}
},
"async": false
}
Paramètres :
| Champ | Type | Description |
|---|---|---|
input |
object | Données d'entrée pour le workflow |
async |
boolean | true pour exécution asynchrone, false pour synchrone |
Réponse (synchrone) :
{
"success": true,
"data": {
"execution_id": "exec_abc123",
"status": "completed",
"output": { ... },
"duration_ms": 2450
}
}
Réponse (asynchrone) :
{
"success": true,
"data": {
"execution_id": "exec_abc123",
"status": "running"
}
}
Vérifier le Statut d'une Exécution
GET /api/v1/orchestration/executions/{execution_id}
Crews (NeuraCrew)
Lister les Crews
GET /api/v1/orchestration/crews
Exécuter un Crew
POST /api/v1/orchestration/crews/{id}/execute
Corps de la requête :
{
"objective": "Analysez les données de vente du Q1 et produisez un rapport",
"context": {
"project_id": 1,
"additional_data": "..."
},
"async": true
}
Paramètres :
| Champ | Type | Description |
|---|---|---|
objective |
string | Objectif à atteindre par le crew |
context |
object | Contexte additionnel (projet, données) |
async |
boolean | Recommandé true car les crews sont souvent longs |
Historique des Exécutions
Lister l'Historique
GET /api/v1/orchestration/executions?type=workflow&status=completed&limit=20
Paramètres de filtrage :
| Paramètre | Valeurs | Description |
|---|---|---|
type |
workflow, crew | Filtrer par type |
status |
running, completed, failed | Filtrer par statut |
limit |
1-100 | Nombre de résultats (défaut : 20) |
offset |
number | Pagination |
Webhooks
Vous pouvez configurer des webhooks pour recevoir des notifications lorsqu'une exécution se termine :
POST /api/v1/orchestration/webhooks
{
"url": "https://votre-serveur.com/webhook",
"events": ["execution.completed", "execution.failed"]
}
Bonnes Pratiques
- Utilisez le mode asynchrone pour les workflows longs et les crews multi-agents
- Implémentez un polling sur l'endpoint d'exécution pour suivre le statut
- Configurez des webhooks pour éviter le polling intensif
- Gérez les erreurs : vérifiez le champ
successet les codes HTTP