Référence API

L'API HeartBeatAgents permet d'invoquer n'importe quel agent par programmation via un point de terminaison HTTP unique. Chaque agent dispose de sa propre URL de point de terminaison et de ses propres clés API, générées depuis la page de paramètres de l'agent. L'API fonctionne avec n'importe quel client HTTP : cURL, Python, JavaScript, Zapier, Make, n8n, ou votre propre code.

URL du point de terminaison

Chaque agent dispose d'un point de terminaison d'invocation unique :

{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke

Authentification

Toutes les requêtes nécessitent une clé API transmise en tant que jeton Bearer, générée depuis la section Agent API de la page de paramètres de votre agent.

Authorization: Bearer hb_agent_YOUR_KEY

Les clés API sont limitées à un seul agent. Chaque agent peut avoir plusieurs clés actives, ce qui permet de faire tourner les identifiants sans interruption de service. Révoquez immédiatement toute clé compromise depuis la page de paramètres de l'agent.

Invoquer un agent (synchrone)

Définissez wait: true pour obtenir la réponse de l'agent en un seul appel. La requête reste bloquée jusqu'à ce que l'agent termine son traitement.

cURL

curl -X POST {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke \
  -H "Authorization: Bearer hb_agent_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello agent!", "wait": true}'

Python

import requests

response = requests.post(
    "{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke",
    headers={"Authorization": "Bearer hb_agent_YOUR_KEY"},
    json={"message": "Hello agent!", "wait": True},
    timeout=300,
)
print(response.json()["response"])

JavaScript

const response = await fetch(
  "{YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer hb_agent_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Hello agent!", wait: true }),
  }
);
const { status, response: reply } = await response.json();
console.log(reply);

Invoquer un agent (asynchrone : lancer et interroger)

Omettez wait ou définissez-le à false pour une exécution non bloquante. L'appel d'invocation renvoie immédiatement un statut 202 et un identifiant de conversation.

Étape 1 : lancer (renvoie 202 immédiatement)

curl -X POST {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke \
  -H "Authorization: Bearer hb_agent_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello agent!"}'

Étape 2 : interroger le résultat

curl {YOUR_URL}/api/v1/agents/{AGENT_ID}/invoke/{CONVERSATION_ID}/status \
  -H "Authorization: Bearer hb_agent_YOUR_KEY"

Statuts : "pending" | "running" | "completed" | "failed"

Corps de la requête

• message (chaîne, requis) : le message à envoyer à l'agent.
• wait (booléen, optionnel) : définir à true pour le mode synchrone. Par défaut à false (asynchrone).

Paramètres de fiabilité

Trois options, toutes sous Paramètres → API d'invocation, prenant effet dès la requête suivante sans redémarrage nécessaire :

• Nouvelles tentatives idempotentes : une fois activée, les appelants peuvent transmettre un en-tête Idempotency-Key sur POST /invoke. Une nouvelle tentative avec la même clé renvoie l'envoi original au lieu de démarrer une seconde exécution, ce qui compte pour tout outil d'automatisation HTTP (n8n, Zapier, Make) ayant sa propre politique de nouvelle tentative.
• Livraison par webhook : une fois activée, POST /invoke accepte un champ callback_url. À la fin du traitement, la plateforme envoie une requête POST avec un corps JSON signé à cette URL, avec une signature HMAC-SHA256 dans l'en-tête X-HBA-Signature que vous pouvez vérifier. Désactivez-la pour forcer tous les appelants à utiliser l'API d'interrogation à la place.
• Indications Retry-After : une fois activée, une réponse asynchrone 202 et une réponse /status pour un agent encore en cours d'exécution portent toutes deux un en-tête Retry-After et un champ JSON, afin qu'un client qui le respecte ralentisse automatiquement au lieu d'interroger à intervalle fixe. Sur un agent de longue durée, cela réduit la charge d'interrogation /status d'environ 30 fois.

Points de terminaison de mémoire

Chaque agent dispose de sa propre mémoire à long terme, persistante entre les conversations. Voir Concepts de base pour le modèle sous-jacent.

GET /agents/:id/memory

Recherche dans la mémoire d'un agent. Prend en charge le filtrage par type de mémoire et la recherche sémantique via le paramètre query.

GET {YOUR_URL}/api/v1/agents/{AGENT_ID}/memory?type=semantic&query=customer+preferences&limit=5
Authorization: Bearer hb_agent_YOUR_KEY

// Réponse 200
{
  "data": [
    {
      "id": "mem_001",
      "type": "semantic",
      "content": "Customer prefers email communication over Slack",
      "confidence": 0.92,
      "source_conversation": "conv_xyz789",
      "created_at": "2026-02-08T09:00:00Z"
    }
  ],
  "total": 1
}

DELETE /agents/:id/memory/:memoryId

Supprime une entrée de mémoire spécifique.

DELETE {YOUR_URL}/api/v1/agents/{AGENT_ID}/memory/mem_001
Authorization: Bearer hb_agent_YOUR_KEY

// Réponse 204 No Content

À voir aussi

• Concepts de base : les agents, conversations et la mémoire en tant que concepts, indépendamment de l'API
• Auto-hébergement : exposer {YOUR_URL} hors de votre propre réseau pour que les webhooks et rappels puissent l'atteindre