API Reference

Supported formats, filter values, error codes, and rate limits.

---

Supported Audio Formats

Format	Extension	MIME Type
MP3	.mp3	audio/mpeg
WAV	.wav	audio/wav
FLAC	.flac	audio/flac
OGG	.ogg	audio/ogg
M4A	.m4a	audio/x-m4a
AAC	.aac	audio/aac
WebM	.webm	audio/webm
Opus	.opus	audio/opus

Max File Size: 150 MB

---

Supported Video Formats

Format	Extension	MIME Type
MP4	.mp4	video/mp4
WebM	.webm	video/webm
MOV	.mov	video/quicktime

Max File Size: 49 MB Max Duration: 30 minutes

---

Musical Keys

Keys are formatted as {note}{quality}:

Minor Keys

aMinor, bMinor, cMinor, dMinor, eMinor, fMinor, gMinor, bbMinor, csMinor, dsMinor, fsMinor, gsMinor

Major Keys

cMajor, dMajor, eMajor, fMajor, gMajor, aMajor, bMajor, dbMajor, ebMajor, fsMajor, abMajor, bbMajor

Example usage:

/api/search?key=aMinor,cMajor

---

Genres

Filter by main_genres. Valid values are returned by the filter options endpoint for your library.

Example usage:

/api/search?main_genres=Electronic,Pop,Hip-Hop

---

Mood

Mood is open vocabulary — both standardized tags and free-text descriptors (e.g. bittersweet longing, quiet determination) are indexed and searchable.

Example usage:

/api/search?mood_tags=Energetic,Uplifting
/api/search?mood_tags=bittersweet longing

---

Instruments

Filter by any instrument audible in the track. Valid values are returned by the filter options endpoint for your library.

Example usage:

/api/search?instruments=Piano,Strings,Synths

---

Vocal Gender

Filter by the predominant vocal type present in the track.

Example usage:

/api/search?vocal_gender=Female
/api/search?vocal_gender=Male and Female

---

Rate Limits

Tier	Requests/Hour	Daily Uploads	API Keys
Free	100	15	1
Pro	1,000	100	5
Enterprise	10,000	Unlimited	20

Rate Limit Headers

Every response includes:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1703000000

When rate limited (HTTP 429):

Retry-After: 3600

Error Codes

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid auth
402	Payment Required - Insufficient credits
403	Forbidden - No permission
404	Not Found
413	Payload Too Large
429	Too Many Requests
500	Internal Server Error

Common Error Responses

Invalid Authentication (401)

{
  "detail": "Invalid or missing authentication token"
}

Insufficient Credits (402)

{
  "detail": "Insufficient credits for this operation",
  "required": 10,
  "balance": 5
}

Not Found (404)

{
  "detail": "Track not found"
}

File Too Large (413)

{
  "detail": "File size exceeds 150MB limit"
}

Rate Limit Exceeded (429)

{
  "error": "Rate limit exceeded",
  "tier": "free",
  "limit": 100,
  "reset_at": "2025-12-18T11:00:00Z"
}

Unsupported Format (400)

{
  "detail": "Unsupported file type '.xyz'. Allowed: .mp3, .wav, .ogg, .flac, .m4a, .aac, .webm, .opus"
}

Daily Limit Reached (429)

{
  "detail": "Daily upload limit reached (15 files)",
  "uploads_today": 15,
  "daily_limit": 15
}