Prérequis
Avant d’appeler l’API, vérifiez ces quatre points :1
Un compte et une organisation active
Vous devez être membre d’une organisation, et l’avoir sélectionnée : les appels opèrent toujours dans le contexte de l’organisation courante.
2
Des crédits disponibles
Une organisation non créditée fait échouer certaines actions avec
402. Créditez dans le dashboard.3
Une clé API
Créez-la dans le dashboard, rubrique Clés API. Le secret n’est affiché qu’une seule fois.
4
Un appel côté serveur
L’API est server-to-server : appelez-la depuis un backend, jamais depuis un navigateur.
URL de base
Un endpoint ressemble donc à :
/api/v1/api.
En-têtes
Première requête : lister vos agents
id, name, status, created_at et total_runs.
Wrapper TypeScript prêt à l’emploi
Ce petit client gère les en-têtes, le204 No Content et l’extraction du message d’erreur :
Dans le wrapper, on ne passe que le chemin relatif (
/workflow/fetch) : le préfixe /api/v1/api est ajouté une fois pour toutes. Cela évite de le répéter à chaque appel.Codes de statut à gérer
Ne relancez jamais automatiquement un
401, 402, 403 ou 422 : réessayer à l’identique donnera le même résultat.
Types automatiques (recommandé)
La surface clé API n’expose pas de spec OpenAPI. Pour obtenir des types exacts, vous pouvez générer un client depuis votre propre définition, ou typer manuellement à partir des pages de cette section (notamment Outils et Nœuds).Bonnes pratiques
- Stockez la clé dans une variable d’environnement ou un gestionnaire de secrets, jamais dans le code.
- Utilisez une clé distincte par environnement de votre application.
- Journalisez les identifiants de requête, jamais la clé elle-même.
- Implémentez un timeout sur chaque appel et un backoff sur les erreurs transitoires.
Étape suivante
Endpoints
La liste complète, avec les paramètres.
Flows
Créer, tester et publier un agent.
Outils
Le schéma de création d’un outil.
Erreurs
Formats détaillés et stratégie de nouvelle tentative.
