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

Machine-readable OpenAPI 3.1 spec: https://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, ownership share percentages, match status. 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** — platform links, cover art, basic track metadata

**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://credits.fm/api/search?q=bohemian+rhapsody&type=auto&limit=10
```

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

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

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

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

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

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

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

## Usage Patterns

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

**Pattern 2: "Show me all recordings of this composition"**
1. Look up the ISWC: `GET /api/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 /api/ipi/00014107449`
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 /api/ipi/00014107449/publishers`
2. Response includes every publisher with name, IPI, role, and shared song count
3. If you only have a name + ISRCs: `POST /api/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 /api/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 `/api/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://credits.fm/api/isrc/GBAYE0601498
curl "https://credits.fm/api/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 `00014107449` → `creditsId`: `699e9761-6d67-5175-81a1-2585fd31e581` (from `ipi:00014107449`)
- 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://credits.fm/api/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"
    }
  ],
  "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://credits.fm/api/isrc/{isrc_code}
```

Returns recording details, songwriter credits, publisher chains, platform links, and ownership data.

**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": "FREDDIE MERCURY",
      "ipi": "00014107449",
      "role": "Composer/Author",
      "sharePercentage": 100,
      "publishers": [
        {
          "name": "QUEEN MUSIC LTD",
          "ipi": "00148617856",
          "role": "E"
        }
      ]
    }
  ],
  "totalSharePercentage": 100,
  "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
  - `publishers` — Array of publisher objects with `name`, `ipi`, `role` (E=original publisher, SE=sub-publisher, AM=administrator)
- `totalSharePercentage` — Sum of all songwriter shares
- `platforms` — Platform identifiers
- `updatedAt` — Last data refresh timestamp

### 3. ISWC Lookup
```
GET https://credits.fm/api/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": "FREDDIE MERCURY",
      "ipi": "00014107449",
      "roles": ["Composer", "Author"]
    }
  ],
  "songwriterCount": 1,
  "artistNames": ["Queen"],
  "ipis": ["00014107449"],
  "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://credits.fm/api/ipi/{ipi_code}
```

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

**Response example:**
```json
{
  "creditsId": "699e9761-6d67-5175-81a1-2585fd31e581",
  "ipi": "00014107449",
  "fullName": "FREDDIE MERCURY",
  "roles": ["Composer", "Author"],
  "entityType": "songwriter",
  "iswcCount": 168,
  "iswcs": ["T-070237966-1", "T-070245035-9"],
  "isrcCount": 847,
  "isrcs": ["GBAYE0601498", "USUM71922944"],
  "relatedEntities": [
    {
      "ipi": "00008579576",
      "name": "BRIAN MAY",
      "type": "co-writer"
    }
  ],
  "linkedISNIs": ["0000000121269154"],
  "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
- `updatedAt` — Last data refresh timestamp

### 4b. Publishers for Songwriter
```
GET https://credits.fm/api/ipi/{ipi_code}/publishers
GET https://credits.fm/api/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": "00014107449",
  "name": "FREDDIE MERCURY",
  "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://credits.fm/api/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": "Mercury",
  "resolved": true,
  "ipi": "00014107449",
  "fullName": "FREDDIE MERCURY",
  "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://credits.fm/api/ipi/00123456789/publishers" },
    { "ipi": "00987654321", "name": "SARAH BAKER", "roles": ["Author"], "matchedIsrcCount": 3, "publishersUrl": "https://credits.fm/api/ipi/00987654321/publishers" }
  ],
  "message": "Found 2 songwriters matching \"Baker\". Use the IPI from the correct match."
}
```

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

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

**Response example:**
```json
{
  "creditsId": "c4d5e6f7-a8b9-5012-3456-789abcdef012",
  "isni": "0000000121174866",
  "fullName": "Freddie Mercury",
  "entityType": "performer",
  "roles": ["singer", "songwriter", "musician"],
  "linkedIPIs": ["00014107449"],
  "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://credits.fm/api/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 /api/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://credits.fm/api/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 /api/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": "https://i.scdn.co/image/...",
    "genres": ["classic rock", "rock"]
  },
  "totalTracks": 287,
  "albums": [
    {
      "id": "6i6folBtxKV28WX3msQ4FE",
      "name": "A Night At The Opera",
      "releaseDate": "1975-11-21",
      "coverArtUrl": "https://i.scdn.co/image/...",
      "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": "https://i.scdn.co/image/...",
      "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://credits.fm/api/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": "FREDDIE MERCURY",
          "ipi": "00014107449",
          "role": "Composer/Author",
          "sharePercentage": 100,
          "publishers": [
            {
              "name": "QUEEN MUSIC LTD",
              "ipi": "00148617856",
              "role": "E"
            }
          ]
        }
      ],
      "totalSharePercentage": 100,
      "platforms": [],
      "sources": ["credits_db", "notes_credits_api"],
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  },
  "ipis": {
    "00014107449": {
      "creditsId": "699e9761-6d67-5175-81a1-2585fd31e581",
      "ipi": "00014107449",
      "fullName": "FREDDIE MERCURY",
      "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://credits.fm/api/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://credits.fm/api/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": "https://i.scdn.co/image/ab67616d0000b273...",
  "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": "https://i.scdn.co/image/...",
  "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": "https://i.scdn.co/image/...",
  "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": "https://i.scdn.co/image/...",
      "trackNumber": 1,
      "discNumber": 1,
      "creditsUrl": "https://credits.fm/isrc/GBAYE0601498"
    }
  ]
}
```

### 11. Track Resolution
```
POST https://credits.fm/api/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://credits.fm/api/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": "9b033599-8a5e-565a-b6b6-2dafbb91939c", "name": "Bohemian Rhapsody", "artist": "Queen", "isrc": "GBAYE0601498", "credits_url": "https://credits.fm/isrc/GBAYE0601498" },
    { "creditsId": "4e5f6a7b-c8d9-5012-3ef0-123456789abc", "name": "Stairway to Heaven", "artist": "Led Zeppelin", "isrc": "GBZZ7000006", "credits_url": "https://credits.fm/isrc/GBZZ7000006" }
  ]
}
```

### 13. Contribute Data
```
POST https://credits.fm/api/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 missing data to improve the Credits index. Requires a free API key. Contributions are validated and either auto-accepted or queued for review based on trust score.

**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`, or `append` |
| 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.

### 14. Coverage Metrics
```
GET https://credits.fm/api/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 }
}
```

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

Validate ISRCs against MLC ownership data and optionally cross-reference with Spotify and Apple Music. Returns match status, songwriter shares, and any issues found. 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://credits.fm/api/audit/shares
Content-Type: application/json
Body: {"isrcs": ["GBAYE0601498", "USRC17607839"]}
```

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://credits.fm/api/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

- 30M+ ISRC recordings from MLC, MusicBrainz, Spotify, Apple Music
- 95M+ ISWC musical works from CISAC international registry
- 100K+ IPI songwriter/publisher profiles
- 100K+ ISNI creative contributor identities
- 3M+ 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 | Platform links, cover art, track metadata |
| Apple Music | Platform links, cover art, composer credits |

## 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_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 |

### Connect in 30 seconds

**Claude Code** (`.mcp.json`):
```json
{"mcpServers":{"credits":{"type":"http","url":"https://credits.fm/mcp"}}}
```

**Cursor** (`.cursor/mcp.json`):
```json
{"mcpServers":{"credits":{"command":"npx","args":["mcp-remote","https://credits.fm/mcp"]}}}
```

**Test with curl:**
```
curl -X POST https://credits.fm/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"tools/list","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)