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

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: "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, and platform URLs
3. Use search to find the ISRC in the database

**Pattern 5: "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"],
  "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
- `songwriters` — Array of songwriter objects with `name`, `ipi`, `roles`
- `songwriterCount` — Number of credited songwriters
- `artistNames` — Array of performing artist names
- `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"
    }
  ],
  "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`
- `avgSharePercentage` — Average ownership share percentage
- `updatedAt` — Last data refresh timestamp

### 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"],
  "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
- `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 or album metadata.

**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
    }
  ]
}
```

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