Music Credits API

Credits Graph network — identifier nodes (isrc, iswc, ipi, isni, upc) plus musician (people) nodes, and connections around one code, with per-connection source provenance and verification status (verified = 2+ independent sources, single = one). Node no_match lists directions checked with no counterpart (verified absence); typed ISRC↔ISRC relationships (cover, sample, remix, …) appear as kind: relation connections, people credits as kind: credit. Every node carries a credits_id. Explore third-order by re-querying any node at depth=1 and merging.

Credits Graph status feed — recent changes of every type across the index, newest first: link_found, link_verified (connection crossed 2+ independent sources), relation_found (cover/sample/remix), no_match_recorded (verified absence). Poll with since set to the previous response as_of for deltas (clamped to 24h).

Music Identity discovery JSON (path templates, links). Same payload as GET /v1/. Full interactive reference: api.credits.fm/docs.

Bucketed Music Identity search (all, artist, song, recording, release, musician, publisher). Default limit 20 per bucket (max 500; -1 capped). Optional exclude_lyrics, nocache.

Unified search across identifiers. Each bucket is { items, pagination } with snake_case pagination (has_more, total, limit, offset, count). Supports match=recording_title, exclude_lyrics, CDN bypass (nocache, no_cache, fresh). For bucketed Music Identity search with a different type vocabulary, use GET /v1/graph/search.

Fast autocomplete across identifier types. q optional; min 2 characters when provided. limit/offset window ≤ 1000.

Cross-collection typeahead (Typesense-backed). Prefix + typo-tolerant autocomplete across recordings, songs, releases, publishers/writers, and artists. Response shape matches /v1/suggest so clients can share a parser. Falls back to PG /v1/suggest when Typesense is not configured.

Up to ten example identifiers per type from the live index (ISRC, ISWC, IPI, ISNI, UPC, MBID). Use to build working detail URLs against your deployment.

Service health: database reachability and critical table row thresholds. 503 when unavailable or below threshold. Same checks as GET /healthz on api.credits.fm.

Recording by ISRC (snake_case). Flat document by default; graph query keys return Music Identity graph (human-readable /v1/recordings/{isrc} 308s here). See api.credits.fm/docs for the full parameter matrix.

Authoritative live MLC Public Work Search by ISRC — work(s) with writer chains, ISWCs, publishers, and alternative titles. Cached 14 days server-side; pass ?refresh=true to force a fresh MLC fetch. source is cache | live | stale | unavailable. Empty works means no MLC registration (or temporary unavailability when source is unavailable).

Musical work by ISWC. Flat work row or Music Identity graph (/v1/songs/{iswc} 308s here). For large recording lists use graph + include / pagination — not the old credits.fm-only complete query.

Songwriter or publisher by IPI. represent=musician|publisher drives graph shape; older /v1/musicians/… / /v1/publishers/… paths 308 here.

All publishers that co-occur with this songwriter IPI. Optional include=isrcs for shared ISRC lists per publisher.

Creative contributor by ISNI. Flat document, optional isrcs/iswcs pagination, or graph mode. Includes recordings_url → GET /v1/isni/{isni}/recordings.

Release by UPC/EAN (snake_case flat row or graph). Older /v1/releases/{upc} paths 308 here. No contribution hints on flat rows.

Musician profile (MusicBrainz MBID) — songwriter + performer credits, groups, identifiers. Fields are snake_case where emitted.

DSP release-artist discography (snake_case).

Resolve Spotify or Apple Music URLs to identifiers and metadata (snake_case).

Resolve a track to ISRC + credits (name/artist and/or platform URLs). Optional contribute in JSON body.

Resolve songwriter name to IPI using ISRC/ISWC context (snake_case response fields).

Batch-resolve tracks (up to 50 {name, artist} pairs) to ISRCs.

Batch lookup — up to 100 identifiers per type per request (snake_case maps). MusicBrainz fallback where configured. Public: does not validate x-api-key (header ignored). A 200 here does not prove an API key is valid — use POST /v1/contribute to test credentials.

Analyze an ISRC catalog into a publisher → writer-IPI → ISWC graph. Pass a flat isrcs list for ad-hoc lookups, or a pre-grouped songs array to reproduce a publisher catalog structure. Powers catalog tooling and POST /v1/catalog/analyze clients.

