{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Control Panel integration API",
    "version": "1.0.0",
    "summary": "The HTTP calls the Agent Control Panel SDKs make: heartbeats, run reports, prompt fetches, and the signed command webhook sent to your app.",
    "description": "Agent Control Panel (ACP) is a control plane for AI agents running inside your own app. The Node.js and Python SDKs (`agent-control-panel` on npm and PyPI) use these calls; this description is for anyone writing their own client or debugging one. Your model calls never go through these endpoints. Human-readable reference: https://agentcontrolpanel.si/docs/reference/api.html",
    "contact": { "name": "Agent Control Panel", "url": "https://agentcontrolpanel.si/contact" },
    "termsOfService": "https://agentcontrolpanel.si/legal/terms"
  },
  "externalDocs": {
    "description": "HTTP API reference",
    "url": "https://agentcontrolpanel.si/docs/reference/api.html"
  },
  "servers": [{ "url": "https://agentcontrolpanel.si", "description": "Your control panel URL" }],
  "tags": [
    { "name": "Ingest", "description": "Liveness and completed runs, authenticated with the app's API key in the JSON body." },
    { "name": "Prompts", "description": "The agent's approved prompt, authenticated with the x-api-key header." }
  ],
  "paths": {
    "/api/heartbeat": {
      "post": {
        "tags": ["Ingest"],
        "operationId": "sendHeartbeat",
        "summary": "Report liveness and counters; receive the control state ACP holds",
        "description": "The SDKs send one heartbeat every 30 seconds. 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. Request bodies are limited to 1 MB.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatRequest" } } }
        },
        "responses": {
          "200": {
            "description": "Heartbeat accepted.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/report": {
      "post": {
        "tags": ["Ingest"],
        "operationId": "reportRuns",
        "summary": "Report one completed run, or a batch of up to 100",
        "description": "Send one run as an object with `api_key` and the run fields, or several as `{ \"api_key\": \"...\", \"runs\": [ ... ] }`. 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. Request bodies are limited to 10 MB.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/ReportOne" },
                  { "$ref": "#/components/schemas/ReportBatch" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run(s) stored, or an earlier run returned for a repeated `dedupe_key`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/AgentNotFound" },
          "413": { "$ref": "#/components/responses/TooLarge" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/prompts/{agent_id}": {
      "get": {
        "tags": ["Prompts"],
        "operationId": "getPrompt",
        "summary": "Fetch the agent's approved prompt with its enabled skills composed in",
        "description": "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.",
        "security": [{ "apiKeyHeader": [] }],
        "parameters": [
          { "name": "agent_id", "in": "path", "required": true, "description": "An agent of the app the key belongs to.", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "The composed prompt.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromptResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/AgentNotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "webhooks": {
    "command": {
      "post": {
        "operationId": "receiveCommand",
        "summary": "A signed command from ACP to your app (POST {your app URL}/api/acp/webhook)",
        "description": "Verify `x-acp-signature` over the exact raw bytes of the body, reject a timestamp more than 300 seconds from your clock and a nonce you have already seen, then check that `agent_id` is the agent you are applying it to. 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; a 4xx other than 408, 425 or 429 is not retried. Which commands an app accepts depends on its control scope. 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.",
        "parameters": [
          { "name": "x-acp-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `{timestamp}.{nonce}.{raw body}`, keyed with the app's webhook secret.", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } },
          { "name": "x-acp-timestamp", "in": "header", "required": true, "description": "Unix time in seconds.", "schema": { "type": "string", "pattern": "^[0-9]+$" } },
          { "name": "x-acp-nonce", "in": "header", "required": true, "description": "Unique per request.", "schema": { "type": "string" } },
          { "name": "x-acp-protocol", "in": "header", "required": true, "description": "Protocol version.", "schema": { "type": "string", "const": "1" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } }
        },
        "responses": {
          "2XX": { "description": "Command received." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "The app's API key (created in Agent Control Panel, shown once). Heartbeats and reports carry the same key as `api_key` in the JSON body instead."
      }
    },
    "schemas": {
      "ApiKey": {
        "type": "string",
        "minLength": 1,
        "description": "The app's API key, sent in the JSON body. Unknown or revoked keys get 401."
      },
      "HeartbeatAgent": {
        "type": "object",
        "required": ["agent_id"],
        "properties": {
          "agent_id": { "type": "string", "description": "An agent of this app; others are ignored." },
          "status": { "type": "string", "description": "The agent's own status, for example `running`, `idle` or `error`. `paused` and `stopped` are ignored here." },
          "model": { "type": "string", "maxLength": 120, "description": "The model the agent runs now; confirms a model swap." },
          "tokens_since_last": { "type": "integer", "minimum": 0 },
          "runs_since_last": { "type": "integer", "minimum": 0 },
          "errors_since_last": { "type": "integer", "minimum": 0 }
        }
      },
      "HeartbeatRequest": {
        "type": "object",
        "required": ["api_key"],
        "properties": {
          "api_key": { "$ref": "#/components/schemas/ApiKey" },
          "agents": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/HeartbeatAgent" } }
        }
      },
      "ControlEntry": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "status": { "type": "string", "description": "The status ACP holds. Adopt `paused` and `stopped`, and release them when ACP no longer says so." },
          "model": { "type": "string", "description": "Present after a model swap: the model the agent should run. Missing means no instruction, not \"clear the override\"." }
        }
      },
      "HeartbeatResponse": {
        "type": "object",
        "required": ["success", "timestamp", "control"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "timestamp": { "type": "string", "format": "date-time" },
          "control": {
            "type": "object",
            "required": ["agents"],
            "properties": {
              "agents": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ControlEntry" }, "description": "Keyed by agent_id, for the agents in the heartbeat." }
            }
          }
        }
      },
      "Run": {
        "type": "object",
        "required": ["agent_id", "status"],
        "properties": {
          "agent_id": { "type": "string", "description": "An agent of this app." },
          "status": { "type": "string", "enum": ["success", "error"], "description": "An error run sets the agent to `error` unless it is paused or stopped." },
          "user_input": { "type": "string", "description": "The end user's request; up to 20,000 characters are stored." },
          "input_summary": { "type": "string", "description": "Up to 2,000 characters are stored." },
          "output_summary": { "type": "string", "description": "Up to 2,000 characters are stored." },
          "full_input": { "description": "A string or JSON; up to 100,000 characters are stored (JSON is measured after serialising)." },
          "full_output": { "description": "A string or JSON; up to 100,000 characters are stored (JSON is measured after serialising)." },
          "full_input_truncated": { "type": "boolean", "description": "Set when you cut full_input yourself." },
          "full_output_truncated": { "type": "boolean", "description": "Set when you cut full_output yourself." },
          "error_message": { "type": "string", "description": "Shown on the run and as the agent's last error." },
          "tokens_input": { "type": "integer", "minimum": 0, "description": "Missing counts as 0. Cost is estimated from the tokens and the model." },
          "tokens_output": { "type": "integer", "minimum": 0 },
          "tokens_total": { "type": "integer", "minimum": 0 },
          "model_used": { "type": "string", "maxLength": 120, "description": "The model that ran. Also fills in the agent's model if none is set." },
          "execution_time_ms": { "type": "integer", "minimum": 0 },
          "trigger": { "type": "string", "description": "What started the run." },
          "prompt_version": { "type": "integer", "description": "The `version` from the prompt fetch." },
          "composition_hash": { "type": "string", "description": "The `compositionHash` from the prompt fetch." },
          "dedupe_key": { "type": "string", "maxLength": 64, "description": "Sending the same key again returns the first run's id and stores nothing new, so retries are safe." }
        }
      },
      "ReportOne": {
        "description": "One run: the run fields plus api_key.",
        "allOf": [
          { "$ref": "#/components/schemas/Run" },
          { "type": "object", "required": ["api_key"], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" } } }
        ]
      },
      "ReportBatch": {
        "type": "object",
        "required": ["api_key", "runs"],
        "properties": {
          "api_key": { "$ref": "#/components/schemas/ApiKey" },
          "runs": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Run" } }
        }
      },
      "ReportResponse": {
        "type": "object",
        "required": ["success", "run_id"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "run_id": { "type": "string", "description": "The stored run (the first one, for a batch)." },
          "run_ids": { "type": "array", "items": { "type": "string" }, "description": "Every stored run, for a batch." }
        }
      },
      "PromptResponse": {
        "type": "object",
        "required": ["prompt", "version", "skillCount", "compositionHash"],
        "properties": {
          "prompt": { "type": "string", "description": "The approved prompt with the agent's enabled skills composed in." },
          "version": { "type": "integer" },
          "skillCount": { "type": "integer", "minimum": 0 },
          "compositionHash": { "type": "string" }
        }
      },
      "Command": {
        "type": "object",
        "required": ["command", "agent_id", "payload", "command_id", "timestamp"],
        "properties": {
          "command": {
            "type": "string",
            "enum": ["pause", "resume", "stop", "restart", "update_model", "update_prompt", "ping", "verify"],
            "description": "`update_model` carries payload.model; `update_prompt` carries payload.prompt and payload.version (fetch the composed prompt afterwards); `ping` and `verify` only check the connection and change nothing."
          },
          "agent_id": { "type": "string" },
          "payload": { "type": "object", "description": "Command data, for example `{ \"model\": \"gpt-4.1\" }`." },
          "command_id": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["message"],
        "properties": { "message": { "type": "string" } }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed body or a missing field, for example no api_key or agent_id, or more than 100 runs in a batch.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Unknown or revoked API key, or no x-api-key header on a prompt fetch.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "AgentNotFound": {
        "description": "The agent is not in the app the key belongs to.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "TooLarge": {
        "description": "The body is over the endpoint's limit (1 MB for heartbeats, 10 MB for reports)."
      },
      "RateLimited": {
        "description": "Rate limited. Heartbeats and reports together: 120 requests a minute per key and address, and 600 a minute per address; prompt fetches: 120 a minute per address. The reply is plain text and carries RateLimit headers.",
        "content": { "text/plain": { "schema": { "type": "string" } } }
      }
    }
  }
}
