API overview

Use the Pushctl v1 API to register installations, send notifications, and report delivery events.

The Pushctl API is JSON over HTTPS and is scoped to the application represented by the bearer token.

https://pushctl.com/api/v1

Installations

Register device identifiers, identity, permission, and metadata.

Notifications

Send to external users and read aggregate delivery results.

Delivery events

Report received, displayed, opened, and dismissed events.

Request conventions

curl --request GET \
  --url https://pushctl.com/api/v1/notifications \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer push_live_your_token'

• Send and accept application/json.
• Treat installation and notification IDs as opaque strings.
• Use ISO 8601 timestamps returned by the API.
• Paginated collections default to 25 items and accept at most 100 per page.

Typical integration

1. Register an installation

   A client SDK or app creates a stable installation ID and sends its provider identifier.
2. Associate an external user

   Set user_id when the person signs in and clear it with null on sign-out.
3. Send from a trusted server

   Create a notification for one or more external user IDs.
4. Inspect and report

   Read aggregate status from the server API while client SDKs report device lifecycle events.

Use the official SDKs when available. They handle provider identifiers, permission changes, event persistence, and idempotent retries.