canonical: https://jentic.com/apis/onesignal.com/onesignal-api

# OneSignal API (Full)

Jentic publishes the only available OpenAPI specification for OneSignal API (Full), keeping it validated and agent-ready. The full OneSignal API exposes 55 endpoints covering apps, notifications, segments, users, subscriptions, templates, players, organizations, and outcomes analytics. Agents and applications can create and update apps, send notifications across push, email, and SMS channels, manage user records and aliases, build and edit segments, transfer subscription ownership, and pull outcome metrics filtered by attribution, platform, and time range.

## For AI agents

Manage OneSignal apps, users, subscriptions, segments, templates, and notifications across push, email, and SMS through the full 55-endpoint OneSignal API.

## Scope

Does not handle in-product UI personalisation, payments, or CRM contact storage - use for OneSignal app, user, segment, subscription, notification, and outcomes management only.

## Capabilities

- Create, update, and view OneSignal apps under an organization
- Send push, email, and SMS notifications and pull message history
- Build, edit, and delete user segments based on tags and properties
- Create and update users by alias and manage subscription ownership transfers
- Manage subscriptions by id or by token type and token value
- Pull outcome analytics filtered by name, time range, platform, and attribution
- Export player records to CSV for offline analysis or migration

## Use cases

### Multi-Channel Notification Campaigns

Coordinate push, email, and SMS sends from one API for a marketing campaign and inspect delivery outcomes afterwards. Notifications are created against an app, history can be pulled per message, and outcome analytics reveal conversions broken down by platform and attribution window.

Example prompt: Send a push notification to the 'Lapsed Users' segment under app id 'app-xyz' with heading 'We miss you' and pull the outcomes for 'click' over the next 7 days.

### User and Subscription Management

Manage end-user identities through OneSignal aliases, link multiple device subscriptions to a single user, and transfer ownership when a subscription moves between accounts. POST /apps/{app_id}/users creates the user; PATCH endpoints update aliases and subscription assignments.

Example prompt: Create a user under app 'app-xyz' with external_id 'cust-123' and attach an existing iOS subscription id to that user.

### Segmentation for Targeted Messaging

Define audience segments inside OneSignal programmatically based on tags or user properties, then reuse those segments when creating notifications. POST /apps/{app_id}/segments creates the segment, PATCH updates it, and DELETE removes it when no longer needed.

Example prompt: Create a segment named 'Active iOS Premium' under app 'app-xyz' filtered to platform=iOS and tag plan=premium.

### Outcome and Conversion Analytics

Pull outcome metrics with platform and attribution filters to evaluate campaign performance after a send. GET /apps/{app_id}/outcomes accepts outcome names, a time range, platforms, and attribution windows, returning aggregate counts ready for reporting dashboards.

Example prompt: Pull outcome metrics for 'os__click' on app 'app-xyz' for the last 7 days filtered to iOS with direct attribution.

### Agent-Run OneSignal Operations via Jentic

Customer engagement and marketing-ops agents drive OneSignal end to end through Jentic - sending notifications, editing segments, transferring subscriptions, and pulling outcomes - without ever holding the REST API key. Agents search by intent, load the matching schema, and execute against the OneSignal endpoint.

Example prompt: Use Jentic search 'create onesignal segment' to locate POST /apps/{app_id}/segments, load the schema, and execute with the segment definition.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /apps | Create a OneSignal app |
| GET | /apps | List apps under the organization |
| POST | /apps/{app_id}/segments | Create a user segment |
| POST | /apps/{app_id}/users | Create a user |
| PATCH | /apps/{app_id}/subscriptions/{subscription_id}/owner | Transfer a subscription to another user |
| GET | /apps/{app_id}/outcomes | Retrieve outcome analytics with filters |
| POST | /players/csv_export | Export player records to CSV |
| POST | /notifications/{message_id}/history | Retrieve message history for a notification |

## Key resources

- **Apps** — Create, view, and update OneSignal apps under an organization
- **Notifications** — Send notifications and retrieve per-message history
- **Segments** — Create, update, and delete user segments by app
- **Users** — Manage user records by alias and update identities
- **Subscriptions** — Update, delete, and transfer subscriptions by id or token
- **Outcomes** — Retrieve outcome analytics with platform and attribution filters
- **Players** — Export player CSVs for offline analysis or migration

## Why Jentic

- **Setup:** Wiring the full OneSignal API by hand means managing its REST API key and building calls across 55 endpoints for apps, users, segments, subscriptions, and outcomes against api.onesignal.com yourself. Through Jentic you install once, import the OneSignal API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** OneSignal puts the app id in the URL path (/apps/{app_id}/segments, /apps/{app_id}/users), so a rule can pin your agent to one app: it can manage segments and users for that app and nothing else. You choose the operations it may call, so creating apps or exporting players are not included unless you add them.
- **Credential handling:** Your OneSignal REST API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a onesignal segment' or 'add a onesignal user', and Jentic returns the matching OneSignal operation across the 55-endpoint surface with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OneSignal API (minimal)** — The minimal OneSignal entry covering only the notification creation endpoint.
- **Pusher Beams** — Pusher Beams is an alternative push notification delivery platform.
- **Pushover API** — Pushover offers a simpler push API focused on personal and developer use cases.

## FAQ

### Why is there no official OpenAPI spec for OneSignal API (Full)?

OneSignal does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call OneSignal API (Full) via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the OneSignal API (Full) use?

The API uses an apiKey credential - the OneSignal REST API Key sent in the Authorization header. Through Jentic the key is held encrypted in the vault (your Jentic One instance) and the agent only sees a scoped reference.

### Can I manage OneSignal segments programmatically?

Yes. POST /apps/{app_id}/segments creates a segment, GET lists segments, PATCH updates an existing segment, and DELETE removes it. Segments can then be referenced when sending notifications.

### How do I transfer a subscription between users?

Use PATCH /apps/{app_id}/subscriptions/{subscription_id}/owner with the target user's identity. The endpoint reassigns the subscription so future activity is attributed to the new owner.

### Does the OneSignal API expose outcome analytics?

Yes. GET /apps/{app_id}/outcomes returns aggregated counts for named outcomes filtered by time range, platform, and attribution window, suitable for campaign reporting.

### What are the rate limits for the OneSignal API (Full)?

Rate limits are not declared in this OpenAPI spec. Consult documentation.onesignal.com for the current REST API limits, which differ by endpoint family.

### How do I run a OneSignal segment update through Jentic?

Run pip install jentic, search 'update onesignal segment', then load the PATCH /apps/{app_id}/segments/{segment_id} schema and execute. Jentic injects the REST API key from its vault.

### Can I limit what my agent is allowed to do with the OneSignal API?

Yes. Because you run Jentic One yourself, your own rules decide which OneSignal operations and credentials the agent may use. OneSignal carries the app id in the URL path, such as /apps/{app_id}/segments and /apps/{app_id}/users, so a rule can pin the agent to a single app and let it manage only that app's segments and users. You also choose the exact operations it can call, so actions like creating apps or exporting player records stay off limits unless you add them.