Pushctl API

Introduction

Application-scoped APIs for registering installations, sending push notifications, and tracking delivery events.

Base URL: http://pushctl.test

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_APPLICATION_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Use an application-scoped Sanctum token with the ability required by the endpoint.

Delivery events

Report lifecycle events emitted by a client installation.

Report a delivery event

POST

http://pushctl.test

/api/v1/events

requires authentication

Idempotently records a received, displayed, or opened event.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

event_id

string

required

Must be a valid UUID.

Example:

6ff8f7f6-1eb3-3525-be4a-3932c805afed

delivery_id

string

required

Example:

architecto

installation_id

string

required

Must not be greater than 255 characters.

Example:

type

string

required

Must be one of:

received
displayed
opened
dismissed

Example:

received

occurred_at

string

required

Must be a valid date in the format Y-m-d\TH:i:sP.

Example:

2026-08-10T19:33:00+00:00

metadata

object

Auth

Bearer

Headers

Body

{ "event_id": "6ff8f7f6-1eb3-3525-be4a-3932c805afed", "delivery_id": "architecto", "installation_id": "n", "type": "received", "occurred_at": "2026-08-10T19:33:00+00:00", "metadata": null }

Received response

Example request:

curl --request POST \
    "http://pushctl.test/api/v1/events" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"event_id\": \"6ff8f7f6-1eb3-3525-be4a-3932c805afed\",
    \"delivery_id\": \"architecto\",
    \"installation_id\": \"n\",
    \"type\": \"received\",
    \"occurred_at\": \"2026-08-10T19:33:00+00:00\"
}"

Installations

Register an installation

PUT

http://pushctl.test

/api/v1/installations/{installationId}

requires authentication

Creates or replaces an installation and associates it with an optional external user.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

installationId

string

required

Example:

architecto

Body Parameters

user_id

string

Must not be greater than 255 characters.

Example:

platform

string

required

Must be one of:

ios
android

Example:

android

provider

object

required

permission

string

required

Must be one of:

unknown
not_determined
authorized
provisional
ephemeral
denied

Example:

ephemeral

device

object

app_version

string

Must not be greater than 100 characters.

Example:

os_version

string

Must not be greater than 100 characters.

Example:

model

string

Must not be greater than 255 characters.

Example:

locale

string

Must not be greater than 35 characters.

Example:

en_CA

timezone

string

Must be a valid time zone, such as Africa/Accra.

Example:

America/Moncton

Auth

Bearer

Headers

URL Parameters

Body

{ "user_id": "b", "platform": "android", "provider": { "type": "apns_token", "identifier": "b" }, "permission": "ephemeral", "device": { "app_version": "n", "os_version": "g", "model": "z", "locale": "en_CA", "timezone": "America\/Moncton" } }

Received response

Example request:

curl --request PUT \
    "http://pushctl.test/api/v1/installations/architecto" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": \"b\",
    \"platform\": \"android\",
    \"provider\": {
        \"type\": \"apns_token\",
        \"identifier\": \"b\"
    },
    \"permission\": \"ephemeral\",
    \"device\": {
        \"app_version\": \"n\",
        \"os_version\": \"g\",
        \"model\": \"z\",
        \"locale\": \"en_CA\",
        \"timezone\": \"America\\/Moncton\"
    }
}"

Update an installation

PATCH

http://pushctl.test

/api/v1/installations/{installationId}

requires authentication

Updates user association, permission state, or installation metadata.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

installationId

string

required

Example:

architecto

Body Parameters

user_id

string

Must not be greater than 255 characters.

Example:

permission

string

Must be one of:

unknown
not_determined
authorized
provisional
ephemeral
denied

Example:

ephemeral

Auth

Bearer

Headers

URL Parameters

Body

{ "user_id": "b", "permission": "ephemeral" }

Received response

Example request:

curl --request PATCH \
    "http://pushctl.test/api/v1/installations/architecto" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"user_id\": \"b\",
    \"permission\": \"ephemeral\"
}"

Get an installation

GET

