Public API

The Public API provides read access to station data for external integrations such as website widgets, mobile apps, and third-party services.

Setup

Create an API

1. Navigate to Project → API in the sidebar
2. Click Create API
3. Enter a name for the API
4. Save the API

After creation, configure which stations the API can access and which media types to exclude on the API detail page.

Each API receives a unique identifier (UUID) used in request URLs.

The exposed data covers three categories per station: the now-playing track with metadata, recent play history, and upcoming tracks.

Authentication

All requests use the API identifier in the URL path. No authentication headers are required.

https://api.xtra.audio/public/{apiIdentifier}/...

The identifier is a public UUID embedded in the URL. It is not a secret key.

Caching

API responses are cached for 6 minutes (360 seconds). Track changes and metadata updates may take up to 6 minutes to appear in API responses.

Endpoints

List Stations

Retrieve all stations accessible through this API.

GET /public/{apiIdentifier}/stations

Response:

[
  {
    "id": "64a7b2c1e4b0f1a2b3c4d5e6",
    "name": "Radio Example",
    "running": true,
    "description": "24/7 music station",
    "now": [
      {
        "playedAt": 1715270400,
        "media": {
          "id": "64a7b2c1e4b0f1a2b3c4d5e7",
          "artist": "The Beatles",
          "title": "Hey Jude",
          "album": "Past Masters",
          "year": 1968,
          "isrc": "GBAYE0601690",
          "bpm": 74,
          "duration": 431,
          "cover": "https://signed-url.example.com/cover-500x500.jpg"
        }
      }
    ],
    "history": [
      {
        "id": "64a7b2c1e4b0f1a2b3c4d5e8",
        "playedAt": 1715270100,
        "media": {
          "id": "64a7b2c1e4b0f1a2b3c4d5e9",
          "artist": "Queen",
          "title": "Bohemian Rhapsody",
          "album": "A Night at the Opera",
          "year": 1975,
          "isrc": null,
          "bpm": 72,
          "duration": 354,
          "cover": "https://signed-url.example.com/cover-500x500.jpg"
        }
      }
    ],
    "next": [
      {
        "id": "64a7b2c1e4b0f1a2b3c4d5f0",
        "artist": "Fleetwood Mac",
        "title": "Dreams",
        "album": "Rumours",
        "year": 1977,
        "isrc": null,
        "bpm": 120,
        "duration": 254,
        "cover": null
      }
    ]
  }
]

Get Station

Retrieve data for a single station.

GET /public/{apiIdentifier}/station/{stationId}

The response format is identical to a single station object from the list endpoint.

Response fields:

Field	Type	Description
id	string	Station ID
name	string	Station name
running	boolean	Whether the station is currently on air
description	string	Station description
now	array	Currently playing track (single-element array)
history	array	Last 5 played tracks, newest first
next	array	Up to 3 upcoming tracks

Media Object

Each track in now, history, and next contains a media object:

Field	Type	Description
id	string	Media item ID
artist	string	Artist name
title	string	Track title
album	string	Album name
year	number	Release year
isrc	string	ISRC code (may be null)
bpm	number	Beats per minute (may be null)
duration	number	Duration in seconds
cover	string	Signed URL to cover image (500x500px, may be null)

Items in history and now also include playedAt (Unix timestamp in seconds).

Error Responses

Status	Description
404	Station not found
500	Internal server error

{
  "message": "Station not found"
}

Configuration

Delay

The API supports a configurable delay (in milliseconds) that shifts the reported playback time. This is useful for synchronizing the API response with buffered stream output.

Exclude Media Types

Filter which media types appear in API responses. This prevents internal content (jingles, ads) from showing in public-facing integrations.

1. Open the API detail page
2. Select media types to exclude
3. Save changes

Excluded types are filtered from history, now, and next arrays.

Use Cases

Integration	Description
Website widget	Display the current track with cover art
Mobile app	Show now-playing, history, and upcoming tracks
Social media	Auto-post track changes via webhook + API
Analytics	Track listening data externally

Related

• Webhooks - Push notifications for track changes
• Encoders - Stream configuration