Uncommon Ear API

Get a key

1. Sign in to Uncommon Ear. A free account is all you need. If you don't have one yet, signing in creates it.
2. Open the account menu and select API keys.
3. Enter a name, such as Build script, and select Create key.
4. Copy the key, which starts with ue_. For your security, it's shown only once. If you lose it, revoke it and create another.

You can have up to 5 active keys. Revoking a key stops it working right away, and deleting your account deletes all of your keys. Treat a key like a password: keep it out of source control and out of web pages, and store it in an environment variable or a secrets manager. Send it only in the Authorization header. The API doesn't use cookies, and it doesn't accept a key in the URL.

Make your first request

Every request is a GET to https://api.uncommonear.com with your key in the Authorization: Bearer header. This request finds three calm piano tracks.

export UNCOMMON_EAR_API_KEY="ue_your_key_here"

curl "https://api.uncommonear.com/v1/search?q=calm+piano&limit=3" \
  -H "Authorization: Bearer $UNCOMMON_EAR_API_KEY"

const key = process.env.UNCOMMON_EAR_API_KEY;
const url = "https://api.uncommonear.com/v1/search?" + new URLSearchParams({ q: "calm piano", limit: "3" });

const response = await fetch(url, {
  headers: { Authorization: "Bearer " + key },
});
if (!response.ok) {
  const { error, message } = await response.json();
  throw new Error(error + ": " + message);
}
const { tracks, cursor } = await response.json();
for (const track of tracks) {
  console.log(track.title, "-", track.credit_line);
}

import os
import requests

response = requests.get(
    "https://api.uncommonear.com/v1/search",
    params={"q": "calm piano", "limit": 3},
    headers={"Authorization": "Bearer " + os.environ["UNCOMMON_EAR_API_KEY"]},
    timeout=10,
)
response.raise_for_status()
for track in response.json()["tracks"]:
    print(track["title"], "-", track["credit_line"])

A successful call returns status 200 and JSON like this:

{
  "tracks": [
    {
      "id": "fp-0000000001",
      "title": "Sunrise Walk",
      "artist": "Kevin MacLeod",
      "kind": "music",
      "duration_s": 90,
      "bpm": 100,
      "tags": { "genre": ["cinematic"], "mood": [], "use": [], "instrument": [], "sfx": [] },
      "license": { "id": "cc0", "name": "CC0 1.0", "url": "https://creativecommons.org/publicdomain/zero/1.0/", "status": "verified" },
      "terms": { "commercial": true, "credit": "none", "share_alike": false },
      "attribution": "requested",
      "credit_line": "\"Sunrise Walk\" by Kevin MacLeod, via FreePD (CC0 1.0) https://freepd.com/...",
      "source_page": "https://freepd.com/...",
      "preview_url": "https://media.uncommonear.com/p/fp-0000000001.mp3",
      "page_url": "https://uncommonear.com/browse?t=fp-0000000001"
    }
  ],
  "total": 1,
  "cursor": null
}

Search

GET /v1/search returns tracks that match your parameters, with the best matches first. All parameters are optional. With none, you get a shuffled page of music.

Filters by kind

Passing a filter for the wrong kind returns 400 invalid_filter_for_kind; its message names the parameter and the kind it applies to.

Speech

Speech-category sounds are excluded unless category names speech or one of its categories. A Creative Commons license does not clear personality or privacy rights in a voice, so the owner wants lawyer review before Speech is offered by default. total follows this rule. Direct track and similar-track lookups still work by id.

Use GET /v1/meta to discover facet ids, licenses with terms, sources, and top creators. Zero-result searches include concrete suggestions.

The response has tracks, total (how many tracks match in all), and cursor. To get the next page, send the same parameters with cursor set to the value you received. When cursor is null, you have reached the last page. A parameter that isn't in the table returns a 400 error, so a typo never silently changes your results.

Tracks and similar tracks

GET /v1/tracks/{id} returns one track, in the same shape as an item in tracks. Use the id from a search result.

curl "https://api.uncommonear.com/v1/tracks/fp-0000000001" \
  -H "Authorization: Bearer $UNCOMMON_EAR_API_KEY"