http://pushctl.test

/api/v1/installations/{installationId}

requires authentication

Returns an installation belonging to the authenticated application.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

installationId

string

required

Example:

architecto

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "http://pushctl.test/api/v1/installations/architecto" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *

{
    "message": "Unauthenticated."
}

Notifications

Create notifications and inspect their delivery lifecycle.

Send a notification

POST

http://pushctl.test

/api/v1/notifications

requires authentication

Queues a notification for all eligible installations belonging to the specified external users.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

recipients

object

required

notification

object

required

title

string

Must not be greater than 255 characters.

Example:

body

string

Must not be greater than 4096 characters.

Example:

image_url

string

Must be a valid URL. Must not be greater than 2048 characters.

Example:

http://crooks.biz/et-fugiat-sunt-nihil-accusantium

action_url

string

Must match the regex /^[a-z][a-z0-9+.-]*:\/\/\S+$/i. Must not be greater than 2048 characters.

Example:

http://tillman.com/

data

object

options

object

ttl

integer

Must be at least 0. Must not be greater than 2419200.

Example:

priority

string

Must be one of:

normal
high

Example:

high

collapse_id

string

Must not be greater than 64 characters.

Example:

sound

string

Must not be greater than 255 characters.

Example:

badge

integer

Must be at least 0.

Example:

android_channel_id

string

Must not be greater than 255 characters.

Example:

ios_category

string

Must not be greater than 255 characters.

Example:

platform_overrides

object

Auth

Bearer

Headers

Body

{ "recipients": { "user_ids": [ "b" ] }, "notification": { "title": "b", "body": "n", "image_url": "http:\/\/crooks.biz\/et-fugiat-sunt-nihil-accusantium", "action_url": "http:\/\/tillman.com\/" }, "data": null, "options": { "ttl": 14, "priority": "high", "collapse_id": "w", "sound": "a", "badge": 50, "android_channel_id": "k", "ios_category": "c", "platform_overrides": { "ios": null, "android": null } } }

Received response

Example request:

curl --request POST \
    "http://pushctl.test/api/v1/notifications" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"recipients\": {
        \"user_ids\": [
            \"b\"
        ]
    },
    \"notification\": {
        \"title\": \"b\",
        \"body\": \"n\",
        \"image_url\": \"http:\\/\\/crooks.biz\\/et-fugiat-sunt-nihil-accusantium\",
        \"action_url\": \"http:\\/\\/tillman.com\\/\"
    },
    \"options\": {
        \"ttl\": 14,
        \"priority\": \"high\",
        \"collapse_id\": \"w\",
        \"sound\": \"a\",
        \"badge\": 50,
        \"android_channel_id\": \"k\",
        \"ios_category\": \"c\"
    }
}"

List notifications

GET

http://pushctl.test

/api/v1/notifications

requires authentication

Returns a paginated notification history, optionally filtered by status.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

Body Parameters

status

string

Must be one of:

queued
processing
completed
partial
failed

Example:

queued

per_page

integer

Must be at least 1. Must not be greater than 100.

Example:

Auth

Bearer

Headers

Body

{ "status": "queued", "per_page": 1 }

Received response

Example request:

curl --request GET \
    --get "http://pushctl.test/api/v1/notifications" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"status\": \"queued\",
    \"per_page\": 1
}"

Example response:

Headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *

{
    "message": "Unauthenticated."
}

Get a notification

GET

http://pushctl.test

/api/v1/notifications/{notificationId}

requires authentication

Returns aggregate lifecycle counts for a notification.

Headers

Authorization

Example:

Bearer {YOUR_APPLICATION_TOKEN}

Content-Type

Example:

application/json

Example:

application/json

URL Parameters

notificationId

string

required

Example:

architecto

Auth

Bearer

Headers

URL Parameters

Received response

Example request:

curl --request GET \
    --get "http://pushctl.test/api/v1/notifications/architecto" \
    --header "Authorization: Bearer {YOUR_APPLICATION_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Example response:

Headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *

{
    "message": "Unauthenticated."
}