Reference
API reference
This is the route index for HoneyNotify API v1. Each entry explains the job the endpoint performs. Follow the linked concept guides for request fields, response examples, state transitions, and integration advice.
Base URL: https://api.honeynotify.com
All routes require Authorization: Bearer <key>. JSON write requests require Content-Type: application/json.
Rate limits: Every authenticated
/v1route listed below is rate limited per organisation and app. The public/healthand/statusservice endpoints are not rate limited.
How to read this reference#
- Method is the HTTP action to send.
GETreads data,POSTcreates or starts work,PATCHchanges selected data, andDELETEdisables, archives, or removes a resource as described. - Path is added to the base URL. Values in braces are placeholders that you replace with a real ID; for example,
{device_id}becomes a HoneyNotify device UUID. - What it does explains when to use the endpoint and whether it reads data, changes state, or queues asynchronous work.
- Scope is the permission that the bearer API key must have. It is a permission name, not a request field. See Authentication for key types and scopes.
- Success is the usual HTTP success status and the kind of result returned. A
202means work was accepted or queued; it does not mean the background work has finished.
Devices#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
POST |
/v1/devices/register |
Registers a new APNs, FCM, or Web Push destination, or refreshes an existing device's token, user, tags, and metadata. | devices:write |
201 new, 200 refreshed |
GET |
/v1/devices |
Lists devices in the app, with pagination and optional platform or enabled-status filters. Push tokens are never returned. | devices:write |
200 paginated list |
GET |
/v1/devices/{device_id} |
Retrieves one device's platform, status, metadata, and user association. | devices:write |
200 device |
DELETE |
/v1/devices/{device_id} |
Disables and invalidates a device so it can no longer receive notifications. Use it for logout or unsubscribe. | devices:write |
200 disabled |
Public client keys may register and delete only. See Devices and users.
Users and aliases#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/users/{external_user_id} |
Retrieves a user profile together with its aliases and associated devices. | devices:write |
200 user, aliases, devices |
PATCH |
/v1/users/{external_user_id} |
Replaces the supplied user locale, timezone, tags, or properties used for targeting and template values. | devices:write |
200 updated |
DELETE |
/v1/users/{external_user_id} |
Deletes the subscriber record and disables all of the user's devices. This is a destructive privacy action. | devices:write |
200 deleted |
POST |
/v1/users/{external_user_id}/aliases |
Adds an alternate identifier, such as a CRM ID, to the user; an existing alias can be moved to this user. | devices:write |
201 alias created/moved |
DELETE |
/v1/users/{external_user_id}/aliases |
Removes the exact alias label and value supplied in the request body. | devices:write |
200 deletion result |
URL-encode external IDs in path segments.
Segments#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/segments |
Lists the app's current reusable audience definitions. | notifications:read |
200 list |
POST |
/v1/segments |
Creates a reusable audience from rules about devices, users, tags, or events. | notifications:write |
201 created |
POST |
/v1/segments/estimate |
Counts the devices that currently match a saved segment or an unsaved filter without sending anything. | notifications:write |
200 count |
GET |
/v1/segments/{segment_id} |
Retrieves one segment and its current filter definition. | notifications:read |
200 segment |
PATCH |
/v1/segments/{segment_id} |
Updates a segment by creating a new immutable version. Existing notification snapshots are unchanged. | notifications:write |
200 new version |
DELETE |
/v1/segments/{segment_id} |
Archives a segment so it cannot be used for new sends while retaining its history. | notifications:write |
200 archived |
Templates#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/templates |
Lists current metadata for reusable notification templates. | notifications:read |
200 list |
POST |
/v1/templates |
Creates draft or published reusable notification content with optional placeholders. | notifications:write |
201 created |
GET |
/v1/templates/{template_id} |
Retrieves one template and its current content. | notifications:read |
200 template |
PATCH |
/v1/templates/{template_id} |
Changes a template by creating a new immutable content version. | notifications:write |
200 new version |
DELETE |
/v1/templates/{template_id} |
Archives a template so it cannot be used for new notifications; existing snapshots remain intact. | notifications:write |
200 archived |
Notifications#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/notifications |
Lists notification requests and their current delivery state. | notifications:read |
200 paginated list |
POST |
/v1/notifications |
Creates an immediate or scheduled notification, snapshots its content and audience, then queues it or holds it as a draft until due. | notifications:write |
202 queued/draft |
GET |
/v1/notifications/{notification_id} |
Retrieves one notification's status and aggregate recipient, accepted, and failed counts. | notifications:read |
200 summary |
POST |
/v1/notifications/{notification_id}/cancel |
Stops unsent work for a draft, queued, or processing notification. It cannot recall pushes already accepted by a provider. | notifications:write |
200 cancelled |
GET |
/v1/notifications/{notification_id}/recipients |
Lists each targeted device's delivery state, attempts, and last error for one notification. | notifications:read |
200 paginated results |
GET |
/v1/notifications/{notification_id}/events |
Lists lifecycle and engagement events recorded against one notification. | notifications:read |
200 paginated events |
Creation requires an Idempotency-Key header. Requests accept interruption_level as passive, active, time_sensitive, or critical; responses return the normalized level. See Notifications.
Events and analytics#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
POST |
/v1/events |
Records a received, delivered, opened, clicked, dismissed, custom, or outcome event for engagement and targeting. | events:write |
202 accepted |
GET |
/v1/analytics?days=30 |
Returns daily event metrics and outcome totals for the requested 1–365 day reporting window. | notifications:read |
200 metrics/outcomes |
Public client keys may submit events. See Events and analytics.
Webhooks#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/webhooks |
Lists the HTTPS endpoints configured to receive selected HoneyNotify events. | notifications:read |
200 list |
POST |
/v1/webhooks |
Creates a signed webhook endpoint and returns its signing secret once so your receiver can verify deliveries. | notifications:write |
201 created plus secret |
PATCH |
/v1/webhooks/{webhook_id} |
Changes the URL, description, subscribed events, enabled state, or rotates the signing secret. | notifications:write |
200 updated |
DELETE |
/v1/webhooks/{webhook_id} |
Permanently removes a webhook endpoint and stops future deliveries to it. | notifications:write |
200 deleted |
POST |
/v1/webhooks/{webhook_id}/test |
Queues a signed webhook.test delivery so you can verify your receiver and signature handling. |
notifications:write |
202 queued |
Journeys#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/journeys |
Lists the app's automated messaging journeys and their current states. | notifications:read |
200 list |
POST |
/v1/journeys |
Creates a draft or active automation graph triggered by a segment or custom event. | notifications:write |
201 created |
GET |
/v1/journeys/{journey_id} |
Retrieves one journey and its current trigger, nodes, and versioned definition. | notifications:read |
200 journey |
PATCH |
/v1/journeys/{journey_id} |
Changes a journey or its state by creating a new immutable version; existing executions keep their starting version. | notifications:write |
200 new version |
DELETE |
/v1/journeys/{journey_id} |
Archives the journey and cancels its active or waiting executions while retaining history. | notifications:write |
200 archived/cancelled |
GET |
/v1/journeys/{journey_id}/stats |
Returns execution totals grouped by statuses such as active, completed, and cancelled. | notifications:read |
200 counts by status |
Exports and settings#
| Method | Path | What it does | Scope | Success |
|---|---|---|---|---|
GET |
/v1/exports |
Lists the 100 newest audience, message, recipient, event, or audit export jobs and their status. | notifications:read |
200 newest 100 |
POST |
/v1/exports |
Starts an asynchronous CSV export for the requested data type. | notifications:write |
202 pending |
GET |
/v1/exports/{export_id}/download |
Downloads a completed, unexpired export as CSV. Export files expire after 24 hours. | notifications:read |
200 CSV |
PATCH |
/v1/app/settings |
Changes only the supplied app defaults and delivery controls, including identity verification, frequency caps, throttling, and quiet hours. | notifications:write |
200 updated |
Service endpoints#
| Method | Path | What it does | Authentication | Success |
|---|---|---|---|---|
GET |
/health |
Returns machine-readable API, database, Redis, queue, retry, and dead-letter health information for monitoring. | None | 200 health response |
GET |
/status |
Opens the public, human-readable service status page. | None | 200 status page |
These are service endpoints rather than versioned application resources. They do not use app API-key authentication.