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 on lists, creates, detail reads, and patches (for example POST /v1/workspace/tracks?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.

Create a Workspace track

curl -X POST "https://api.musimap.com/v1/workspace/tracks?catalog_id=$CATALOG_UUID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Example Track",
    "outer_id": "external-track-123"
  }'

outer_id is an optional client-supplied external identifier stored on the catalogue membership (organisation + catalogue scoped). It is returned on subsequent GET list/detail responses and can be used as a list filter. Omitting it is valid. It is not an ISRC or other industry identifier and is not accepted on PATCH. Reusing the same outer_id on a later create does not update an existing resource (no upsert). Unbound clients may pass catalog_id as a query parameter; see Catalogues.

Update a Workspace track

curl -X PATCH "https://api.musimap.com/v1/workspace/tracks/$MUSIMAP_TRACK_UUID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Title" }'

PATCH accepts identity fields such as title. It does not accept outer_id.

Atlas tracks

Browse and filter Atlas inventory directly via /v1/atlas/tracks. For structured track search across Workspace and Atlas, use Catalogue search, 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.