api-spec.yml

openapi: 3.0.0
info:
  version: 0.1.0
  title: go-librespot API
  description: go-librespot daemon API

# This spec is the source of truth for the API: the request/response models and
# the HTTP routing in daemon/api_gen.go are generated from it by oapi-codegen.
# Changing a payload here and regenerating is the way to change the API.
#
# Response schemas mark every field required so the generated structs keep
# emitting them; request schemas use x-go-type-skip-optional-pointer so optional
# fields stay plain values that default to their zero value, matching how the
# daemon has always read them.

components:
  schemas:
    track:
      x-go-name: ApiTrack
      description: A track or podcast episode
      type: object
      required:
        - uri
        - name
        - artist_names
        - album_name
        - album_cover_url
        - position
        - duration
        - release_date
        - track_number
        - disc_number
        - format
        - codec
        - bitrate
        - sample_rate
        - bit_depth
      properties:
        uri:
          description: URI
          type: string
        name:
          description: Name
          type: string
        artist_names:
          description: Artists name
          type: array
          items:
            description: Artist name
            type: string
        album_name:
          description: Album name
          type: string
        album_cover_url:
          description: Album cover URL
          type: string
          nullable: true
        position:
          description: Playback position in milliseconds
          type: integer
          format: int64
        duration:
          description: Duration in milliseconds
          type: integer
        release_date:
          description: Album release date, empty for episodes
          type: string
        track_number:
          description: Track number within the disc, zero for episodes
          type: integer
        disc_number:
          description: Disc number within the album, zero for episodes
          type: integer
        format:
          description: >-
            Spotify name of the audio file being decoded, for example
            OGG_VORBIS_160
          type: string
        codec:
          description: Codec family of the audio file
          type: string
          enum:
            - vorbis
            - flac
            - mp3
            - aac
            - unknown
            - ''
        bitrate:
          description: >-
            Nominal bitrate in kbps, null for formats without a fixed one such
            as FLAC
          type: integer
          nullable: true
        sample_rate:
          description: Sample rate of the decoded audio in Hz
          type: integer
          nullable: true
        bit_depth:
          description: >-
            Bits per sample of the source audio, null for lossy formats which
            have no meaningful source bit depth
          type: integer
          nullable: true
    status:
      x-go-name: ApiStatus
      description: The player status
      type: object
      required:
        - username
        - device_id
        - device_type
        - device_name
        - play_origin
        - play_origin_device_id
        - context_uri
        - context_name
        - stopped
        - paused
        - buffering
        - volume
        - volume_steps
        - repeat_context
        - repeat_track
        - shuffle_context
        - track
      properties:
        username:
          description: Currently active account's username
          type: string
        device_id:
          description: The player device ID
          type: string
        device_type:
          description: The player device type, for example COMPUTER or SPEAKER
          type: string
        device_name:
          description: The player device name
          type: string
        play_origin:
          description: >-
            Who started the playback, "go-librespot" identifies the API as the
            play origin, everything else is Spotify own stuff, null when
            nothing has started playback yet
          type: string
          nullable: true
        play_origin_device_id:
          description: >-
            The device ID that sent the command starting the playback, null
            when the playback was started locally through this API
          type: string
          nullable: true
        context_uri:
          description: >-
            The URI of the context playback is coming from, null when there is
            no context
          type: string
          nullable: true
        context_name:
          description: >-
            The display name of the context, for example the playlist or album
            name, null when there is no context or the resolver did not provide
            a description
          type: string
          nullable: true
        stopped:
          description: Whether the player is stopped
          type: boolean
        paused:
          description: Whether the player is paused
          type: boolean
        buffering:
          description: Whether the player is buffering
          type: boolean
        volume:
          description: The player current volume from 0 to max
          type: integer
          format: uint32
          minimum: 0
        volume_steps:
          description: The player max volume value
          type: integer
          format: uint32
        repeat_context:
          description: Whether the repeat context feature is enabled
          type: boolean
        repeat_track:
          description: Whether the repeat track feature is enabled
          type: boolean
        shuffle_context:
          description: Whether the shuffle context feature is enabled
          type: boolean
        track:
          allOf:
            - $ref: '#/components/schemas/track'
          nullable: true
        next_track:
          description: >-
            The upcoming track when its metadata is cached (metadata.enabled),
            so clients can pre-warm its name and cover art before the user
            skips to it. Absent when unknown.
          allOf:
            - $ref: '#/components/schemas/track'
          nullable: true
          x-omitempty: true
    contextTrackItem:
      x-go-name: ApiContextTrackItem
      description: One entry of a context listing
      type: object
      required: [ uri, track ]
      properties:
        uri:
          description: The track URI
          type: string
        track:
          description: >-
            Full track metadata, or null while the background sweep has not
            resolved this entry yet
          allOf:
            - $ref: '#/components/schemas/track'
          nullable: true
    contextTracks:
      x-go-name: ApiContextTracks
      description: A context's track listing
      type: object
      required: [ uri, ready, length, cached, tracks ]
      properties:
        uri:
          description: The context URI
          type: string
        ready:
          description: >-
            False while the context is still being enumerated in the
            background; the listing is empty until it is true
          type: boolean
        length:
          description: Number of track entries
          type: integer
        cached:
          description: >-
            Entries with full metadata; poll again while cached < length
          type: integer
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/contextTrackItem'
    root:
      x-go-name: ApiRoot
      description: API reachability and playback readiness
      type: object
      required: [ playback_ready ]
      properties:
        playback_ready:
          description: >-
            Whether the daemon is fully bootstrapped and ready to accept
            /player/play
          type: boolean
    volume:
      x-go-name: ApiVolume
      description: The player volume settings
      type: object
      required: [ value, max ]
      properties:
        value:
          description: The current volume, ranging from 0 to max
          type: integer
          format: uint32
        max:
          description: The max volume value
          type: integer
          format: uint32
    token:
      x-go-name: ApiToken
      description: A Spotify access token for the active session
      type: object
      required: [ token ]
      properties:
        token:
          description: The access token
          type: string
    deviceAuth:
      x-go-name: ApiDeviceAuth
      description: The pairing details of an in-flight device authorization flow
      type: object
      required: [ url, code, expires_at ]
      properties:
        url:
          description: >-
            The URL the user must visit to approve the request. It usually
            embeds the code already, in which case entering it is not needed.
          type: string
        code:
          description: The code the user must enter at the URL, if prompted
          type: string
        expires_at:
          description: When the code stops being accepted
          type: string
          format: date-time
    play:
      x-go-name: ApiPlay
      description: An initiate playback payload
      type: object
      required: [ uri ]
      properties:
        uri:
          description: Spotify URI to start playing
          type: string
        skip_to_uri:
          description: Spotify URI to skip to (when playing playlists)
          type: string
          x-go-type-skip-optional-pointer: true
        paused:
          description: Start playback as paused
          type: boolean
          x-go-type-skip-optional-pointer: true
        position:
          description: >-
            Position in milliseconds to start playback at within the selected
            track (0 starts from the beginning)
          type: integer
          format: int64
          x-go-type-skip-optional-pointer: true
    next:
      x-go-name: ApiNext
      description: A skip to next payload
      type: object
      properties:
        uri:
          description: >-
            The track URI to skip to. When omitted the next track in the
            context is played.
          type: string
    seek:
      x-go-name: ApiSeek
      description: A seek payload
      type: object
      required: [ position ]
      properties:
        position:
          description: >-
            Seek position in milliseconds. Must not be negative unless relative
            is set.
          type: integer
          format: int64
        relative:
          description: Whether the seek position is relative to the current one
          type: boolean
          default: false
          x-go-type-skip-optional-pointer: true
    setVolume:
      x-go-name: ApiSetVolume
      description: A set volume payload
      type: object
      required: [ volume ]
      properties:
        volume:
          description: >-
            Volume from 0 to max. Must not be negative unless relative is set.
          type: integer
          format: int32
        relative:
          description: Whether to change the volume relative to the current volume
          type: boolean
          default: false
          x-go-type-skip-optional-pointer: true
    repeatContext:
      x-go-name: ApiRepeatContext
      description: A toggle repeating context payload
      type: object
      required: [ repeat_context ]
      properties:
        repeat_context:
          description: Whether repeating context should be enabled
          type: boolean
    repeatTrack:
      x-go-name: ApiRepeatTrack
      description: A toggle repeating track payload
      type: object
      required: [ repeat_track ]
      properties:
        repeat_track:
          description: Whether repeating track should be enabled
          type: boolean
    shuffleContext:
      x-go-name: ApiShuffleContext
      description: A toggle shuffling context payload
      type: object
      required: [ shuffle_context ]
      properties:
        shuffle_context:
          description: Whether shuffling context should be enabled
          type: boolean
    addToQueue:
      x-go-name: ApiAddToQueue
      description: An add to queue payload
      type: object
      required: [ uri ]
      properties:
        uri:
          description: The URI for the track that should be added
          type: string
    setDeviceName:
      x-go-name: ApiSetDeviceName
      description: A set device name payload
      type: object
      required: [ name ]
      properties:
        name:
          description: The new device name
          type: string
    output:
      x-go-name: ApiOutput
      description: A reopen audio output payload
      type: object
      properties:
        device:
          description: >-
            The output device name to open (backend-specific, e.g. an ALSA
            device). Empty selects the configured default.
          type: string
          x-go-type-skip-optional-pointer: true

