Developers

Developer API

Changelog

What changed in the Developer API, and when.

The Developer API is versioned in its URL. Within /api/v1, changes are only ever additive: new endpoints, new event types and new fields. Nothing is renamed or removed, and no meaning changes. Your tool should ignore fields and event types it does not know.

Stream Manager redemptions

  • PATCH /api/v1/stream/{platform}/redemptions/{id} with status fulfilled or canceled: fulfil or refund a channel point redemption of a reward Gleem created. See Redemptions.
  • activity.redemption gains can_manage, true when the reward was created by Gleem and so can be fulfilled or refunded. Cards from before this change do not have it.
  • activity.redemption's status now follows the redemption: fulfilled or refunded by Gleem, by your tool or on Twitch.
  • New event activity.redemption.updated (redemption_id, reward_id, status) on the Stream Manager channel.
  • capabilities.redemptions in GET /api/v1/stream.
  • New error codes reward_not_manageable (403), redemption_not_found (404) and redemption_already_processed (409).

Stream Manager chatters

  • GET /api/v1/stream/{platform}/chatters: who is in chat right now, a page of up to 1,000 at a time with total and cursor. See Chatters.
  • capabilities.chatters in GET /api/v1/stream. It needs the Twitch scope moderator:read:chatters, which the Stream Manager reconnect now asks for; earlier connections list it in missing_scopes until they reconnect.
  • New error code platform_unsupported (422), for a platform that does not offer something the Stream Manager does elsewhere.

Browser-source audio on the IRL Sidekick

  • POST /api/v1/irl/devices/{uuid}/commands takes the audio.* and bluetooth.* commands with a payload: set, update and remove browser sources with their routes and gains, choose where their sound plays, and pair a Bluetooth speaker. See Browser-source audio and Bluetooth.
  • New command audio.test: a short test chime on the IRL Sidekick's speaker and/or into its stream.
  • IRL devices gain audio, the same object, in GET /api/v1/irl/devices and GET /api/v1/irl/devices/{uuid}; null while the device is offline or reports none.
  • The telemetry events on an IRL Sidekick's telemetry channel gain audio: its browser sources (without URLs), outputs and Bluetooth devices. Like interfaces and update, it is left out of an event that would otherwise be too large.

Network addresses behind irl:network

An IRL device's IP addresses locate the streamer's modems, and stream tools need bitrate and link health, not addresses. They now need their own scope. This is the one change in /api/v1 that takes something away: a security fix, not a precedent. See Network addresses.

  • New scope: irl:network, sensitive, on top of irl:read. The consent screen and the token form flag it.
  • The IRL device telemetry channel private-irl-device.<uuid>.telemetry no longer carries addresses: interfaces[].addresses is gone from telemetry events, and remote from the links in ingest.stats. Everything else stays.
  • New channel private-irl-device.<uuid>.network (telemetry_socket.network_channel): the same events in full, for tokens with irl:read and irl:network. See the WebSocket docs.
  • IRL devices gain interfaces (name, kind, state, addresses); addresses is null without irl:network.
  • Tokens Gleem hands to a rented OBS machine can now sign the telemetry channel, since it carries no addresses. They still cannot sign the network channel or see addresses, whatever their scopes.

Stream Manager

The backend of the Gleem IRL app's Stream Manager, open to any tool with the new scopes on an account in the Gleem IRL beta (otherwise 403 feature_unavailable). gleem.gg calls Twitch with your own Twitch sign-in, so the tool never holds a Twitch token; the Stream Manager's Twitch permissions are granted once through reconnect_url, not at sign-in. See Stream Manager and the Stream Manager channel.

  • New scopes: stream:read and stream:write.
  • GET /api/v1/stream: live, viewers, title and category on each platform, what the connection allows, and which Twitch scopes it still lacks.
  • PATCH /api/v1/stream/{platform} and GET …/categories: change the title and category.
  • POST /api/v1/stream/{platform}/chat/messages, DELETE …/chat/messages/{id}, POST …/bans and DELETE …/bans/{user_id}: chat and moderate as the streamer.
  • GET /api/v1/stream/chat and GET /api/v1/stream/activity: the last day's chat and activity.
  • GET and PUT /api/v1/stream/quick-actions: the Gleem IRL app's Quick Actions layout, per account.
  • POST /api/v1/socket/auth signs private-creator.{id}.stream for tokens with stream:read: chat, moderation, follows, subs, gifts, raids, redemptions and Gems, in one platform-neutral shape.

