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.

URL de base

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

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_…).

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.

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

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.

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

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_…)

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
}

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"
}

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_…)

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

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" }