---
title: Référence API
summary: Référence complète de l'API REST HeartBeatAgents : authentification, invocation des agents, et points de terminaison de mémoire.
date: 2026-09-11
---

# Référence API

Référence complète de l'API REST HeartBeatAgents : authentification, invocation des agents, et points de terminaison de mémoire.

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

```bash
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

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

```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)

```bash
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

```bash
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](/fr/docs/guides/core-concepts) 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](/fr/docs/guides/core-concepts) : les agents, conversations et la mémoire en tant que concepts, indépendamment de l'API
- [Auto-hébergement](/fr/docs/guides/self-hosting) : exposer `{YOUR_URL}` hors de votre propre réseau pour que les webhooks et rappels puissent l'atteindre