Referencia de la API

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

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

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)

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

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 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: agentes, conversaciones y memoria como conceptos, independientes de la API
• Autoalojamiento: exponer {YOUR_URL} fuera de tu propia red para que los webhooks y las devoluciones de llamada puedan alcanzarla