Skip to main content

​
Base URL

All HaloAgents SDK endpoints live under a single base URL: 
https://api.haloagents.ai/api/sdk
For example, the chat endpoint is at: 
POST https://api.haloagents.ai/api/sdk/chat

​
Authentication

Most endpoints require your publishable widget key in the Authorization header: 
Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx
The same ab_live_... value is embedded in your install snippet under Setup > Install. It identifies your organization on each request. It is designed to be public (like Stripe’s pk_live_), not a server-only secret.
A dedicated server-only API key class is on the roadmap. This page will be updated when it ships. Until then, prefer calling the REST API from your backend and enabling Identity Verification for any route that scopes data by user_id.
The Config endpoint is the only exception — it is unauthenticated and uses an org_id query parameter instead. This allows the widget to load agent configuration before authentication is established.

​
Identity Verification (JWT)

For additional security, you can enable identity verification to prevent user impersonation. When enabled, your backend signs a JWT containing the user_id (and optional trusted claims like email, role, plan) using your Identity Secret (ha_secret_...), and passes it as user_token in chat requests. 
// Server-side: generate the JWT
const jwt = require("jsonwebtoken");

const userToken = jwt.sign(
  {
    user_id: userId,     // preferred; "sub" is also accepted as a fallback
    email: user.email,   // optional trusted claim
    role: user.role,     // optional trusted claim
  },
  process.env.HALOAGENTS_SECRET_KEY,
  { algorithm: "HS256", expiresIn: "24h" }
);
If identity verification is enabled and a non-anonymous user_id is provided without a valid user_token, the request is rejected with a 403 error. See Identity Verification for full setup instructions.

​
CORS

All endpoints support CORS with Access-Control-Allow-Origin: *. You can call them from any domain. Preflight (OPTIONS) requests are handled automatically.

​
Rate Limits

LimitValue
Max message length10,000 characters
Max conversation history50 messages
Max behavior context5,000 characters
Max custom fields payload10,000 characters
Max user traits + context payload (/users/identify)20,000 bytes
Max company traits + context payload (/companies/identify)50,000 bytes
Max events per batch100
Max event metadata10,000 bytes per event

​
Common Response Format

Successful responses return JSON with relevant data. Error responses follow this format: 
{
  "error": "Description of what went wrong"
}
HTTP status codes:
  • 200 — Success
  • 400 — Invalid request (missing fields, validation failure)
  • 401 — Missing or invalid API key
  • 403 — Identity verification failed (invalid or expired user_token)
  • 404 — Resource not found (no active agent, etc.)
  • 500 — Server error

​
Endpoints

POST /chat

Send a message and get a complete AI response.

POST /chat/stream

Send a message and get a streaming AI response.

POST /tickets/create

Create a support ticket programmatically.

POST /events

Send behavioral tracking events.

POST /users/identify

Create or update an end user record.

POST /companies/identify

Create or update a company record.

POST /series

Enroll or remove users from email series.

GET /config

Get the active agent configuration for an org.