Batch lookup

POST/api/v1/metadata/album-covers

Look up up to 100 identifiers in one request. This is the path for preloading a catalogue: one request instead of one per asset. Same auth and covers:read scope as the single endpoint.

Request body#

{
  "items": [
    { "id": "row-1", "isrc": "USRC12345678", "title": "Black Sheep", "artist": "Kng Ego" },
    { "id": "row-2", "iswc": "T-123.456.789-0" },
    { "id": "row-3", "external_id": "A12345" }
  ],
  "allow_title_fallback": false
}

• Each item takes the same fields as the single endpoint (isrc, iswc, external_id, plus optional title/artist/album for verification).
• id is optional; we echo it back so you can map results without relying on order (results are also returned in input order).
• allow_title_fallback is a single top-level flag applied to every item (off by default; still gated on our side).
• Max 100 items per request; more returns a 400.

Response#

{
  "schema_version": "1.0",
  "results": [
    { "id": "row-1", "status": "ok", "result": { /* same shape as the single endpoint */ } },
    { "id": "row-2", "status": "not_found" },
    { "id": "row-3", "status": "invalid", "error": { "code": "INVALID_IDENTIFIER", "message": "...", "param": "isrc" } }
  ]
}

Each item carries a status of ok, not_found, invalid or source_unavailable. The last one is a transient per-item failure at the cover source. One bad item never fails the whole batch.

The request itself returns 400 only for a malformed body, such as bad JSON or an empty or oversized items. It returns 401 or 403 for auth. It returns 503 only when the cover source is down for the whole request.

Rate limit: 120 batch requests/minute per key (each request already covers up to 100 assets).

curl -s -X POST -H "Authorization: Bearer $TRK_KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"id":"1","isrc":"USRC12345678"},{"id":"2","iswc":"T-123.456.789-0"}]}' \
  "https://ingest.takerecord.com/api/v1/metadata/album-covers"