Bookivox Documentation

Tous les endpoints ci-dessous requièrent l’en-tête X-API-Key. Les chemins sont relatifs à la base https://api.bookivox.com/api/v1/api : l’endpoint /workflow/fetch correspond donc à https://api.bookivox.com/api/v1/api/workflow/fetch.

Authentification / clés API

Méthode	Endpoint	Corps	Réponse
`GET`	`/api-keys`	— (`?include_archived=false`)	Liste des clés (`id`, `name`, `key_prefix`, `is_active`, `created_at`, `last_used_at`, `archived_at`)
`POST`	`/api-keys`	`{ "name": string }`	`201` avec `api_key` en clair, renvoyé une seule fois
`DELETE`	`/api-keys/{api_key_id}`	—	`204`, archive la clé (ne la supprime pas)
`POST`	`/api-keys/{api_key_id}/reactivate`	—	`204`, réactive une clé archivée

Le corps de création ne prend que name : il n’existe ni scopes ni date d’expiration.

Agents (workflows)

Méthode	Endpoint	Paramètres
`GET`	`/workflow/fetch`	`?status=` (une valeur ou une liste séparée par virgules : `active,archived`)
`GET`	`/workflow/fetch/{workflow_id}`	Renvoie le draft s’il existe, sinon la version publiée
`POST`	`/workflow/create/definition`	`{ "name": string, "workflow_definition": object }`
`PUT`	`/workflow/{workflow_id}`	`{ "name"?, "workflow_definition"?, "template_context_variables"?, "workflow_configurations"? }`
`POST`	`/workflow/{workflow_id}/validate`	Aucun corps. `422` si invalide
`GET`	`/workflow/{workflow_id}/versions`	`?limit=` (1 à 100), `?offset=` (défaut 0)
`POST`	`/workflow/{workflow_id}/create-draft`	Aucun corps
`POST`	`/workflow/{workflow_id}/publish`	Aucun corps. `400` sans draft, `422` si validation échoue
`PUT`	`/workflow/{workflow_id}/status`	`{ "status": string }`
`PUT`	`/workflow/{workflow_id}/folder`	`{ "folder_id": string \| null }` (`null` = non classé)
`POST`	`/workflow/{workflow_id}/duplicate`	Aucun corps
`GET`	`/workflow/{workflow_id}/runs`	`?page=` (défaut 1), `?limit=` (défaut 50), `?filters=` (JSON), `?sort_by=`, `?sort_order=` (`asc`/`desc`)

Sur GET /workflow/{id}/runs, le paramètre filters est un tableau JSON encodé. Les attributs autorisés sont dateRange, dispositionCode, duration, status et tokenUsage. Tout autre attribut renvoie 403.

Templates (recommandé pour créer un agent)

Méthode	Endpoint	Paramètres
`GET`	`/workflow/templates`	Aucun. Renvoie `id`, `template_name`, `template_description`, `template_json`
`POST`	`/workflow/templates/duplicate`	`{ "template_id": int, "workflow_name": string }`

Test d’agent (chat texte)

Méthode	Endpoint	Paramètres
`POST`	`/workflow/{workflow_id}/text-chat/sessions`	`{ "name"?, "initial_context"?, "annotations"? }`
`GET`	`/workflow/{workflow_id}/text-chat/sessions/{run_id}`	`run_id` est un entier
`POST`	`/workflow/{workflow_id}/text-chat/sessions/{run_id}/messages`	`{ "text": string, "expected_revision"?: int }`
`POST`	`/workflow/{workflow_id}/text-chat/sessions/{run_id}/rewind`	`{ "cursor_turn_id"?, "expected_revision"?: int }`

expected_revision protège contre les écritures concurrentes : si la révision ne correspond plus, l’API renvoie 409. Relisez la session, puis renvoyez avec la révision à jour.

Campagnes

Méthode	Endpoint	Paramètres
`POST`	`/campaign/create`	`{ "name", "workflow_id", "source_type": "csv", "source_id", "telephony_configuration_id"?, "max_concurrency"?, "retry_config"?, "schedule_config"?, "circuit_breaker"? }`
`GET`	`/campaign/`	Aucun. Renvoie `{ "campaigns": [...] }`
`GET`	`/campaign/{campaign_id}`	Aucun
`POST`	`/campaign/{campaign_id}/start`	Aucun corps. `401` sans config téléphonie, `402` sans crédits
`POST`	`/campaign/sources/presigned-upload-url`	`{ "file_name" (.csv), "file_size" (≤ 10 Mo), "content_type" }`

Détail des champs de création : Campagnes.

Base de connaissance

