Navidrome Server API

openapi: 3.2.0
info:
  title: Navidrome Server API
  version: 1.0.0
  description: 'Navidrome API v1. Spec-first, additive within v1. Clients discover implemented

    capability modules through `GET /server` and never sniff versions.


    Enums are open: new values may be added to any enum within v1. Clients must

    accept values they do not recognise instead of failing.


    Every operation declares `x-stability-level`: `alpha` operations may change or

    disappear without notice, `beta` and `stable` operations only change additively.

    A level is only ever raised, never lowered.


    `HEAD` is accepted wherever `GET` is. A `405` response lists the allowed methods

    in its `Allow` header.'
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
servers:
- url: /api/v1
tags:
- name: Server
  description: Server discovery and the published OpenAPI document.
paths:
  /server:
    get:
      operationId: getServerInfo
      x-module: core
      x-stability-level: alpha
      tags:
      - Server
      summary: Describe the server
      description: 'Returns the public server description. No authentication required.

        Authenticated requests will additionally receive the implemented capability modules

        once authentication is available.'
      responses:
        '200':
          description: Server description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /openapi.json:
    get:
      operationId: getOpenAPISpecJSON
      x-module: core
      x-stability-level: alpha
      tags:
      - Server
      summary: Get the OpenAPI document (JSON)
      description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
      responses:
        '200':
          description: The OpenAPI document.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                type: object
                description: OpenAPI 3.0 document.
        '304':
          $ref: '#/components/responses/NotModified'
  /openapi.yaml:
    get:
      operationId: getOpenAPISpecYAML
      x-module: core
      x-stability-level: alpha
      tags:
      - Server
      summary: Get the OpenAPI document (YAML)
      description: The bundled OpenAPI document of the running server version. Supports ETag revalidation.
      responses:
        '200':
          description: The OpenAPI document.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/yaml:
              schema:
                type: object
                description: OpenAPI 3.0 document.
        '304':
          $ref: '#/components/responses/NotModified'
components:
  headers:
    ETag:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  responses:
    InternalError:
      description: Unexpected server failure. Details are in the server log.
    NotModified:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  schemas:
    ServerInfo:
      type: object
      description: Public server description. Everything an add-server screen needs before login.
      required:
      - name
      - serverVersion
      - specVersion
      - setupRequired
      - loginMethods
      properties:
        name:
          type: string
          description: Human-readable server product name.
        serverVersion:
          type: string
          description: Version of the running server build.
        specVersion:
          type: string
          description: Version of the OpenAPI document this server implements.
        setupRequired:
          type: boolean
          description: True until the first admin user has been created.
        loginMethods:
          type: array
          description: Login methods this server accepts. New methods may be added; clients ignore values they do not recognise.
          items:
            type: string
            enum:
            - password
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived access token minted from a device grant. Not yet applied to any operation.