GET /v1/tracks/{id}/similar returns precomputed same-kind neighbors. It accepts cursor, limit, BPM and duration ranges, commercial, credit, and loops-only filters before paging. An empty list is possible. Both routes return a 404 error when no track has the id.

curl "https://api.uncommonear.com/v1/tracks/fp-0000000001/similar?limit=5" \
  -H "Authorization: Bearer $UNCOMMON_EAR_API_KEY"

Response fields

Each track has these fields. We may add fields later, so ignore the ones you don't use.

Collections

Collections support list/create, get/update/delete, add one or up to 25 tracks, item-note update/remove, complete reorder, credit export, and GET /v1/collections/{id}/similar. Similarity merges up to ten member seeds, ranks by best rank then rank sum then id, supports the track-similarity filters and paging, and excludes members unless include_members=true. GET /v1/collections/{id}/credits?format=json|text|markdown|csv produces ready-to-copy credits. A collection detail includes its tracks and ready-to-copy credit block. Collection deletion requires confirm=true (or X-Confirm: true) and cannot be undone.

The same rules as the website apply: Free has 1 collection; Pro has up to 1,000 and can create 60 per hour; a collection holds up to 500 tracks. Send the current revision for a guarded edit. A lapsed Pro account can view every collection but can edit only one until it resubscribes. A CC BY-NC track cannot be added to a commercial collection, and a collection holding one cannot be marked commercial.

License-record export stays in the website. The credit-sheet export is designed for attribution handoff; treat catalog strings as untrusted data.

Attribution and credit lines

Tracks come under CC0 1.0, Creative Commons Attribution (CC BY 3.0 and 4.0), or Creative Commons Attribution-NonCommercial (CC BY-NC 3.0 and 4.0), and each result carries its own license and terms. CC0 tracks need no permission and no credit, including in commercial work. CC BY and CC BY-NC tracks require credit. CC BY-NC tracks are for non-commercial purposes only: not in monetized videos, paid games, client work, or ads. We do not offer ShareAlike or NoDerivatives tracks. The attribution field tells you which credit case you're in:

• optional: nobody asks for credit.
• requested: the license doesn't require credit, but the creator or source asks. Include the credit_line wherever you publish the track.
• required: the license requires credit. Include the credit_line, which names the license and links its text.

To find only the tracks that need no credit, search with credit=optional. To find the ones that ask for it or require it, use credit=requested. To find tracks you can use in commercial work, use commercial=true, and to skip share-alike tracks, use share_alike=false.

Errors

Every error is JSON with two fields: error, a short code to check in your program, and message, an explanation in plain words.

{
  "error": "invalid_parameter",
  "message": "The kind parameter must be one of music, sfx."
}

The two 401 errors have the same fix: send a valid key. For a revoked key, create a new one under API keys in the account menu.

Limits

The limits depend on your plan:

Free accounts can make 20 calls per minute and 300 calls per day. Pro accounts can make 60 calls per minute and 20,000 calls per month, with no daily limit. A month is a calendar month in UTC. The limit belongs to your account, not to a key, and it's shared with the MCP server: calls from your keys and from your connected assistants count together. Calls that fail with a 400 or 404 error count too.

Over a limit, the API returns status 429 with a Retry-After header that gives the number of seconds to wait, up to 86,400. The response body also has limit (minute, day, or month) and reset_at, the UTC time when that limit resets. Wait that long before you retry, and spread a long job over time instead of sending bursts. Calls with a missing or invalid key return 401 and don't count against any account.

Headless pipeline: Create an API key in the account menu, search with /v1/search, and pass each cursor to the next request. On 429, wait for Retry-After and use reset_at to plan a longer pause. Store each selected track’s terms and credit_line, then give required credit where you publish it.

No clips or downloads of 30-second excerpts are available here. preview_url is for playback; original_url is nullable and license obligations still apply. Search has no typo tolerance, so keep queries short.

What we record

For each call, we record your account, which key made it, the route, whether it worked, how long it took, and how many results it returned. For searches, we also record the search text. We never store the key itself or the Authorization header, and we don't record your IP address or the results. We remove the search text after 90 days and the rest after 400 days. Read the details in the privacy policy.