Documentation Powered by ReDoc

Whereby REST API (v1)

These are the reference docs for the Whereby REST API.

If you haven't already read the embedded developer resources, you will want to read that first for a high level overview over the Whereby APIs.

Rate limiting (throttling)

We rate limit our APIs, returning a 429 status code response when your request has been throttled. You will have to wait and retry the request later.

We use a point system to limit the number of requests that you can make.
A read request consumes 1 point, a delete consumes 2 points and a write request consumes 3 points.
Here are some examples of how a 1000 point budget could be spent within 1 minute:

  • 1000 GET requests (1000 x 1 = 1000 points)
  • 500 DELETE requests (500 x 2 = 1000 points)
  • 333 POST requests (333 x 3 = 999 points)
  • 200 DELETE + 100 POST + 300 GET requests (200 x 2 + 100 x 3 + 300 x 1 = 1000 points)

Grow plans have 1000 points in total per minute, and Build plans have 100. The limits are global and are shared across all your API keys. Talk to us if you need higher limits.

You may read the Retry-After (seconds) or X-RateLimit-Reset (date) response headers in order to know when you can restart your requests. In addition, the X-RateLimit-Limit header includes the total number of points for your organization, and the X-RateLimit-Remaining header displays the remaining available points.

Authentication

BearerAuth

The bearer token will be provided upon request and it is up to the client to keep it secret. Every API call needs to contain this token in order to authenticate and authorize the client.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Create meeting

Creates a transient room that is available between creation and an hour after the given end date. After this time the room will be automatically deleted. The URL to this room is present in the response.

Request Body schema: application/json

Meeting to add.

templateType
string
Value: "viewerMode"

[BETA]: This is a beta feature, and might change in the future. If provided, the room will be created with the given template type. Each template defines a set of properties needed for a particular use-case. Currently the only supported template type is "viewerMode". This will set up a room with properties that are needed to create a viewer mode room. The room will be locked, roomMode set to "group" and fields like hostRoomUrl and viewerRoomUrl will be added to the response.

isLocked
boolean

The initial lock state of the room. If true, only hosts will be able to let in other participants and change lock state.

roomNamePrefix
string <= 39 characters [a-z0-9]{0,39}

This will be used as the prefix for the room name. The string should be lowercase, and spaces will be automatically removed.

roomNamePattern
string
Default: "uuid"
Enum: "uuid" "human-short"

The format of the randomly generated room name. uuid is the default room name pattern and follows the usual 8-4-4-4-12 pattern. human-short generates a shorter string made up of six distinguishable characters.

roomMode
string
Default: "normal"
Enum: "group" "normal"

The mode of the created transient room. normal is the default room mode and should be used for meetings up to 4 participants. group should be used for meetings that require more than 4 participants.

startDate
string <date-time>
Deprecated

When the meeting starts. By default in UTC but a timezone can be specified, e.g. 2021-05-07T17:42:49-05:00. This date must be in the future. (DEPRECATED - value is ignored)

endDate
required
string <date-time>

When the meeting ends. By default in UTC but a timezone can be specified, e.g. 2021-05-07T17:42:49-05:00. This has to be the same or after the current date.

object

Options for how a meeting should be recorded.

object

A configuration object for live RTMP streaming of the meeting

fields
Array of strings (Fields)
Items Enum: "hostRoomUrl" "viewerRoomUrl"

Additional fields that should be populated.

  • hostRoomUrl - Include hostRoomUrl field in the meeting response.
  • viewerRoomUrl - Include viewerRoomUrl field in the meeting response.

Responses

Response Schema: application/json
meetingId
required
string

The ID of the meeting.

roomName
string

The name of the room.

roomUrl
required
string <uri>

The URL to room where the meeting will be hosted.

startDate
string <date-time>

When the meeting starts. Always in UTC, regardless of the input timezone.

endDate
required
string <date-time>

When the meeting ends. Always in UTC, regardless of the input timezone.

hostRoomUrl
string <uri>

The URL to the room where the meeting will be hosted which will also make the user the host of the meeting. A host will get additional privileges like locking the room, and removing and muting participants, so you should be careful with whom you share this URL. The user will only become a host if the meeting is on-going (some additional slack is added to allow a host joining the meeting ahead of time or if the meeting goes over time). This field is optional and will only be returned if requested through the fields parameter.

viewerRoomUrl
string <uri>

The URL to the room where the meeting will be hosted which will make the user a viewer of the meeting. A viewer will not be able to turn on the camera or microphone, but will be able to join the meeting. This field is optional and will only be returned if requested through the fields parameter.

