canonical: https://jentic.com/apis/airship.com/airship

# Airship REST API

Jentic publishes the only available OpenAPI specification for Airship REST API, keeping it validated and agent-ready. Airship is a customer engagement platform best known for push notifications across iOS, Android, and web, with extensions for in-app messages, named-user identity, segmentation, and tags. The 16 documented endpoints cover sending and validating pushes, managing channels and named users, associating channels with named-user IDs, and bulk tag operations. Authentication uses HTTP Basic with the Airship app key and master secret.

## For AI agents

Send push notifications, validate payloads before sending, and manage channels, named users, and tags across mobile and web audiences.

## Scope

Does not handle email delivery, SMS, voice calls, or transactional payments - use for push notifications, in-app messaging, and audience identity management only.

## Capabilities

- Send push notifications to channels, segments, named users, or tags via POST /push
- Validate a push payload without sending via POST /push/validate
- Look up an individual channel record by channel ID
- Associate or disassociate a device channel with a named-user identifier
- Add or remove tags in bulk on channels or named users
- List all channels and named users for audience auditing

## Use cases

### Cross-Platform Push Broadcast

Send a single push notification to a unified audience across iOS, Android, and web by POSTing a payload to /push with an audience selector and platform overrides. Airship handles fan-out, retries, and per-platform formatting (APNs, FCM, web push). Suitable for marketing announcements, news alerts, and product launch broadcasts.

Example prompt: Send a push to audience { 'tag': 'subscribers' } with title 'Sale Today' and verify the response returns push_ids

### Named-User Identity Mapping

Associate device channels with a stable named-user identifier so a logged-in customer receives pushes on every registered device. POST /named_users/associate links a channel to a named-user ID; /named_users/disassociate reverses the link. The /named_users and /named_users/{named_user_id} endpoints expose the resulting identity graph.

Example prompt: Associate channel 'ch-12345' with named_user 'user-987' and confirm by looking up named_user 'user-987'

### Bulk Tag Management

Apply or remove tags across many channels or named users in a single API call via POST /channels/tags or POST /named_users/tags. Useful for syncing CRM segments to Airship, reacting to lifecycle events, or running re-engagement campaigns scoped to tagged audiences.

Example prompt: Add tag 'paid_user' to named_users ['user-1', 'user-2', 'user-3'] in a single bulk request

### Pre-Send Payload Validation

Catch malformed pushes before they hit the production audience by POSTing the payload to /push/validate. Airship returns the same validation errors it would surface during a real send, without dispatching to devices. Use during template development and CI checks.

Example prompt: Validate a push payload targeting tag 'beta_testers' and confirm the response returns ok:true

### Agent Push Sending via Jentic

An agent triggers Airship pushes by searching Jentic for the send-push operation, loading its schema, and executing with the audience and notification body. Jentic injects the Basic auth header derived from the Airship app key and master secret stored in the credential vault.

Example prompt: Search Jentic for 'send a push notification', load the Airship POST /push operation, and execute with audience 'all' and a transactional alert body

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /push | Send a push notification to an audience |
| POST | /push/validate | Validate a push payload without sending |
| GET | /channels | List device channels |
| GET | /channels/{channel_id} | Look up a channel by ID |
| POST | /channels/tags | Add or remove tags in bulk on channels |
| POST | /named_users/associate | Associate a channel with a named user |
| POST | /named_users/disassociate | Disassociate a channel from a named user |
| POST | /named_users/tags | Add or remove tags on named users |

## Key resources

- **Push** — Send and validate push notifications across platforms
- **Channels** — List and look up device channels by ID and apply tag operations
- **Named Users** — Map channels to user identities and manage tags on named users
- **Segments** — Audience selectors for targeted sends

## Why Jentic

- **Setup:** Wiring Airship by hand means constructing a Basic auth header from the app key and master secret, building push audience payloads, and writing your own retry logic. Through Jentic you install once, import Airship from the API Directory, store the app key and secret once, and your agent calls it.
- **Permission scoping:** Airship carries its push audience and tag targets in the request body, so scope your agent by operation: limit it to the operations it needs, such as sending a push or adding a tag to channels, and leave out named-user disassociation it does not use.
- **Credential handling:** Your Airship app key and master secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a push notification', and Jentic returns the matching POST operation with its audience and notification schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OneSignal API** — Push and in-app messaging with a generous free tier and simpler audience model
- **Firebase Cloud Messaging** — Google's push service for Android, iOS, and web tightly integrated with Firebase
- **SendGrid** — Pair email delivery with Airship push for multi-channel customer messaging
- **Twilio** — Add SMS and voice channels alongside Airship push for omnichannel reach

## FAQ

### Why is there no official OpenAPI spec for Airship REST API?

Airship does not publish a single OpenAPI specification for its REST API. Jentic generates and maintains this spec so that AI agents and developers can call Airship REST API 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 Airship REST API use?

Airship uses HTTP Basic auth: the username is the Airship app key and the password is the master secret. Through Jentic, both values are stored encrypted and the Authorization header is constructed at execution time so the master secret never enters the agent context.

### Can I send a push to a specific named user?

Yes. POST /push with an audience selector of { 'named_user': '<user_id>' } targets every channel associated with that named-user ID. Use POST /named_users/associate first to link channels to the user.

### What are the rate limits for the Airship REST API?

Airship applies per-app rate limits in the range of hundreds of requests per second for push and lower for management endpoints. Exact limits vary by plan; consult docs.airship.com. Treat HTTP 429 as a backoff-and-retry signal.

### How do I send a push notification through Jentic?

Install with pip install jentic, search for 'send a push notification', load the Airship POST /push operation, and execute with the audience and notification fields. Jentic injects the Basic auth header at execution time.

### Can I validate a push payload before sending it?

Yes. POST /push/validate runs the same validation as POST /push without dispatching to devices. Useful in CI pipelines and during template iteration to catch malformed audience selectors or platform overrides early.

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

Yes. Because your Jentic One instance is self-hosted, you set the rules for which Airship operations and credentials your agent can use. Airship carries its audience and tag targets in the request body, so you scope the agent by operation: grant only the calls it needs, such as POST /push to send notifications or POST /channels/tags to tag channels, and withhold operations like POST /named_users/disassociate that it never uses. The Airship app key and master secret are injected at execution time under your own rules, so the agent only ever exercises the operations you allow.