---
title: "API, tokens and triggers"
description: "Call the HTTP API with personal access tokens, and run agents on schedules and webhooks."
---

> Documentation Index
> Fetch the complete documentation index at: https://agenthold.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API, tokens and triggers

## API reference

The HTTP API is described by `api/openapi.yaml`, which the server also publishes at `/api/v1/openapi.yaml`. The
[API reference](https://agenthold.dev/api/) 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:

```sh
TOKEN=ahp_...
curl -H "Authorization: Bearer $TOKEN" https://agents.example.com/api/v1/me
```

WebSocket 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`.

Source: https://agenthold.dev/automation/index.mdx