Notify API.
The management API your server, the console and the MCP server use, and the client API browsers and apps call with a recipient token. Every endpoint, request and response, generated from the live OpenAPI spec.
Base URL
https://api.notify.productcraft.coAuth
Authorization: Bearer …Spec version
OpenAPI spec
https://api.notify.productcraft.co/docs-jsonApprovals
Approval requests: an AI agent or your backend asks people a yes/no question before acting (agents propose, humans approve). The question reaches them on the type's channels; the first answer wins and comes back as the signed `approval.resolved` webhook and here. Requests time out, and every step is in their trail and the audit log.
- get
/v1/workspaces/{workspace_id}/approvalsList approval requests - post
/v1/workspaces/{workspace_id}/approvalsRequest an approval - get
/v1/workspaces/{workspace_id}/approvals/{approval_id}Get an approval request - post
/v1/workspaces/{workspace_id}/approvals/{approval_id}/cancelCancel an approval request - post
/v1/workspaces/{workspace_id}/approvals/{approval_id}/decisionRecord an approver's answer
Categories
Groups of notification types that recipients opt in or out of together, with a default per channel (`on`, `off` or `mandatory`).
- get
/v1/workspaces/{workspace_id}/categoriesList categories - post
/v1/workspaces/{workspace_id}/categoriesCreate a category - get
/v1/workspaces/{workspace_id}/categories/{category_id}Get a category - patch
/v1/workspaces/{workspace_id}/categories/{category_id}Update a category - delete
/v1/workspaces/{workspace_id}/categories/{category_id}Delete a category
Channels
Which channels can deliver now, and their credentials (metadata only; secrets are write-only). Web push uses a VAPID key pair that Notify generates for you, or that you import from another provider.
- get
/v1/workspaces/{workspace_id}/channelsList channels - get
/v1/workspaces/{workspace_id}/channels/webpushGet the web push public key - post
/v1/workspaces/{workspace_id}/channels/webpush/vapid-keysGenerate the web push VAPID key - put
/v1/workspaces/{workspace_id}/channels/webpush/vapid-keysImport a web push VAPID key - put
/v1/workspaces/{workspace_id}/channels/apns/credentialsUpload an APNs key - delete
/v1/workspaces/{workspace_id}/channels/apns/credentials/{credential_id}Delete an APNs key - put
/v1/workspaces/{workspace_id}/channels/fcm/credentialsUpload an FCM service account - delete
/v1/workspaces/{workspace_id}/channels/fcm/credentials/{credential_id}Delete an FCM service account
Client
The client API, called from your users' apps and browsers with a recipient token (`Authorization: Bearer`), never an API key: their inbox (list, counts, mark, button presses, the real-time stream), their devices and web push subscription, and their preferences. Browser calls must come from the workspace's `client_origins`.
- get
/v1/client/inboxList the inbox - get
/v1/client/inbox/countsGet the inbox counts - post
/v1/client/inbox/markMark inbox items - post
/v1/client/inbox/{item_id}/interactRecord a press on an inbox item - post
/v1/client/devicesRegister this device - delete
/v1/client/devices/{device_id}Remove this device - get
/v1/client/webpush/vapid-public-keyGet the web push key - get
/v1/client/preferencesGet my preferences - patch
/v1/client/preferencesUpdate my preferences - get
/v1/client/approvals/{approval_id}Get an approval request - post
/v1/client/approvals/{approval_id}/decisionAnswer an approval request - get
/v1/client/inbox/streamStream inbox events
Deliveries
One row per notification, recipient, channel and target (the inbox, an email address or a device), with its state, the reason for every skip, retry or failure, and each provider attempt.
Export
The whole Notify configuration of a workspace as JSON, to keep in source control or apply to another workspace.
Notification-Types
What you send: a key, a category, routing (`always` channels and ordered `fallback` steps), templates per channel and locale with version history, and a preview that renders without sending.
- get
/v1/workspaces/{workspace_id}/notification-typesList notification types - post
/v1/workspaces/{workspace_id}/notification-typesCreate a notification type - put
/v1/workspaces/{workspace_id}/notification-types/by-key/{key}Create or replace a notification type by key - get
/v1/workspaces/{workspace_id}/notification-types/{type_id}Get a notification type - patch
/v1/workspaces/{workspace_id}/notification-types/{type_id}Update a notification type - post
/v1/workspaces/{workspace_id}/notification-types/{type_id}/archiveArchive a notification type - post
/v1/workspaces/{workspace_id}/notification-types/{type_id}/previewPreview a notification type - get
/v1/workspaces/{workspace_id}/notification-types/{type_id}/templates/{channel}/{locale}Get a template - put
/v1/workspaces/{workspace_id}/notification-types/{type_id}/templates/{channel}/{locale}Create or replace a template - delete
/v1/workspaces/{workspace_id}/notification-types/{type_id}/templates/{channel}/{locale}Delete a template - get
/v1/workspaces/{workspace_id}/notification-types/{type_id}/templates/{channel}/{locale}/versionsList a template's versions - post
/v1/workspaces/{workspace_id}/notification-types/{type_id}/templates/{channel}/{locale}/revertRevert a template
Notifications
Send a notification to up to 1,000 recipients with one call (Idempotency-Key required), explain a send with `dry_run`, and read, cancel or retract what was sent (the message log).
- get
/v1/workspaces/{workspace_id}/notificationsList notifications (message log) - post
/v1/workspaces/{workspace_id}/notificationsSend a notification - post
/v1/workspaces/{workspace_id}/notifications/cancelCancel notifications by cancellation key - get
/v1/workspaces/{workspace_id}/notifications/{notification_id}Get a notification - post
/v1/workspaces/{workspace_id}/notifications/{notification_id}/cancelCancel a notification - post
/v1/workspaces/{workspace_id}/notifications/{notification_id}/retractRetract a notification from inboxes - get
/v1/workspaces/{workspace_id}/batchesList batches - get
/v1/workspaces/{workspace_id}/batches/{batch_id}Get a batch - post
/v1/workspaces/{workspace_id}/batches/{batch_id}/flushClose a batch now
Recipient-Tokens
Short-lived tokens your backend mints for one signed-in user, so their app or browser can call the client API without your secret key. Revoke one recipient's tokens, or every token of the workspace.
Recipients
The people you notify, keyed by your own user id (`external_id`), with their email, phone, locale, time zone, quiet hours, your custom properties, their devices (APNs and FCM tokens, web push subscriptions) and their preferences. Erase one for GDPR with `DELETE`.
- post
/v1/workspaces/{workspace_id}/recipients/bulkCreate or update up to 1,000 recipients - get
/v1/workspaces/{workspace_id}/recipientsList recipients - get
/v1/workspaces/{workspace_id}/recipients/{external_id}Get a recipient - put
/v1/workspaces/{workspace_id}/recipients/{external_id}Create or update a recipient - patch
/v1/workspaces/{workspace_id}/recipients/{external_id}Update a recipient - delete
/v1/workspaces/{workspace_id}/recipients/{external_id}Erase a recipient (GDPR) - get
/v1/workspaces/{workspace_id}/recipients/{external_id}/devicesList a recipient's devices - post
/v1/workspaces/{workspace_id}/recipients/{external_id}/devicesRegister a device - delete
/v1/workspaces/{workspace_id}/recipients/{external_id}/devices/{device_id}Remove a device - get
/v1/workspaces/{workspace_id}/recipients/{external_id}/preferencesGet a recipient's preferences - put
/v1/workspaces/{workspace_id}/recipients/{external_id}/preferencesReplace a recipient's preferences - patch
/v1/workspaces/{workspace_id}/recipients/{external_id}/preferencesUpdate a recipient's preferences - get
/v1/workspaces/{workspace_id}/recipients/{external_id}/inboxList a recipient's inbox items - get
/v1/workspaces/{workspace_id}/recipients/{external_id}/timelineGet a recipient's delivery timeline - post
/v1/workspaces/{workspace_id}/recipients/{external_id}/preference-linkCreate a hosted preference page link
Settings
Workspace settings: email on or off, and the automatic email pause (more than 0.1 % complaints or 5 % hard bounces among recent emails) with how to resume it.
Setup-Status
A checklist of what Notify needs before notifications reach anyone (a notification type, the Mail sender and templates for email), with where to fix each item.
Stats
Daily delivery counts per channel from an hourly rollup (planned, sent, delivered, failed, skipped, inbox reads), kept beyond the 30 days of delivery history.
Webhooks
Signed webhooks (Standard Webhooks) for sends, delivery outcomes (sent, delivered, failed, bounced, skipped with the reason), inbox reads, archives and clicks, pruned and moved devices, refused credentials, the email auto-pause and recipient erasure, with an event log, retries, Send test and replay. Payloads carry ids, the type key, channel, state and reason: never rendered text, addresses or tokens.
- get
/v1/workspaces/{workspace_id}/webhooks/event-typesList the events an endpoint can subscribe to. - get
/v1/workspaces/{workspace_id}/webhooks/endpointsList webhook endpoints, oldest first. - post
/v1/workspaces/{workspace_id}/webhooks/endpointsAdd a webhook endpoint. - get
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Get one webhook endpoint (without its secret). - patch
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Change a webhook endpoint: URL, description, events, on/off. - delete
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}Delete a webhook endpoint. - post
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/rotate-secretRotate the signing secret. - post
/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}/testSend a test event to this endpoint now and return the result. - get
/v1/workspaces/{workspace_id}/webhooks/eventsList webhook events, newest first (kept for 30 days). - get
/v1/workspaces/{workspace_id}/webhooks/events/{event_id}Get one webhook event with every delivery attempt. - post
/v1/workspaces/{workspace_id}/webhooks/events/{event_id}/replaySend a logged event again, to its endpoints or to one endpoint.