Single lookup

GET/api/v1/metadata/lookup

One asset, looked up by identifier. The response says what the identifier resolves to. It gives a verification verdict against the title and artist you send. It carries the album and recording metadata and the cover art we hold. The same endpoint answers at /api/v1/metadata/album-cover, its original name, kept for the partner that calls it today.

Query parameters#

Provide at least one identifier, or title and writer, or title and artist with allow_title_fallback=true.

Send everything you have. When you send both isrc and iswc, they cross-check each other. See matched.confirmed and identifier_conflict. A title and artist let us tell you when a bad statement ISRC resolved to the wrong asset.

Verification (recommended for catching bad ISRCs). Pass the title and artist from your statement alongside the identifier. We resolve by identifier as usual, then compare our resolved metadata to what you sent and return a verification block. When both your title and artist disagree with the resolved asset, we add a metadata_mismatch warning, the strong signal that the statement ISRC is wrong. An artist-only difference raises no warning, so a writer named where the performer was expected does not false-alarm.

A title check on iswc and external_id lookups. These identifiers name a work, and we find its recordings through MLC links. Some links point at another work's recording. So when you send a title, we serve the cover only when the recording's title matches yours. Spelling differences such as "U DONT KNOW ME LIKE THAT" and "U Don't Know Me Like Dat" still match. Otherwise we answer 404, and the message names the recording and its ISRC. Look that ISRC up yourself if you know it is the right recording.

The 404 body carries a refusal when we refuse a cover for its title:

• title_near_miss: the two titles are close, for example "Sin" and "Sing". One title can have a typing error. The hint starts with "This may be the same song.". Send these rows to a person to check.
• title_mismatch: the two titles are far apart. Treat the row as a miss.

A 404 for any other cause has no refusal.

The same performer, a different recording. When the artist agrees and the title does not, we add a recording_mismatch warning. The code resolves to a different recording by the same performer, which is how an ISRC issued twice presents. Do not send that code on a new recording.

Title and writer, for rows with no identifier. You pass a title and one or more writer names, and no identifier resolves. We then resolve the composition by title corroborated by a writer, never by title alone. We return the cover from that work's recordings.

When two or more works carry that title and a matching writer, we answer 404 rather than guess. Writers match by name, so a shared name cannot pick between two compositions. When exactly one work matches, the result carries via: "title_writer" and confidence: "low". It suits a source like ASCAP that carries a composer and a title, but no ISRC, ISWC or performing artist.

Title-search fallback. Opt-in, low confidence, covers only. By default this endpoint uses identifiers only. A closest match by title is exactly the failure that produces a wrong cover.

Pass allow_title_fallback=true with a title and artist, and we search by artist and title when no identifier resolves. We return a cover only when the match is unambiguous, meaning exactly one recording matches. Anything ambiguous returns a 404 rather than a guess. We measured it against 300 covers we already knew: it answered 128, and 121 of those were the right recording. It refused the other 172 as ambiguous or not found. Check every result with confidence: "low" before you publish it.

We flag such a result via: "title_search" and confidence: "low", with a title_search_fallback warning. Treat it as best effort, not as authority.

Response (200)#

{
  "schema_version": "1.0",
  "cover": {
    "url": "https://...mzstatic.com/.../1400x1400bb.jpg",
    "url_template": "https://...mzstatic.com/.../{w}x{h}bb.jpg",
    "source": "apple"
  },
  "song": {
    "title": "Black Sheep",
    "duration_ms": 183000,
    "track_number": 3,
    "preview_url": "https://...",
    "apple_music_url": "https://music.apple.com/..."
  },
  "album": {
    "name": "Original Album",
    "release_date": "2021-03-19",
    "artist_name": "Kng Ego",
    "genres": ["Hip-Hop/Rap"],
    "label": "Label Records",
    "upc": "0001112223334",
    "album_type": "Album"
  },
  "matched": {
    "via": "isrc",
    "isrc": "USRC12345678",
    "iswc": "T-123.456.789-0",
    "apple_album_id": "1440857781",
    "confirmed": true,
    "confidence": "high",
    "bridged": false
  },
  "verification": {
    "supplied_title": "Black Sheep",
    "supplied_artist": "Kng Ego",
    "supplied_album": null,
    "resolved_title": "Black Sheep",
    "resolved_artist": "Kng Ego",
    "resolved_album": "Original Album",
    "title_match": true,
    "artist_match": true,
    "verdict": "match"
  },
  "warnings": []
}

