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.