Works

Technical catalogue inventory for ingested musical works with GET /v1/works.

The works endpoints expose technical catalogue inventory for musical compositions (the underlying work), distinct from tracks which represent recordings of those works.

Works vs tracks

A work is the composition (title, ISWC when available). A track is a specific recording (ISRC, audio assets). Work inventory returns the fields documented in OpenAPI for list and detail calls.

Scope and access

  • GET /v1/works lists works visible in organisation-owned catalogues through your current API context.
  • 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/works/{work_id} uses the MusiMap work 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.

List works

curl "https://api.musimap.com/v1/works?iswc=T-010.171.157-7" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Supported list filters include:

  • outer_id — client/source-side identifier.
  • title — exact title match (case-insensitive).
  • iswc, source_record_key, delivery_id.
  • created_after, created_before, updated_after, updated_before.
  • page, page_size (1–100) for pagination.

List responses use the standard MusiMap paginated envelope inside data. See Pagination.

Typical response fields

Each work summary in data.results includes:

  • id — MusiMap canonical work UUID.
  • title, optional iswc.
  • catalog_id, outer_id when present.
  • created_at, updated_at.

Get one work

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

Detail responses use the same public summary fields as list rows in V1. Returns HTTP 404 when the work does not exist or is outside your access scope.

  • Tracks — recording inventory (ISRC, audio metadata).
  • Releases — product/album inventory.
  • Artists — performer inventory.

Errors

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