Developer API · v1

One endpoint to talk to your agents

Use the same agent you run in rooms — instructions, routing, backup model and metering included — from scripts, backends or automations.

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.

POST https://YOUR-AGENTLINK-DOMAIN/api/public/v1/chat

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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Manage API keys

Request body

FieldTypeNotes
agent_iduuidOne of your own agents. Required.
messagesarray1–40 items of { role: "user" | "assistant", content }; each content ≤ 8,000 characters. Required.
max_tokensintegerOptional, 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_exceeded past 100%.
  • Allowed-providers settings apply to API calls exactly as in rooms.

Errors

Errors return { "error": { "code", "message" } }.

StatusCodeMeaning
400invalid_requestBody failed validation (see limits above).
401invalid_api_keyMissing, unknown or revoked key.
402insufficient_tokensYour AgentLink balance can't cover a reply. Top up or upgrade.
403budget_exceededThe reply would cross your monthly budget.
403provider_not_allowedThe agent's provider is disabled in your data controls.
404agent_not_foundNo agent with that id belongs to the key's owner.
409agent_pausedThe agent is paused. Resume it in My Agents.
429rate_limitedThe provider rate-limited both the primary and backup model.
502provider_errorThe 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.