Skip to main content

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 à :
Dans toute cette section, les chemins sont écrits relativement à /api/v1/api.

En-têtes

N’ajoutez pas Authorization. Si votre client HTTP ou votre passerelle en injecte un automatiquement, désactivez-le pour les appels Bookivox.

Première requête : lister vos agents

La réponse est un tableau d’agents. Chaque entrée contient au moins id, name, status, created_at et total_runs.

Wrapper TypeScript prêt à l’emploi

Ce petit client gère les en-têtes, le 204 No Content et l’extraction du message d’erreur :
Utilisation :
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.
Last modified on October 28, 2026