Démarrage rapide

Ce guide vous mène de zéro à une intégration qui fonctionne : une clé API, un appel réussi, et une vraie livraison de webhook que vous pouvez examiner.

Tous les identifiants de ce guide (aut_…, whk_…, evt_…, agt_…) sont des chaînes opaques préfixées — jamais des UUID, et jamais quelque chose à analyser ou à valider.

Prérequis

Un espace de travail Agentova dont vous êtes administrateur, avec au moins une automatisation active. Il n’existe pas d’environnement de test séparé : si vous préférez ne pas toucher à vos vraies automatisations, utilisez un espace de travail réservé aux tests (voir plus bas).
curl et jq dans un terminal.
Un navigateur, pour ouvrir une adresse webhook.site.

Bien démarrer

Créez votre clé API

Dans Agentova, ouvrez Paramètres → API et cliquez sur Créer une clé. La clé ressemble à agk_live_ suivi de 32 caractères, et ne s’affiche qu’une seule fois. Une clé donne accès à tout l’espace de travail — la v1 ne permet pas de restreindre une clé.Gardez-la dans une variable pour la suite de ce guide :

export AGENTOVA_API_KEY="agk_live_your_key_here"

Gardez cette clé secrète. Quiconque la détient peut lire les leads et les exécutions de votre espace de travail, et mettre en pause ou activer ses automatisations. Voir Sécurité.

Faites votre premier appel

Listez les automatisations actuellement actives :

curl -s "https://core-api.agentova.ai/v1/automations?status=active" \
  -H "Authorization: Bearer $AGENTOVA_API_KEY" | jq

Une clé valide renvoie une liste paginée :

{
  "data": [
    {
      "id": "aut_example123",
      "name": "Comment replies — Support Agent",
      "type": "social_comments",
      "provider": "instagram_page",
      "agent_id": "agt_example456",
      "agent_name": "Support Agent",
      "status": "active",
      "updated_at": "2026-10-01T09:14:22Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Le name d’une automatisation dit ce qu’elle fait, suivi du nom de son agent.Choisissez une automatisation qui n’est pas critique pour votre activité — vous allez la mettre en pause quelques secondes — et gardez son id :

export AUTOMATION_ID="aut_example123"

Une clé absente ou révoquée renvoie à la place 401 invalid_api_key — voir Erreurs.

Ouvrez un récepteur pour votre premier webhook

Allez sur webhook.site et copiez l’adresse unique qu’il vous donne. Elle servira de destination à l’abonnement — pas besoin de votre propre serveur pour ce guide.

Abonnez-vous à un événement

curl -s -X POST "https://core-api.agentova.ai/v1/webhooks" \
  -H "Authorization: Bearer $AGENTOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-id",
    "events": ["automation.status_changed"]
  }' | jq

La réponse contient un secret — affiché une seule fois. C’est lui qui vous sert à vérifier l’en-tête X-Agentova-Signature de chaque livraison de cet abonnement :

{
  "id": "whk_example789",
  "url": "https://webhook.site/your-unique-id",
  "events": ["automation.status_changed"],
  "created_at": "2026-10-01T12:00:00Z",
  "disabled_at": null,
  "secret": "whsec_your_secret_here"
}

Gardez aussi l’id : il vous servira pour faire le ménage.

Provoquez l'événement

Cette étape met en pause une vraie automatisation jusqu’à ce que vous la réactiviez. Lancez les deux commandes l’une après l’autre, sur une automatisation non critique : rien de ce qui arrive pendant une pause n’est rattrapé ensuite — un e-mail reçu pendant que son automatisation est en pause ne reçoit pas de réponse (voir Concepts).

Mettez en pause l’automatisation choisie, puis réactivez-la :

curl -s -X PATCH "https://core-api.agentova.ai/v1/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $AGENTOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}' | jq

curl -s -X PATCH "https://core-api.agentova.ai/v1/automations/$AUTOMATION_ID" \
  -H "Authorization: Bearer $AGENTOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}' | jq

Rafraîchissez la page webhook.site : deux livraisons arrivent, une par changement de statut — en général en quelques secondes —, chacune avec un en-tête X-Agentova-Signature et un corps comme celui-ci, où data est l’automatisation complète :

{
  "id": "evt_example012",
  "type": "automation.status_changed",
  "created_at": "2026-10-01T12:00:05Z",
  "data": {
    "id": "aut_example123",
    "name": "Comment replies — Support Agent",
    "type": "social_comments",
    "provider": "instagram_page",
    "agent_id": "agt_example456",
    "agent_name": "Support Agent",
    "status": "paused",
    "updated_at": "2026-10-01T12:00:05Z"
  }
}

Les deux livraisons peuvent arriver dans n’importe quel ordre : pour connaître le dernier statut, comparez data.updated_at, pas l’ordre d’arrivée. Pour vérifier une signature vous-même, Webhooks et signatures donne du code en Node.js, Python et PHP, ainsi qu’un vecteur de test.

Faites le ménage

curl -s -o /dev/null -w "%{http_code}\n" -X DELETE \
  "https://core-api.agentova.ai/v1/webhooks/whk_your_subscription_id" \
  -H "Authorization: Bearer $AGENTOVA_API_KEY"

204 signifie que l’abonnement est supprimé. Si vous avez créé la clé uniquement pour ce guide, révoquez-la dans Paramètres → API.

Tester sans toucher à la production

Il n’y a ni bac à sable ni clé de test : chaque clé est une clé réelle, sur un vrai espace de travail. Pour expérimenter sans risque, créez dans Agentova un espace de travail réservé au développement et aux tests, avec ses propres automatisations et sa propre clé, et gardez votre espace de travail de production pour le trafic réel.

Découvrir l’API sans espace de travail

Pour découvrir l’API sans compte Agentova, lancez une simulation générée depuis le contrat (le même fichier que celui dont est construit l’onglet Référence de l’API). Elle répond à chaque route avec ses exemples documentés, mais ne garde aucun état, n’envoie pas de webhook et n’applique pas de limite de requêtes.

npx @stoplight/prism-cli mock https://docs.agentova.ai/openapi/openapi-v1.yaml

Utilisez ensuite http://127.0.0.1:4010 à la place de https://core-api.agentova.ai/v1 dans les commandes ci-dessus.

Pour aller plus loin

Concepts

Ce que couvre l’API : automatisations, sources de leads, exécutions.

Webhooks et signatures

Livraison, nouveaux essais et vérification de la signature.

Erreurs

La liste complète des codes d’erreur et comment les traiter.

Limites de requêtes

Quotas, en-têtes, et ce qui se passe au-delà.

Bien démarrer

Guides

Aide

Nouveautés

Prérequis

Bien démarrer

Tester sans toucher à la production

Découvrir l’API sans espace de travail

Pour aller plus loin

Concepts

Webhooks et signatures

Erreurs

Limites de requêtes

​Prérequis

​Bien démarrer

​Tester sans toucher à la production

​Découvrir l’API sans espace de travail

​Pour aller plus loin

Concepts

Webhooks et signatures

Erreurs

Limites de requêtes

Prérequis

Bien démarrer

Tester sans toucher à la production

Découvrir l’API sans espace de travail

Pour aller plus loin