Tracks

Technical catalogue inventory for ingested tracks with GET /v1/tracks.

The tracks endpoints expose technical catalogue inventory: what your organisation has ingested, which client identifiers were delivered, and safe audio metadata such as received filenames. They answer operational questions about your catalogue contents.

Not advanced music search

These endpoints list ingested catalogue rows with delivery metadata. For MusiTag analysis, semantic filters, and track discovery, use Catalogue search and the tagging guides.

Scope and access

  • GET /v1/tracks lists tracks visible in organisation-owned catalogues through your current API context.
  • Inventory endpoints return rows from catalogues your token can access through organisation-owned catalogues.
  • In V1, inventory is scoped to the token's current catalogue context from /v1/me (catalog_id). An optional catalog_id query filter must match that context.
  • GET /v1/tracks/{track_id} uses the MusiMap track UUID only. Client/source ids belong in the outer_id list filter.
  • OAuth scope: catalog.read. Request this scope when exchanging client credentials. Tenant and catalogue access is enforced on every call.
  • To read a track from MusiMap Atlas (for example after MusiSearch returns source.layer: "musimap-atlas"), call GET /v1/tracks/{track_id}?source=musimap-atlas. Requires musimap-atlas.read and organisation entitlement musimap_atlas_read. See MusiMap Atlas.

List tracks

curl "https://api.musimap.com/v1/tracks?outer_id=qobuz_123456" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Supported technical filters include:

  • outer_id — client/source-side identifier.
  • isrc, source_record_key, delivery_id.
  • analysis_status, has_audio, has_analysis.
  • created_after, created_before, updated_after, updated_before.
  • page, page_size for pagination.

List responses use the standard MusiMap paginated envelope inside data: count, page, page_size, total_pages, has_next, has_previous, and results.

Get one track

curl "https://api.musimap.com/v1/tracks/$MUSIMAP_TRACK_UUID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

For MusiMap Atlas items, pass source=musimap-atlas: 

curl "https://api.musimap.com/v1/tracks/$MUSIMAP_TRACK_UUID?source=musimap-atlas" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Detail responses may include an audio_assets array with safe metadata such as received filename, content type, duration, and a technical availability status.

Audio access

MusiMap does not provide audio download or streaming through these endpoints. You supplied the audio during ingestion; to listen to it, use your own storage or source system. Storage paths, bucket names, object keys, and signed URLs are never returned.

Errors

Missing or invalid tokens return HTTP 401 with the MusiMap error envelope. Inaccessible track ids return HTTP 404 with data.error_code: "not_found" so callers cannot infer cross-tenant existence.