Airship API

Airship’s REST APIs for messaging, content personalization and audience management.

Libraries

Airship maintains open source server libraries to support your integrations with our APIs in multiple languages. Click below for library documentation.

• Python
• Java
• Ruby
• PHP

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 pre-defined 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.

Base URL

Select the domain associated with your Airship project.

• https://go.urbanairship.com
  The base URL for Airship’s North American cloud site when using HTTP authentication
• https://go.airship.eu
  The base URL for Airship’s European cloud site when using HTTP authentication
• https://api.asnapius.com
  The base URL for Airship’s North American cloud site when using OAuth authentication
• https://api.asnapieu.com
  The base URL for Airship’s European cloud site when using OAuth authentication

Authentication

For additional information, including steps for creating bearer tokens and OAuth client credentials, see Airship API Security.

• HTTP Authentication

  Basic Auth (App)
  Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App KeyThe unique identifier for your Airship project. It is used to authenticate the application for API calls. and App SecretA secret used to authorize requests for low-security API calls. It is intended to be embedded in your distributed application, and as such is limited in what it can do. in appKey:appSecret format. For example, Basic YXBwX2tleTphcHBfc2VjcmV0.

• HTTP Authentication

  Basic Auth (Master)
  Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your App KeyThe unique identifier for your Airship project. It is used to authenticate the application for API calls. and Master SecretA secret that can be used as the Basic authorization password for any API call. Guard the Master Secret carefully, and never embed it in an application you distribute to users. in appKey:masterSecret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0.

• HTTP Authentication

  Basic Auth (OAuth)
  Authorization header containing the word Basic followed by a space and a Base64-encoded string generated from your OAuth Client ID and Client Secret in client_id:client_secret format. For example, Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0. Used only for requesting OAuth tokens. See OAuth.

• HTTP Authentication

  Bearer Token
  Authorization header containing the word Bearer followed by a space and a bearer token generated from the Airship dashboard. You can generate tokens for different roles. If your role does not grant you access to a feature, the endpoint will respond with a 401 status code. Tokens can be revoked at will.

• OAuth Authentication

  OAuth 2.0
  Authorization header containing the word Bearer followed by a space and an OAuth 2.0 JWT bearer token provided by our authorization server. See OAuth.

OAuth

Request an OAuth 2.0 token using Basic Auth or an assertion.

Request Token

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic <base64 encoded string of "client_id:client_secret">

grant_type=client_credentials&sub=app:JQIMcndxIHWy2QISpt1SpZ&scope=chn&scope=nu&ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setClientSecret("<client_secret>")
        .setSub("<sub>")
        .setScopes(Arrays.asList("<scope1>","<scope2>","<...>"))
        .setIpAddresses(Arrays.asList("<IP1>","<IP2>",<...>))
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("yourAppKey")
        .setOAuthCredentials(oAuthCredentials)
        .build();

POST /token HTTP/1.1
Host: oauth2.asnapius.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&assertion=<encoded_jwt>

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "scope": "chn nu",
  "expires_in": 3600
}

OAuthCredentials oAuthCredentials = OAuthCredentials.newBuilder("<client_id>")
        .setAssertionJWT("<encoded_jwt>")
        .build();

UrbanAirshipClient oAuthClient = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setOAuthCredentials(oAuthCredentials)
        .build();

POST /token

Request an OAuth access token with Basic Auth or an assertion. When making a request with an assertion, do not provide the Basic Auth header. See also OAuth 2.0 in the API Security documentation.

Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when requesting an OAuth token.

Security:

• HTTP Basic Auth (OAuth)

• Content-Type : StringREQUIRED

  The request must have a Content-Type of application/x-www-form-urlencoded.

Request Body

• Content-Type: application/x-www-form-urlencoded

  One of

  • Request Token with Basic Auth : Object

    OBJECT PROPERTIES

    • grant_type : StringREQUIRED

      Possible values: client_credentials

    • ipaddr : String

      A list of CIDR representations of valid IP addresses to which the issued token is restricted. IP addresses can be sent as a URL-encoded, space-delimited list (example: ipaddr=24.20.40.0%2F24%202001%3A4860%3A4860%3A%3A8888%2F32) or as a list as expected in a query parameter form (example: ipaddr=24.20.40.0/24&ipaddr=2001:4860:4860::8888/32).

    • scope : OAuth Scope

      A list of scopes to which the issued token will be entitled. Scopes can be sent as URL-encoded, space-delimited list (example: scope=chn%20nu) or as a list as expected in a query parameter form (example: scope=chn&scope=nu).

    • sub : SubjectREQUIRED

      A space-delimited set of identifiers for which subjects a token is allowed. An app subject is required. Example: app:JQIMcndxIHWy2QISpt1SpZ.

  • Request Token with Assertion : Object

    OBJECT PROPERTIES

    • assertion : Assertion JWTREQUIRED

      An encoded JWT that contains the required headers and claims and is signed with the client credentials’ private key.

    • grant_type : StringREQUIRED

      Possible values: client_credentials

Responses

• 200

  Returned on token request success.

  RESPONSE HEADERS

  • Cache-Control : String

    Possible values: no-store

  • Content-Type : String

    Possible values: application/json

  • Pragma : String

    Possible values: no-cache

  RESPONSE BODY

  • Content-Type: application/json

    Issued access token.

    OBJECT PROPERTIES

    • access_token : String

      The issued token that can be used for all endpoints as allowed by set scopes.

    • expires_in : Integer

      The number of seconds from the time the token is generated until it expires.

    • scope : OAuth Scope

      A space-delimeted list of scopes of the issued token. There may be undocumented scopes in this list.

    • token_type : String

      The type of issued token.

      Possible values: Bearer

• 400

  Token not generated.

  RESPONSE BODY

  • Content-Type: application/json

    Token request error.

    OBJECT PROPERTIES

    • error : StringREQUIRED

      Error code.

      Possible values: invalid_scope, invalid_request, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_client

    • error_description : String

      A plain-text description of the error.

• 401

  Unauthorized.

  RESPONSE HEADERS

  • WWW-Authenticate : String

    The HTTP authentication methods that can be used to request an access token.

  RESPONSE BODY

  • Content-Type: application/json

    Authentication via the Authorization request header failed.

    OBJECT PROPERTIES

    • error : StringREQUIRED

      Error code.

      Possible values: invalid_client

    • error_description : String

      A plain-text description of the error.

