Référence API
=============

L'API REST Manivox.ai vous permet de lire les données d'agents et d'appels par programme. Tous les endpoints retournent du JSON et requièrent une clé API.

![API keys and endpoint reference](/docs/api-keys-dark.gif)

URL de base
-----------

```
https://www.manivox.ai/api/v1
```

Tous les chemins de cette référence sont relatifs à l'URL de base. Une URL de requête complète ressemble à :  
`https://www.manivox.ai/api/v1/accounts/{id}/calls`

Endpoints
---------

L'API publique `/v1` est en lecture seule. Tous les endpoints utilisent la méthode `GET` et s'authentifient avec une clé API (Bearer `la_…`).

Méthode et cheminDescriptionDocumenté dans   `GET /v1/ping`Health check, vérifie votre clé API[Health check](#health-check) `GET /v1/accounts`Liste les comptesCette page `GET /v1/accounts/{id}`Détail d'un compteCette page `GET /v1/accounts/{id}/agents`Liste les agents du compte[API Agents](https://www.manivox.ai/docs/api/agents) `GET /v1/accounts/{id}/calls`Liste les appels du compte[API Appels](https://www.manivox.ai/docs/api/calls) `GET /v1/accounts/{id}/connections`Liste les connexions du compteCette page `GET /v1/accounts/{id}/connections/{connectionId}`Détail d'une connexionCette page `GET /v1/calls/{id}/handoff`Résumé de transfert et variables collectées[API Appels](https://www.manivox.ai/docs/api/calls) `GET /v1/calls/{id}/transcript`Transcription tour par tour, avec les appels d'outils/API en option[API Appels](https://www.manivox.ai/docs/api/calls) `GET /v1/calls/{id}/recording`Télécharge l'enregistrement de l'appel (WAV)[API Appels](https://www.manivox.ai/docs/api/calls) Authentification
----------------

Chaque requête doit inclure votre clé API comme Bearer token dans l'en-tête `Authorization` :

```
curl https://www.manivox.ai/api/v1/ping \
-H "Authorization: Bearer la_YOUR_API_KEY"
```

Les clés API commencent par le préfixe `la_`. Une clé au format invalide, ou qui n'existe pas (supprimée ou faute de frappe), retourne `401` ; une clé révoquée ou désactivée (inactive) retourne `403` avec `API key is inactive`.

### Activer l'accès à l'API

L'accès à l'API s'active par organisation. Demandez à votre interlocuteur Manivox d'activer l'accès API pour votre organisation. Lorsque l'accès est activé et que l'organisation n'a encore aucune clé active, une première clé est générée automatiquement et affichée **une seule fois** : copiez-la immédiatement. Tant que l'accès n'est pas activé, chaque requête `/v1` retourne `403`.

Une clé API donne un accès en lecture à **toute la surface `/v1`** de votre organisation, elle n'est restreinte à aucun endpoint en particulier. Quiconque détient la clé peut interroger les comptes, connexions, données de handoff d'appel, transcriptions et enregistrements de votre organisation : traitez-la comme un secret.

### Gérer vos clés API

Une fois l'accès activé, les admins de l'organisation gèrent eux-mêmes les clés depuis le dashboard :

1. Connectez-vous au dashboard Manivox.ai avec un compte **admin de l'organisation** (la gestion des clés est réservée aux admins)
2. Allez dans **Paramètres → API**
3. Générez une nouvelle clé et donnez-lui un nom descriptif (ex : `production-server`)
4. Copiez la valeur complète `la_…` depuis le bandeau de copie immédiatement : elle n'est affichée qu'une fois et n'est jamais stockée en clair

**Gardez votre clé API secrète.** Ne la commitez jamais dans un dépôt de versions et ne l'exposez pas dans du code côté client. Stockez-la dans une variable d'environnement ou un gestionnaire de secrets (Vault, AWS Secrets Manager, etc.).

### Cycle de vie d'une clé

Depuis **Paramètres → API**, vous pouvez révoquer une clé (elle devient inactive et retourne immédiatement `403`) ou la supprimer entièrement. Il n'y a pas de bouton de rotation : pour faire tourner une clé, générez-en une nouvelle et supprimez l'ancienne. Une organisation peut détenir plusieurs clés à la fois.

Réponse d'erreurCause   `401 Authentication required`Aucun en-tête `Authorization` envoyé `401 Invalid API key format`La clé ne commence pas par `la_` `401 Invalid API key`Clé introuvable (supprimée ou faute de frappe) `403 API key is inactive`Clé révoquée, désactivée ou inactive `403 API key has expired`La clé a dépassé sa date d'expiration `403 API access is not enabled for this organization`L'API est désactivée pour cette organisation Pagination
----------

Les endpoints de liste utilisent une pagination basée sur l'offset avec les paramètres de requête `limit` et `offset`. La `limit` maximale est de `100`.

```
# Récupérer les appels 51-100
GET /v1/accounts/{id}/calls?limit=50&offset=50
```

La réponse inclut toujours un champ `total` avec le nombre total d'enregistrements correspondants.

Format d'erreur
---------------

Toutes les erreurs retournent un objet JSON avec un champ `error` décrivant ce qui a mal tourné :

```
// 401, clé API absente ou invalide
{ "error": "Invalid API key" }

// 404, ressource introuvable
{ "error": "Account not found" }

// 422, paramètre de requête invalide
{ "error": "Invalid \"from\" datetime format. Use ISO 8601 (e.g. 2026-01-15T10:00:00)" }

// 429, limite d'appels concurrents
{
"error": "Concurrent call limit reached",
"active_calls": 10,
"max_concurrent_calls": 10
}
```

Codes de statut HTTP
--------------------

CodeSignification   `200 OK`Requête réussie `401 Unauthorized`Clé API absente ou invalide `403 Forbidden`Clé inactive, expirée, ou API désactivée pour l'org `404 Not Found`La ressource n'existe pas ou n'est pas dans votre org `422 Unprocessable`Valeur de paramètre de requête invalide `429 Too Many Requests`Limite de débit dépassée, s'applique à tous les endpoints `/v1` (voir [Limites de débit](#rate-limits)) `500 Server Error`Quelque chose a mal tourné de notre côté, réessayez avec backoff Limites de débit
----------------

Chaque endpoint `/v1` est limité à **120 requêtes par minute et par organisation** (la limite est partagée entre toutes les clés de votre organisation, pas par clé). Le plafond exact est configurable par organisation, contactez-nous si vous avez besoin de l'augmenter. Dépasser la limite retourne `429 Too Many Requests` : appliquez un backoff puis réessayez.

Journalisation des requêtes
---------------------------

Chaque requête `/v1` est journalisée, y compris les appels réussis et les rejets `401` / `403` / `429`. Chaque entrée enregistre l'horodatage, la méthode HTTP, le chemin, le statut de réponse, l'IP cliente, le user agent et la durée en millisecondes. Les journaux sont purgés automatiquement au bout d'environ 90 jours.

Vous pouvez consulter cette activité dans le dashboard sous **Paramètres → API → Activité API récente** (les requêtes les plus récentes, avec l'heure, la requête, le statut et l'IP). Les opérateurs Manivox.ai voient la même activité récente dans la carte **API Access** de l'organisation.

Comptes et connexions
---------------------

Un **compte** est l'un des clients finaux de votre organisation (l'entité pour laquelle un agent agit). Une **connexion** est un toolkit tiers (CRM, agenda, etc.) lié à un compte pour que les agents puissent appeler ses outils. Les quatre endpoints ci-dessous sont en lecture seule et s'authentifient avec une clé API.

### Lister les comptes

Retourne les comptes de l'organisation, triés par nom.

```
GET /v1/accounts
```

**Auth :** clé API (Bearer `la_…`)

ParamètreTypeDéfautDescription   `limit`entier100Nombre max d'enregistrements à retourner (max 100) `offset`entier0Enregistrements à ignorer ```
curl "https://www.manivox.ai/api/v1/accounts?limit=50" \
-H "Authorization: Bearer la_YOUR_API_KEY"
```

**Réponse, 200 OK**

```
{
"data": [
{
"id": "acc_01hx...",
"name": "Acme Corp",
"city": "Paris",
"country": "FR",
"created_at": "2026-05-26T14:30:00+00:00"
}
],
"total": 12
}
```

ChampTypeDescription   `id`stringIdentifiant unique du compte `name`stringNom du compte `city`string | nullVille `country`string | nullCode pays `created_at`ISO 8601Date de création du compte ### Détail d'un compte

Retourne un seul compte avec son adresse complète, son représentant et son statut KYC.

```
GET /v1/accounts/{id}
```

**Auth :** clé API (Bearer `la_…`)

**Réponse, 200 OK**

```
{
"id": "acc_01hx...",
"name": "Acme Corp",
"country": "FR",
"address": {
"street_number": "10",
"street": "Rue de la Paix",
"postal_code": "75002",
"city": "Paris"
},
"representative": {
"first_name": "Marie",
"last_name": "Dupont",
"role": "CEO",
"email": "marie@acme.example",
"phone": "+33612345678"
},
"kyc_status": "VALIDATED",
"created_at": "2026-05-26T14:30:00+00:00"
}
```

ChampTypeDescription   `id`stringIdentifiant unique du compte `name`stringNom du compte `country`string | nullCode pays `address`objectAdresse postale : `street_number`, `street`, `postal_code`, `city` `representative`objectReprésentant légal : `first_name`, `last_name`, `role`, `email`, `phone` `kyc_status`enum`DRAFT`, `PENDING`, `VALIDATED` ou `REJECTED` `created_at`ISO 8601Date de création du compte **Erreur, 404 Not Found** : le compte n'existe pas pour l'organisation de cette clé API :

```
{ "error": "Account not found" }
```

### Lister les connexions

Retourne les connexions tierces liées à un compte, les plus récentes d'abord.

```
GET /v1/accounts/{id}/connections
```

**Auth :** clé API (Bearer `la_…`)

ParamètreTypeDéfautDescription   `limit`entier100Nombre max d'enregistrements à retourner (max 100) `offset`entier0Enregistrements à ignorer `status`string-Filtre par statut : `PENDING`, `ACTIVE`, `EXPIRED` ou `ERROR` (insensible à la casse) ```
# Uniquement les connexions actives
curl "https://www.manivox.ai/api/v1/accounts/acc_01hx.../connections?status=active" \
-H "Authorization: Bearer la_YOUR_API_KEY"
```

**Réponse, 200 OK**

```
{
"data": [
{
"id": "con_01hx...",
"reference": "acme-hubspot",
"toolkit_slug": "hubspot",
"toolkit_name": "HubSpot",
"status": "ACTIVE",
"created_at": "2026-05-26T14:30:00+00:00",
"updated_at": "2026-05-26T14:35:00+00:00"
}
],
"total": 3
}
```

ChampTypeDescription   `id`stringIdentifiant unique de la connexion `reference`string | nullVotre référence pour la connexion `toolkit_slug`string | nullSlug du toolkit (ex : `hubspot`) `toolkit_name`string | nullNom lisible du toolkit `status`enum`PENDING`, `ACTIVE`, `EXPIRED` ou `ERROR` `oauth_redirect_url`stringPrésent uniquement lorsque `status` vaut `PENDING` : l'URL pour terminer le flux OAuth `created_at`ISO 8601Date de création de la connexion `updated_at`ISO 8601Date de dernière mise à jour de la connexion ### Détail d'une connexion

Retourne une seule connexion par son id. L'objet a la même forme qu'une entrée de la liste ci-dessus.

```
GET /v1/accounts/{id}/connections/{connectionId}
```

**Auth :** clé API (Bearer `la_…`)

```
{
"id": "con_01hx...",
"reference": "acme-hubspot",
"toolkit_slug": "hubspot",
"toolkit_name": "HubSpot",
"status": "ACTIVE",
"created_at": "2026-05-26T14:30:00+00:00",
"updated_at": "2026-05-26T14:35:00+00:00"
}
```

**Erreurs, 404 Not Found**

```
// Le compte n'existe pas pour l'organisation de cette clé API
{ "error": "Account not found" }

// Le compte existe mais l'id de connexion est inconnu
{ "error": "Connection not found" }
```

Explorateur d'API interactif
----------------------------

Le dashboard intègre une référence API sous **Paramètres → API → Documentation API** : chaque endpoint `/v1` est présenté sous forme de carte dépliable avec ses paramètres, un exemple `curl` prêt à copier et un exemple de réponse. Chaque carte dispose aussi d'un testeur **Essayer** en direct — collez votre clé API (et un identifiant d'appel lorsque l'endpoint en a besoin) et lancez une vraie requête sans quitter le navigateur. L'URL de base et le format de l'en-tête `Authorization` sont affichés en haut.

Health check
------------

Utilisez l'endpoint ping pour vérifier votre clé API et la connectivité :

```
curl https://www.manivox.ai/api/v1/ping \
-H "Authorization: Bearer la_YOUR_API_KEY"

# 200 OK
{ "status": "ok", "organization_id": "org_01hx...", "timestamp": "2026-06-29T10:00:00+00:00" }
```