# Wake API

> Read what agents did on your site, where they got stuck, what to fix and how the listing is going. Base URL `/api/wake/v1`. Auth: `Authorization: Bearer wk_live_…`. Machine description at [`/api/wake/v1/openapi.json`](/api/wake/v1/openapi.json).

## Authentication

Mint a key on your desk under **Connect your AI** (up to 10 active keys per desk; shown once; stored hashed; revoke any time). Send it as a bearer token:

```bash
curl -H "Authorization: Bearer wk_live_…" "https://wakeagents.ai/api/wake/v1/overview?window=7d"
```

A key reads exactly one desk (one host). Limits: 120 requests per minute per key.

## Windows

`window` is `24h`, `7d` (default) or `30d`. `24h` buckets by hour, the others by day.

## Endpoints

| Method and path | Returns |
|---|---|
| `GET /` | API index (no auth). |
| `GET /openapi.json` | OpenAPI 3.1 (no auth). |
| `GET /me` | Host, verification, collector status, key label, MCP and docs URLs. |
| `GET /overview?window=` | Events, sessions, unique agents, conversions, friction, by provider / class / intent / country / network operator, the funnel, top friction. |
| `GET /agents?window=` | One row per nickname: sessions, events, stage reached, converted, friction types, intents. |
| `GET /sessions?window=&limit=&nickname=` | Session rows, newest first (limit ≤ 500). |
| `GET /sessions.csv?window=` | The same as CSV. |
| `GET /funnel?window=` | Sessions that reached each stage (not cumulative), share, drop, biggest drop. |
| `GET /friction?window=` | Friction tally by kind and page class, with the fixes it implies. |
| `GET /fixes?window=` | Ranked fixes with evidence, plus readiness recommendations (verified desks). |
| `GET /alerts?window=` | Changes versus the previous window. |
| `GET /series?window=` | Time buckets of events, sessions, agents, friction sessions, conversions. |
| `GET /pages?window=` | Page classes touched and the most common sequences. |
| `GET /insight?window=&metric=&breakdown=&filters=&compare=` | A trend: metric (sessions, agents, events, errors, friction_sessions, conversions) per hour or day, broken down by one dimension (provider, agent_class, country, network, path_class, status_class, status, method, stage, intent, friction), filtered by a JSON array of `{dimension, value}`, with the previous window when `compare=true`. |
| `GET /errors?window=` | Every 4xx and 5xx agents received, grouped by page class and status: requests, sessions, agents, families, countries, first and last seen, sessions that ended or looped on it, daily trend, what it means for an agent. |
| `GET /events?window=&limit=&filters=` | The newest coarse requests (max 500), newest first, each with its session's family, tier, country and network. |
| `GET /security?window=` | Threat scoring of agent sessions: hostile, suspicious, watch or clean, from behaviour, claimed identity versus network, anonymisers and your watchlists; flagged sessions with evidence, actors, signal totals, guidance. |
| `GET /destinations` | The PostHog destination: host, masked key, last sync, events sent. Configure it on the desk under Connect your AI. |
| `GET /alert_rules` | The alert rules on this desk (threshold, silence, signal), their channel, last check and delivery, and the delivery log. Rules are created on the desk under Alerts. |
| `GET /health` | Collector health: first and last event, requests and agents in 24 h and 7 d, 14 daily counts, what the requests carry, warnings that name the fix. |
| `GET /readiness` | The public site as an agent sees it: scores, recommendations, probe, publish-ready files. Verified desks. |
| `GET /listing` | AEO plan, step status, arrivals (identified vs crawler), trial. |
| `POST /verify` | Run the ownership check now; records it when it passes. Returns the tag, file and record to place when not yet verified. |
| `POST /provision` · `{rotate}` | Mint the collector keys and return the deploy-ready files (verified desks). The install agent calls verify, then provision, writes the file, deploys. |
| `POST /listing/plan` | Prepare the listing plan (never publishes). Verified desks. |
| `GET /benchmarks` | k-anonymous cohort medians, withheld below k=5. |
| `GET /install` · `?kit=1` | Collector status; with `kit=1` the deploy-ready files (verified desks). |
| `POST /mcp` | MCP endpoint, see [MCP](/wake/docs/mcp). |

## Public, no key

| Method and path | Returns |
|---|---|
| `GET /public/readiness?host=` | Readiness of any public host: scores, recommendations, publish-ready files. 20 requests per minute per address. |
| `GET /public/about` | What Wake is, with links. |
| `POST /public/mcp` | Public MCP server with `wake_check_site` and `wake_about`. Listed on Smithery as `wake-site-readiness`. |

## Shapes

A session row:

```json
{
  "nickname": "ax_1a1IT2kn",
  "provider": "anthropic",
  "agent_class": "declared_ai",
  "started_at": "2026-10-29T04:37:00.000Z",
  "ended_at": "2026-10-29T04:41:12.000Z",
  "duration_ms": 252000,
  "event_count": 6,
  "stage": "attempted_action",
  "intent": "Call the API / integrate",
  "inferred": true,
  "converted": false,
  "friction": [{ "type": "action_unauthorized", "path_class": "api", "detail": "2 failed api requests (status 401) with no success." }],
  "path_classes": ["docs", "docs", "api", "api", "auth", "api"]
}
```

Friction kinds: `auth_wall`, `action_unauthorized`, `action_rejected`, `action_not_found`, `action_wrong_method`, `action_rate_limited`, `action_server_error`, `repeated_error`, `abandoned_on_error`, `docs_dead_end`. Intent is a labelled inference with a confidence, never a claim about what the remote agent meant.

## Errors

JSON `{ "error": "…", "code": "…" }`:

| Status | code | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing, unknown or revoked key. |
| 403 | `unverified` | The desk has not verified ownership of the host. |
| 404 | `not_provisioned` / `not_found` | No collector yet, or unknown route. |
| 429 | `rate_limited` | More than 120 requests in a minute for this key. |

## Privacy

Every answer is coarse by construction: daily HMAC nicknames, page classes, status codes, operator families, country codes, network operator names. There is no raw IP, user-agent, query, body, cookie or referrer anywhere in the store, so none can be returned. See [Privacy](/wake/docs/privacy).

## Account and desk hygiene (signed-in session)

- `POST /api/v1/wake/fixes/done` `{ id, done }`: marks a fix done on the desk record (every browser agrees). Returns `{ ok, fixes_done }`.
- `POST /api/v1/wake/sites/remove` `{ id }`: removes a site from the account: its desk row, its link sessions and the account's pointer. Events on the edge age out with retention.
- `GET /api/v1/wake/export`: one JSON file with the desk record (no secrets), the last 90 days of requests and visits, the rules and the alert log.
- `POST /api/v1/wake/account/delete` `{ "confirm": "DELETE" }`: deletes every desk on the account, every session, then the account.

Errors on these routes are `{ error, code }`.
