Side note: REST APIs

If your friend was going to the store and you needed something, you might ask them to "get" something for you. After they get back, they might "put" that item away for you. These are the constructs we use in everyday life, and REST APIs attempt to build on those, but, rather than operating on physical items, you're dealing with objects on the computer.

When you send HTTP requests to webpages, each request contains a verb. Most browsing you do involves your web browser making GET requests—asking for this page, for instance! But there are several other verbs your browser uses:

  • GET looks something up, as we've said
  • POST creates something
  • PUT updates something
  • DELETE destroys something

On our RESTful API, you make requests by calling VERB We'll abbreviate this as VERB /resources from now on. For instance, to create a new user, you would call POST /users (the endpoints are always plural). If you want to operate on a particular user object, you would append their ID to that URL, such as GET /users/344 to return information about user ID 344.

You can also run actions on a particular user by chaining on "actions", such as PUT /users/344/confirm, which is used to verify an account. Here's a full blueprint with some examples:

Endpoint Description Example
GET /resources Returns a list of 'resource' objects. GET /users
POST /resources Creates a new 'resource' object. POST /users
GET /resources/{id} Returns information about the 'resource' with the provided ID. GET /users/314
PUT /resources/{id} Updates a resource with the provided ID. PUT /users/314
POST /resources/{id}/action Runs some action on a 'resource'. PUT /users/314/confirm
GET /resources/{id}/data Gets some nested information about a 'resource'. GET /users/314/avatar
DELETE /resources/{id} Delete a resource from the server. DELETE /channels/314/streamKey

If you want some more information about talking to our REST API, check out our REST Tutorial.

Rate Limiting

In order to garantuee API stability there are a few rate limits in place, all endpoints that are rate limited have their bucket noted below.

Here is a list of all rate limiting buckets and their attributes.

Each endpoint can be called Request Count times per Time Interval.
Name Request Count Time Interval (in Seconds)
channel-follow 100 60
channel-read 1000 300
channel-search 250 300
channel-write 250 300
chats 500 60
contact 3 60
global 1000 60
ingest 5 60
mail-subscribe 3 60
notification-read 100 60
report 10 60
upload 5 600
user-email 2 86400
user-login 50 60
user-login-failed 8 900
user-read 500 60
user-register 2 60
user-write 100 60

CSRF Tokens

Beam's REST API requires the use of CSRF Tokens when using cookie-base authentication.

CSRF tokens are alphanumeric strings issued by the server and are included in the X-CSRF-Token header in responses. They are used to authorize requests and are bound a specific session cookie. They are invalidated after the session expires and may be invalidated at any point prior to the session expiration.

CSRF tokens must be passed to the server in the X-CSRF-Token header when making requests which use cookie-based authentication. Failing to pass a valid CSRF token will cause the request to return in a 461 CSRF Token Invalid response. The server will include an X-CSRF-Token header in the response, which contains a CSRF token that the client can use to retry the request.

$ # Without passing a CSRF token:
$ http get

HTTP/1.1 461 CSRF token invalid
Content-Type: application/json
X-CSRF-Token: dca5130a5a6390bd83c077a902e1edf8d052bcc8

    "error": "Invalid CSRF header",
    "statusCode": 461

$ # Now we have a CSRF token to use:
$ http get X-CSRF-Token:dca5130a5a6390bd83c077a902e1edf8d052bcc8

HTTP/1.1 200 OK

Need more help?

If you're still not sure, or would like some help, hit us up on Gitter!



get /achievements


post /announcements


get /channels
get /channels/{channelIdOrToken}
get /channels/{channelIdOrToken}/details
put /channels/{channelId}
patch /channels/{channelId}
get /channels/{channelId}/analytics/viewers
get /channels/{channelId}/analytics/tsdb/viewers
get /channels/{channelId}/analytics/tsdb/viewersMetrics
get /channels/{channelId}/analytics/tsdb/streamSessions
get /channels/{channelId}/analytics/tsdb/streamHosts
get /channels/{channelId}/analytics/tsdb/subscriptions
get /channels/{channelId}/analytics/tsdb/followers
get /channels/{channelId}/analytics/tsdb/sparkSpent
get /channels/{channelId}/analytics/tsdb/emojiUsageRanks
get /channels/{channelId}/analytics/tsdb/emojiUsage
get /channels/{channelId}/analytics/tsdb/gameRanks
get /channels/{channelId}/analytics/tsdb/gameRanksGlobal
get /channels/{channelId}/analytics/tsdb/subRevenue
get /channels/{channelId}/analytics/tsdb/cpm
post /channels/{channelId}/badge
get /channels/{channelId}/follow
put /channels/{channelId}/follow
post /channels/{channelId}/follow
delete /channels/{channelId}/follow
get /channels/{channelId}/emoticons
patch /channels/{channelId}/emoticons
get /channels/{channelId}/hostee
put /channels/{channelId}/hostee
delete /channels/{channelId}/hostee
get /channels/{channelId}/hosters
get /channels/{channelId}/manifest.light
get /channels/{channelId}/manifest.light2
get /channels/{channelId}/manifest.smil
get /channels/{channelId}/manifest.m3u8
get /channels/{channelId}/manifest.ftl
get /channels/{channelId}/partnership/app
post /channels/{channelId}/partnership/app
post /channels/{channelId}/partnership/app/deny
post /channels/{channelId}/partnership/app/accept
get /channels/{channelId}/partnership/codes
get /channels/{channelId}/preferences
post /channels/{channelId}/preferences
get /channels/{channelId}/related
delete /channels/{channelId}/streamKey
get /channels/{channelId}/relationship
post /channels/{channelId}/suspend
delete /channels/{channelId}/suspend
post /channels/{channelId}/thumbnail
get /channels/{channelId}/users
patch /channels/{channelId}/users/{userId}
get /channels/{channelId}/discord
put /channels/{channelId}/discord
get /channels/{channelId}/discord/channels
get /channels/{channelId}/discord/roles
get /channels/{channelId}/discord/invite
post /channels/{channelId}/discord/invite
get /channels/{channelId}/recordings
post /channels/{channelId}/transcodes/unlock
get /channels/{channelId}/confetti
get /channels/{channelId}/banner
post /channels/{channelId}/banner
delete /channels/{channelId}/banner


get /chats/endpoints
get /chats/{channelId}
get /chats/{channelId}/friends
get /chats/{channelId}/users
get /chats/{channelId}/users/{user}
get /chats/{channelId}/users/search


put /confetti
get /confetti/{confettiId}
patch /confetti/{confettiId}
delete /confetti/{confettiId}


get /frontendVersions


get /ingests
get /ingests/best


get /interactive/{channel}
get /interactive/{channel}/robot
get /interactive/hosts
get /interactive/games
post /interactive/games
get /interactive/games/{game}
put /interactive/games/{game}
delete /interactive/games/{game}
get /interactive/games/{game}/versions
post /interactive/games/{game}/cover
post /interactive/games/{game}/editors
get /interactive/games/{game}/editors
delete /interactive/games/{game}/editors/{user}
get /interactive/games/owned
get /interactive/games/shared
get /interactive/games/reviewing
get /interactive/games/editor
post /interactive/versions
get /interactive/versions/{version}
put /interactive/versions/{version}
delete /interactive/versions/{version}


get /invoices/{invoice}
post /invoices/{invoice}/capture


post /jwt/authorize


get /language/channels
get /language/channels/active
get /language/channels/available


get /notifications/{notificationId}
post /notifications/{notificationId}/shareSub
delete /notifications/{notificationId}/shareSub
post /notifications/emailUnsubscribe