Run your Central AI agents programmatically from any backend, app, or website. Send a message and get the agent response back. The agent always executes inside Central AI and usage is billed to your account; the API only triggers it.
POST /api/v1/run{
"Authorization": "Bearer cai_live_YOUR_KEY",
"Content-Type": "application/json"
}{
"client_agent_id": "string (required unless agent_id is sent) - an agent you added to your account",
"agent_id": "string (required unless client_agent_id is sent) - marketplace agent id you have added",
"message": "string (required) - the user input for the agent"
}Authorization: Bearer cai_live_<key>. Key-only keys need just this header; signed keys also require X-Signature, X-Timestamp, and X-Nonce.
60 requests/minute, 1000/hour, 10000/day per API key (configurable per key)
The API supports cross-origin (browser) requests. Preflight OPTIONS requests are answered automatically, and successful responses include the right CORS headers. To call /api/v1/run directly from a website, create a "Key only" key (uncheck request signing), and in Dashboard -> API Keys add your site to "Allowed website domains" (e.g. example.com, which also allows app.example.com). The API then only accepts browser requests whose Origin matches one of those domains and reflects that Origin back in Access-Control-Allow-Origin. Leaving the allowlist empty permits any origin and is intended for keys used only from your own backend.
Any API key placed in front-end JavaScript is visible to your website visitors. If you must call the API from the browser, protect the key by (1) restricting it to a single agent, (2) locking it to your website domains, and (3) setting a low per-request and daily spend cap on the key. For anything sensitive or high-volume, call /api/v1/run from your own server instead and keep the key secret.
Send an Idempotency-Key header (any unique string per logical request) on POST /api/v1/run. If the same key is reused, the API returns the original stored response with an Idempotency-Replayed: true header instead of running and billing the agent again. Keys are scoped to your account and retained for 24 hours. Use a fresh key for each new request and reuse it only when retrying that exact request.
Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When you exceed a limit the API returns HTTP 429 with a Retry-After header (seconds). Honour Retry-After and use exponential backoff.
All /api/v1 errors return JSON shaped as { "error": { "code": "...", "message": "..." } }. Codes: invalid_request (400), unauthorized (401), payment_required (402), forbidden (403), not_found (404), rate_limited (429), email_verification_required (403), upstream_error/internal_error (5xx). Successful runs return { "response": "...", "usage": { ... } }.
Add "async": true to the POST /api/v1/run body to queue the run. The API responds immediately with HTTP 202 and { "run_id": "...", "status": "queued" }. Poll GET /api/v1/runs/{run_id} (with the same Authorization header) until status is "succeeded" or "failed"; the "result" field holds the final response. If you have a Webhooks integration configured for the agent.run.completed event, Central AI also POSTs the result to your webhook URL when the run finishes. Use async for long-running imported/automation agents that may exceed normal request timeouts.
curl -X POST https://your-domain.com/api/v1/run \
-H "Authorization: Bearer cai_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_agent_id": "YOUR_CLIENT_AGENT_ID",
"message": "Hello, AI!"
}'
# Response:
# {
# "response": "...agent reply...",
# "usage": {
# "tokens": 1234,
# "inputTokens": 1000,
# "outputTokens": 234,
# "costCents": 5,
# "costDollars": "0.0500"
# }
# }// Call from your backend (keep the key server-side).
const res = await fetch('https://your-domain.com/api/v1/run', {
method: 'POST',
headers: {
'Authorization': 'Bearer cai_live_YOUR_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
client_agent_id: 'YOUR_CLIENT_AGENT_ID',
message: 'Hello, AI!'
})
})
const data = await res.json()
console.log(data.response)import requests
url = "https://your-domain.com/api/v1/run"
headers = {
"Authorization": "Bearer cai_live_YOUR_KEY",
"Content-Type": "application/json"
}
data = {
"client_agent_id": "YOUR_CLIENT_AGENT_ID",
"message": "Hello, AI!"
}
response = requests.post(url, headers=headers, json=data)
print(response.json()["response"])<?php
$ch = curl_init('https://your-domain.com/api/v1/run');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer cai_live_YOUR_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'client_agent_id' => 'YOUR_CLIENT_AGENT_ID',
'message' => 'Hello, AI!'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>Solution: Verify the key is active and sent as "Authorization: Bearer cai_live_...". Signed keys also require X-Signature/X-Timestamp/X-Nonce.
Solution: Your wallet balance is too low or a spend cap was hit. Top up your wallet or raise the limit on the key.
Solution: The key is restricted to a different agent, or the request Origin is not in the allowed website domains for the key.
Solution: Send a client_agent_id for an agent you have added, or an agent_id you have added to your account.
Solution: Rate limit exceeded. Honour the Retry-After header and use exponential backoff.