# Credits.fm — Full API Documentation for AI Agents

> Credits.fm is a free, open music identifier search database by Notes.fm. No authentication required for basic use. Rate limits: 30 req/min (lookups) and 10 req/min (search) without a key, or 300/60 req/min with a free API key from https://credits.fm/api#get-api-key. Contribute endpoint requires an API key (10/min). All responses are JSON.

**Programmatic API (use this):** `https://api.credits.fm/v1/...` — canonical Nitro API; JSON field names are **snake_case** (`recording_title`, `artist_names`, …). **Do not** use `https://credits.fm/api/...` — those paths are internal to the website, not a public API surface.

**Discovery:** `GET https://api.credits.fm/` — OpenAPI JSON: `https://api.credits.fm/_openapi.json` — Scalar UI: `https://api.credits.fm/docs`

**Note:** some JSON examples later in this file are illustrative; for exact request/response schemas, use `https://api.credits.fm/_openapi.json`.

## Attribution & Licensing

Credits.fm data is free — no registration, no authentication required for basic use. We ask that you include attribution when citing or reproducing this data.

**How to attribute:**
1. Link to the relevant Credits.fm page or domain-specific URL
2. Credit the upstream data source(s) — API responses include a `sources` array to help identify which sources contributed

**Domain-specific attribution links:**
- ISRC recordings → https://isrc.fm/{isrc_code} (or https://credits.fm/isrc/{isrc_code})
- ISWC works → https://iswc.fm/{iswc_code} (or https://credits.fm/iswc/{iswc_code})
- IPI songwriters/publishers → https://ipi.fm/{ipi_code} (or https://credits.fm/ipi/{ipi_code})
- ISNI identities → https://isni.fm/{isni_code} (or https://credits.fm/isni/{isni_code})
- UPC albums → https://credits.fm/upc/{upc_code}
- Musicians → https://credits.fm/musician/{mbid}

**Upstream source attribution:**
- **Mechanical Licensing Collective (MLC)** — songwriter names, roles, publisher chains, match status. (Ownership share percentages are NOT currently exposed on the public API — withheld pending MLC licensing.) Source value: `notes_credits_api`
- **MusicBrainz** (CC0 open data) — artist metadata, recording↔work relationships, IPIs, ISNIs, UPC barcodes. Source value: `musicbrainz`
- **CISAC** — authoritative ISWC registry (~95M musical works)
- **ISNI.org** — creative contributor identities, name variants, birth/death dates
- **Spotify / Apple Music** — navigation links plus supplementary factual metadata (recording/album titles, artist names) used to fill records the open sources don't cover. Platform-origin fields are attributed to the platform and are NOT claimed under Credits.fm's CC-BY license. Their cover art is governed by their own developer terms and is NOT redistributed — the API does not return Apple/Spotify cover-art URLs; cover art in API responses is limited to open-licensed MusicBrainz Cover Art Archive images. Source values: `spotify`, `apple_music`

**Example attributions:**
- "Songwriter data from Credits.fm (https://isrc.fm/GBAYE0601498), sourced from the Mechanical Licensing Collective."
- "Recording metadata from Credits.fm (https://credits.fm), with data from MusicBrainz (CC0) and the MLC."
- "ISWC registry data from Credits.fm (https://iswc.fm/T-070237966-1), sourced from CISAC."

## Quick Start

Search anything:
```
GET https://api.credits.fm/v1/search?q=bohemian+rhapsody&type=auto&limit=10
```

Look up a specific identifier:
```
GET https://api.credits.fm/v1/isrc/GBAYE0601498
GET https://api.credits.fm/v1/iswc/T-070237966-1
GET https://api.credits.fm/v1/ipi/00508530861
GET https://api.credits.fm/v1/isni/0000000000012571
GET https://api.credits.fm/v1/musician/0383dadf-2a4e-4d10-a46a-e9e041da8eb3
```

Batch lookup (up to 100 per type):
```
POST https://api.credits.fm/v1/batch
Content-Type: application/json
Body: {"isrcs": ["GBAYE0601498", "USUM71922944"], "ipis": ["00508530861"]}
```

Autocomplete suggestions (<300ms):
```
GET https://api.credits.fm/v1/suggest?q=taylor
```

All publishers for a songwriter:
```
GET https://api.credits.fm/v1/ipi/00508530861/publishers
GET https://api.credits.fm/v1/ipi/00508530861/publishers?include=isrcs
```

Resolve songwriter name to IPI (when IPI unknown):
```
POST https://api.credits.fm/v1/resolve/songwriter
Content-Type: application/json
Body: {"name": "Mercury", "isrcs": ["GBAYE0601498", "USUM71922944"]}
```

All ISRCs for a composition (uncapped):
```
GET https://api.credits.fm/v1/iswc/T-070237966-1?complete=true
```

Resolve Spotify/Apple Music URLs:
```
GET https://api.credits.fm/v1/lookup?url=https://open.spotify.com/track/5eIDxmWYxRA0HJBYM9bIIS
```

## Credits Graph

The Credits Graph is the canonical machine-readable graph of music credits: identifier codes as nodes (`isrc`, `iswc`, `ipi`, `isni`, `upc`), `connections` with full source provenance, and a verification status on every connection — `verified` (asserted by 2+ independent sources) or `single` (one source so far). Verified ABSENCE is first-class: each node's `no_match` array lists the directions that were checked against every source with no counterpart found. Typed recording↔recording relationships (cover, sample, remix, interpolation, …) appear as `kind: relation` connections. (The response field is `connections`; `edges` remains as a deprecated alias for now.) Data is CC-BY 4.0; URLs are stable and citable.

Network around one code (depth 1–2; explore further by re-querying any node at depth=1 and merging):
```
GET https://api.credits.fm/v1/graph/isrc/GBAYE0601498?depth=2
GET https://api.credits.fm/v1/graph/iswc/T-070237966-1
GET https://api.credits.fm/v1/graph/ipi/00508530861?per_hop=25&max_nodes=300
```

Live status feed — every change type across the whole index (`link_found`, `link_verified`, `relation_found`, `no_match_recorded`); poll with `since={previous as_of}` for deltas:
```
GET https://api.credits.fm/v1/graph/activity?limit=60
```

People and verification (phase 2):
- Musician (people) nodes ride every network (performers/producers per recording, IPI/ISNI identity links). Musician identity is the CREDITS ID — deterministic UUID; the MusicBrainz MBID rides as the node's `mbid` provenance field. Musician roots: `GET /v1/graph/musician/{mbid}`.
- Single-source ISWC<->ISRC edges carry `verifiable: true` — verify one via `GET /v1/compute/unit?task_type=crosslink_verify&anchor={iswc}` + `POST /v1/compute/result`. Consensus (3 independent sessions) adds the `compute` second source that flips the edge to verified.
- `people=0` skips people nodes.

