API reference
Every route notify serves, from internal/httpapi and the services it mounts. The pages in this section list each route with its purpose and the details that are easy to get wrong. The behaviour behind them is explained in the other sections.
Conventions
Base path and contract
All API routes are under /v1. Every /v1 response, errors included, carries Notify-Contract: 1. A /v1 route only ever changes additively; a change that would break a client moves to a new major path and a new header value, so a client can refuse a server whose contract it does not understand.
Authentication
| Scheme | Header | Routes |
|---|---|---|
| API key | Authorization: ApiKey <key> | Everything under /v1 unless noted. |
| Subscriber session | Authorization: Bearer <token> | The four inbox message routes only (an API key also works there). |
| A2A caller | Authorization: Bearer <token> | The A2A routes: an A2A client key or a subscriber session. Never an API key. |
| Source key | Authorization: SourceKey <key> | POST /v1/sources/{sourceID}/events. |
| Inbound secret | X-Inbound-Secret: <secret> | POST /v1/inbound/email. |
A missing or unrecognised credential is 401 with a plain-text unauthorized body. The key decides the scope; there is no organization or environment parameter on any route.
Optional routes
Some route groups are mounted only when their backing service is wired. notify serve wires all of them, with one exception: the three /v1/inbound/messages archive routes exist only when a blob store is configured.
Errors
Most routes return a JSON envelope:
{ "error": { "code": "not_found", "message": "workflow not found" } }code is one of bad_request (400), not_found (404), conflict (409), unprocessable_entity (422), too_large (413), unavailable (503) or internal (500). The message of a 500 is deliberately generic and the real error is logged.
Some older surfaces return a plain-text body instead of the envelope: the inbox message routes, the agents API, the conversation routes, the streams, analytics, and the inbound webhook. The status code is still meaningful.
Bodies
Request and response bodies are JSON with camelCase fields, with these exceptions:
- Integration
credentialsuse snake_case keys on the unified endpoint and camelCase on the legacy channel endpoints.
Pagination
There is no single scheme. Each list says which it uses: after/next keyset cursors on subscribers, contexts, env vars and inbound domains, cursor/next on notifications, before/next on messages, after/nextKey on layouts, and cursors returned by the inbound archive and drafts. Cursors are opaque.
Identifiers in paths
GET, PATCH and DELETE /v1/subscribers/{id} take the subscriber’s internal id (the id in the subscriber object). Every other subscriber path (/session, /credentials, /preferences) takes your subscriberId.