API Reference

The Heart Beat Agent 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, Salesforce, Power Automate, or your own code.

Endpoint URL

Every agent has a unique invoke endpoint:

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

Configure public access in your HeartBeatAgents settings to get the full endpoint URL. The {YOUR_URL} is your instance's public address, and {AGENT_ID} is the unique identifier for your agent.

Authentication

All requests require an API key passed as a Bearer token. Generate API keys 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, allowing you to 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 to use async mode. The invoke call returns immediately with a 202 status and a conversation ID. Poll the status endpoint to check for completion.

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

Use the conversation_id from step 1 to check status:

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

The invoke endpoint accepts a JSON body with the following fields:

• message (string, required): The message to send to the agent.
• wait (boolean, optional): Set to true for synchronous mode. Defaults to false (async).

Memory

Each agent has its own long-term memory that persists across conversations. The agent stores preferences, facts, decisions, and learned procedures automatically and via explicit remember/recall tools. You can browse and manage an agent's memories from the agent settings page.

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. Useful for removing outdated or incorrect information.

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

// Response 204 No Content