API Reference

The HeartBeatAgents API lets you invoke any agent programmatically via a single HTTP endpoint. Each agent gets its own endpoint URL and API keys, generated from the agent settings page. The API works with any HTTP client: cURL, Python, JavaScript, Zapier, Make, n8n, or your own code.

Endpoint URL

Every agent has a unique invoke endpoint:

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

Authentication

All requests require an API key passed as a Bearer token, generated from the Agent API section on your agent's settings page.

Authorization: Bearer hb_agent_YOUR_KEY

API keys are scoped to a single agent. Each agent can have multiple active keys, so you can rotate credentials without downtime. Revoke compromised keys immediately from the agent settings page.

Invoke Agent (Synchronous)

Set wait: true to get the agent's response in a single call. The request blocks until the agent finishes processing.

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

Invoke Agent (Async: Fire and Poll)

Omit wait or set it to false for non-blocking execution. The invoke call returns immediately with a 202 status and a conversation ID.

Step 1: Fire (returns 202 immediately)

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

Step 2: Poll for result

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

Statuses: "pending" | "running" | "completed" | "failed"

Request Body

Reliability settings

Three toggles, all under Settings → Invoke API, all taking effect on the next request with no restart needed:

• Idempotent retries: once turned on, callers can pass an Idempotency-Key header on POST /invoke. A retry with the same key returns the original dispatch instead of starting a second run, which matters for any HTTP automation tool (n8n, Zapier, Make) with its own retry policy.
• Webhook delivery: once turned on, POST /invoke accepts a callback_url field. On completion, the platform POSTs a signed JSON body to that URL, with an HMAC-SHA256 signature in the X-HBA-Signature header you can verify. Turn it off to force every caller onto the polling API instead.
• Retry-After hints: once turned on, an async 202 response and a /status response for a still-running agent both carry a Retry-After header and JSON field, so a client that respects it backs off automatically instead of polling on a fixed interval. On a long-running agent this cuts /status polling load by roughly 30x.

Memory Endpoints

Each agent has its own long-term memory that persists across conversations. See Core Concepts for the underlying model.

GET /agents/:id/memory

Search an agent's memory. Supports filtering by memory type and semantic search via the query parameter.

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

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

Delete a specific memory entry.

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

// Response 204 No Content

Related

• Core Concepts: agents, conversations, and memory as concepts, independent of the API
• Self-Hosting: exposing {YOUR_URL} outside your own network for webhooks and callbacks to reach