Human-viewable + embeddable surfaces:
- `https://credits.fm/graph` — the live Credits Graph (global constellation, updates as codes are linked and verified)
- `https://credits.fm/graph/embed` — chrome-less iframe variant
- `https://credits.fm/{type}/embed/{code}/graph` — per-identifier graph embed (isrc, iswc, ipi, isni, upc)
- oEmbed: `https://credits.fm/api/oembed?url=https://credits.fm/graph` (also accepts `?view=graph` entity URLs)

Personal graph & claims (Credits Graph 0.2):
- A session (client-minted UUIDv4, the same `session_id` Credits Compute uses) can CLAIM identifiers as its own: `POST /v1/me/claims {session_id, type, code}` (types isrc|iswc|ipi|isni|upc|musician-MBID; code must exist in the index; cap 24/session; idempotent). `GET /v1/me/claims` lists; `DELETE /v1/me/claims/{code}?type=` removes (idempotent).
- `GET /v1/me/graph?session_id=&depth=1|2` returns the claimed subgraph: one seeded traversal across every claim, a synthetic `you` root node (hop 0) with `kind: "claim"` connections, and a per-claim `gaps` block ({connections, verified, single_source, verifiable, no_match}) — the actionable list of unverified/missing links. Zero claims answers 200 with a hint.
- Claiming is open (a viewing/organizing tool, never a gate). Each claim carries a `verification` trust signal: `unverified` | `compute_verified` (the session earned tier >= contributor via Credits Compute) | `owner_verified` (reserved).
- Optional passwordless accounts persist claims across devices by ADOPTING sessions (`POST /v1/account/magic-link` -> emailed single-use link -> `POST /v1/account/verify` -> bearer `account_token` -> `GET /v1/account/me`). Claims always live on sessions and never move; an account's claims are the union across its adopted sessions. Deployments without email sign-in answer 503 — check `account_sign_in` on `GET /v1/me`.
- Human surface: `https://credits.fm/graph/me` — claim by name search or pasted code, see your personal graph, work through the gaps.
- `GET /v1/me` now also returns a bounded `claims` block and `account_sign_in` ("available" | "unconfigured").

## Usage Patterns

**Pattern 1: "Who wrote this song?"**
1. Search by song title: `GET https://api.credits.fm/v1/search?q=bohemian+rhapsody`
2. Get ISRC from results: `GBAYE0601498`
3. Look up songwriter credits: `GET https://api.credits.fm/v1/isrc/GBAYE0601498`
4. Response includes `songwriters` array with names, roles, and publisher chains (share percentages are not currently returned)

**Pattern 2: "Show me all recordings of this composition"**
1. Look up the ISWC: `GET https://api.credits.fm/v1/iswc/T-070237966-1`
2. Response includes `isrcs` array with all recording codes
3. Look up individual ISRCs for details on each recording

**Pattern 3: "What has this songwriter written?"**
1. Look up the IPI: `GET https://api.credits.fm/v1/ipi/00508530861`
2. Response includes `iswcs` (works) and `isrcs` (recordings) arrays
3. `relatedEntities` shows co-writers and publishers

**Pattern 4: "Who publishes this songwriter?"**
1. If you have the IPI: `GET https://api.credits.fm/v1/ipi/00508530861/publishers`
2. Response includes every publisher with name, IPI, role, and shared song count
3. If you only have a name + ISRCs: `POST https://api.credits.fm/v1/resolve/songwriter` with `{"name": "Baker", "isrcs": [...]}`
4. If one match: returns publishers inline. If multiple: returns disambiguation list with IPIs.

**Pattern 5: "Identify songs from a Spotify link"**
1. Resolve the URL: `GET https://api.credits.fm/v1/lookup?url=https://open.spotify.com/track/...`
2. Response includes track name, artists, resolved ISRC, and platform URLs
3. Works with track, album, playlist, and artist URLs
4. Playlist URLs return the full track list with ISRCs resolved from the Credits index

**Pattern 6: "Bulk lookup"**
1. Collect identifiers
2. POST to `https://api.credits.fm/v1/batch` with arrays of ISRCs, ISWCs, IPIs, ISNIs, or UPCs
3. Results are keyed by identifier code for easy lookup

## Authentication

Optional. Pass via header (recommended) or query parameter:
```
curl -H "x-api-key: cfm_your_key_here" https://api.credits.fm/v1/isrc/GBAYE0601498
curl "https://api.credits.fm/v1/isrc/GBAYE0601498?api_key=cfm_your_key_here"
```

## Credits ID

Every entity in Credits.fm has a deterministic `creditsId` — a UUIDv5 derived from `{type}:{externalId}`. Because the input is deterministic, the same identifier always produces the same UUID.

**Entity types:** `isrc`, `iswc`, `ipi`, `isni`, `upc`, `musician`, `artist`

**Examples:**
- ISRC `GBAYE0601498` → `creditsId`: `9b033599-8a5e-565a-b6b6-2dafbb91939c` (from `isrc:GBAYE0601498`)
- IPI `00508530861` → `creditsId`: `5f8f3def-adf3-5f8e-b81f-db45093bf8c6` (from `ipi:00508530861`)
- Musician `0383dadf-...` → `creditsId`: `a1b2c3d4-e5f6-5789-abcd-ef0123456789` (from `musician:0383dadf-...`)

Phase 1: `creditsId` is included in all API responses. It is not yet accepted as a lookup parameter.

## API Endpoints

### 1. Unified Search
```
GET https://api.credits.fm/v1/search
```

**Parameters:**
| Param | Required | Description |
|-------|----------|-------------|
| q | Yes | Search query — ISRC code, ISWC code, IPI number, ISNI, UPC, artist name, song title, or Spotify/Apple Music URL |
| type | No | Force search type: `isrc`, `iswc`, `ipi`, `isni`, `upc`, `musician`, `all`, or `auto` (default: `auto`) |
| limit | No | Max results per type, 1-25 (default: 10) |

**Auto-detection:** The API automatically detects identifier types from the query string:
- ISRC: 12 alphanumeric chars (e.g., GBAYE0601498)
- ISWC: T followed by 10-11 digits (e.g., T-070237966-1)
- IPI: 9-11 digit number
- ISNI: 16-digit number
- UPC: 12-14 digit number
- Spotify/Apple Music URLs are parsed and resolved to identifiers

**Response example:**
```json
{
  "isrcs": [
    {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "recordingTitle": "Bohemian Rhapsody",
      "artistNames": ["Queen"],
      "source": "notes",
      "sources": ["mb", "mlc_bulk", "notes"]
    }
  ],
  "iswcs": [
    {
      "creditsId": "359586ff-b848-502f-98aa-8d33b7dba9fd",
      "iswc": "T-070237966-1",
      "songTitle": "Bohemian Rhapsody",
      "isrcCount": 42
    }
  ],
  "ipis": [],
  "isnis": [],
  "upcs": [],
  "musicians": [
    {
      "creditsId": "a1b2c3d4-e5f6-5789-abcd-ef0123456789",
      "mbid": "0383dadf-2a4e-4d10-a46a-e9e041da8eb3",
      "name": "Queen",
      "typeLabel": "Group",
      "beginYear": 1970,
      "endYear": null
    }
  ]
}
```

