HoneyNotify API

All API responses include a validated UUID in X-Request-ID. Errors use { "error": { "code", "message", "details" }, "request_id" }. Requests with bodies require Content-Type: application/json, are limited to MAX_REQUEST_BYTES, authenticated with Authorization: Bearer …, and rate limited by organisation and app.

Scopes

• devices:write — register and disable devices.
• notifications:write — create notifications.
• notifications:read — read notification status and delivery totals.
• events:write — submit received, opened, clicked, dismissed or custom events.

Endpoints

POST /v1/devices/register

Required: platform (ios or android) and push_token. Optional: external_user_id, app_version, device_model, os_version, locale, timezone, and string-valued tags. Registering an existing token refreshes its metadata and re-enables it.

DELETE /v1/devices/{device_id}

Disables the device and marks its token invalidated.

POST /v1/notifications

Requires an Idempotency-Key header plus title, body, and target. Concurrent requests using the same key return the original notification rather than creating duplicates. Target types are all, device, user, and tag; their required target identifiers are validated. Priorities are transactional, high, normal, and bulk. Optional timezone-qualified ISO-8601 scheduled_at values are picked up by the scheduler.

GET /v1/notifications/{notification_id}

Returns status, timestamps, recipient count, accepted count, and failed count.

POST /v1/events

Requires event_type; accepts optional notification_id, device_id, event_name, metadata, and ISO-8601 occurred_at.

Public mobile keys

Mobile apps should receive a Public mobile client key with a ps_public_ prefix. The server fixes these keys to devices:write and events:write; notification scopes cannot be added. Never embed a ps_live_ server key in shipped client code.