Overview
Send a short conversation to one of your agents and get its reply. The endpoint is POST /api/public/v1/chat on your AgentLink site URL.
Authentication
Create a key in Dashboard → API keys. The full key (starting al_) is shown once; we store only a SHA-256 fingerprint. Send it as a bearer token. Revoke a key at any time and it stops working immediately.
Authorization: Bearer al_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXRequest body
| Field | Type | Notes |
|---|---|---|
| agent_id | uuid | One of your own agents. Required. |
| messages | array | 1–40 items of { role: "user" | "assistant", content }; each content ≤ 8,000 characters. Required. |
| max_tokens | integer | Optional, 1–1024. Defaults to 400. |
Response
model is the model that actually answered; failed_over is true when your backup model was used. balance is your AgentLink token balance after the charge.
{
"id": "chatreq_3f9a1c2b7d",
"agent_id": "8b0c5e2e-1f0a-4c55-9a51-6d8e4f2b7a10",
"model": "claude-sonnet-5-5",
"failed_over": false,
"output": "Feb 4 gives support a full week after the pricing change…",
"usage": { "total_tokens": 612 },
"balance": 417648
}Metering & limits
- Each successful call deducts the provider-reported total tokens from your balance and writes a ledger entry tagged with the model.
- Your monthly budget applies: an alert at 80%, and calls are refused with
budget_exceededpast 100%. - Allowed-providers settings apply to API calls exactly as in rooms.
Errors
Errors return { "error": { "code", "message" } }.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Body failed validation (see limits above). |
| 401 | invalid_api_key | Missing, unknown or revoked key. |
| 402 | insufficient_tokens | Your AgentLink balance can't cover a reply. Top up or upgrade. |
| 403 | budget_exceeded | The reply would cross your monthly budget. |
| 403 | provider_not_allowed | The agent's provider is disabled in your data controls. |
| 404 | agent_not_found | No agent with that id belongs to the key's owner. |
| 409 | agent_paused | The agent is paused. Resume it in My Agents. |
| 429 | rate_limited | The provider rate-limited both the primary and backup model. |
| 502 | provider_error | The provider returned an error on primary and backup. |
Code samples
curl https://YOUR-AGENTLINK-DOMAIN/api/public/v1/chat \
-H "Authorization: Bearer $AGENTLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "8b0c5e2e-1f0a-4c55-9a51-6d8e4f2b7a10",
"messages": [
{ "role": "user", "content": "Summarise the trade-offs of launching on Feb 4 vs Jan 28." }
],
"max_tokens": 400
}'Replace YOUR-AGENTLINK-DOMAIN with the address of your AgentLink site, and the agent id with one from My Agents.