Méthode	Endpoint	Paramètres
`POST`	`/knowledge-base/upload-url`	`{ "filename", "mime_type", "custom_metadata"? }`
`POST`	`/knowledge-base/process-document`	`{ "document_uuid", "upload_url", "retrieval_mode"? }` (défaut `chunked`)
`GET`	`/knowledge-base/documents`	`?status=`, `?limit=` (1 à 100, défaut 100), `?offset=` (défaut 0)
`DELETE`	`/knowledge-base/documents/{document_uuid}`	Aucun corps
`POST`	`/knowledge-base/search`	`{ "query", "limit"? (1 à 50, défaut 5), "document_uuids"?, "min_similarity"? (0 à 1) }`

Le champ de quantité de résultats s’appelle limit, pas top_k. Le seuil de similarité s’appelle min_similarity, pas threshold.

Détail : Base de connaissance (API).

Outils

Méthode	Endpoint	Paramètres
`GET`	`/tools/`	`?status=`, `?category=` (valeurs séparées par virgules acceptées)
`POST`	`/tools/`	Voir le schéma complet dans Outils (API)
`GET`	`/tools/{tool_uuid}`	Aucun
`PUT`	`/tools/{tool_uuid}`	`{ "name"?, "description"?, "icon"?, "icon_color"?, "definition"?, "status"? }`
`DELETE`	`/tools/{tool_uuid}`	Aucun. Archive l’outil
`POST`	`/tools/{tool_uuid}/unarchive`	Aucun. Restaure un outil archivé

La catégorie d’un outil n’est pas modifiable après création : seul definition et les métadonnées (nom, description, icône, statut) peuvent changer.

Intégrations

Les endpoints d’intégration dépendent du fournisseur. Pour Calendly (OAuth, event types, génération d’outils) : Intégrations (API).

Crédits & usage

Méthode	Endpoint	Paramètres
`GET`	`/organizations/billing/credits`	`?page=` (défaut 1), `?limit=` (1 à 100, défaut 50)
`GET`	`/organizations/usage/current-period`	Aucun
`GET`	`/organizations/usage/runs`	`?start_date=`, `?end_date=` (ISO 8601), `?page=`, `?limit=`, `?filters=`
`GET`	`/organizations/usage/daily-breakdown`	`?days=` (1 à 30, défaut 7)

GET /organizations/billing/credits renvoie le solde (remaining_credits), le quota total, les tarifs et le journal des mouvements de crédits.

Téléphonie

Lecture (autorisée via clé API)

Méthode	Endpoint	Paramètres
`GET`	`/organizations/telephony-configs`	Aucun
`GET`	`/organizations/telephony-configs/{config_id}`	Aucun
`GET`	`/organizations/telephony-configs/{config_id}/phone-numbers`	Aucun

Gestion des numéros (bloquée via clé API → `403`)

Méthode	Endpoint
`POST`	`/organizations/telephony-configs/{config_id}/phone-numbers`
`PUT`	`/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}`
`DELETE`	`/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}`

L’achat et la gestion des numéros passent uniquement par le dashboard. Voir Téléphonie (API).

Catalogue node-types

Méthode	Endpoint	Réponse
`GET`	`/node-types`	`{ "spec_version": string, "node_types": list }`
`GET`	`/node-types/{name}`	Un `NodeSpec` complet

Détail de la structure NodeSpec : Nœuds (graphe).

Pages dédiées

Campagnes

Créer et piloter une campagne.

Knowledge base

Documents et recherche.

Outils

CRUD des outils.

Téléphonie

Configs et numéros (lecture).

Agents

Base de connaissance

Campagnes

Chat texte

Clés API

Crédits et usage

Node-types

Outils

Téléphonie

Templates

Endpoints

Authentification / clés API

Agents (workflows)

Templates (recommandé pour créer un agent)

Test d’agent (chat texte)

Campagnes

Base de connaissance

Outils

Intégrations

Crédits & usage

Téléphonie

Lecture (autorisée via clé API)

Gestion des numéros (bloquée via clé API → `403`)

Catalogue node-types

Pages dédiées

Campagnes

Knowledge base

Outils

Téléphonie

​Authentification / clés API

​Agents (workflows)

​Templates (recommandé pour créer un agent)

​Test d’agent (chat texte)

​Campagnes

​Base de connaissance

​Outils

​Intégrations

​Crédits & usage

​Téléphonie

​Lecture (autorisée via clé API)

​Gestion des numéros (bloquée via clé API → 403)

​Catalogue node-types

​Pages dédiées

Campagnes

Knowledge base

Outils

Téléphonie

Authentification / clés API

Agents (workflows)

Templates (recommandé pour créer un agent)

Test d’agent (chat texte)

Campagnes

Base de connaissance

Outils

Intégrations

Crédits & usage

Téléphonie

Lecture (autorisée via clé API)

Gestion des numéros (bloquée via clé API → `403`)

Catalogue node-types

Pages dédiées