# For AI agents

Coding agents and automation should read the machine-readable summary instead of scraping the HTML docs. It lists base URLs, authentication headers, route paths, and error codes in plain text.

- Machine-readable summary: [`/llms.txt`](https://hooks.events/llms.txt)
- Full documentation in one file: [`/llms-full.txt`](https://hooks.events/llms-full.txt)

## Recommended flow

1. Fetch `/llms.txt`, then read the REST API section.
2. Create a dedicated API key per agent in **Settings → API keys**, and load it from an environment variable.
3. Create an endpoint, queue a test event, then poll deliveries until they succeed or fail.

```bash
curl -X POST "https://api.hooks.events/v1/endpoints" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-test",
    "provider": "generic",
    "verificationMode": "hmac",
    "destinations": [{ "url": "https://example.com/hooks" }]
  }'

# Queue a test event, then poll deliveries
curl -X POST "https://api.hooks.events/v1/endpoints/$ENDPOINT_ID/test-events" \
  -H "Authorization: Bearer $HOOKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eventType":"agent.check"}'
```

## Guardrails

- Never print API keys, signing secrets, or raw `Authorization` headers in logs, commits, or chat.
- Prefer test events over replaying production events.
- Treat the ingestion URL as a secret: anyone with it can create events.
- Respect `429` responses and the `Retry-After` header instead of retrying immediately.