openapi: 3.0.3
info:
  title: Navidrome API
  version: 1.0.0
  description: |
    Navidrome API v1. Spec-first, additive within v1. Clients discover implemented
    capability modules through `GET /capabilities` 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.

    Operations that need an access token declare `security: [{bearerAuth: []}]` and the scope they need in
    `x-scope` (OpenAPI 3.0 does not allow scopes on bearer schemes). A revoked grant, and every token minted
    from it, stops working within one access-token lifetime at most.
  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.
  - name: auth
    description: Grants, access tokens, and login methods.
paths:
  /server:
    $ref: ./paths/server.yaml
  /capabilities:
    $ref: ./paths/capabilities.yaml
  /openapi.json:
    $ref: ./paths/openapi.yaml#/json
  /openapi.yaml:
    $ref: ./paths/openapi.yaml#/yaml
  /auth/token:
    $ref: ./paths/auth.yaml#/token
  /auth/grants:
    $ref: ./paths/auth.yaml#/grants
  /auth/grants/{id}:
    $ref: ./paths/auth.yaml#/grant
  /auth/logout:
    $ref: ./paths/auth.yaml#/logout
  /auth/login:
    $ref: ./paths/auth.yaml#/login
  /auth/setup:
    $ref: ./paths/auth.yaml#/setup
  /auth/password:
    $ref: ./paths/auth.yaml#/password
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Short-lived access token from `POST /auth/token`. Opaque. The required scope is in each operation's `x-scope`."
    grantAuth:
      type: http
      scheme: bearer
      description: "Long-lived grant secret. Accepted only by `POST /auth/token`."