Skip to main content

​
Vue d’ensemble

L’API Bookivox est une surface server-to-server. Deux conventions valent pour toutes les pages de cette section. URL de base
Chemin des endpoints. Tous les endpoints de cette section sont relatifs au préfixe :
Autrement dit, quand cette documentation écrit /workflow/fetch, l’URL complète est :
La surface clé API ne sert pas d’OpenAPI auto-servie : les pages docs, redoc et openapi.json n’y sont pas montées. Cette section fait donc office de référence pour cette surface.

​
Authentification

Envoyez votre clé dans l’en-tête X-API-Key. Aucun autre mécanisme n’est accepté sur cette surface.
Pour les POST et PUT, envoyez toujours Content-Type: application/json.
N’envoyez jamais Authorization en plus de X-API-Key : sa seule présence provoque un refus 400. Utilisez un seul mécanisme, X-API-Key.

​
Créer une clé

Une clé se crée dans le dashboard, puis se gère aussi par API. Le corps de création ne prend qu’un seul champ, name : il n’existe ni périmètre (scopes) ni date d’expiration.
La réponse contient le secret en clair (api_key), affiché une seule fois. Copiez-le immédiatement : il n’est plus jamais renvoyé ensuite. Guide produit : Clés API.

​
Ce que couvre la surface

​
Le parcours produit

1

Créer un compte et créditer

La création du compte et la recharge de crédits se font dans le dashboard.
2

Créer une clé API

Toujours dans le dashboard. Copiez le secret immédiatement.
3

Opérer par API

Créez vos agents, campagnes, documents et outils par API, avec X-API-Key.
Vous revenez principalement sur la plateforme pour créditer votre organisation.

​
Codes de statut

Détail complet, exemples réels et stratégie de nouvelle tentative : Erreurs.

​
Actions bloquées via clé API

Pour limiter l’impact d’une fuite de clé, certaines opérations sont interdites avec une clé API et renvoient 403. Elles doivent être faites dans le dashboard.
Création de sessions de paiement et accès au portail de facturation. 403 : Billing write operations are not available via API key.
Achat et gestion de numéros de téléphone. 403 : Telephony provisioning is not available via API key.
La lecture de la téléphonie (configurations et numéros) reste autorisée via clé API.

​
Formats de données

  • Les identifiants publics (workflow_id, campaign_id, config_id, tool_uuid, document_uuid, credential_uuid) sont des chaînes.
  • Les identifiants d’exécution de test en chat texte (run_id) sont des entiers.
  • Les dates sont au format ISO 8601.
  • Les erreurs de validation (422) suivent le format Pydantic dans detail.

​
Sécurité

  • Traitez une clé API comme un secret : elle donne accès aux ressources de votre organisation.
  • Utilisez une clé dédiée par usage (site web, back-office, agent IA) pour pouvoir la révoquer isolément.
  • Tournez vos clés régulièrement, notamment après le départ d’un collaborateur.
  • N’exposez jamais une clé dans du code client (navigateur), un dépôt public ou un journal.
  • L’API est server-to-server : appelez-la depuis votre backend, jamais depuis le navigateur.
Cette surface bloque déjà les opérations les plus sensibles (facturation, provisioning). C’est une défense en profondeur : même en cas de fuite de clé, l’attaquant ne peut pas dépenser de crédits ni acheter de numéros.

​
À lire ensuite

Démarrage rapide

Première requête et bonnes pratiques.

Endpoints

Le cheatsheet complet, avec paramètres.

Flows

Recettes de bout en bout.

Erreurs

Formats et réaction attendue.
Last modified on October 28, 2026