API reference
API overview
The Agentower API — base address, authentication, conventions and every endpoint at a glance.
The Agentower API is how tools report agents to Agentower, how you read your own data back out, and how your own tools can answer agents. It's the same API the Claude Code, Codex and Cursor hooks use.
From TypeScript or Python, the SDKs wrap it: npm install agentower or pip install agentower.
#Base address
Every endpoint lives on Agentower's address, shown on Keys & connections in the app. For Agentower's hosted service that's:
https://ingest.agentower.comThe examples in these pages use $AGENTOWER_URL for it, and $AGENTOWER_KEY (and friends) for keys, so you can paste them into a terminal after setting those two variables.
#Pricing
Reporting your agents — hooks, events, telemetry, plan limits, asks — is always free, and so are public stats, which are never counted as API calls. Reading and acting through the API (MCP, export, agent actions) and the anonymous insights API are priced per call, with 1,000 calls a month on Solo, 25,000 included on Team and 250,000 on Enterprise. See API pricing.
#Authentication
Send a key as a bearer token on every request:
authorization: Bearer at_live_…Keys are made on Keys & connections (and History → Export) in the app. Each key has one scope that decides which endpoints it can call — see Keys and scopes. A key used on an endpoint outside its scope gets 401 unauthorized, exactly as a wrong key would.
#Conventions
- Request and response bodies are JSON (
content-type: application/json), apart from CSV exports. - Times you send (
ts) are milliseconds since 1970 (Unix epoch, UTC). Times Agentower returns are ISO 8601 strings in UTC, unless a field says otherwise. - Agent states use these names everywhere:
starting,working,needs_you,idle,done,failed. - IDs you send —
session_idand the like — are 1–128 characters fromA–Z a–z 0–9 . _ : -. - Project names you send are 1–100 characters from letters, digits, spaces and
. _ -. Anything else is dropped, and the agent goes into Unsorted. - Text fields are cleaned (control characters removed) and cut to their maximum length rather than rejected.
- The API doesn't send CORS headers: call it from a server or a script, not from a web page, and keep keys out of browsers.
#Endpoints
| Method | Path | Key scope | What it does |
|---|---|---|---|
POST | /v1/events | ingest | Report an agent's status from any tool or script |
POST | /v1/hooks/{tool} | ingest | Claude Code, Codex and Cursor hook events |
GET | /v1/settings | ingest | Which projects have opted in to questions and answering, and whether guardrails are on |
GET | /v1/guard/{tool} | ingest | Is this session paused by a guardrail? |
POST | /v1/logs | ingest | OpenTelemetry logs (OTLP/HTTP JSON): token and cost usage |
POST | /v1/metrics, /v1/traces | ingest | Accepted and ignored |
POST | /v1/status/claude-code | ingest | Plan limits from the Claude Code status line |
POST | /v1/limits | ingest | Plan limits from any tool (Codex's hook, your own) |
POST | /v1/asks | ingest | Any agent: open a request for an answer from the app |
GET | /v1/asks/{id} | ingest | Any agent: check whether it has been answered |
POST | /v1/asks/{tool} | ingest | The Claude Code and Codex hooks: open a request for an answer from the app |
GET | /v1/asks/{tool}/{id} | ingest | The hooks: check whether it has been answered |
POST | /v1/import/claude-code | ingest | Import finished sessions from before you connected |
GET | /v1/stats | public:read | The counters you chose to publish |
GET | /v1/agents | agents:act | Open agents, optionally by state or project |
GET | /v1/agents/{id} | agents:act | One open agent |
POST, DELETE | /v1/agents/{id}/message | agents:act | Message an agent, or take a waiting message back |
POST | /v1/agents/{id}/approve | agents:act | Allow or deny its permission request |
POST | /v1/agents/{id}/continue | agents:act | Let it past a guardrail |
GET | /v1/export | export:read | The datasets you can export |
GET | /v1/export/{dataset} | export:read | One dataset, as JSON or CSV |
POST | /mcp | mcp | The MCP server |
GET | /health | none | {"ok":true,"service":"tower","environment":"production"} |
Outgoing: webhooks that Agentower sends to your own address.
#OpenAPI
The whole API is described in an OpenAPI 3.1 file: openapi.yaml. See OpenAPI file.