• 406

  Not acceptable.

  RESPONSE BODY

  • Content-Type: application/json

    Unsupported Accept header. The request only supports application/json, application/x-www-form-urlencoded, text/plain.

    OBJECT PROPERTIES

    • error : StringREQUIRED

      Error code.

      Possible values: invalid_request

    • error_description : String

      A plain-text description of the error.

Key Verification

GET /verify/public_key/8817e96 HTTP/1.1
Host: oauth2.asnapius.com
Accept: text/plain

HTTP/1.1 200 OK
Content-Type: application/x-pem-file
Cache-Control: max-age=600, must-revalidate

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE7tcTz03ypC7PSPa73Cbgl7AbDDo+92eH
DWgjAi6vt1gmlHE35e+GhpcwbywBByOiooY+5bvfUHkc0aKy4R8VbBK0rYwlp8B+
fxyDr9Ye/oiUewMwwlp0z5AMPjgBUIKS
-----END PUBLIC KEY-----

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PublicKeyVerificationRequest request = PublicKeyVerificationRequest.newRequest("<kid>");
Response<String> response = client.execute(request);

GET /verify/public_key/{kid}

Retrieve the public key of a key ID. Use oauth2.asnapius.com for Airship’s North American cloud site and oauth2.asnapieu.com for Airship’s European cloud site when when verifying an OAuth public key.

• kid : StringREQUIRED

  The private key ID used to sign the token. Example: 8817e96

Responses

• 200

  Returned on success with the public key for the given kid.

  RESPONSE HEADERS

  • Cache-Control : String

    The response contains a Cache-Control header which must be respected.

  RESPONSE BODY

  • Content-Type: application/x-pem-file

    The PEM-formatted public key.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/json

    The error includes as much information as possible to help you understand the reason for the failure.

Push

Send notifications or rich messages to supported channels, or validate JSON payloads.

Send a Push

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()
push.audience = ua.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
push.notification = ua.notification(alert='Hello!')
push.device_types = ua.device_types('ios')
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.or( UA.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5'))
push.notification = UA.notification(alert: 'Hello!')
push.device_types = UA.device_types(['ios'])
push.send_push

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "device_types": [ "ios", "android" ],
   "audience": {
      "tag": "needs_a_greeting",
      "group": "new_customer"
   },
   "notification": {
      "alert": "Hi!"
   },
   "localizations": [
       {
          "language": "de",
          "country": "AT",
          "notification": {
             "alert": "Grüss Gott"
          }
       },
       {
          "language": "de",
          "country": "DE",
          "notification": {
             "alert": "Guten Tag"
          }
       }
    ]
 }

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "df6a6b50-9843-0304-d5a5-743f246a4946",
    "push_ids": [
        "9d78a53b-b16a-c58f-b78d-181d5e242078",
        "1cbfbfa2-08d1-92c2-7119-f8f7f670f5f6",
        "939c3796-a755-413b-a36b-3026b1f92df8"
    ],
    "localized_ids": [
       "1a38a2ba-c174-d32f-d01b-481a5d241934"
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization localization = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.or(Selectors.tagWithGroup("needs_a_greeting", "new_customer")))
        .addLocalization(localization)
        .setNotification(Notifications.alert("Hi!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
        .build();

PushRequest request = PushRequest.newRequest(payload);
Response<PushResponse> response = client.execute(request);

import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()

push.audience = ua.tag_group(tag_group="new_customer", tag="needs_a_greeting")
push.notification = ua.notification(alert='Hello!')
push.localizations = [
   ua.localization(country='at', language='de', notification=ua.notification(alert="Grüss Gott")),
   ua.localization(country='de', language='de', notification=ua.notification(alert="Guten Tag")),
]
push.device_types = ua.device_types('ios')
push.send()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag("needs_a_greeting", group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}
push.send_push

POST /api/push HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "tag": "needs_a_greeting",
        "group": "new_customer"
    },
    "device_types": [
        "email"
    ],
    "notification": {
      "email": {
        "message_type": "commercial",
        "reply_to": "no-reply@airship.com",
        "sender_address": "team@airship.com",
        "sender_name": "Airship",
        "template": {
            "template_id": "876624ff-0120-4364-bf02-dba3d0cb5b85"
        }
      }
    }
}

HTTP/1.1 202 Accepted
Data-Attribute: push_ids
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "be97b696-8d6b-4aec-ac50-c9cfc4be57d6",
    "push_ids": [
        "72ce9ade-aa71-4fbe-b960-246f1a2ca9ee"
    ],
    "message_ids": [],
    "content_urls": [],
    "localized_ids": []
}

POST /api/push

Send a push notification to a specified audience. The body of the request must be a Push Object or an array of Push Objects.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [psh]

Request Body

A single push object or an array of push objects.

• Content-Type: application/json

  One of

  • Push Object

    A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

  • Array of Push Objects. : Array [Push Object]

    Max items: 100 Min items: 1

Responses

• 202

  The push notification has been accepted for processing. The response contains push_id, message_id, and/or content_url arrays based on the type of push.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    A push response contains a list of identifiers for the notifications sent in the request.

    OBJECT PROPERTIES

    • content_urls : Array [String]

      An array of URLs where the push payload contains a landing page action. Max items: 100

    • localized_ids : Array [String]

      An array of identifiers used for reporting. Each ID represents a localized message (push object with localizations array).

    • message_ids : Array [String]

      An array of message IDs, each uniquely identifying a Message Center message.

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string identifying the operation, useful for reporting and troubleshooting. Format: uuid

    • push_ids : Array [String]

      An array of push IDs, each uniquely identifying a push. Max items: 100 Min items: 1

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 413

  The request included a payload larger than the maximum size of 5MiB.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 429

  There were too many similar requests in a short amount of time.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Push

POST /api/push/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "audience": {
        "ios_channel": "9c36e8c7-5a73-47c0-9716-99fd3d4197d5"
    },
    "notification": {
        "alert": "Hello!"
    },
    "device_types": [ "ios" ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

PushPayload payload = PushPayload.newBuilder()
        .setAudience(Selectors.iosChannel("9c36e8c7-5a73-47c0-9716-99fd3d4197d5"))
        .setNotification(Notifications.alert("Hello!"))
        .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS))
        .build();

PushRequest request = PushRequest.newRequest(payload).setValidateOnly(true);
Response<PushResponse> response = client.execute(request);

