{"openapi":"3.1.0","info":{"title":"The Rights Foundry API","version":"1.0","description":"The Rights Foundry API gives you access to **100,000+ fully licensed music tracks** for app development and creative applications.\n\n## Getting Started\n\n1. **Get an API token** from your [dashboard](https://therightsfoundry.com/dashboard/token)\n2. **Add the token** to authenticated API requests as a Bearer token in the `Authorization` header\n3. **Find tracks** — filter by genre, mood, BPM and more, describe what you want in plain language, or match a reference recording by sound\n4. **Preview or stream audio** using the signed URLs returned in track responses\n5. **Building an agent?** The same catalog is available as an MCP connector at `https://mcp.therightsfoundry.com/mcp` — OAuth sign-in with your Rights Foundry account, no token handling in the agent\n\n## Every endpoint at a glance\n\n| Call | What it does | Charged at (`costs` key) | Audio it returns | License it grants |\n|---|---|---|---|---|\n| `GET /v1/tracks` | Browse, filter or text-search the catalog | `tracks_list` to browse; with nonempty `search`, page 1 at `tracks_search_first_page` and later pages at `tracks_search_next_page` | An MP3 preview link per track | Single-time stream, or use to preview a potential sync license |\n| `GET /v1/tracks/{id}` | One track with every alternate version (instrumental, acoustic, …) | `track_detail` | MP3 preview links for the track and each alternate | Single-time stream, or use to preview a potential sync license |\n| `POST /v1/tracks/deep-search` | **Deep Search** — describe what you want in plain language; get matching tracks | Page 1 at `deep_search_first_page`; later pages at `deep_search_next_page` (1 credit per page) | An MP3 preview link per track | Single-time stream, or use to preview a potential sync license |\n| `POST /v1/tracks/search` | **Acoustic Similarity Search** — give a public URL to a reference recording; get tracks that sound like it | Page 1 at `file_search_first_page`; later pages at `file_search_next_page` (1 credit per page) | An MP3 preview link per track | Single-time stream, or use to preview a potential sync license |\n| `POST /v1/tracks/{id}/sync` | A download link to the track's WAV master; a new window lasts 1 hour | `sync`, when the link is issued; asking again while the link is valid is free | A WAV master link | Allows one-time synchronization of the track(s) and use of the resulting content on online third-party platforms, without monetization |\n| `POST /v1/tracks/{id}/sync` with `{\"external_export\": true}` | **Export Sync** — the same WAV master link, for use offline or outside the platform; its own 1-hour window | `export_sync`, when the link is issued; asking again (with `external_export: true`) while it is valid is free | A WAV master link | Standard sync, plus use of the synced output or audio file offline, or placing / exporting / distributing it outside the platform |\n| `GET /v1/taxonomies` | The genres, moods, instruments and other values you can filter on | Free | — | — |\n| `GET /v1/credits` | Your balance, overdraft, credits about to expire, and the live rate card | Free | — | — |\n| `GET /v1/health` | Service status | Free | — | — |\n\nPreview links are signed and valid for 1 hour. The WAV master is only ever returned by `POST /v1/tracks/{id}/sync`. This page prints no prices on purpose, apart from the 1 credit charged for each later page of an AI search: the `costs` column names the key on the rate card that `GET /v1/credits` returns, and the operator can retune any rate without a new API version. Read the live values from there.\n\n## Which way the charge runs: sync vs stream\n\nAudio leaves this API by two routes, with opposite charging directions by design. Sync link issuance is billed today; stream charging is not yet active. This is deliberate, and it is the part of the pricing integrations most often get backwards, so it comes before everything else.\n\n| Audio | Getting the link | Moving the bytes |\n|---|---|---|\n| **WAV master** — `POST /v1/tracks/{id}/sync` | **Charged** at `sync` (or `export_sync` with `external_export: true`) for a new window; reissues within a paid window are free | **Free.** Download a link you hold as many times as you like, for as long as it is valid |\n| **MP3 preview** — `asset_url` on every catalog response | **Free.** It rides along with the listing, search or detail call you already paid for | **Intended to be charged per stream, from your API credits.** Streams are metered today but not yet charged; stream costs are a coming change |\n\n**Sync pays at issue, not at transfer.** Requesting a link for the same track again while the original is still valid is free (`credits_charged: 0`, `reissued: true`) and the replacement inherits the original expiry. The window is per account, track and mode — standard sync and Export Sync (`external_export: true`) each have their own. Concurrent first requests can both be charged before either records its link; serialize requests for the same track. Re-requesting does not extend access.\n\n**Stream reverses that direction by design: the link is free; playback is what is intended to be charged. Streams are not yet billed.**\n\n> **Where stream billing stands today — read this before you budget.**\n> Preview streams are already **metered**: the streaming host writes an Analytics Engine event for each successful asset request, recording the file, reported bytes served and country. Dashboard streaming reports depend on aggregation of those events. That usage is **not yet deducted from any balance**.\n>\n> **Stream costs are a documented coming change.** The planned behavior is to deduct preview streams from your API credit total, at a per-stream rate. It will not need a new API version. `GET /v1/credits` shows the stream cost as `costs.stream`; nothing deducts it yet. Budget for it now: treat every preview play as a metered event, do not auto-play previews nobody asked for, and do not build on the assumption that streaming stays free. As an interim measure, bandwidth is calculated through Cloudflare for every preview stream, against an allowance viewable as `bandwidth_bytes.spendable` through `GET /v1/credits`.\n\n## Authentication\n\nAll API calls, except health which is public, require a Bearer token. Signed asset URLs carry their own authorization — **do not submit a token** with them.\n\n```\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\nCharged calls use **API credits**. The rate card — which key prices which call — is in the **Credits** section below; the live values come from `GET /v1/credits`. Preview streams are metered but not yet charged — see *Which way the charge runs* above.\n\n## Your first call\n\nThree requests, no code. `curl` and a token are all you need.\n\n```bash\nexport RF_TOKEN=\"paste your token here\"\n\n# 1. Is the API up? No token needed, nothing charged.\ncurl https://api.therightsfoundry.com/v1/health\n\n# 2. Does my token work, and what can I spend? Free.\ncurl https://api.therightsfoundry.com/v1/credits \\\n  -H \"Authorization: Bearer $RF_TOKEN\"\n\n# 3. Five piano tracks with streaming previews. Charged at costs.tracks_list.\ncurl \"https://api.therightsfoundry.com/v1/tracks?instrument=piano&limit=5\" \\\n  -H \"Authorization: Bearer $RF_TOKEN\"\n```\n\nOpen any `asset_url` from step 3 in a browser or media player — it plays without a token. If step 2 answers `403`, the token is unknown, inactive, or expired; if step 3 answers `402`, top up from the dashboard. Every API response carries an `X-Request-Id` header — quote it if you contact support.\n\n## From brief to master, end to end\n\nThe whole integration in one script: budget, search, audition the preview, read the full record, get the WAV master. It spends one `deep_search_first_page`, one `track_detail` and one `sync` — and it reads all three from `GET /v1/credits` before it starts, so it never needs to know the numbers.\n\n```python\n# Python 3.9+. pip install requests. Export RF_TOKEN first.\nimport os\nimport requests\n\nBASE = \"https://api.therightsfoundry.com\"\nS = requests.Session()\nS.headers[\"Authorization\"] = f\"Bearer {os.environ['RF_TOKEN']}\"\n\n\ndef call(method, path, **kw):\n    r = S.request(method, BASE + path, timeout=60, **kw)\n    if r.status_code == 402:\n        raise SystemExit(f\"Out of credits: {r.json()}\")\n    if not r.ok:\n        raise SystemExit(f\"{r.status_code} {r.text} (X-Request-Id {r.headers.get('X-Request-Id')})\")\n    return r.json()\n\n\n# 1. Budget off the live rate card, not this page. Free call.\ncredits = call(\"GET\", \"/v1/credits\")\ncosts = credits[\"costs\"]\nneed = costs[\"deep_search_first_page\"] + costs[\"track_detail\"] + costs[\"sync\"]\nif credits[\"api_credits\"][\"spendable\"] < need:\n    raise SystemExit(f\"Need {need} credits, have {credits['api_credits']['spendable']} spendable\")\n\n# 2. Deep Search. Every page 1 is charged at deep_search_first_page, so ask for a big page once.\nhits = call(\"POST\", \"/v1/tracks/deep-search\",\n            json={\"query\": \"warm hopeful acoustic guitar for a nature documentary\", \"limit\": 50})\nif not hits[\"data\"]:\n    raise SystemExit(\"No matches — try a broader brief\")\npick = hits[\"data\"][0]\nprint(pick[\"id\"], pick[\"title\"], \"—\", pick[\"artist\"])\n\n# 3. Audition. The MP3 preview needs no token. Playing it is metered, not yet billed.\npreview = requests.get(pick[\"asset_url\"], timeout=60)\npreview.raise_for_status()\nopen(\"preview.mp3\", \"wb\").write(preview.content)\n\n# 4. Full record with alternative versions (instrumental and so on). Charged at costs.track_detail.\ntrack = call(\"GET\", f\"/v1/tracks/{pick['id']}\")[\"data\"]\nfor alt in track[\"child_tracks\"]:\n    print(\"  alt:\", alt[\"id\"], alt[\"title\"], alt[\"vocals\"])\n\n# 5. The WAV master. Charged at costs.sync when the link is issued; the download is free.\nlink = call(\"POST\", f\"/v1/tracks/{pick['id']}/sync\")[\"data\"]\nwav = requests.get(link[\"download_url\"], timeout=600)  # no Authorization header\nwav.raise_for_status()\nopen(link[\"file_name\"], \"wb\").write(wav.content)\nprint(f\"Saved {link['file_name']}; this call charged {link['credits_charged']} credits\")\n```\n\nListing and detail calls cost credits too (`tracks_list` and `track_detail`). `/v1/credits`, `/v1/taxonomies`, `/v1/health`, fetching signed URLs, and reissuing a still-valid sync link are free in credits.\n\n## Three Ways to Search\n\nThe catalog has three search modes. Pick the one that matches how you know what you want:\n\n- **Filter** — `GET /v1/tracks`. Deterministic filtering and browsing. Exact tag matches (genre, mood, instrument, theme), BPM and duration ranges, full-text search, field sorting, stable pagination. Use it when you know which fields to constrain — filter UIs, catalog exports, \"all piano tracks under 2 minutes\".\n- **Deep Search** — `POST /v1/tracks/deep-search`. Natural-language search. Describe what you want (\"warm hopeful acoustic guitar for a nature documentary\") and results come back in relevance order.\n- **Acoustic Similarity Search** — `POST /v1/tracks/search` with `file_url`. Point at a publicly reachable `.mp3` or `.wav` file and get catalog tracks that are acoustically similar to it — the provider fingerprints your audio and matches on the signal, not on metadata. Use it to match a reference track a client sent, or the temp track in an edit.\n\nBoth `POST` endpoints charge page 1 at their first-page rate every time it is sent; every later page of the same search costs 1 credit. Check `GET /v1/credits` for the first-page rates.\n\n## Two ways to get audio for different purposes\n\n- **Stream / preview** — If you wish to stream music, either as part of your application or as a preview for a potential sync, use the `asset_url` links returned by the `GET` and `POST /v1/tracks` calls. Streaming these URLs grants you a license for a single-time stream, or to preview a potential sync license.\n- **Sync** — If you wish to synchronize a track to a piece of video, use `POST /v1/tracks/{id}/sync`. This grants you a license for a one-time synchronization of the track and use of the resulting content on online third-party platforms, without monetization.\n- **Export Sync** — If the synchronized output or the audio file will be used **offline**, or **placed, exported or distributed outside** the platform (client delivery, broadcast, social media, offline playback), send `{\"external_export\": true}` to the same endpoint. It is charged at `export_sync` instead of `sync`.\n\n| Purpose | Call | Audio | License it grants |\n|---|---|---|---|\n| Stream or preview | `asset_url` from `GET /v1/tracks`, `GET /v1/tracks/{id}`, `POST /v1/tracks/deep-search`, `POST /v1/tracks/search` | MP3 preview | Single-time stream, or use to preview a potential sync license |\n| Sync to video | `POST /v1/tracks/{id}/sync` | WAV master | Allows one-time synchronization of the track(s) and use of the resulting content on online third-party platforms, without monetization |\n| Export Sync — offline or outside the platform | `POST /v1/tracks/{id}/sync` with `{\"external_export\": true}` | WAV master | Standard sync, plus use of the synced output or audio file offline, or placing / exporting / distributing it outside the platform |\n\n## Credits\n\nEvery charged call is priced by exactly one key on the rate card that `GET /v1/credits` returns under `costs`. This section names the keys; apart from the 1-credit rule for later pages of an AI search, it deliberately prints no numbers. The platform operator can retune any rate at any time without a new API version, so a figure printed here would be wrong the day after it changed. Read the live value from `GET /v1/credits` — it is free — and budget from that.\n\n| Operation | Condition | `costs` key |\n|---|---|---|\n| `GET /v1/tracks` | `search` absent or empty — browse or filter, any page | `tracks_list` |\n| `GET /v1/tracks` | With a nonempty `search`, `page` omitted or `1` | `tracks_search_first_page` |\n| `GET /v1/tracks` | With a nonempty `search`, `page` 2 or higher | `tracks_search_next_page` |\n| `GET /v1/tracks/{id}` | Track exists; includes all returned alternatives | `track_detail` |\n| `POST /v1/tracks/deep-search` — Deep Search | `page` omitted or `1` | `deep_search_first_page` |\n| `POST /v1/tracks/deep-search` — Deep Search | `page` 2 or higher — 1 credit per page | `deep_search_next_page` |\n| `POST /v1/tracks/search` — Acoustic Similarity Search | `page` omitted or `1` | `file_search_first_page` |\n| `POST /v1/tracks/search` — Acoustic Similarity Search | `page` 2 or higher — 1 credit per page | `file_search_next_page` |\n| `POST /v1/tracks/{id}/sync` | No body, or `external_export: false` — a link is issued (a repeat within a paid window is free) | `sync` |\n| `POST /v1/tracks/{id}/sync` | `{\"external_export\": true}` — an Export Sync link is issued (a repeat export within its paid window is free) | `export_sync` |\n| `GET /v1/taxonomies` | Every call | free |\n| `GET /v1/credits` | Every call | free, and not counted |\n| `GET /v1/health` | Every call | free, no token |\n| Playing a preview (`asset_url`) | Every stream | `stream` — published, **not yet charged**; see *Which way the charge runs* |\n| Fetching any other signed URL | Every fetch | free in credits |\n\nEvery search is charged at its first-page key each time page 1 is sent, cached or not; keep the search fixed and page through the result set. Later pages of either AI search (`deep_search_next_page`, `file_search_next_page`) cost 1 credit each. A sync link (standard or export) is charged when it is issued and never on the download. For every other rate, read `GET /v1/credits`.\n\n## Checking Your Balance\n\n`GET /v1/credits` tells you how many credits you have left, how much bandwidth allowance remains (recorded, not yet deducted — see *Which way the charge runs*), which credits expire next, and what each operation currently costs. **It is free and uncounted**, so you can check it before a charged call rather than discovering a shortfall as a `402` halfway through a batch:\n\n```\ncurl https://api.therightsfoundry.com/v1/credits -H \"Authorization: Bearer YOUR_API_TOKEN\"\n```\n\nYour API credit balance may go negative within `api_credits.overdraft_limit`, your account's own tolerance: it depends on your monthly plan, and an account without a plan may have none. Billing also refuses a charged call if the existing bandwidth balance is below its own overdraft floor, even though catalog calls deduct no bandwidth. Top-ups reduce any debt; the balance becomes nonnegative once enough is added. Budget against `api_credits.spendable` (`balance + overdraft_limit`), which already includes that tolerance.\n\nBalances are **per account**. Every token on the account draws down the same pool; the call and API response-data counters are per token.\n\n## Rate Limits & Usage\n\n- Successful catalog calls and their JSON response sizes are tracked per token per month, including free sync reissues. Counters reset lazily on the first authenticated request of each UTC month and are returned by `GET /v1/credits` under `token`; cached records and asynchronous updates can lag. `bandwidth_month_bytes` counts API response data, not streamed audio, and does not deduct from the bandwidth allowance.\n- **MCP connections** carry a daily cap (currently 1,000 calls per UTC day, returned as `token.daily_call_limit`). Once the cap is detected, authenticated endpoints answer `429` with a `Retry-After` header holding the seconds until 00:00 UTC (at least 60). `GET /v1/credits` and `GET /v1/taxonomies` do not count toward the cap but are refused like everything else once it is reached. Topping up does not reset it. **Dashboard-issued API keys have no cap.**\n- View your usage on the [dashboard](https://therightsfoundry.com/dashboard).\n\n## Errors\n\nErrors on catalog and credits endpoints are JSON — `{\"success\": false, \"error\": \"<message>\"}` — and the status tells you what to do. Every API response, error or not, carries an `X-Request-Id` header; quote it when you contact support.\n\n| Status | Meaning | Charged? | What to do |\n|---|---|---|---|\n| `400` | Bad parameter or body; `error` names it | No — except Acoustic Similarity Search's \"Could not download or decode\" case, charged at `file_search_first_page` or `file_search_next_page` | Fix the request. |\n| `401` | No `Authorization: Bearer …` header | No | Add the header. A wrong token is `403`, not `401`. |\n| `402` | The API cost would exceed its overdraft floor, or bandwidth is already below its floor; body carries `apiCredits` and `bandwidthBytes` | No | Top up from the dashboard, then retry. `GET /v1/credits` still works. |\n| `403` | Token unknown, revoked or expired | No | Issue a new token from the dashboard; for an MCP connection, reconnect. |\n| `404` | No such track, no available WAV master, or a missing account on a database balance read | No | Confirm the ID with `GET /v1/tracks?id=…&includeChildren=true`. |\n| `405` | `GET` on a `POST`-only search or sync endpoint | No | Use `POST`. |\n| `429` | Daily cap on an MCP connection | No | Wait `Retry-After` seconds. |\n| `500` | Failure on our side | Any recorded charge gets an asynchronous, best-effort refund | Retry once; keep the `X-Request-Id`. |\n| `503` | Search provider down (`Search is temporarily unavailable…`) or billing down (`Billing is temporarily unavailable…`, `Retry-After: 5`) | Search failure: best-effort refund. Billing failure: deduction unconfirmed | Honor `Retry-After` when present; retries use the normal rate. |\n\nErrors from signed asset URLs are plain text, not JSON — see Signed URLs. An unhealthy `/v1/health` returns `503` with a health-status body, not the `Error` schema; it is free and unauthenticated.\n\n## Signed URLs\n\nAudio preview URLs (`asset_url`), waveform data URLs (`peak_data_url`) and newly issued sync master URLs (`download_url`) are HMAC-signed with a **1-hour** lifetime. A free sync reissue inherits the original expiry, so it can have less than an hour remaining. The `expires` query parameter is the Unix expiry in seconds, so you can check it before fetching.\n\n- **No token.** The signature is the authorization. Send no `Authorization` header — the streaming host is a different origin from the API and the header would only leak your token.\n- **Range requests work.** The host answers `Accept-Ranges: bytes` and `206 Partial Content`, so `<audio>` elements and players can seek without downloading the whole file. Both `bytes=start-end` and open-ended `bytes=start-` are served with the correct length. Responses are `Cache-Control: private, no-store`.\n- **Errors are plain text, not JSON.** `403 URL has expired` — request the track again for a fresh URL. `403 Invalid signature` — the URL was altered; use it exactly as returned. `400 Missing signature parameters` — same cause. `404 File not found` — the asset is missing; do not retry, report the track ID.\n- **Store track IDs, not URLs.** Every API response signs afresh — even a cached listing comes back with new signatures — but JSON you store keeps its old URLs. Keep the `id` and re-fetch when you need a live link: `GET /v1/tracks?id=…` (charged at `tracks_list`) or `GET /v1/tracks/{id}` (charged at `track_detail`). A WAV link is refreshed through `POST /v1/tracks/{id}/sync`, free while the original is still valid.\n- **Browsers.** The API allows cross-origin requests, but your API token is a secret. Call the API from your server and hand the browser only the signed URLs.\n\n`asset_url` is the **MP3 preview** and rides along with every track at no cost beyond the call that returned it. Playing it is the other side of the ledger: every stream is metered, and stream costs are a documented coming change — see *Which way the charge runs*. The **WAV master** is never returned on a catalog response — it comes only from `POST /v1/tracks/{id}/sync`.\n","contact":{"name":"The Rights Foundry","email":"contact@therightsfoundry.com","url":"https://therightsfoundry.com"}},"servers":[{"url":"https://api.therightsfoundry.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Your API token, issued from the [dashboard](https://therightsfoundry.com/dashboard/token). 128 hexadecimal characters; dashboard keys do not expire and are revoked from the same page. Send it on every request:\n\n`Authorization: Bearer abc123...`\n\nKeep it server-side — see Signed URLs for how to give a browser playable audio without the token.\n"}},"schemas":{"Track":{"type":"object","properties":{"id":{"type":"integer","description":"Unique track identifier (client_id)","example":29446060},"title":{"type":"string","example":"Forever Yours"},"artist":{"type":"string","example":"Dominik Hauser"},"performed_by":{"type":"string","example":"Dominik Hauser"},"album":{"type":"string","example":"Cinematic Themes Vol. 3"},"duration":{"type":"number","format":"float","description":"Duration in seconds. Fractional on almost every track — round it yourself for display. `durationMin` / `durationMax` compare against this value.","example":243.4},"term_matches":{"type":"integer","description":"Only when `search` was given. How many of the query's terms this track matched. The list is ordered by this first, so a drop in the value marks the end of the fully-matching block.","example":3},"bpm":{"type":"integer","description":"Editorial beats per minute. `0` means unknown; prefer `bpm_detected` when it is present. `bpmMin` / `bpmMax` filter on `bpm_detected` where it exists and fall back to this editorial value, so the filter always matches the tempo the response shows.","example":120},"musical_key":{"type":"string","example":"C Major"},"decades":{"type":["string","null"],"description":"Decade the production style belongs to, e.g. `2010s`. `null` on a handful of tracks. Filter with `decade`.","example":"2020s"},"vocals":{"type":["string","null"],"description":"Editorial vocal type, lowercase. One of `instrumental`, `male`, `female`, `duet`, `choir`, `background`, `a cappella`. Use the `vocals` filter for an enforced constraint; the `search` parameter also understands `instrumental`, `no vocals`, `vocals`, `male vocals` and `female vocals`.\n","example":"instrumental"},"explicit":{"type":"boolean","example":false},"first_published":{"type":["string","null"],"format":"date-time","example":"2024-01-15T00:00:00Z"},"release_date":{"type":["string","null"],"format":"date-time"},"asset_url":{"type":["string","null"],"description":"HMAC-signed MP3 preview URL, valid for 1 hour. Obtaining it costs nothing beyond the call that returned the track. Playing it is metered per stream — recorded today, not yet deducted from any balance; stream costs (`costs.stream`) are a documented coming change. See *Which way the charge runs* in the API overview.\n","example":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.mp3?expires=1774530330&sig=abc..."},"peak_data_url":{"type":["string","null"],"description":"HMAC-signed waveform data URL (expires in 1 hour)"},"genres":{"type":"array","items":{"type":"string"},"example":["cinematic","orchestral"]},"sub_genres":{"type":"array","items":{"type":"string"},"example":["film score"]},"moods":{"type":"array","items":{"type":"string"},"example":["epic","uplifting"]},"instruments":{"type":"array","items":{"type":"string"},"example":["orchestra","strings"]},"sub_instruments":{"type":"array","items":{"type":"string"}},"themes":{"type":"array","items":{"type":"string"},"example":["adventure","triumph"]},"sub_themes":{"type":"array","items":{"type":"string"}},"main_genre":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed primary genre(s).","example":["cinematic"]},"subgenre":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed sub-genre(s).","example":["film score"]},"free_genre":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed free-form genre labels — a wider, less controlled vocabulary than `main_genre`."},"mood_simple":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed mood, coarse vocabulary.","example":["epic"]},"mood_advanced":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed mood, fine-grained vocabulary.","example":["triumphant","sweeping"]},"character":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed character/production descriptors.","example":["orchestral","cinematic"]},"movement":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed sense of motion — how the track develops over time.","example":["building"]},"instruments_detected":{"type":["array","null"],"items":{"type":"string"},"description":"Instruments heard in the audio, as distinct from the editorial `instruments` tags.","example":["strings","brass","timpani"]},"music_for":{"type":["array","null"],"items":{"type":"string"},"description":"What the track suits — the analyzed counterpart to the editorial `themes`. Also matched by the `theme` query filter.","example":["documentary","trailer"]},"vocals_detected":{"type":["array","null"],"items":{"type":"string"},"description":"Vocal content heard in the audio.","example":["instrumental"]},"vocal_style":{"type":["array","null"],"items":{"type":"string"},"description":"Analyzed vocal style.","example":["instrumental"]},"vocal_presence":{"type":["string","null"],"description":"How prominent the vocal is in the mix."},"vocal_gender":{"type":["string","null"],"description":"Analyzed vocal gender."},"voiceover_degree":{"type":["number","null"],"format":"float","description":"How strongly the track is shaped for voiceover (0–1).","example":0.82},"voiceover_dominant":{"type":["boolean","null"],"description":"Whether the track reads primarily as a voiceover bed."},"bpm_detected":{"type":["integer","null"],"description":"Tempo measured from the audio. May differ from the editorial `bpm`.","example":118},"bpm_confidence":{"type":["number","null"],"format":"float","description":"Confidence in `bpm_detected` (0–1).","example":0.94},"key":{"type":["string","null"],"description":"Key detected from the audio. May differ from the editorial `musical_key`.","example":"C major"},"key_confidence":{"type":["number","null"],"format":"float","description":"Confidence in `key` (0–1)."},"tempo":{"type":["string","null"],"description":"Tempo as a descriptive band rather than a number.","example":"medium"},"time_signature":{"type":["string","null"],"example":"4/4"},"valence":{"type":["number","null"],"format":"float","description":"Musical positivity (0–1). Low is somber, high is bright.","example":0.71},"arousal":{"type":["number","null"],"format":"float","description":"Energy/intensity (0–1). Low is calm, high is agitated.","example":0.63},"energy_level":{"type":["string","null"],"description":"Energy as a descriptive band.","example":"high"},"emotion_profile":{"type":["string","null"],"description":"Dominant emotional profile."},"musical_era":{"type":["string","null"],"description":"Era the production style evokes.","example":"2010s"},"production_year":{"type":["integer","null"],"description":"Estimated production year.","example":2021},"auto_description":{"type":["string","null"],"description":"Generated prose description of the track. Also indexed by the `search` parameter.","example":"Sweeping orchestral cue with soaring strings and driving percussion."},"is_ai_music":{"type":["boolean","null"],"description":"Whether the recording is judged to be AI-generated.","example":false},"ai_music_score":{"type":["number","null"],"format":"float","description":"Confidence behind `is_ai_music` (0–1)."},"tag_source":{"type":["string","null"],"enum":["direct","parent",null],"description":"Where the analysis fields came from: `direct` means this recording was\nanalyzed itself, `parent` means it inherited its parent track's analysis\n(typical for alternative versions). `null` means the track has no analysis.\n","example":"direct"},"tagged_at":{"type":["string","null"],"format":"date-time","description":"When the analysis was produced."},"has_alternatives":{"type":"boolean","description":"Whether this track has alternative versions (instrumental, acoustic, etc.)","example":true}}},"TrackWithChildren":{"allOf":[{"$ref":"#/components/schemas/Track"},{"type":"object","properties":{"child_tracks":{"type":"array","description":"Alternative versions of this track (instrumental, acoustic, etc.)","items":{"$ref":"#/components/schemas/Track"}}}}]},"PaginatedTracks":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Track"}},"total":{"type":"integer","description":"Tracks matching this request across all pages. Without `search` that is every track the filters admit. With `search` it counts only the coverage levels the response actually pages through — terms are OR-ed, so the tracks matching just one term of a five-term query are not all included; the levels needed to fill the first 100 rows are. It is stable across pages of the same query. `coverage.levels` gives the per-level counts if you need the full distribution.","example":2211},"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"limit":{"type":"integer","description":"Tracks per page","example":20},"matched":{"type":"array","description":"Only when `search` was given. Query terms recognized as catalog vocabulary and the facet/value they matched. A term can match several facets.","items":{"type":"object","properties":{"term":{"type":"string","example":"hip hop"},"field":{"type":"string","example":"genre","enum":["genre","mood","theme","instrument","character","movement","vocals","tempo","energy","era","decade","key"]},"value":{"type":"string","example":"hip hop"},"partial":{"type":"boolean","description":"Present and `true` when the term matched only as part of a longer tag (`guitar` via `acoustic guitar`). Absent on exact matches.","example":true}}}},"unmatched_terms":{"type":"array","description":"Only when `search` was given. Words that matched no vocabulary and were sent to full-text search.","items":{"type":"string"},"example":["ominous"]},"corrections":{"type":"array","description":"Only when `search` was given. Spelling substitutions applied before matching; empty when nothing was corrected.","items":{"type":"object","properties":{"from":{"type":"string","example":"acoustc"},"to":{"type":"string","example":"acoustic"}}}},"relaxed":{"type":"boolean","description":"Only when `search` was given. `true` when no track matched every term — i.e. `coverage.levels` has no entry whose `matched` equals `coverage.terms`. Results are still returned and still ranked; this only says the best block is a partial match. A word that matches no vocabulary and no track's text is a term like any other, so a single unrecognized word is enough to make this `true`.","example":false},"coverage":{"type":"object","description":"Only when `search` was given. Terms are OR-ed, not AND-ed, and ranked by how many of them each track matches. `levels` is the whole distribution, best-covered first, so you can see where the fully matching tracks end and the near misses begin.","properties":{"terms":{"type":"integer","description":"How many terms the query produced after vocabulary matching.","example":3},"levels":{"type":"array","description":"One entry per coverage level present, ordered by `matched` descending.","items":{"type":"object","properties":{"matched":{"type":"integer","description":"Number of terms matched.","example":3},"rows":{"type":"integer","description":"Tracks matching exactly that many.","example":12}}}}}},"ignored_terms":{"type":"array","description":"Recognized vocabulary terms that were dropped because the query exceeded the eight-term cap. Unlike `unmatched_terms` these WERE understood — they just did not take part in ranking. Absent when nothing was dropped.","items":{"type":"string"}},"hint":{"type":"string","enum":["reference"],"description":"Present when the query named a reference recording (\"sounds like X\", \"X style\") rather than describing a sound. The lexical index cannot match a recording — describe the music instead, or use `POST /v1/tracks/search` with a `file_url`."},"constraints":{"type":"object","description":"Present whenever a hard constraint was applied, from a parameter or from words in `search`. Hard constraints are never relaxed: a track that violates one is never returned, including on a `relaxed: true` page.","properties":{"vocals":{"type":"string","enum":["instrumental","male","female","any"]},"key":{"type":"string","description":"The key as asked for; enharmonic spellings were matched with it.","example":"A minor"},"bpm":{"type":"array","description":"The BPM window that was enforced, as `[min, max]`. A `120 bpm` in the query text becomes a ±5 window.","items":{"type":"integer"},"example":[115,125]},"duration":{"type":"object","description":"The duration window that was enforced, in seconds.","properties":{"min":{"type":"number"},"max":{"type":"number"},"widened":{"type":"boolean","description":"`true` when the requested window was narrower than four seconds and was widened to the midpoint ±2. `duration` is fractional, so `durationMin=30&durationMax=30` would otherwise match almost nothing."}}},"empty_because":{"type":"array","description":"Only when the page is empty, and it comes in two forms.\nNormally: for each constraint, how many tracks would have matched if that one constraint were dropped and every other kept (`rows_without`), highest first — the constraint at the top is the one to loosen. Constraints that exclude nothing on their own are omitted.\nWhen no single constraint can be dropped to return rows — several stacked constraints that are each satisfiable but not together — every constraint is listed instead, each with `rows_with`: how many tracks it admits **on its own**, ignoring the others. The order is rarest first, so the entry at the top is the constraint to give ground on, and a `rows_with` of 0 names one that no track in the catalog satisfies at all. `rows_without` is 0 on every entry in this form — that is what distinguishes it.","items":{"type":"object","properties":{"constraint":{"type":"string","description":"`search` means the query text itself is what emptied the page, not any filter.","enum":["search","genre","mood","instrument","theme","vocals","key","bpm","duration"]},"rows_without":{"type":"integer","example":412},"rows_with":{"type":"integer","example":141,"description":"Only in the second form. Tracks matching this constraint alone."}}}}}}}},"Taxonomies":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"One array per facet, ordered by count descending. Every value is recognized by the `search` parameter (which may also match longer tags containing it); `genre`, `mood`, `instrument` and `theme` values double as exact filters on `GET /v1/tracks`.","additionalProperties":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","example":"hip hop"},"count":{"type":"integer","description":"Tracks carrying this value (editorial and analyzed tags combined)","example":9570}}}},"example":{"genre":[{"value":"rock","count":21000},{"value":"hip hop","count":9570}],"mood":[{"value":"confident","count":15400}],"theme":[{"value":"study","count":22000},{"value":"road trip","count":20134}],"instrument":[{"value":"percussion","count":45000}],"tempo":[{"value":"medium slow","count":17000}]}}}},"CreditBalance":{"type":"object","description":"Body of `GET /v1/credits` — the account's balances, the batches that expire next, the per-token counters, and `costs`, the only place a price is stated. `api_credits.balance` can be negative; `spendable` is `balance + overdraft_limit`.\n","properties":{"success":{"type":"boolean","example":true},"as_of":{"type":"string","format":"date-time","description":"When this balance was read.","example":"2026-09-09T11:42:07.115Z"},"balance_source":{"type":"string","enum":["live","database"],"description":"`live` — read from the counter that serves your requests, so it includes deductions made moments ago.\n`database` — read from the persisted balance, which can lag the live counter by a few seconds. Used when the live read fails or the live-counter binding is absent.\n","example":"live"},"api_credits":{"type":"object","description":"API credits, the unit every charged endpoint is priced in.","properties":{"balance":{"type":"integer","description":"Credits remaining. **Can be negative** — see `overdraft_limit`.","example":1250},"overdraft_limit":{"type":"integer","description":"Allowed API credit debt before a charged request is refused with `402`. Your account's own figure, set by your monthly plan; an account without a plan may have none.","example":10},"spendable":{"type":"integer","description":"`balance + overdraft_limit` — what you can still spend before the next `402`.","example":1260}}},"bandwidth_bytes":{"type":"object","description":"Streaming bandwidth allowance, in bytes. **Today, stream transfers do not deduct from it.** Catalog endpoints deduct no bandwidth, and the streaming host serves signed URLs without checking or decrementing this balance. Charged API calls still check whether the existing bandwidth balance is below its overdraft floor. Streaming *is* metered through Analytics Engine events recording the file, reported bytes served and country; dashboard reports depend on event aggregation.\n\n**Interim measure.** This allowance stands in until stream costs arrive; the planned behavior is to charge each preview stream against API credits at `costs.stream`, without a new API version. See *Which way the charge runs* in the API overview.\n","properties":{"balance":{"type":"integer","format":"int64","example":5368709120},"overdraft_limit":{"type":"integer","format":"int64","example":0},"spendable":{"type":"integer","format":"int64","example":5368709120}}},"expiring_credits":{"type":"array","description":"Unexpired batches that still hold API credits or bandwidth, soonest expiry first, at most 20. Batches that never expire are not listed. Batch deductions are applied soonest-expiry-first, with nonexpiring batches last. A batch can appear here for its bandwidth alone. This list is not a guarantee of which batch the next call consumes: it omits expired batches even if their expiry cleanup is pending. Values come from the batch ledger, which trails the live balance by a few seconds, and the array is also empty if the ledger lookup fails — so do not sum these to reconstruct `balance`.\n","items":{"type":"object","properties":{"api_credits":{"type":"integer","example":500},"bandwidth_bytes":{"type":"integer","format":"int64","example":0},"expires_at":{"type":"string","format":"date-time","example":"2026-10-01T00:00:00.000Z"}}}},"costs":{"type":"object","description":"**Your** rate card — what each call costs this account right now, including any plan discount (see `discounts`). These are the prices the endpoints in this document charge you, and the **only place a price is stated**. Each key is named after the call it prices; the condition is in each key's description. The example values on this page are illustrative and may not match what your account is charged today: read the live response.\n","properties":{"tracks_list":{"type":"integer","description":"`GET /v1/tracks` with `search` absent or empty — every page, any filters.","example":1},"tracks_search_first_page":{"type":"integer","description":"`GET /v1/tracks` with nonempty `search`, `page` omitted or `1`.","example":2},"tracks_search_next_page":{"type":"integer","description":"`GET /v1/tracks` with nonempty `search`, `page` 2 or higher.","example":1},"track_detail":{"type":"integer","description":"`GET /v1/tracks/{id}` — every successful call, however many `child_tracks` come back.","example":5},"deep_search_first_page":{"type":"integer","description":"`POST /v1/tracks/deep-search` (Deep Search), `page` omitted or `1` — charged every time page 1 is sent, cached or not.","example":10},"deep_search_next_page":{"type":"integer","description":"`POST /v1/tracks/deep-search` (Deep Search), `page` 2 or higher, even if `query` or `instrumental` changed. 1 credit per page.","example":1},"file_search_first_page":{"type":"integer","description":"`POST /v1/tracks/search` (Acoustic Similarity Search), `page` omitted or `1` — charged every time page 1 is sent, cached or not.","example":15},"file_search_next_page":{"type":"integer","description":"`POST /v1/tracks/search` (Acoustic Similarity Search), `page` 2 or higher, even if `file_url` or `instrumental` changed. 1 credit per page.","example":1},"sync":{"type":"integer","description":"`POST /v1/tracks/{id}/sync` (no body, or `external_export: false`) — per new access window, never on the download. A repeat request while a valid link exists is free.","example":200},"export_sync":{"type":"integer","description":"Credits per POST /v1/tracks/{id}/sync with external_export: true (offline use or placing outside; free reissue while the export link is live)","example":200},"stream":{"type":"integer","description":"One play of a preview `asset_url`. **Published, not yet charged** — nothing deducts it today. Stream costs are a documented coming change; see *Which way the charge runs* in the API overview.","example":0}}},"standard_costs":{"type":"object","description":"The standard rate card before any plan discount, with the same keys as `costs`. Equal to `costs` when no discount applies.\n","properties":{"sync":{"type":"integer","description":"Standard rate for `POST /v1/tracks/{id}/sync` (no body, or `external_export: false`).","example":200},"export_sync":{"type":"integer","description":"Credits per POST /v1/tracks/{id}/sync with external_export: true (offline use or placing outside; free reissue while the export link is live)","example":200}},"additionalProperties":{"type":"integer"}},"discounts":{"type":"object","description":"One entry per `costs` key that is currently below its standard rate, keyed like `costs`; empty when no discount applies. A top-up plan can carry discounted rates for some calls. They apply while you hold unexpired credits bought with that plan. When those credits run out or expire, the call returns to its standard rate. If several of your plans discount the same call, the lowest price applies.\n","additionalProperties":{"type":"object","properties":{"standard":{"type":"integer","description":"The standard rate for this call (as in `standard_costs`)."},"plan_id":{"type":"integer","description":"The plan whose discount sets the price."},"plan":{"type":"string","description":"That plan's name."}}}},"subscription":{"type":["object","null"],"description":"Your monthly plan, if you have one. Its rates set your base price for each call (in `costs` and `standard_costs`); a top-up discount can only lower them further. `null` without a plan. Unused plan credits roll over month to month.\n","properties":{"plan_id":{"type":"integer"},"plan":{"type":"string","description":"The plan's name."}}},"token":{"type":"object","description":"The token this request authenticated with. Balances are per account; these counters are per token.","properties":{"name":{"type":"string","example":"Production key"},"public_code":{"type":"string","description":"Short public identifier for the token — safe to log, unlike the token itself.","example":"AB12"},"api_calls_month":{"type":"integer","description":"Successful catalog calls recorded for this token, including free sync reissues. Resets lazily on the first authenticated request of a new UTC month; cached records and asynchronous updates can lag.","example":4821},"bandwidth_month_bytes":{"type":"integer","format":"int64","description":"API response-data counter accumulated from serialized JSON response lengths, not streamed audio bytes. Resets with `api_calls_month` and can lag. It does not deduct from `bandwidth_bytes`.","example":91234567},"month_reset_at":{"type":"string","format":"date-time","description":"When the monthly counters were last zeroed. The reset is lazy — it happens on the first request of a new UTC month — so this is the time of that request, not midnight on the 1st.","example":"2026-09-01T00:00:04.221Z"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expiry for MCP connections; `null` for dashboard-issued API keys, which do not expire.","example":null},"daily_call_limit":{"type":["integer","null"],"description":"Per-day call cap on this token, or `null` for uncapped.","example":null}}}}},"DeepSearchResults":{"type":"object","description":"Relevance-ordered results from `POST /v1/tracks/deep-search`.","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","description":"Matching tracks, best match first. Same shape as `GET /v1/tracks` results, including signed streaming URLs.","items":{"$ref":"#/components/schemas/Track"}},"total":{"type":"integer","description":"Size of the candidate set, not a catalog-wide count. The search provider returns at most 1,000 candidates per search; after dropping any that are not in this catalog, `total` is what remains, and every page is a slice of it. Expect `total` ≤ 1000 even for a broad brief.","example":148},"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"limit":{"type":"integer","description":"Tracks per page","example":20}}},"SearchResults":{"type":"object","description":"Relevance-ordered results from `POST /v1/tracks/search` (Acoustic Similarity Search).","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","description":"Matching tracks, best match first. Same shape as `GET /v1/tracks` results, including signed streaming URLs.","items":{"$ref":"#/components/schemas/Track"}},"total":{"type":"integer","description":"Size of the candidate set, not a catalog-wide count. The search provider returns at most 1,000 candidates per search; after dropping any that are not in this catalog, `total` is what remains, and every page is a slice of it. Expect `total` ≤ 1000 even for a broad brief.","example":148},"page":{"type":"integer","description":"Current page number (1-indexed)","example":1},"limit":{"type":"integer","description":"Tracks per page","example":20},"did_you_mean":{"deprecated":true,"type":"array","description":"**Always `[]`.** Acoustic Similarity Search has no text query to interpret. Retained so existing clients that read this field keep working; do not build on it.\n","items":{"type":"string"},"example":[]},"search_type":{"deprecated":true,"type":["string","null"],"description":"**Always `null`.** Acoustic Similarity Search has no query-routing strategy to report. Retained so existing clients that read this field keep working; do not build on it.\n","example":null}}},"SyncLink":{"type":"object","description":"A signed link to a track's WAV master. A new access window is charged at `sync`\n(or `export_sync` when issued with `external_export: true`) when the link is\nissued; a reissue within a paid window of the same mode is free and inherits\nits expiry. Fetching `download_url` is never charged.\n","required":["id","title","artist","format","file_name","download_url","expires_at","expires_in","credits_charged","reissued","external_export","billing"],"properties":{"id":{"type":"integer","description":"Track ID (client_id)","example":29446060},"title":{"type":"string","example":"Golden Hour"},"artist":{"type":["string","null"],"example":"Marta Vellum"},"format":{"type":"string","description":"Always `wav` — this endpoint serves masters, not previews.","example":"wav"},"file_name":{"type":"string","description":"Suggested filename for the saved download.","example":"29446060_track.wav"},"download_url":{"type":"string","format":"uri","description":"HMAC-signed URL to the WAV master, valid until `expires_at`. Fetching\nit is free — never charged in credits, no bandwidth deducted; it\ncarries its own authorization, so no `Authorization` header is\nneeded (and none should be sent).\n","example":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.wav?expires=1774530330&sig=abc..."},"expires_at":{"type":"string","format":"date-time","description":"When `download_url` stops working.","example":"2026-09-08T21:45:30.000Z"},"expires_in":{"type":"integer","description":"Seconds remaining on the link at the moment of the response.","example":3600},"credits_charged":{"type":"integer","description":"Credits deducted by this call at the `sync` rate (or `export_sync` with `external_export: true`), or `credits_charged: 0` for a free reissue.","example":200},"reissued":{"type":"boolean","description":"`true` when a still-valid charged link already existed for this account, track and\nmode, so this call returned a replacement free of charge and did not extend the expiry.\n","example":false},"external_export":{"type":"boolean","description":"Which licence the link was issued under. `false`: standard sync, charged at `sync`.\n`true`: Export Sync — use of the synced output or audio file offline, or placing /\nexporting / distributing it outside the platform — charged at `export_sync`. Echoes the\nrequest (`false` when the body was empty). Each mode has its own reissue window.\n","example":false},"billing":{"type":"object","description":"The billing rule, restated in the payload so integrations can surface it.","properties":{"charged_on":{"type":"string","enum":["api_call"],"description":"Always `api_call` — never on the file transfer.","example":"api_call"},"note":{"type":"string"}}}}},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Invalid API token"},"message":{"type":"string","description":"Detail of a request-body validation failure, where the route gives one (for example `POST /v1/tracks/{id}/sync`, whose `error` is then `Bad Request`)."}}},"InsufficientCredits":{"type":"object","description":"Body of every catalog `402`. The balances are the account's current values before the rejected deduction. Billing checks both overdraft floors, even though catalog calls deduct no bandwidth. Compare with the rates and overdraft limits from `GET /v1/credits` to determine the shortfall.","required":["success","error","apiCredits","bandwidthBytes"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Insufficient credits. Please top up to continue."},"apiCredits":{"type":"integer","description":"Current API credit balance. Can be negative inside the overdraft.","example":-8},"bandwidthBytes":{"type":"integer","format":"int64","example":5368709120}}}},"responses":{"Unauthorized":{"description":"No `Authorization` header, one that does not start with `Bearer `, or an empty bearer token. Nothing is charged. Add the header — a wrong or revoked token is a `403`, not a `401`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Missing authorization header"}}}},"Forbidden":{"description":"The header was well-formed but the token cannot be used. Nothing is charged. Three messages, three fixes:\n\n- `Invalid API token` — unknown token. Check for a truncated paste (tokens are 128 hex characters), then issue a new one from the dashboard.\n- `API token is inactive` — revoked from the dashboard. Issue a new one.\n- `API token has expired` — only MCP connections expire (after 30 days). Reconnect the MCP client.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"unknown":{"value":{"success":false,"error":"Invalid API token"}},"inactive":{"value":{"success":false,"error":"API token is inactive"}},"expired":{"value":{"success":false,"error":"API token has expired"}}}}}},"DeepSearchForbidden":{"description":"Any of the token messages under `Forbidden` (unknown, inactive or expired token), or:\n\n- `Deep Search is not enabled for this API token. Contact support to enable it.` — Deep Search (including sound-alike search) is switched off for this token by The Rights Foundry. Nothing was charged and no upstream call was made. Contact support to have it enabled. Other endpoints keep working with the same token.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"disabled":{"value":{"success":false,"error":"Deep Search is not enabled for this API token. Contact support to enable it."}},"inactive":{"value":{"success":false,"error":"API token is inactive"}}}}}},"SyncForbidden":{"description":"Any of the token messages under `Forbidden` (unknown, inactive or expired token), or:\n\n- `Sync licensing is not enabled for this API token. Contact support to enable it.` — Sync licensing is switched off for this token by The Rights Foundry. Nothing was charged and no link was issued. Contact support to have it enabled. Other endpoints keep working with the same token.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"disabled":{"value":{"success":false,"error":"Sync licensing is not enabled for this API token. Contact support to enable it."}},"inactive":{"value":{"success":false,"error":"API token is inactive"}}}}}},"RateLimited":{"description":"Daily call cap reached. Only MCP connections carry a cap (currently 1,000 calls per UTC day); dashboard-issued API keys have none. Nothing is charged. `Retry-After` is the number of seconds until 00:00 UTC (never less than 60). Topping up does not reset the cap.\n","headers":{"Retry-After":{"description":"Seconds until the cap resets.","schema":{"type":"integer","example":41220}}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"limit":{"type":"integer","description":"The connection's daily cap.","example":1000}}}]},"example":{"success":false,"error":"Daily call limit reached for this connection. It resets at 00:00 UTC.","limit":1000}}}},"BillingUnavailable":{"description":"Billing could not confirm a successful deduction: the service was unavailable, the production binding was missing, or the response was unsuccessful or malformed. The requested catalog result was not served. A failed billing response does not guarantee that no deduction occurred; this path queues no automatic refund. Check `GET /v1/credits` before retrying if the outcome is uncertain. Wait `Retry-After` seconds (currently 5); retries are normal requests at the applicable rate-card key.\n","headers":{"Retry-After":{"schema":{"type":"integer","example":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Billing is temporarily unavailable. Please retry shortly."}}}},"ServerError":{"description":"Something failed on our side after the request was accepted. If the route recorded a successful charge, an asynchronous, best-effort refund is queued; it can be delayed or fail. Retry once after a short delay and keep the `X-Request-Id` header if the problem persists.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Internal server error"}}}}}},"paths":{"/v1/tracks":{"get":{"operationId":"searchTracks","summary":"Search & filter tracks","description":"Search, filter, and paginate through the music catalog. By default, only returns **root tracks** (not alternative versions). Use `includeChildren=true` to include all versions.\n\nAll tag filters (genre, mood, instrument, theme) use **exact match** within arrays and are **AND-ed** together. Text search is weighted full-text across title/artist/album, the tag arrays, and each track's generated description.\n\nThis endpoint is **deterministic**: you say exactly which fields to constrain and how to sort, and identical requests return identical results. If you would rather describe what you want in plain language — a brief, a mood, a scene — use `POST /v1/tracks/deep-search`; to find tracks that **sound like** an audio file you have a URL for, use `POST /v1/tracks/search`. Both return relevance-ordered results.\n\n### Credits\n\n| Request | `costs` key |\n|---|---|\n| Browse or filter — `search` absent or empty | `tracks_list` |\n| With a nonempty `search` — page 1 (`page` omitted or `1`) | `tracks_search_first_page` |\n| With a nonempty `search` — page 2 onwards | `tracks_search_next_page` |\n\nThe raw `search` value and requested `page` determine the rate. An absent or empty `search` uses `tracks_list`; any nonempty value, including whitespace-only text, uses `tracks_search_first_page` or `tracks_search_next_page`. Tag, BPM, duration, sort and `limit` parameters do not change the rate. The charge is per request, not per returned track, including empty results. The operator can retune any rate: read the live values from `GET /v1/credits`.\n\n### Quick Examples\n\n| Use Case | Query |\n|----------|-------|\n| Browse all tracks | `/v1/tracks` |\n| Search by keyword | `?search=summer+vibes` |\n| Filter by genre | `?genre=electronic` |\n| BPM range for DJ sets | `?bpmMin=120&bpmMax=130` |\n| Cinematic instrumentals | `?genre=cinematic&mood=epic&search=instrumental` (charged at `tracks_search_first_page`) |\n| Short tracks under 2 min | `?durationMax=120&sortBy=duration&sortOrder=asc` |\n| Find specific track | `?id=29446060` |\n| Include all versions | `?includeChildren=true` |\n\nOnly the parameters listed below are read; anything else in the query string is ignored without error. Use the `vocals` and `key` parameters for enforced constraints; lexical `search` also understands phrases such as `instrumental` and `female vocals`.\n","tags":["Tracks"],"parameters":[{"name":"search","in":"query","description":"Lexical search over the catalog's own vocabulary. The query is lowercased, stripped of punctuation and spell-corrected against that vocabulary (`acoustc` → `acoustic`; substitutions come back in `corrections`), then matched one to three words at a time against every genre, mood, theme, instrument, character, movement, vocal, tempo, energy, era, decade and key value listed by `GET /v1/taxonomies`. A recognized term matches a track that carries the tag itself or a longer tag containing it — `guitar` also matches `acoustic guitar` (reported with `partial: true`, scored lower). Recognized terms are OR-ed and ranked by how many of them a track carries: `dark epic` leads with the tracks carrying both, then those carrying one. Each track's `term_matches` says how many it matched and `coverage.levels` gives the distribution, so the fully-matching block is always identifiable. `total` counts the coverage levels needed to fill the first 100-row page, not every track that matched a single term — it is stable across pages of the same query. Words that match no vocabulary go to full-text search (title, artist, performed_by, album, every tag column and `auto_description`), prefix-matched, and are listed in `unmatched_terms`. Each is a term like any recognized one: it does not gate the set, but it counts toward coverage, so a track carrying the tag and the word outranks one carrying only the tag, and a track carrying only the word is still returned below them. A query of five words or fewer is also scored against title and artist by trigram similarity, so a part-remembered title or artist name is carried to the top of its coverage level. `120 bpm` becomes a ±5 BPM range; a bare `vocals` means sung vocals; `instrumental` or `no vocals` means none. `relaxed: true` means no track matched every term; results are still ranked by coverage. Filters — `vocals`, `key`, BPM and duration — are enforced at every coverage level and are never relaxed. Ranking is by relevance (exact tag hits weighted by column, then partial hits, then full-text rank, then title similarity) unless `sortBy` is given. Queries longer than eight recognized terms keep the eight most selective and report the rest in `ignored_terms`. For exact-tag filtering with no expansion use `genre`, `mood`, `instrument` and `theme`. `vocals` and `key` are hard constraints with their own parameters — state them there rather than in `search`, and they are enforced on every page, relaxed or not; the response echoes what was enforced under `constraints`, and names the constraint to loosen under `constraints.empty_because` when a page comes back empty. The remaining facets (character, movement, tempo, energy, era) have no filter parameter and are reached through `search` only.\n","schema":{"type":"string","maxLength":200},"example":"ambient piano"},{"name":"genre","in":"query","description":"Filter by genre tag (exact match, case-insensitive). Examples: `electronic`, `rock`, `classical`, `hip-hop`, `jazz`","schema":{"type":"string"},"example":"electronic"},{"name":"mood","in":"query","description":"Filter by mood tag. Examples: `uplifting`, `melancholy`, `energetic`, `calm`, `dark`","schema":{"type":"string"},"example":"uplifting"},{"name":"instrument","in":"query","description":"Filter by instrument tag. Examples: `piano`, `guitar`, `strings`, `drums`, `synthesizer`","schema":{"type":"string"},"example":"piano"},{"name":"theme","in":"query","description":"Filter by theme. Matches the editorial `themes` tags and the analyzed `music_for` tags (what the track is *for*). Examples: `cinematic`, `adventure`, `romance`, `nature`, `technology`","schema":{"type":"string"},"example":"cinematic"},{"name":"artist","in":"query","description":"Filter by artist name (partial match, case-insensitive)","schema":{"type":"string","maxLength":200},"example":"John"},{"name":"album","in":"query","description":"Filter by album name (partial match, case-insensitive)","schema":{"type":"string","maxLength":200}},{"name":"vocals","in":"query","description":"Enforced filter, never relaxed. `instrumental` returns only tracks with no voice at all (tracks whose vocals are unknown are excluded too); `male` / `female` return sung vocals of that kind; `any` returns any sung vocal. Matches `vocals_detected` where it exists and the editorial `vocals` otherwise — the same precedence the response displays.","schema":{"type":"string","enum":["instrumental","male","female","any"]},"example":"instrumental"},{"name":"key","in":"query","description":"Enforced filter, never relaxed. Musical key, e.g. `C minor`, `F# major`. Enharmonic spellings are matched together, so `C# minor` also returns tracks filed as `Db minor`.","schema":{"type":"string","maxLength":12},"example":"A minor"},{"name":"bpmMin","in":"query","description":"Minimum BPM (beats per minute). Use with `bpmMax` for a range. Compares against `bpm_detected`, falling back to the editorial `bpm`.","schema":{"type":"number","minimum":0},"example":90},{"name":"bpmMax","in":"query","description":"Maximum BPM. Use with `bpmMin` for a range. Compares against `bpm_detected`, falling back to the editorial `bpm`.","schema":{"type":"number","minimum":0,"maximum":999},"example":130},{"name":"durationMin","in":"query","description":"Minimum duration in seconds","schema":{"type":"number","minimum":0},"example":60},{"name":"durationMax","in":"query","description":"Maximum duration in seconds","schema":{"type":"number","minimum":0,"maximum":99999},"example":300},{"name":"featured","in":"query","description":"Filter featured tracks only. The flag itself is not returned on the track.","schema":{"type":"string","enum":["true","false"]}},{"name":"explicit","in":"query","description":"Filter by explicit content flag","schema":{"type":"string","enum":["true","false"]}},{"name":"decade","in":"query","description":"Filter by decade (partial match). Example: `1990s`, `2010s`","schema":{"type":"string","maxLength":10},"example":"2020s"},{"name":"id","in":"query","description":"Find a specific track by its ID (client_id). Returns at most 1 result. Alternative versions are hidden by default, so a child track's ID returns an empty page unless `includeChildren=true` is also set.","schema":{"type":"integer"},"example":29446060},{"name":"includeChildren","in":"query","description":"Include alternative versions (instrumentals, acoustic, etc.) in results. Default: only root tracks.","schema":{"type":"string","enum":["true","false"]}},{"name":"sortBy","in":"query","description":"Sort field. Default: `relevance` when `search` is given, otherwise `first_published` (latest on top, undated last). `relevance` without a `search` behaves like `first_published`.","schema":{"type":"string","enum":["relevance","first_published","created_at","title","artist","bpm","duration"]}},{"name":"sortOrder","in":"query","description":"Sort direction","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","description":"Page number (1-indexed)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Results per page (max 100). Values above 100 are clamped to 100, not rejected; `0`, negatives and non-integers are a `400`.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Paginated list of tracks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedTracks"},"examples":{"basic":{"summary":"Basic track listing","value":{"success":true,"data":[{"id":29446060,"title":"Forever Yours","artist":"Dominik Hauser","performed_by":"Dominik Hauser","album":"Cinematic Themes","duration":243,"bpm":120,"musical_key":"C Major","decades":"2020s","vocals":"instrumental","explicit":false,"first_published":"2024-01-15T00:00:00Z","release_date":null,"asset_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.mp3?expires=1774530330&sig=abc...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.json?expires=1774530330&sig=def...","genres":["cinematic"],"sub_genres":["film score"],"moods":["epic","uplifting"],"instruments":["orchestra"],"sub_instruments":[],"themes":["adventure"],"sub_themes":[],"has_alternatives":true}],"total":2211,"page":1,"limit":20}},"empty":{"summary":"No results","value":{"success":true,"data":[],"total":0,"page":1,"limit":20}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient credits. The request was not charged: the API cost would exceed its overdraft floor, or the existing bandwidth balance is already below its own floor. Catalog calls deduct no bandwidth. A browse is charged at `tracks_list` and a first search page at the higher `tracks_search_first_page`, so a balance that refuses a new search may still cover a browse or a later page. Top-ups reduce the debt; add enough to cover it and the next request. Call `GET /v1/credits` (free, uncharged) for the current balance, how much overdraft is left and the live rates.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"},"example":{"success":false,"error":"Insufficient credits. Please top up to continue.","apiCredits":-8,"bandwidthBytes":5368709120}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/BillingUnavailable"}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"# Search for electronic tracks with uplifting mood\ncurl \"https://api.therightsfoundry.com/v1/tracks?genre=electronic&mood=uplifting&limit=10\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n\n# BPM range for DJ sets (120-130 BPM)\ncurl \"https://api.therightsfoundry.com/v1/tracks?bpmMin=120&bpmMax=130&sortBy=bpm&sortOrder=asc\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n\n# Text search with genre filter\ncurl \"https://api.therightsfoundry.com/v1/tracks?search=summer+vibes&genre=pop\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n\n# Find specific track by ID\ncurl \"https://api.therightsfoundry.com/v1/tracks?id=29446060\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n"},{"lang":"javascript","label":"JavaScript","source":"const API_URL = 'https://api.therightsfoundry.com';\nconst TOKEN = 'YOUR_API_TOKEN';\n\n// Search for cinematic tracks\nconst response = await fetch(\n  `${API_URL}/v1/tracks?genre=cinematic&mood=epic&limit=10`,\n  { headers: { Authorization: `Bearer ${TOKEN}` } }\n);\nconst { data, total } = await response.json();\nconsole.log(`Found ${total} tracks`);\n\n// Stream audio from the first result\nif (data[0]?.asset_url) {\n  const audio = new Audio(data[0].asset_url);\n  audio.play();\n}\n"},{"lang":"python","label":"Python","source":"import requests\n\nAPI_URL = \"https://api.therightsfoundry.com\"\nTOKEN = \"YOUR_API_TOKEN\"\nheaders = {\"Authorization\": f\"Bearer {TOKEN}\"}\n\n# Search by BPM range + genre\nparams = {\"genre\": \"electronic\", \"bpmMin\": 120, \"bpmMax\": 140, \"limit\": 20}\nresponse = requests.get(f\"{API_URL}/v1/tracks\", headers=headers, params=params)\ndata = response.json()\n\nfor track in data[\"data\"]:\n    print(f\"{track['title']} by {track['artist']} ({track['bpm']} BPM)\")\n    print(f\"  Stream: {track['asset_url']}\")\n"},{"lang":"javascript","label":"Node.js","source":"// npm install axios — save as example.mjs and run: node example.mjs\nimport axios from 'axios';\n\nconst API_URL = 'https://api.therightsfoundry.com';\nconst TOKEN = 'YOUR_API_TOKEN';\n\n// Paginate through all piano tracks\nasync function getAllPianoTracks() {\n  let page = 1;\n  let allTracks = [];\n\n  while (true) {\n    const { data } = await axios.get(`${API_URL}/v1/tracks`, {\n      headers: { Authorization: `Bearer ${TOKEN}` },\n      params: { instrument: 'piano', page, limit: 100 },\n    });\n\n    allTracks.push(...data.data);\n    if (allTracks.length >= data.total) break;\n    page++;\n  }\n\n  console.log(`Fetched ${allTracks.length} piano tracks`);\n  return allTracks;\n}\n\nconst tracks = await getAllPianoTracks();\n"}]}},"/v1/tracks/deep-search":{"post":{"operationId":"searchTracksDeepSearch","summary":"Deep Search","description":"Describe what you want in plain language and get relevance-ordered music back.\n\n> **Formerly `POST /v1/tracks/creative-brief`.** That path was retired on 24 September 2026 and now answers `410 Gone` (nothing charged) with a pointer here. The request body and pricing are unchanged; the rate-card keys are now `deep_search_first_page` / `deep_search_next_page` (formerly `creative_brief_*`).\n\nSend a sync brief, a scene description, a mood, or a sentence about the edit you are scoring — the whole string is read as a brief, not parsed as a query language:\n\n| Example brief |\n|---|\n| `warm hopeful acoustic guitar for a nature documentary` |\n| `tense driving percussion for a chase scene` |\n| `sparse melancholy piano under a voiceover about loss` |\n\nThere is no query syntax and no operators. Field-exact lookups — genre, mood, BPM range, artist, album — belong on `GET /v1/tracks`, which is deterministic and sortable. To find tracks that **sound like** a recording you can link to, use `POST /v1/tracks/search` with `file_url`.\n\nOn a cache miss, the API waits up to 20 seconds for the provider to rank the catalog. Cache hits avoid that upstream wait; any page can miss the cache. Allow additional time for the API to assemble the response.\n\nResults use the **same `Track` shape as `GET /v1/tracks`**, including signed `asset_url` and `peak_data_url`, so existing rendering and playback code works unchanged.\n\n### Choosing between this and `GET /v1/tracks`\n\n| You want to… | Use |\n|---|---|\n| Describe a scene, mood, or brief in plain language | `POST /v1/tracks/deep-search` |\n| Find tracks that sound like an audio file you can link to | `POST /v1/tracks/search` with `file_url` |\n| Filter on exact fields — genre, mood, BPM range, duration, artist | `GET /v1/tracks` |\n| Sort by a field (title, BPM, date) or paginate the whole catalog | `GET /v1/tracks` |\n\nResults here are **always relevance-ordered** — there is no `sortBy`/`sortOrder`. For field-sorted browsing, stay on `GET /v1/tracks`.\n\n### Credits\n\nThis endpoint has its own rate-card keys, separate from `GET /v1/tracks`:\n\n| Request | `costs` key |\n|---|---|\n| Page 1 of a brief (`page` omitted or `1`) | `deep_search_first_page` |\n| Page 2 onwards, including a cache miss | `deep_search_next_page` |\n\nLater pages cost 1 credit each. Read the first-page rate from `GET /v1/credits`.\n\nBilling is classified by **page number, not cache state**: every `page: 1` request is charged at `deep_search_first_page` and every later page at `deep_search_next_page`, so the charge for a request is predictable before you send it. The result set has a **1-hour** shared-cache TTL. Later pages reuse it when available; expiry, eviction, or catalog changes can cause the search to run again. A later-page request still uses `deep_search_next_page`.\n\n**What starts a new first-page charge — the main way to waste credits:**\n\n- Changing the normalized `query` **or** `instrumental` changes the search identity (brief whitespace is trimmed and collapsed). That is a new search, and its page 1 is charged at `deep_search_first_page`.\n- Changing `page` or `limit` does **not** — pages 2 and up of the same brief are always charged at `deep_search_next_page`.\n- Re-sending `page: 1` is charged at `deep_search_first_page` every time, cached or not. Fetch page 1 once, generously (`limit` up to 100), then only page forward.\n\nWorked example, in rate-card terms: one brief fetched as page 1 with `limit: 100`, then four more pages, costs 1 × `deep_search_first_page` + 4 credits for up to 500 results. Making five separate first-page requests — for different briefs or by re-sending page 1 — costs 5 × `deep_search_first_page` and does not guarantee 500 distinct rows. Fix `query` and `instrumental` before you start paging.\n\nThe operator can retune both rates without a new API version, and `GET /v1/credits` returns the current rate card. If your balance cannot cover a request, you receive `402`.\n\n### Behavior notes\n\n- A search that matches nothing returns `200` with an empty `data` array and `total: 0` — not an error.\n- A search-provider `503` queues an asynchronous, best-effort refund of any charge. A billing `503` instead means the deduction was not confirmed; it includes `Retry-After` and queues no refund. Retrying is a normal request charged at `deep_search_first_page` or `deep_search_next_page` according to `page`.\n- This endpoint is **POST-only**. `GET /v1/tracks/deep-search` returns `405` with a reminder to use POST.\n","tags":["Tracks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"The brief, in plain language. Changing the normalized text changes the cached search; billing still uses `deep_search_first_page` for page 1 and `deep_search_next_page` for later pages.\n","example":"warm hopeful acoustic guitar for a nature documentary"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page of results to return (1-indexed). Page 1 (or omitting `page`) is charged as a new search at `deep_search_first_page`; higher pages of the same brief are charged at `deep_search_next_page`, 1 credit per page. Read the first-page rate from `GET /v1/credits`.\n"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Results per page (max 100 — larger values are rejected with `400`; `GET /v1/tracks` clamps instead). Changing `limit` does not change the page-based rate or cached search, but every request is still priced by `page`. It moves page boundaries, so keep it fixed while paging.\n"},"instrumental":{"type":"boolean","default":false,"description":"Only instrumental recordings. This also lifts the root-tracks-only rule, so the instrumental alternative versions of vocal tracks — hidden from a default search — become results in their own right. Part of the search identity: changing it changes the cached search, but the rate still depends on `page` (`deep_search_first_page` or `deep_search_next_page`). Keep it fixed while paging.\n"}}},"examples":{"brief":{"summary":"Descriptive brief","value":{"query":"warm hopeful acoustic guitar for a nature documentary","limit":20}},"instrumentalOnly":{"summary":"Instrumental only","value":{"query":"tense driving percussion for a chase scene","instrumental":true}},"nextPage":{"summary":"Next page of the same brief (cheap)","value":{"query":"warm hopeful acoustic guitar for a nature documentary","page":2,"limit":20}}}}}},"responses":{"200":{"description":"Relevance-ordered results. Also returned when nothing matches (`data` is empty and `total` is 0) — zero matches is not an error.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepSearchResults"},"examples":{"matches":{"summary":"Descriptive brief with matches","value":{"success":true,"data":[{"id":30284117,"title":"Morning Meadow","artist":"Clara Whitfield","performed_by":"Clara Whitfield","album":"Field & Sky","duration":187,"bpm":96,"musical_key":"G Major","decades":"2020s","vocals":"instrumental","explicit":false,"first_published":"2023-06-02T00:00:00Z","release_date":null,"asset_url":"https://assets.therightsfoundry.com/stream/AB12/30284117/30284117_track.mp3?expires=1774530330&sig=abc...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/30284117/30284117_track.json?expires=1774530330&sig=def...","genres":["folk","acoustic"],"sub_genres":["indie folk"],"moods":["hopeful","warm"],"instruments":["acoustic guitar"],"sub_instruments":["nylon string guitar"],"themes":["nature"],"sub_themes":[],"has_alternatives":true},{"id":29881204,"title":"River Light","artist":"Tom Averill","performed_by":"Tom Averill","album":"Northbound","duration":214,"bpm":104,"musical_key":"D Major","decades":"2020s","vocals":"male","explicit":false,"first_published":"2022-09-14T00:00:00Z","release_date":null,"asset_url":"https://assets.therightsfoundry.com/stream/AB12/29881204/29881204_track.mp3?expires=1774530330&sig=ghi...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29881204/29881204_track.json?expires=1774530330&sig=jkl...","genres":["folk"],"sub_genres":[],"moods":["uplifting","warm"],"instruments":["acoustic guitar","strings"],"sub_instruments":[],"themes":["nature","journey"],"sub_themes":[],"has_alternatives":false}],"total":148,"page":1,"limit":20}},"empty":{"summary":"No matches","value":{"success":true,"data":[],"total":0,"page":1,"limit":20}}}}}},"400":{"description":"**Request validation failed.** The body was not valid JSON, `query` was missing, empty, or over 500 characters, `limit` was over 100, or `page` was below 1. Rejected before any upstream work is performed, so nothing is charged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notJson":{"summary":"Body is not JSON","value":{"success":false,"error":"Request body must be valid JSON"}},"missingQuery":{"summary":"query is missing or empty","value":{"success":false,"error":"query is required"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient credits — the API cost would exceed its overdraft floor, or the existing bandwidth balance is already below its own floor. Catalog calls deduct no bandwidth. Nothing was charged. Page 1 is charged at `deep_search_first_page` and later pages at `deep_search_next_page` (1 credit), so a low balance — even one already inside the overdraft — can still cover paging an existing brief while refusing a new one. Check `api_credits.spendable` against the key you are about to use before sending. Top-ups reduce the debt; add enough to cover it and the next request. Call `GET /v1/credits` (free, uncharged) for the current balance, how much overdraft is left and the live rates.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"},"example":{"success":false,"error":"Insufficient credits. Please top up to continue.","apiCredits":-8,"bandwidthBytes":5368709120}}}},"403":{"$ref":"#/components/responses/DeepSearchForbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Two bodies share this status. `Search is temporarily unavailable, please retry.` — the upstream provider failed; an asynchronous, best-effort refund is queued for any charge. It can be delayed or fail. `Billing is temporarily unavailable. Please retry shortly.` with `Retry-After: 5` — billing could not confirm a successful deduction, so no search ran. A deduction may still have occurred, and this path queues no automatic refund. Check `GET /v1/credits` if the outcome is uncertain and honor `Retry-After` when present. Retries use the same page-based rate-card keys as other requests.\n","headers":{"Retry-After":{"description":"Present on the billing variant only. Seconds to wait.","schema":{"type":"integer","example":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchDown":{"summary":"Search provider unavailable (refund attempted)","value":{"success":false,"error":"Search is temporarily unavailable, please retry."}},"billingDown":{"summary":"Billing unavailable (deduction unconfirmed)","value":{"success":false,"error":"Billing is temporarily unavailable. Please retry shortly."}}}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"# Deep Search page 1 — charged at costs.deep_search_first_page\ncurl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \\\n  -H 'Authorization: Bearer YOUR_API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\": \"warm hopeful acoustic guitar for a nature documentary\", \"limit\": 20}'\n\n# Page 2 — costs.deep_search_next_page, even on a cache miss\ncurl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \\\n  -H 'Authorization: Bearer YOUR_API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\": \"warm hopeful acoustic guitar for a nature documentary\", \"page\": 2, \"limit\": 20}'\n\n# Instrumental only, page 1 — costs.deep_search_first_page\ncurl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \\\n  -H 'Authorization: Bearer YOUR_API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\": \"tense driving percussion for a chase scene\", \"instrumental\": true}'\n"},{"lang":"javascript","label":"Node.js","source":"// npm install axios — save as example.mjs and run: node example.mjs\nimport axios from 'axios';\n\nconst API_URL = 'https://api.therightsfoundry.com';\nconst TOKEN = 'YOUR_API_TOKEN';\n\nasync function deepSearch(body, retries = 2) {\n  for (let attempt = 0; ; attempt++) {\n    try {\n      const { data } = await axios.post(\n        `${API_URL}/v1/tracks/deep-search`, body,\n        { headers: { Authorization: `Bearer ${TOKEN}` } },\n      );\n      return data;\n    } catch (err) {\n      // A search 503 attempts a refund; a billing 503 leaves\n      // the deduction unconfirmed. Retrying uses the page rate.\n      if (err.response?.status === 503 && attempt < retries) {\n        const waitSeconds = Number(err.response.headers['retry-after'] ?? attempt + 1);\n        await new Promise((r) => setTimeout(r, 1000 * waitSeconds));\n        continue;\n      }\n      throw err;\n    }\n  }\n}\n\n// Page 1 uses costs.deep_search_first_page, cached or not.\n// Fetch generously — up to 100 per page.\nconst query = 'tense driving percussion for a chase scene';\nconst first = await deepSearch({ query, limit: 100 });\nconsole.log(`${first.total} matches`);\n\n// Later pages use costs.deep_search_next_page, even on a cache miss.\n// Keep `query` and `instrumental` fixed for consistent paging.\nfor (let page = 2; (page - 1) * 100 < first.total; page++) {\n  const next = await deepSearch({ query, page, limit: 100 });\n  console.log(`Page ${page}: ${next.data.length} tracks`);\n  if (next.data.length === 0) break;\n}\n"},{"lang":"python","label":"Python","source":"import time\nimport requests\n\nAPI_URL = \"https://api.therightsfoundry.com\"\nTOKEN = \"YOUR_API_TOKEN\"\nHEADERS = {\"Authorization\": f\"Bearer {TOKEN}\"}\n\n\ndef deep_search(body, retries=2):\n    for attempt in range(retries + 1):\n        resp = requests.post(\n            f\"{API_URL}/v1/tracks/deep-search\", headers=HEADERS, json=body\n        )\n        if resp.status_code == 503 and attempt < retries:\n            # A search 503 attempts a refund; a billing 503 leaves\n            # the deduction unconfirmed. Retrying uses the page rate.\n            time.sleep(float(resp.headers.get(\"Retry-After\", attempt + 1)))\n            continue\n        resp.raise_for_status()\n        return resp.json()\n\n\n# Page 1 uses costs.deep_search_first_page, cached or not.\nquery = \"warm hopeful acoustic guitar for a nature documentary\"\nresults = deep_search({\"query\": query, \"limit\": 20})\n\nfor track in results[\"data\"]:\n    print(f\"{track['title']} — {track['artist']} ({track['duration']}s)\")\n\n# Later pages use costs.deep_search_next_page, even on a cache miss.\n# Keep `query` and `instrumental` fixed for consistent paging.\nif results[\"total\"] > results[\"limit\"]:\n    page2 = deep_search({\"query\": query, \"page\": 2, \"limit\": 20})\n"}]}},"/v1/tracks/search":{"post":{"operationId":"searchTracksByFile","summary":"Acoustic Similarity Search","description":"Point at a publicly reachable `.mp3` or `.wav` recording and get catalog tracks that **sound like** it. Matching is acoustic — the search provider analyzes the audio itself, not its metadata. Typical uses: \"find me more like this reference track a client sent\", matching the temp track in an edit, or finding catalog tracks similar to one you already use.\n\n> **Moved:** this endpoint previously also accepted a text `query`. Natural-language search now lives at **`POST /v1/tracks/deep-search`**. A body containing `query` is rejected with `400` and a pointer to the new path.\n\nRequirements for `file_url`:\n\n- A valid absolute `http(s)` URL, at most 2000 characters\n- Points to an **`.mp3` or `.wav`** file — the extension is checked; a `?query` or `#fragment` after it is fine\n- **Publicly reachable by GET** — the search provider downloads the file server-side. The audio is **not** uploaded through this API, so a URL behind authentication, a login wall, or an IP allowlist will fail.\n- At most **120 MB** (upstream limit)\n- **Allow 60 seconds** for a cache miss: the provider downloads and fingerprints the file before it can search (we wait up to 45 s upstream). Cache hits avoid that upstream wait; any page can miss the cache.\n\nResults use the **same `Track` shape as `GET /v1/tracks`**, including signed `asset_url` and `peak_data_url`, so existing rendering and playback code works unchanged. Responses still carry `did_you_mean: []` and `search_type: null`; both are deprecated constants kept for backwards compatibility — there is no text query to interpret.\n\n### Credits\n\nThe provider has to download and fingerprint the audio before it can search, and this endpoint has its own rate-card keys, separate from Deep Search:\n\n| Request | `costs` key |\n|---|---|\n| Page 1 for a `file_url` (`page` omitted or `1`) | `file_search_first_page` |\n| Page 2 onwards, including a cache miss | `file_search_next_page` |\n\nLater pages cost 1 credit each. Read the first-page rate from `GET /v1/credits`.\n\nBilling is classified by **page number, not cache state**: every `page: 1` request is charged at `file_search_first_page` and every later page at `file_search_next_page`, so the charge for a request is predictable before you send it. The result set has a **1-hour** shared-cache TTL. Later pages reuse it when available; expiry, eviction, or catalog changes can cause the search to run again. A later-page request still uses `file_search_next_page`.\n\n**What starts a new first-page charge — the main way to waste credits:**\n\n- Changing `file_url` **or** `instrumental` changes the search identity. That is a new search, and its page 1 is charged at `file_search_first_page`. The URL string itself is the identity — the same audio at a different URL is a new search.\n- Changing `page` or `limit` does **not** — pages 2 and up of the same `file_url` are always charged at `file_search_next_page`.\n- Re-sending `page: 1` is charged at `file_search_first_page` every time, cached or not. Fetch page 1 once, generously (`limit` up to 100), then only page forward.\n\nWorked example, in rate-card terms: one reference file fetched as page 1 with `limit: 100`, then four more pages, costs 1 × `file_search_first_page` + 4 credits for up to 500 results. Making five separate first-page requests — for different reference files or by re-sending page 1 — costs 5 × `file_search_first_page` and does not guarantee 500 distinct rows. Fix `file_url` and `instrumental` before you start paging.\n\nThe operator can retune both rates without a new API version, and `GET /v1/credits` returns the current rate card. If your balance cannot cover a request, you receive `402`.\n\n### Refunds on failure — 400 vs 503\n\nTwo failure modes look superficially similar but are charged differently. Do not conflate them:\n\n- **`503`** — a search-provider failure queues an asynchronous, best-effort refund of any charge. A billing failure instead means the deduction was not confirmed; it includes `Retry-After` and queues no refund. A retry is charged at `file_search_first_page` or `file_search_next_page` according to `page`.\n- **`400` — `Could not download or decode the audio at file_url. It must be a publicly reachable .mp3 or .wav under 120MB.`** — the provider reached out for your file and could not fetch or decode it. This is a **client error and the credits are not refunded**, because the upstream download attempt was performed. Common causes: the URL is not public, the host blocks server-side fetches, the link is dead, or the file is the wrong or an unsupported format. Fix the URL before retrying — retrying the same broken URL is charged again.\n\n(400s from request validation — bad JSON, a missing or malformed `file_url`, a `query` that belongs on `/v1/tracks/deep-search` — are rejected before any upstream work is performed.)\n\n### Behavior notes\n\n- A search that matches nothing returns `200` with an empty `data` array and `total: 0` — not an error.\n- This endpoint is **POST-only**. `GET /v1/tracks/search` returns `405` with a reminder to use POST.\n","tags":["Tracks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["file_url"],"properties":{"file_url":{"type":"string","format":"uri","maxLength":2000,"description":"Absolute `http(s)` URL of a **publicly reachable** `.mp3` or `.wav` file, at most 120 MB. The search provider downloads it server-side — the audio is not uploaded through this API — and results are catalog tracks that sound like the recording. Changing this changes the cached search; billing still uses `file_search_first_page` for page 1 and `file_search_next_page` for later pages.\n","example":"https://cdn.example.com/references/client-temp-track.mp3"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page of results to return (1-indexed). Page 1 (or omitting `page`) is charged as a new search at `file_search_first_page`; higher pages of the same `file_url` are charged at `file_search_next_page`, 1 credit per page. Read the first-page rate from `GET /v1/credits`.\n"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Results per page (max 100 — larger values are rejected with `400`; `GET /v1/tracks` clamps instead). Changing `limit` does not change the page-based rate or cached search, but every request is still priced by `page`. It moves page boundaries, so keep it fixed while paging.\n"},"instrumental":{"type":"boolean","default":false,"description":"Only instrumental recordings. This also lifts the root-tracks-only rule, so the instrumental alternative versions of vocal tracks — hidden from a default search — become results in their own right. Part of the search identity: changing it changes the cached search, but the rate still depends on `page` (`file_search_first_page` or `file_search_next_page`). Keep it fixed while paging.\n"}}},"examples":{"soundAlike":{"summary":"Acoustic Similarity Search from a reference file","value":{"file_url":"https://cdn.example.com/references/client-temp-track.mp3","limit":20}},"soundAlikeNextPage":{"summary":"Next page of the same reference recording (cheap)","value":{"file_url":"https://cdn.example.com/references/client-temp-track.mp3","page":2,"limit":20}}}}}},"responses":{"200":{"description":"Relevance-ordered results. Also returned when nothing matches (`data` is empty and `total` is 0) — zero matches is not an error.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"},"examples":{"fileMatches":{"summary":"Acoustic Similarity Search with matches","value":{"success":true,"data":[{"id":30117492,"title":"Slow Burn","artist":"Nadia Kern","performed_by":"Nadia Kern","album":"Emberline","duration":201,"bpm":88,"musical_key":"A Minor","decades":"2020s","vocals":"instrumental","explicit":false,"first_published":"2023-11-08T00:00:00Z","release_date":null,"asset_url":"https://assets.therightsfoundry.com/stream/AB12/30117492/30117492_track.mp3?expires=1774530330&sig=mno...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/30117492/30117492_track.json?expires=1774530330&sig=pqr...","genres":["electronic","ambient"],"sub_genres":["downtempo"],"moods":["moody","atmospheric"],"instruments":["synthesizer"],"sub_instruments":[],"themes":["night"],"sub_themes":[],"has_alternatives":true}],"total":62,"page":1,"limit":20,"did_you_mean":[],"search_type":null}},"empty":{"summary":"No matches","value":{"success":true,"data":[],"total":0,"page":1,"limit":20,"did_you_mean":[],"search_type":null}}}}}},"400":{"description":"Two distinct cases share this status — they differ in whether credits are involved:\n\n**Request validation failed.** The body was not valid JSON, `file_url` was missing or failed validation (not a valid http(s) URL, or not an `.mp3`/`.wav`), a `query` was supplied (it belongs on `POST /v1/tracks/deep-search`), `limit` was over 100, or `page` was below 1. Rejected before any upstream work is performed, so nothing is charged.\n\n**The file could not be fetched.** The search provider tried to download the audio at `file_url` and could not fetch or decode it. This is a client error and **credits are not refunded** — the upstream work was performed. (A search-provider `503` instead queues a best-effort refund; a billing `503` does not.) Common causes: the URL is not public, the host blocks server-side fetches, the link is dead, or the file is the wrong or an unsupported format. Fix the URL before retrying — retrying the same broken URL is charged again.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notJson":{"summary":"Body is not JSON","value":{"success":false,"error":"Request body must be valid JSON"}},"queryMoved":{"summary":"query was supplied — it moved to /v1/tracks/deep-search","value":{"success":false,"error":"query is no longer supported on this endpoint; use POST /v1/tracks/deep-search"}},"missingFileUrl":{"summary":"file_url is missing","value":{"success":false,"error":"file_url is required"}},"invalidUrl":{"summary":"file_url is not a URL","value":{"success":false,"error":"file_url must be a valid URL"}},"notHttp":{"summary":"file_url is not http(s)","value":{"success":false,"error":"file_url must be an http(s) URL"}},"wrongExtension":{"summary":"file_url is not .mp3 / .wav","value":{"success":false,"error":"file_url must point to an .mp3 or .wav file"}},"fileUnreachable":{"summary":"File could not be downloaded or decoded (credits NOT refunded)","value":{"success":false,"error":"Could not download or decode the audio at file_url. It must be a publicly reachable .mp3 or .wav under 120MB."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient credits — the API cost would exceed its overdraft floor, or the existing bandwidth balance is already below its own floor. Catalog calls deduct no bandwidth. Nothing was charged. Page 1 of a `file_url` search is charged at `file_search_first_page`, while paging an existing one is charged at `file_search_next_page` (1 credit), so a balance too low for a new reference search may still cover paging it. Check `api_credits.spendable` against the key you are about to use before sending. Top-ups reduce the debt; add enough to cover it and the next request. Call `GET /v1/credits` (free, uncharged) for the current balance, how much overdraft is left and the live rates.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"},"example":{"success":false,"error":"Insufficient credits. Please top up to continue.","apiCredits":-8,"bandwidthBytes":5368709120}}}},"403":{"$ref":"#/components/responses/DeepSearchForbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"description":"Two bodies share this status. `Search is temporarily unavailable, please retry.` — the upstream provider failed; an asynchronous, best-effort refund is queued for any charge. It can be delayed or fail. `Billing is temporarily unavailable. Please retry shortly.` with `Retry-After: 5` — billing could not confirm a successful deduction, so no search ran. A deduction may still have occurred, and this path queues no automatic refund. Check `GET /v1/credits` if the outcome is uncertain and honor `Retry-After` when present. Retries use the same page-based rate-card keys as other requests.\n\nDo not confuse this with the `400` (\"Could not download or decode the audio at file_url…\"): that one means *your file* was the problem, and those credits are **not** refunded.\n","headers":{"Retry-After":{"description":"Present on the billing variant only. Seconds to wait.","schema":{"type":"integer","example":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"searchDown":{"summary":"Search provider unavailable (refund attempted)","value":{"success":false,"error":"Search is temporarily unavailable, please retry."}},"billingDown":{"summary":"Billing unavailable (deduction unconfirmed)","value":{"success":false,"error":"Billing is temporarily unavailable. Please retry shortly."}}}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"# Acoustic Similarity Search — a direct, publicly reachable .mp3/.wav URL\n# goes in file_url. Page 1 uses costs.file_search_first_page; on a\n# cache miss the provider downloads and fingerprints the audio.\ncurl -X POST 'https://api.therightsfoundry.com/v1/tracks/search' \\\n  -H 'Authorization: Bearer YOUR_API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"file_url\": \"https://cdn.example.com/references/client-temp-track.mp3\", \"limit\": 100}'\n\n# Page 2 — costs.file_search_next_page, even on a cache miss\ncurl -X POST 'https://api.therightsfoundry.com/v1/tracks/search' \\\n  -H 'Authorization: Bearer YOUR_API_TOKEN' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"file_url\": \"https://cdn.example.com/references/client-temp-track.mp3\", \"page\": 2, \"limit\": 100}'\n"},{"lang":"javascript","label":"Node.js","source":"// npm install axios — save as example.mjs and run: node example.mjs\nimport axios from 'axios';\n\nconst API_URL = 'https://api.therightsfoundry.com';\nconst TOKEN = 'YOUR_API_TOKEN';\n\nasync function soundAlike(body, retries = 2) {\n  for (let attempt = 0; ; attempt++) {\n    try {\n      const { data } = await axios.post(`${API_URL}/v1/tracks/search`, body, {\n        headers: { Authorization: `Bearer ${TOKEN}` },\n      });\n      return data;\n    } catch (err) {\n      const status = err.response?.status;\n      // A search 503 attempts a refund; a billing 503 leaves\n      // the deduction unconfirmed. Retrying uses the page rate.\n      if (status === 503 && attempt < retries) {\n        const waitSeconds = Number(err.response.headers['retry-after'] ?? attempt + 1);\n        await new Promise((r) => setTimeout(r, 1000 * waitSeconds));\n        continue;\n      }\n      // Validation 400s are uncharged; a download/decode 400\n      // retains the page-based charge. Fix the reported problem.\n      if (status === 400) {\n        console.error('Request rejected:', err.response.data.error);\n      }\n      throw err;\n    }\n  }\n}\n\n// Page 1 uses costs.file_search_first_page.\n// On a cache miss the provider downloads the file server-side.\nconst file_url = 'https://cdn.example.com/references/client-temp-track.mp3';\nconst similar = await soundAlike({ file_url, limit: 100 });\nconsole.log(`${similar.total} tracks sound like the reference`);\n\n// Later pages use costs.file_search_next_page, even on a cache miss.\n// Keep `file_url` and `instrumental` fixed for consistent paging.\nfor (let page = 2; (page - 1) * 100 < similar.total; page++) {\n  const next = await soundAlike({ file_url, page, limit: 100 });\n  if (next.data.length === 0) break;\n}\n"},{"lang":"python","label":"Python","source":"import time\nimport requests\n\nAPI_URL = \"https://api.therightsfoundry.com\"\nTOKEN = \"YOUR_API_TOKEN\"\nHEADERS = {\"Authorization\": f\"Bearer {TOKEN}\"}\n\n\ndef sound_alike(body, retries=2):\n    for attempt in range(retries + 1):\n        resp = requests.post(\n            f\"{API_URL}/v1/tracks/search\", headers=HEADERS, json=body\n        )\n        if resp.status_code == 503 and attempt < retries:\n            # A search 503 attempts a refund; a billing 503 leaves\n            # the deduction unconfirmed. Retrying uses the page rate.\n            time.sleep(float(resp.headers.get(\"Retry-After\", attempt + 1)))\n            continue\n        if resp.status_code == 400:\n            # Validation 400s are uncharged; a download/decode 400\n            # retains the page-based charge. Fix the reported problem.\n            raise RuntimeError(\n                f\"Request rejected: {resp.json()['error']}\"\n            )\n        resp.raise_for_status()\n        return resp.json()\n\n\n# Page 1 uses costs.file_search_first_page.\n# On a cache miss the provider downloads the file server-side.\nfile_url = \"https://cdn.example.com/references/client-temp-track.mp3\"\nsimilar = sound_alike({\"file_url\": file_url, \"limit\": 20})\nprint(f\"{similar['total']} tracks sound like the reference\")\n\n# Later pages use costs.file_search_next_page, even on a cache miss.\n# Keep `file_url` and `instrumental` fixed for consistent paging.\nif similar[\"total\"] > similar[\"limit\"]:\n    page2 = sound_alike({\"file_url\": file_url, \"page\": 2, \"limit\": 20})\n"}]}},"/v1/taxonomies":{"get":{"operationId":"getTaxonomies","summary":"What the catalog offers","description":"Every genre, mood, theme, instrument, character, movement, vocal type, tempo, energy level, era, decade and key present in the catalog, with track counts. Built from the same vocabulary that powers the `search` parameter, so every value here is recognized by `search` (which may also match longer tags that contain it). Values under `genre`, `mood`, `instrument` and `theme` double as exact filters on `GET /v1/tracks`; `vocals`, `key`, and `decade` also have filter parameters; the remaining facets are reached through `search`. Not charged. Cached; values refresh within 24 hours of catalog changes.\n","tags":["Tracks"],"responses":{"200":{"description":"Facets with values and counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Taxonomies"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/v1/credits":{"get":{"operationId":"getCreditBalance","summary":"Credit balance","description":"How many API credits and how much bandwidth the account behind your token has left, the overdraft you may still dip into, which credits expire next, and the rate card currently in force. **This is the single source of truth for pricing.** Nothing else in this document states a price; every figure a client uses should come from here.\n\n**This endpoint is free and uncounted.** It deducts no credits and does not count toward the monthly per-token call counter or an MCP connection's daily cap, so a client that has run out of credits can always find out where it stands. The one thing it cannot bypass: once an MCP connection has already reached its daily cap, authenticated requests — this one included — are refused with `429` once the cap is detected, until 00:00 UTC. Public health checks and signed asset fetches do not pass through that cap. Dashboard API keys have no cap.\n\n### The rate card — `costs`\n\nEvery charged call is priced by exactly one key. \"Page 1\" includes a request that omits `page`. If the operator makes a rate free, its billing deduction and balance check are skipped. Prices are per request, not per returned track.\n\n| Key | Prices | Condition |\n|---|---|---|\n| `tracks_list` | `GET /v1/tracks` | `search` absent or empty. Every page, any filters |\n| `tracks_search_first_page` | `GET /v1/tracks` | Nonempty `search`, page 1 |\n| `tracks_search_next_page` | `GET /v1/tracks` | Nonempty `search`, page 2 or higher |\n| `track_detail` | `GET /v1/tracks/{id}` | Every successful call, however many `child_tracks` come back |\n| `deep_search_first_page` | `POST /v1/tracks/deep-search` — Deep Search | Page 1, every time it is sent, cached or not |\n| `deep_search_next_page` | `POST /v1/tracks/deep-search` — Deep Search | Page 2 or higher, even if `query` or `instrumental` changed. 1 credit per page |\n| `file_search_first_page` | `POST /v1/tracks/search` — Acoustic Similarity Search | Page 1, every time it is sent, cached or not |\n| `file_search_next_page` | `POST /v1/tracks/search` — Acoustic Similarity Search | Page 2 or higher, even if `file_url` or `instrumental` changed. 1 credit per page |\n| `sync` | `POST /v1/tracks/{id}/sync` | No body, or `external_export: false`. A new access window **issued**. A repeat within the account/track's paid window is free (`credits_charged: 0`, `reissued: true`) and inherits its expiry. Never charged on the download |\n| `export_sync` | `POST /v1/tracks/{id}/sync` with `{\"external_export\": true}` | Export Sync — offline use, or placing the output outside the platform. A new export window **issued**; a repeat export within that window is free. A live standard `sync` window does not make an export free, nor the other way round. Never charged on the download |\n| `stream` | Playing a preview `asset_url` | **Published, not yet charged.** Nothing deducts it today; stream costs are a coming change |\n\nNot on the card because they are free in credits: this endpoint, `GET /v1/taxonomies`, `GET /v1/health`, and fetching `peak_data_url` or `download_url`. Playing an MP3 preview is metered but not yet billed — `costs.stream` is what it will cost once stream costs arrive; see *Which way the charge runs* in the API overview. Never charged: `400` request-validation errors, `401`, `403`, `404`, `405`, `429`. A `402` also makes no deduction. A `500` after a recorded charge, or a search-provider `503`, queues an asynchronous, best-effort refund; refunds can be delayed or fail. A billing `503` means the deduction could not be confirmed and queues no refund; check the balance and honor `Retry-After` before retrying. The Acoustic Similarity Search `400` for an undownloadable or undecodable reference file deliberately retains its page-based charge (`file_search_first_page` or `file_search_next_page`). Successful empty results are also charged at the applicable rate-card key.\n\n### Reading the numbers\n\n- `api_credits.balance` **can be negative**. A charged request is refused with `402` if its API cost would leave the balance below `-api_credits.overdraft_limit`, or if bandwidth is already below `-bandwidth_bytes.overdraft_limit`. Catalog calls deduct no bandwidth, and signed asset fetches check neither balance. Top-ups reduce the debt; they clear it only once enough is added.\n- `api_credits.spendable` is the number to budget against: `balance + overdraft_limit`, what you can still spend before the next `402`. Compare it with `costs.<key>` for the call you are about to make.\n- `api_credits.overdraft_limit` is the tolerance in force for your account. It depends on your monthly plan: subscribers get a tolerance that scales with their plan, and an account without a plan may have none (a small one while automatic top-up is on). It can change when your plan does.\n- `bandwidth_bytes` is the interim streaming allowance. Stream transfers do not deduct from it today — streaming is metered, not billed. Stream costs, when they arrive, will be charged per stream from API credits at `costs.stream`. See the schema and *Which way the charge runs*.\n- `expiring_credits` lists unexpired batches soonest-expiry first. Batch deductions use expiry order, with nonexpiring batches last, but the list omits expired batches pending cleanup and can lag live deductions. Credits with no expiry are also omitted, so do not sum this array to reconstruct `balance` or assume it identifies the next batch to be consumed.\n- `token` counters are per token; balances are per account. Several tokens on one account draw down the same balance. `token.daily_call_limit` is `null` on dashboard keys and set on MCP connections; calls to this endpoint and to `GET /v1/taxonomies` are not counted against it.\n\nBalances are read from the live counter that serves your requests, with a database fallback if that read fails or the binding is absent. `balance_source` identifies which was used; persisted balances and batch data can lag. Rates are cached, so operator changes may take time to propagate. If the rate lookup fails and no cached rules are available, built-in defaults are used temporarily.\n","tags":["Credits"],"responses":{"200":{"description":"Current balances, expiring batches and rate card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The token is valid but its account row is missing. Cannot be fixed client-side — contact support with the `X-Request-Id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Account not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.therightsfoundry.com/v1/credits\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n"},{"lang":"javascript","label":"JavaScript","source":"const res = await fetch('https://api.therightsfoundry.com/v1/credits', {\n  headers: { Authorization: 'Bearer YOUR_API_TOKEN' }\n});\nconst credits = await res.json();\n\nconsole.log(`${credits.api_credits.balance} credits left`);\nconsole.log(`${credits.api_credits.spendable} spendable before a 402`);\n\n// Budget the next call off the live rate card, not a hard-coded number.\nconst briefCost = credits.costs.deep_search_first_page;\nif (credits.api_credits.spendable < briefCost) {\n  throw new Error('Top up before running a Deep Search.');\n}\n\nconst next = credits.expiring_credits.find((b) => b.api_credits > 0);\nif (next) {\n  console.log(`${next.api_credits} credits expire on ${next.expires_at}`);\n}\n"},{"lang":"python","label":"Python","source":"import requests\n\nAUTH = {\"Authorization\": \"Bearer YOUR_API_TOKEN\"}\n\ncredits = requests.get(\n    \"https://api.therightsfoundry.com/v1/credits\", headers=AUTH\n).json()\n\nprint(f\"{credits['api_credits']['balance']} credits left\")\n\n# Free to call, so check before a charged search rather than\n# discovering the shortfall as a 402 halfway through a batch.\nif credits[\"api_credits\"][\"spendable\"] < credits[\"costs\"][\"file_search_first_page\"]:\n    raise SystemExit(\"Not enough credits for Acoustic Similarity Search.\")\n\nfor batch in credits[\"expiring_credits\"]:\n    print(f\"{batch['api_credits']} credits expire {batch['expires_at']}\")\n"}]}},"/v1/tracks/{id}":{"get":{"operationId":"getTrack","summary":"Get track by ID","description":"Retrieve a single track by its ID. If the track is a root track with alternative versions (instrumental, acoustic, etc.), the `child_tracks` array will contain all variants with their own signed preview URLs (`asset_url`, `peak_data_url`).\n\n### Credits\n\nA single-track fetch is charged at `track_detail` regardless of how many child tracks come back. It returns the full record plus fresh signed streaming URLs for every variant. If you only need to confirm an ID or read its listing row, `GET /v1/tracks?id=...&includeChildren=true` does that at `tracks_list`; it returns no `child_tracks`, and without `includeChildren=true` a child ID comes back empty. The operator can retune either rate; read the live values from `GET /v1/credits`.\n","tags":["Tracks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Track ID (client_id)","schema":{"type":"integer"},"example":29446060}],"responses":{"200":{"description":"Track details with alternative versions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/TrackWithChildren"}}},"examples":{"withAlternatives":{"summary":"Track with alternative versions (abridged — every Track field is returned)","value":{"success":true,"data":{"id":29446060,"title":"Forever Yours","artist":"Dominik Hauser","asset_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.mp3?expires=1774530330&sig=abc...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.json?expires=1774530330&sig=def...","has_alternatives":true,"child_tracks":[{"id":29446061,"title":"Forever Yours (Instrumental)","artist":"Dominik Hauser","asset_url":"https://assets.therightsfoundry.com/stream/AB12/29446061/29446061_track.mp3?expires=1774530330&sig=ghi...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29446061/29446061_track.json?expires=1774530330&sig=jkl..."},{"id":29446062,"title":"Forever Yours (Acoustic)","artist":"Dominik Hauser","asset_url":"https://assets.therightsfoundry.com/stream/AB12/29446062/29446062_track.mp3?expires=1774530330&sig=mno...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29446062/29446062_track.json?expires=1774530330&sig=pqr..."}]}}},"withoutAlternatives":{"summary":"Track without alternatives (abridged)","value":{"success":true,"data":{"id":29446060,"title":"Stand Alone Track","artist":"Artist Name","asset_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.mp3?expires=1774530330&sig=abc...","peak_data_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.json?expires=1774530330&sig=def...","has_alternatives":false,"child_tracks":[]}}}}}}},"400":{"description":"Invalid track ID format — the path must contain 1–15 decimal digits. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Invalid track ID"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient credits. The request was not charged: the API cost would exceed its overdraft floor, or the existing bandwidth balance is already below its own floor. Catalog calls deduct no bandwidth. A single-track fetch is charged at `track_detail`; a balance that refuses this call may still cover `GET /v1/tracks?id=...&includeChildren=true` at `tracks_list` if confirming the ID is all you need. Top-ups reduce the debt; add enough to cover it and the next request. Call `GET /v1/credits` (free, uncharged) for the current balance, how much overdraft is left and the live rates.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"},"example":{"success":false,"error":"Insufficient credits. Please top up to continue.","apiCredits":-8,"bandwidthBytes":5368709120}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Track not found. Nothing is charged — the track is looked up before your balance is touched. Confirm IDs with `GET /v1/tracks?id=...&includeChildren=true` (charged at `tracks_list`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"error":"Track not found"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/BillingUnavailable"}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"# Get track with all alternative versions\ncurl \"https://api.therightsfoundry.com/v1/tracks/29446060\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n"},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\n  'https://api.therightsfoundry.com/v1/tracks/29446060',\n  { headers: { Authorization: 'Bearer YOUR_API_TOKEN' } }\n);\nconst { data } = await response.json();\n\nconsole.log(`${data.title} by ${data.artist}`);\nif (data.has_alternatives) {\n  console.log(`${data.child_tracks.length} alternative version(s):`);\n  data.child_tracks.forEach(alt => console.log(`  - ${alt.title}`));\n}\n"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.therightsfoundry.com/v1/tracks/29446060\",\n    headers={\"Authorization\": \"Bearer YOUR_API_TOKEN\"}\n)\ntrack = response.json()[\"data\"]\n\nprint(f\"{track['title']} by {track['artist']}\")\nfor alt in track.get(\"child_tracks\", []):\n    print(f\"  Alternative: {alt['title']}\")\n"}]}},"/v1/tracks/{id}/sync":{"post":{"operationId":"createSyncLink","summary":"Sync Track Download","description":"Get a signed, expiring download link to the track's **WAV master** — the full-quality delivery file, not the preview.\n\nThis is the only endpoint that exposes the master. The `asset_url` on every catalog response is a 128 kbps MP3 preview for auditioning; it is unchanged by this endpoint. Preview billing is designed to run the other way around from the master: its link is free, and playback is what is intended to be charged. Streams are metered but not yet billed — see *Preview billing runs in the opposite direction by design* below. When you have chosen a track and need the full-quality file for your production, call this.\n\n### Standard sync or Export Sync — `external_export`\n\nThe request body is optional. It takes one field, `external_export` (boolean, default `false`):\n\n| `external_export` | Use it when | Charged at |\n|---|---|---|\n| `false` — the default; also what an empty body or no body means | Standard in-app / in-platform sync: the track is synchronized and the result is used inside the platform | **`costs.sync`** (`sync_cost`) |\n| `true` — **Export Sync** | The user will use the synchronized output or the audio file **offline**, or **place, export or distribute it outside** the platform — for example downloading the final synced video or audio for external publishing, client delivery, broadcast, social media, or offline use | **`costs.export_sync`** (`export_sync_cost`) |\n\nBoth modes return the same WAV master link and follow the same billing rules below. They are separate licences, so they keep **independent 1-hour free-reissue windows per track**: a live standard link does not make an Export Sync request free (it is charged at `export_sync` and opens its own window), and a live export link does not make a standard request free. `data.external_export` in the response confirms which mode the link was issued under.\n\nThe body is validated strictly before anything is looked up or charged: it must be a JSON object whose only key is `external_export`, and that value must be a JSON boolean (`\"true\"`, `1` and `null` are rejected). Anything else answers `400` and costs nothing.\n\n### A new access window is charged at issue, never at transfer\n\nThis is the opposite of how most download APIs bill, so it is worth stating plainly:\n\n- The **`sync` cost (or `export_sync` with `external_export: true`) comes off when this endpoint issues a link for a new access window**. Reissues within a paid window are free.\n- **Downloading the file is free.** Fetch the returned `download_url` once or fifty times, resume it, range-request it — none of that is charged in credits.\n- **A link you already hold can be replaced free.** Call this endpoint again for the same track — with the same `external_export` value — while your current link is still valid and you get a fresh `download_url` back with `credits_charged: 0` and `reissued: true`. Lose a link to a crashed job and you are not paying twice.\n- **The re-issued link inherits the original expiry.** It does not start a new hour. Once `expires_at` passes, the next request is a new, charged request.\n- **The window is per account, per track and per mode** (standard sync or Export Sync). Any token on the account gets the free re-issue, and only a *charged* link opens a window — a free re-issue never extends one. Two first requests for the same track that arrive at the same instant can both find no live link and both be charged, so if several workers may sync the same track, serialize that call per track. If the operator makes `sync` free, those issuances do not open a paid window; without one, each request gets a new expiry and `reissued: false`.\n\nBilling at `sync` and `export_sync` counts charged link issuances; free reissues and byte transfers do not add a charge. The dashboard reports link issuances separately from streaming usage.\n\n### Preview billing runs in the opposite direction by design\n\nThe MP3 preview on every catalog response runs in the opposite direction, and it pays to hold both rules in your head at once:\n\n| | Link | Bytes |\n|---|---|---|\n| WAV master (this endpoint) | charged at `sync` (or `export_sync`) for a new window; reissues are free | free |\n| MP3 preview (`asset_url`) | free | intended to be charged per stream at `costs.stream`; metered but not yet billed |\n\nToday a preview stream is metered but **not yet deducted from any balance**. Stream costs are a documented coming change: each preview stream will be charged from API credits at `costs.stream`. The master transfer is free by design; do not assume previews will stay free. See *Which way the charge runs* in the API overview.\n\n### Response\n\n| Field | Meaning |\n|---|---|\n| `download_url` | Signed URL to the WAV master. Valid until `expires_at`. |\n| `format` | Always `wav` for this endpoint. |\n| `file_name` | Suggested filename for the download. |\n| `expires_at` | ISO 8601 expiry of the link. |\n| `expires_in` | Seconds remaining, for a client that would rather not do date math. |\n| `credits_charged` | The `sync` rate (or `export_sync` for an Export Sync) for this call, or `credits_charged: 0` on a free reissue. |\n| `reissued` | `true` when this replaced a still-valid link of the same mode and was not charged. |\n| `external_export` | `false` for standard sync, `true` for Export Sync — the mode this link was issued and charged under. |\n| `billing` | The rule above, restated in the payload so it reaches code as well as readers. |\n\n### Usage reporting\n\nEvery link issued is recorded against your account and your token. Your [dashboard](https://therightsfoundry.com/dashboard) reports, for the last 30 days: distinct **tracks synced**, total **links generated** (split into charged and free re-issues), **sync credits spent**, and how many of your links are **still valid**.\n","tags":["Tracks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Track ID (client_id)","schema":{"type":"integer"},"example":29446060}],"requestBody":{"required":false,"description":"Optional. Omit it, or send an empty body or `{}`, for standard sync. Send `{\"external_export\": true}` for Export Sync.\n","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"external_export":{"type":"boolean","default":false,"description":"`false` (default): standard in-app / in-platform sync, charged at `costs.sync`.\n`true`: Export Sync — required when the synchronized output or the audio file will be used\noffline, or placed, exported or distributed outside the platform (external publishing,\nclient delivery, broadcast, social media, offline use). Charged at `costs.export_sync`,\nwith its own 1-hour free-reissue window per track.\n"}}},"examples":{"standard_sync":{"summary":"Standard sync (same as no body)","value":{"external_export":false}},"external_export_sync":{"summary":"Export Sync — offline use or placing outside the platform","value":{"external_export":true}}}}}},"responses":{"200":{"description":"A signed link to the WAV master","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SyncLink"}}},"examples":{"charged":{"summary":"First request — charged","value":{"success":true,"data":{"id":29446060,"title":"Golden Hour","artist":"Marta Vellum","format":"wav","file_name":"29446060_track.wav","download_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.wav?expires=1774530330&sig=abc...","expires_at":"2026-09-08T21:45:30.000Z","expires_in":3600,"credits_charged":200,"reissued":false,"external_export":false,"billing":{"charged_on":"api_call","note":"Credits are deducted for this API call, which creates the link — not for downloading the file. Downloading this link, however many times, costs nothing while it is valid. Requesting a link for this track again before it expires returns a fresh link free of charge; after it expires, the next request is charged again."}}}},"reissued":{"summary":"Repeat request inside the window — free","value":{"success":true,"data":{"id":29446060,"title":"Golden Hour","artist":"Marta Vellum","format":"wav","file_name":"29446060_track.wav","download_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.wav?expires=1774530330&sig=abc...","expires_at":"2026-09-08T21:45:30.000Z","expires_in":2840,"credits_charged":0,"reissued":true,"external_export":false,"billing":{"charged_on":"api_call","note":"Credits are deducted for this API call, which creates the link — not for downloading the file. Downloading this link, however many times, costs nothing while it is valid. Requesting a link for this track again before it expires returns a fresh link free of charge; after it expires, the next request is charged again."}}}},"export_charged":{"summary":"Export Sync (`external_export: true`) — charged at export_sync","value":{"success":true,"data":{"id":29446060,"title":"Golden Hour","artist":"Marta Vellum","format":"wav","file_name":"29446060_track.wav","download_url":"https://assets.therightsfoundry.com/stream/AB12/29446060/29446060_track.wav?expires=1774530400&sig=def...","expires_at":"2026-09-08T21:46:40.000Z","expires_in":3600,"credits_charged":200,"reissued":false,"external_export":true,"billing":{"charged_on":"api_call","note":"Credits are deducted for this API call, which creates the link — not for downloading the file. Downloading this link, however many times, costs nothing while it is valid. Requesting a link for this track again before it expires returns a fresh link free of charge; after it expires, the next request is charged again."}}}}}}}},"400":{"description":"Malformed track ID (the path must contain 1–15 decimal digits), or an invalid request body: malformed JSON, anything other than a JSON object, an unknown key, or an `external_export` that is not a JSON boolean (`\"true\"`, `1` and `null` are rejected). Nothing is charged and no link is issued.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"badId":{"summary":"Malformed track ID","value":{"success":false,"error":"Invalid track ID"}},"badBody":{"summary":"external_export is not a boolean","value":{"success":false,"error":"Bad Request","message":"external_export must be a boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Insufficient credits — the API cost would exceed its overdraft floor, or the existing bandwidth balance is already below its own floor. Catalog calls deduct no bandwidth. Nothing was charged and no link was issued. A repeat request for a track whose link is still valid is never charged and cannot produce this status. Call `GET /v1/credits` (free, uncharged) for the current balance, how much overdraft is left and the live `sync` rate.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCredits"},"example":{"success":false,"error":"Insufficient credits. Please top up to continue.","apiCredits":-8,"bandwidthBytes":5368709120}}}},"403":{"$ref":"#/components/responses/SyncForbidden"},"404":{"description":"Either the track does not exist, or it has no WAV master available. **Nothing is charged in either case** — the API checks track metadata and excludes a known unavailable master prefix before billing. It does not check the file in storage at issuance. A later `404` when fetching an issued URL does not automatically refund the `sync` charge.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"noMaster":{"summary":"Track exists but has no master","value":{"success":false,"error":"No sync master is available for this track"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"503":{"$ref":"#/components/responses/BillingUnavailable"}},"x-codeSamples":[{"lang":"shell","label":"cURL","source":"# Standard sync (no body). A new window costs costs.sync;\n# a live-window reissue and download are free.\ncurl -X POST \"https://api.therightsfoundry.com/v1/tracks/29446060/sync\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\"\n\n# Export Sync: the output or file will be used offline or placed outside\n# the platform. A new export window costs costs.export_sync.\ncurl -X POST \"https://api.therightsfoundry.com/v1/tracks/29446060/sync\" \\\n  -H \"Authorization: Bearer YOUR_API_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"external_export\": true}'\n\n# Fetch the master with the returned link — no credits deducted.\ncurl -o track.wav \"PASTE_THE_download_url_HERE\"\n"},{"lang":"javascript","label":"JavaScript","source":"// Standard sync: a new window costs costs.sync; a live-window reissue is free.\n// Set exportSync = true when the result will be used offline or placed\n// outside the platform — charged at costs.export_sync instead.\nconst exportSync = false;\nconst res = await fetch(\n  'https://api.therightsfoundry.com/v1/tracks/29446060/sync',\n  {\n    method: 'POST',\n    headers: {\n      Authorization: 'Bearer YOUR_API_TOKEN',\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({ external_export: exportSync }),\n  }\n);\nconst { data } = await res.json();\n\nconsole.log(`Charged ${data.credits_charged} credits`);  // free if reissued\nconsole.log(`Export Sync: ${data.external_export}`);\nconsole.log(`Link valid for ${data.expires_in}s`);\n\n// Downloading costs nothing, now or again before it expires.\nconst audio = await fetch(data.download_url);\nconst wav = await audio.arrayBuffer();\n"},{"lang":"python","label":"Python","source":"import requests\n\nHEADERS = {\"Authorization\": \"Bearer YOUR_API_TOKEN\"}\n\n# Standard sync: a new window costs costs.sync; a live-window\n# reissue and download are free.\nres = requests.post(\n    \"https://api.therightsfoundry.com/v1/tracks/29446060/sync\",\n    headers=HEADERS,\n)\n\n# Export Sync: use this instead when the output or file will be used\n# offline or placed outside the platform (costs.export_sync).\nres = requests.post(\n    \"https://api.therightsfoundry.com/v1/tracks/29446060/sync\",\n    headers=HEADERS,\n    json={\"external_export\": True},\n)\ndata = res.json()[\"data\"]\nprint(f\"Charged {data['credits_charged']} credits, \"\n      f\"export={data['external_export']}, \"\n      f\"link valid {data['expires_in']}s\")\n\n# Free: the signed link carries its own authorization.\nwav = requests.get(data[\"download_url\"]).content\nwith open(data[\"file_name\"], \"wb\") as f:\n    f.write(wav)\n"}]}}},"tags":[{"name":"Tracks","description":"Search, filter, and retrieve music tracks from the catalog. The API provides access to **100,000+ fully licensed tracks** with rich metadata including genres, moods, instruments, themes, BPM, duration, and more.\n\n### Three Search Modes\n\n- `GET /v1/tracks` — field filters plus a lexical `search` that understands the catalog's own vocabulary (see `GET /v1/taxonomies`). No search provider is involved. It is charged at `tracks_list`, or `tracks_search_first_page` / `tracks_search_next_page` with `search`. Use it when you know the genre, mood, instrument or words you want.\n- `POST /v1/tracks/deep-search` — **Deep Search**: natural-language search. Use it when you have a brief, a mood, or a scene to describe.\n- `POST /v1/tracks/search` with `file_url` — **Acoustic Similarity Search**. Use it when you have a direct link to an `.mp3`/`.wav` and want catalog tracks that are acoustically similar to it.\n\nBoth `POST` endpoints are relevance-ordered and priced separately, each with its own pair of rate-card keys: a Deep Search first page is charged at `deep_search_first_page`, an Acoustic Similarity Search first page at `file_search_first_page`; later pages of either cost 1 credit each (`deep_search_next_page`, `file_search_next_page`). Read the live values from `GET /v1/credits`.\n\n### Track Hierarchy\n\nTracks can have **alternative versions** (instrumentals, acoustic versions, etc.). Root tracks are returned by default. Use `includeChildren=true` to include all versions in search results, or use the single track endpoint to see all alternatives.\n\n### Signed Streaming URLs\n\nEach track response includes `asset_url` and `peak_data_url` — HMAC-signed URLs that expire after 1 hour. Use `asset_url` for audio playback and `peak_data_url` for waveform visualization. The links are free; each play of `asset_url` is metered per stream. That usage is recorded today and not yet deducted from any balance, and stream costs are a documented coming change — see *Which way the charge runs* in the API overview.\n"},{"name":"Credits","description":"Your account's spending power. `GET /v1/credits` is free and uncounted, subject to token authentication and any reached daily cap: it reports the API credits left and the interim bandwidth allowance, the overdraft you may still dip into, the credits that expire next, and the rate card currently in force.\n\nBalances are **per account**, not per token — several tokens on one account draw down the same pool. The per-token call and API response-data counters ride along in the same response; they do not measure streamed audio.\n\nRead `costs` from this endpoint instead of hard-coding the rate table: the operator can retune any rule without a new API version, and this endpoint exposes the rules currently used by the API, subject to cache propagation.\n"}]}