Introduction

Airship provides a number of REST API endpoints collectively known as the Airship API Version 3, in support of our messaging product lines and related features. Version 3 is the current and only supported version of the Airship API.

API Request Format

All API requests are HTTP requests. For all requests with a body, the body may be in JSON  format or other formats like CSV as specified for the endpoint. The proper Content-Type for JSON is application/json and the proper content type for CSV is text/csv.

Date-Time Format

All date-time values are represented as a string according to ISO 8601  in UTC.

• The string must be in the format YYYY-MM-dd['T']hh:mm:ss['Z'] where the T can be replaced by a space and the Z is optional.
• A T separator is preferred but not required. It will be included in all date-time values generated by the API. For example:
  • 2023-11-13T09:42:30Z
  • 2023-11-13T09:42:30
  • 2023-11-13 09:42:30Z
  • 2023-11-13 09:42:30
• A trailing time zone identifier or offset should not be included.
• UTC is implicit.

Color Format

All color values are represented by a string format reminiscent of CSS color values used for web programming. The format is #rrggbb, a literal # character followed by 6 hexadecimal digits representing 3 values in the range 00 to FF. The values are red, green, and blue color components.

API Response Format

All API responses are HTTP responses, making use of appropriate HTTP response codes. When a body is present, it SHALL be in JSON  format, except in certain cases where reporting data MAY be returned in CSV format. The body of all JSON responses SHALL consist of a single JSON object, which SHALL contain a boolean ok attribute indicating overall success or failure. When a request results in a return value containing multiple entities, they SHALL be contained in an array-valued attribute, the name of which MAY vary by endpoint. For example, /api/tag will return a list of tags in the tags attribute, while /api/schedules will return a list of schedules in the schedules attribute. The name of the response object attribute containing the list of returned entities SHALL be contained in the Data-Attribute HTTP header.

Operation ID

All API calls that create or modify resources, or cause side effects, SHALL generate an operation ID. An operation ID is an opaque unique string that identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. For example, the batch push API call can be used to send multiple pushes in one call. Each push has a unique push ID, but they will all share a common operation ID. This enables roll-ups of multiple related operations (such as push to local time or push to language) and better end-to-end tracing in the push pipeline. Operation IDs are returned in the JSON body of the response, in the operation_id attribute of the root response object. An operation ID will be generated even for error responses.

Response Codes

The API makes use of standard HTTP response codes, with standard HTTP semantics. Response codes in the 200 range indicate success. Codes in the 400 range indicate errors of a correctable nature. Codes in the 500 range indicate system errors.

This table lists general response definitions. Refer to the actual response definition per endpoint.

Validation

All requests must be validated. Proper validation at the API level can prevent invalid pushes from using resources in our delivery pipeline and educate API users about their own mistakes without involving Support. In the event of an error processing the request, the response body will contain one or more error objects. Parsing errors, arising from syntactically invalid JSON, should return an HTTP 400 Bad Request response. Semantic errors, arising from requests that are syntactically valid but otherwise malformed (for example, missing required fields), should return an HTTP 400 response, with a JSON body indicating details about the validation failure.

Some examples of specific validation cases that cause pushes to be rejected with an HTTP 400 error:

• Invalid attributes — Any additional JSON keys that are not explicitly allowed by the spec will result in an HTTP 400 error, except where arbitrary keys are explicitly allowed (for example, the extra sections of a push payload).
• Unconfigured open platform — Any open platform specified in the device_types array must be configured and active for the appKey. If the open platform is not configured, we will return an HTTP 400.
• Missing payload — A push that specifies delivery to a platform but does not supply a payload for that platform is invalid.
• Device identifier/restriction mismatch — A push that includes a device identifier in the audience selection but does not include the corresponding platform in the device_types specifier is invalid.
• Schedule times — Requests to schedule pushes for times that have already passed will return an HTTP 400 response. However, requests to schedule local time pushes for a time that has elapsed in a local time zone will be accepted.
• Unsupported platform feature — A push that includes features not supported on all platforms must explicitly target the supported platforms. Location is the only feature not supported across all platforms. This includes location expressions in predefined segments. Location pushes must specify device_types : [ ios, android ], or either iOS or Android explicitly.

