openapi: 3.0.1
servers:
  - url: https://rest.ably.io
info:
  contact:
    email: support@ably.io
    name: Ably Support
    url: https://www.ably.io/contact
    x-twitter: ablyrealtime
  description: The [REST API specification](https://www.ably.io/documentation/rest-api) for Ably.
  title: Platform API
  version: 1.1.0
  x-apisguru-categories:
    - cloud
  x-logo:
    url: https://twitter.com/ablyrealtime/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/ably/open-specs/main/definitions/platform-v1.yaml
      version: "3.0"
  x-providerName: ably.io
  x-serviceName: platform
security:
  - basicAuth: []
  - bearerAuth: []
paths:
  /channels:
    get:
      description: Enumerate all active channels of the application
      operationId: getMetadataOfAllChannels
      parameters:
        - in: query
          name: limit
          schema:
            default: 100
            type: integer
        - description: Optionally limits the query to only those channels whose name starts with the given prefix
          in: query
          name: prefix
          schema:
            type: string
        - description: optionally specifies whether to return just channel names (by=id) or ChannelDetails (by=value)
          in: query
          name: by
          schema:
            enum:
              - value
              - id
            type: string
      responses:
        2XX:
          content:
            application/json:
              schema:
                oneOf:
                  - items:
                      $ref: "#/components/schemas/ChannelDetails"
                    type: array
                  - items:
                      type: string
                    type: array
            application/x-msgpack:
              schema:
                oneOf:
                  - items:
                      $ref: "#/components/schemas/ChannelDetails"
                    type: array
                  - items:
                      type: string
                    type: array
            text/html:
              schema:
                type: string
          description: OK
          headers:
            link:
              $ref: "#/components/headers/Link"
        default:
          $ref: "#/components/responses/Error"
      summary: Enumerate all active channels of the application
      tags:
        - Status
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  "/channels/{channel_id}":
    get:
      description: Get metadata of a channel
      operationId: getMetadataOfChannel
      parameters:
        - $ref: "#/components/parameters/channelId"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelDetails"
          description: OK
          headers:
            x-ably-serverid:
              $ref: "#/components/headers/ServerId"
        default:
          $ref: "#/components/responses/Error"
      summary: Get metadata of a channel
      tags:
        - Status
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  "/channels/{channel_id}/messages":
    get:
      description: Get message history for a channel
      operationId: getMessagesByChannel
      parameters:
        - $ref: "#/components/parameters/channelId"
        - $ref: "#/components/parameters/filterStart"
        - $ref: "#/components/parameters/filterLimit"
        - $ref: "#/components/parameters/filterEnd"
        - $ref: "#/components/parameters/filterDirection"
      responses:
        2XX:
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Message"
                type: array
            application/x-msgpack:
              schema:
                items:
                  $ref: "#/components/schemas/Message"
                type: array
            text/html:
              schema:
                type: string
          description: OK
          headers:
            link:
              $ref: "#/components/headers/Link"
            x-ably-serverid:
              $ref: "#/components/headers/ServerId"
        default:
          description: Error
          headers:
            x-ably-errorcode:
              $ref: "#/components/headers/ErrorCode"
            x-ably-errormessage:
              $ref: "#/components/headers/ErrorMessage"
            x-ably-serverid:
              $ref: "#/components/headers/ServerId"
      summary: Get message history for a channel
      tags:
        - History
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    post:
      description: Publish a message to the specified channel
      operationId: publishMessagesToChannel
      parameters:
        - $ref: "#/components/parameters/channelId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Message"
          application/x-msgpack:
            schema:
              $ref: "#/components/schemas/Message"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/Message"
      responses:
        2XX:
          content:
            application/json:
              schema:
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
                type: object
            application/x-msgpack:
              schema:
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
                type: object
            text/html:
              schema:
                properties:
                  channel:
                    type: string
                  messageId:
                    type: string
                type: object
          description: OK
          headers:
            x-ably-serverid:
              $ref: "#/components/headers/ServerId"
        default:
          $ref: "#/components/responses/Error"
      summary: Publish a message to a channel
      tags:
        - Publishing
  "/channels/{channel_id}/presence":
    get:
      description: Get presence on a channel
      operationId: getPresenceOfChannel
      parameters:
        - $ref: "#/components/parameters/channelId"
        - in: query
          name: clientId
          schema:
            type: string
        - in: query
          name: connectionId
          schema:
            type: string
        - in: query
          name: limit
          schema:
            default: 100
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/PresenceMessage"
                type: array
            application/x-msgpack:
              schema:
                items:
                  $ref: "#/components/schemas/PresenceMessage"
                type: array
            text/html:
              schema:
                type: string
          description: OK
          headers:
            link:
              $ref: "#/components/headers/Link"
            x-ably-serverid:
              $ref: "#/components/headers/ServerId"
        default:
          $ref: "#/components/responses/Error"
      summary: Get presence of a channel
      tags:
        - Status
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  "/channels/{channel_id}/presence/history":
    get:
      description: Get presence on a channel
      operationId: getPresenceHistoryOfChannel
      parameters:
        - $ref: "#/components/parameters/channelId"
        - $ref: "#/components/parameters/filterStart"
        - $ref: "#/components/parameters/filterLimit"
        - $ref: "#/components/parameters/filterEnd"
        - $ref: "#/components/parameters/filterDirection"
      responses:
        2XX:
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/PresenceMessage"
                type: array
            application/x-msgpack:
              schema:
                items:
                  $ref: "#/components/schemas/PresenceMessage"
                type: array
            text/html:
              schema:
                type: string
          description: OK
          headers:
            link:
              $ref: "#/components/headers/Link"
        default:
          $ref: "#/components/responses/Error"
      summary: Get presence history of a channel
      tags:
        - History
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  "/keys/{keyName}/requestToken":
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    post:
      description: This is the means by which clients obtain access tokens to use the service. You can see how to construct an Ably TokenRequest in the [Ably TokenRequest spec](https://www.ably.io/documentation/rest-api/token-request-spec) documentation, although we recommend you use an Ably SDK rather to create a TokenRequest, as the construction of a TokenRequest is complex. The resulting token response object contains the token properties as defined in Ably TokenRequest spec. Authentication is not required if using a Signed TokenRequest.
      operationId: requestAccessToken
      parameters:
        - $ref: "#/components/parameters/key_name"
      requestBody:
        content:
          application/json:
            example:
              capability:
                channel1:
                  - publish
                  - subscribe
                wildcard:channels:*:
                  - publish
              keyName: YourKey.Name
              timestamp: "1559124196551"
            schema:
              oneOf:
                - $ref: "#/components/schemas/TokenRequest"
                - $ref: "#/components/schemas/SignedTokenRequest"
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/TokenDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Request an access token
      tags:
        - Authentication
  /push/channelSubscriptions:
    delete:
      description: Delete a device details object.
      operationId: deletePushDeviceDetails
      parameters:
        - description: Filter to restrict to subscriptions associated with that channel.
          in: query
          name: channel
          schema:
            type: string
        - description: Must be set when clientId is empty, cannot be used with clientId.
          in: query
          name: deviceId
          schema:
            type: string
        - description: Must be set when deviceId is empty, cannot be used with deviceId.
          in: query
          name: clientId
          schema:
            type: string
      responses:
        2XX:
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Delete a registered device's update token
      tags:
        - Push
    get:
      description: Get a list of push notification subscriptions to channels.
      operationId: getPushSubscriptionsOnChannels
      parameters:
        - description: Filter to restrict to subscriptions associated with that channel.
          in: query
          name: channel
          schema:
            type: string
        - description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
          in: query
          name: deviceId
          schema:
            type: string
        - description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
          in: query
          name: clientId
          schema:
            type: string
        - description: The maximum number of records to return.
          in: query
          name: limit
          schema:
            default: 100
            maximum: 1000
            type: integer
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: List channel subscriptions
      tags:
        - Push
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    post:
      description: Subscribe either a single device or all devices associated with a client ID to receive push notifications from messages sent to a channel.
      operationId: subscribePushDeviceToChannel
      requestBody:
        content:
          application/json:
            example:
              channel: my:channel
              clientId: myClientId
            schema:
              oneOf:
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    deviceId:
                      description: Must be set when clientId is empty, cannot be used with clientId.
                      type: string
                  type: object
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    clientId:
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
                      type: string
                  type: object
          application/x-msgpack:
            example:
              channel: my:channel
              clientId: myClientId
            schema:
              oneOf:
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    deviceId:
                      description: Must be set when clientId is empty, cannot be used with clientId.
                      type: string
                  type: object
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    clientId:
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
                      type: string
                  type: object
          application/x-www-form-urlencoded:
            example:
              channel: my:channel
              clientId: myClientId
            schema:
              oneOf:
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    deviceId:
                      description: Must be set when clientId is empty, cannot be used with clientId.
                      type: string
                  type: object
                - properties:
                    channel:
                      description: Channel name.
                      type: string
                    clientId:
                      description: Must be set when deviceId is empty, cannot be used with deviceId.
                      type: string
                  type: object
      responses:
        2XX:
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Subscribe a device to a channel
      tags:
        - Push
  /push/channels:
    get:
      description: Returns a paginated response of channel names.
      operationId: getChannelsWithPushSubscribers
      responses:
        2XX:
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
            application/x-msgpack:
              schema:
                items:
                  type: string
                type: array
            text/html:
              schema:
                items:
                  type: string
                type: array
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: List all channels with at least one subscribed device
      tags:
        - Push
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  /push/deviceRegistrations:
    delete:
      description: Unregisters devices. All their subscriptions for receiving push notifications through channels will also be deleted.
      operationId: unregisterAllPushDevices
      parameters:
        - description: Optional filter to restrict to devices associated with that deviceId. Cannot be used with clientId.
          in: query
          name: deviceId
          schema:
            type: string
        - description: Optional filter to restrict to devices associated with that clientId. Cannot be used with deviceId.
          in: query
          name: clientId
          schema:
            type: string
      responses:
        2XX:
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Unregister matching devices for push notifications
      tags:
        - Push
    get:
      description: List of device details of devices registed for push notifications.
      operationId: getRegisteredPushDevices
      parameters:
        - description: Optional filter to restrict to devices associated with that deviceId.
          in: query
          name: deviceId
          schema:
            type: string
        - description: Optional filter to restrict to devices associated with that clientId.
          in: query
          name: clientId
          schema:
            type: string
        - description: The maximum number of records to return.
          in: query
          name: limit
          schema:
            default: 100
            maximum: 1000
            type: integer
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: List devices registered for receiving push notifications
      tags:
        - Push
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    post:
      description: Register a device’s details, including the information necessary to deliver push notifications to it. Requires "push-admin" capability.
      operationId: registerPushDevice
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeviceDetails"
          application/x-msgpack:
            schema:
              $ref: "#/components/schemas/DeviceDetails"
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Register a device for receiving push notifications
      tags:
        - Push
  "/push/deviceRegistrations/{device_id}":
    delete:
      description: Unregisters a single device by its device ID. All its subscriptions for receiving push notifications through channels will also be deleted.
      operationId: unregisterPushDevice
      parameters:
        - $ref: "#/components/parameters/deviceId"
      responses:
        2XX:
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Unregister a single device for push notifications
      tags:
        - Push
    get:
      description: Get the full details of a device.
      operationId: getPushDeviceDetails
      parameters:
        - $ref: "#/components/parameters/deviceId"
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Get a device registration
      tags:
        - Push
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    patch:
      description: Specific attributes of an existing registration can be updated. Only clientId, metadata and push.recipient are mutable.
      operationId: patchPushDeviceDetails
      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:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Update a device registration
      tags:
        - Push
    put:
      description: Device registrations can be upserted (the existing registration is replaced entirely) with a PUT operation. Only clientId, metadata and push.recipient are mutable.
      operationId: putPushDeviceDetails
      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:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Update a device registration
      tags:
        - Push
  "/push/deviceRegistrations/{device_id}/resetUpdateToken":
    get:
      description: Gets an updated device details object.
      operationId: updatePushDeviceDetails
      parameters:
        - $ref: "#/components/parameters/deviceId"
      responses:
        2XX:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            application/x-msgpack:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
            text/html:
              schema:
                $ref: "#/components/schemas/DeviceDetails"
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Reset a registered device's update token
      tags:
        - Push
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  /push/publish:
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
    post:
      description: A convenience endpoint to deliver a push notification payload to a single device or set of devices identified by their client identifier.
      operationId: publishPushNotificationToDevices
      requestBody:
        content:
          application/json:
            schema:
              properties:
                push:
                  $ref: "#/components/schemas/Push"
                recipient:
                  $ref: "#/components/schemas/Recipient"
              required:
                - recipient
              type: object
          application/x-msgpack:
            schema:
              properties:
                push:
                  $ref: "#/components/schemas/Push"
                recipient:
                  $ref: "#/components/schemas/Recipient"
              required:
                - recipient
              type: object
          application/x-www-form-urlencoded:
            schema:
              properties:
                push:
                  $ref: "#/components/schemas/Push"
                recipient:
                  $ref: "#/components/schemas/Recipient"
              required:
                - recipient
              type: object
      responses:
        2XX:
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Publish a push notification to device(s)
      tags:
        - Push
  /stats:
    get:
      description: The Ably system can be queried to obtain usage statistics for a given application, and results are provided aggregated across all channels in use in the application in the specified period. Stats may be used to track usage against account quotas.
      operationId: getStats
      parameters:
        - $ref: "#/components/parameters/filterStart"
        - $ref: "#/components/parameters/filterLimit"
        - $ref: "#/components/parameters/filterEnd"
        - $ref: "#/components/parameters/filterDirection"
        - description: Specifies the unit of aggregation in the returned results.
          in: query
          name: unit
          schema:
            default: minute
            enum:
              - minute
              - hour
              - day
              - month
            type: string
      responses:
        2XX:
          content:
            application/json:
              schema:
                type: object
          description: OK
        default:
          $ref: "#/components/responses/Error"
      summary: Retrieve usage statistics for an application
      tags:
        - Stats
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
  /time:
    get:
      description: This returns the service time in milliseconds since the epoch.
      operationId: getTime
      responses:
        2XX:
          content:
            application/json:
              schema:
                items:
                  type: integer
                type: array
            application/x-msgpack:
              schema:
                items:
                  type: integer
                type: array
            text/html:
              schema:
                type: string
          description: OK
        default:
          $ref: "#/components/responses/Error"
      security: []
      summary: Get the service time
      tags:
        - Stats
    parameters:
      - $ref: "#/components/parameters/versionHeader"
      - $ref: "#/components/parameters/responseFormat"
components:
  headers:
    ErrorCode:
      description: The error code.
      schema:
        type: integer
    ErrorMessage:
      description: The error message.
      schema:
        type: string
    Link:
      description: Links to related resources, in the format defined by [RFC 5988](https://tools.ietf.org/html/rfc5988#section-5). This will potentially include a link with relation type `next`, `first`, and `current`, where appropiate.
      required: true
      schema:
        pattern: (<(.*)?>; rel=\"(first|current|last)?\",)*(<(.*)?>; rel=\"(first|current|last)?\")+
        type: string
    ServerId:
      description: The ID for the server communicated with.
      required: true
      schema:
        type: string
  parameters:
    channelId:
      description: The [Channel's ID](https://www.ably.io/documentation/rest/channels).
      in: path
      name: channel_id
      required: true
      schema:
        type: string
    deviceId:
      description: Device's ID.
      in: path
      name: device_id
      required: true
      schema:
        type: string
    filterDirection:
      in: query
      name: direction
      schema:
        default: backwards
        enum:
          - forwards
          - backwards
        type: string
    filterEnd:
      in: query
      name: end
      schema:
        default: now
        type: string
    filterLimit:
      in: query
      name: limit
      schema:
        default: "100"
        type: integer
    filterStart:
      in: query
      name: start
      schema:
        type: string
    key_name:
      description: The [key name](https://www.ably.io/documentation/rest-api/token-request-spec#api-key-format) comprises of the app ID and key ID of an API key.
      in: path
      name: keyName
      required: true
      schema:
        type: string
    responseFormat:
      description: The response format you would like
      in: query
      name: format
      schema:
        enum:
          - json
          - jsonp
          - msgpack
          - html
        type: string
    versionHeader:
      description: The version of the API you wish to use.
      in: header
      name: X-Ably-Version
      schema:
        type: string
  responses:
    Error:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
        application/x-msgpack:
          schema:
            $ref: "#/components/schemas/Error"
        text/html:
          schema:
            $ref: "#/components/schemas/Error"
      description: Error
      headers:
        x-ably-errorcode:
          $ref: "#/components/headers/ErrorCode"
        x-ably-errormessage:
          $ref: "#/components/headers/ErrorMessage"
        x-ably-serverid:
          $ref: "#/components/headers/ServerId"
  schemas:
    ChannelDetails:
      properties:
        channelId:
          description: The required name of the channel including any qualifier, if any.
          type: string
        isGlobalMaster:
          description: In events relating to the activity of a channel in a specific region, this optionally identifies whether or not that region is responsible for global coordination of the channel.
          type: boolean
        region:
          description: In events relating to the activity of a channel in a specific region, this optionally identifies the region.
          type: string
        status:
          $ref: "#/components/schemas/ChannelStatus"
      required:
        - channelId
      type: object
    ChannelStatus:
      description: A ChannelStatus instance.
      properties:
        isActive:
          description: A required boolean value indicating whether the channel that is the subject of the event is active. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
          type: boolean
        occupancy:
          $ref: "#/components/schemas/Occupancy"
      required:
        - isActive
      type: object
    DeviceDetails:
      properties:
        clientId:
          description: Optional trusted client identifier for the device.
          type: string
        deviceSecret:
          description: Secret value for the device.
          type: string
        formFactor:
          description: Form factor of the push device.
          enum:
            - phone
            - tablet
            - desktop
            - tv
            - watch
            - car
            - embedded
          type: string
        id:
          description: Unique identifier for the device generated by the device itself.
          type: string
        metadata:
          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.
          type: object
        platform:
          description: Platform of the push device.
          enum:
            - ios
            - android
          type: string
        push.recipient:
          $ref: "#/components/schemas/Recipient"
        push.state:
          description: the current state of the push device.
          enum:
            - Active
            - Failing
            - Failed
          readOnly: true
          type: string
      type: object
    Error:
      description: Returned error from failed REST.
      properties:
        code:
          description: Error code.
          type: integer
        href:
          description: Link to help with error.
          type: string
        message:
          description: Message explaining the error's cause.
          type: string
        serverId:
          description: Server ID with which error was encountered.
          type: string
        statusCode:
          description: Status error code.
          type: integer
      type: object
    Extras:
      description: Extras object. Currently only allows for [push](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example) extra.
      properties:
        push:
          $ref: "#/components/schemas/Push"
      type: object
    Message:
      description: Message object.
      properties:
        clientId:
          description: The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) of the publisher of this message.
          type: string
        connectionId:
          description: The connection ID of the publisher of this message.
          type: string
        data:
          description: The string encoded payload, with the encoding specified below.
          type: string
        encoding:
          description: This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
          type: string
        extras:
          $ref: "#/components/schemas/Extras"
        id:
          description: A Unique ID that can be specified by the publisher for [idempotent publishing](https://www.ably.io/documentation/rest/messages#idempotent).
          readOnly: true
          type: string
        name:
          description: The event name, if provided.
          type: string
        timestamp:
          description: Timestamp when the message was received by the Ably, as milliseconds since the epoch.
          format: int64
          readOnly: true
          type: integer
      type: object
    Notification:
      properties:
        body:
          description: Text below title on the expanded notification.
          type: string
        collapseKey:
          description: Platform-specific, used to group notifications together.
          type: string
        icon:
          description: Platform-specific icon for the notification.
          type: string
        sound:
          description: Platform-specific sound for the notification.
          type: string
        title:
          description: Title to display at the notification.
          type: string
      type: object
    Occupancy:
      description: An Occupancy instance indicating the occupancy of a channel. For events indicating regional activity of a channel this indicates activity in that region, not global activity.
      properties:
        presenceConnections:
          description: The number of connections that are authorised to enter members into the presence channel.
          type: integer
        presenceMembers:
          description: The number of members currently entered into the presence channel.
          type: integer
        presenceSubscribers:
          description: The number of connections that are authorised to subscribe to presence messages.
          type: integer
        publishers:
          description: The number of connections attached to the channel that are authorised to publish.
          type: integer
        subscribers:
          description: The number of connections attached that are authorised to subscribe to messages.
          type: integer
      type: object
    PresenceMessage:
      properties:
        action:
          description: The event signified by a PresenceMessage.
          enum:
            - ABSENT
            - PRESENT
            - ENTER
            - LEAVE
            - UPDATE
          readOnly: true
          type: string
        clientId:
          description: The client ID of the publisher of this presence update.
          type: string
        connectionId:
          description: The connection ID of the publisher of this presence update.
          type: string
        data:
          description: The presence update payload, if provided.
          type: string
        encoding:
          description: This will typically be empty as all presence updates received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
          type: string
        extras:
          $ref: "#/components/schemas/Extras"
        id:
          description: Unique ID assigned by Ably to this presence update.
          readOnly: true
          type: string
        timestamp:
          description: Timestamp when the presence update was received by Ably, as milliseconds since the epoch.
          format: int64
          readOnly: true
          type: integer
      type: object
    Push:
      properties:
        apns:
          description: Extends and overrides generic values when delivering via APNs. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          properties:
            notification:
              $ref: "#/components/schemas/Notification"
          type: object
        data:
          description: Arbitrary [key-value string-to-string payload](https://www.ably.io/documentation/general/push/publish#channel-broadcast-example).
          type: string
        fcm:
          description: Extends and overrides generic values when delivering via GCM/FCM. [See examples](https://www.ably.io/documentation/general/push/publish#payload-structure)
          properties:
            notification:
              $ref: "#/components/schemas/Notification"
          type: object
        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)
          properties:
            notification:
              $ref: "#/components/schemas/Notification"
          type: object
      type: object
    Recipient:
      description: Push recipient details for a device.
      properties:
        clientId:
          description: Client ID of recipient
          type: string
          writeOnly: true
        deviceId:
          description: Client ID of recipient
          type: string
          writeOnly: true
        deviceToken:
          description: when using APNs, specifies the required device token.
          type: string
        registrationToken:
          description: when using GCM or FCM, specifies the required registration token.
          type: string
        transportType:
          description: Defines which push platform is being used.
          enum:
            - apns
            - fcm
            - gcm
          type: string
      type: object
    SignedTokenRequest:
      allOf:
        - $ref: "#/components/schemas/TokenRequest"
        - properties:
            mac:
              description: A signature, generated as an HMAC of each of the above components, using the key secret value.
              type: string
          required:
            - mac
          type: object
    TokenDetails:
      properties:
        capability:
          description: Regular expression representation of the capabilities of the token.
          type: string
        expires:
          description: Timestamp of token expiration.
          type: integer
        issued:
          description: Timestamp of token creation.
          type: integer
        keyName:
          description: Name of the key used to create the token
          type: string
        token:
          description: The Ably Token.
          type: string
      type: object
    TokenRequest:
      properties:
        capability:
          description: The [capabilities](https://www.ably.io/documentation/core-features/authentication#capabilities-explained) (i.e. a set of channel names/namespaces and, for each, a set of operations) which should be a subset of the set of capabilities associated with the key specified in keyName.
          example:
            channel1:
              - publish
              - subscribe
          type: object
        clientId:
          description: The [client ID](https://www.ably.io/documentation/core-features/authentication#identified-clients) to be assosciated with the token. Can be set to * to allow for any client ID to be used.
          type: string
        keyName:
          description: Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.
          example: xVLyHw.LMJZxw
          type: string
        nonce:
          description: An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.
          type: string
        timestamp:
          description: Time of creation of the Ably TokenRequest.
          type: integer
      required:
        - keyName
        - capability
        - timestamp
        - nonce
      type: object
  securitySchemes:
    basicAuth:
      description: Basic Authentication using an [API key](https://www.ably.io/documentation/core-features/authentication#basic-authentication).
      scheme: basic
      type: http
    bearerAuth:
      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).
      scheme: bearer
      type: http