### 2. ISRC Lookup
```
GET https://api.credits.fm/v1/isrc/{isrc_code}
```

Returns recording details, songwriter credits, publisher chains (names, IPIs, roles), and platform links.

**Response example:**
```json
{
  "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
  "isrc": "GBAYE0601498",
  "recordingTitle": "Bohemian Rhapsody",
  "songTitle": "Bohemian Rhapsody",
  "artistNames": ["Queen"],
  "iswc": "T-070237966-1",
  "matchStatus": "matched",
  "songwriters": [
    {
      "name": "AUTUMN ROWE",
      "ipi": "00508530861",
      "role": "Composer/Author",
      "publishers": [
        {
          "name": "QUEEN MUSIC LTD",
          "ipi": "00148617856",
          "role": "E"
        }
      ]
    }
  ],
  "platforms": [],
  "updatedAt": "2025-01-15T00:00:00Z"
}
```

**Response fields:**
- `creditsId` — Deterministic Credits ID (UUIDv5) for this entity
- `isrc` — The ISRC code
- `recordingTitle` — Track name
- `songTitle` — Song/composition title
- `artistNames` — Array of performing artist names
- `iswc` — Linked musical work code (null if unknown)
- `matchStatus` — MLC match status: `matched` or `unmatched`
- `songwriters` — Array of songwriter objects:
  - `name` — Songwriter name
  - `ipi` — IPI number (null if unknown)
  - `role` — Role: Composer, Author/Lyricist, Composer/Author, Arranger
  - `sharePercentage` — Ownership share percentage. NOT currently returned — withheld pending MLC licensing.
  - `publishers` — Array of publisher objects with `name`, `ipi`, `role` (E=original publisher, SE=sub-publisher, AM=administrator)
- `totalSharePercentage` — Sum of all songwriter shares. NOT currently returned — withheld pending MLC licensing.
- `platforms` — Platform identifiers
- `updatedAt` — Last data refresh timestamp

### 3. ISWC Lookup
```
GET https://api.credits.fm/v1/iswc/{iswc_code}
```

Returns musical work details, all recordings (ISRCs), songwriters, and CISAC registration status.

**Response example:**
```json
{
  "creditsId": "359586ff-b848-502f-98aa-8d33b7dba9fd",
  "iswc": "T-070237966-1",
  "songTitle": "BOHEMIAN RHAPSODY",
  "alternativeTitles": [],
  "isrcCount": 42,
  "isrcs": ["GBAYE0601498", "USUM71922944"],
  "songwriters": [
    {
      "name": "AUTUMN ROWE",
      "ipi": "00508530861",
      "roles": ["Composer", "Author"]
    }
  ],
  "songwriterCount": 1,
  "artistNames": ["Queen"],
  "ipis": ["00508530861"],
  "isnis": [],
  "upcs": ["0602547202659"],
  "updatedAt": "2025-01-15T00:00:00Z"
}
```

**Response fields:**
- `creditsId` — Deterministic Credits ID (UUIDv5) for this entity
- `iswc` — The ISWC code
- `songTitle` — Composition title
- `alternativeTitles` — Array of alternative titles
- `isrcCount` — Number of recordings of this work
- `isrcs` — Array of ISRC codes for recordings of this work (default: top 100; use `?complete=true` for all)
- `songwriters` — Array of songwriter objects with `name`, `ipi`, `roles`
- `songwriterCount` — Number of credited songwriters
- `artistNames` — Array of performing artist names
- `ipis` — Linked songwriter/publisher IPI codes
- `isnis` — Linked creative contributor ISNI codes
- `upcs` — Linked release UPC barcodes
- `updatedAt` — Last data refresh timestamp

### 4. IPI Lookup
```
GET https://api.credits.fm/v1/ipi/{ipi_code}
```

Returns songwriter/publisher profile, all works (ISWCs), recordings (ISRCs), and related entities.

**Response example:**
```json
{
  "creditsId": "5f8f3def-adf3-5f8e-b81f-db45093bf8c6",
  "ipi": "00508530861",
  "fullName": "Autumn Rowe",
  "roles": ["Composer", "Author"],
  "entityType": "songwriter",
  "iswcCount": 168,
  "iswcs": ["T-070237966-1", "T-070245035-9"],
  "isrcCount": 847,
  "isrcs": ["GBAYE0601498", "USUM71922944"],
  "relatedEntities": [],
  "linkedISNIs": [],
  "upcs": ["0602547202659"],
  "avgSharePercentage": 42.5,
  "updatedAt": "2025-01-15T00:00:00Z"
}
```

**Response fields:**
- `creditsId` — Deterministic Credits ID (UUIDv5) for this entity
- `ipi` — The IPI number
- `fullName` — Name of the rights holder
- `roles` — Array of roles (Composer, Author, Arranger, etc.)
- `entityType` — `songwriter`, `publisher`, or `artist`
- `iswcCount` — Number of musical works
- `iswcs` — Array of ISWC codes
- `isrcCount` — Number of recordings
- `isrcs` — Array of ISRC codes
- `relatedEntities` — Array of co-writers and publishers with `ipi`, `name`, `type`
- `linkedISNIs` — Linked ISNI codes for this person
- `upcs` — Linked release UPC barcodes
- `avgSharePercentage` — Average ownership share percentage. NOT currently returned — withheld pending MLC licensing.
- `updatedAt` — Last data refresh timestamp

### 4b. Publishers for Songwriter
```
GET https://api.credits.fm/v1/ipi/{ipi_code}/publishers
GET https://api.credits.fm/v1/ipi/{ipi_code}/publishers?include=isrcs
```

Returns ALL publishers that co-occur with this songwriter across every song — uncapped (unlike `relatedEntities` which is capped at 50). Add `?include=isrcs` to see which ISRCs each publisher shares.

**Response example:**
```json
{
  "ipi": "00508530861",
  "name": "Autumn Rowe",
  "publishers": [
    {
      "name": "QUEEN MUSIC LTD",
      "ipi": "00148617856",
      "role": "OriginalPublisher",
      "isrcCount": 168
    },
    {
      "name": "SONY/ATV SONGS LLC",
      "ipi": "00187062752",
      "role": "OriginalPublisher",
      "isrcCount": 42
    }
  ],
  "totalSongs": 847
}
```

