Playlist

POST

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

On this pageEndpoint

▼

Endpoint
Headers
Request Body
Get Response
Sound Bank Response
List Response
Example
Errors

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",
    "kind": "music",                // "music" | "sfx" | "mixed"
    "track_count": 25,
    "sound_count": 0,
    "slots": []                     // sfx only — see below
  },
  "tracks": [
    {
      "asset_id": "123456789",
      "name": "Midnight Drive",
      "artist": "Neon Pulse",
      "album": "Synthwave Dreams",
      "genre": "Electronic",          // canonical
      "genre_slug": "electronic",     // URL-safe, drill-downable via /v1/browse
      "duration": 195,
      "bpm": 128,
      "position": 1,
      "created_at": "2024-01-15T...",
      "updated_at": "2024-01-15T..."
    }
  ],
  "meta": { "total": 25 }
}

Sound Bank Response

A playlist can hold sound effects instead of music. Sound effects arrive in sounds, not tracks — the two are kept separate so neither needs a type check before use. Branch on playlist.kind.

200 OK

{
  "playlist": {
    "id": "sfx-1785256484251",
    "name": "Footsteps & Impacts",
    "kind": "sfx",
    "track_count": 0,
    "sound_count": 4,
    "slots": [
      { "label": "footstep", "asset_ids": ["1837879082", "9046863579"] },
      { "label": "impact",   "asset_ids": ["1839851000"] }
    ]
  },
  "tracks": [],
  "sounds": [
    {
      "asset_id": "1837879082",
      "name": "Gravel Step 01",
      "category": "Foley",
      "subcategory": "Footsteps",
      "duration": 0.8,
      "sound_start_sec": 0.06,      // where the audio actually starts
      "sound_end_sec": 0.71,
      "true_peak_dbtp": -2.4,
      "label": "footstep",          // the slot this sound belongs to
      "position": 1
    }
  ],
  "meta": { "total": 4 }
}

Slots group interchangeable sounds: rows sharing a label are variants of one slot. playlist.slots is the grouped view of the same sounds, so you don't have to group them yourself — it's what createSoundBank consumes.

List Playlists Response

200 OK

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

Example

Using the Luau SDK to fetch and play a playlist:

Luau (Roblox)

-- List all playlists
local list, listErr = AudioScape:listPlaylists()
if not list or #list.playlists == 0 then
    warn(listErr or "no playlists configured")
    return
end

-- Fetch a specific playlist
local result, err = AudioScape:getPlaylist({
    playlist_id = "station-electronic-1712...",
})
if not result then warn(err) return end

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

-- Play tracks sequentially (Ended:Wait blocks until each finishes)
for _, track in result.tracks do
    local sound = Instance.new("Sound")
    sound.SoundId = "rbxassetid://" .. track.asset_id
    sound.Parent = workspace
    sound:Play()
    sound.Ended:Wait()
    sound:Destroy()
end

Error Responses

400Bad Request

Missing or invalid playlist_id.

401Unauthorized

Missing or invalid API key. Confirm your x-api-key header is set.

404Not Found

Playlist not found — wrong ID, or it belongs to a different API key.

429Too Many Requests

You've exceeded your rate limit. See your current tier on the API Keys page.

500Internal Server Error

Something went wrong on our end. Retry with backoff; if it persists, ping us on Discord.

Ready to soundtrack your game?

Wire a curated playlist into your radio, lobby, or boombox in minutes.

Get Your API Key