{"openapi":"3.1.0","info":{"title":"Uncommon Ear API","version":"1.0.0","summary":"Search free music and sound effects, with each track’s license and terms.","description":"Search a catalog of music and sound effects that come under different licenses, mostly CC0. Every call needs an API key from a free Uncommon Ear account, sent as \"Authorization: Bearer ue_...\". Free accounts can make 20 calls per minute and 300 per day; Pro accounts can make 60 per minute and 20,000 per month. The limits are shared with MCP. Guide: https://uncommonear.com/docs/api"},"servers":[{"url":"https://uncommonear.com"}],"tags":[{"name":"Catalog","description":"Search and look up tracks."}],"paths":{"/v1/search":{"get":{"operationId":"searchTracks","summary":"Search tracks","description":"Search the catalog of music and sound effects. Tracks come under different licenses; every track carries its license and terms, an attribution status, and a credit_line to paste. With no parameters it returns a shuffled page. Every filter on the website is a parameter here.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Words for mood, genre, instrument, title, or intended use, such as \"calm piano\".","schema":{"type":"string","maxLength":500,"description":"Words for mood, genre, instrument, title, or intended use, such as \"calm piano\"."}},{"name":"kind","in":"query","required":false,"description":"music (the default) or sfx for sound effects.","schema":{"type":"string","enum":["music","sfx"],"description":"music (the default) or sfx for sound effects."}},{"name":"tempo","in":"query","required":false,"description":"Beats per minute as a range, such as 90-120.","schema":{"type":"string","pattern":"^\\d{1,3}-\\d{1,3}$","description":"Beats per minute as a range, such as 90-120."}},{"name":"length","in":"query","required":false,"description":"Length buckets, comma-separated: xs, s, m, l. Music: under 30 s, 30 s to 2 min, 2 to 5 min, over 5 min. Sound effects use shorter buckets.","schema":{"type":"string","pattern":"^(xs|s|m|l)(,(xs|s|m|l))*$","description":"Length buckets, comma-separated: xs, s, m, l. Music: under 30 s, 30 s to 2 min, 2 to 5 min, over 5 min. Sound effects use shorter buckets."}},{"name":"energy","in":"query","required":false,"description":"Energy, comma-separated: calm, steady, driving.","schema":{"type":"string","pattern":"^(calm|steady|driving)(,(calm|steady|driving))*$","description":"Energy, comma-separated: calm, steady, driving."}},{"name":"tone","in":"query","required":false,"description":"Tone, comma-separated: dark, warm, bright.","schema":{"type":"string","pattern":"^(dark|warm|bright)(,(dark|warm|bright))*$","description":"Tone, comma-separated: dark, warm, bright."}},{"name":"loops","in":"query","required":false,"description":"Set to true to return only tracks marked as loops.","schema":{"type":"string","enum":["0","1","true","false"],"description":"Set to true to return only tracks marked as loops."}},{"name":"quality","in":"query","required":false,"description":"Set to good to hide lower-quality recordings. Default: any.","schema":{"type":"string","enum":["any","good"],"description":"Set to good to hide lower-quality recordings. Default: any."}},{"name":"genre","in":"query","required":false,"description":"Genre tag ids, comma-separated, such as rock,jazz. A track matches if it has any of them. Tags across different facets must all match.","schema":{"type":"string","pattern":"^[a-z0-9_-]+(,[a-z0-9_-]+)*$","description":"Genre tag ids, comma-separated, such as rock,jazz. A track matches if it has any of them. Tags across different facets must all match."}},{"name":"mood","in":"query","required":false,"description":"Mood tag ids, comma-separated. Any-of, like genre.","schema":{"type":"string","pattern":"^[a-z0-9_-]+(,[a-z0-9_-]+)*$","description":"Mood tag ids, comma-separated. Any-of, like genre."}},{"name":"use","in":"query","required":false,"description":"Intended-use tag ids, comma-separated, such as menu,trailer. Any-of.","schema":{"type":"string","pattern":"^[a-z0-9_-]+(,[a-z0-9_-]+)*$","description":"Intended-use tag ids, comma-separated, such as menu,trailer. Any-of."}},{"name":"instrument","in":"query","required":false,"description":"Instrument tag ids for music, comma-separated, such as piano,guitar. Any-of.","schema":{"type":"string","pattern":"^[a-z0-9_-]+(,[a-z0-9_-]+)*$","description":"Instrument tag ids for music, comma-separated, such as piano,guitar. Any-of."}},{"name":"sfx","in":"query","required":false,"description":"Sound-effect type tag ids, comma-separated, such as impact,door. Any-of.","schema":{"type":"string","pattern":"^[a-z0-9_-]+(,[a-z0-9_-]+)*$","description":"Sound-effect type tag ids, comma-separated, such as impact,door. Any-of."}},{"name":"credit","in":"query","required":false,"description":"optional keeps tracks that need no credit (\"No credit needed\" on the site). requested keeps tracks whose license requires credit or whose creator or source asks for it. Default: any.","schema":{"type":"string","enum":["any","optional","requested"],"description":"optional keeps tracks that need no credit (\"No credit needed\" on the site). requested keeps tracks whose license requires credit or whose creator or source asks for it. Default: any."}},{"name":"license","in":"query","required":false,"description":"License ids, comma-separated. A track matches if it has any of them. Ids: cc0, cc-by-3.0, cc-by-4.0, oga-by-3.0, oga-by-4.0, cc-by-sa-3.0, cc-by-sa-4.0, cc-by-nc-3.0, cc-by-nc-4.0, cc-by-nc-sa-3.0, cc-by-nc-sa-4.0.","schema":{"type":"string","pattern":"^(cc0|cc-by-3\\.0|cc-by-4\\.0|oga-by-3\\.0|oga-by-4\\.0|cc-by-sa-3\\.0|cc-by-sa-4\\.0|cc-by-nc-3\\.0|cc-by-nc-4\\.0|cc-by-nc-sa-3\\.0|cc-by-nc-sa-4\\.0)(,(cc0|cc-by-3\\.0|cc-by-4\\.0|oga-by-3\\.0|oga-by-4\\.0|cc-by-sa-3\\.0|cc-by-sa-4\\.0|cc-by-nc-3\\.0|cc-by-nc-4\\.0|cc-by-nc-sa-3\\.0|cc-by-nc-sa-4\\.0))*$","description":"License ids, comma-separated. A track matches if it has any of them. Ids: cc0, cc-by-3.0, cc-by-4.0, oga-by-3.0, oga-by-4.0, cc-by-sa-3.0, cc-by-sa-4.0, cc-by-nc-3.0, cc-by-nc-4.0, cc-by-nc-sa-3.0, cc-by-nc-sa-4.0."}},{"name":"commercial","in":"query","required":false,"description":"true keeps tracks the license lets you use commercially (\"Free for commercial use\" on the site). false keeps only non-commercial tracks. Default: both.","schema":{"type":"string","enum":["true","false"],"description":"true keeps tracks the license lets you use commercially (\"Free for commercial use\" on the site). false keeps only non-commercial tracks. Default: both."}},{"name":"share_alike","in":"query","required":false,"description":"false keeps tracks with no share-alike condition (\"No share-alike\" on the site). true keeps only share-alike tracks. Default: both.","schema":{"type":"string","enum":["true","false"],"description":"false keeps tracks with no share-alike condition (\"No share-alike\" on the site). true keeps only share-alike tracks. Default: both."}},{"name":"creator","in":"query","required":false,"description":"Artist name, matched without regard to case. Use the artist shown in earlier results.","schema":{"type":"string","minLength":1,"maxLength":200,"description":"Artist name, matched without regard to case. Use the artist shown in earlier results."}},{"name":"source","in":"query","required":false,"description":"Source domain, such as kenney.nl. Comma-separate several.","schema":{"type":"string","pattern":"^[^,\\s]+(,[^,\\s]+)*$","description":"Source domain, such as kenney.nl. Comma-separate several."}},{"name":"sort","in":"query","required":false,"description":"Order of results. Default: relevance when q is set, otherwise shuffle (a fixed order, so paging is stable).","schema":{"type":"string","enum":["shuffle","relevance","quality","short","long","slow","fast"],"description":"Order of results. Default: relevance when q is set, otherwise shuffle (a fixed order, so paging is stable)."}},{"name":"limit","in":"query","required":false,"description":"Number of tracks per page, from 1 to 50. Default: 20.","schema":{"type":"string","pattern":"^\\d+$","description":"Number of tracks per page, from 1 to 50. Default: 20."}},{"name":"cursor","in":"query","required":false,"description":"The cursor from the previous response, to get the next page.","schema":{"type":"string","pattern":"^\\d+$","description":"The cursor from the previous response, to get the next page."}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"$ref":"#/components/schemas/Track"}},"total":{"type":"number","description":"How many tracks match in all, across every page."},"cursor":{"description":"Pass as the cursor parameter to get the next page. null on the last page.","type":["string","null"]}},"required":["tracks","total","cursor"],"additionalProperties":false}}}},"400":{"description":"A parameter is not valid. The message names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_parameter","message":"The kind parameter must be one of music, sfx."}}}},"401":{"description":"The API key is missing, not valid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"That API key is not valid or has been revoked. Create a new key in the account menu under API keys."}}},"headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}}},"429":{"description":"Over your plan's limit. Free accounts get 20 calls per minute and 300 calls per day. Pro accounts get 60 calls per minute and 20,000 calls per month (UTC). MCP and the API share one allowance per account. The Retry-After header gives the seconds to wait, up to 86,400, and the limit and reset_at fields in the body name the limit you hit and when it resets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests. Try again in 12 seconds."}}},"headers":{"Retry-After":{"description":"Seconds to wait before the next call, at most 86,400.","schema":{"type":"integer","minimum":1}}}}}}},"/v1/tracks/{id}":{"get":{"operationId":"getTrack","summary":"Get one track","description":"Get one track by id.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The track id, such as fp-0000000001, from a search result.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Track"}}}},"400":{"description":"A parameter is not valid. The message names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_parameter","message":"The kind parameter must be one of music, sfx."}}}},"401":{"description":"The API key is missing, not valid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"That API key is not valid or has been revoked. Create a new key in the account menu under API keys."}}},"headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}}},"404":{"description":"No track has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"No track has the id fp-0000000000. Use /v1/search to find ids."}}}},"429":{"description":"Over your plan's limit. Free accounts get 20 calls per minute and 300 calls per day. Pro accounts get 60 calls per minute and 20,000 calls per month (UTC). MCP and the API share one allowance per account. The Retry-After header gives the seconds to wait, up to 86,400, and the limit and reset_at fields in the body name the limit you hit and when it resets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests. Try again in 12 seconds."}}},"headers":{"Retry-After":{"description":"Seconds to wait before the next call, at most 86,400.","schema":{"type":"integer","minimum":1}}}}}}},"/v1/tracks/{id}/similar":{"get":{"operationId":"findSimilarTracks","summary":"Find similar tracks","description":"Get precomputed neighbors of the same kind for a track, closest first.","tags":["Catalog"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The track id, such as fp-0000000001, from a search result.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Number of tracks per page, from 1 to 50. Default: 20.","schema":{"type":"string","pattern":"^\\d+$","description":"Number of tracks per page, from 1 to 50. Default: 20."}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"tracks":{"type":"array","items":{"$ref":"#/components/schemas/Track"}}},"required":["tracks"],"additionalProperties":false}}}},"400":{"description":"A parameter is not valid. The message names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_parameter","message":"The kind parameter must be one of music, sfx."}}}},"401":{"description":"The API key is missing, not valid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"That API key is not valid or has been revoked. Create a new key in the account menu under API keys."}}},"headers":{"WWW-Authenticate":{"description":"Always Bearer.","schema":{"type":"string"}}}},"404":{"description":"No track has that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"No track has the id fp-0000000000. Use /v1/search to find ids."}}}},"429":{"description":"Over your plan's limit. Free accounts get 20 calls per minute and 300 calls per day. Pro accounts get 60 calls per minute and 20,000 calls per month (UTC). MCP and the API share one allowance per account. The Retry-After header gives the seconds to wait, up to 86,400, and the limit and reset_at fields in the body name the limit you hit and when it resets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests. Try again in 12 seconds."}}},"headers":{"Retry-After":{"description":"Seconds to wait before the next call, at most 86,400.","schema":{"type":"integer","minimum":1}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key that starts with ue_. Create one in the account menu under API keys."}},"schemas":{"Track":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"artist":{"type":"string"},"kind":{"type":"string","enum":["music","sfx"]},"duration_s":{"type":"number"},"bpm":{"type":["number","null"]},"tags":{"type":"object","properties":{"genre":{"type":"array","items":{"type":"string"}},"mood":{"type":"array","items":{"type":"string"}},"use":{"type":"array","items":{"type":"string"}},"instrument":{"type":"array","items":{"type":"string"}},"sfx":{"type":"array","items":{"type":"string"}}},"required":["genre","mood","use","instrument","sfx"],"additionalProperties":false},"license":{"type":"object","properties":{"id":{"type":"string","description":"The license id, such as cc0 or cc-by-4.0."},"name":{"type":"string","description":"The license by name, such as CC BY 4.0."},"url":{"type":"string","description":"The license text."},"status":{"type":"string","enum":["verified","listed"],"description":"verified: we checked the source page. listed: the collection says so and we have not checked."}},"required":["id","name","url","status"],"additionalProperties":false},"terms":{"type":"object","properties":{"commercial":{"type":"boolean","description":"true when the license allows commercial use."},"credit":{"type":"string","enum":["none","required"],"description":"required when the license requires credit."},"share_alike":{"type":"boolean","description":"true when what you make with it must be shared under the same license."}},"required":["commercial","credit","share_alike"],"additionalProperties":false},"attribution":{"type":"string","enum":["optional","requested","required"]},"credit_line":{"type":"string"},"source_page":{"type":["string","null"]},"preview_url":{"type":["string","null"]},"page_url":{"type":"string"}},"required":["id","title","artist","kind","duration_s","bpm","tags","license","terms","attribution","credit_line","source_page","preview_url","page_url"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A short code: missing_api_key, invalid_api_key, invalid_parameter, not_found, rate_limited, method_not_allowed, or internal_error."},"message":{"type":"string","description":"What went wrong, in plain words."},"limit":{"description":"Only on rate_limited: which limit you hit.","type":"string","enum":["minute","day","month"]},"reset_at":{"description":"Only on rate_limited: when that limit resets, as an ISO 8601 UTC time.","type":"string"}},"required":["error","message"],"additionalProperties":false}}}}