import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

push = airship.create_push()
push.audience = ua.ios_channel('9c36e8c7-5a73-47c0-9716-99fd3d4197d5')
push.notification = ua.notification(alert='Hello!')
push.device_types = ua.device_types('ios')
push.validate()

POST /api/push/validate

Accept the same range of payloads as POSTing to /api/push, but parse and validate only, without sending any pushes. The body of the request must be a Push Object or an array of Push Objects.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [psh]

Request Body

A single push object or an array of push objects.

• Content-Type: application/json

  One of

  • Push Object

    A push object describes everything about a push notification, including the audience and push payload. A push object is composed of up to seven attributes.

  • Array of Push Objects. : Array [Push Object]

    Max items: 100 Min items: 1

Responses

• 200

  The payload was valid.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3;

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 413

  The request included a payload larger than the maximum size of 5MiB.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Multiple Messages from Inbox

POST /api/user/messages/batch-delete HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "message_ids": [
        "drKa4OdxEeyhSwJC9TkdtQ",
        "W5ersOdxEeyvwAJCxz92iA"
    ]
}

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "deleted_message_ids": [
        "W5ersOdxEeyvwAJCxz92iA",
        "drKa4OdxEeyhSwJC9TkdtQ"
   ],
   "errors": []
}

HTTP/1.1 404 Not Found
Content-Type: application/vnd.urbanairship+json; version=3

