Rest API

The API hosted at http://CLUSTER.broadcastt.xyz, where CLUSTER represents your own apps cluster. The API can be accessed via HTTP or HTTPS. However, we recommend to use HTTPS.

All request described here must be authenticated. Read about it here.

For POST methods authentication parameters must be query parameters. Request data must be in POST body as a JSON hash.

To indicate the status of the request the following HTTP status codes are in use:

Code Description
200 Success
400 Bad request. Error details in response body.
401 Unauthorized. Error details in response body.
403 Forbidden. Error details in response body.
404 Not found.
413 Request Entity Too Large.

Events

POST event

Triggers an event on channels.

/apps/<id>/event

Request data

Parameter Required Description
name true Event name
data true Event data
channels true Array of channel names. Limited to 100 channels.
socket_id false Exclude a connection from the targets of the event.

POST events

Triggers events on channels.

/apps/<id>/events

Request data must be an array of events.

Event data

Parameter Required Description
name true Event name
data true Event data
channel true A single channel name. Limited to 100 channels.
socket_id false Exclude a connection from the targets of the event.

Channels

GET channel

Channel endpoint can be used to retrieve information about a specific channel.

/apps/<id>/channel/<name>

Request

Parameter Required Description
info false User count and subscription count attributes can be requested
Info attributes
Attribute Type Restrictions Description
user_count int only valid to presence channels The requested channel's user count
subscription_count int - The requested channel's subscription count

Response

A successful response contains a JSON object. The response optionally contains user count and subscription count attributes if requested.

It returns 400 Bad request as a response if the query contains invalid attributes. The response body of an error contains detailed information. It is invalid to request the user_count attribute for non-presence channels.

Example response:

{
    "occupied":true,
    "user_count":1,
    "subscription_count":1
}

GET channels

Channels endpoint can be used to retrieve information about channels.

/apps/<id>/channels

Request

Parameter Required Description
filter_by_prefix false Channels can be filtered by prefix
info false User count attribute can be requested
Info attributes
Attribute Type Restrictions Description
user_count int only valid to presence channels The requested channels’ user count

Response

A successful response contains a JSON object. The response optionally contains presence channels’ user count if the user_count attribute is requested and only presence channels are filtered.

It returns 400 Bad request as a response if the query contains invalid attributes. The response body of an error contains detailed information. It is invalid to request the user_count attribute for non-presence channels.

Example response:

{
  "channels": {
    "presence-test": {
      "user_count":1
    },
    "presence-test2": {
      "user_count":1
    }
  }
}

Users

GET users

Users endpoint can be used to retrieve a list of user ids which belongs to users who has an active subscription to a specific presence channel.

/apps/<id>/channels/<name>/users

Request

The request is only valid to presence channels.

Response

A successful response contains a JSON object. The JSON contains a list of user ids. It returns an empty list if the channel is currently unoccupied.

It returns 400 Bad request as a response if the requested channel is a non-presence channel.

Example response:
{
  "users": [
    { "id": "1" },
    { "id": "2" }
  ]
}

Authentication

Query params

Parameter Required Description
auth_key true Application key
auth_timestamp true Timestamp. Timestamps over 600s of the current time (during process) are rejected.
auth_version true Authentication version. Currently 1.0
body_md5 For POST requests This parameter must contain the hexadecimal MD5 hash of the body.
auth_signature true Authentication signature

Authentication signature

The signature is a HMAC SHA256 hex digest.

The signature is generated by signing a string made up of the following components:

  • The request method in uppercase. (example POST)
  • The request path with leading forward slash. (example /api/path)
  • The query parameters sorted alphabetically by key. The string must not be URL escaped. (example a=foo&b=bar&c=foo bar)

These components then must be concatenated with new line characters \n.

Full example

POST\n/api/path\na=foo&b=bar&c=foo bar

Table of Contents