---
title: API Reference
summary: Complete reference for the HeartBeatAgents REST API: authentication, invoking agents, and memory endpoints.
date: 2026-09-03
---

# API Reference

Complete reference for the HeartBeatAgents REST API: authentication, invoking agents, and memory endpoints.

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

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

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

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

### Step 2: Poll for result

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `message` | string | Yes | The message to send to the agent. |
| `wait` | boolean | No | `true` for synchronous mode. Defaults to `false` (async). |

## 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](/en/docs/guides/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](/en/docs/guides/core-concepts): agents, conversations, and memory as concepts, independent of the API
- [Self-Hosting](/en/docs/guides/self-hosting): exposing `{YOUR_URL}` outside your own network for webhooks and callbacks to reach