Search Music

POST

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

Endpoint

Search our catalog of music using natural language. Describe a mood, genre, or style and the API returns the most relevant tracks. Artist-based queries are also supported.

Headers

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

Request Body

Parameter	Type	Description
query	string required	What you're looking for — an artist name, mood, genre, or description
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)
filters	object optional	Narrow your results: `genres`—Array of genre strings `duration`—Object with `min` and `max` in seconds

Response

Returns matching tracks along with grouped artist and album information.

{
  "tracks": [
    {
      "asset_id": "string",
      "name": "string",
      "artist": "string",
      "album": "string",
      "duration": number,
      "genre": "string",
      "bpm": number,
      "score": number,
      "thumbnail_url": "string"
    }
  ],
  "artists": [
    {
      "name": "string",
      "track_count": number
    }
  ],
  "albums": [
    {
      "name": "string",
      "artist": "string",
      "track_count": number
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "search_method": "semantic" | "text",
    "matched_artist": "string" | null
  }
}

Search Features

Natural Language

Default

Describe what you're looking for in plain language — "upbeat summer vibes", "dark cinematic tension", or "chill lo-fi beats" — and get semantically relevant results.

Artist Recognition

Searching for an artist name like "taylor swift" automatically finds music with a similar sound and style. When this happens, the meta.matched_artist field tells you which artist was recognized.

Keyword Fallback

If semantic search is unavailable, the API automatically falls back to keyword matching so you always get results. Check meta.search_method to see which method was used.

Example Request

Here's a complete example using Roblox's HttpService:

Luau (Roblox)

-- Search for chill lo-fi music
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 response = HttpService:RequestAsync({
  Url = "https://api.audioscape.ai/developer/v1/search",
  Method = "POST",
  Headers = {
    ["x-api-key"] = apiKey,
    ["Content-Type"] = "application/json"
  },
  Body = HttpService:JSONEncode({
    query = "chill lo-fi beats",
    limit = 10,
    filters = {
      genres = { "Lo-Fi", "Chill" },
      duration = { min = 60, max = 180 }
    }
  })
})

local data = HttpService:JSONDecode(response.Body)
print("Found", data.meta.total, "tracks")

Try It

Test the API with your own key. Responses hit the live endpoint.

Response will appear here

Error Responses

400Bad Request

Missing or invalid parameters.

{
  "error": "Missing required field: query"
}

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