The Rights Foundry (https://therightsfoundry.com/) is music rights infrastructure operated by AudioSocket: royalty-free music for commercial and creative sync, with programmable licensing across 85,000+ tracks of cleared, human-made music (61,784 original recordings plus instrumental and alternate versions). Developers and AI systems search the catalog, stream signed MP3 previews and license broadcast-quality WAV masters in one API call. Calls are paid from a prepaid fiat credit balance, topped up directly or through an optional monthly plan.
rightsfoundry is the official Python client for that API. It is typed, has zero runtime dependencies, and is built so that a bug in your code does not spend credits you did not mean to spend.
Website · API Reference · Get an API Key · Claim Free Beta Credits · For Builders · Licensing Terms · MCP Connector
- Why rightsfoundry?
- Install
- 60-second quickstart
- Three ways to search
- Understanding billing: sync vs stream
- Credit guardrails, budgets and auto-pagination
- Configuration
- Per-call options
- AsyncIO and web backends
- Typed error handling and charge state
- Retries and money safety
- Hooks and logging
- Command line
- GitHub Action
- Building AI agents?
- Security and supply chain
- FAQ
- License in one call.
client.tracks.sync(track_id)returns a signed, 1-hour link to the track's WAV master, and that call is the licence transaction. You do not open a ticket or wait for an approval email. An AI agent can do the same through the MCP connector. - Prepaid fiat credits. You top up a balance and every charged call draws from it. Your live prices come from
GET /v1/credits, and the SDK reads them from there. It never hard-codes a price. - Reissues inside the 1-hour sync window are free. If you ask again for the same track and mode while the link is valid, you get
credits_charged == 0,reissued is Trueand the original expiry. Concurrentsync()calls for the same track on one client are merged into a single HTTP request. - Zero runtime dependencies. The SDK uses only the standard library (
http.client,ssl,json,zlib,asyncio,hashlib). The CI build fails if the built wheel or sdist declares a dependency. - Money-safe defaults. Charged calls are not retried when the outcome is ambiguous. Each call can carry a credit cap that is checked before anything is sent. Iterators accept a budget. Every error tells you whether the call was charged (
charge_state). - Secure by construction. The SDK requires TLS 1.2+ with certificate verification, never follows redirects, reads response bodies up to a size limit, and validates
base_urlagainst an allowlist. The API key is wrapped in a type that refuses to print or pickle it, and logs show only a fingerprint ([REDACTED fp=1a2b3c4d]) that matches the one on /dashboard/token. - Sync and async clients.
Clientis thread-safe andAsyncClientis task-safe. They expose the same methods, models and errors, and iterators work with bothforandasync for. - Fully typed. The package ships
py.typedand passesmypy --strict. Responses decode into frozen dataclasses that keep the original JSON in.raw, so fields the API adds later are still available. Models pickle andcopy.deepcopycleanly, so they can travel throughmultiprocessing, Celery or a cache.
pip install rightsfoundry
# or
uv add rightsfoundryPython 3.9–3.14 (CPython). Python 3.9 is past upstream end-of-life, so the SDK emits a one-time DeprecationWarning on 3.9.
Create an API key at therightsfoundry.com/dashboard/token. New accounts can claim free beta credits: promotional welcome credits, granted when you save a payment method on your account (not at registration). If you use them up inside the promotion window, the account moves to the Starter Beta monthly plan unless you cancel that transition from your billing dashboard. See current plan and auto-conversion terms on therightsfoundry.com. Keep the key in your environment or a secret manager:
export TRF_API_KEY="…" # paste your key; never commit itThe path from a creative brief to a licensed WAV master:
import rightsfoundry
client = rightsfoundry.Client() # reads TRF_API_KEY from the environment, once
# 1. Describe what you need in plain language. Charged at costs.deep_search_first_page.
results = client.tracks.deep_search(
"warm hopeful acoustic guitar for a nature documentary",
limit=10,
instrumental=True,
)
if not results.data:
raise SystemExit("No matches; try a broader brief")
track = results.data[0]
print(track.id, track.title, "by", track.artist, f"{track.duration}s")
# 2. License it. Returns a signed 1-hour link to the WAV master, charged at costs.sync.
link = client.tracks.sync(track.id)
print("charged:", link.credits_charged, "reissued:", link.reissued, "expires:", link.expires_at)
# 3. Download the master. This is free and atomic, and no Authorization header goes to the asset host.
path = client.sync_links.download(link, "./masters/")
print("saved", path)This spends one deep_search_first_page and one sync; the download is free. A runnable version is in examples/01_quickstart_brief_to_wav.py.
Store track IDs, not signed URLs. Every response signs its URLs afresh. A stored
asset_urlordownload_urlstops working after an hour. Keeptrack.idand fetch a new link when you need one.
| Mode | SDK method | HTTP | Use it when | Charged at (costs key) |
|---|---|---|---|---|
| Filter | client.tracks.list(...) / .iter(...) |
GET /v1/tracks |
You know which fields to constrain: genre, mood, instrument, BPM, duration, key, vocals, or full-text search |
tracks_list; with a non-empty search, page 1 at tracks_search_first_page and later pages at tracks_search_next_page |
| Deep Search | client.tracks.deep_search(query, ...) / .deep_search_iter(...) |
POST /v1/tracks/deep-search |
You have a natural-language brief ("tense heist build-up, no vocals") | page 1 at deep_search_first_page, later pages at deep_search_next_page, the next-page rate from GET /v1/credits |
| Acoustic Similarity Search | client.tracks.search_similar(file_url, ...) / .search_similar_iter(...) |
POST /v1/tracks/search |
You have a reference recording or temp track (public .mp3/.wav) |
page 1 at file_search_first_page, later pages at file_search_next_page, the next-page rate from GET /v1/credits |
# Filter: deterministic, exact tag matches, stable pagination.
page = client.tracks.list(
mood="uplifting",
vocals="instrumental",
bpm_min=90,
bpm_max=120, # sent as bpmMin / bpmMax
duration_max=150, # seconds
sort_by="bpm",
sort_order="asc",
limit=20,
)
for t in page:
print(t.id, t.title, t.bpm, t.genres)
# Full-text search adds match metadata.
page = client.tracks.list(search="dark epic orchestral", limit=20)
print(page.total, page.relaxed, [c.to for c in page.corrections])
# Deep Search. Page 1 is charged every time it is sent, so ask for a large page once.
brief = client.tracks.deep_search("tense heist build-up with pizzicato strings", limit=50)
# Acoustic Similarity Search. An unreachable file is CHARGED, so the SDK validates the URL first.
similar = client.tracks.search_similar("https://cdn.example.com/temp-track.mp3", limit=20)
# One track with every alternate version (instrumental, acoustic, …). Charged at track_detail; a 404 is free.
full = client.tracks.get(track.id)
for alt in full.child_tracks:
print("alt:", alt.id, alt.title, alt.vocals)
# Every facet value you can filter on. Free.
taxonomies = client.taxonomies.list()
print(taxonomies.values("mood")[:10])limit is 1–100. The server silently caps larger values, so the SDK rejects them before sending, which means you never get fewer rows than you asked for without knowing it. String limits (search ≤ 200, a Deep Search query ≤ 500, …) are measured in UTF-16 code units, the way the server measures them, after surrounding whitespace and a leading byte-order mark are stripped. tracks.list accepts page, limit, search, genre, mood, instrument, theme, artist, album, vocals, key, bpm_min, bpm_max, duration_min, duration_max, featured, explicit, decade, id, include_children, sort_by, sort_order. Unknown keyword arguments are a TypeError.
Audio leaves the API by two routes, and they are charged in opposite directions on purpose:
| Audio | Getting the link | Moving the bytes |
|---|---|---|
WAV master: POST /v1/tracks/{id}/sync (client.tracks.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 while it is valid. |
MP3 preview: asset_url on every catalog response |
Free. It comes with the listing, search or detail call you already paid for. | Intended to be billed per stream (costs.stream) from API credits in a future update (metered today, not yet deducted). |
- Sync pays when the link is issued, not when the file transfers. A repeat request for the same account, track and mode while the link is valid is free (
credits_charged == 0,reissued is True) and keeps the originalexpires_at. Asking again does not extend access. Standard sync and Export Sync (external_export=True) each have their own window. - Stream charges the other way: the link is free and playback is what is intended to be billed, from API credits in a future update (metered today, not yet deducted). Plan 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.
GET /v1/creditsalready publishescosts.stream. - Other charged calls: listings (
tracks_list), detail (track_detail) and the searches above.credits.retrieve(),taxonomies.list(),health.*, downloads of signed URLs, and sync reissues inside the window are free. - The rate card is per account and can change at any time. Read it with
client.credits.retrieve().costs; never hard-code a price. Thosecostsalready include your plan discounts.
credits = client.credits.retrieve() # free and unmetered
need = credits.costs["deep_search_first_page"] + credits.costs["sync"]
if credits.api_credits.spendable < need:
raise SystemExit(f"Need {need} credits, have {credits.api_credits.spendable}")
for batch in credits.expiring_credits:
print(f"{batch.api_credits} credits expire at {batch.expires_at}")api_credits.spendable is balance + overdraft_limit, and your balance may go negative within your account's overdraft. Balances are per account, so every key on the account draws from the same pool. The full set of cost keys and the retry rules are in docs/billing-and-retries.md.
These guards run on the client side. They are meant to stop a runaway loop before it spends your balance. The server's 402 is still the final word on what an account can spend.
import rightsfoundry
def alert(event: rightsfoundry.LowCreditEvent) -> None:
# Edge-triggered: fires once per drop below the threshold. Keep it fast (enqueue, don't email inline).
print(f"low credits: {event.spendable} < {event.threshold} (source={event.source})")
client = rightsfoundry.Client(
max_credits_per_request=25, # refuse any single call projected above 25 credits
low_credit_warning_threshold=1_000, # call on_low_credit when spendable drops below this
on_low_credit=alert,
auto_check_credits=True, # preflight: refresh balance (free) at most every 30 s
guard_failure_mode="closed", # default: if prices can't be read, refuse rather than guess
)
# Per-call override: allow this one sync above the client-wide cap.
link = client.tracks.sync(track_id, max_credits=200)| Guard | What it does | Error (nothing is sent) |
|---|---|---|
max_credits_per_request / per-call max_credits= |
Projects the call's cost from your live rate card (GET /v1/credits, cached rate_card_ttl_ms = 60 s) and refuses if it is above the cap. sync is projected at full price. |
CreditCapExceededError (.projected, .cap, .cost_key) |
auto_check_credits=True |
Before each charged call, estimates spendable − cost from a balance snapshot (refreshed every credit_check_ttl_ms = 30 s) and refuses if it would go below zero. min_bandwidth_bytes adds a bandwidth floor. |
PreflightInsufficientCreditsError (.resource = api_credits or bandwidth) |
guard_failure_mode |
"closed" (default) refuses when the rate card cannot be read or has no price for the call. "open" logs a warning and sends anyway. |
CreditGuardUnavailableError |
low_credit_warning_threshold + on_low_credit |
Watches spendable from credits.retrieve(), 402 bodies and, with auto_check_credits, local estimates. Without a callback it logs a warning. |
— (callback, never raises) |
Iterator max_credits= |
A budget for a whole walk. The next page's cost is projected before it is sent. | CreditBudgetExceededError (.spent_projected, .next_cost, .cap) |
Auto-pagination. Every page is charged, so iterators are lazy and bounded by default:
# Walk a filtered catalogue: at most 40 credits and 1,000 tracks, 100 per page (the fewest charged calls).
it = client.tracks.iter(genre="jazz", vocals="instrumental", max_items=1_000, max_credits=40)
try:
for track in it:
index(track.id, track.title, track.genres)
except rightsfoundry.CreditBudgetExceededError as e:
print(f"stopped before page costing {e.next_cost}; ~{e.spent_projected} credits spent")
# Page by page, for example to checkpoint progress:
for page in client.tracks.iter(mood="calm").pages():
checkpoint(page.page, [t.id for t in page])
# AI searches paginate too (candidate set ≤ 1,000 → at most 10 pages at limit 100).
for t in client.tracks.deep_search_iter("lo-fi study beats with vinyl crackle", max_credits=15):
...Iterators stop at the end of the result set (page * limit >= total), on an empty page, at max_pages (default 50), at max_items, or before going over max_credits. A short page does not end the walk.
Iterators are single-use. Looping over an iterator (or its .pages()) a second time raises rightsfoundry.IteratorConsumedError (a RightsFoundryError and a RuntimeError) instead of silently sending, and paying for, every page again. To walk the results again, call client.tracks.iter(...) again.
Values are resolved in this order: keyword argument, then environment variable (read once, when the client is constructed), then the default. Every option is checked at construction, and an invalid value raises ConfigurationError straight away rather than on the first request.
| Option | Default | Env var | Notes |
|---|---|---|---|
api_key |
— (required) | TRF_API_KEY |
128 hex characters. Passing api_key=None explicitly does not fall back to the env var. |
environment |
"production" |
TRF_ENVIRONMENT |
"production" or "staging" (staging keys work only on staging) |
base_url |
from environment |
TRF_BASE_URL |
HTTPS only; host must be a Rights Foundry API host or in allowed_hosts (code only) |
connect_timeout / read_timeout |
10 s / 60 s | TRF_CONNECT_TIMEOUT / TRF_READ_TIMEOUT |
Every method also takes timeout= (per-call options) |
total_timeout |
None |
— | Wall-clock limit across all attempts and backoff |
max_retries |
2 | TRF_MAX_RETRIES |
0–10, gated by money safety |
charged_retry_policy |
"refund_backed" |
— | "never", "refund_backed" or "always" |
max_retry_after_ms |
30 000 | — | A longer Retry-After is raised as an error instead of slept on |
max_credits_per_request |
None |
TRF_MAX_CREDITS_PER_REQUEST |
Client-side cap per charged call |
low_credit_warning_threshold / on_low_credit |
None |
TRF_LOW_CREDIT_WARNING_THRESHOLD |
Edge-triggered low-balance callback |
auto_check_credits |
False |
TRF_AUTO_CHECK_CREDITS |
Preflight balance check before charged calls |
guard_failure_mode |
"closed" |
— | Code only: no env var can make a guard fail open |
on_request / on_response / on_error |
None |
— | Hooks receive redacted, immutable events |
logger |
silent rightsfoundry logger |
TRF_LOG |
off, error, warn, info, debug |
user_agent_suffix |
None |
TRF_USER_AGENT_SUFFIX |
e.g. "acme-editor/4.2" |
custom_headers |
{} |
— | X-… and W3C trace headers only; sent to the API host, never to the asset host |
ca_bundle |
system trust store | TRF_CA_BUNDLE |
Trusts this PEM bundle instead of the system store; verification stays on |
proxy_url |
none | HTTPS_PROXY, NO_PROXY |
http:// or https:// CONNECT proxy (with https://, TLS to the proxy, then CONNECT, then TLS to the API); TLS to the API is always end to end. Other schemes such as socks5:// raise ConfigurationError naming the source (proxy_url or HTTPS_PROXY) |
max_connections |
10 | — | Per-host pool size (also the AsyncClient worker count) |
max_concurrency |
None |
— | Limit on in-flight requests per AsyncClient |
max_response_bytes / max_download_bytes |
10 MiB / 2 GiB | — | Hard body limits |
taxonomies_cache_ttl_ms |
0 (off) | — | In-process cache for the free taxonomies.list() |
Use client.with_options(...) to get a client with a few options changed. It shares the original's connection pool and re-checks the merged configuration:
batch_client = client.with_options(max_credits_per_request=5, charged_retry_policy="never")The full option list (write_timeout, jitter, retryable_status_codes, asset_hosts, allow_insecure_localhost, transport, …) is in llms-full.txt.
Every typed method (tracks.list, .iter, .get, .deep_search, .search_similar, .sync, taxonomies.list, credits.retrieve, health.check, .live, .ready) accepts these keywords for a single call:
| Keyword | Effect |
|---|---|
timeout= |
Seconds for this call (0 < t ≤ 600) |
max_retries= |
Retry budget for this call (0–10), replacing the client's max_retries; the money-safety rules still apply |
idempotency_key= |
Sent as Idempotency-Key (printable ASCII without spaces, 1–255 characters). With a key, ambiguous outcomes are retried even under "refund_backed"; see Retries and money safety |
send_max_credits_header= |
With a cap in force, also sends X-TRF-Max-Credits: <cap> so the server can enforce it once it supports the header (forward-compatible; ignored today) |
max_credits= |
Charged methods only: a client-side cap on the projected cost; nothing is sent if it would be exceeded |
The same fields are bundled in rightsfoundry.CallOptions, a frozen dataclass (timeout, max_credits, max_retries, idempotency_key, send_max_credits_header) that client.request() also accepts:
import uuid
import rightsfoundry
link = client.tracks.sync(track_id, max_credits=200, timeout=30, idempotency_key=f"order-{order_id}")
page = client.tracks.list(mood="calm", max_retries=0)
opts = rightsfoundry.CallOptions(timeout=20, max_credits=10, idempotency_key=str(uuid.uuid4()))
data = client.request("GET", "/v1/tracks", query={"mood": "calm", "limit": 5}, options=opts)client.request() is the escape hatch for endpoints added to the API before an SDK release. It runs the full pipeline (auth, guards, retries, redaction, bounded reads), supports GET, POST, PUT, PATCH, DELETE and HEAD, returns None for a 204 or an empty 2xx body, and returns JSON arrays and primitives as they are.
AsyncClient has the same surface as Client: every method can be awaited, and iterators are consumed with async for.
import asyncio
import rightsfoundry
async def main() -> None:
async with rightsfoundry.AsyncClient() as client:
credits = await client.credits.retrieve()
print(credits.api_credits.spendable)
page = await client.tracks.list(mood="uplifting", limit=10)
async for track in client.tracks.deep_search_iter("cinematic sunrise swell", max_credits=10):
print(track.id, track.title)
asyncio.run(main())Create one AsyncClient per event loop, for example in your app's lifespan. By default it runs the same hardened http.client transport in a bounded thread pool; set max_concurrency= to limit in-flight requests.
The API key is an account secret and stays on your server. Browsers get only what they need: track metadata and the signed preview asset_url. Never send the key to a browser, mobile app or client bundle.
# FastAPI (pip install fastapi uvicorn). The full runnable version is in examples/03.
from contextlib import asynccontextmanager
from fastapi import FastAPI
import rightsfoundry
@asynccontextmanager
async def lifespan(app: FastAPI):
async with rightsfoundry.AsyncClient(max_credits_per_request=10) as client:
app.state.trf = client
yield
app = FastAPI(lifespan=lifespan)
@app.get("/api/tracks")
async def tracks(mood: str):
page = await app.state.trf.tracks.list(mood=mood, limit=20)
return [
{"id": t.id, "title": t.title, "artist": t.artist, "duration": t.duration, "preview_url": t.asset_url}
for t in page.data
]- Django / Flask: create one module-level
rightsfoundry.Client()(it is thread-safe) or put it in your app factory, and call it from views. Return the same small dicts. - Every proxied browser request spends your credits. Put authentication and rate limiting in front of these endpoints, and set
max_credits_per_request. - Previews are metered and intended to be billed from API credits in a future update (not yet deducted). Do not auto-play, and do not hand out preview URLs nobody asked for.
- Cloudflare Workers: Python Workers run on Pyodide/WebAssembly, where
http.clientsockets are unavailable, and the SDK refuses that platform. From a Worker, call the REST API withfetchand keep the key in a Worker secret, or run this SDK on a server and have the Worker call it.
Every error is a subclass of rightsfoundry.RightsFoundryError and carries .status, .request_id, .operation, .charge_state, .retry_after and .attempts. str(err) always includes the request_id, so quote it when you contact support.
import rightsfoundry as rf
try:
link = client.tracks.sync(track_id)
except rf.InsufficientCreditsError as e: # 402
notify_billing(e.api_credits) # balance before the refused charge
except rf.FeatureNotEnabledError as e: # 403; e.feature == "sync" or "deep_search"
show("Sync licensing is not enabled for this key. Contact support.")
except (rf.TrackNotFoundError, rf.SyncMasterUnavailableError):
mark_unlicensable(track_id) # free 404s, never retried
except rf.CreditCapExceededError as e: # client-side, nothing sent
log.warning("blocked: %s would cost %s > cap %s", e.cost_key, e.projected, e.cap)
except rf.APIStatusError as e:
log.error("TRF %s %s (request %s, charge %s)", e.status, e, e.request_id, e.charge_state)
raisecharge_state tells you what the server did with your money:
charge_state |
Meaning | Raised for |
|---|---|---|
"not_charged" |
Nothing was deducted | All client-side errors (ValidationError, CreditGuardError, ConfigurationError); 400 (except below), 401, 402, 403, 404, 405, 410, 429; BillingUnavailableError (request not served, pending deduction cancelled); connect-phase failures |
"refund_pending" |
A charge was recorded and a best-effort refund is queued | 500 InternalServerError on charged calls; 503 SearchUnavailableError |
"charged" |
You paid, and no refund will come | UnreachableFileError: Acoustic Similarity Search could not fetch or decode your file_url |
"unknown" |
The call may or may not have been charged | Read timeouts or resets after the request was sent; 408, 502, 504 |
The main families are ValidationError (incl. InvalidTrackIdError), CreditGuardError, APIConnectionError (incl. APITimeoutError with .phase, and TLSVerificationError, which is never retried), APIStatusError (BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError → InvalidTokenError/InactiveTokenError/ExpiredTokenError/FeatureNotEnabledError, NotFoundError, RateLimitError → DailyCallLimitError, InternalServerError, ServiceUnavailableError → BillingUnavailableError/SearchUnavailableError), SyncLinkError (SyncLinkExpiredError, SyncLinkInvalidError), ResponseTooLargeError, UnexpectedRedirectError, UnexpectedResponseError and HealthCheckError. The full table of exact server messages is in llms-full.txt.
Catalogue and AI-search calls are charged before the work is done, and the API does not honour idempotency keys yet. Retrying a call that actually succeeded would charge you twice. The SDK therefore decides whether to retry based on what the server guarantees about money for each outcome:
| Outcome | free ops |
sync |
charged ops, refund_backed (default) |
charged, never |
charged, always |
|---|---|---|---|---|---|
| Connect failure (request never written) | retry | retry | retry | retry | retry |
429 |
retry* | retry* | retry* | retry* | retry* |
503 billing unavailable (not served) |
retry | retry | retry | no | retry |
503 search unavailable (refunded) |
— | — | retry | no | retry |
500 (refund queued) |
retry | retry | retry | no | retry |
408, 502, 504 (outcome unknown) |
retry | retry | no† | no | retry |
| Read timeout / reset after send | retry | retry | no† | no | retry |
† Retried when the call carries idempotency_key= (see below).
* Only if Retry-After ≤ max_retry_after_ms (30 s by default). A daily-cap 429 on an MCP connection asks you to wait until 00:00 UTC, so it is raised immediately as DailyCallLimitError with .reset_at.
synccan be retried even when the outcome is ambiguous. The server records each paid window under a per-(account, track, mode) lock, so a retry either reissues for free or pays once.- With
idempotency_key=, ambiguous outcomes are retried (408,502,504, read-phase connection failures) even under"refund_backed", because once the API honours the key the server will recognise a repeat and charge once. This is forward-compatible: the SDK sends the key today, and your calls get full retry safety as soon as the API honours it. Until then, a retried key-carrying call can still be charged twice, so use a key only where that risk is acceptable or where you reconcile withcredits.retrieve(). - Health probes are not retried by default (
max_retries=0): a degraded503comes back at once asHealthStatus(status="degraded"). Passmax_retries=2to retry. - Backoff is exponential with CSPRNG full jitter (500 ms → 8 s) and never shorter than the server's
Retry-After. - A success that followed a refundable failure is flagged with
retried_after_refundable_failure=TrueonTrackPageandSyncLink, so your reconciliation code can explain a temporary double deduction. charged_retry_policy="always"buys availability at the risk of paying twice. Choose it deliberately.
Hooks receive immutable, already redacted events. They cannot change the outgoing request. If a hook raises, the exception is logged and swallowed, and it never fails your call.
client = rightsfoundry.Client(
on_request=lambda e: print("→", e.operation, e.method, e.url, e.cost_key, e.projected_credits),
on_response=lambda e: metrics.timing("trf.call", e.duration_ms, tags={"op": e.operation, "status": e.status}),
on_error=lambda e: print("✗", e.operation, e.status, e.charge_state, "retry" if e.will_retry else "final"),
)
print(client)
# Client(environment='production', base_url='https://api.therightsfoundry.com', api_key=[REDACTED fp=1a2b3c4d], ...)- URLs in events and logs have
sig=[REDACTED].Authorizationappears asBearer [REDACTED fp=…], and any 128-hex run becomes[REDACTED_TOKEN]. Response headers are allowlisted, andset-cookieis never exposed. client.api_key_fingerprintreturns the same 8-character fingerprint that /dashboard/token shows, so you can tell which key a process is using without revealing the key.- The library logger
rightsfoundryis silent by default. SetTRF_LOG=debugto get one redacted line per attempt, or passlogger=. - Use
SyncLink.redacted_download_url()andTrack.redacted_asset_url()whenever a link goes to a log.
The package installs a rightsfoundry command (also python -m rightsfoundry). It reads the key from TRF_API_KEY only, never from a flag, so the key does not end up in shell history or ps output.
rightsfoundry health # no key needed, free
rightsfoundry credits # balance + your rate card, free
rightsfoundry taxonomies --facet mood # free
rightsfoundry search "dark epic" --vocals instrumental --bpm-min 90 --bpm-max 120 --limit 10
rightsfoundry deep-search "warm hopeful acoustic guitar" --instrumental --limit 10 --max-credits 20
rightsfoundry similar https://cdn.example.com/temp-track.mp3 --limit 10
rightsfoundry track 123456
rightsfoundry sync 123456 --download ./masters/ # standard sync
rightsfoundry sync 123456 --external-export --download ./masters/ # Export SyncAdd --json for machine-readable output and --environment staging for staging. Global flags such as --json and --environment work before or after the subcommand. JSON output is ASCII-escaped, so catalogue text cannot put control or bidirectional characters on your terminal. Exit codes: 0 ok, 1 API or network error, 2 usage, validation or guard error, 3 health not healthy. Human-readable output redacts signed URLs.
You can search the catalogue and license masters from a workflow. Save this as .github/workflows/soundtrack.yml and add a repository secret named TRF_API_KEY:
name: soundtrack
on:
workflow_dispatch:
permissions:
contents: read
jobs:
soundtrack:
runs-on: ubuntu-24.04
steps:
- id: search
uses: therightsfoundry/trf-python@v1
with:
action: deep-search
api-key: ${{ secrets.TRF_API_KEY }}
query: "upbeat corporate background, no vocals"
instrumental: "true"
max-credits: "50"
- id: sync
if: steps.search.outputs.track-id != ''
uses: therightsfoundry/trf-python@v1
with:
action: sync
api-key: ${{ secrets.TRF_API_KEY }}
track-id: ${{ steps.search.outputs.track-id }}
download-path: masters/
max-credits: "200"Actions: deep-search, search, search-similar, track, sync, credits, health. Outputs: result-json (with signatures redacted), track-id, track-title, track-artist, downloaded-file, credits-charged, credits-spendable, request-id. The key and every signature are masked in the log, and catalogue text runs inside ::stop-commands:: so it cannot issue workflow commands. The action needs Python 3.9 or newer on the runner and runs it in isolated mode (python3 -I), so nothing in the checked-out workspace can be imported in its place. @v1 follows the latest 1.x release; for production, pin the action to a commit SHA. The full reference and recipes are in docs/github-action.md, and a complete workflow is in examples/github_workflow_soundtrack.yml.
- MCP connector:
https://mcp.therightsfoundry.com/mcp. It works with any MCP client that supports remote servers and OAuth: the user signs in with their Rights Foundry account, and the agent never handles an API key. Its tools let the agent browse the catalogue, read a track, list taxonomies, read the licensing terms and license a track. Directory metadata is at the server card. - Writing your own agent loop? Wrap this SDK in tools.
docs/llm-and-mcp-guide.mdhas OpenAI- and Anthropic-style tool schemas fordeep_search,list,syncandcredits, plus the safety rules: cap credits per tool call, require human approval beforesync, and never give the model the API key. - Machine-readable docs:
llms.txt(index) andllms-full.txt(the complete SDK reference in one file). Coding assistants should readAGENTS.md.
-
Zero runtime dependencies.
dependencies = []. CI asserts it on the built wheel and sdist, then imports the wheel in a fresh venv installed with--no-deps. -
TLS 1.2+ with certificate and hostname verification, using the SDK's own
SSLContext, soPYTHONHTTPSVERIFY=0and patched default contexts do not affect it. There is noverify=Falseoption. -
Redirects are never followed, so your
Authorizationheader cannot be carried to another host. Signed downloads go only toassets.therightsfoundry.com(https, port 443,/stream/…?expires=…&sig=…) and are sent no credentials, custom headers or cookies. -
SSRF and injection defence: strict
base_urlallowlist (no IP literals, no userinfo, no env-var override of the host allowlist), ASCII track IDs only, an allowlist of typed query parameters,file_urlchecks, and header values that cannot contain CR, LF or NUL. -
Secret fingerprint. The key is held in
rightsfoundry.Secret. Itsrepr,strandformatshow[REDACTED fp=1a2b3c4d], which is the same fingerprint as /dashboard/token. Pickling a key, config or client raisesTypeError. -
Bounded everything: 10 MiB response limit (counted after gzip decompression, so a decompression bomb is stopped too), JSON nesting ≤ 64, no NaN/Infinity, 2 GiB download limit. Downloads are written to an exclusively created
0600temp file,fsynced, and atomically renamed; symlinks are refused. Withresume=True, the hidden partial file is keyed by a hash of the URL path, so one track never appends onto another's partial, and if a ranged resume fails the SDK truncates the partial and retries once with a full download. -
Models are safe to log and share. Models pickle and
copy.deepcopycleanly..rawis an immutable, read-only mapping whosestr()andrepr()redact signed-URLsigvalues; indexing it still returns the real value. -
Provenance. Releases are built in GitHub Actions and published to PyPI through Trusted Publishing (OIDC, no stored tokens), with PEP 740 attestations and GitHub build provenance. To verify a downloaded file:
pip download rightsfoundry==1.0.0 --no-deps -d dist/ gh attestation verify dist/<file> --repo therightsfoundry/trf-python
-
Report vulnerabilities privately: see
SECURITY.md. Every control (SEC-01 to SEC-20) is described indocs/security.md.
Residual risks you own: the key sits in plaintext in process memory and in the environment variable it came from, and child processes inherit that variable. For long-running services, read the key from a secret manager and pass api_key= explicitly. Error trackers that capture frame locals (e.g. Sentry with include_local_variables) should keep their default scrubbing of authorization turned on.
How do I license music programmatically via API in Python?
Install rightsfoundry, set TRF_API_KEY, find a track (client.tracks.list, .deep_search or .search_similar), then call client.tracks.sync(track_id). That single call is the licence transaction: it charges costs.sync and returns a signed 1-hour link to the WAV master, which client.sync_links.download(link, "./masters/") saves to disk. See the quickstart.
Can I use licensed music in YouTube videos, commercials, apps, or AI-generated videos?
It depends on where the finished content is used, not on how the video was made. A standard sync licence (tracks.sync(id)) allows one-time synchronization of the track and use of the resulting content on online third-party platforms, without monetization. An Export Sync licence (tracks.sync(id, external_export=True), charged at export_sync) adds use of the synced output or audio file offline, and placing, exporting or distributing it outside the platform (for example client delivery, broadcast, social media or offline playback). A track synced into an AI-generated video is licensed the same way as any other video. For monetized uploads, paid advertising, or any use not described here, read the licensing terms before you publish; they govern, and this README only summarises them. If you are unsure, ask info@therightsfoundry.com.
Are the tracks human-made or AI-generated?
The catalogue is cleared, human-made music. Each Track also carries AI musical analysis fields, including is_ai_music and ai_music_score. These come from an automated audio classifier and are None for tracks that were never analysed.
Can I use The Rights Foundry catalog to train AI models? No. Sync licences cover synchronizing music into videos, apps, games, podcasts and similar productions. They do not grant AI or machine-learning training rights. Licensing training data is a separate agreement: see Licensed AI training data and the licensing terms.
Is there a free tier? How is it priced?
Usage is paid from prepaid credits, topped up directly or through an optional monthly plan. New accounts can claim free beta credits: promotional welcome credits, granted when you save a payment method on your account. If they are used up inside the promotion window, the account moves to the Starter Beta monthly plan unless you cancel that transition; current plan and auto-conversion terms are on therightsfoundry.com. Prices are per call and are read live from GET /v1/credits (client.credits.retrieve().costs), which is free. Do not hard-code prices, because the rate card can change without a new API version. Health, taxonomies, the credits call itself, signed-URL downloads and sync reissues inside the window are free.
Does the SDK work in the browser?
No, by design. The API key can spend your whole account's balance. The SDK refuses Pyodide/WebAssembly runtimes unless you pass dangerously_allow_browser=True, and you should not pass it. Call the API from your server and send the browser only track metadata and signed preview URLs.
Which Python versions are supported?
CPython 3.9–3.14. CI runs every version on Linux and 3.11–3.14 on macOS and Windows. Python 3.9 is past upstream end-of-life and triggers a one-time DeprecationWarning. Support for it will be dropped in a future minor release, announced in the changelog.
Where do I get help? API reference: docs.therightsfoundry.com. Builder overview: therightsfoundry.com/for-builders. Bugs and feature requests: GitHub issues, but never paste your API key or a signed URL there. Account and licensing questions: info@therightsfoundry.com.
MIT. See LICENSE. The SDK is MIT-licensed; the music is licensed under The Rights Foundry's licensing terms.
Website · API Reference · OpenAPI · PyPI · Changelog · Security · Privacy · Terms