**Response fields:**
- `ipi` — The songwriter's IPI number
- `name` — The songwriter's name
- `publishers` — Array of publisher objects, sorted by `isrcCount` descending
  - `name` — Publisher name
  - `ipi` — Publisher IPI (or null)
  - `role` — Publisher role (OriginalPublisher, AdministeredPublisher, etc.)
  - `isrcCount` — Number of songs where this publisher appears with the songwriter
  - `isrcs` — (only with `?include=isrcs`) Array of shared ISRC codes
- `totalSongs` — Total ISRCs where this songwriter appears

### 4c. Resolve Songwriter Name to IPI
```
POST https://api.credits.fm/v1/resolve/songwriter
Content-Type: application/json
Body: {"name": "Baker", "isrcs": ["USRC12345678", "USRC87654321"]}
```

When you don't have an IPI but know the songwriter's name and some of their songs, this resolves to the IPI. If exactly one match, returns publishers inline. If multiple match, returns disambiguation.

**Response example (single match):**
```json
{
  "name": "Rowe",
  "resolved": true,
  "ipi": "00508530861",
  "fullName": "Autumn Rowe",
  "roles": ["Composer", "Author"],
  "publishers": [
    { "name": "QUEEN MUSIC LTD", "ipi": "00148617856", "role": "OriginalPublisher", "isrcCount": 168 }
  ],
  "totalSongs": 847
}
```

**Response example (multiple matches):**
```json
{
  "name": "Baker",
  "resolved": false,
  "matches": [
    { "ipi": "00123456789", "name": "JOHN BAKER", "roles": ["Composer"], "matchedIsrcCount": 15, "publishersUrl": "https://api.credits.fm/v1/ipi/00123456789/publishers" },
    { "ipi": "00987654321", "name": "SARAH BAKER", "roles": ["Author"], "matchedIsrcCount": 3, "publishersUrl": "https://api.credits.fm/v1/ipi/00987654321/publishers" }
  ],
  "message": "Found 2 songwriters matching \"Baker\". Use the IPI from the correct match."
}
```

### 5. ISNI Lookup
```
GET https://api.credits.fm/v1/isni/{isni_code}
```

Returns creative contributor profile, linked IPIs, works, and recordings.

**Response example:**
```json
{
  "creditsId": "c4d5e6f7-a8b9-5012-3456-789abcdef012",
  "isni": "0000000000012571",
  "fullName": "Freddie Mercury",
  "entityType": "performer",
  "roles": ["singer", "songwriter", "musician"],
  "linkedIPIs": [],
  "iswcCount": 168,
  "iswcs": ["T-070237966-1"],
  "isrcCount": 847,
  "isrcs": ["GBAYE0601498"],
  "upcs": ["0602547202659"],
  "relatedEntities": [],
  "sources": ["isni.org", "musicbrainz"],
  "updatedAt": "2025-01-15T00:00:00Z"
}
```

**Response fields:**
- `creditsId` — Deterministic Credits ID (UUIDv5) for this entity
- `isni` — The ISNI code
- `fullName` — Primary name
- `entityType` — `performer`, `group`, `songwriter`, etc.
- `roles` — Array of creation roles
- `linkedIPIs` — Array of linked IPI numbers
- `iswcCount` / `iswcs` — Musical works
- `isrcCount` / `isrcs` — Recordings
- `upcs` — Linked release UPC barcodes
- `relatedEntities` — Related contributors
- `sources` — Data sources that contributed to this profile
- `updatedAt` — Last data refresh timestamp

### 6. Musician Lookup
```
GET https://api.credits.fm/v1/musician/{musicbrainz_mbid}
```

Returns the real-person musician profile — songwriter credits, performer credits, group memberships, IPI/ISNI identifiers. Musician = the human behind the music. For the release artist's DSP discography, use `https://api.credits.fm/v1/artist/{id}`.

**Response example:**
```json
{
  "creditsId": "a1b2c3d4-e5f6-5789-abcd-ef0123456789",
  "artist": {
    "mbid": "0383dadf-2a4e-4d10-a46a-e9e041da8eb3",
    "name": "Queen",
    "sortName": "Queen",
    "type": "Group",
    "beginYear": 1970,
    "country": "GB"
  },
  "ipis": [],
  "isnis": [],
  "members": [
    {
      "mbid": "7d478e69-...",
      "name": "Freddie Mercury",
      "type": "Person",
      "beginYear": 1946,
      "endYear": 1991
    }
  ],
  "groups": [],
  "stats": {
    "songwriterCredits": 168,
    "performerCredits": 847
  },
  "imageUrl": null
}
```

### 7. Artist Lookup
```
GET https://api.credits.fm/v1/artist/{id}
```

Returns the full discography for a release artist (the performing entity on DSPs). Artist = the brand/stage name on releases (e.g., "Queen", "The Weeknd"). For the real person behind the music (songwriter credits, IPI/ISNI), use `https://api.credits.fm/v1/musician/{mbid}`.

**Artist vs Musician:**
- **Artist** = performing entity / release artist on DSPs. Identified by platform ID. Has a catalog of releases and tracks.
- **Musician** = the real person. Identified by MusicBrainz MBID. Has songwriter + performer credits, IPI/ISNI identifiers, group memberships.

**Response example:**
```json
{
  "creditsId": "b2c3d4e5-f6a7-5890-bcde-f01234567890",
  "artist": {
    "spotifyId": "1dfeR4HaWDbWqFHLkxsg1d",
    "name": "Queen",
    "spotifyUrl": "https://open.spotify.com/artist/1dfeR4HaWDbWqFHLkxsg1d",
    "imageUrl": null,
    "genres": ["classic rock", "rock"]
  },
  "totalTracks": 287,
  "albums": [
    {
      "id": "6i6folBtxKV28WX3msQ4FE",
      "name": "A Night At The Opera",
      "releaseDate": "1975-11-21",
      "coverArtUrl": null,
      "upc": "602445790098",
      "creditsUrl": "https://credits.fm/upc/602445790098"
    }
  ],
  "tracks": [
    {
      "name": "Bohemian Rhapsody - Remastered 2011",
      "artists": ["Queen"],
      "isrc": "GBAYE0601498",
      "albumName": "A Night At The Opera",
      "releaseDate": "1975-11-21",
      "coverArtUrl": null,
      "durationMs": 354320,
      "trackNumber": 11,
      "discNumber": 1,
      "spotifyUrl": "https://open.spotify.com/track/5eIDxmWYxRA0HJBYM9bIIS",
      "inDatabase": true,
      "creditsUrl": "https://credits.fm/isrc/GBAYE0601498"
    }
  ]
}
```

**Response fields:**
- `creditsId` — Deterministic Credits ID (UUIDv5) for this entity
- `artist` — Artist metadata (name, image, genres, platform URL)
- `totalTracks` — Total tracks in discography
- `albums` — Array of albums with UPCs and credits.fm links
- `tracks` — Array of tracks with ISRCs, release dates, and credits.fm links
- `inDatabase` — Whether the ISRC exists in Credits DB (true = has songwriter credits)
- `creditsUrl` — Direct link to the Credits.fm page for this identifier

