Songs are the main playable resource. A song contains display metadata, one preferred file, optional alternative files, and relationships to albums and artists.

List Songs

Use GET /songs to page through the catalog.

GET /songs?limit=25&offset=0&sort=name

The response is a List<Song>.

Look Up Songs

Use lookup when you already have ids or ISRCs. Lookup results keep the request order and omit missing resources.

GET /songs/lookup?ids=song_1,omm:song:song_2
GET /songs/lookup?isrc=USRC17607839,GBARL0600786

Lookup requests should contain at most 100 ids.

Fetch One Song

Use GET /song/{id} when you know the song id.

GET /song/song_123

The response is Single<Song>.

Include Relationships

Use relationship names in include.

GET /song/song_123?include=albums,artists
GET /song/song_123?include=albums,albums.tracks

Fields are scoped by resource type:

GET /song/song_123?fields[song]=name,artworkUrl

Included relationship lists can be limited and sorted with singular resource:relationship syntax:

GET /song/song_123?include=albums,albums.tracks&limit[album:tracks]=10&sort[album:tracks]=name

Relationship Endpoints

Use relationship endpoints when you only need the related resources.

GET /song/song_123/rel/albums
GET /song/song_123/rel/artists

Relationship endpoints return lists and support fields[...], limit, offset, and sort.

Files

The preferred file is available at attributes.files.preferred. If a file does not include streamUrl or downloadUrl, use:

GET /file/{fileId}/stream
GET /file/{fileId}/download