Ably Push API

openapi: 3.2.0
info:
  title: Platform Push API
  description: The REST API specification for Ably.
  version: 1.1.1
  contact:
    name: Ably Support
    url: https://www.ably.io/contact
    email: support@ably.io
servers:
- url: https://rest.ably.io
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Push
paths:
  /push/deviceRegistrations:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    get:
      summary: List devices registered for receiving push notifications
      operationId: getRegisteredPushDevices
      description: List of device details of devices registed for push notifications.
      tags:
      - Push
      parameters:
      - name: deviceId
        description: Optional filter to restrict to devices associated with that deviceId.
        in: query
        schema:
          type: string
      - name: clientId
        in: query
        description: Optional filter to restrict to devices associated with that clientId.
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of records to return.
        schema:
          type: integer
          default: 100
          maximum: 1000
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    post:
      summary: Register a device for receiving push notifications
      operationId: registerPushDevice
      description: Register a device’s details, including the information necessary to deliver push notifications to it. Requires "push-admin" capability.
      tags:
      - Push
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    delete:
      summary: Unregister matching devices for push notifications
      operationId: unregisterAllPushDevices
      description: Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.
      tags:
      - Push
      parameters:
      - name: deviceId
        description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
        in: query
        schema:
          type: string
      - name: clientId
        in: query
        description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
        schema:
          type: string
      responses:
        2XX:
          description: OK
        default:
          $ref: '#/components/responses/Error'
  /push/deviceRegistrations/{device_id}:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    get:
      operationId: getPushDeviceDetails
      summary: Get a device registration
      description: Get the full details of a device.
      tags:
      - Push
      parameters:
      - $ref: '#/components/parameters/deviceId'
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    put:
      summary: Update a device registration
      operationId: putPushDeviceDetails
      description: Device registrations can be upserted (the existing registration is replaced entirely) with a PUT operation. Only clientId, metadata and push.recipient are mutable.
      tags:
      - Push
      parameters:
      - $ref: '#/components/parameters/deviceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    patch:
      summary: Update a device registration
      operationId: patchPushDeviceDetails
      description: Specific attributes of an existing registration can be updated. Only clientId, metadata and push.recipient are mutable.
      tags:
      - Push
      parameters:
      - $ref: '#/components/parameters/deviceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-msgpack:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeviceDetails'
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    delete:
      summary: Unregister a single device for push notifications
      operationId: unregisterPushDevice
      description: Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.
      tags:
      - Push
      parameters:
      - $ref: '#/components/parameters/deviceId'
      responses:
        2XX:
          description: OK
        default:
          $ref: '#/components/responses/Error'
  /push/deviceRegistrations/{device_id}/resetUpdateToken:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    get:
      summary: Reset a registered device's update token
      operationId: updatePushDeviceDetails
      description: Gets an updated device details object.
      tags:
      - Push
      parameters:
      - $ref: '#/components/parameters/deviceId'
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
            text/html:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
  /push/channelSubscriptions:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    get:
      summary: List channel subscriptions
      operationId: getPushSubscriptionsOnChannels
      description: Get a list of push notification subscriptions to channels.
      tags:
      - Push
      parameters:
      - name: channel
        in: query
        description: Filter to restrict to subscriptions associated with that channel.
        schema:
          type: string
      - name: deviceId
        description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
        in: query
        schema:
          type: string
      - name: clientId
        in: query
        description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of records to return.
        schema:
          type: integer
          default: 100
          maximum: 1000
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDetails'
        default:
          $ref: '#/components/responses/Error'
    post:
      summary: Subscribe a device to a channel
      operationId: subscribePushDeviceToChannel
      description: Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.
      tags:
      - Push
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  deviceId:
                    type: string
                    description: Must be set when clientId is empty, cannot be used with clientId.
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  clientId:
                    type: string
                    description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
          application/x-msgpack:
            schema:
              oneOf:
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  deviceId:
                    type: string
                    description: Must be set when clientId is empty, cannot be used with clientId.
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  clientId:
                    type: string
                    description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
          application/x-www-form-urlencoded:
            schema:
              oneOf:
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  deviceId:
                    type: string
                    description: Must be set when clientId is empty, cannot be used with clientId.
              - type: object
                properties:
                  channel:
                    type: string
                    description: Channel name.
                  clientId:
                    type: string
                    description: Must be set when deviceId is empty, cannot be used with deviceId.
            example:
              channel: my:channel
              clientId: myClientId
      responses:
        2XX:
          description: OK
        default:
          $ref: '#/components/responses/Error'
    delete:
      summary: Delete a registered device's update token
      operationId: deletePushDeviceDetails
      description: Delete a device details object.
      tags:
      - Push
      parameters:
      - name: channel
        in: query
        description: Filter to restrict to subscriptions associated with that channel.
        schema:
          type: string
      - name: deviceId
        description: Must be set when clientId is empty, cannot be used with clientId.
        in: query
        schema:
          type: string
      - name: clientId
        in: query
        description: Must be set when deviceId is empty, cannot be used with deviceId.
        schema:
          type: string
      responses:
        2XX:
          description: OK
        default:
          $ref: '#/components/responses/Error'
  /push/channels:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    get:
      summary: List all channels with at least one subscribed device
      operationId: getChannelsWithPushSubscribers
      description: Returns a paginated response of channel names.
      tags:
      - Push
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
            application/x-msgpack:
              schema:
                type: array
                items:
                  type: string
            text/html:
              schema:
                type: array
                items:
                  type: string
        default:
          $ref: '#/components/responses/Error'
  /push/publish:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    post:
      summary: Publish a push notification to device(s)
      operationId: publishPushNotificationToDevices
      description: A convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.
      tags:
      - Push
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
              - recipient
          application/x-msgpack:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
              - recipient
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                recipient:
                  $ref: '#/components/schemas/Recipient'
                push:
                  $ref: '#/components/schemas/Push'
              required:
              - recipient
      responses:
        2XX:
          description: OK
        default:
          $ref: '#/components/responses/Error'
