# The SDKs and APIs

Airship's SDKs expose messaging and data-gathering functionality on your client devices, and our APIs support messaging mediums that can't use an SDK. Airship has SDKs for iOS, Android/Fire OS, Windows, and Web platforms. The APIs correspond to Airship's engagement (messaging) and real-time event stream products.

## SDK Uses

The SDK registers [channels](https://www.airship.com/docs/reference/glossary/#channel_dev) and interprets
notifications sent from Airship. You must integrate the SDK with your app
or website in order to issue notifications to your mobile and/or web audiences.
Devices that have installed your app and web browsers that have opted-in are
eligible to receive notifications. Refer to your app's
[platform documentation](https://www.airship.com/docs/developer/sdk-integration/) for help integrating and
using the SDK.

## API Uses

Most features are available via the
APIs, however some are available only from the
[Dashboard](https://www.airship.com/docs/reference/glossary/#dashboard).
Dashboard- and API-only exceptions are noted throughout the docs. See
[API vs Dashboard](#api-vs-dashboard)
below for more information.

[Airship API](https://www.airship.com/docs/developer/rest-api/ua/)
: Create and send messages to users, and use advanced messaging features like [Automation](https://www.airship.com/docs/reference/glossary/#automation). This API encompasses the majority of the Airship feature set.

[Data Streaming API](https://www.airship.com/docs/developer/rest-api/connect/)
: Access your app's event stream, helping you gather information about user
   interactions with your notifications and app. With [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds), you have access
   to the data that will help you maximize the effectiveness of your
   communications.

## Channel Registration

Airship's SDK and Airship API are fundamental to the platform, as they are the
mechanisms for registering [channels](https://www.airship.com/docs/reference/glossary/#channel_dev). Channel
registration is a basic requirement for sending notifications; you cannot send
notifications to a channel that is not registered or in the process of becoming
registered.

### SDK vs API

The SDK enables communications with mobile devices and web browsers; it makes
devices and browsers Airship clients. You will bundle the SDK with your
app or website to register and issue notifications to mobile devices and web
browsers.

For an [Open Platform](https://www.airship.com/docs/reference/glossary/#open_platform), you will use our
[Channels API](https://www.airship.com/docs/guides/getting-started/developers/channels-intro/#channels-api)
to register and manage the opt-in/opt-out status of end users.


### Registration Requirements

This table represents the minimum requirements for communicating with the
various channels supported by Airship. A channel must either have
installed the SDK or be registered via the API.

| Channel type | API registration | SDK registration |
| --- | :---: | :---:|
| App | | ✓ |
| Web | | ✓ |
| Email | ✓ | |
| SMS | ✓ | |
| Open Channel | ✓ | ✓ |

## Authentication

<!-- moved:

You make use of all Airship features from within a project or using your
   project's app key. Each of your apps or websites requires an individual
   Airship project, which will have separate application keys and audiences. 

-->

All Airship APIs require authentication. Some
endpoints allow multiple authentication schemes. In general, your app should
use Basic App authentication, and server-side implementations should use
Bearer authentication where available. See also:
[App Keys & Secrets: Security](https://www.airship.com/docs/guides/getting-started/developers/app-keys-secrets/).

| Auth type | Value | API | Description |
|-----------|-------|----------|-------------|
| Basic App | App Key and App Secret, Base64 encoded |<ul><li>Airship</li><li>Wallet</li></ul>| The typical authentication scheme for apps integrating with Airship. Basic App authentication is limited to low-security API endpoints, ensuring that users can't compromise your data with your app in the wild.|
| Basic Master | App Key and Master Secret, Base64 encoded |<ul><li>Airship</li><li>Compliance Data Streaming</li></ul>| Grants access to the complete Airship API and should be reserved for server-to-server communications only. You should not give out your Master Secret or use Basic Master authorization with your app.
| Bearer | Bearer Token | <ul><li>Airship</li><li>Data Streaming</li></ul> | Bearer authentication uses a token that you can create and revoke. Because you can create and revoke tokens for your team at will, bearer authentication maximizes your control over who can access Airship. |


## API vs Dashboard

It may be helpful to think of Airship APIs as an expansion of the dashboard
feature set. You can do almost anything via the API that you would do using the
dashboard — with notable additions, such as:

* Use the `custom-events` endpoint to associate external data with channels and users.
* Open an event stream with the Data Streaming API to determine the effectiveness of your notifications.
* Use `open-channels` to communicate with channels and platforms that aren't natively supported by Airship.

> **Note:** Some API endpoints may be restricted by your Airship feature bundle.
> [Contact Airship Sales](https://www.airship.com/contact-us/) if you do not have access to an endpoint or
> feature that you want to take advantage of.


> **Tip:** If you use an AI coding assistant, you can connect it to Airship with Skills and an MCP server. See [Airship AI Tools](https://www.airship.com/docs/developer/ai-tools/ai-tools/).

### Airship

The Airship API and dashboard support similar functionality, with some
differences in terminology between the two. The tables below map message types,
composer types, and features to their respective API objects and endpoints.


#### Message Types

| Message type | Dashboard | API object | Requires SDK |
|---------------|:---------:|-----------|:------------:|
| Push Notification | &#10003; | `"notification": {}` | &#10003; |
| Silent Push Notification | &#10003; | `"notification": {}` | &#10003; |
| Web Push Notification | &#10003; | `"notification": { "web": {}}` | &#10003; |
| In-App Message | &#10003;| `"in_app": {}` <sup>1</sup>  | &#10003; |
| Message Center | &#10003; | `"message": {}` | &#10003; |
| Apple News Notification | &#10003; | Not supported |  |
| Email Notification | &#10003; | `"notification": { "email": {}}` |  |
| SMS Notification | &#10003; | `"notification": { "sms": {}}` |  |

<sup>1. There is currently no API for in-app automation.</sup>


#### Composers and API Equivalents

| Composer | API endpoint|
| --- | --- |
| Message | `/push` |
| A/B Test | `/experiments` |
| Automation | `/pipelines` |
| In-App Automation | Not supported |
| Scene | Not supported |
| Sequence | Not supported |
| Apple News | Not supported |

#### Features

Some features, e.g., tags and named users, can be set via the API (server-side)
or the SDK (device-side) but not via the dashboard.

| Feature | Dashboard | API endpoint |
|---------|:---------:|--------------|
| Email Channel registration |  | `/channels/email` |
| SMS Channel registration |  | `/channels/sms` |
| Open Channel registration<sup>1</sup> | | `/channels/open` |
| Named Users<sup>2</sup> | | `/named-users` |
| Tags<sup>2</sup> | &#10003; | various |
| Segments | &#10003; | `/segments` |
| Lists | &#10003; | `/static-lists` |
| Custom Events | | `/custom-events` |
| Reports | &#10003; | `/reports` |
| Location | &#10003; | |

<sup>1</sup> Open Channels require a webhook server that will accept a `/push` payload.<br>
<sup>2</sup> Named users and tags can be set client-side, via the SDK.


### Real-Time Data Streaming

**Real-Time Data Streaming is an API-only feature.** The Date Streaming API consists of a single endpoint
that opens a real-time event stream for a messaging project. You can authorize
event streams for various apps via the dashboard, but you can only access an event stream via the API.

The event stream reflects user actions, changes in device environment, e.g.,
encountering beacons, and server-side actions, e.g., sending push notifications.
You can use the event stream to gather information about how users use your app
and determine effectiveness of your communications with your users.

When you make a call to the Data Streaming API, you can set the criteria that
determines the events the stream will return. See the
[Data Streaming API Reference](https://www.airship.com/docs/developer/rest-api/connect/) for help with opening and
filtering the event stream.