### 8. Batch Lookup
```
POST https://api.credits.fm/v1/batch
Content-Type: application/json
Body: {"isrcs": [...], "iswcs": [...], "ipis": [...], "isnis": [...], "upcs": [...]}
```

Batch lookup for up to 100 identifiers per type in a single request. Accepts any combination of identifier types. Returns results keyed by identifier code. Falls back to MusicBrainz for identifiers not yet in the index. Each result includes a `sources` array indicating data origin (`credits_db`, `notes_credits_api`, or `musicbrainz`).

**Response example:**
```json
{
  "isrcs": {
    "GBAYE0601498": {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "recordingTitle": "Bohemian Rhapsody",
      "songTitle": "Bohemian Rhapsody",
      "artistNames": ["Queen"],
      "iswc": "T-070237966-1",
      "matchStatus": "matched",
      "songwriters": [
        {
          "name": "AUTUMN ROWE",
          "ipi": "00508530861",
          "role": "Composer/Author",
          "publishers": [
            {
              "name": "QUEEN MUSIC LTD",
              "ipi": "00148617856",
              "role": "E"
            }
          ]
        }
      ],
      "platforms": [],
      "sources": ["credits_db", "notes_credits_api"],
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  },
  "ipis": {
    "00508530861": {
      "creditsId": "5f8f3def-adf3-5f8e-b81f-db45093bf8c6",
      "ipi": "00508530861",
      "fullName": "Autumn Rowe",
      "entityType": "songwriter",
      "roles": ["Composer", "Author"],
      "iswcCount": 168,
      "isrcCount": 847,
      "avgSharePercentage": 42.5,
      "sources": ["credits_db"],
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  }
}
```

### 9. Autocomplete Suggestions
```
GET https://api.credits.fm/v1/suggest?q={query}
```

Fast autocomplete endpoint returning up to 8 suggestions across all identifier types. Designed for <300ms response time. Each suggestion includes type, title, subtitle, and URL.

**Response example:**
```json
{
  "suggestions": [
    {
      "creditsId": "f1a2b3c4-d5e6-5789-0abc-def012345678",
      "type": "isrc",
      "id": "USUG12100488",
      "title": "Love Story",
      "subtitle": "Taylor Swift",
      "url": "/isrc/USUG12100488"
    },
    {
      "creditsId": "e2f3a4b5-c6d7-5890-1bcd-ef0123456789",
      "type": "musician",
      "id": "20244d07-534f-4eff-b4d4-930878889f84",
      "title": "Taylor Swift",
      "subtitle": "Person",
      "url": "/musician/20244d07-534f-4eff-b4d4-930878889f84"
    }
  ]
}
```

### 10. URL Resolution
```
GET https://api.credits.fm/v1/lookup?url={spotify_or_apple_music_url}
```

Resolves Spotify or Apple Music URLs to track, album, playlist, or artist metadata. Playlist URLs return the full track list with resolved ISRCs from the Credits index.

**Track response example:**
```json
{
  "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
  "type": "track",
  "isrc": "GBAYE0601498",
  "name": "Bohemian Rhapsody - Remastered 2011",
  "artists": ["Queen"],
  "spotifyUrl": "https://open.spotify.com/track/5eIDxmWYxRA0HJBYM9bIIS",
  "albumName": "A Night At The Opera",
  "coverArtUrl": null,
  "creditsUrl": "https://credits.fm/isrc/GBAYE0601498"
}
```

**Album response example:**
```json
{
  "creditsId": "d3e4f5a6-b7c8-5901-2def-012345678901",
  "type": "album",
  "upc": "602445790098",
  "name": "A Night At The Opera",
  "artists": ["Queen"],
  "spotifyUrl": "https://open.spotify.com/album/...",
  "releaseDate": "1975-11-21",
  "label": "Hollywood Records",
  "totalTracks": 12,
  "coverArtUrl": null,
  "creditsUrl": "https://credits.fm/upc/602445790098",
  "tracks": [
    {
      "name": "Death on Two Legs",
      "artists": ["Queen"],
      "trackNumber": 1,
      "discNumber": 1
    }
  ]
}
```

**Playlist response example:**
```json
{
  "type": "playlist",
  "name": "Today's Top Hits",
  "imageUrl": null,
  "spotifyUrl": "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
  "totalTracks": 50,
  "tracks": [
    {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "name": "Bohemian Rhapsody - Remastered 2011",
      "artists": ["Queen"],
      "spotifyUrl": "https://open.spotify.com/track/5eIDxmWYxRA0HJBYM9bIIS",
      "albumName": "A Night At The Opera",
      "coverArtUrl": null,
      "trackNumber": 1,
      "discNumber": 1,
      "creditsUrl": "https://credits.fm/isrc/GBAYE0601498"
    }
  ]
}
```

### 11. Track Resolution
```
POST https://api.credits.fm/v1/resolve/track
```

Resolve a track to its ISRC and songwriter credits by name + artist, Spotify URL, or Apple Music URL.

**Request:**
```json
{ "name": "Bohemian Rhapsody", "artist": "Queen" }
```
Or: `{ "spotify_url": "https://open.spotify.com/track/..." }`
Or: `{ "apple_music_url": "https://music.apple.com/..." }`

**Response:**
```json
{
  "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
  "isrc": "GBAYE0601498",
  "recording_title": "Bohemian Rhapsody",
  "artist_names": ["Queen"],
  "iswc": "T-010.477.438-3",
  "songwriters": [{ "name": "Freddie Mercury", "role": "Composer" }],
  "credits_url": "https://credits.fm/isrc/GBAYE0601498",
  "sources": ["credits_db", "notes_credits_api"]
}
```

### 12. Batch Track Resolution
```
POST https://api.credits.fm/v1/resolve/batch
```

Resolve up to 50 tracks to ISRCs in a single request.

**Request:**
```json
{
  "tracks": [
    { "name": "Bohemian Rhapsody", "artist": "Queen" },
    { "name": "Stairway to Heaven", "artist": "Led Zeppelin" }
  ]
}
```

**Response:**
```json
{
  "total": 2,
  "resolved": 2,
  "results": [
    { "creditsId": "28d0ff4e-dfc1-559f-9dd2-a36fc05d4073", "name": "Bohemian Rhapsody", "artist": "Queen", "isrc": "GBCEE9800022", "credits_url": "https://credits.fm/isrc/GBCEE9800022" },
    { "creditsId": "4e5f6a7b-c8d9-5012-3ef0-123456789abc", "name": "Stairway to Heaven", "artist": "Led Zeppelin", "isrc": "GBZZ7000006", "credits_url": "https://credits.fm/isrc/GBZZ7000006" }
  ]
}
```

