Tracks

The tracks endpoints expose technical catalogue inventory on two planes: organisation-owned Workspace (/v1/workspace/tracks) and read-only Atlas (/v1/atlas/tracks). They answer operational questions about catalogue contents, not open-ended discovery.

Workspace and Atlas

• GET /v1/workspace/tracks and GET /v1/workspace/tracks/{track_id}: organisation Workspace catalogues. OAuth scope catalog.read.
• POST /v1/workspace/tracks and PATCH /v1/workspace/tracks/{track_id}: create or update Workspace tracks. OAuth scope catalog.write.
• GET /v1/atlas/tracks and GET /v1/atlas/tracks/{track_id}: MusiMap Atlas. OAuth scope atlas.read.
• There is no flat /v1/tracks path and no entity delete.
• Request the OAuth scopes your integration needs when exchanging client credentials.

Catalogue context for Workspace depends on client binding. Bound clients use the bound catalogue from /v1/me.catalog_id; an optional catalog_id query must match that binding. Unbound clients omit catalog_id to use the organisation default, or pass an organisation-accessible catalog_id. See Catalogues.

Include expansions

On detail GET only (for example /v1/workspace/tracks/{track_id}), pass include as a comma-separated list of expansion groups (for example details,references,credits,tags). Use include=all for the plane-specific allowlist. Unknown tokens return HTTP 400. List endpoints do not support include.

List Workspace tracks

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

Supported technical filters include:

• outer_id: client/source-side identifier.
• isrc, source_record_key, delivery_id.
• label_id: tracks placed on a release credited to that label.
• analysis_status, has_audio, has_analysis.
• created_after, created_before, updated_after, updated_before.
• page, page_size for pagination.

Identifier filters (isrc, outer_id, and similar ids) use exact (normalized) match. Track lists have no free-text title filter; use Catalogue search for recording discovery. Multiple filters combine with logical AND. Pagination applies after filters. A date window value that is not a real date matches nothing. Unsupported query parameters return HTTP 400.

Get one Workspace track

curl "https://api.musimap.com/v1/workspace/tracks/$MUSIMAP_TRACK_UUID?include=details,tags" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Path ids are MusiMap track UUIDs. Client/source ids belong in the outer_id list filter.

Atlas tracks

Browse and filter Atlas inventory directly via /v1/atlas/tracks. For relevance-based discovery across Workspace and Atlas, use MusiSearch, then retrieve the selected track from its plane inventory endpoint when you need the full record. See Atlas.

List Atlas tracks

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

The same identifier and pagination semantics apply as on Workspace lists: isrc / outer_id are exact (normalized) matches; multiple filters AND; pagination is computed after filters; unsupported query parameters return HTTP 400.

Get one Atlas track

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

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. Invalid include values return HTTP 400.