API Overview - HaloAgents

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. Routes that scope data by user_id require Identity Verification: without an Identity Secret, identified requests are rejected with 403.

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)

Identity verification prevents user impersonation and is required for any request that names a user. 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. Anonymous requests (no user_id, or user_id: "anonymous") need no token.

// 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 a non-anonymous user_id is provided without a valid user_token, the request is rejected with a 403 error. Workspaces that have not generated an Identity Secret yet receive the same 403 for identified requests (the server fails closed rather than trusting an unverifiable user_id). 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

Limit	Value
Max message length	10,000 characters
Max conversation history	50 messages
Max behavior context	5,000 characters
Max custom fields payload	10,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 batch	100
Max event metadata	10,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.

​Base URL

​Authentication

​Identity Verification (JWT)

​CORS

​Rate Limits

​Common Response Format

​Endpoints

POST /chat

POST /chat/stream

POST /tickets/create

POST /events

POST /users/identify

POST /companies/identify

POST /series

GET /config

Base URL

Authentication

Identity Verification (JWT)

CORS

Rate Limits

Common Response Format

Endpoints