Browse

POST

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

Endpoint

Browse the AudioScape catalog by artist, album, genre, or mood. Use this endpoint to list available entities or drill down into a specific one to get its tracks.

Headers

Name	Type	Description
x-api-key	required	Your API key
Content-Type	required	Must be `application/json`

Request Body

Parameter	Type	Description
type	string required	One of: `artist`, `album`, `genre`, `mood`
name	string optional	Name of the entity to browse. When provided, returns tracks belonging to that entity. When omitted, lists all entities of the given type.
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)

Browse Types

artist

Lists artists with track and album counts. Drill into an artist to get all their tracks.

album

Lists albums with artist and track count. Drill into an album to get its tracks.

genre

Lists all available genres with track counts. Use the genre name to get all tracks in that genre.

mood

Lists available moods (Happy, Exciting, Ambient, etc.) with track counts. Browse tracks by mood to curate playlists.

List Response

When name is omitted, returns a list of entities. The shape of each item depends on the type:

Artist / Album List

{
  "items": [
    {
      "name": "string",
      "track_count": number,
      "album_count": number    // artist only
      "artist": "string",     // album only
      "genre": "string"       // album only
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "artist" | "album"
  }
}

Genre / Mood List

{
  "items": [
    {
      "name": "string",
      "display_name": "string",
      "track_count": number
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "genre" | "mood"
  }
}

Tracks Response

When name is provided, returns tracks belonging to that entity. Same track format as the search endpoint.

{
  "tracks": [
    {
      "asset_id": "string",
      "name": "string",
      "artist": "string",
      "album": "string",
      "duration": number,
      "genre": "string",
      "bpm": number,
      "score": number,
      "thumbnail_url": "string"
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "type": "artist",
    "name": "string"
  }
}

Example Requests

Browse genres to find what's available, then get tracks for a specific genre:

Luau (Roblox)

-- Browse all genres, then get tracks for one
local HttpService = game:GetService("HttpService")
local RunService = game:GetService("RunService")

-- Use a test key in Studio, Secrets in production
local apiKey = if RunService:IsStudio()
    then "your-test-key"
    else HttpService:GetSecret("AudioScapeKey")

local headers = { ["x-api-key"] = apiKey, ["Content-Type"] = "application/json" }

-- Step 1: List available genres
local genres = HttpService:JSONDecode(HttpService:RequestAsync({
  Url = "https://api.audioscape.ai/developer/v1/browse",
  Method = "POST",
  Headers = headers,
  Body = HttpService:JSONEncode({ type = "genre" })
}).Body)

-- Step 2: Get tracks for a specific genre
local tracks = HttpService:JSONDecode(HttpService:RequestAsync({
  Url = "https://api.audioscape.ai/developer/v1/browse",
  Method = "POST",
  Headers = headers,
  Body = HttpService:JSONEncode({
    type = "genre",
    name = "electronic",
    limit = 10
  })
}).Body)

print("Found", tracks.meta.total, "electronic tracks")

Error Responses

400Bad Request

Missing or invalid type parameter.

{
  "error": "type is required and must be one of: artist, album, genre, mood"
}

401Unauthorized

Invalid or missing API key.

{
  "error": "Invalid API key"
}

429Too Many Requests

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

{
  "message": "Too Many Requests"
}

500Internal Server Error

Something went wrong on our end. Try again or contact support if the issue persists.

Ready to get started?

Create your API key and start building with AudioScape today.

Get Your API Key