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.
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. |
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 loginDirect 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. |
| webhookId | string | Optional saved account reply endpoint (whk_…) in addition to applicable defaults. |
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 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.
https://notify.belweave.ai/api/agent/openapi.jsonMCP reference
OAuth discovery, granted scopes, and the tool families available to a remote client. For configuration snippets, use [Connect an MCP client](#mcp-connect).
Reach an internal service
Expose a private HTTP service through Notify Connector and the OpenTunnel relay. The public hostname reaches the service; a verified Notify pass or signed callback still determines who may use it.