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.

    ## Getting Started

    1. **Get an API token** from your [dashboard](https://therightsfoundry.com/dashboard/token)
    2. **Add the token** to authenticated API requests as a Bearer token in the `Authorization` header
    3. **Find tracks** — filter by genre, mood, BPM and more, describe what you want in plain language, or match a reference recording by sound
    4. **Preview or stream audio** using the signed URLs returned in track responses
    5. **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

    ## Every endpoint at a glance

    | Call | What it does | Charged at (`costs` key) | Audio it returns | License it grants |
    |---|---|---|---|---|
    | `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 |
    | `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 |
    | `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 |
    | `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 |
    | `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 |
    | `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 |
    | `GET /v1/taxonomies` | The genres, moods, instruments and other values you can filter on | Free | — | — |
    | `GET /v1/credits` | Your balance, overdraft, credits about to expire, and the live rate card | Free | — | — |
    | `GET /v1/health` | Service status | Free | — | — |

    Preview 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.

    ## Which way the charge runs: sync vs stream

    Audio 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.

    | Audio | Getting the link | Moving the bytes |
    |---|---|---|
    | **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 |
    | **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 |

    **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.

    **Stream reverses that direction by design: the link is free; playback is what is intended to be charged. Streams are not yet billed.**

    > **Where stream billing stands today — read this before you budget.**
    > 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**.
    >
    > **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`.

    ## Authentication

    All 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.

    ```
    Authorization: Bearer YOUR_API_TOKEN
    ```

    Charged 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.

    ## Your first call

    Three requests, no code. `curl` and a token are all you need.

    ```bash
    export RF_TOKEN="paste your token here"

    # 1. Is the API up? No token needed, nothing charged.
    curl https://api.therightsfoundry.com/v1/health

    # 2. Does my token work, and what can I spend? Free.
    curl https://api.therightsfoundry.com/v1/credits \
      -H "Authorization: Bearer $RF_TOKEN"

    # 3. Five piano tracks with streaming previews. Charged at costs.tracks_list.
    curl "https://api.therightsfoundry.com/v1/tracks?instrument=piano&limit=5" \
      -H "Authorization: Bearer $RF_TOKEN"
    ```

    Open 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.

    ## From brief to master, end to end

    The 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.

    ```python
    # Python 3.9+. pip install requests. Export RF_TOKEN first.
    import os
    import requests

    BASE = "https://api.therightsfoundry.com"
    S = requests.Session()
    S.headers["Authorization"] = f"Bearer {os.environ['RF_TOKEN']}"


    def call(method, path, **kw):
        r = S.request(method, BASE + path, timeout=60, **kw)
        if r.status_code == 402:
            raise SystemExit(f"Out of credits: {r.json()}")
        if not r.ok:
            raise SystemExit(f"{r.status_code} {r.text} (X-Request-Id {r.headers.get('X-Request-Id')})")
        return r.json()


    # 1. Budget off the live rate card, not this page. Free call.
    credits = call("GET", "/v1/credits")
    costs = credits["costs"]
    need = costs["deep_search_first_page"] + costs["track_detail"] + costs["sync"]
    if credits["api_credits"]["spendable"] < need:
        raise SystemExit(f"Need {need} credits, have {credits['api_credits']['spendable']} spendable")

    # 2. Deep Search. Every page 1 is charged at deep_search_first_page, so ask for a big page once.
    hits = call("POST", "/v1/tracks/deep-search",
                json={"query": "warm hopeful acoustic guitar for a nature documentary", "limit": 50})
    if not hits["data"]:
        raise SystemExit("No matches — try a broader brief")
    pick = hits["data"][0]
    print(pick["id"], pick["title"], "—", pick["artist"])

    # 3. Audition. The MP3 preview needs no token. Playing it is metered, not yet billed.
    preview = requests.get(pick["asset_url"], timeout=60)
    preview.raise_for_status()
    open("preview.mp3", "wb").write(preview.content)

    # 4. Full record with alternative versions (instrumental and so on). Charged at costs.track_detail.
    track = call("GET", f"/v1/tracks/{pick['id']}")["data"]
    for alt in track["child_tracks"]:
        print("  alt:", alt["id"], alt["title"], alt["vocals"])

    # 5. The WAV master. Charged at costs.sync when the link is issued; the download is free.
    link = call("POST", f"/v1/tracks/{pick['id']}/sync")["data"]
    wav = requests.get(link["download_url"], timeout=600)  # no Authorization header
    wav.raise_for_status()
    open(link["file_name"], "wb").write(wav.content)
    print(f"Saved {link['file_name']}; this call charged {link['credits_charged']} credits")
    ```

    Listing 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.

    ## Three Ways to Search

    The catalog has three search modes. Pick the one that matches how you know what you want:

    - **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".
    - **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.
    - **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.

    Both `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.

    ## Two ways to get audio for different purposes

    - **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.
    - **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.
    - **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`.

    | Purpose | Call | Audio | License it grants |
    |---|---|---|---|
    | 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 |
    | 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 |
    | 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 |

    ## Credits

    Every 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.

    | Operation | Condition | `costs` key |
    |---|---|---|
    | `GET /v1/tracks` | `search` absent or empty — browse or filter, any page | `tracks_list` |
    | `GET /v1/tracks` | With a nonempty `search`, `page` omitted or `1` | `tracks_search_first_page` |
    | `GET /v1/tracks` | With a nonempty `search`, `page` 2 or higher | `tracks_search_next_page` |
    | `GET /v1/tracks/{id}` | Track exists; includes all returned alternatives | `track_detail` |
    | `POST /v1/tracks/deep-search` — Deep Search | `page` omitted or `1` | `deep_search_first_page` |
    | `POST /v1/tracks/deep-search` — Deep Search | `page` 2 or higher — 1 credit per page | `deep_search_next_page` |
    | `POST /v1/tracks/search` — Acoustic Similarity Search | `page` omitted or `1` | `file_search_first_page` |
    | `POST /v1/tracks/search` — Acoustic Similarity Search | `page` 2 or higher — 1 credit per page | `file_search_next_page` |
    | `POST /v1/tracks/{id}/sync` | No body, or `external_export: false` — a link is issued (a repeat within a paid window is free) | `sync` |
    | `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` |
    | `GET /v1/taxonomies` | Every call | free |
    | `GET /v1/credits` | Every call | free, and not counted |
    | `GET /v1/health` | Every call | free, no token |
    | Playing a preview (`asset_url`) | Every stream | `stream` — published, **not yet charged**; see *Which way the charge runs* |
    | Fetching any other signed URL | Every fetch | free in credits |

    Every 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`.

    ## Checking Your Balance

    `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:

    ```
    curl https://api.therightsfoundry.com/v1/credits -H "Authorization: Bearer YOUR_API_TOKEN"
    ```

    Your 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.

    Balances are **per account**. Every token on the account draws down the same pool; the call and API response-data counters are per token.

    ## Rate Limits & Usage

    - 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.
    - **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.**
    - View your usage on the [dashboard](https://therightsfoundry.com/dashboard).

    ## Errors

    Errors 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.

    | Status | Meaning | Charged? | What to do |
    |---|---|---|---|
    | `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. |
    | `401` | No `Authorization: Bearer …` header | No | Add the header. A wrong token is `403`, not `401`. |
    | `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. |
    | `403` | Token unknown, revoked or expired | No | Issue a new token from the dashboard; for an MCP connection, reconnect. |
    | `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`. |
    | `405` | `GET` on a `POST`-only search or sync endpoint | No | Use `POST`. |
    | `429` | Daily cap on an MCP connection | No | Wait `Retry-After` seconds. |
    | `500` | Failure on our side | Any recorded charge gets an asynchronous, best-effort refund | Retry once; keep the `X-Request-Id`. |
    | `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. |

    Errors 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.

    ## Signed URLs

    Audio 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.

    - **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.
    - **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`.
    - **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.
    - **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.
    - **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.

    `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`.

  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:

        `Authorization: Bearer abc123...`

        Keep it server-side — see Signed URLs for how to give a browser playable audio without the token.

  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`.
          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.
          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

        # --- Audio analysis -------------------------------------------------
        # Machine-listening tags derived from the audio itself, alongside the
        # editorial tags above. `null` on the small number of tracks that have
        # not been analyzed; a track inherits its parent's analysis when it has
        # none of its own (see `tag_source`).
        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
            analyzed itself, `parent` means it inherited its parent track's analysis
            (typical for alternative versions). `null` means the track has no analysis.
          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.

                Normally: 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.

                When 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`.
      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.
            `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.
          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.

            **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.
          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`.
          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.
          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.
          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.
          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.
          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.
          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.
          example: null

    SyncLink:
      type: object
      description: |
        A signed link to a track's WAV master. A new access window is charged at `sync`
        (or `export_sync` when issued with `external_export: true`) when the link is
        issued; a reissue within a paid window of the same mode is free and inherits
        its expiry. Fetching `download_url` is never charged.
      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
            it is free — never charged in credits, no bandwidth deducted; it
            carries its own authorization, so no `Authorization` header is
            needed (and none should be sent).
          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
            mode, so this call returned a replacement free of charge and did not extend the expiry.
          example: false
        external_export:
          type: boolean
          description: |
            Which licence the link was issued under. `false`: standard sync, charged at `sync`.
            `true`: Export Sync — use of the synced output or audio file offline, or placing /
            exporting / distributing it outside the platform — charged at `export_sync`. Echoes the
            request (`false` when the body was empty). Each mode has its own reissue window.
          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`.
      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:

        - `Invalid API token` — unknown token. Check for a truncated paste (tokens are 128 hex characters), then issue a new one from the dashboard.
        - `API token is inactive` — revoked from the dashboard. Issue a new one.
        - `API token has expired` — only MCP connections expire (after 30 days). Reconnect the MCP client.
      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:

        - `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.
      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:

        - `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.
      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.
      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.
      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.
      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.

        All 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.

        This 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.

        ### Credits

        | Request | `costs` key |
        |---|---|
        | Browse or filter — `search` absent or empty | `tracks_list` |
        | With a nonempty `search` — page 1 (`page` omitted or `1`) | `tracks_search_first_page` |
        | With a nonempty `search` — page 2 onwards | `tracks_search_next_page` |

        The 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`.

        ### Quick Examples

        | Use Case | Query |
        |----------|-------|
        | Browse all tracks | `/v1/tracks` |
        | Search by keyword | `?search=summer+vibes` |
        | Filter by genre | `?genre=electronic` |
        | BPM range for DJ sets | `?bpmMin=120&bpmMax=130` |
        | Cinematic instrumentals | `?genre=cinematic&mood=epic&search=instrumental` (charged at `tracks_search_first_page`) |
        | Short tracks under 2 min | `?durationMax=120&sortBy=duration&sortOrder=asc` |
        | Find specific track | `?id=29446060` |
        | Include all versions | `?includeChildren=true` |

        Only 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`.

      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.
          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.
          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
            curl "https://api.therightsfoundry.com/v1/tracks?genre=electronic&mood=uplifting&limit=10" \
              -H "Authorization: Bearer YOUR_API_TOKEN"

            # BPM range for DJ sets (120-130 BPM)
            curl "https://api.therightsfoundry.com/v1/tracks?bpmMin=120&bpmMax=130&sortBy=bpm&sortOrder=asc" \
              -H "Authorization: Bearer YOUR_API_TOKEN"

            # Text search with genre filter
            curl "https://api.therightsfoundry.com/v1/tracks?search=summer+vibes&genre=pop" \
              -H "Authorization: Bearer YOUR_API_TOKEN"

            # Find specific track by ID
            curl "https://api.therightsfoundry.com/v1/tracks?id=29446060" \
              -H "Authorization: Bearer YOUR_API_TOKEN"
        - lang: javascript
          label: "JavaScript"
          source: |
            const API_URL = 'https://api.therightsfoundry.com';
            const TOKEN = 'YOUR_API_TOKEN';

            // Search for cinematic tracks
            const response = await fetch(
              `${API_URL}/v1/tracks?genre=cinematic&mood=epic&limit=10`,
              { headers: { Authorization: `Bearer ${TOKEN}` } }
            );
            const { data, total } = await response.json();
            console.log(`Found ${total} tracks`);

            // Stream audio from the first result
            if (data[0]?.asset_url) {
              const audio = new Audio(data[0].asset_url);
              audio.play();
            }
        - lang: python
          label: "Python"
          source: |
            import requests

            API_URL = "https://api.therightsfoundry.com"
            TOKEN = "YOUR_API_TOKEN"
            headers = {"Authorization": f"Bearer {TOKEN}"}

            # Search by BPM range + genre
            params = {"genre": "electronic", "bpmMin": 120, "bpmMax": 140, "limit": 20}
            response = requests.get(f"{API_URL}/v1/tracks", headers=headers, params=params)
            data = response.json()

            for track in data["data"]:
                print(f"{track['title']} by {track['artist']} ({track['bpm']} BPM)")
                print(f"  Stream: {track['asset_url']}")
        - lang: javascript
          label: "Node.js"
          source: |
            // npm install axios — save as example.mjs and run: node example.mjs
            import axios from 'axios';

            const API_URL = 'https://api.therightsfoundry.com';
            const TOKEN = 'YOUR_API_TOKEN';

            // Paginate through all piano tracks
            async function getAllPianoTracks() {
              let page = 1;
              let allTracks = [];

              while (true) {
                const { data } = await axios.get(`${API_URL}/v1/tracks`, {
                  headers: { Authorization: `Bearer ${TOKEN}` },
                  params: { instrument: 'piano', page, limit: 100 },
                });

                allTracks.push(...data.data);
                if (allTracks.length >= data.total) break;
                page++;
              }

              console.log(`Fetched ${allTracks.length} piano tracks`);
              return allTracks;
            }

            const tracks = await getAllPianoTracks();

  /v1/tracks/deep-search:
    post:
      operationId: searchTracksDeepSearch
      summary: Deep Search
      description: |
        Describe what you want in plain language and get relevance-ordered music back.

        > **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_*`).

        Send 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:

        | Example brief |
        |---|
        | `warm hopeful acoustic guitar for a nature documentary` |
        | `tense driving percussion for a chase scene` |
        | `sparse melancholy piano under a voiceover about loss` |

        There 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`.

        On 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.

        Results 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.

        ### Choosing between this and `GET /v1/tracks`

        | You want to… | Use |
        |---|---|
        | Describe a scene, mood, or brief in plain language | `POST /v1/tracks/deep-search` |
        | Find tracks that sound like an audio file you can link to | `POST /v1/tracks/search` with `file_url` |
        | Filter on exact fields — genre, mood, BPM range, duration, artist | `GET /v1/tracks` |
        | Sort by a field (title, BPM, date) or paginate the whole catalog | `GET /v1/tracks` |

        Results here are **always relevance-ordered** — there is no `sortBy`/`sortOrder`. For field-sorted browsing, stay on `GET /v1/tracks`.

        ### Credits

        This endpoint has its own rate-card keys, separate from `GET /v1/tracks`:

        | Request | `costs` key |
        |---|---|
        | Page 1 of a brief (`page` omitted or `1`) | `deep_search_first_page` |
        | Page 2 onwards, including a cache miss | `deep_search_next_page` |

        Later pages cost 1 credit each. Read the first-page rate from `GET /v1/credits`.

        Billing 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`.

        **What starts a new first-page charge — the main way to waste credits:**

        - 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`.
        - Changing `page` or `limit` does **not** — pages 2 and up of the same brief are always charged at `deep_search_next_page`.
        - 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.

        Worked 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.

        The 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`.

        ### Behavior notes

        - A search that matches nothing returns `200` with an empty `data` array and `total: 0` — not an error.
        - 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`.
        - This endpoint is **POST-only**. `GET /v1/tracks/deep-search` returns `405` with a reminder to use POST.

      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.
                  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`.
                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.
                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.
            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.
          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.
          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.
          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.
          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
            curl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \
              -H 'Authorization: Bearer YOUR_API_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"query": "warm hopeful acoustic guitar for a nature documentary", "limit": 20}'

            # Page 2 — costs.deep_search_next_page, even on a cache miss
            curl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \
              -H 'Authorization: Bearer YOUR_API_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"query": "warm hopeful acoustic guitar for a nature documentary", "page": 2, "limit": 20}'

            # Instrumental only, page 1 — costs.deep_search_first_page
            curl -X POST 'https://api.therightsfoundry.com/v1/tracks/deep-search' \
              -H 'Authorization: Bearer YOUR_API_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"query": "tense driving percussion for a chase scene", "instrumental": true}'
        - lang: javascript
          label: Node.js
          source: |
            // npm install axios — save as example.mjs and run: node example.mjs
            import axios from 'axios';

            const API_URL = 'https://api.therightsfoundry.com';
            const TOKEN = 'YOUR_API_TOKEN';

            async function deepSearch(body, retries = 2) {
              for (let attempt = 0; ; attempt++) {
                try {
                  const { data } = await axios.post(
                    `${API_URL}/v1/tracks/deep-search`, body,
                    { headers: { Authorization: `Bearer ${TOKEN}` } },
                  );
                  return data;
                } catch (err) {
                  // A search 503 attempts a refund; a billing 503 leaves
                  // the deduction unconfirmed. Retrying uses the page rate.
                  if (err.response?.status === 503 && attempt < retries) {
                    const waitSeconds = Number(err.response.headers['retry-after'] ?? attempt + 1);
                    await new Promise((r) => setTimeout(r, 1000 * waitSeconds));
                    continue;
                  }
                  throw err;
                }
              }
            }

            // Page 1 uses costs.deep_search_first_page, cached or not.
            // Fetch generously — up to 100 per page.
            const query = 'tense driving percussion for a chase scene';
            const first = await deepSearch({ query, limit: 100 });
            console.log(`${first.total} matches`);

            // Later pages use costs.deep_search_next_page, even on a cache miss.
            // Keep `query` and `instrumental` fixed for consistent paging.
            for (let page = 2; (page - 1) * 100 < first.total; page++) {
              const next = await deepSearch({ query, page, limit: 100 });
              console.log(`Page ${page}: ${next.data.length} tracks`);
              if (next.data.length === 0) break;
            }
        - lang: python
          label: Python
          source: |
            import time
            import requests

            API_URL = "https://api.therightsfoundry.com"
            TOKEN = "YOUR_API_TOKEN"
            HEADERS = {"Authorization": f"Bearer {TOKEN}"}


            def deep_search(body, retries=2):
                for attempt in range(retries + 1):
                    resp = requests.post(
                        f"{API_URL}/v1/tracks/deep-search", headers=HEADERS, json=body
                    )
                    if resp.status_code == 503 and attempt < retries:
                        # A search 503 attempts a refund; a billing 503 leaves
                        # the deduction unconfirmed. Retrying uses the page rate.
                        time.sleep(float(resp.headers.get("Retry-After", attempt + 1)))
                        continue
                    resp.raise_for_status()
                    return resp.json()


            # Page 1 uses costs.deep_search_first_page, cached or not.
            query = "warm hopeful acoustic guitar for a nature documentary"
            results = deep_search({"query": query, "limit": 20})

            for track in results["data"]:
                print(f"{track['title']} — {track['artist']} ({track['duration']}s)")

            # Later pages use costs.deep_search_next_page, even on a cache miss.
            # Keep `query` and `instrumental` fixed for consistent paging.
            if results["total"] > results["limit"]:
                page2 = deep_search({"query": query, "page": 2, "limit": 20})

  /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.

        > **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.

        Requirements for `file_url`:

        - A valid absolute `http(s)` URL, at most 2000 characters
        - Points to an **`.mp3` or `.wav`** file — the extension is checked; a `?query` or `#fragment` after it is fine
        - **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.
        - At most **120 MB** (upstream limit)
        - **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.

        Results 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.

        ### Credits

        The 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:

        | Request | `costs` key |
        |---|---|
        | Page 1 for a `file_url` (`page` omitted or `1`) | `file_search_first_page` |
        | Page 2 onwards, including a cache miss | `file_search_next_page` |

        Later pages cost 1 credit each. Read the first-page rate from `GET /v1/credits`.

        Billing 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`.

        **What starts a new first-page charge — the main way to waste credits:**

        - 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.
        - Changing `page` or `limit` does **not** — pages 2 and up of the same `file_url` are always charged at `file_search_next_page`.
        - 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.

        Worked 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.

        The 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`.

        ### Refunds on failure — 400 vs 503

        Two failure modes look superficially similar but are charged differently. Do not conflate them:

        - **`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`.
        - **`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.

        (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.)

        ### Behavior notes

        - A search that matches nothing returns `200` with an empty `data` array and `total: 0` — not an error.
        - This endpoint is **POST-only**. `GET /v1/tracks/search` returns `405` with a reminder to use POST.

      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.
                  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`.
                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.
                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.
            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.
          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:

            **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.

            **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.
          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.
          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.

            Do 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.
          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
            # goes in file_url. Page 1 uses costs.file_search_first_page; on a
            # cache miss the provider downloads and fingerprints the audio.
            curl -X POST 'https://api.therightsfoundry.com/v1/tracks/search' \
              -H 'Authorization: Bearer YOUR_API_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"file_url": "https://cdn.example.com/references/client-temp-track.mp3", "limit": 100}'

            # Page 2 — costs.file_search_next_page, even on a cache miss
            curl -X POST 'https://api.therightsfoundry.com/v1/tracks/search' \
              -H 'Authorization: Bearer YOUR_API_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"file_url": "https://cdn.example.com/references/client-temp-track.mp3", "page": 2, "limit": 100}'
        - lang: javascript
          label: Node.js
          source: |
            // npm install axios — save as example.mjs and run: node example.mjs
            import axios from 'axios';

            const API_URL = 'https://api.therightsfoundry.com';
            const TOKEN = 'YOUR_API_TOKEN';

            async function soundAlike(body, retries = 2) {
              for (let attempt = 0; ; attempt++) {
                try {
                  const { data } = await axios.post(`${API_URL}/v1/tracks/search`, body, {
                    headers: { Authorization: `Bearer ${TOKEN}` },
                  });
                  return data;
                } catch (err) {
                  const status = err.response?.status;
                  // A search 503 attempts a refund; a billing 503 leaves
                  // the deduction unconfirmed. Retrying uses the page rate.
                  if (status === 503 && attempt < retries) {
                    const waitSeconds = Number(err.response.headers['retry-after'] ?? attempt + 1);
                    await new Promise((r) => setTimeout(r, 1000 * waitSeconds));
                    continue;
                  }
                  // Validation 400s are uncharged; a download/decode 400
                  // retains the page-based charge. Fix the reported problem.
                  if (status === 400) {
                    console.error('Request rejected:', err.response.data.error);
                  }
                  throw err;
                }
              }
            }

            // Page 1 uses costs.file_search_first_page.
            // On a cache miss the provider downloads the file server-side.
            const file_url = 'https://cdn.example.com/references/client-temp-track.mp3';
            const similar = await soundAlike({ file_url, limit: 100 });
            console.log(`${similar.total} tracks sound like the reference`);

            // Later pages use costs.file_search_next_page, even on a cache miss.
            // Keep `file_url` and `instrumental` fixed for consistent paging.
            for (let page = 2; (page - 1) * 100 < similar.total; page++) {
              const next = await soundAlike({ file_url, page, limit: 100 });
              if (next.data.length === 0) break;
            }
        - lang: python
          label: Python
          source: |
            import time
            import requests

            API_URL = "https://api.therightsfoundry.com"
            TOKEN = "YOUR_API_TOKEN"
            HEADERS = {"Authorization": f"Bearer {TOKEN}"}


            def sound_alike(body, retries=2):
                for attempt in range(retries + 1):
                    resp = requests.post(
                        f"{API_URL}/v1/tracks/search", headers=HEADERS, json=body
                    )
                    if resp.status_code == 503 and attempt < retries:
                        # A search 503 attempts a refund; a billing 503 leaves
                        # the deduction unconfirmed. Retrying uses the page rate.
                        time.sleep(float(resp.headers.get("Retry-After", attempt + 1)))
                        continue
                    if resp.status_code == 400:
                        # Validation 400s are uncharged; a download/decode 400
                        # retains the page-based charge. Fix the reported problem.
                        raise RuntimeError(
                            f"Request rejected: {resp.json()['error']}"
                        )
                    resp.raise_for_status()
                    return resp.json()


            # Page 1 uses costs.file_search_first_page.
            # On a cache miss the provider downloads the file server-side.
            file_url = "https://cdn.example.com/references/client-temp-track.mp3"
            similar = sound_alike({"file_url": file_url, "limit": 20})
            print(f"{similar['total']} tracks sound like the reference")

            # Later pages use costs.file_search_next_page, even on a cache miss.
            # Keep `file_url` and `instrumental` fixed for consistent paging.
            if similar["total"] > similar["limit"]:
                page2 = sound_alike({"file_url": file_url, "page": 2, "limit": 20})

  /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.
      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.

        **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.

        ### The rate card — `costs`

        Every 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.

        | Key | Prices | Condition |
        |---|---|---|
        | `tracks_list` | `GET /v1/tracks` | `search` absent or empty. Every page, any filters |
        | `tracks_search_first_page` | `GET /v1/tracks` | Nonempty `search`, page 1 |
        | `tracks_search_next_page` | `GET /v1/tracks` | Nonempty `search`, page 2 or higher |
        | `track_detail` | `GET /v1/tracks/{id}` | Every successful call, however many `child_tracks` come back |
        | `deep_search_first_page` | `POST /v1/tracks/deep-search` — Deep Search | Page 1, every time it is sent, cached or not |
        | `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 |
        | `file_search_first_page` | `POST /v1/tracks/search` — Acoustic Similarity Search | Page 1, every time it is sent, cached or not |
        | `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 |
        | `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 |
        | `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 |
        | `stream` | Playing a preview `asset_url` | **Published, not yet charged.** Nothing deducts it today; stream costs are a coming change |

        Not 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.

        ### Reading the numbers

        - `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.
        - `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.
        - `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.
        - `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*.
        - `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.
        - `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.

        Balances 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.
      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" \
              -H "Authorization: Bearer YOUR_API_TOKEN"
        - lang: javascript
          label: "JavaScript"
          source: |
            const res = await fetch('https://api.therightsfoundry.com/v1/credits', {
              headers: { Authorization: 'Bearer YOUR_API_TOKEN' }
            });
            const credits = await res.json();

            console.log(`${credits.api_credits.balance} credits left`);
            console.log(`${credits.api_credits.spendable} spendable before a 402`);

            // Budget the next call off the live rate card, not a hard-coded number.
            const briefCost = credits.costs.deep_search_first_page;
            if (credits.api_credits.spendable < briefCost) {
              throw new Error('Top up before running a Deep Search.');
            }

            const next = credits.expiring_credits.find((b) => b.api_credits > 0);
            if (next) {
              console.log(`${next.api_credits} credits expire on ${next.expires_at}`);
            }
        - lang: python
          label: "Python"
          source: |
            import requests

            AUTH = {"Authorization": "Bearer YOUR_API_TOKEN"}

            credits = requests.get(
                "https://api.therightsfoundry.com/v1/credits", headers=AUTH
            ).json()

            print(f"{credits['api_credits']['balance']} credits left")

            # Free to call, so check before a charged search rather than
            # discovering the shortfall as a 402 halfway through a batch.
            if credits["api_credits"]["spendable"] < credits["costs"]["file_search_first_page"]:
                raise SystemExit("Not enough credits for Acoustic Similarity Search.")

            for batch in credits["expiring_credits"]:
                print(f"{batch['api_credits']} credits expire {batch['expires_at']}")

  /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`).

        ### Credits

        A 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`.

      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"
        "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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCredits'
              example:
                success: false
                error: "Insufficient credits. Please top up to continue."
                apiCredits: -8
                bandwidthBytes: 5368709120
        "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"
        "401":
          $ref: '#/components/responses/Unauthorized'
        "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: |
            # Get track with all alternative versions
            curl "https://api.therightsfoundry.com/v1/tracks/29446060" \
              -H "Authorization: Bearer YOUR_API_TOKEN"
        - lang: javascript
          label: "JavaScript"
          source: |
            const response = await fetch(
              'https://api.therightsfoundry.com/v1/tracks/29446060',
              { headers: { Authorization: 'Bearer YOUR_API_TOKEN' } }
            );
            const { data } = await response.json();

            console.log(`${data.title} by ${data.artist}`);
            if (data.has_alternatives) {
              console.log(`${data.child_tracks.length} alternative version(s):`);
              data.child_tracks.forEach(alt => console.log(`  - ${alt.title}`));
            }
        - lang: python
          label: "Python"
          source: |
            import requests

            response = requests.get(
                "https://api.therightsfoundry.com/v1/tracks/29446060",
                headers={"Authorization": "Bearer YOUR_API_TOKEN"}
            )
            track = response.json()["data"]

            print(f"{track['title']} by {track['artist']}")
            for alt in track.get("child_tracks", []):
                print(f"  Alternative: {alt['title']}")

  /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.

        This 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.

        ### Standard sync or Export Sync — `external_export`

        The request body is optional. It takes one field, `external_export` (boolean, default `false`):

        | `external_export` | Use it when | Charged at |
        |---|---|---|
        | `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`) |
        | `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`) |

        Both 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.

        The 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.

        ### A new access window is charged at issue, never at transfer

        This is the opposite of how most download APIs bill, so it is worth stating plainly:

        - 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.
        - **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.
        - **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.
        - **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.
        - **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`.

        Billing 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.

        ### Preview billing runs in the opposite direction by design

        The MP3 preview on every catalog response runs in the opposite direction, and it pays to hold both rules in your head at once:

        | | Link | Bytes |
        |---|---|---|
        | WAV master (this endpoint) | charged at `sync` (or `export_sync`) for a new window; reissues are free | free |
        | MP3 preview (`asset_url`) | free | intended to be charged per stream at `costs.stream`; metered but not yet billed |

        Today 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.

        ### Response

        | Field | Meaning |
        |---|---|
        | `download_url` | Signed URL to the WAV master. Valid until `expires_at`. |
        | `format` | Always `wav` for this endpoint. |
        | `file_name` | Suggested filename for the download. |
        | `expires_at` | ISO 8601 expiry of the link. |
        | `expires_in` | Seconds remaining, for a client that would rather not do date math. |
        | `credits_charged` | The `sync` rate (or `export_sync` for an Export Sync) for this call, or `credits_charged: 0` on a free reissue. |
        | `reissued` | `true` when this replaced a still-valid link of the same mode and was not charged. |
        | `external_export` | `false` for standard sync, `true` for Export Sync — the mode this link was issued and charged under. |
        | `billing` | The rule above, restated in the payload so it reaches code as well as readers. |

        ### Usage reporting

        Every 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**.

      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.
        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`.
                    `true`: Export Sync — required when the synchronized output or the audio file will be used
                    offline, or placed, exported or distributed outside the platform (external publishing,
                    client delivery, broadcast, social media, offline use). Charged at `costs.export_sync`,
                    with its own 1-hour free-reissue window per track.
            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.
          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'
        "403":
          $ref: '#/components/responses/SyncForbidden'
        "429":
          $ref: '#/components/responses/RateLimited'
        "500":
          $ref: '#/components/responses/ServerError'
        "503":
          $ref: '#/components/responses/BillingUnavailable'
        "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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCredits'
              example:
                success: false
                error: "Insufficient credits. Please top up to continue."
                apiCredits: -8
                bandwidthBytes: 5368709120
        "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.
          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"
      x-codeSamples:
        - lang: shell
          label: "cURL"
          source: |
            # Standard sync (no body). A new window costs costs.sync;
            # a live-window reissue and download are free.
            curl -X POST "https://api.therightsfoundry.com/v1/tracks/29446060/sync" \
              -H "Authorization: Bearer YOUR_API_TOKEN"

            # Export Sync: the output or file will be used offline or placed outside
            # the platform. A new export window costs costs.export_sync.
            curl -X POST "https://api.therightsfoundry.com/v1/tracks/29446060/sync" \
              -H "Authorization: Bearer YOUR_API_TOKEN" \
              -H "Content-Type: application/json" \
              -d '{"external_export": true}'

            # Fetch the master with the returned link — no credits deducted.
            curl -o track.wav "PASTE_THE_download_url_HERE"
        - lang: javascript
          label: "JavaScript"
          source: |
            // Standard sync: a new window costs costs.sync; a live-window reissue is free.
            // Set exportSync = true when the result will be used offline or placed
            // outside the platform — charged at costs.export_sync instead.
            const exportSync = false;
            const res = await fetch(
              'https://api.therightsfoundry.com/v1/tracks/29446060/sync',
              {
                method: 'POST',
                headers: {
                  Authorization: 'Bearer YOUR_API_TOKEN',
                  'Content-Type': 'application/json',
                },
                body: JSON.stringify({ external_export: exportSync }),
              }
            );
            const { data } = await res.json();

            console.log(`Charged ${data.credits_charged} credits`);  // free if reissued
            console.log(`Export Sync: ${data.external_export}`);
            console.log(`Link valid for ${data.expires_in}s`);

            // Downloading costs nothing, now or again before it expires.
            const audio = await fetch(data.download_url);
            const wav = await audio.arrayBuffer();
        - lang: python
          label: "Python"
          source: |
            import requests

            HEADERS = {"Authorization": "Bearer YOUR_API_TOKEN"}

            # Standard sync: a new window costs costs.sync; a live-window
            # reissue and download are free.
            res = requests.post(
                "https://api.therightsfoundry.com/v1/tracks/29446060/sync",
                headers=HEADERS,
            )

            # Export Sync: use this instead when the output or file will be used
            # offline or placed outside the platform (costs.export_sync).
            res = requests.post(
                "https://api.therightsfoundry.com/v1/tracks/29446060/sync",
                headers=HEADERS,
                json={"external_export": True},
            )
            data = res.json()["data"]
            print(f"Charged {data['credits_charged']} credits, "
                  f"export={data['external_export']}, "
                  f"link valid {data['expires_in']}s")

            # Free: the signed link carries its own authorization.
            wav = requests.get(data["download_url"]).content
            with open(data["file_name"], "wb") as f:
                f.write(wav)


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.

      ### Three Search Modes

      - `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.
      - `POST /v1/tracks/deep-search` — **Deep Search**: natural-language search. Use it when you have a brief, a mood, or a scene to describe.
      - `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.

      Both `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`.

      ### Track Hierarchy

      Tracks 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.

      ### Signed Streaming URLs

      Each 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.

  - 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.

      Balances 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.

      Read `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.
