> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Référence API

> Pilotez Bookivox en server-to-server : authentification X-API-Key, base /api/v1/api, et chaque surface (agents, campagnes, base de connaissance, outils, téléphonie, crédits).

## 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**

```
https://api.bookivox.com
```

**Chemin des endpoints.** Tous les endpoints de cette section sont **relatifs** au préfixe :

```
/api/v1/api
```

Autrement dit, quand cette documentation écrit `/workflow/fetch`, l'URL complète est :

```
https://api.bookivox.com/api/v1/api/workflow/fetch
```

> [!NOTE]
>
> 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.

```bash theme={null}
curl -sS "https://api.bookivox.com/api/v1/api/workflow/fetch" \
  -H "X-API-Key: $BOOKIVOX_API_KEY"
```

| En-tête | Règle | Si absent ou interdit |
| - | - | - |
| **`X-API-Key`** | Obligatoire sur chaque requête | `401` |
| **`Authorization`** | **Interdit** sur cette surface | `400` |
| **`Content-Type`** | `application/json` sur les `POST` et `PUT` | `422` possible |

Pour les `POST` et `PUT`, envoyez toujours `Content-Type: application/json`.

> [!WARNING]
>
> 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.

```json theme={null}
{ "name": "Intégration site web" }
```

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](https://docs.bookivox.com/workspace/api-keys.md).

## Ce que couvre la surface

| Domaine | Endpoints | Page dédiée |
| - | - | - |
| **Clés API** | `/api-keys` (liste, création, archivage, réactivation) | [Endpoints](https://docs.bookivox.com/api-reference/endpoints) |
| **Agents (workflows)** | `/workflow/fetch`, `/workflow/create/definition`, `/workflow/{id}/…` | [Flows](https://docs.bookivox.com/api-reference/flows) |
| **Templates** | `/workflow/templates`, `/workflow/templates/duplicate` | [Flows](https://docs.bookivox.com/api-reference/flows) |
| **Test texte** | `/workflow/{id}/text-chat/sessions/…` | [Flows](https://docs.bookivox.com/api-reference/flows) |
| **Campagnes** | `/campaign/create`, `/campaign/{id}/start` | [Campagnes](https://docs.bookivox.com/api-reference/campaigns) |
| **Base de connaissance** | `/knowledge-base/…` | [Base de connaissance](https://docs.bookivox.com/api-reference/knowledge-base) |
| **Outils** | `/tools/`, `/tools/{uuid}` | [Outils](https://docs.bookivox.com/api-reference/tools) |
| **Intégrations** | `/integrations/…` | [Intégrations](https://docs.bookivox.com/api-reference/integrations) |
| **Crédits & usage** | `/organizations/billing/credits`, `/organizations/usage/…` | [Endpoints](https://docs.bookivox.com/api-reference/endpoints) |
| **Téléphonie (lecture)** | `/organizations/telephony-configs/…` | [Téléphonie](https://docs.bookivox.com/api-reference/telephony) |
| **Catalogue de nœuds** | `/node-types`, `/node-types/{name}` | [Nœuds (graphe)](https://docs.bookivox.com/api-reference/nodes) |

## 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

| Code | Signification |
| - | - |
| `400` | Entrée invalide, ou en-tête `Authorization` présent |
| `401` | Clé API absente ou invalide |
| `402` | Crédits insuffisants |
| `403` | Opération interdite via clé API, ou filtre non autorisé |
| `404` | Ressource inexistante |
| `409` | Conflit (révision, chemin de déclencheur en doublon) |
| `422` | Erreur de validation (champs manquants ou invalides) |
| `429` | Trop de requêtes (limitation sur la base de connaissance) |
| `502` / `503` / `504` | Erreur d'un service en amont ou indisponibilité |

Détail complet, exemples réels et stratégie de nouvelle tentative : [Erreurs](https://docs.bookivox.com/api-reference/errors).

## 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**.

> **Recharger des crédits**
>
> Création de sessions de paiement et accès au portail de facturation.
> `403` : `Billing write operations are not available via API key`.

> **Provisionner la téléphonie**
>
> 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é

> [!WARNING]
>
> * 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.

> [!NOTE]
>
> 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](https://docs.bookivox.com/api-reference/quickstart)**
>
> Première requête et bonnes pratiques.

> **[Endpoints](https://docs.bookivox.com/api-reference/endpoints)**
>
> Le cheatsheet complet, avec paramètres.

> **[Flows](https://docs.bookivox.com/api-reference/flows)**
>
> Recettes de bout en bout.

> **[Erreurs](https://docs.bookivox.com/api-reference/errors)**
>
> Formats et réaction attendue.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.