components:
  parameters:
    versionHeader:
      in: header
      name: X-Ably-Version
      schema:
        type: string
      description: The version of the API you wish to use.
    responseFormat:
      in: query
      name: format
      schema:
        type: string
        enum:
        - json
        - jsonp
        - msgpack
        - html
      description: The response format you would like
    deviceId:
      name: device_id
      in: path
      schema:
        type: string
      required: true
      description: Device's ID.
  schemas:
    Recipient:
      type: object
      description: Push recipient details for a device.
      properties:
        transportType:
          type: string
          description: Defines which push platform is being used.
          enum:
          - apns
          - fcm
          - gcm
          - web
        deviceToken:
          type: string
          description: when using APNs, specifies the required device token.
        registrationToken:
          type: string
          description: when using GCM or FCM, specifies the required registration token.
          properties:
            auth:
              type: string
              description: An Elliptic curve Diffie-Hellman public key on the P-256 curve. Obtained from a PushDescription using the `getKey` method.
            p256dh:
              type: string
              description: An authentication secret, as described by [Message Encryption for Web Push](https://datatracker.ietf.org/doc/html/draft-ietf-webpush-encryption-08).
        encryptionKey:
          type: object
          description: when using web push, specifies the required encryptionKey.
        clientId:
          type: string
          description: Client ID of recipient
          writeOnly: true
        deviceId:
          type: string
          description: Client ID of recipient
          writeOnly: true
    Push:
      type: object
      properties:
        data:
          description: Arbitrary [key-value string-to-string payload](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example).
          type: string
        notification:
          $ref: '#/components/schemas/Notification'
        apns:
          description: Extends and overrides generic values when delivering via APNs. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'
        fcm:
          description: Extends and overrides generic values when delivering via GCM/FCM. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'
        web:
          description: Extends and overrides generic values when delivering via web. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          type: object
          properties:
            notification:
              $ref: '#/components/schemas/Notification'
    DeviceDetails:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the device generated by the device itself.
        clientId:
          type: string
          description: Optional trusted client identifier for the device.
        formFactor:
          type: string
          description: Form factor of the push device.
          enum:
          - phone
          - tablet
          - desktop
          - tv
          - watch
          - car
          - embedded
        metadata:
          type: object
          description: Optional metadata object for this device. The metadata for a device may only be set by clients with push-admin privileges and will be used more extensively in the future with smart notifications.
        platform:
          type: string
          description: Platform of the push device.
          enum:
          - ios
          - android
          - browser
        deviceSecret:
          type: string
          description: Secret value for the device.
        push.recipient:
          $ref: '#/components/schemas/Recipient'
        push.state:
          type: string
          description: the current state of the push device.
          enum:
          - Active
          - Failing
          - Failed
          readOnly: true
    Error:
      type: object
      description: Returned error from failed REST.
      properties:
        message:
          type: string
          description: Message explaining the error's cause.
        code:
          type: integer
          description: Error code.
        statusCode:
          type: integer
          description: Status error code.
        href:
          type: string
          description: Link to help with error.
        serverId:
          type: string
          description: Server ID with which error was encountered.
    Notification:
      type: object
      properties:
        title:
          description: Title to display at the notification.
          type: string
        body:
          description: Text below title on the expanded notification.
          type: string
        icon:
          description: Platform-specific icon for the notification.
          type: string
        sound:
          description: Platform-specific sound for the notification.
          type: string
        collapseKey:
          description: Platform-specific, used to group notifications together.
          type: string
  headers:
    ErrorMessage:
      description: The error message.
      schema:
        type: string
    ErrorCode:
      description: The error code.
      schema:
        type: integer
    ServerId:
      description: The ID for the server communicated with.
      schema:
        type: string
      required: true
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/x-msgpack:
          schema:
            $ref: '#/components/schemas/Error'
        text/html:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        x-ably-errorcode:
          $ref: '#/components/headers/ErrorCode'
        x-ably-errormessage:
          $ref: '#/components/headers/ErrorMessage'
        x-ably-serverid:
          $ref: '#/components/headers/ServerId'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic Authentication using an [API key](https://www.ably.io/documentation/core-features/authentication#basic-authentication).
    bearerAuth:
      type: http
      scheme: bearer
      description: Token Authentication using an [Ably Token](https://www.ably.io/documentation/core-features/authentication#basic-authentication), or optionally an [Ably JWT](https://www.ably.io/documentation/core-features/authentication#ably-jwt-process).