mirror of
https://github.com/navidrome/navidrome.git
synced 2026-08-01 07:21:17 +00:00
726 lines
22 KiB
YAML
726 lines
22 KiB
YAML
openapi: 3.0.0
|
||
info:
|
||
version: 0.2.0
|
||
title: Navidrome API
|
||
description: >
|
||
This spec describes the Navidrome API, which allows users to browse and manage their music library via a JSON:API
|
||
based interface. The API provides endpoints for albums, tracks, artists, playlists and images, along with their
|
||
relationships. Clients can retrieve information about the items in the library, filter and sort results, and
|
||
perform actions such as creating and deleting playlists. With this API, developers can build music apps and
|
||
services that integrate with Navidrome music server, providing a seamless experience for users to access and
|
||
manage their music collection.
|
||
contact:
|
||
name: Navidrome
|
||
url: https://navidrome.org
|
||
servers:
|
||
- url: /api/v2
|
||
paths:
|
||
/server:
|
||
get:
|
||
summary: Get server's global info
|
||
operationId: getServerInfo
|
||
responses:
|
||
'200':
|
||
description: The response’s data key maps to a resource object dictionary representing the server.
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data]
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ServerInfo'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/tracks:
|
||
get:
|
||
summary: Get a list of tracks
|
||
operationId: getTracks
|
||
parameters:
|
||
- $ref: '#/components/parameters/pageLimit'
|
||
- $ref: '#/components/parameters/pageOffset'
|
||
- $ref: '#/components/parameters/filterEquals'
|
||
- $ref: '#/components/parameters/filterContains'
|
||
- $ref: '#/components/parameters/filterLessThan'
|
||
- $ref: '#/components/parameters/filterLessOrEqual'
|
||
- $ref: '#/components/parameters/filterGreaterThan'
|
||
- $ref: '#/components/parameters/filterGreaterOrEqual'
|
||
- $ref: '#/components/parameters/filterStartsWith'
|
||
- $ref: '#/components/parameters/filterEndsWith'
|
||
- $ref: '#/components/parameters/sort'
|
||
- $ref: '#/components/parameters/include'
|
||
responses:
|
||
'200':
|
||
description: A list of tracks
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data, links]
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Track'
|
||
links:
|
||
$ref: '#/components/schemas/PaginationLinks'
|
||
meta:
|
||
$ref: '#/components/schemas/PaginationMeta'
|
||
'400':
|
||
$ref: '#/components/responses/BadRequest'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/tracks/{trackId}:
|
||
get:
|
||
summary: Retrieve an individual track
|
||
operationId: getTrack
|
||
parameters:
|
||
- $ref: '#/components/parameters/include'
|
||
- name: trackId
|
||
in: path
|
||
description: The unique identifier of the track
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: A track object
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data]
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Track'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/artists:
|
||
get:
|
||
summary: Retrieve a list of artists
|
||
operationId: getArtists
|
||
parameters:
|
||
- $ref: '#/components/parameters/pageLimit'
|
||
- $ref: '#/components/parameters/pageOffset'
|
||
- $ref: '#/components/parameters/filterEquals'
|
||
- $ref: '#/components/parameters/filterContains'
|
||
- $ref: '#/components/parameters/filterLessThan'
|
||
- $ref: '#/components/parameters/filterLessOrEqual'
|
||
- $ref: '#/components/parameters/filterGreaterThan'
|
||
- $ref: '#/components/parameters/filterGreaterOrEqual'
|
||
- $ref: '#/components/parameters/filterStartsWith'
|
||
- $ref: '#/components/parameters/filterEndsWith'
|
||
- $ref: '#/components/parameters/sort'
|
||
- $ref: '#/components/parameters/include'
|
||
responses:
|
||
'200':
|
||
description: A list of artists
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data, links]
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Artist'
|
||
links:
|
||
$ref: '#/components/schemas/PaginationLinks'
|
||
meta:
|
||
$ref: '#/components/schemas/PaginationMeta'
|
||
'400':
|
||
$ref: '#/components/responses/BadRequest'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/artists/{artistId}:
|
||
get:
|
||
summary: Retrieve an individual artist
|
||
operationId: getArtist
|
||
parameters:
|
||
- $ref: '#/components/parameters/include'
|
||
- name: artistId
|
||
in: path
|
||
description: The unique identifier of the artist
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: An artist object
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data]
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Artist'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/albums:
|
||
get:
|
||
summary: Retrieve a list of albums
|
||
operationId: getAlbums
|
||
parameters:
|
||
- $ref: '#/components/parameters/pageLimit'
|
||
- $ref: '#/components/parameters/pageOffset'
|
||
- $ref: '#/components/parameters/filterEquals'
|
||
- $ref: '#/components/parameters/filterContains'
|
||
- $ref: '#/components/parameters/filterLessThan'
|
||
- $ref: '#/components/parameters/filterLessOrEqual'
|
||
- $ref: '#/components/parameters/filterGreaterThan'
|
||
- $ref: '#/components/parameters/filterGreaterOrEqual'
|
||
- $ref: '#/components/parameters/filterStartsWith'
|
||
- $ref: '#/components/parameters/filterEndsWith'
|
||
- $ref: '#/components/parameters/sort'
|
||
- $ref: '#/components/parameters/include'
|
||
responses:
|
||
'200':
|
||
description: A list of albums
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data, links]
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Album'
|
||
links:
|
||
$ref: '#/components/schemas/PaginationLinks'
|
||
meta:
|
||
$ref: '#/components/schemas/PaginationMeta'
|
||
'400':
|
||
$ref: '#/components/responses/BadRequest'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
/albums/{albumId}:
|
||
get:
|
||
summary: Retrieve an individual album
|
||
operationId: getAlbum
|
||
parameters:
|
||
- $ref: '#/components/parameters/include'
|
||
- name: albumId
|
||
in: path
|
||
description: The unique identifier of the album
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: An album object
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
type: object
|
||
required: [data]
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/Album'
|
||
'403':
|
||
$ref: '#/components/responses/NotAuthorized'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'500':
|
||
$ref: '#/components/responses/InternalServerError'
|
||
|
||
components:
|
||
parameters:
|
||
pageOffset:
|
||
name: page[offset]
|
||
in: query
|
||
description: The offset for pagination
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
format: int32
|
||
minimum: 0
|
||
default: 0
|
||
pageLimit:
|
||
name: page[limit]
|
||
in: query
|
||
description: The number of items per page
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
format: int32
|
||
minimum: 0
|
||
default: 10
|
||
filterEquals:
|
||
name: filter[equals]
|
||
in: query
|
||
description: 'Filter by any property with an exact match. Usage: filter[equals]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\w+'
|
||
filterLessThan:
|
||
name: filter[lessThan]
|
||
in: query
|
||
description: 'Filter by any numeric property less than a value. Usage: filter[lessThan]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\d+'
|
||
filterLessOrEqual:
|
||
name: filter[lessOrEqual]
|
||
in: query
|
||
description: 'Filter by any numeric property less than or equal to a value. Usage: filter[lessOrEqual]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\d+'
|
||
filterGreaterThan:
|
||
name: filter[greaterThan]
|
||
in: query
|
||
description: 'Filter by any numeric property greater than a value. Usage: filter[greaterThan]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\d+'
|
||
filterGreaterOrEqual:
|
||
name: filter[greaterOrEqual]
|
||
in: query
|
||
description: 'Filter by any numeric property greater than or equal to a value. Usage: filter[greaterOrEqual]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\d+'
|
||
filterContains:
|
||
name: filter[contains]
|
||
in: query
|
||
description: 'Filter by any property containing text. Usage: filter[contains]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\w+'
|
||
filterStartsWith:
|
||
name: filter[startsWith]
|
||
in: query
|
||
description: 'Filter by any property that starts with text. Usage: filter[startsWith]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\w+'
|
||
filterEndsWith:
|
||
name: filter[endsWith]
|
||
in: query
|
||
description: 'Filter by any property that ends with text. Usage: filter[endsWith]=property:value'
|
||
required: false
|
||
schema:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern: '^\w+:\w+'
|
||
sort:
|
||
name: sort
|
||
in: query
|
||
description: Sort the results by one or more properties, separated by commas. Prefix the property with '-' for descending order.
|
||
required: false
|
||
schema:
|
||
type: string
|
||
include:
|
||
name: include
|
||
in: query
|
||
description: Related resources to include in the response, separated by commas
|
||
required: false
|
||
schema:
|
||
type: string
|
||
schemas:
|
||
ServerInfo:
|
||
type: object
|
||
required: [server, serverVersion, authRequired, features]
|
||
properties:
|
||
server:
|
||
type: string
|
||
description: The name of the server software.
|
||
example: "navidrome"
|
||
serverVersion:
|
||
type: string
|
||
description: The version number of the server.
|
||
example: "0.60.0"
|
||
authRequired:
|
||
type: boolean
|
||
description: Whether the user has access to the server.
|
||
example: true
|
||
features:
|
||
type: array
|
||
description: A list of optional features the server supports.
|
||
items:
|
||
type: string
|
||
enum:
|
||
- albums
|
||
- artists
|
||
- images
|
||
ResourceObject:
|
||
type: object
|
||
required: [id, type]
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: The unique identifier for the resource
|
||
type:
|
||
$ref: '#/components/schemas/ResourceType'
|
||
ResourceType:
|
||
type: string
|
||
description: The type of the resource
|
||
enum:
|
||
- album
|
||
- artist
|
||
- track
|
||
ResourceList:
|
||
type: object
|
||
properties:
|
||
data:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/Track'
|
||
- $ref: '#/components/schemas/Album'
|
||
- $ref: '#/components/schemas/Artist'
|
||
- type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
included:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/IncludedResource'
|
||
links:
|
||
$ref: '#/components/schemas/PaginationLinks'
|
||
meta:
|
||
$ref: '#/components/schemas/PaginationMeta'
|
||
IncludedResource:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/Track'
|
||
- $ref: '#/components/schemas/Artist'
|
||
discriminator:
|
||
propertyName: type
|
||
mapping:
|
||
track: '#/components/schemas/Track'
|
||
album: '#/components/schemas/Album'
|
||
artist: '#/components/schemas/Artist'
|
||
Track:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResourceObject'
|
||
- type: object
|
||
properties:
|
||
attributes:
|
||
$ref: '#/components/schemas/TrackAttributes'
|
||
relationships:
|
||
$ref: '#/components/schemas/TrackRelationships'
|
||
TrackAttributes:
|
||
type: object
|
||
required: [title, artist, album, albumartist, track, mimetype, duration, channels, bitrate, size]
|
||
properties:
|
||
title:
|
||
type: string
|
||
description: The title of the track
|
||
artist: # TODO: Remove
|
||
type: string
|
||
description: The name of the artist who performed the track
|
||
albumartist: # TODO: Remove
|
||
type: string
|
||
description: The primary artist of the album the track belongs to.
|
||
album: # TODO Remove
|
||
type: string
|
||
description: The name of the album the track belongs to
|
||
genre: # TODO Remove
|
||
type: string
|
||
description: The genre of the track.
|
||
track:
|
||
type: integer
|
||
description: The track number within the album.
|
||
disc:
|
||
type: integer
|
||
description: The disc number within a multi-disc album.
|
||
year:
|
||
type: integer
|
||
description: The release year of the track or album.
|
||
bpm:
|
||
type: integer
|
||
description: The beats per minute (BPM) of the track.
|
||
recording-mbid:
|
||
type: string
|
||
description: The MusicBrainz identifier for the recording of the track.
|
||
track-mbid:
|
||
type: string
|
||
description: The MusicBrainz identifier for the track.
|
||
comments:
|
||
type: string
|
||
description: Any additional comments or notes about the track.
|
||
mimetype:
|
||
type: string
|
||
description: The MIME type of the audio file.
|
||
duration:
|
||
type: number
|
||
format: float
|
||
description: The duration of the track in seconds
|
||
channels:
|
||
type: integer
|
||
description: The number of audio channels in the track.
|
||
bitrate:
|
||
type: integer
|
||
description: The bitrate of the audio file in kilobits per second (kbps).
|
||
size:
|
||
type: integer
|
||
description: The size of the audio file in bytes.
|
||
TrackRelationships:
|
||
type: object
|
||
properties:
|
||
artists:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/TrackArtistRelationship'
|
||
albums:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AlbumTrackRelationship'
|
||
required:
|
||
- artists
|
||
TrackArtistRelationship:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: #/components/schemas/ArtistMetaObject
|
||
data:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
required:
|
||
- meta
|
||
- data
|
||
ArtistRole:
|
||
type: string
|
||
enum:
|
||
- artist
|
||
- albumArtist
|
||
description: The role of an artist in a track or album
|
||
Artist:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResourceObject'
|
||
- type: object
|
||
properties:
|
||
attributes:
|
||
$ref: '#/components/schemas/ArtistAttributes'
|
||
relationships:
|
||
type: object
|
||
properties:
|
||
tracks:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ArtistTrackRelationship'
|
||
required:
|
||
- data
|
||
albums:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ArtistAlbumRelationship'
|
||
required:
|
||
- data
|
||
ArtistAttributes:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The name of the artist
|
||
bio:
|
||
type: string
|
||
description: A short biography of the artist
|
||
ArtistAlbumRelationship:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: '#/components/schemas/ArtistMetaObject'
|
||
data:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
required:
|
||
- meta
|
||
- data
|
||
ArtistTrackRelationship:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
type: object
|
||
properties:
|
||
role:
|
||
$ref: '#/components/schemas/ArtistRole'
|
||
required:
|
||
- role
|
||
data:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
required:
|
||
- meta
|
||
- data
|
||
ArtistMetaObject:
|
||
type: object
|
||
properties:
|
||
role:
|
||
$ref: '#/components/schemas/ArtistRole'
|
||
required:
|
||
- role
|
||
Album:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ResourceObject'
|
||
- type: object
|
||
properties:
|
||
attributes:
|
||
$ref: '#/components/schemas/AlbumAttributes'
|
||
relationships:
|
||
type: object
|
||
properties:
|
||
artists:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AlbumArtistRelationship'
|
||
tracks:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AlbumTrackRelationship'
|
||
required:
|
||
- artists
|
||
- tracks
|
||
AlbumAttributes:
|
||
type: object
|
||
properties:
|
||
title:
|
||
type: string
|
||
description: The title of the album
|
||
releaseDate:
|
||
type: string
|
||
format: date
|
||
description: The release date of the album
|
||
genre:
|
||
type: string
|
||
description: The genre of the album
|
||
required:
|
||
- title
|
||
- releaseDate
|
||
- genre
|
||
AlbumArtistRelationship:
|
||
type: object
|
||
properties:
|
||
meta:
|
||
$ref: #/components/schemas/ArtistMetaObject
|
||
data:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
required:
|
||
- meta
|
||
- data
|
||
AlbumTrackRelationship:
|
||
type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ResourceObject'
|
||
required:
|
||
- data
|
||
PaginationLinks:
|
||
type: object
|
||
properties:
|
||
first:
|
||
type: string
|
||
format: uri
|
||
prev:
|
||
type: string
|
||
format: uri
|
||
next:
|
||
type: string
|
||
format: uri
|
||
last:
|
||
type: string
|
||
format: uri
|
||
PaginationMeta:
|
||
type: object
|
||
properties:
|
||
currentPage:
|
||
type: integer
|
||
format: int32
|
||
description: The current page in the collection
|
||
totalPages:
|
||
type: integer
|
||
format: int32
|
||
description: The total numeber of pages in the collection
|
||
totalItems:
|
||
type: integer
|
||
format: int32
|
||
description: The total number of items in the collection
|
||
ErrorList:
|
||
type: object
|
||
required: [errors]
|
||
properties:
|
||
errors:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ErrorObject'
|
||
ErrorObject:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
status:
|
||
type: string
|
||
title:
|
||
type: string
|
||
detail:
|
||
type: string
|
||
required:
|
||
- errors
|
||
responses:
|
||
NotFound:
|
||
description: Not Found
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorList'
|
||
NotAuthorized:
|
||
description: Not Authorized
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorList'
|
||
BadRequest:
|
||
description: Bad Request
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorList'
|
||
InternalServerError:
|
||
description: Internal Server Error
|
||
content:
|
||
application/vnd.api+json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorList'
|