The specification uses a small set of resource types:

• song
• album
• artist
• playlist
• station

Each resource has an id, a singular type, an attributes object, and optional relationships.

First Request

Clients should request GET / first. The info response contains branding, the OpenMusic version, available capabilities, and supported authentication methods.

Capabilities currently include:

Query Conventions

lang is a BCP 47 language tag, for example en-US, de-CH, or ja-JP. Servers may ignore localization. When localized data is available, the requested language should be used where possible.

include embeds relationships in a response. Include paths use relationship names:

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

Nested includes may be up to three levels deep from the root resource.

Fields are always scoped by resource type:

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

Included relationships 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

Root list, relationship, search, and explore endpoints support limit. The usual maximum is 100. Search uses one limit for all requested groups, except top, which always returns at most 10 resources. Search suggestions always return at most 10 suggestions.

Root list and relationship endpoints support offset and sort. Sorting supports name, dateAdded, and minus-prefixed descending variants. Song and album result sets also support releaseDate.

Files

Music files are described by MusicFile. A file may expose direct streamUrl and downloadUrl values. If those are omitted, clients can use the default routes:

GET /file/{id}/stream
GET /file/{id}/download

Streaming implementations should support Range requests and return 206 Partial Content for partial responses. If streaming is not supported, /file/{id}/stream returns 501.