Documentation

The Custom Text / JSON API

If you are a developer, or you simply want to pipe your currently playing text into a Twitch Chatbot (like Nightbot or StreamElements), you can use our dynamic formatting endpoints.

Navigate to the API Link Generator in your Dashboard to easily construct these links.

Mode 1: Plain Text Formatting

To get your current song as a raw, physical text string, provide a text template using the format=text and text= query parameters.

Example GET request: .../api/widget/YOUR-UUID/data?format=text&text={{artist}} - {{title}}

Example Output: Rick Astley - Never Gonna Give You Up

You can use the fallback= parameter to specify what text should be served when Spotify is paused.

Mode 2: Dynamic JSON Schema

If you are building your own tools or dashboards, simply hitting the endpoint with format=json will return all the internal track data.

However, you can also inject our templating variables straight into your own JSON architecture by passing a stringified JSON schema to the schema= parameter.

Example schema= query parameter:

{
  "is_live": {{isPlaying}},
  "now": "{{songName}}",
  "art": "{{albumArt}}"
}

The server will recursively evaluate your schema and return perfectly valid JSON fitting your software’s requirements.

Available Variables

These magic variables can be placed anywhere inside the text= string or your custom schema=:

  • {{title}} or {{songName}} - The name of the track.
  • {{artist}} - Comma-separated list of track artists.
  • {{albumArt}} - Direct URL to the primary 640x640 JPEG album cover.
  • {{url}} - Direct open.spotify.com link to the track.
  • {{progress}} - Formatted time (e.g. 1:04)
  • {{duration}} - Formatted time (e.g. 3:32)
  • {{isPlaying}} - Literal true or false (Useful for JSON schemas).
  • {{progress_ms}} & {{duration_ms}} - Raw integers.