# Agent API reference

Route inventory for scoped HTTP clients, with the canonical generated schemas. The CLI and MCP tools use this API; human consent is described in [Access and consent](https://notify.belweave.ai/docs/access).

HTML: https://notify.belweave.ai/docs/agent-api

## HTTP route inventory

| Route | Purpose |
| --- | --- |
| `GET /api/agent/auth/status` | Describe the calling token. Any scope. |
| `POST /api/agent/auth/revoke` | Revoke the calling token. Any scope. |
| `GET /api/agent/tokens` | List the account's API tokens (never secrets). `tokens:manage`. |
| `DELETE /api/agent/tokens/:id` | Revoke another token of the same account. `tokens:manage`. |
| `GET /api/agent/devices` | List registered devices. `devices:read`. |
| `DELETE /api/agent/devices/:id` | Remove a device; it registers again when Notify next opens on it. `devices:write`. |
| `GET /api/agent/services` | List webhook services (without webhook URLs). `services:read`. |
| `POST /api/agent/services` | Create a webhook service; the webhook URL is returned once. `services:write`. |
| `GET /api/agent/services/:id` | Get a webhook service. `services:read`. |
| `PATCH /api/agent/services/:id` | Update a webhook service's title, avatar, or tap URL. `services:write`. |
| `DELETE /api/agent/services/:id` | Delete a webhook service. `services:write`. |
| `POST /api/agent/services/:id/share` | Share a webhook service with your family, or unshare it. `services:write`. |
| `POST /api/agent/services/:id/rotate` | Rotate the webhook token; the new URL is returned once. `services:write`. |
| `GET /api/agent/webhooks` | List saved reply webhooks with masked header values. `services:read`. |
| `POST /api/agent/webhooks` | Create a reply webhook; the signing secret is returned once. `services:write`. |
| `GET /api/agent/webhooks/:id` | Read a reply webhook and its last 50 deliveries. `services:read`. |
| `PATCH /api/agent/webhooks/:id` | Update a reply webhook; omit headers to preserve their saved values. `services:write`. |
| `DELETE /api/agent/webhooks/:id` | Delete a reply webhook. `services:write`. |
| `POST /api/agent/webhooks/:id/test` | Queue a signed sample interaction.answered event (202); inspect logs for completion. `services:write`. |
| `POST /api/agent/webhooks/:id/rotate-secret` | Rotate the signing secret; its replacement is returned once. `services:write`. |
| `GET /api/agent/events` | Recent webhook deliveries. `events:read`. |
| `GET /api/agent/activity-feed` | Merged account activity history, newest first (20 per page). `events:read`. |
| `POST /api/agent/notifications` | Send a one-shot push. `notifications:send`. |
| `POST /api/agent/notifications/:id/withdraw` | Withdraw an agent notification from the account's devices. `notifications:send`. |
| `GET /api/agent/interactions` | List the account's pending prompts from every source. `interactions:read`. |
| `POST /api/agent/interactions` | Ask a question (approval, yes/no, or reply). `interactions:create`, `notifications:send`. |
| `GET /api/agent/interactions/:id` | Get a prompt created by this token. `interactions:read`. |
| `GET /api/agent/interactions/:id/wait` | Long-poll a prompt created by this token until it is answered. `interactions:read`. |
| `POST /api/agent/interactions/:id/cancel` | Cancel a pending prompt created by this token. `interactions:create`. |
| `GET /api/agent/activities` | List Live Activities started by this token. `activities:read`. |
| `POST /api/agent/activities` | Start a Live Activity. `activities:write`. |
| `GET /api/agent/activities/:identifier` | Get a Live Activity by ID or key. `activities:read`. |
| `PATCH /api/agent/activities/:identifier` | Update a Live Activity. `activities:write`. |
| `POST /api/agent/activities/:identifier/end` | End a Live Activity. `activities:write`. |
| `GET /api/agent/apps` | List web apps. `apps:read`. |
| `POST /api/agent/apps` | Register a web app (an existing URL is updated). `apps:write`. |
| `GET /api/agent/apps/:id` | Get a web app. `apps:read`. |
| `PATCH /api/agent/apps/:id` | Update a web app's name, URL, icon, or project. `apps:write`. |
| `DELETE /api/agent/apps/:id` | Remove a web app. `apps:write`. |
| `POST /api/agent/apps/:id/revoke` | Revoke sign-in consent; the owner approves again on the next sign-in request. `apps:write`. |
| `POST /api/agent/apps/:id/share` | Move an app into a team, or (teamId null) back to your own apps. `apps:write`. |
| `GET /api/agent/teams` | List the teams you belong to. `teams:read`. |
| `POST /api/agent/teams` | Create a family with `kind: family`; you become its owner. Omitting `kind` or using `kind: team` returns `403` because Teams is TBD. `teams:write`. |
| `GET /api/agent/teams/:id` | A team and its members. `teams:read`. |
| `PATCH /api/agent/teams/:id` | Update a team (name: admin; auto-join and retention: owner). `teams:write`. |
| `DELETE /api/agent/teams/:id` | Delete a team (owner); its apps return to the members who added them. `teams:write`. |
| `POST /api/agent/teams/:id/leave` | Leave a team (the owner must transfer ownership first). `teams:write`. |
| `PATCH /api/agent/teams/:id/members/:userId` | Change a member's role; `owner` transfers ownership (owner only). `teams:write`. |
| `DELETE /api/agent/teams/:id/members/:userId` | Remove a member (admin or owner); the owner cannot be removed. `teams:write`. |
| `GET /api/agent/teams/:id/invites` | List invites (admin or owner). `teams:read`. |
| `POST /api/agent/teams/:id/invites` | Create a 7-day join link (admin or owner). `teams:write`. |
| `DELETE /api/agent/teams/:id/invites/:inviteId` | Revoke an invite. `teams:write`. |
| `GET /api/agent/teams/:id/apps` | The team's shared apps. `teams:read`, `apps:read`. |
| `GET /api/agent/teams/:id/groups` | The team's device groups. `teams:read`. |
| `POST /api/agent/teams/:id/groups` | Create a device group (admin or owner). `teams:write`. |
| `GET /api/agent/teams/:id/groups/:groupId` | A device group. `teams:read`. |
| `PATCH /api/agent/teams/:id/groups/:groupId` | Update a device group (admin or owner). `teams:write`. |
| `DELETE /api/agent/teams/:id/groups/:groupId` | Delete a device group (admin or owner). `teams:write`. |
| `GET /api/agent/teams/:id/devices` | Devices belonging to team members (admin or owner). `teams:read`. |
| `POST /api/agent/teams/:id/domain` | Request a DNS TXT challenge for an email domain (owner). `teams:write`. |
| `DELETE /api/agent/teams/:id/domain` | Clear the pending or verified domain (owner). `teams:write`. |
| `POST /api/agent/teams/:id/domain/verify` | Verify the pending domain's DNS TXT record (owner). `teams:write`. |
| `GET /api/agent/teams/:id/audit` | Audit log (admin or owner); members receive 403. `teams:read`. |
| `GET /api/agent/teams/:id/oncall` | The team's on-call groups with current and upcoming shifts. `oncall:read`. |
| `POST /api/agent/teams/:id/oncall` | Create an on-call group (admin or owner). `oncall:write`. |
| `GET /api/agent/teams/:id/pages` | The team's pages, newest first. `oncall:read`. |
| `GET /api/agent/oncall/me` | Your upcoming shifts and the open pages that notified you. `oncall:read`. |
| `GET /api/agent/oncall/:groupId` | An on-call group. `oncall:read`. |
| `PATCH /api/agent/oncall/:groupId` | Edit a group's name, rotation, or escalation (admin or owner). `oncall:write`. |
| `DELETE /api/agent/oncall/:groupId` | Delete an on-call group (admin or owner). `oncall:write`. |
| `POST /api/agent/oncall/:groupId/overrides` | Put someone on call for a window (admins: anyone; members: themselves). `oncall:write`. |
| `DELETE /api/agent/oncall/:groupId/overrides/:overrideId` | Remove an override. `oncall:write`. |
| `POST /api/agent/oncall/:groupId/pages` | Page the group: whoever is on call first, then escalation. `oncall:write`. |
| `GET /api/agent/pages/:id` | A page. `oncall:read`. |
| `GET /api/agent/connectors` | List tunnel connectors. `connectors:read`. |
| `POST /api/agent/connectors` | Register a tunnel connector; the callback HMAC secret is returned once. `connectors:write`. |
| `GET /api/agent/connectors/:id` | A tunnel connector. `connectors:read`. |
| `PATCH /api/agent/connectors/:id` | Update a connector's name, routes, or on-call group. `connectors:write`. |
| `DELETE /api/agent/connectors/:id` | Remove a tunnel connector. `connectors:write`. |
| `POST /api/agent/connectors/:id/heartbeat` | Mark a connector online and refresh its last-seen time. `connectors:write`. |
| `POST /api/agent/connectors/:id/access` | Gateway-only pass exchange or access revalidation; requires the connector's credential and a phone-issued pass. `connectors:write`. |
| `POST /api/agent/connectors/:id/callback-access` | Gateway-only authorization of a signed callback against its saved target and durable replay receipt. `connectors:write`. |
| `POST /api/agent/connectors/:id/rotate-secret` | Rotate a connector callback HMAC secret; the new secret is returned once. `connectors:write`. |
| `POST /api/agent/pages/:id/resolve` | Resolve a page; anyone still being paged is cleared. `oncall:write`. |
| `GET /api/agent/inbox/projects` | Inbox projects with unread counts. `inbox:read`. |
| `GET /api/agent/inbox/notifications` | Inbox notifications, newest first, with cursor pagination. `inbox:read`. |
| `GET /api/agent/inbox/notifications/:id` | One inbox notification with its full body. `inbox:read`. |
| `POST /api/agent/inbox/notifications/read-all` | Mark everything up to a list response's readThroughToken read. `inbox:write`. |
| `POST /api/agent/inbox/notifications/:id/read` | Mark one notification read. `inbox:write`. |
| `POST /api/agent/inbox/notifications/:id/unread` | Mark one notification unread. `inbox:write`. |
| `GET /api/agent/billing` | Plan, limits, and remaining usage. `billing:read`. |

```bash
notify inbox list --unread --limit 20
notify inbox read-all --project unfiled
notify interaction list
notify send withdraw anot_...
notify services rotate svc_...
notify apps update app_example_warehouse --name "Maintenance board"
notify billing
notify tokens list   # needs --scope tokens:manage at login
```

## Direct interaction fields

Direct HTTP and MCP questions use the interaction schema rather than the webhook’s nested `response` object. Create requires `interactions:create` and `notifications:send`; reading and waiting require `interactions:read`. A successful create only establishes the pending request.

| Field | Type | Description |
| --- | --- | --- |
| `title` | string, required | Sender title, 1–80 characters after trimming. |
| `prompt` | string, required | Question, 1–2,000 characters after trimming. live_activity presentation caps this at 240. |
| `kind` | enum, required | `approval`, `yes_no`, or `reply`. Note that webhook type `text` maps to agent kind `reply`. |
| `expiresInSeconds` | integer | 30–86,400 seconds, default 900. live_activity presentation cannot exceed 28,800. |
| `presentation` | enum | `notification` (default) or `live_activity`. The latter uses ActivityKit on capable iOS and an ordinary actionable alert on native Android. |
| `style` | enum | Only with live_activity: `approval`, `shell`, `verdict`, or `signal`. |
| `primaryLabel / secondaryLabel` | string | Only with live_activity: 1–24 characters each, single-line labels. Canonical returned actions do not change. |
| `imageUrl / url` | string | Optional sender image and tap destination, using notification validation. Not accepted with live_activity. |
| `deviceIds / group` | string[] / string | Optional selected devices or authorized workplace group. Supply one targeting form, not both. |
| `callback` | object | Classic URL/token or connector-target answered callback; see [per-question callbacks](https://notify.belweave.ai/docs/notification-api#response-callbacks). |
| `webhookId` | string | Optional saved account reply endpoint (`whk_…`) in addition to applicable defaults. |

```bash
curl -X POST https://notify.belweave.ai/api/agent/interactions   -H "Authorization: Bearer $NOTIFY_TOKEN"   -H 'Content-Type: application/json'   -d '{"title":"Warehouse desk","prompt":"Hold package PKG-42 until tomorrow?","kind":"approval","expiresInSeconds":900}'
```

> For live_activity, use approval or yes_no, never reply. The generated [OpenAPI schemas](https://notify.belweave.ai/docs/agent-api#agent-api-openapi) describe create, wait, get, list, and cancel HTTP requests. Only a valid human answer can settle the question as approved or denied.

## Generated OpenAPI schemas

Use the OpenAPI 3.1 document for exact HTTP schemas and automation. It includes `x-notify-scopes` and request validators generated from the server’s schemas. The route inventory above is kept in step with that implementation.

OpenAPI document:

```text
https://notify.belweave.ai/api/agent/openapi.json
```