paths:
  /:
    get:
      operationId: getRoot
      description: Returns API reachability and playback readiness
      responses:
        200:
          description: API is ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/root'
  /status:
    get:
      operationId: getStatus
      description: Returns the player status
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
        204:
          description: No active session
  /token:
    post:
      operationId: getToken
      description: Returns a Spotify access token for the active session
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token'
        204:
          description: No active session
  /auth/code:
    get:
      operationId: getAuthCode
      description: >-
        Returns the pairing URL and code of the device authorization flow the
        daemon is waiting on, so a UI can show them instead of having the user
        read the logs. Only the `device_auth` credentials type ever has one, and
        only until the user approves the request or the code expires.
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAuth'
        204:
          description: No device authorization flow is waiting for the user
  /events:
    get:
      operationId: getEvents
      description: >-
        WebSocket endpoint streaming player events as JSON objects of the form
        `{"type": "...", "data": {...}}`. This is a protocol upgrade, not a
        plain HTTP response.
      responses:
        101:
          description: Switching protocols to WebSocket
  /set_device_name:
    post:
      operationId: setDeviceName
      description: Set the player device name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setDeviceName'
      responses:
        200:
          description: Successful response
        400:
          description: The name is missing or empty
  /context/tracks:
    get:
      operationId: getContextTracks
      description: >-
        List a context's tracks in order with metadata (name, artists, cover
        art), fetched via the internal API (not the rate-limited public Web
        API). Any context the player can play is accepted — playlist, album,
        artist, show, a user's Liked Songs collection — and enumerated the
        same way. The response never waits on the network: the first call for
        an unknown context starts a background enumeration and returns
        ready=false with an empty listing. Once ready is true, entries whose
        metadata is not cached yet have a null track while a background sweep
        fills them in. Poll until ready is true and cached == length. Clients
        can render a browsable song list from this and start any entry via
        POST /player/play with the context uri and the track as skip_to_uri.

        Tracks and episodes are both listed, so shows enumerate to their
        episodes. Long contexts are truncated to metadata.max_tracks. Listings
        are reused for five minutes, so an edit made to a playlist within that
        window is not reflected. Requires metadata.enabled; responds 404
        otherwise.
      parameters:
        - name: uri
          in: query
          required: true
          description: Spotify context URI (playlist, album, artist, show, collection)
          schema:
            type: string
      responses:
        200:
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contextTracks'
        400:
          description: The uri does not name a listable context
        404:
          description: The metadata cache is disabled
  /player/play:
    post:
      operationId: playerPlay
      description: >-
        Starts playing new content. To start a context shuffled (on a random
        track), enable shuffle first via /player/shuffle_context and then call
        this. Calling /player/shuffle_context after play only shuffles the
        upcoming queue and keeps the current (first) track, so play alone (or
        shuffle after play) always begins on the context's first track.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/play'
      responses:
        200:
          description: Successful response
        400:
          description: The uri is missing or empty
  /player/resume:
    post:
      operationId: playerResume
      description: Resume playback (from paused state)
      responses:
        200:
          description: Successful response
  /player/pause:
    post:
      operationId: playerPause
      description: Pause playback (from playing state)
      responses:
        200:
          description: Successful response
  /player/playpause:
    post:
      operationId: playerPlayPause
      description: Resume playback when paused, or pause playback when playing
      responses:
        200:
          description: Successful response
  /player/stop:
    post:
      operationId: playerStop
      description: Stop playback and disconnect session
      responses:
        200:
          description: Successful response
  /player/output:
    post:
      operationId: playerOutput
      description: >-
        Reopen the audio output on a different device without touching the
        Spotify session, preserving the current track, playback position,
        paused state and volume. Useful for switching speakers (e.g. ALSA or
        bluealsa) live without reconnecting. If playback is active it switches
        devices immediately (with a brief audio gap); if nothing is playing the
        device is recorded and takes effect on the next output open. An empty
        device selects the configured default output device.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/output'
      responses:
        200:
          description: Successful response
  /player/next:
    post:
      operationId: playerNext
      description: Skip to next track
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/next'
      responses:
        200:
          description: Successful response
  /player/prev:
    post:
      operationId: playerPrev
      description: Skip to previous track (or rewind current track)
      responses:
        200:
          description: Successful response
  /player/seek:
    post:
      operationId: playerSeek
      description: Seek current track
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/seek'
      responses:
        200:
          description: Successful response
        400:
          description: The position is negative and the seek is not relative
  /player/volume:
    get:
      operationId: playerGetVolume
      description: Get player volume
      responses:
        200:
          description: Returns the player volume settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/volume'
    post:
      operationId: playerSetVolume
      description: Set player volume
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/setVolume'
      responses:
        200:
          description: Successful response
        400:
          description: The volume is negative and the change is not relative
  /player/repeat_context:
    post:
      operationId: playerRepeatContext
      description: Toggle repeating context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/repeatContext'
      responses:
        200:
          description: Successful response
  /player/repeat_track:
    post:
      operationId: playerRepeatTrack
      description: Toggle repeating track
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/repeatTrack'
      responses:
        200:
          description: Successful response
  /player/shuffle_context:
    post:
      operationId: playerShuffleContext
      description: >-
        Toggle shuffling the context. Enabling it BEFORE /player/play makes
        playback start on a random track; enabling it after play only reshuffles
        the upcoming queue and keeps the current (first) track.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shuffleContext'
      responses:
        200:
          description: Successful response
  /player/add_to_queue:
    post:
      operationId: playerAddToQueue
      description: Add a track to the queue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addToQueue'
      responses:
        200:
          description: Successful response
        400:
          description: The uri is missing or empty