Request samples

Content type
application/json
{
  • "templateType": "viewerMode",
  • "isLocked": true,
  • "roomNamePrefix": "example-prefix",
  • "roomNamePattern": "uuid",
  • "roomMode": "normal",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "recording": {
    },
  • "streaming": {
    },
  • "fields": [
    ]
}

Response samples

Content type
application/json
{}

Get meetings

Returns the meetings.

query Parameters
cursor
string
Example: cursor=8f4031bfc7640c5f267b11b6fe0c2507

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

limit
integer [ 1 .. 100 ]
Default: 50

The limit for the pagination - the maximum number of results that will be returned within a single API response.

fields
Array of strings (Fields)
Items Enum: "hostRoomUrl" "viewerRoomUrl"

Additional fields that should be populated.

  • hostRoomUrl - Include hostRoomUrl field in the meeting response.
  • viewerRoomUrl - Include viewerRoomUrl field in the meeting response.

Responses

Response Schema: application/json
required
Array of objects (Meeting) [ items ]
cursor
required
string

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request. If there are no more results, the value returned is null.

Response samples

Content type
application/json
{}

Delete meeting

Deletes the specified meeting. The endpoint is idempotent, meaning it will return the same response even if the meeting has already been deleted.

path Parameters
meetingId
required
any
Example: 1

meeting ID.

Responses

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Get meeting

Returns the specified meeting.

path Parameters
meetingId
required
any
Example: 1

meeting ID.

query Parameters
fields
Array of strings (Fields)
Items Enum: "hostRoomUrl" "viewerRoomUrl"

Additional fields that should be populated.

  • hostRoomUrl - Include hostRoomUrl field in the meeting response.
  • viewerRoomUrl - Include viewerRoomUrl field in the meeting response.

Responses

Response Schema: application/json
meetingId
required
string

The ID of the meeting.

roomName
string

The name of the room.

roomUrl
required
string <uri>

The URL to room where the meeting will be hosted.

startDate
string <date-time>

When the meeting starts. Always in UTC, regardless of the input timezone.

endDate
required
string <date-time>

When the meeting ends. Always in UTC, regardless of the input timezone.

hostRoomUrl
string <uri>

The URL to the room where the meeting will be hosted which will also make the user the host of the meeting. A host will get additional privileges like locking the room, and removing and muting participants, so you should be careful with whom you share this URL. The user will only become a host if the meeting is on-going (some additional slack is added to allow a host joining the meeting ahead of time or if the meeting goes over time). This field is optional and will only be returned if requested through the fields parameter.

viewerRoomUrl
string <uri>

The URL to the room where the meeting will be hosted which will make the user a viewer of the meeting. A viewer will not be able to turn on the camera or microphone, but will be able to join the meeting. This field is optional and will only be returned if requested through the fields parameter.

Response samples

Content type
application/json
{}

Set room colors

Set primary, secondary and focus room colors.

path Parameters
roomName
required
any
Example: 913c4449-c904-4313-b560-ae5bf0b04a39

Room name.

Request Body schema: application/json
object

Room colors defined in an object.

tokensPreset
string
Enum: "custom" "default"

Use the given primary or secondary colors when custom. Use organization defaults when default or not defined.

Responses

Request samples

Content type
application/json
{
  • "tokens": {
    },
  • "tokensPreset": "custom"
}

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Set room logo

Upload room logo.

path Parameters
roomName
required
any
Example: 913c4449-c904-4313-b560-ae5bf0b04a39

Room name.

Request Body schema:
multipart/form-data
multipart/form-data
application/json
image
string <binary>

The logo image. We recommend PNG images at least 400px wide.

Responses

Request samples

Content type
multipart/form-data
multipart/form-data
application/json
No sample

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Set room background

Set room background.

path Parameters
roomName
required
any
Example: 913c4449-c904-4313-b560-ae5bf0b04a39

Room name.

Request Body schema:
multipart/form-data
multipart/form-data
application/json
image
string <binary>

The background image. We recommend PNG images at least 1400px wide (max 600 kb).

Responses

Request samples

Content type
multipart/form-data
multipart/form-data
application/json
No sample

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Set room knock page background

Set room knock page background.

path Parameters
roomName
required
any
Example: 913c4449-c904-4313-b560-ae5bf0b04a39

Room name.

Request Body schema:
multipart/form-data
multipart/form-data
application/json
image
string <binary>

The knock page background image. We recommend PNG images at least 1400px wide (max 600 kb).