Pagination

Some resource collections, such as tags and segments, may have a very large number of items, necessitating iterating through them in chunks (or pages) if an API consumer wishes to retrieve them all.

Request Parameters

There are two methods for pagination results:

• start and limit
• page and page_size

Using a non-unique identifier for the start parameter is unsound and will not paginate correctly. For endpoints that support sorting, if sorting is applied to a non-unique field, a secondary sort on a unique field must be used internally to ensure stable pagination results.

• start — Optional string or integer. Identifies the starting element for paginating results. It can be either a unique string identifier or a zero-based offset, depending on the API.
• limit — Optional integer. The maximum number of elements to return.
• page — Optional integer. Specifies which page to retrieve, starting with 1.
• page_size — Optional integer. The number of elements to return per page. The last page may have fewer elements.
• sort — Optional string. The name of the field to sort results by. This is not necessarily supported by all endpoints.
• order — Optional asc or desc. If the sort parameter is available, this parameter may be used to specify the direction of the sort as ascending or descending.

Link Header

Collections of entities SHALL be paginated by specifying a start point and a limit on the number of returned items as parameters of the request. The response SHALL include the requested items and a link to the next page of results. A link to the previous page MAY also be included if the underlying service supports it. For example, the Segments API supports previous page links. The links SHALL be provided in the Link HTTP header, as per RFC 5988 Web Linking , using the relations next and prev.

Count and Total

The number of items in the response SHALL be returned in the custom HTTP header Count, as well as in the "count" field of the response object. The total number of items in the collection MAY be returned in the custom HTTP header Total-Count, as well as in the "total_count" field of the response object, if the collection is countable and the total number of items is known.

Version Syntax

You must specify the version of the API you are using with the Accept HTTP header. If you do not specify an API version in the Accept header, a 406 is returned.

The content type used is a vendor-specific media type (see RFC 4288 Media Type Specifications and Registration Procedures ) and must be specified as: application/vnd.urbanairship+json; version=3.

Transport Layer Security

As of October 6, 2020, Airship supports only Transport Layer Security (TLS) versions 1.2 and 1.3 in our APIs, in accordance with PCI Security Standards Council  recommendations.

If your API integration uses TLS 1.0 or 1.1, contact our Support team  for assistance migrating to TLS 1.2 or 1.3.

Delivery Speed Options

The Airship push API is designed for extremely high throughput to ensure delivery to your entire audience as fast as possible. Depending on the size and/or complexity of your audience and the urgency of the message, you may find that you need to either slow down or speed up the delivery. To that end, we offer the following add-on services: Boost and Throttling.

If you are interested in enabling Boost or Throttling, contact Support .

Boost

Boost optimizes your segmented messages through parallel processing. Consider adding Boost if your notifications are extremely time-sensitive. Boost is a paid add-on. Contact your Account Manager for details.

Throttling

For less time-sensitive messages, our standard delivery speed may cause undue pressure on your internal systems or APIs, for example, when millions of users open your app at the same time. Use Throttling to tune delivery to a level that doesn’t put strain on those systems.

Complex segments can cause delays in processing

When creating segments or pushes with logical expressions, keep in mind that one or more NOT statements may cause latency when sending notifications, as NOT operations are inherently more expensive to perform than OR or AND operations. For example, tag_a AND NOT tag_b is basically the same speed as tag_a AND tag_b, but just NOT tag_b is likely to be slower than just tag_b.

Latency is more significant with larger audiences. We recommend using AND statements in place of NOT statements whenever possible as a best practice.

Device changes can take a few minutes

Some requests to register or unregister information about a device may take a few minutes to process before you are able to see the changes. Keep this in mind when performing PUT or POST requests.