POST /search
curl --request POST \
--url https://api.trackyard.com/api/external/v1/searchimport requests
url = "https://api.trackyard.com/api/external/v1/search"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.trackyard.com/api/external/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.trackyard.com/api/external/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.trackyard.com/api/external/v1/search"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.trackyard.com/api/external/v1/search")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.trackyard.com/api/external/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"tracks": [
{
"id": "<string>",
"title": "<string>",
"artist": "<string>",
"duration_seconds": 123,
"bpm": 123,
"key": "<string>",
"genre": "<string>",
"subgenres": [
{}
],
"moods": [
{}
],
"has_vocals": true,
"energy_level": "<string>",
"instruments": [
{}
],
"preview_url": "<string>"
}
],
"credits_remaining": 123
}API Reference
POST /search
Natural language music search with AI-powered intent extraction
POST
/
api
/
external
/
v1
/
search
POST /search
curl --request POST \
--url https://api.trackyard.com/api/external/v1/searchimport requests
url = "https://api.trackyard.com/api/external/v1/search"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.trackyard.com/api/external/v1/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.trackyard.com/api/external/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.trackyard.com/api/external/v1/search"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.trackyard.com/api/external/v1/search")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.trackyard.com/api/external/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"tracks": [
{
"id": "<string>",
"title": "<string>",
"artist": "<string>",
"duration_seconds": 123,
"bpm": 123,
"key": "<string>",
"genre": "<string>",
"subgenres": [
{}
],
"moods": [
{}
],
"has_vocals": true,
"energy_level": "<string>",
"instruments": [
{}
],
"preview_url": "<string>"
}
],
"credits_remaining": 123
}Search the Trackyard catalog using natural language queries. Describe what you need in plain English, and the AI infers genre, mood, BPM, instrumentation, and more.
Cost: 1 credit per request
See Rate Limits & Credits for details.
See Error Codes for full reference.
Authentication
All requests require a valid API key in theAuthorization header:
Authorization: Bearer your_api_key_here
Request Body
string
required
Natural language description of the music you need.Examples:
"upbeat electronic music for a tech startup video""moody piano for a rainy scene""15-second clip for an Instagram Reel about travel"
number
default:20
Maximum number of results to return.Range: 1-100
number
default:0
Pagination offset. Use with
limit to paginate through results.object
Optional structured filters to refine results.
Show Filter Options
Show Filter Options
array
Filter by genres. Array of strings.Example:
["Electronic", "Pop"]array
Filter by moods. Array of strings.Example:
["Upbeat", "Energetic"]boolean
Filter by vocal presence.
true: Only tracks with vocalsfalse: Instrumental only
number
Minimum BPM (beats per minute).Range: 40-200
number
Maximum BPM (beats per minute).Range: 40-200
string
Energy level filter.Options:
"low", "medium", "high"array
Filter by instruments. Array of strings.Example:
["Piano", "Guitar", "Drums"]Example Request
curl -X POST https://api.trackyard.com/api/external/v1/search \
-H "Authorization: Bearer $TRACKYARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "upbeat electronic music for tech startup video",
"limit": 5,
"filters": {
"has_vocals": false,
"min_bpm": 120,
"max_bpm": 140
}
}'
Response
array
required
Array of track objects matching your query.
Show Track Object
Show Track Object
string
required
Unique track identifier. Use this with
/download-track.string
required
Track title.
string
required
Artist or producer name.
number
required
Track length in seconds.
number
Beats per minute.
string
Musical key (e.g., “C Major”, “A Minor”).
string
Parent genre (e.g., “Hip Hop”, “Electronic”, “Rock”).
array
Array of sub-genre tags (e.g., [“Boom Bap”, “Lo-Fi Hip Hop”]).
array
Array of mood tags.
boolean
Whether the track contains vocals.
string
Energy level: “low”, “medium”, or “high”.
array
Array of primary instruments.
string
URL to a 30-second preview MP3. Free to stream.
number
required
Your remaining credit balance after this request.
Example Response
{
"tracks": [
{
"id": "trk_abc123",
"title": "Digital Sunrise",
"artist": "Sync Lab",
"duration_seconds": 142,
"bpm": 128,
"key": "C Major",
"genre": "Electronic",
"subgenres": ["Deep House", "Tech House"],
"moods": ["Upbeat", "Energetic", "Modern"],
"has_vocals": false,
"energy_level": "high",
"instruments": ["Synth", "Electronic Drums", "Bass"],
"preview_url": "https://cdn.trackyard.com/previews/trk_abc123.mp3"
},
{
"id": "trk_def456",
"title": "Innovation Drive",
"artist": "The Production House",
"duration_seconds": 156,
"bpm": 132,
"key": "D Major",
"genre": "Pop",
"subgenres": ["Dance-Pop", "Electropop"],
"moods": ["Upbeat", "Motivational", "Tech"],
"has_vocals": false,
"energy_level": "high",
"instruments": ["Synth", "Piano", "Drums"],
"preview_url": "https://cdn.trackyard.com/previews/trk_def456.mp3"
}
],
"credits_remaining": 487
}
Rate Limits
All responses include rate limit headers:X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Limit-Daily: 50
X-RateLimit-Remaining-Daily: 42
X-Credits-Remaining: 44
Error Responses
Missing or invalid API key.
{
"error": "Unauthorized",
"message": "Invalid API key"
}
Out of credits.
{
"error": "Out of credits",
"message": "Please top up or upgrade your plan"
}
Rate limit exceeded.
{
"error": "Too Many Requests",
"message": "Rate limit exceeded"
}
Tips for Better Results
Be specific: “upbeat electronic music for a tech startup video” beats “upbeat music”
Include context: Describe the scene, use case, or platform (Instagram Reel, podcast intro, etc.)
Combine AI + filters: Let the AI interpret your query, then add filters for surgical precision
Preview before downloading: Stream the
preview_url to audition tracks before spending a credit on /download-trackNext Steps
Download Track
Download full tracks or smart-trimmed clips
Parameters Guide
Full reference of all search filters
AI-Powered Search
Learn how natural language search works
Code Examples
Python and JavaScript examples