{
    "deleted_message_ids": [],
    "errors": [
        {
            "message_id": "drKa4OdxEeyhSwJC9Tkdt1",
            "error_message": "Message not found.",
            "error_code": 40404
        },
        {
            "message_id": "W5ersOdxEeyvwAJCxz92i1",
            "error_message": "Message not found.",
            "error_code": 40404
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();
        
 List<String> arrayList = new ArrayList<>();
 arrayList.add("9dWD3LBIS5iZ51Y1GwOi4Q");
 arrayList.add("lsDtpTBJTN6KpQTwfOSNbw");

 InboxBatchDeleteRequest inboxBatchDeleteRequest = InboxBatchDeleteRequest.newRequest(arrayList);
 Response<InboxBatchDeleteResponse> response = client.execute(inboxBatchDeleteRequest);

POST /api/user/messages/batch-delete

Deletes multiple Message Center messages (up to 50 messages per request) completely, removing them from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

It is not possible to delete Message Center messages generated by an automation, a recurring message, or a Sequence.

Security:

• HTTP Basic Auth (Master)

Request Body

A request body containing an array of message IDs to be deleted.

• Content-Type: application/json

  Object

  An array of message IDs, each uniquely identifying a Message Center message.

  OBJECT PROPERTIES

  • message_ids : Array [String]REQUIRED

    Array of Message IDs. Max items: 50 Min items: 1

Responses

• 202

  The request has been accepted for processing.

  RESPONSE BODY

  • Content-Type: application/json

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Message from Inbox

DELETE /api/user/messages/(push_id) HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 202 Accepted
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

 InboxDeleteRequest request = InboxDeleteRequest.newRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
 Response<GenericResponse> response = client.execute(request);

import urbanairship as ua

airship = ua.Airship(key="<app key>", secret="<master secret>", location="<us|eu>")

ua.Push.message_center_delete(airship=airship, 
                              push_id="941086fd-f7db-493b-a8a7-1f5a7dc6aae4")

DELETE /api/user/messages/{push_id}

Delete a Message Center message completely, removing it from every user’s inbox. This is an asynchronous call; a success response means that the deletion has been queued for processing.

This delete call will work with either the message_id or the push_id of the accompanying push notification.

This endpoint will not work with a group_id from an automated message or a push to local time delivery. To delete a rich message that was part of an automated or local time delivery, you must use the relevant push_id from the operation.

Security:

• HTTP Basic Auth (Master)

• push_id : StringREQUIRED

  The push_id or message_id of the Rich Message you want to delete from users` inboxes.

  Format: uuid

Responses

• 202

  The request has been accepted for processing.

  RESPONSE BODY

  • Content-Type: application/json

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedules

Schedule notifications.

List Schedules

GET /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Count: 2
Data-Attribute: schedules
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "count": 2,
    "total_count": 4,
    "next_page": "https://go.urbanairship.com/api/schedules/?start=5c69320c-3e91-5241-fad3-248269eed104&limit=2&order=asc",
    "schedules": [
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed109",
            "schedule": { },
            "push": { }
        },
        {
            "url": "http://go.urbanairship/api/schedules/2d69320c-3c91-5241-fac4-248269eed10A",
            "schedule": { },
            "push": { }
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest();
Response<ListAllSchedulesResponse> response = client.execute(request);
List<SchedulePayloadResponse> schedules = response.getBody().get().getSchedules();

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

for schedule in ua.ScheduledList(airship):
    print(
    schedule.name, schedule.url, schedule.push_ids,
    schedule.schedule, schedule.push
    )

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

scheduled_push_list = UA::ScheduledPushList.new(client: airship)
scheduled_push_list.each do |schedule|
    puts(schedule)
end

GET /api/schedules

List all existing schedules. Returns an array of schedule objects in the schedules attribute.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• start : String

  An optional string ID of the starting element for paginating results.

• limit : Integer

  An optional integer as maximum number of elements to return. The default limit is 200 Schedule Objects per request. Set the limit to 200 or fewer in your API calls.

Responses

• 200

  Returned on success, with the JSON representation of the scheduled pushes in the body of the response.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • count : Integer

    • next_page : String

      There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results. Format: url

    • ok : Boolean

      Success.

    • schedules : Array [Schedule Object]

      An array of Schedule Objects.

    • total_count : Integer

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Schedule a Notification

POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
  {
    "name": "Morning People",
    "schedule": {
        "scheduled_time": "2020-06-03T09:15:00"
    },
    "push": {
        "audience": { "tag": "earlyBirds" },
        "notification": { "alert": "Good Day Sunshine" },
        "device_types": [ "ios", "android" ]
    }
  },
  {
    "name": "Everybody Else",
    "schedule": {
        "best_time": {
          "send_date": "2020-06-03"
        }
    },
    "push": {
        "audience": { "tag": "normalPeople" },
        "notification": { "alert": "Stay Up Late" },
        "device_types": [ "ios", "android" ]
    }
  }
]

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Morning People")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-06-03T09:15:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Good Day Sunshine"))
                .setAudience(Selectors.tag("earlyBirds"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);

import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
sched = airship.create_scheduled_push()
sched.name = 'Morning People'
sched.schedule = ua.scheduled_time(
  datetime.datetime.(2020, 6, 3, 9, 15, 0)
)
sched.push = airship.create_push()
sched.push.audience = ua.tag('earlyBirds')
sched.push.notification = ua.notification(alert='Good Day Sunshine')
sched.push.device_types = ['ios', 'android']
sched.send()

response = sched.send()
print ('Created schedule. URL:', response.schedule_url)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('earlyBirds')
push.notification = UA.notification(alert: 'Morning People')
push.device_types = UA.device_types(['ios','android'])

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Morning People"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

POST /api/schedules HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
  {
    "name": "Greetings",
    "schedule": {
        "best_time": {
          "send_date": "2020-11-15"
        }
    },
    "push": {
        "device_types": [
          "ios",
          "android"
        ],
        "audience": {
          "tag": "needs_a_greeting",
          "group": "new_customer"
        },
        "notification": {
          "alert": "Hi!"
        },
        "localizations": [
          {
              "language": "de",
              "country": "AT",
              "notification": {
                "alert": "Grüss Gott"
              }
          },
          {
              "language": "de",
              "country": "DE",
              "notification": {
                "alert": "Guten Tag"
              }
          }
        ]
    }
  }
]

HTTP/1.1 201 Created
Data-Attribute: schedule_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "efb18e92-9a60-6689-45c2-82fedab36399",
   "schedule_urls": [
        "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
        "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
    "schedule_ids": [
        "eac2ace6-349a-41a2-b874-5496d7bf0100",
        "6c7c9bf5-cb2b-47cb-b27f-f85981391c4e"
    ],
   "schedules": [
      {
         "url": "https://go.urbanairship.com/api/schedules/eac2ace6-349a-41a2-b874-5496d7bf0100",
         "schedule": {
            "scheduled_time": "2020-06-03T09:15:00"
         },
         "name": "Morning People",
         "push": {
            "audience": { "tag": "earlyBirds" },
            "notification": { "alert": "Good Day Sunshine" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "83046227-9b06-4114-9f23-0df349792bbd" ]
      }
      {
          "url": "https://go.urbanairship.com/api/schedules/6c7c9bf5-cb2b-47cb-b27f-f85981391c4e",
          "schedule": {
            "best_time": {
              "send_date": "2020-06-03"
            }
          },
          "name": "Everybody Else",
          "push": {
            "audience": { "tag": "normalPeople" },
            "notification": { "alert": "Stay Up Late" },
            "device_types": [ "ios", "android" ]
         },
         "push_ids": [ "8438e81-bb31-82a9-5feb-e7fd5b21ca7e" ]
      }
   ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

Localization one = Localization.newBuilder()
        .setCountry("AT")
        .setLanguage("de")
        .setNotification(Notifications.alert("Grüss Gott"))
        .build();

Localization two = Localization.newBuilder()
        .setCountry("DE")
        .setLanguage("de")
        .setNotification(Notifications.alert("Guten Tag"))
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("Greetings")
        .setSchedule(Schedule.newBuilder()
                .setBestTime(BestTime.newBuilder()
                        .setSendDate(DateTime.parse("2020-11-15T00:00:00Z"))
                        .build())
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Hi!"))
                .setAudience(Selectors.tagWithGroup("needs_a_greeting", "new_customer"))
                .addLocalization(one)
                .addLocalization(two)
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newRequest(schedulePayload);
Response<ScheduleResponse> response = client.execute(scheduleRequest);

import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = airship.create_scheduled_push()
sched.name = 'Greetings'
sched.schedule = ua.best_time(datetime.datetime(2020, 11, 15))

sched.push = airship.create_push()
sched.push.audience = ua.tag_group(tag_group="new_customer", tag="needs_a_greeting")
sched.push.notification = ua.notification(alert='Good Day!')
sched.push.device_types = ['ios', 'android']
sched.push.localizations = [
    ua.localization(country='at', language='de', notification=ua.notification(alert="Grüss Gott")),
    ua.localization(country='de', language='de', notification=ua.notification(alert="Guten Tag")),
 ]

response = sched.send()
print ('Created schedule. URL:', response.schedule_url)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

push = airship.create_push
push.audience = UA.tag('needs_a_greeting', group:'new_customer')
push.notification = UA.notification(alert: 'Hi!')
push.device_types = UA.device_types(['ios', 'android'])
push.localizations = {
  "language": "de",
  "country": "AT",
  "notification": {
  "alert": "Grüss Gott"
  }
}

schedule = airship.create_scheduled_push
schedule.push = push
schedule.name = "Greetings"
schedule.schedule = UA.scheduled_time(Time.now.utc + 60)
response = schedule.send_push
print ("Created schedule. url: " + response.schedule_url)

POST /api/schedules

Scheduled notifications are created by POSTing to the schedule URI. The body of the request must be one of a single schedule object or an array of one or more schedule objects.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [psh]

Request Body

A single schedule object or an array of schedule objects. For Local Time Delivery, include no more than 100 Schedule Objects in your batch request.

• Content-Type: application/json

  One of

  • Array [Schedule Object]

    Max items: 1000

  • Schedule Object

    A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

• 201

  The response body will contain an array of response objects with the created resource URIs.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. Format: uuid

    • schedule_ids : Array [String]

      An array of schedule IDs, each string uniquely identifying a schedule. Max items: 100 Min items: 1

    • schedule_urls : Array [String]

      An array of schedule URLs. Max items: 100

    • schedules : Array [Schedule Object]

      An array of schedule objects.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 413

  The number of schedules in the array exceeded the maximum amount (error_code 41301). The request included a payload larger than the maximum size of 5MiB (error_code 41307).

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List a Specific Schedule

GET /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas"                       ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleListingRequest request = ScheduleListingRequest.newRequest("5cde3564-ead8-9743-63af-821e12337812");
Response<ListAllSchedulesResponse> response = client.execute(request);
SchedulePayloadResponse schedule = response.getBody().get().getSchedules().get(0);
// Get the schedule's name
Optional<String> name = schedule.getName();
// Get the push IDs
Set<String> pushIds = schedule.getPushIds();
// Get the scheduled time
Schedule sched = schedule.getSchedule();
// Get the associated push payload
PushPayload payload = schedule.getPushPayload();
// Get the URL
Optional<String> url = schedule.getUrl();

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
scheduled_push = UA::ScheduledPush.new(airship)
schedule_details = scheduled_push.list(schedule_id: '5cde3564-ead8-9743-63af-821e12337812')
puts(schedule_details)

GET /api/schedules/{schedule_id}

Fetch the current definition of a single schedule resource. Returns a single schedule object.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• schedule_id : StringREQUIRED

  The ID of a schedule.

Responses

• 200

  Returned on success, with the JSON representation of the scheduled push in the body of the response.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Schedule

PUT /api/schedules/5cde3564-ead8-9743-63af-821e12337812 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
   "name": "I would like to subscribe to your newsletter",
   "schedule": {
      "scheduled_time": "2020-04-01T18:45:30"
   },
   "push": {
      "audience": {
         "tag": [
            "intriguing",
            "ideas",
            "thought_leadership"
         ]
      },
      "notification": {
         "alert": "Check your inbox!"
      },
      "device_types": [ "ios", "android" ]
   }
}

HTTP/1.1 200 OK
Content-Length: 123
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "7c56d013-5599-d66d-6086-6205115d85e2",
    "schedule_urls": [ "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e" ],
    "schedules": [
        {
            "url": "https://go.urbanairship.com/api/schedules/0af1dead-e769-4b78-879a-7c4bb52d7c9e",
            "schedule": {
                "scheduled_time": "2020-04-01T18:45:30"
            },
            "name": "I would like to subscribe to your newsletter",
            "push": {
                "audience": {"tag": ["intriguing", "ideas", "thought_leadership"] },
                "notification": {"alert": "Check your inbox!"},
                "device_types": [ "ios", "android" ]
            },
            "push_ids": [ "48fb8e8a-ee51-4e2a-9a47-9fab9b13d846" ]
        }
    ]
}

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

SchedulePayload schedulePayload = SchedulePayload.newBuilder()
        .setName("I would like to subscribe to your newsletter")
        .setSchedule(Schedule.newBuilder()
                .setScheduledTimestamp(DateTime.parse("2020-04-01T18:45:00Z"))
                .build())
        .setPushPayload(PushPayload.newBuilder()
                .setDeviceTypes(DeviceTypeData.of(DeviceType.IOS, DeviceType.ANDROID))
                .setNotification(Notifications.alert("Check your inbox!"))
                .setAudience(Selectors.tag("intriguing"))
                .build())
        .build();

ScheduleRequest scheduleRequest = ScheduleRequest.newUpdateRequest(schedulePayload, "5cde3564-ead8-9743-63af-821e12337812");
Response<ScheduleResponse> response = client.execute(scheduleRequest);

import datetime
import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')

# change scheduled time to tomorrow
schedule.schedule = ua.scheduled_time(
    datetime.datetime.utcnow() + datetime.timedelta(days=1))
resp = schedule.update()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/5cde3564-ead8-9743-63af-821e12337812')
# change scheduled time to tomorrow
schedule.schedule = UA.scheduled_time(Time.now.utc + (60 * 60 * 24))
schedule.update

PUT /api/schedules/{schedule_id}

Update the state of a single schedule resource. The body must contain a single schedule object. A PUT cannot be used to create a new schedule; it can only be used to update an existing one. A push to local time schedule cannot be updated once it has begun sending pushes to a time zone.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• schedule_id : StringREQUIRED

  The ID of a schedule.

Request Body

A single schedule object.

• Content-Type: application/json

  Schedule Object

  A schedule object consists of a schedule, i.e., a future delivery time, an optional name, and a push object.

Responses

• 200

  Returned if the scheduled push has been successfully updated.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string which identifies a single API call, and can be used to group multiple entities or side effects as related, in reporting and troubleshooting logs. Format: uuid

    • schedule_urls : Array [String]

      An array of schedule URLs. Max items: 100

    • schedules : Array [Schedule Object]

      An array of schedule objects.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 409

  Returned if the local time scheduled push is in progress.

• 413

  The request included a payload larger than the maximum size of 5MiB.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Delete Schedule

DELETE /api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66 HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 204 No Content

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleDeleteRequest request = ScheduleDeleteRequest.newRequest("b384ca54-0a1d-9cb3-2dfd-ae5964630e66");
Response<GenericResponse> response = client.execute(request);

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
schedule = ua.ScheduledPush.from_url(airship, 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')

# Cancel schedule
schedule.cancel()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

schedule = airship.create_scheduled_push
schedule = UA::ScheduledPush.from_url(client: airship, url: 'https://go.urbanairship.com/api/schedules/b384ca54-0a1d-9cb3-2dfd-ae5964630e66')
schedule.cancel

DELETE /api/schedules/{schedule_id}

Delete a schedule resource, which will result in no more pushes being sent. If the resource is successfully deleted, the response does not include a body.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• schedule_id : StringREQUIRED

  The ID of a schedule.

Responses

• 204

  The delete operation was successful.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Pause a Schedule

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/pause HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest pauseRequest = ScheduleStatusRequest.pauseScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> pauseResponse = client.execute(pauseRequest);      

import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = ua.ScheduledPush(airship)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.pause()

POST /api/schedules/{schedule_id}/pause

Pause a recurring scheduled message, preventing Airship from sending messages on a recurring scheduled message interval. Use the /resume endpoint to resume a schedule. The pause operation cannot be completed for recurring schedules that have schedule end times in the past.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• schedule_id : StringREQUIRED

  The ID of the schedule you want to pause.

Request Body

A pause request is empty.

• Content-Type: application/json

  Object

Responses

• 204

  The pause operation was successful.

• 400

  Returned if the schedule end time for a recurring schedule is in the past.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 500

  Occurs if a schedule fails to pause. The error includes a list of failed_triggers, detailing the schedule triggers that caused this operation to fail.

  RESPONSE BODY

  • Content-Type: application/json

    OBJECT PROPERTIES

    • error : String

      A description of the error.

    • error_code : Integer

      An error code representing the HTTP status and a more specific Airship error, if known.

    • failed_triggers : Array [Object]

      ARRAY ITEM
      • OBJECT PROPERTIES

        • id : String

          The list of failed schedule triggers. Format: uuid

        • state : String

          The reason that the operation failed.

          Possible values: BLOCKED, FAILED

    • ok : Boolean

      If false, an error occurred.

Resume a Schedule

POST /api/schedules/5cde3564-ead8-9743-63af-821e12337812/resume HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3

UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .build();

ScheduleStatusRequest resumeRequest = ScheduleStatusRequest.resumeScheduleRequest("68b2d71f-1c10-4592-bd96-2725aee0ae57");
Response<GenericResponse> resumeResponse = client.execute(resumeRequest);

import urbanairship as ua

airship = ua.Airship('<app key>', '<master secret>')

sched = ua.ScheduledPush(airship)
sched.url = "http://go.urbanairship/api/schedules/5cde3564-ead8-9743-63af-821e12337812"

sched.resume()

POST /api/schedules/{schedule_id}/resume

Resume a recurring schedule that you previously paused, beginning with the next scheduled interval. The resume operation cannot be completed for recurring schedules that have schedule end times in the past.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [sch]

• schedule_id : StringREQUIRED

  The ID of the schedule you want to resume.

Request Body

A resume request is empty.

• Content-Type: application/json

  Object

Responses

• 204

  The operation was successful.

• 400

  Returned if the schedule end time is in the past.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 500

  Occurs if a schedule fails to resume. The error includes a list of failed_triggers, detailing the specific schedule IDs that caused the operation to fail.

  RESPONSE BODY

  • Content-Type: application/json

    OBJECT PROPERTIES

    • error : String

      A description of the error.

    • error_code : Integer

      An error code representing the HTTP status and a more specific Airship error, if known.

    • failed_triggers : Array [Object]

      ARRAY ITEM
      • OBJECT PROPERTIES

        • id : String

          The list of failed schedule triggers. Format: uuid

        • state : String

          The reason that the operation failed.

          Possible values: BLOCKED, FAILED

    • ok : Boolean

      If false, an error occurred.

Automation

Manage Automated notifications using the /api/pipelines endpoints.

List Existing Pipelines

GET /api/pipelines/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "creation_time": "2020-03-20T18:37:23",
          "enabled": true,
          "immediate_trigger": {
            "tag_added": { "tag": "bought_shoes" }
          },
          "last_modified_time": "2020-03-20T19:35:12",
          "name": "Shoe buyers",
          "outcome": {
            "push": {
                "audience": "triggered",
                "device_types": [ "android" ],
                "notification": { "alert": "So you like shoes, huh?" }
            }
          },
          "status": "live",
          "uid": "3987f98s-89s3-cx98-8z89-89adjkl29zds",
          "url": "https://go.urbanairship.com/api/pipelines/3987f98s-89s3-cx98-8z89-89adjkl29zds"
      },
      {
          "..."
      }
    ]
}

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

for automation in ua.Automation(airship).list_automations():
  print(automation)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.limit = 5
automation.list_automations

GET /api/pipelines

List existing pipelines. Pipelines are ordered by creation_date from newest to oldest.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

• limit : Integer

  The maximum number of results to return. This is effectively the page size for the response. No default limit. For maximum performance, set your limit between 25 and 100.

  Min: 1

• enabled : Boolean

  If true, limits the listing to enabled pipelines ("enabled": true). If false or omitted, lists all pipelines, whether enabled is true or false.

• offset : Integer

  The first result you want to return. This parameter assists in pagination.

Responses

• 200

  Returned on success, with a JSON representation of pipelines matching your query parameters.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    The response body for a pipelines request.

    OBJECT PROPERTIES

    • next_page : String

      An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string identifying a single API call. Format: uuid

    • pipeline_ids : Array [String]

      An array of pipeline IDs.

    • pipeline_urls : Array [String]

      An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

    • pipelines : Array [Pipeline Object]

      A list of pipeline objects.

    • prev_page : String

      An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

    • total_count : Integer

      The total count of pipelines.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Create Pipeline (Automated Message)

POST /api/pipelines HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android",
            "web"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

HTTP/1.1 201 Created
Content-Length: 123
Data-Attribute: pipeline_urls
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "operation_id": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
    "pipeline_urls": [
      "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    ]
}

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

automation = ua.Automation(airship)
pipeline = ua.Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger=['first_open'],
    outcome={
        'audience': 'triggered',
        'device_types': ua.device_types('ios', 'android', 'web'),
        'notification': ua.notification(alert='Cool goatee, Abed')
    },
    timing={
        delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.create(pipeline.payload)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
details = automation.create_automation
puts(details)

POST /api/pipelines

Create one or more pipelines. You can provide a single pipeline object or an array of pipeline objects.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

Request Body

A single pipeline object or an array of pipeline objects.

• Content-Type: application/json

  One of

  • Pipeline Object

    A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

  • Array [Pipeline Object]

Responses

• 201

  If creating more than one pipeline, pipeline URIs are returned in the same order as the pipeline objects in the request.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    The response body for a create pipeline request.

    OBJECT PROPERTIES

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string identifying a single API call. Format: uuid

    • pipeline_urls : Array [String]

      An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 409

  The application has exceeded the maximum number of active or total pipelines. In order to increase pipeline maximum, contact Airship Support.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 413

  The request included a payload larger than the maximum size of 5MiB.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List Pipelines Constraints

GET /api/pipelines/constraints/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "constraints" : [
        {
            "rate" : {
                "pushes" : 30,
                "lifetimes" : 1
            }
        },
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}

GET /api/pipelines/constraints

Returns an array of cross-pipeline rate limit constraints. These are the rates that the combination of all pipelines for an app may not exceed.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

Responses

• 200

  Returns an array of cross-pipeline rate limit constraints.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • constraints : Array [Object]

      An array of rate objects determining the maximum number of messages each audience member can receive over a period of time.

      ARRAY ITEM

      • Rate Limit Constraint

        A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

        OBJECT PROPERTIES

        • rate : Any

          A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

          One of

          • Pushes/days constraint : Object

            Limits the number of pushes any individual audience member will receive from the pipeline over a number of days.

            OBJECT PROPERTIES

            • days : Integer

              An integer, specifying the time period in number of days. Max: 90

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

          • Pushes/hours constraint : Object

            Limits the number of pushes any individual audience member will receive from the pipeline over a number of hours.

            OBJECT PROPERTIES

            • hours : Integer

              An integer, specifying the time period in number of hours. Max: 72

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

          • Pushes/lifetime constraint : Object

            Limits the number of pushes any individual audience member will ever receive from the pipeline.

            OBJECT PROPERTIES

            • lifetimes : Integer

              An integer specifying a lifetime. Max: 1 Min: 1

            • pushes : Integer

              An integer, specifying the maximum number of pushes to any individual audience member per time period.

    • ok : Boolean

      Success.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Pipelines Constraints

PUT /api/pipelines/constraints/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "constraints" : [
        {
            "rate" : {
                "pushes" : 15,
                "days" : 3
            }
        },
        {
            "rate" : {
                "pushes" : 4,
                "hours" : 6
            }
        }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

PUT /api/pipelines/constraints

Update the pipelines constraints.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

Request Body

An array of no more than 5 cross-pipeline rate limit constraints.

• Content-Type: application/json

  Object

  OBJECT PROPERTIES

  • constraints : Array [Object]

    An array of rate objects determining the maximum number of messages each audience member can receive over a period of time. Max items: 5

    ARRAY ITEM

    • Rate Limit Constraint

      A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

      OBJECT PROPERTIES

      • rate : Any

        A rate limit constraint describes a limit on the number of pushes that can be sent to an individual device per a specified time period.

        One of

        • Pushes/days constraint : Object

          Limits the number of pushes any individual audience member will receive from the pipeline over a number of days.

          OBJECT PROPERTIES

          • days : Integer

            An integer, specifying the time period in number of days. Max: 90

          • pushes : Integer

            An integer, specifying the maximum number of pushes to any individual audience member per time period.

        • Pushes/hours constraint : Object

          Limits the number of pushes any individual audience member will receive from the pipeline over a number of hours.

          OBJECT PROPERTIES

          • hours : Integer

            An integer, specifying the time period in number of hours. Max: 72

          • pushes : Integer

            An integer, specifying the maximum number of pushes to any individual audience member per time period.

        • Pushes/lifetime constraint : Object

          Limits the number of pushes any individual audience member will ever receive from the pipeline.

          OBJECT PROPERTIES

          • lifetimes : Integer

            An integer specifying a lifetime. Max: 1 Min: 1

          • pushes : Integer

            An integer, specifying the maximum number of pushes to any individual audience member per time period.

  • ok : Boolean

    Success.

Responses

• 200

  Returned if the constraints have been successfully updated.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List Deleted Pipelines

GET /api/pipelines/deleted/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipelines": [
      {
          "deletion_time": "2020-03-31T20:54:45",
          "pipeline_id": "0sdicj23-fasc-4b2f-zxcv-0baf934f0d69"
      },
      {
          "..."
      }
    ]
}

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).list_deleted_automations()

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.start = 2020-11-23
automation.list_deleted_automations

GET /api/pipelines/deleted

Produces a list of all deleted pipelines starting with the most recently deleted entry.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

• start : String

  The date-time of the starting element for paginating results.

  Format: date-time

• limit : Integer

  The maximum number of elements to return.

Responses

• 200

  Returns an array of deleted pipeline objects.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • ok : Boolean

      Success.

    • pipelines : Array [Object]

      ARRAY ITEM
      • OBJECT PROPERTIES

        • deletion_time : String

          The date-time indicating when the pipeline was deleted. Format: date-time

        • pipeline_id : String

          The unique identifier for a pipeline. Format: uuid

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List Filtered Pipelines

GET /api/pipelines/filtered

Lists all pipelines, which fulfill the provided filter criteria. Returns a response container, which contains an array of pipeline objects in the pipelines attribute. The response container also provides total count and links to the next page next_page and previous page prev_page, if applicable. We also always apply a sort order. By default we apply an ascending sort order on the name name field, but we also support a sort order on the started date started_date field. Pagination is always applied, which means that the pipeline result list is not the complete list of pipelines if the total count is greater than the page limit.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

• start : Integer

  Non-negative zero-based index of the starting element for paginating results. Default value 0.

  Min: 1

• limit : Integer

  The maximum number of results to return. This is effectively the page size for the response.

  Min: 1

• enabled : Boolean

  If true, limits the listing to enabled pipelines. If false or omitted, lists all pipelines, whether enabled is true or false.

• started_date_mills : Integer

  Limits the listing to only pipelines that were started after the specified date in milliseconds.

  Format: int64

• prefix : String

  Search term, which is used as a prefix search term.

• triggers : String

  0 or more trigger types. The triggers filter limits the listing of pipelines by the specified trigger types. For example, if you specify REGION_EXITED and REGION_ENTERED, only pipelines that are associated with region entry and region exit triggers will be shown. If no trigger types are specified, no triggers filter will be applied and all pipelines will be listed.

  Possible values: TAG_ADDED, TAG_REMOVED, FIRST_REG, FIRST_OPT_IN, ACTIVITY, REGION_ENTERED, REGION_EXITED, CUSTOM_EVENT, SUBSCRIPTION_ADDED, SUBSCRIPTION_REMOVED

• sort : String

  Specifies the field, which should be sorted. Two fields are supported: name and started_date. If you omit the sort parameter, the default value name is used. If you provide an unknown field name, we will default to the name field.

  Possible values: name, started_date

• order : String

  Specifies the sort order asc or desc. If you omit the order parameter, the default value asc is used.

  Possible values: asc, desc

Responses

• 200

  Returned on success, with a JSON representation of pipelines matching your query parameters.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    The response body for a pipelines request.

    OBJECT PROPERTIES

    • next_page : String

      An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string identifying a single API call. Format: uuid

    • pipeline_ids : Array [String]

      An array of pipeline IDs.

    • pipeline_urls : Array [String]

      An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

    • pipelines : Array [Pipeline Object]

      A list of pipeline objects.

    • prev_page : String

      An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

    • total_count : Integer

      The total count of pipelines.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

List Pipelines Limits

GET /api/pipelines/limits/ HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "limits" : {
        "total_limit" : 50,
        "active_limit" : 20,
        "total_count" : 23,
        "active_count" : 7
    }
}

GET /api/pipelines/limits

Return the currently configured limits for number of total and active pipelines, as well as the total and active counts.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

Responses

• 200

  Returns a JSON dictionary in the limits attribute.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    OBJECT PROPERTIES

    • limits : Object

      OBJECT PROPERTIES

      • active_count : Integer

        An integer indicating the number of pipelines created by the application which are currently enabled.

      • active_limit : Integer

        An integer indicating the total number of active pipelines that the app is allowed to have.

      • total_count : Integer

        An integer indicating the total number of pipelines that currently exist for the application, regardless of their enabled state.

      • total_limit : Integer

        An integer indicating the total number of pipelines that the app is allowed to have, regardless of their enabled state.

    • ok : Boolean

      Success.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Validate Pipeline

POST /api/pipelines/validate HTTP/1.1
Authorization: Basic <master authorization string>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

{
    "name":"The Darkest Pipeline",
    "enabled":true,
    "immediate_trigger":"first_open",
    "outcome":{
      "push":{
          "audience":"triggered",
          "device_types":[
            "ios",
            "android"
          ],
          "notification":{
            "alert":"Cool goatee, Abed"
          }
      }
    },
    "timing":{
      "delay":{
          "seconds":7200
      },
      "schedule":{
          "type":"local",
          "miss_behavior":"wait",
          "dayparts":[
            {
                "days_of_week":[
                  "thursday"
                ],
                "allowed_times":[
                  {
                      "preferred":"21:30:00"
                  }
                ]
            }
          ]
      }
    }
}

HTTP/1.1 200 OK
Content-Length: 11
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true
}

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')

automation = ua.Automation(airship)
pipeline = ua.Pipeline(
    name='The Darkest Pipeline',
    enabled=True,
    immediate_trigger=['first_open'],
    outcome={
        'audience': 'triggered',
        'device_types': ua.device_types('ios', 'android', 'web'),
        'notification': ua.notification(alert='Cool goatee, Abed')
    },
    timing={
        delay': {'seconds': 7200},
        'schedule': {
            'type': 'local',
            'miss_behavior': 'wait',
            'dayparts': [{
                'days_of_week': ['thursday'],
                'allowed_times': [
                    {'preferred': '21:30:00'}
                ]
            }]
        }
    }
)
response = automation.validate(pipeline.payload)

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

pipeline = UA::Pipeline.new(client: airship)
pipeline.enabled = true
pipeline.immediate_trigger = "first_open"
pipeline.outcome = {
    "push": {
        "audience": "triggered",
        "device_types": ['ios','android','web'],
        "notification": {
            "alert": "Cool goatee, Abed"
        }
    }
}
automation = UA::Automation.new(client: airship)
automation.pipeline_object = pipeline.payload
automation.validate_automation

POST /api/pipelines/validate

This endpoint accepts the same range of payloads as a POST to /api/pipelines, but only parses and validates the payload, without creating the pipeline. The body of the request must be a single pipeline object or an array of pipeline objects.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

Request Body

A single pipeline object or an array of pipeline objects.

• Content-Type: application/json

  One of

  • Pipeline Object

    A pipeline object encapsulates the complete set of objects that define an Automation pipeline: Triggers, Outcomes, and metadata. At least one of immediate_trigger or historical_trigger must be supplied.

  • Array of Push Templates : Array [Pipeline Object]

Responses

• 200

  The payload was valid.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    Returned with 2xx Responses. At a minimum, successful calls return true for the ok key. If your call includes a verbose response (as with GET requests, etc.), the ok key will appear in the top-most object, outside the verbose response.

• 400

  There was a parsing or validation error in the request. Bad Request errors typically include path and location in the response, to help you find the cause of the error.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 406

  Return when the client requests a version of the API that cannot be satisfied, because no compatible version is currently deployed.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 413

  The request included a payload larger than the maximum size of 5MiB.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Individual Pipeline Lookup

GET /api/pipelines/4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4 HTTP/1.1
Authorization: Basic <authorization string>
Accept: application/vnd.urbanairship+json; version=3

HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
    "ok": true,
    "pipeline": {
      "creation_time": "2020-02-14T19:19:19",
      "enabled": true,
      "immediate_trigger": { "tag_added": "new_customer" },
      "last_modified_time": "2020-03-01T12:12:54",
      "name": "New customer",
      "outcome": {
          "push": {
            "audience": "triggered",
            "device_types": [ "ios", "android" ],
            "notification": { "alert": "Hello new customer!" }
          }
      },
      "status": "live",
      "uid": "86ad9239-373d-d0a5-d5d8-04fed18f79bc",
      "url": "https://go.urbanairship/api/pipelines/86ad9239-373d-d0a5-d5d8-04fed18f79bc"
    }
}

import urbanairship as ua
airship = ua.Airship('<app key>', '<master secret>')
response = ua.Automation(airship).lookup('4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4')

require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', secret: '<master secret>')

automation = UA::Automation.new(client: airship)
automation.pipeline_id = '4d3ff1fd-9ce6-5ea4-5dc9-5ccbd38597f4'
automation.lookup_automation

GET /api/pipelines/{pipeline_id}

Fetch a single pipeline resource. Returns an array containing a single pipeline object in the pipeline attribute.

Security:

• HTTP Basic Auth (Master)
• HTTP Bearer Token
• OAuth 2.0 : [pln]

• pipeline_id : StringREQUIRED

  The pipeline you want to return or modify.

Responses

• 200

  Returned on success, with the JSON representation of the pipeline in the body of the response.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json; version=3

    The response body for a pipelines request.

    OBJECT PROPERTIES

    • next_page : String

      An URI that points to the next page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a next page we omit the next page link.

    • ok : Boolean

      Success.

    • operation_id : String

      A unique string identifying a single API call. Format: uuid

    • pipeline_ids : Array [String]

      An array of pipeline IDs.

    • pipeline_urls : Array [String]

      An array of of pipeline URIs. If more than one entity was included in the request, the URIs will be in the same order as the objects in the request.

    • pipelines : Array [Pipeline Object]

      A list of pipeline objects.

    • prev_page : String

      An URI that points to the previous page of pipelines. The page size is specified by the limit parameter and the start point by the start parameter. If there are no more pipelines for a previous page we omit the previous page link.

    • total_count : Integer

      The total count of pipelines.

• 401

  Authentication information (the app key and secret or bearer token) was either incorrect or missing.

  RESPONSE BODY

  • Content-Type: text/plain

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 403

  Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

  RESPONSE BODY

  • Content-Type: application/json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

• 404

  The requested resource doesn’t exist.

  RESPONSE BODY

  • Content-Type: application/vnd.urbanairship+json

    Errors returned with 4xx responses. Errors include as much information as possible to help you understand the reason for the failure.

Update Pipeline