More for the Gleem IRL app

  • GET /api/v1/irl/pair/{code} shows the IRL Sidekick waiting under a pairing code (its hardware, version and when the code expires) so the Gleem IRL app can show it before the creator approves. See Pairing an IRL Sidekick.
  • IRL devices gain version and bitrate (the window the device is set to stream with), and ingest.current_bps: what ingest measured in its latest report, where average_bps is the mean over the whole session.
  • A command sent to a device that goes offline at that very moment answers 409 device_offline instead of a bare 503; a bitrate window is then saved for its next heartbeat.

The Gleem IRL app

Endpoints for the Gleem IRL app, open to any tool with the new scopes. See The Gleem IRL app and OBS rentals.

  • New scopes: irl:write, hosting:read, and hosting:write, which is reserved for starting and ending rentals.
  • POST /api/v1/irl/devices registers a phone as an IRL device and returns its gid_ credential once.
  • POST /api/v1/irl/pair/approve and /decline answer an IRL Sidekick's pairing by the code it shows.
  • POST /api/v1/irl/devices/{uuid}/commands, PUT …/bitrate, PATCH and DELETE /api/v1/irl/devices/{uuid}: remote control, the same as the dashboard.
  • GET /api/v1/hosting/rentals and GET /api/v1/hosting/rentals/{uuid}: the creator's OBS rentals, with their obs-websocket while they run.
  • POST /api/v1/socket/auth signs an IRL device's telemetry channel for tokens with irl:read.
  • IRL devices gain board, hardware, phone and telemetry_socket.
  • Public OAuth apps can register a private-use URI scheme such as gg.gleem.irl:/oauth/callback as a redirect URI (RFC 8252 § 7.1).

General availability

The Developer API is out of preview and open to every creator: the Developer page, personal access tokens, webhooks, OAuth app registration and the consent screen no longer need an invitation. Nothing in /api/v1 changed; tokens and integrations from the preview keep working.

OAuth apps

Third-party tools can now be registered as OAuth apps, so creators connect them with a click instead of pasting a token. See OAuth apps.

  • The authorization code flow with PKCE, the device flow (/activate) and client credentials, at /oauth/authorize, /oauth/token, /oauth/device_authorization and /oauth/revoke, with discovery at /.well-known/oauth-authorization-server.
  • OAuth access tokens (gleem_oat_…) work with every endpoint and the WebSocket, with the same scopes.
  • GET /api/v1/me gains an app object when called with an OAuth token.
  • A 401 for an expired or revoked OAuth token says so in WWW-Authenticate.
  • App webhooks: GET, POST and DELETE /api/v1/webhooks with the new webhooks:write scope.
  • Personal access tokens are unchanged.

Preview

The first version of the Developer API, built together with the Streamer.bot integration.

  • Personal access tokens with scopes, created on the dashboard's Developer page.
  • GET /api/v1/me and POST /api/v1/socket/auth.
  • REST endpoints for the queue, Treats, Gem messages, the leaderboard, memberships and Trigger Tickets, described by an OpenAPI 3.1 spec.
  • Real-time events over the WebSocket: Gem messages, Treat redemptions, queue changes, memberships, post unlocks, follows, Bits exchanges, Trigger Tickets and going live or offline.
  • Signed webhooks with retries, a delivery log and redelivery.
  • login (the Twitch handle) on every viewer object, and total_slots optional when opening a queue.
  • A per-creator message filter for Gem messages and Treat inputs, marked with message_filtered and input_filtered.
  • Test events and a live event log on the Developer page.
  • GET /api/v1/irl/devices and GET /api/v1/irl/devices/{uuid} with the new irl:read scope: Gleem IRL devices and their stream health, for tools such as the OBS IRL Control plugin.