openapi: 3.0.1
info:
title: Control API v1 apps Push API
version: 1.0.32
description: 'Use the Control API to manage your applications, namespaces, keys, queues, rules, and more.
Detailed information on using this API can be found in the Ably <a href="https://ably.com/docs/account/control-api">Control API docs</a>.
Control API is currently in Preview.
'
servers:
- url: https://control.ably.net/v1
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:
schemas:
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
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'
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
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
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.
headers:
ErrorCode:
description: The error code.
schema:
type: integer
ServerId:
description: The ID for the server communicated with.
schema:
type: string
required: true
ErrorMessage:
description: The error message.
schema:
type: string
parameters:
responseFormat:
in: query
name: format
schema:
type: string
enum:
- json
- jsonp
- msgpack
- html
description: The response format you would like
versionHeader:
in: header
name: X-Ably-Version
schema:
type: string
description: The version of the API you wish to use.
deviceId:
name: device_id
in: path
schema:
type: string
required: true
description: Device's ID.
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:
bearer_auth:
type: http
scheme: bearer
description: Control API uses bearer authentication. You need to generate an access token for use with this API. More details can be found in the <a href="https://ably.com/docs/account/control-api/#authentication">Ably docs</a>.