IntroductionGet your Record API keyQuickstartAuthenticationCatalogue lifecycleDestinationsRecord AIWorkspace and rolesOverviewSend worksShare semanticsCatalogue routingValidation and gapsLoad a full catalogueEndpoint referenceOverviewSingle lookupBatch lookupCheck an IPIRoadmapErrorsRate limits and retriesGlossaryVersioning

Partner Metadata API

Overview

Look up and verify identifiers, and pull metadata and cover art, as an approved partner.

Machine-to-machine endpoints for approved partners. Look up a recording or a work by identifier. Verify the identifier against the title and artist you hold. Pull the metadata and cover art Record holds for it.

Two endpoints ship today: a single lookup and a batch lookup. Roadmap shows where this surface grows.

Base URL: https://ingest.takerecord.com

Authentication#

Every request carries a Bearer token:

code
Authorization: Bearer trk_live_<key>

The key uses the same system as the Catalogue Ingest API. A workspace owner or admin creates it in Settings, under API keys, with the use "Look up metadata". That gives it the metadata:read scope. Keys issued before September 2026 carry the older name covers:read, which still works.

It is not tied to one client. A reporting partner may serve several catalogue clients, so a scope gates access, not a tenant binding. You can revoke, rotate and expire it on its own, and we track its use per key.

Send no x-client-id. Identifiers, metadata and covers are shared reference data, and they are not tenant-scoped. Per-client endpoints on the roadmap will accept an x-client-id authorised against the catalogue clients a partner acts for.

Rate limit: 600 requests per minute per key for a single lookup. A 429 response carries a Retry-After header in seconds. Wait that long, then retry.

To preload a whole catalogue, use the batch lookup rather than one request per asset.

Errors always carry error (human readable) and code (a machine code). Some add a field such as param, which names the offending input.

Keep the request id#

Every response, success or error, carries an x-request-id header. It is a UUID (universally unique identifier). We store one record under that id for every request that carries a valid key. The record holds the identifiers you sent, the ISRC and Apple album we served, the confidence and the verification verdict. If that write fails on our side, the response still returns and we log the failure.

Store the id next to the cover URL you keep, the same way you store the URL. A report that quotes it is a direct lookup on our side. A report without it is a reconstruction.

Measure our time#

A response to a valid key also carries a Server-Timing header. It gives our time in milliseconds for three stages: auth, ratelimit and handler. Subtract their sum from the time you measure. The rest is the network between you and our servers, which are in the US West region.

Report a wrong cover#

Send us, for each affected asset:

  • the x-request-id of the response you stored
  • the identifier you sent (isrc, iswc or external_id) and the title and artist if you sent them
  • the matched block you received
  • the time of the request, in UTC

We answer from the stored record, so the report does not depend on a re-run. An identifier-only response is cacheable for a day. A corrected cover reaches your cache when the old entry expires, or when you check a stored cover with If-None-Match and the stored ETag. A cache that honours max-age will not check on its own before the day ends.