### Verify vs Contribute vs Crowd vs Compute

- `GET /v1/verify/{type}/{code}` INSPECTS what independent sources say about an identifier. It does not accept a caller-supplied value.
- `POST /v1/contribute` SUBMITS sourced data the caller already has. It requires an API key.
- `GET /v1/crowd/task` + `POST /v1/crowd/vote` asks a human or agent one field-choice question. It uses an anonymous session UUID.
- `GET /v1/compute/unit` + `POST /v1/compute/result` asks software to rank a bounded server-issued candidate set. It uses an anonymous session UUID.

Verify, Crowd, and Compute do not require an API key. Generate one UUID and reuse it as `session_id`; it is a public session identifier, not a secret.

### 13. Multi-source Verify
```
GET  https://api.credits.fm/v1/verify/{isrc|iswc|ipi|isni|upc}/{code}
POST https://api.credits.fm/v1/verify/batch
```

Verify returns `overall_level` (`unverified`, `single_source`, `verified`, or `conflicted`), field-level `{ value, verified, agreeing_sources, disagreeing_sources }`, and linked identifiers with edge provenance. A field is verified when at least 2 independent sources agree. An unavailable adapter is not negative evidence. Use `?raw=1` only for adapter-level debugging.

Use Contribute, not Verify, when you already have a sourced value to submit.

### 14. Contribute Data
```
POST https://api.credits.fm/v1/contribute
Content-Type: application/json
x-api-key: cfm_your_key_here
Body: {"contributions": [{"target": "isrc", "id": "GBAYE0601498", "field": "iswc", "value": "T-070237966-1", "citation": "CISAC registry"}]}
```

Submit sourced data to improve the Credits index. Requires a free API key. HTTP 201 means the batch was processed; inspect every `results[].status`. An item may be auto-accepted, verified against independent evidence, queued, recorded as negative evidence, replayed idempotently, or rejected.

**Parameters (in request body):**
| Param | Required | Description |
|-------|----------|-------------|
| contributions | Yes | Array of contribution objects (max 25) |
| contributions[].target | Yes | Index type: `isrc`, `iswc`, `ipi`, `isni`, or `upc` |
| contributions[].id | Yes | The identifier code to contribute to |
| contributions[].field | Yes | Field name (e.g., `iswc`, `song_title`, `songwriters`, `full_name`, `roles`) |
| contributions[].value | Yes | The value to contribute |
| contributions[].type | No | `fill_null` (default), `correction`, `append`, or internal-only `no_match` |
| contributions[].citation | No | Source citation (e.g., "MusicBrainz MBID xyz") |

**Contributable fields:**
- ISRC: `recording_title`, `song_title`, `artist_names`, `iswc`, `songwriters`, `cover_art_url`, `mlc_song_code` (fill_null, correction)
- ISWC: `song_title` (fill_null, correction), `alternative_titles`, `songwriter_names`, `artist_names` (append)
- IPI: `full_name` (fill_null, correction), `alternative_names`, `roles` (append), `entity_type` (fill_null)
- ISNI: `full_name` (fill_null, correction), `roles` (append), `linked_ipis` (append)
- UPC: `album_title` (fill_null, correction), `artist_names` (fill_null)

**Response example:**
```json
{
  "accepted": 1,
  "pending": 0,
  "total": 1,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "target": "isrc",
      "targetId": "GBAYE0601498",
      "field": "iswc",
      "status": "auto_accepted",
      "message": "Contribution accepted and applied"
    }
  ]
}
```

**Trust system:** New keys start with manual review. Each accepted contribution increases your trust score. Higher trust unlocks auto-acceptance for more field types. Accepted ISRC<->ISWC contributions update both `isrc.iswc` and `iswc.isrcs` before the response returns.

### 15. Coverage Metrics
```
GET https://api.credits.fm/v1/coverage
```

Returns row counts, data completeness metrics, and growth data for all Credits index tables. Use this to see where data gaps exist and where contributions would be most valuable.

**Response example:**
```json
{
  "isrc": { "total": 52000000, "withSongwriters": 12000000, "withISWC": 18000000 },
  "iswc": { "total": 95000000, "withISRCs": 45000000 },
  "ipi": { "total": 500000, "withISRCs": 400000 },
  "isni": { "total": 100000, "withIPIs": 80000 },
  "upc": { "total": 3000000, "withISRCs": 2500000 }
}
```

### Credits Compute (server-issued candidate matching)
```
GET  https://api.credits.fm/v1/compute/unit?session_id={uuid}
POST https://api.credits.fm/v1/compute/result   { "session_id", "unit_token", "winner_id", "score?" }
GET  https://api.credits.fm/v1/me?session_id={uuid}
```

Optionally earn higher rate limits and access tiers by contributing verified computation back to the index. No API key required — identify with a `session_id` (any UUID you generate and reuse).

Flow:
1. `GET /v1/compute/unit?session_id={uuid}` returns `{ unit_token, task_type, anchor, candidates[] }`, or `{ "unit": null }`.
2. ALWAYS branch on the RETURNED `task_type`. Hidden composition controls can be interleaved even when identity work was requested.
3. Pick one candidate and submit its ID with the unchanged token. `score` is required for real `composition_similarity` units and optional for judgment tasks.
4. Results are verified server-side. `staged` means accepted for downstream consensus, not already public; `recorded` means the judgment landed without a merge-worthy link.
5. Verified contributions accrue an access-credit balance that raises your tier (`base → contributor → partner`).
6. `GET /v1/me?session_id={uuid}` returns `{ tier, base_api_tier, accepted_30d, compute_balance }`.

Task types:
- `composition_similarity`: choose the same musical work; real units require a local score.
- `identity`: choose the ISNI representing the same person/organization as the IPI anchor.
- `crosslink_verify`: choose the ISRC recording belonging to the ISWC anchor.
- `writer_ipi`: choose the IPI belonging to the named writer.

Verification, anti-abuse, and credit accounting are handled server-side. The credits.fm website runs this automatically in a background worker for visitors; agents and scripts can participate directly via the endpoints above. Full request/response schemas: https://api.credits.fm/docs

### Crowd Verification (help verify data — humans and agents)
```
GET  https://api.credits.fm/v1/crowd/task?target={isrc|iswc|ipi|isni|upc}&id={code}&session_id={uuid}
POST https://api.credits.fm/v1/crowd/vote   { "task_id", "session_id", "value" }
```

Both endpoints are anonymous (no API key). `GET /v1/crowd/task` returns one neutral field-choice task. Render only the returned `field` and `options`; control tasks are deliberately indistinguishable from source disagreements. Submit one exact option `value` via `POST /v1/crowd/vote`, or `{ "not_sure": true }`.

