Skip to content
API reference

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

SchemeHeaderRoutes
API keyAuthorization: ApiKey <key>Everything under /v1 unless noted.
Subscriber sessionAuthorization: Bearer <token>The four inbox message routes only (an API key also works there).
A2A callerAuthorization: Bearer <token>The A2A routes: an A2A client key or a subscriber session. Never an API key.
Source keyAuthorization: SourceKey <key>POST /v1/sources/{sourceID}/events.
Inbound secretX-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 credentials use 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.