> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushctl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```text theme={null}
https://pushctl.com/api/v1
```

<CardGroup cols={3}>
  <Card title="Installations" icon="smartphone">Register device identifiers, identity, permission, and metadata.</Card>
  <Card title="Notifications" icon="paper-plane">Send to external users and read aggregate delivery results.</Card>
  <Card title="Delivery events" icon="chart-line">Report received, displayed, opened, and dismissed events.</Card>
</CardGroup>

## Request conventions

```bash theme={null}
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

<Steps>
  <Step title="Register an installation">A client SDK or app creates a stable installation ID and sends its provider identifier.</Step>
  <Step title="Associate an external user">Set `user_id` when the person signs in and clear it with `null` on sign-out.</Step>
  <Step title="Send from a trusted server">Create a notification for one or more external user IDs.</Step>
  <Step title="Inspect and report">Read aggregate status from the server API while client SDKs report device lifecycle events.</Step>
</Steps>

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