Answers are trusted by **independent agreement**: consensus requires at least 3 distinct voters, trusted weight >=2, and a winning margin >=1. Confirming the live value adds `crowd` as a field source. Selecting the competing value flags it for trusted review; anonymous votes never overwrite the canonical scalar.

Quality control: a session's vote weight is 0 until it has answered ≥3 credit control items correctly, so low-effort or adversarial voting cannot move canonical data; and anonymous votes never overwrite a stored value — a disagreeing consensus only flags the conflict for a later trusted pass.

### 15. Validate ISRCs
```
POST https://api.credits.fm/v1/validate/batch
Content-Type: application/json
Body: {"isrcs": ["GBAYE0601498", "USRC17607839"], "include_dsp_check": true}
```

Validate ISRCs against MLC data and optionally cross-reference with Spotify and Apple Music. Returns match status and any issues found. (Share-completeness checks are not currently available — ownership share percentages are withheld pending MLC licensing.) Supports CSV export via `?format=csv` query parameter.

**Parameters (in request body):**
| Param | Required | Description |
|-------|----------|-------------|
| isrcs | Yes | Array of up to 100 ISRC codes to validate |
| include_dsp_check | No | Cross-reference ISRCs with Spotify and Apple Music (default: false) |

**Issue types:** `not_in_database`, `not_matched_at_mlc`, `no_iswc`, `incomplete_shares`, `missing_shares`, `over_allocated_shares`, `title_mismatch_spotify`, `artist_mismatch_spotify`, `title_mismatch_apple_music`, `artist_mismatch_apple_music`, `not_found_spotify`, `not_found_apple_music`

**Response example:**
```json
{
  "results": {
    "GBAYE0601498": {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "status": "validated",
      "mlcMatched": true,
      "recordingTitle": "Bohemian Rhapsody",
      "artistNames": ["Queen"],
      "iswc": "T-070237966-1",
      "totalSharePercentage": 100,
      "dspCrossReference": {
        "spotify": { "found": true, "title": "Bohemian Rhapsody", "artists": ["Queen"], "titleMatch": true, "artistMatch": true },
        "appleMusic": { "found": true, "title": "Bohemian Rhapsody", "artists": ["Queen"], "titleMatch": true, "artistMatch": true }
      },
      "issues": [],
      "creditsUrl": "https://isrc.fm/GBAYE0601498"
    }
  },
  "summary": { "total": 1, "validated": 1, "issuesFound": 0, "notFound": 0 }
}
```

### 16. Audit Songwriter Shares
```
POST https://api.credits.fm/v1/audit/shares
Content-Type: application/json
Body: {"isrcs": ["GBAYE0601498", "USRC17607839"]}
```

**NOT currently available on the public API** — this endpoint returns HTTP 403 (`mlc_shares_unavailable`) while ownership share percentages are withheld pending MLC licensing. The schema below is retained for when it is re-enabled. Analyze songwriter share percentages for ISRCs. Identifies songs with incomplete shares (< 100%), missing shares, or over-allocated shares (> 100%). Supports CSV export via `?format=csv`.

**Response example:**
```json
{
  "results": [
    {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "recordingTitle": "Bohemian Rhapsody",
      "artistNames": ["Queen"],
      "iswc": "T-070237966-1",
      "totalSharePercentage": 100,
      "shareGap": 0,
      "issue": "complete",
      "songwriters": [{ "name": "FREDDIE MERCURY", "role": "Composer/Author", "sharePercentage": "100" }],
      "creditsUrl": "https://isrc.fm/GBAYE0601498"
    }
  ],
  "summary": { "total": 1, "complete": 1, "incomplete": 0, "missing": 0, "overAllocated": 0 }
}
```

**Response fields:**
- `issue` — Share status: `complete` (100%), `incomplete` (< 100%), `missing` (no shares), `over_allocated` (> 100%)
- `shareGap` — Difference from 100% (0 = complete, positive = incomplete, negative = over-allocated)
- `songwriters` — Array with `name`, `ipi`, `role`, `sharePercentage` for each credited writer

### 17. Audit MLC Match Status
```
POST https://api.credits.fm/v1/audit/unmatched
Content-Type: application/json
Body: {"isrcs": ["GBAYE0601498", "USRC17607839"]}
```

Check which ISRCs are matched or unmatched at the MLC. Categorizes each ISRC as matched, unmatched, or not in database. Supports CSV export via `?format=csv`.

**Response example:**
```json
{
  "results": [
    {
      "creditsId": "9b033599-8a5e-565a-b6b6-2dafbb91939c",
      "isrc": "GBAYE0601498",
      "recordingTitle": "Bohemian Rhapsody",
      "artistNames": ["Queen"],
      "iswc": "T-070237966-1",
      "matchStatus": "matched",
      "songwriters": [{ "name": "FREDDIE MERCURY", "role": "Composer/Author" }],
      "creditsUrl": "https://isrc.fm/GBAYE0601498"
    }
  ],
  "summary": { "total": 1, "matched": 1, "unmatched": 0, "notInDb": 0 }
}
```

**Response fields:**
- `matchStatus` — `matched` (found at MLC), `unmatched` (in DB but not matched at MLC), `not_in_db` (ISRC not in Credits database)

## Error Responses

All errors return JSON with an `error` field:

| Status | Meaning | Example |
|--------|---------|---------|
| 400 | Missing or invalid parameter | `{"error": "ISRC is required"}` |
| 404 | Identifier not found | `{"error": "ISRC not found"}` |
| 429 | Rate limit exceeded | `{"error": "Rate limit exceeded", "retryAfter": 42, "hint": "Get a free API key at https://credits.fm/api for 10x higher limits."}` |
| 503 | Service unavailable | `{"error": "Service unavailable"}` |

Rate limit headers on every response:
- `X-RateLimit-Limit` — Total requests allowed per window
- `X-RateLimit-Remaining` — Remaining in current window

## Identifier Types Reference

| Code | Full Name | Format | Identifies | Standard |
|------|-----------|--------|-----------|----------|
| ISRC | International Standard Recording Code | 12 alphanumeric (e.g., GBAYE0601498) | Sound recordings | ISO 3901 |
| ISWC | International Standard Musical Work Code | T-NNNNNNNNN-C (e.g., T-070237966-1) | Musical compositions | ISO 15707 |
| IPI | Interested Parties Information | 9-11 digits | Songwriters & publishers | CISAC/SUISA |
| ISNI | International Standard Name Identifier | 16 digits (e.g., 0000 0001 2345 6789) | Creative contributors | ISO 27729 |
| UPC | Universal Product Code | 12-14 digits | Album releases | GS1 |

## Relationships Between Identifiers

```
UPC (release/album)
 └── contains N ISRCs (individual tracks)
      └── each ISRC maps to 1 ISWC (the underlying composition)
           └── each ISWC has N IPIs (songwriters & publishers)
                └── each IPI may have ISNIs (cross-industry identity)
```