Field notes:

• cover.url is a public Apple CDN link (1400x1400). cover.url_template contains literal {w}x{h} placeholders; substitute any size you need. Fetch and store on your side; we serve links, not image bytes.
• Cover choice is deterministic: the song's own album, preferring the earliest artwork-bearing release (the original release). This replaces the "latest released" heuristic that picks re-releases and compilations.
• song carries recording-level extras Apple gives us on the same lookup (duration, track number, a short audio preview URL, the Apple Music page).
• matched tells you how the asset was identified. via is the identifier that anchored the result (title_writer for a title + writer resolution, or title_search for the opt-in fallback). confirmed: true means two independent identifiers (ISRC and ISWC) agreed. confidence is high for an identifier resolution and low for a title_writer or title_search result. bridged: true means you named a work (an iswc, an external_id, or a title + writer) and we chose one of its recordings from the MLC's recording links. Those links can point at recordings of other works. Send a title with such requests and read verification. It is false when your ISRC named the recording.
• verification appears only when you pass title/artist/album. verdict reflects the fields you supplied: match (all agree), mismatch (all disagree), partial (mixed, only when you supply both title and artist), unknown (for every field you supplied, we hold nothing to compare it with: a supplied title needs our title or album, a supplied album needs our album, a supplied artist needs our artist; no warning is raised). The actionable signals are the warnings. metadata_mismatch is raised only when you supplied both a title and an artist and both disagree. recording_mismatch is raised when the artist agrees and the title does not. A title-only or artist-only request can read verdict: mismatch without a warning.
• warnings surface degraded-but-servable outcomes instead of hiding them:
  • identifier_conflict: your ISRC and ISWC point at different works, or an unconfirmed ISRC result conflicts with the title evidence you supplied. We anchor on the ISWC (work-level identity is the trustworthy one when statements carry bad ISRCs) and tell you, so you can flag the statement row.
  • metadata_mismatch: your supplied title AND artist both disagree with the resolved asset, a likely wrong statement ISRC. The cover is still returned; treat it as suspect.
  • recording_mismatch: your artist agrees and your title does not. The code resolves to a different recording by the same performer. Do not send that code on a new recording.
  • title_search_fallback: the result came from the opt-in low-confidence artist+title search, not an identifier. Best-effort, not authoritative.
  • artwork_unavailable: the asset resolved but we hold no cover; metadata fields are still populated where known.
  • isrc_invalid_ignored / iswc_invalid_ignored: one identifier was malformed; we proceeded on the valid one.
  • iswc_unmatched: the ISWC is unknown to us; the result is ISRC-anchored.
  • mirror_stale: our copy of the Apple catalogue is older than its refresh interval. A cover or a recording changed since may not show. A 404 during that time carries the same note in hint.
• Missing values are explicit nulls, never invented. "Unknown Artist" will never appear.
• During our Apple data refresh a first lookup of a recording can take up to 15 seconds, and one request spends at most 20 seconds on our cover source before it answers 503. Set your client timeout above that.
• Identifier-only 200 responses are publicly cacheable for a day: Cache-Control: public, max-age=86400. Responses that include supplied verification or fallback fields are private-cacheable for a day: Cache-Control: private, max-age=86400.
• Every 200 carries an ETag. Store it with the cover. To check a stored cover, repeat the request with If-None-Match: <etag>. A 304 with no body means your copy stands. A 200 carries the new cover. A corrected cover reaches you at your next check, not when the day ends. A check runs the full lookup on our side and counts against your rate limit. It saves bytes, not requests.

Error responses#

Quickstart#

# By ISRC
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/lookup?isrc=USRC12345678"

# By ISWC only (no ISRC needed: this is the lookup ACRCloud could not do)
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/lookup?iswc=T-123.456.789-0"

# Both: the identifiers cross-check each other; watch matched.confirmed / warnings
curl -s -H "Authorization: Bearer $TRK_KEY" \
  "https://ingest.takerecord.com/api/v1/metadata/lookup?isrc=USRC12345678&iswc=T-123.456.789-0"