Playlist

POST

https://api.audioscape.ai/developer/v1/playlist

Endpoint

Fetch playlists configured in the Configure tab. Use this endpoint to list all playlists for your API key, or fetch a specific playlist with its ordered tracks for playback in your game.

Headers

Name	Type	Description
x-api-key	required	Your API key
Content-Type	required	Must be `application/json`
X-Universe-Id	optional	Roblox Universe ID (sent automatically by SDK)
X-Place-Id	optional	Roblox Place ID
X-Player-Id	optional	Player ID for per-player analytics

Request Body

This endpoint supports two modes depending on the request body:

Get Playlist

Pass a playlist_id to fetch a specific playlist and its tracks.

Field	Type	Description
playlist_id	string, required	The playlist ID (e.g. `station-electronic-1712...`)

List Playlists

Pass {"action": "list"} to list all playlists for your API key.

Field	Type	Description
action	string, required	Must be `"list"`

Get Playlist Response

200 OK

{
  "playlist": {
    "id": "station-electronic-1712...",
    "name": "Electronic",
    "genre": "electronic",
    "playback_mode": "shuffle",
    "track_count": 25
  },
  "tracks": [
    {
      "asset_id": "123456789",
      "name": "Midnight Drive",
      "artist": "Neon Pulse",
      "album": "Synthwave Dreams",
      "genre": "electronic",
      "duration": 195,
      "bpm": 128,
      "position": 1,
      "created_at": "2024-01-15T...",
      "updated_at": "2024-01-15T..."
    }
  ],
  "meta": { "total": 25 }
}

List Playlists Response

200 OK

{
  "playlists": [
    {
      "id": "station-electronic-1712...",
      "name": "Electronic",
      "genre": "electronic",
      "track_count": 25,
      "playback_mode": "shuffle"
    }
  ],
  "meta": { "total": 1 }
}

Example

Using the Luau SDK to fetch and play a playlist:

Luau

-- List all playlists
local list, err = client:listPlaylists()

-- Fetch a specific playlist
local result, err = client:getPlaylist({
    playlist_id = "station-electronic-1712...",
})

if result then
    print(result.playlist.name, "—", #result.tracks, "tracks")

    for _, track in result.tracks do
        local sound = Instance.new("Sound")
        sound.SoundId = "rbxassetid://" .. track.asset_id
        sound:Play()
    end
end

Errors

Status	Description
400	Missing or invalid `playlist_id`
401	Invalid or missing API key
404	Playlist not found (wrong ID or belongs to a different API key)
429	Rate limit exceeded
500	Internal server error