## Data Coverage


Counts as of <!-- counts:asof -->2026-04-24<!-- /counts:asof -->.

- <!-- counts:isrc -->53M+<!-- /counts:isrc --> ISRC recordings from MLC, MusicBrainz, Spotify, Apple Music
- <!-- counts:iswc -->125M+<!-- /counts:iswc --> ISWC musical works across CISAC, MLC, MusicBrainz, and Notes
- <!-- counts:ipi -->2M+<!-- /counts:ipi --> IPI songwriter/publisher profiles
- <!-- counts:isni -->144K+<!-- /counts:isni --> ISNI creative contributor identities
- <!-- counts:upc -->5M+<!-- /counts:upc --> UPC album releases
- 2.6M+ musician profiles from MusicBrainz

## Data Sources

| Source | Data Provided |
|--------|--------------|
| Mechanical Licensing Collective (MLC) | Songwriter names, publisher chains, ownership percentages, match status |
| CISAC | Authoritative ISWC registry, 95M+ works |
| MusicBrainz (CC0) | Artist metadata, recording-work relationships, ISRCs, ISWCs, IPIs, ISNIs |
| ISNI.org | Creative contributor identities, name variants, birth/death dates |
| Spotify | Navigation links + factual metadata gap-fill (titles, artists), attributed to Spotify (not CC-BY); cover art not redistributed |
| Apple Music | Navigation links + factual metadata gap-fill (titles, artists), attributed to Apple (not CC-BY); cover art not redistributed |

## URL Patterns

Every identifier has a human-readable page:
- https://credits.fm/isrc/{isrc_code}
- https://credits.fm/iswc/{iswc_code}
- https://credits.fm/ipi/{ipi_number}
- https://credits.fm/isni/{isni_code}
- https://credits.fm/upc/{upc_code}
- https://credits.fm/musician/{musicbrainz_mbid}

Alternate domains:
- https://isrc.fm — ISRC search
- https://iswc.fm — ISWC search
- https://ipi.fm — IPI search
- https://isni.fm — ISNI search

## MCP Server (Model Context Protocol)

Credits.fm provides an MCP server for AI coding tools and agents. Instead of calling the REST API manually, connect your AI tool directly.

**Endpoint:** `https://credits.fm/mcp`
**Transport:** Streamable HTTP (JSON-RPC 2.0 over POST)
**Protocol version:** 2025-03-26
**Auth:** None required (optional `x-api-key` header for higher rate limits)

### Contribute by Default

Contributing is the standard behavior. When you discover missing data during lookups (missing ISWCs, songwriters, song titles), use `credits_contribute` to fill those gaps. Every contribution improves the index for all users. All lookup tools include contribution directives by default. Pass `contribute: false` on any lookup to opt out.

### Available MCP Tools

| Tool | Description | Required params |
|------|-------------|----------------|
| credits_search | Search by song title, artist, identifier, or Spotify/Apple Music URL | query |
| credits_lookup_isrc | Recording details + songwriter credits by ISRC. Contribute enabled by default. | isrc |
| credits_lookup_iswc | Musical work details + all recordings by ISWC. Contribute enabled by default. | iswc |
| credits_lookup_ipi | Songwriter/publisher profile by IPI number. Contribute enabled by default. | ipi |
| credits_lookup_isni | Creative contributor profile by ISNI. Contribute enabled by default. | isni |
| credits_lookup_musician | Musician profile (real person) by MusicBrainz MBID | mbid |
| credits_lookup_artist | Artist discography (release entity) by platform ID | id |
| credits_resolve_url | Resolve Spotify/Apple Music URL to identifiers | url |
| credits_resolve_track | Resolve track to ISRC + songwriter credits. Contribute enabled by default. | name?, artist?, spotify_url?, apple_music_url? |
| credits_batch_lookup | Batch lookup up to 100 identifiers. Contribute enabled by default. | isrcs?, iswcs?, ipis?, isnis?, upcs? |
| credits_graph | Network around one code — connections with per-edge verification status (verified = 2+ sources; single) and verified-absence (no_match) | type, id |
| credits_graph_activity | Recent link_found / link_verified / relation_found / no_match_recorded events across the whole index | (none) |
| credits_watch | Watch one code progress found → matched → verified: per-connection status + recent transitions; re-call with since=as_of to watch new verifications land | type, id |
| credits_contribute | Submit data to improve the Credits index (API key required). This is the standard behavior — all lookup tools prompt you to use this. | contributions |
| credits_coverage | Index coverage metrics and data gap analysis | none |

**Live found → matched → verified progression.** Every lookup result includes a `progression` block: the looked-up code is classed **matched** (one source) or **verified** (2+ independent sources), and each connected code it surfaces is listed as **found**. A looked-up code that resolves but carries no descriptive payload at all — no title, artist, or credits — is also reported as **found**, not matched: the code is in the index but nothing has been established about it yet. The `credits_resolve_url`, `credits_lookup_musician`, and `credits_lookup_artist` results also carry a `progression` — a normalized inventory of the codes they surface (all **found**, since those responses carry no per-code provenance), each with a `credits_watch` pointer. Verification runs asynchronously in the background, so to watch a code cross into **verified**, call `credits_watch` with the code and re-call it with `since={previous as_of}` — it returns each connection's current verified/single/no_match status plus the recent transitions.

### Connect in 30 seconds

Get a free `cfm_` key at https://credits.fm/api. Pass it as header `x-api-key` (raw key, never Bearer). `tools/list` can succeed while lookups fail without a key.

**Cursor Cloud Agents** (native HTTP only — `mcp-remote` is not supported in Cloud):
```json
{"Credits":{"url":"https://credits.fm/mcp","headers":{"x-api-key":"cfm_YOUR_KEY"}}}
```

**Claude Code / Cursor Desktop** (`.mcp.json` / `.cursor/mcp.json`):
```json
{"mcpServers":{"credits":{"type":"http","url":"https://credits.fm/mcp","headers":{"x-api-key":"cfm_YOUR_KEY"}}}}
```

**Demo lookup:** ISRC `GBCEE9800022` (Queen — Bohemian Rhapsody), Freddie Mercury IPI `00077406269`.

**Test with curl:**
```
curl -X POST https://credits.fm/mcp -H "Content-Type: application/json" -H "x-api-key: cfm_YOUR_KEY" -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"credits_lookup_isrc","arguments":{"isrc":"GBCEE9800022","contribute":false}},"id":1}'
```

Full setup guide: https://credits.fm/mcp/docs

## Caching

API responses include `Cache-Control: public, s-maxage=300, stale-while-revalidate=3600`. Detail pages are revalidated every hour.

## Contact

Credits.fm is built by Notes Frequencies, Inc. (https://notes.fm)