API fundamentals

The HoneyNotify API is a JSON-over-HTTPS API rooted at https://api.honeynotify.com/v1. It uses bearer authentication, predictable HTTP status codes, UUID resource identifiers, and a common error envelope.

Request format#

Send JSON objects with Content-Type: application/json. Array or scalar request bodies are rejected. Request sizes are capped by the service, so store large media externally and send an HTTPS URL rather than file data.

POST /v1/notifications HTTP/1.1
Host: api.honeynotify.com
Authorization: Bearer ps_live_…
Content-Type: application/json
Idempotency-Key: invoice-4831-reminder-v1

Query parameters belong in the URL. Do not send JSON bodies with GET requests.

Response format#

Successful responses are JSON except completed export downloads, which are CSV. Create operations normally return 201 Created; asynchronous operations such as sends, events, webhook tests, and exports return 202 Accepted.

Every response includes an X-Request-ID UUID. You may supply your own valid UUID in the request's X-Request-ID header to correlate HoneyNotify activity with your logs. Invalid values are replaced with a generated UUID.

Asynchronous work#

Several endpoints accept work before it finishes:

• a notification moves through draft, queued, processing, and a terminal result;
• an export starts as pending and becomes downloadable when completed;
• a webhook test is queued for delivery;
• scheduled notifications stay in draft until their due time.

Poll the resource endpoint or consume webhooks where available. A 202 response confirms acceptance by HoneyNotify, not completion by a downstream push provider.

Notification create, replay, list, and detail responses expose the normalized interruption_level. Omitted values are returned as active; see Notifications for platform mappings and Critical Alert prerequisites.

Notification targets may include platform with both, ios, or android. The dashboard defaults this target value to both; API requests may omit it to retain all-platform delivery, including Web Push.

Pagination#

Device, notification, recipient, and event lists use page-number pagination.

GET /v1/devices?page=2&limit=100

page starts at 1. limit defaults to 50 and is clamped between 1 and 250.

{
  "devices": [],
  "pagination": {
    "page": 2,
    "limit": 100,
    "total": 263,
    "pages": 3
  }
}

Lists without pagination are intentionally bounded by the relevant resource semantics. Export history, for example, returns the newest 100 records.

Time, locale, and identifiers#

• Send timestamps in ISO 8601 with seconds and Z or a numeric offset, such as 2026-09-20T14:30:00Z.
• API-generated resource identifiers are UUIDs. Treat them as opaque strings.
• external_user_id is your stable user identifier and may be up to 190 characters.
• Locale values should use language tags such as en-GB; timezone values should use IANA names such as Europe/London.
• Scheduled times are normalised to UTC by the service.

Safe retries#

Reads are safe to retry. For notification creation, reuse the same Idempotency-Key when retrying the same logical message. HoneyNotify returns the existing notification instead of creating another one.

Do not reuse an idempotency key for a different notification. Keys are scoped to the app and may be up to 190 characters.

For 429 and server errors, use exponential backoff with jitter. Respect the X-RateLimit-Limit and X-RateLimit-Remaining headers to avoid preventable throttling.

Status-code guide#

See Errors and limits for the error envelope and retry patterns.