---
title: Referencia de la API
summary: Referencia completa de la API REST de HeartBeatAgents: autenticación, invocación de agentes, y endpoints de memoria.
date: 2026-09-11
---

# Referencia de la API

Referencia completa de la API REST de HeartBeatAgents: autenticación, invocación de agentes, y endpoints de memoria.

La API de HeartBeatAgents te permite invocar cualquier agente mediante programación a través de un único endpoint HTTP. Cada agente tiene su propia URL de endpoint y claves de API, generadas desde la página de configuración del agente. La API funciona con cualquier cliente HTTP: cURL, Python, JavaScript, Zapier, Make, n8n, o tu propio código.

## URL del endpoint

Cada agente tiene un endpoint de invocación único:

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

## Autenticación

Todas las solicitudes requieren una clave de API enviada como token Bearer, generada desde la sección Agent API en la página de configuración de tu agente.

```
Authorization: Bearer hb_agent_YOUR_KEY
```

Las claves de API están limitadas a un solo agente. Cada agente puede tener varias claves activas, lo que permite rotar credenciales sin interrupciones. Revoca de inmediato cualquier clave comprometida desde la página de configuración del agente.

## Invocar un agente (síncrono)

Establece `wait: true` para obtener la respuesta del agente en una sola llamada. La solicitud se bloquea hasta que el agente termina de procesar.

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

## Invocar un agente (asíncrono: disparar y consultar)

Omite `wait` o establécelo en `false` para una ejecución no bloqueante. La llamada de invocación devuelve de inmediato un estado `202` y un ID de conversación.

### Paso 1: disparar (devuelve 202 de inmediato)

```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!"}'
```

### Paso 2: consultar el resultado

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

**Estados:** `"pending"` | `"running"` | `"completed"` | `"failed"`

## Cuerpo de la solicitud

- `message` (cadena, obligatorio): el mensaje que se enviará al agente.
- `wait` (booleano, opcional): establécelo en `true` para el modo síncrono. Por defecto es `false` (asíncrono).

## Configuración de fiabilidad

Tres opciones, todas en **Configuración → Invoke API**, y todas surten efecto en la siguiente solicitud sin necesidad de reiniciar:

- **Reintentos idempotentes**: una vez activada, quien llama puede incluir un encabezado `Idempotency-Key` en `POST /invoke`. Un reintento con la misma clave devuelve el envío original en lugar de iniciar una segunda ejecución, algo relevante para cualquier herramienta de automatización HTTP (n8n, Zapier, Make) con su propia política de reintentos.
- **Entrega por webhook**: una vez activada, `POST /invoke` acepta un campo `callback_url`. Al completarse, la plataforma envía mediante POST un cuerpo JSON firmado a esa URL, con una firma HMAC-SHA256 en el encabezado `X-HBA-Signature` que puedes verificar. Desactívala para forzar a todos los llamantes a usar la API de consulta en su lugar.
- **Indicaciones Retry-After**: una vez activada, tanto una respuesta asíncrona `202` como una respuesta `/status` de un agente aún en ejecución incluyen un encabezado `Retry-After` y un campo JSON equivalente, de modo que un cliente que lo respete espera automáticamente en lugar de consultar a un intervalo fijo. En un agente de larga duración, esto reduce la carga de consultas a `/status` en aproximadamente 30 veces.

## Endpoints de memoria

Cada agente tiene su propia memoria a largo plazo que persiste entre conversaciones. Ver [Conceptos básicos](/es/docs/guides/core-concepts) para el modelo subyacente.

### GET /agents/:id/memory

Busca en la memoria de un agente. Admite filtrado por tipo de memoria y búsqueda semántica mediante el parámetro `query`.

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

// Respuesta 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

Elimina una entrada de memoria específica.

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

// Respuesta 204 No Content
```

## Relacionado

- [Conceptos básicos](/es/docs/guides/core-concepts): agentes, conversaciones y memoria como conceptos, independientes de la API
- [Autoalojamiento](/es/docs/guides/self-hosting): exponer `{YOUR_URL}` fuera de tu propia red para que los webhooks y las devoluciones de llamada puedan alcanzarla