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 https://mixer.com/api/v1/resources. 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 guarantee 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 20 5
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
upload-interactive 15 300
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

Mixer'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.

Example
$ # Without passing a CSRF token:
$ http get https://mixer.com/api/v1/chats/129

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 https://mixer.com/api/v1/chats/129 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!

Endpoints

/achievements

get /achievements

/broadcasts

get /broadcasts/current
get /broadcasts/{broadcastId}
get /broadcasts/{broadcastId}/manifest.{type}

/channels

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/ingestStream
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/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
get /channels/{channelId}/analytics/tsdb/viewerSessionCount
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.light2
get /channels/{channelId}/manifest.m3u8
get /channels/{channelId}/manifest.ftl
get /channels/{channelId}/partnership/app
post /channels/{channelId}/partnership/app
get /channels/{channelId}/partnership/codes
get /channels/{channelId}/partnership/verify
get /channels/{channelId}/preferences
post /channels/{channelId}/preferences
get /channels/{channelId}/related
delete /channels/{channelId}/streamKey
get /channels/{channelId}/relationship
post /channels/{channelId}/thumbnail
get /channels/{channelId}/users
get /channels/{channelId}/users/{role}
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 /channels/{channelId}/broadcast

/chats

get /chats/{channelId}
get /chats/{channelId}/joinIfNotBigEvent
get /chats/{channelId}/anonymous
get /chats/{channelId}/friends
get /chats/{channelId}/users
get /chats/{channelId}/users/{user}
get /chats/{channelId}/users/search
get /chats/{channelId}/history

/confetti

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

/costreams

get /costreams/{costreamId}
patch /costreams/{costreamId}
delete /costreams/{costreamId}/channels/{channelId}
post /costreams/invite
get /costreams/current
delete /costreams/current

/frontendVersions

get /frontendVersions

/ingests

get /ingests
get /ingests/best

/interactive

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/editor
post /interactive/versions
get /interactive/versions/{version}
put /interactive/versions/{version}
delete /interactive/versions/{version}

/invoices

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

/jwt

post /jwt/authorize

/language

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

/notifications

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

/oauth