Submit index improvements. Requires cfm_… key registered in api_keys (same Supabase project as lookups). Request/response use snake_case (e.g. target_id in results). If batch works with the same header but this returns 401, the key is invalid or not cfm_-prefixed — not a separate database.

Index row counts / coverage metrics (snake_case nested keys).

Multi-source verification for one identifier (type: isrc | iswc | ipi | isni | upc). Per-field agreement across Notes Credits, MusicBrainz, DSPs, CISAC, ISNI.org as applicable. Optional ?raw=1 for adapter debug payloads.

Batch verify up to 100 { type, code } items. Invalid rows return inline { error, input }; order preserved.

Validate ISRCs against MLC (+ optional DSP cross-check). ?format=csv supported. Results use snake_case.

Songwriter share-ownership audit. Not currently available on the public API — ownership share percentages are withheld pending licensing, so this endpoint returns 403. Songwriter/publisher names, roles, IPIs and relationships remain available on the lookup endpoints.

MLC match status audit. ?format=csv supported.

Create a free cfm_… API key (name + email). Returns the secret once. Max 3 active keys per email. Same flow as the key form at credits.fm/api.

Batch ISWC titles + ISRC metadata (title, artists) for lazy UI loads. Public; capped per array server-side.

Cover art URLs for up to 10 ISRCs (cache + Spotify when configured).

One one-tap verification microtask for a record — a real source disagreement (kind: conflict) or a known-answer control item (kind: credit). No API key. Pass a client-generated session_id (UUID) so voted tasks are not re-served. Returns { task: null } when there is nothing to verify.

Record an anonymous vote on a microtask. No API key. value must be one of the task options’ values, or { "not_sure": true }. Credit tasks score the session’s trust weight; conflict tasks evaluate weighted consensus. A field flips to verified only when enough trusted, independent sessions confirm the live value — anonymous votes never overwrite a canonical value.

Request a Credits Compute work unit — rank the candidate compositions by similarity to the anchor and submit the best to earn access credits. No API key; identify with a session_id. Returns { unit: { unit_token, anchor, candidates[] } }, or { unit: null } when none is available. Results are verified server-side.

Submit a work-unit result. No API key. The server re-verifies the ranking before it counts; verified contributions are staged additively (never overwriting canonical data) and accrue an access-credit balance that raises your tier (base → contributor → partner).

Your earned Credits Compute status. Identify with an API key (x-api-key) and/or a compute session_id. Returns your effective tier, contribution totals, your claimed identifiers (claims), and whether the optional email account layer is available on this deployment (account_sign_in).

Claim an identifier for your personal Credits Graph. No API key — identify with your compute session_id (body, query, or x-compute-session header). The code must exist in the Credits index; up to 24 claims per session (the personal graph’s one-traversal budget). Idempotent — re-claiming answers 200. Claiming is open and never gates anything; verification (unverified | compute_verified | owner_verified) is a separate trust signal derived from your earned Credits Compute tier.

List your claimed identifiers, each with its verification trust signal.

Remove a claim. Idempotent — removing a code you never claimed answers 200 with removed: 0.

Your personal Credits Graph: one seeded traversal across every claimed code, a synthetic you root node (hop 0) with kind: claim connections to your codes, and a per-claim gaps summary — verified, single_source, verifiable (fixable right now via Credits Compute), and no_match (verified absences). Zero claims still answers 200 with the you node and a hint. depth 1–2 (default 1). Musician claims expand to their IPI/ISNI/ISRC codes.

Optional passwordless account: email yourself a single-use sign-in link (15 min). Accounts exist to persist your claims across devices by ADOPTING your session — claims always live on sessions and never move. Dormant until configured: answers 503 on deployments without email sign-in (check account_sign_in on GET /v1/me). Rate-limited per IP and per email; the response never reveals whether an account already existed.

Exchange the emailed token for a 90-day bearer account_token (send it as Authorization: Bearer …). Verifying adopts your session onto the account; a session already on a different account reports session_conflict: true and login still succeeds. Links are single-use — used, expired, or superseded links answer 401.

The signed-in account: adopted sessions, the best earned Credits Compute tier across them, and the deduped union of their claims. Authorization: Bearer <account_token> — header-only transport, no cookies.