API reference
The HTTP API is described by api/openapi.yaml, which the server also publishes at /api/v1/openapi.yaml. The
API reference on this site is generated from it. Your own server also serves a viewer at /api/docs, which loads the Scalar viewer from jsDelivr in your browser. Everything the
web UI does goes through this API.
An mcp is planned. soon
Personal access tokens
Create tokens under API tokens (top bar) or with POST /api/v1/me/tokens. A token acts as you, with exactly
your permissions, and is shown once. Use it as a bearer token:
TOKEN=ahp_...
curl -H "Authorization: Bearer $TOKEN" https://agents.example.com/api/v1/meWebSocket endpoints (session streams, terminals) accept the same header. Only a hash of each token is stored. Tokens can expire, and you can revoke them at any time.
Schedules
A schedule prompts a session of an agent on a cron schedule: five fields (minute hour day month weekday) or
@hourly, @daily, @weekly, in an IANA time zone. Each schedule has its own session, created with it. Runs
wake a sleeping agent like any prompt. If the previous run is still going, the run is skipped and the error is
shown on the schedule. Missed runs while the server was down are not replayed.
Webhooks
A webhook is a secret URL (/api/v1/hooks/<token>, shown once) and a prompt template. A POST to the URL prompts
the webhook’s session with the template. The request body (up to 256 KiB) goes where {{payload}} stands, or
after the template, between markers that tell the agent it is untrusted data. With a signing secret, the
request must carry the HMAC-SHA256 of the body in the signature header (X-Hub-Signature-256 by default,
sha256=<hex> or plain hex, as GitHub sends it). Unsigned or wrongly signed requests are rejected with 401.
Acting as their creator
Schedules and webhooks prompt as the agent admin who created them. That user’s name appears in the session log, for example “Alice (webhook: ci)”, and the audit log records each run. If the creator later loses operator access to the agent, the trigger stops working.
The end-to-end check runs against the dev stack: scripts/e2e/api.sh.