Whereby (1.0.0)

These are the reference docs for the Whereby REST API.

If you haven't already read the embedded developer guide, 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 the 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. 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.



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.


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

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.

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.

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.

string <date-time>

When the meeting starts. By defa