Search

Find the perfect track in your library using text search, filters, or natural language queries. The search API automatically uses AI-powered semantic search when text search returns no exact matches.

Search Tracks

GET /api/v1/search

Search your tracks with optional filters. Returns full track metadata including genres, moods, instruments, and more.

curl "https://api.songpot.space/api/v1/search?q=upbeat&min_bpm=120&max_bpm=140&moods=Energetic&genres=Pop" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.songpot.space/api/v1/search",
    params={
        "q": "upbeat",
        "min_bpm": 120,
        "max_bpm": 140,
        "moods": "Energetic",
        "genres": "Pop"
    },
    headers={"X-API-Key": API_KEY}
)

tracks = response.json()["tracks"]

const params = new URLSearchParams({
  q: 'upbeat',
  min_bpm: 120,
  max_bpm: 140,
  moods: 'Energetic',
  genres: 'Pop'
});

const response = await fetch(`https://api.songpot.space/api/v1/search?${params}`, {
  headers: { 'X-API-Key': API_KEY }
});

const { tracks } = await response.json();

Query Parameters

Parameter	Type	Description
`q`	string	Text to search for in name and description. Automatically falls back to semantic (AI) search if no exact matches.
`min_bpm`	number	Minimum BPM
`max_bpm`	number	Maximum BPM
`key`	string	Musical keys, comma-separated (e.g., `cMajor,aMinor`)
`genres`	string	Genres, comma-separated (e.g., `Pop,Electronic`)
`moods`	string	Moods, comma-separated (e.g., `Energetic,Happy`)
`instruments`	string	Instruments, comma-separated (e.g., `Piano,Guitar`)
`vocal_gender`	string	Vocal gender (Male, Female, Mixed, None)
`limit`	number	Number of results (default: 20, max: 100)

Filter Logic

Multiple values within a filter: Use commas to select multiple values. Tracks matching any of the values are returned (OR logic).
Multiple filters: Different filters are combined with AND logic.

Example: genres=Pop,Electronic&moods=Energetic,Happy returns tracks that are (Pop OR Electronic) AND (Energetic OR Happy).

Response

{
  "total": 15,
  "tracks": [
    {
      "id": "abc123",
      "name": "Upbeat Pop",
      "duration": 185.4,
      "bpm": 128.0,
      "key": "cMajor",
      "vocal_gender": "Female",
      "genres": ["Pop", "Electronic", "Synth Pop"],
      "moods": ["Energetic", "Happy"],
      "instruments": ["Synths", "Drums", "Vocals"],
      "description": "Upbeat electronic pop track with female vocals"
    }
  ],
  "search_method": "text"
}

Search Methods

The search_method field indicates how results were found:

Method	Description
`text`	Results from exact text and filter matching
`semantic`	Results from AI-powered semantic search (automatic fallback when text search returns no results)

Search Examples

curl "https://api.songpot.space/api/v1/search?genres=Pop,Electronic,Hip-Hop" \
  -H "X-API-Key: YOUR_API_KEY"

response = requests.get(
    "https://api.songpot.space/api/v1/search",
    params={"genres": "Pop,Electronic,Hip-Hop"},
    headers={"X-API-Key": API_KEY}
)

Filter by BPM Range and Mood

curl
Python

curl "https://api.songpot.space/api/v1/search?min_bpm=80&max_bpm=100&moods=Calm,Chilled" \
  -H "X-API-Key: YOUR_API_KEY"

response = requests.get(
    "https://api.songpot.space/api/v1/search",
    params={"min_bpm": 80, "max_bpm": 100, "moods": "Calm,Chilled"},
    headers={"X-API-Key": API_KEY}
)

Combine Text Query with Filters

curl
Python

curl "https://api.songpot.space/api/v1/search?q=summer&genres=Pop&instruments=Guitar,Piano" \
  -H "X-API-Key: YOUR_API_KEY"

response = requests.get(
    "https://api.songpot.space/api/v1/search",
    params={
        "q": "summer",
        "genres": "Pop",
        "instruments": "Guitar,Piano"
    },
    headers={"X-API-Key": API_KEY}
)

Browse All Tracks

To browse all your tracks without filters:

curl
Python

curl "https://api.songpot.space/api/v1/search?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

response = requests.get(
    "https://api.songpot.space/api/v1/search",
    params={"limit": 50},
    headers={"X-API-Key": API_KEY}
)