Overview of available functionality.

The MEDKit REST API gives users of Twitch extensions direct access to persistent storage and viewer data endpoints. It can be accessed directly via HTTP requests, or by using the MEDKit JavaScript library.

The REST API has two base URLs:

Base URLDescription
api.muxy.ioProduction environment. Your released extension will only work with this API.
sandbox.api.muxy.ioSandbox environment with relaxed authentication and limited data persistence.

These are completely separate environments that don’t share information and have different levels of security. Sandbox is used for development and testing only, but is inaccessible by production viewers.

Sandbox does not check the authentication of users to allow developers to simulate viewer/broadcaster/admin combinations. Similarly it does not verify transactions or store state for very long.

All endpoints are versioned by path; for example /v1/e/authenticate.

👍

Authentication

All calls must provide a valid Client ID. This is a Twitch Extension Client ID that has been registered with Muxy.

See Register your Twitch extension with Muxy.

Authorization

User authorization is done by passing a JSON Web Token in the Authorization header.

The Authorization header is required for all API requests except:

  • The authtoken endpoint, which you use to obtain a JWT for the sandbox development environment. This token is not accepted in the production environment.
  • The pin endpoint. This endpoint is an alternative way to authenticate a user by passing a Client ID and 6-character PIN that has been generated previously. The response includes a JWT to use for subsequent API calls.

The value of the Authorization header is a space-separated Client ID/JWT pair of the form Authorization: 12345 eyJhbGciOiJIU...

For example:

curl -X GET https://sandbox.api.muxy.io/v1/e/viewer_state \
  -H "Authorization: 12345 eyJhbGciOiJIU"

Endpoint summary

📘

Endpoint paths

All endpoints below are on the main /e/<endpoint> service unless noted otherwise.

Data Storage and Retrieval

The REST API allows you to define, store, and retrieve data for general extension configuration and for real-time extension usage.

This data store is available in two scopes, extension-wide and channel-wide.

  • Each config store is defined by a single JSON object containing key-value pairs. The keys are developer-defined. Use these endpoints to set, modify, and retrieve configuration keys and values.
  • Use a GET request to all_config to retrieve the current content of all configuration stores.
  • The individual config-store endpoints support GET, POST, and PATCH operations.
Configuration Data EndpointUsage
all_configRetrieves all configuration data in a single call.
extension_configMaintains and reports per-extension configuration across channels.
channel_configMaintains and reports per-channel configuration for all extensions running in a channel.

This data store is available with four different scopes.

  • Each state store is defined by a single JSON object containing key-value pairs. The keys are developer-defined. Use these endpoints to set, modify, and retrieve state keys and values.
  • Use a GET request to all_state to retrieve the current content of all state stores.
  • The individual state-store endpoints support GET, POST, and PATCH operations.
State Data EndpointUsage
all_stateRetrieves all four state stores in a single call.
extension_stateMaintains and reports per-extension state information.
viewer_stateMaintains and reports per-viewer state information.
extension_viewer_stateMaintains and reports per-viewer state information for each extension.
channel_stateMaintains and reports per-channel state information for all extensions running in a channel.

The MEDKit REST API supports a variety of tools and techniques for encouraging viewer interaction and engagement, from simple aggregation of viewer data to support for the creation of interactive events.

  • Accumulating data that users provide is the simplest form of aggregation.
  • A ranking service collects answers to open-ended questions, and counts matching responses.
  • A polling service helps you create and manage viewer polls, collect viewer votes, and work with voting results.
  • The trivia and game codes services help you implement a sophisticated voting-and-reward system.
EndpointUsage
accumulateCollect user input for developer-defined data.
rankCreate open-ended questions, collect user answers, and get statistics on popular answers.
vote
vote/vote_logs
Create and manage polls, cast and collect users' votes, get voting results and logs.

Communication API

Additional endpoints support administrative services, including back-channel and server-to-server communication.

EndpointUsage
Broadcast Messaging
broadcast
broadcast_extension
whisper_self
Broadcast messages to viewers on a per-channel or per-extension basis.

This service also enables server-to-server and back-channel communication.