Responses

Request samples

Content type
multipart/form-data
multipart/form-data
application/json
No sample

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Get room insights

Gets a summary of insights collected for rooms.

query Parameters
object

Filter results by room name.

object

Filter rooms by the date they were created.

sortBy
any
Example: sortBy=totalSessions:asc

Sort results by a field.

cursor
any
Example: cursor=8f4031bfc7640c5f267b11b6fe0c2507

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=30

Limit the number of results.

Responses

Response Schema: application/json
cursor
string

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request. If there are no more results, the value returned is null.

Array of objects[ items ]

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "results": [
    ]
}

Get room session insights

Gets a summary of usage for each session of a given room.

query Parameters
roomName
required
any
Example: roomName=/4b3bd908-cb88-11ec-9d64-0242ac120002

Room name .

sortBy
any
Example: sortBy=totalUniqueParticipants:asc

Sort results by a field.

cursor
any
Example: cursor=8f4031bfc7640c5f267b11b6fe0c2507

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=30

Limit the number of results.

Responses

Response Schema: application/json
cursor
string

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request. If there are no more results, the value returned is null.

Array of objects[ items ]

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "results": [
    ]
}

Get participants

Gets a list of participants, by either a given session id or external id.

query Parameters
roomSessionId
any
Example: roomSessionId=4b3bd908-cb88-11ec-9d64-0242ac120002

session ID.

externalId
any

an externalId that was used in queryParams by the participant when joining.

sortBy
any
Example: sortBy=joinedAt:asc

Sort results by a field. Accepted values are joinedAt and leftAt. Accepted sort values are asc and desc.

cursor
any
Example: cursor=8f4031bfc7640c5f267b11b6fe0c2507

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=30

Limit the number of results.

Responses

Response Schema: application/json
cursor
string

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request. If there are no more results, the value returned is null.

Array of objects[ items ]

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "results": [
    ]
}

Get details for a participant in a session

Returns session data such as user agent, bandwidth and packet loss for the participant.

query Parameters
roomSessionId
required
any
Example: roomSessionId=4b3bd908-cb88-11ec-9d64-0242ac120002

session ID.

participantId
required
any
Example: participantId=32ba120a-a691-4e8e-aec3-a610239271de

participant ID.

Responses

Response Schema: application/json
Array
displayName
required
string

Display name of the participant.

userRole
required
string

The role of the participant.

userAgent
required
string

User agent string of the participant.

timeStamp
required
string

Timestamp the participant joined the session.

sampleRateMs
required
number

The interval (in milliseconds) the samples are collected in.

samples
required
object

Data object arrays with network data. packetLossSend, packetLossRecv, bitrateSend and bitrateRecv.

Response samples

Content type
application/json
[
  • {
    }
]

Get recordings

Returns the recordings.

query Parameters
cursor
string
Example: cursor=8f4031bfc7640c5f267b11b6fe0c2507

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request.

limit
integer [ 1 .. 100 ]
Default: 50

The limit for the pagination - the maximum number of results that will be returned within a single API response.

Responses

Response Schema: application/json
results
required
Array of objects (Recording) [ items ]
cursor
required
string

The cursor for paginating through the results. To fetch the next page, set the cursor to the cursor returned by the previous request. If there are no more results, the value returned is null.

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "cursor": "string"
}

Get recording

Returns the specified recording.

path Parameters
recordingId
required
any
Example: 1

The recording ID.

Responses

Response Schema: application/json
object (Recording)

Response samples

Content type
application/json
{
  • "recordingId": "1",
  • "roomSessionId": "1",
  • "filename": "recording.mp4",
  • "startDate": "2020-01-01T00:00:00.000Z",
  • "endDate": "2020-01-01T00:00:00.000Z",
  • "sizeInMegaBytes": 100
}

Delete recording

Deletes the specified recording. The endpoint is idempotent, meaning it will return the same response even if the meeting has already been deleted.

path Parameters
recordingId
required
any
Example: 1

The recording ID.

Responses

Response samples

Content type
application/json
{
  • "error": "Rate limit active for throttle key: organization:1",
  • "data": {
    }
}

Get recording access link

Returns the access link for the specified recording.

path Parameters
recordingId
required
any
Example: 1

The recording ID.

query Parameters
validForSeconds
integer [ 1 .. 43200 ]
Default: 3600

The number of seconds the access link is valid for.

Responses

Response Schema: application/json
accessLink
required
string

The access link.

expires
required
integer

The timestamp when the access link expires.

Response samples

Content type
application/json
{}