HTTP API reference
The Node.js and Python SDKs use four HTTP calls. This page describes them for anyone writing their own client or debugging one. Send requests to your control panel URL (https://agentcontrolpanel.si) over HTTPS with the app's API key. Your model calls never go through these endpoints. A machine-readable description of the same calls is at /openapi.json (OpenAPI 3.1, with the webhook).
Endpoints
| Call | Authentication | Purpose |
|---|---|---|
POST /api/heartbeat |
api_key in the JSON body |
Liveness and counters; the reply carries the control state Agent Control Panel holds. |
POST /api/report |
api_key in the JSON body |
One completed run, or a batch of up to 100. |
GET /api/prompts/{agent_id} |
x-api-key header |
The agent's current prompt, with its skills composed in. |
POST {your app}/api/acp/webhook |
HMAC signature (your webhook secret) | Signed commands from Agent Control Panel to your app. |
POST /api/heartbeat
{
"api_key": "acp_…",
"agents": [
{ "agent_id": "…", "status": "idle", "model": "gpt-4.1-mini",
"tokens_since_last": 1842, "runs_since_last": 3, "errors_since_last": 0 }
]
}
agents holds up to 500 entries; entries for agents that are not in this app are ignored. A reported status of paused or stopped is never stored: only commands set or clear them. model is the model the agent runs now, which confirms a model swap. The reply:
{
"success": true,
"timestamp": "2026-11-11T09:30:00.000Z",
"control": { "agents": { "<agent_id>": { "status": "paused", "model": "gpt-4.1" } } }
}
status is the status Agent Control Panel holds; adopt paused and stopped, and release them when it no longer says so. model appears after a model swap from the dashboard: the model the agent should run. A missing model means no instruction, not "clear the override". Request bodies are limited to 1 MB.
POST /api/report
Send one run as { "api_key": "acp_…", "agent_id": "…", "status": "success", … }, or several as { "api_key": "acp_…", "runs": [ … ] }. The reply is { "success": true, "run_id": "…" }, with run_ids for a batch.
| Field | Meaning |
|---|---|
agent_id |
Required. An agent of this app. |
status |
success or error. An error run sets the agent to error unless it is paused or stopped. |
user_input |
The end user's request; up to 20,000 characters are stored. |
input_summary / output_summary |
Up to 2,000 characters each. |
full_input / full_output |
A string or JSON; up to 100,000 characters (JSON is measured after serialising). Set full_input_truncated / full_output_truncated if you cut them yourself. |
error_message |
Shown on the run and as the agent's last error. |
tokens_input / tokens_output / tokens_total |
Token counts; missing values count as 0. Cost is estimated from these and the model. |
model_used |
The model that ran (a string, up to 120 characters). Also fills in the agent's model if none is set. |
execution_time_ms, trigger, prompt_version, composition_hash |
Duration, what started the run, and which prompt version and skills it used. |
dedupe_key |
Up to 64 characters. Sending the same key again returns the first run's id and stores nothing new, so retries are safe. |
A batch is processed in order and stops at the first invalid run; the runs before it are kept, so retry with the same dedupe_key values. Credentials in run content are removed before storage (Settings → Data & privacy can also remove emails and card numbers). Request bodies are limited to 10 MB.
GET /api/prompts/{agent_id}
{ "prompt": "You are …", "version": 7, "skillCount": 2, "compositionHash": "…" }
prompt is the agent's approved prompt with its enabled skills composed in. Report version and compositionHash back on each run as prompt_version and composition_hash. The SDKs cache the prompt for 60 seconds and keep using the last good one if this call fails.
Webhook: commands to your app
Agent Control Panel sends each command as POST to your app's URL plus /api/acp/webhook:
{
"command": "update_model",
"agent_id": "…",
"payload": { "model": "gpt-4.1" },
"command_id": "…",
"timestamp": "2026-11-11T09:30:00.000Z"
}
| Header | Meaning |
|---|---|
x-acp-signature |
Hex HMAC-SHA256 of {timestamp}.{nonce}.{raw body}, keyed with the webhook secret. |
x-acp-timestamp |
Unix time in seconds. Reject requests more than 300 seconds away from your clock. |
x-acp-nonce |
Unique per request. Reject a nonce you have already seen. |
x-acp-protocol |
Protocol version, currently 1. |
Verify the signature over the exact raw bytes, then check that agent_id is the agent you are applying it to. Commands: pause, resume, stop, restart, update_model (payload.model), update_prompt (payload.prompt and payload.version; fetch the composed prompt afterwards), and ping / verify, which only check the connection and change nothing. Which commands an app accepts depends on its control scope.
Any 2xx reply acknowledges the command. Redirects are not followed and count as a failure. By default each attempt times out after 10 seconds, with up to three attempts (an organization can set 1 to 15 seconds and 1 to 5 attempts); a 4xx other than 408, 425 or 429 is not retried. If your app has no reachable webhook URL, pauses, stops and model swaps still arrive in the next heartbeat reply, and a new prompt within the 60-second prompt cache.
Errors and rate limits
| Status | Meaning |
|---|---|
400 |
Malformed body or a missing field, e.g. no api_key or agent_id, or more than 100 runs in a batch. |
401 |
Unknown or revoked API key, or no x-api-key header on a prompt fetch. |
404 |
The agent is not in the app the key belongs to. |
413 |
The body is over the endpoint's limit. |
429 |
Rate limited; the reply carries RateLimit headers. |
Errors reply with { "message": "…" }, except 429, which replies with plain text. Heartbeats and reports together are limited to 120 requests a minute per key and address, and 600 a minute per address; prompt fetches to 120 a minute per address. The SDKs send one heartbeat every 30 seconds and batch reports, far below these limits. Rejected calls with a real key are listed in the connection check while you set up an app, so a wrong key shows up at once.