openapi: "3.0.3"
info:
  description: "Interactive documentation for [Funkwhale](https://funkwhale.audio) API."
  version: "2.0.0"
  title: "Funkwhale API"

servers:
  - url: "https://demo.funkwhale.audio"
    description: "Demo server"
  - url: "https://open.audio"
    description: "Real server with real content"
  - url: "https://{domain}"
    description: "Custom server"
    variables:
      domain:
        default: yourdomain
        description: "Your Funkwhale Domain"
      protocol:
        enum:
          - "http"
          - "https"
        default: "https"
tags:
  - name: Collections
  - name: History
  - name: Instance
  - name: Recordings
  - name: Releases
  - name: Tags
paths:
  /api/v2/collections:
    get:
      tags:
        - Collections
      summary: "Retrieve a list of collections from the server"
      description: "Retrieve a list of collections stored on the server"
      operationId: getCollections
      parameters:
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "specs/collections/schema.yml#/Collection"
    post:
      tags:
        - Collections
      summary: "Add a new collection"
      description: "Add a new collection to the server"
      operationId: postCollection
      requestBody:
        description: "The new metadata of the collection"
        required: true
        content:
          application/json:
            schema:
              $ref: "specs/collections/schema.yml#/NewCollection"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "specs/collections/schema.yml#/SimpleCollection"
  /api/v2/collections/{guid}:
    get:
      tags:
        - Collections
      summary: "Retrieve a collection by GUID"
      description: "Retrieve a collection by specifying its GUID"
      operationId: getCollection
      parameters:
        - name: guid
          in: path
          required: true
          description: The GUID of the collection
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "specs/collections/schema.yml#/Collection"
    patch:
      tags:
        - Collections
      summary: "Update the metadata of a collection"
      description: "Change metadata and details about a specific collection"
      operationId: patchCollection
      parameters:
        - name: guid
          in: path
          required: true
          description: The GUID of the collection
          schema:
            type: string
            format: uuid
      requestBody:
        description: "The new metadata of the collection"
        required: true
        content:
          application/json:
            schema:
              $ref: "specs/collections/schema.yml#/UpdateCollection"
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "specs/collections/schema.yml#/SimpleCollection"
    delete:
      tags:
        - Collections
      summary: "Delete a specific collection"
      description: "Delete a collection. This does not delete the associated uploads."
      operationId: deleteCollection
      parameters:
        - name: guid
          in: path
          required: true
          description: The GUID of the collection
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Successful operation
  /api/v2/instance/nodeinfo/2.1:
    get:
      tags:
        - Instance
      summary: "Retrieve nodeinfo data"
      description: "Retrieve details about a Funkwhale server using the Nodeinfo standard"
      operationId: getNodeinfo
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "./specs/nodeinfo21/schema.yml#/Nodeinfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/recordings:
    get:
      tags:
        - Recordings
      summary: "Retrieve a list of recordings"
      description: "Retrieve a list of recordings uploaded to the server"
      operationId: getRecordings
      parameters:
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
        - $ref: "specs/quality-filter/schema.yml#/FormatFilter"
        - $ref: "specs/quality-filter/schema.yml#/TagsFilter"
        - $ref: "specs/quality-filter/schema.yml#/MBIDFilter"
        - $ref: "specs/quality-filter/schema.yml#/QualityFilter"
        - name: release
          in: query
          required: false
          description: Filter recordings by their associated release
          schema:
            type: string
        - name: artist
          in: query
          required: false
          description: Filter recordings by their associated artist
          schema:
            type: string
        - name: id
          in: query
          required: false
          description: Filter recordings by ID
          schema:
            type: array
            items:
              type: string
        - name: collection
          in: query
          required: false
          description: Filter recordings by collection ID
          schema:
            type: string
            format: uuid
        - name: mbid
          in: query
          required: false
          description: Filter recordings by MusicBrainz ID
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/Recording"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/releases:
    get:
      tags:
        - Releases
      summary: Retrieve information about releases on the server
      description: Retrieve a list of releases on the pod
      operationId: getReleases
      parameters:
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
        - $ref: "specs/quality-filter/schema.yml#/FormatFilter"
        - $ref: "specs/quality-filter/schema.yml#/TagsFilter"
        - $ref: "specs/quality-filter/schema.yml#/MBIDFilter"
        - $ref: "specs/quality-filter/schema.yml#/QualityFilter"
        - name: artist
          in: query
          required: false
          description: Filter releases by artist
          schema:
            type: integer
        - name: collection
          in: query
          required: false
          description: Filter releases by collection ID
          schema:
            type: string
            format: uuid
        - name: mbid
          in: query
          required: false
          description: Filter recordings by MusicBrainz ID
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/Release"
    post:
      tags:
        - Releases
      summary: Add a new release to the server
      description: Add a new release object to the server
      operationId: postRelease
      requestBody:
        description: The release information you want to upload
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRelease"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleRelease"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/release-groups:
    get:
      tags:
        - Releases
      summary: "Retrieve a list of release groups"
      description: "Retrieve a list of all release groups on the server"
      operationId: getReleaseGroups
      parameters:
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
        - name: primary_type
          in: query
          required: false
          description: "Filter results by their primary type"
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ReleaseTypeEnum"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/ReleaseGroup"
  /api/v2/tags/podcasts:
    get:
      tags:
        - Tags
      summary: Retrieve podcast categories
      description: Retrieve a list of podcast categories and the number of uploads tagged with those categories
      operationId: getTagsPodcasts
      parameters:
        - $ref: "#/components/parameters/query"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
        - name: ordering
          in: query
          required: false
          description: |
            The order in which results are presented. Preface with `-` to return items in descending order.
          schema:
            type: string
            enum:
              - "name"
              - "creation_date"
              - "tagged_items"
              - "-name"
              - "-creation_date"
              - "-tagged_items"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/Category"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/tags/podcasts/{category}:
    get:
      tags:
        - Tags
      summary: Retrieve podcasts by category
      description: Retrieve all podcasts in a category
      operationId: getTagPodcasts
      parameters:
        - name: category
          in: path
          required: true
          description: The category you want to return information about
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/tags/music:
    get:
      tags:
        - Tags
      summary: Retrieve music genres
      description: Retrieve a list of music genres and the number of uploads tagged with those categories
      operationId: getTagsMusic
      parameters:
        - name: q
          in: query
          required: false
          description: A free text field to filter genre names
          schema:
            type: string
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
        - name: ordering
          in: query
          required: false
          description: |
            The order in which results are presented. Preface with `-` to return items in descending order.
          schema:
            type: string
            enum:
              - "name"
              - "creation_date"
              - "tagged_items"
              - "-name"
              - "-creation_date"
              - "-tagged_items"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/Genre"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/tags/music/{genre}:
    get:
      tags:
        - Tags
      summary: Retrieve music by genre
      description: Retrieve all podcasts in a genre
      operationId: getTagMusic
      parameters:
        - name: genre
          in: path
          required: true
          description: The genre you want to return information about
          schema:
            type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Genre"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v2/history/listenings:
    get:
      tags:
        - History
      summary: Fetch a list of listenings
      description: Fetch a list of listenings from public and followed users
      operationId: getHistory
      parameters:
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/pageSizeParam"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Pagination"
                  - type: object
                    required:
                      - results
                    properties:
                      results:
                        type: array
                        items:
                          $ref: "#/components/schemas/Listening"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            code:
              value: 401
            message:
              value: User not authorized
  parameters:
    pageParam:
      name: page
      in: query
      required: false
      description: The number of the result page you want to return
      schema:
        type: number
    pageSizeParam:
      name: page_size
      in: query
      required: false
      description: The number of results to return on each page. Defaults to 50.
      schema:
        type: number
        default: 50
    query:
      name: q
      in: query
      required: false
      description: A free text field to filter results
      schema:
        type: string
  schemas:
    Actor:
      allOf:
        - $ref: "#/components/schemas/SimpleActor"
        - type: object
          properties:
            lastFetchDate:
              type: string
              format: date-time
            manuallyApprovesFollowers:
              type: boolean
            type:
              type: string
              enum:
                - person
                - tombstone
                - application
                - group
                - organization
                - service
    Artist:
      allOf:
        - $ref: "specs/multi-artist/schema.yml#/SimpleArtist"
        - type: object
          properties:
            creationDate:
              type: string
              format: date-time
            recordingCount:
              type: integer
            tags:
              type: array
              items:
                type: string
            releases:
              type: array
              items:
                $ref: "#/components/schemas/SimpleRelease"
    ArtistCredit:
      type: object
      required:
        - name
        - id
      properties:
        name:
          type: string
        id:
          type: integer
        joinPhrase:
          type: string
    Category:
      type: object
      required:
        - name
        - createdDate
        - resultsPage
      properties:
        name:
          type: string
        createdDate:
          type: string
          format: date-time
        taggedItems:
          type: number
        resultsPage:
          type: string
          format: url
    CoverUrls:
      type: object
      required:
        - uuid
        - mimetype
        - size
        - creationDate
        - urls
      properties:
        uuid:
          type: string
          format: uuid
        mimetype:
          type: string
        size:
          type: integer
        creationDate:
          type: string
          format: date-time
        urls:
          type: object
          required:
            - original
          properties:
            source:
              type: string
              format: url
            original:
              type: string
              format: url
    CreateRelease:
      type: object
      required:
        - title
        - artist
      properties:
        title:
          type: string
        releaseDate:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
        type:
          $ref: "#/components/schemas/ReleaseTypeEnum"
        description:
          type: object
          required:
            - text
            - contentType
          properties:
            text:
              type: string
              description: A description of the release
            contentType:
              type: string
              enum:
                - "text/html"
                - "text/markdown"
                - "text/plain"
            html:
              type: string
        artist:
          type: string
          description: The name of the associated artist
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    Genre:
      type: object
      properties:
        genre:
          type: string
        created_date:
          type: string
          format: date-time
        tagged_items:
          type: number
        results_page:
          type: string
          format: url
    Listening:
      type: object
      required:
        - guid
        - createdDate
        - user
        - recording
      properties:
        guid:
          type: string
          format: uuid
          description: "The globally unique ID of the listening object"
        createdDate:
          type: string
          format: date-time
          description: "The date on which the listening was recorded"
        recording:
          $ref: "#/components/schemas/SimpleRecording"
        user:
          $ref: "#/components/schemas/SimpleUser"
    Pagination:
      type: object
      required:
        - total
      properties:
        total:
          type: integer
        next:
          type: string
          format: url
        previous:
          type: string
          format: url
    Recording:
      allOf:
        - $ref: "#/components/schemas/SimpleRecording"
        - type: object
          required:
            - creationDate
            - downloadsCount
            - attributedTo
          properties:
            creationDate:
              type: string
              format: date-time
            copyright:
              format: string
            license:
              format: string
            tags:
              format: array
              items:
                type: string
            mbid:
              type: string
              format: uuid
            downloadsCount:
              type: integer
            discNumber:
              type: integer
            position:
              type: integer
            attributedTo:
              $ref: "#/components/schemas/SimpleActor"
            collections:
              type: array
              items:
                $ref: "specs/collections/schema.yml#/SimpleCollection"
    Release:
      allOf:
        - $ref: "#/components/schemas/SimpleRelease"
        - type: object
          required:
            - artistCredit
            - creationDate
            - recordingCount
            - duration
            - attributedTo
            - local
            - releaseGroup
            - recordings
          properties:
            artistCredit:
              $ref: "specs/multi-artist/schema.yml#/ArtistCredit"
            creationDate:
              type: string
              format: date-time
            releaseDate:
              type: string
              format: date
            recordingCount:
              type: integer
            duration:
              type: integer
            attributedTo:
              $ref: "#/components/schemas/SimpleActor"
            local:
              type: boolean
            releaseGroup:
              $ref: "#/components/schemas/SimpleReleaseGroup"
            recordings:
              type: array
              items:
                $ref: "#/components/schemas/SimpleRecording"
    ReleaseGroup:
      allOf:
        - $ref: "#/components/schemas/SimpleReleaseGroup"
        - type: object
          required:
            - guid
            - artist
            - releases
          properties:
            artistCredit:
              type: array
              items:
                $ref: "specs/multi-artist/schema.yml#/ArtistCredit"
            secondaryType:
              type: string
              enum:
                - compilation
                - soundtrack
                - spokenword
                - interview
                - audiobook
                - audio-drama
                - live
                - remix
                - dj-mix
                - mixtape
                - demo
                - field-recording
            releases:
              type: array
              items:
                $ref: "#/components/schemas/SimpleRelease"
    ReleaseTypeEnum:
      type: string
      default: album
      description: "The type of release"
      enum:
        - album
        - single
        - ep
        - broadcast
        - other
    SimpleActor:
      type: object
      required:
        - fid
        - preferredUsername
        - fullUsername
        - local
        - domain
      properties:
        fid:
          type: string
          format: url
        url:
          type: string
          format: url
        fullUsername:
          type: string
        preferredUsername:
          type: string
        name:
          type: string
        domain:
          type: string
        local:
          type: boolean
    SimpleArtist:
      type: object
      required:
        - id
        - fid
        - name
        - contentCategory
        - local
      properties:
        id:
          type: integer
        fid:
          type: string
          format: url
        mbid:
          type: string
          format: uuid
        name:
          type: string
        contentCategory:
          type: string
          enum:
            - music
            - podcast
            - other
        local:
          type: boolean
        channel:
          type: string
          format: uuid
    SimpleRecording:
      type: object
      required:
        - guid
        - fid
        - name
        - playable
        - local
        - release
        - artist
        - cover
      properties:
        guid:
          type: string
          format: uuid
        fid:
          type: string
          format: url
        name:
          type: string
        playable:
          type: boolean
        local:
          type: boolean
        release:
          $ref: "#/components/schemas/SimpleRelease"
        artistCredit:
          type: array
          items:
            $ref: "specs/multi-artist/schema.yml#/ArtistCredit"
        cover:
          $ref: "#/components/schemas/CoverUrls"
    SimpleRelease:
      type: object
      required:
        - guid
        - fid
        - name
        - local
      properties:
        guid:
          type: string
          format: uuid
        fid:
          type: string
          format: url
        mbid:
          type: string
          format: uuid
        name:
          type: string
        playable:
          type: boolean
        cover:
          $ref: "#/components/schemas/CoverUrls"
    SimpleReleaseGroup:
      type: object
      required:
        - guid
        - primaryType
      properties:
        guid:
          type: string
          format: uuid
          description: "The unique identifier of the release group"
        name:
          type: string
        primaryType:
          $ref: "#/components/schemas/ReleaseTypeEnum"
        releaseVersions:
          type: integer
          description: "The number of releases associated with this release group"
    SimpleUser:
      type: object
      required:
        - guid
        - username
        - fullUsername
        - avatar
      properties:
        guid:
          type: string
          format: uuid
        username:
          type: string
        fullUsername:
          type: string
        preferredUsername:
          type: string
        avatar:
          $ref: "#/components/schemas/CoverUrls"
  securitySchemes:
    oauth2:
      type: oauth2
      description: This API uses OAuth 2 with the Authorization Code flow. You can register an app using the /oauth/apps/ endpoint.
      flows:
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /api/v1/oauth/token/
          refreshUrl: /api/v1/oauth/token/
          scopes:
            "read": "Read-only access to all user data"
            "write": "Write-only access on all user data"
            "read:edits": "Read-only access to edits"
            "write:edits": "Write-only access to edits"
            "read:favorites": "Read-only access to favorites"
            "write:favorites": "Write-only access to favorites"
            "read:filters": "Read-only to to content filters"
            "write:filters": "Write-only access to content-filters"
            "read:follows": "Read-only to follows"
            "write:follows": "Write-only access to follows"
            "read:libraries": "Read-only access to library and uploads"
            "write:libraries": "Write-only access to libraries"
            "read:listenings": "Read-only access to listening history"
            "write:listenings": "Write-only access to listening history"
            "read:notifications": "Read-only access to notifications"
            "write:notifications": "Write-only access to notifications"
            "read:playlists": "Read-only access to playlists"
            "write:playlists": "Write-only access to playlists"
            "read:profile": "Read-only access to profile data"
            "write:profile": "Write-only access to profile data"
            "read:radios": "Read-only access to radios"
            "write:radios": "Write-only access to radios"
            "read:reports": "Read-only access to reports"
            "write:reports": "Write-only access to reports"
            "read:security": "Read-only access security settings"
            "write:security": "write-only access security settings"

security:
  - oauth2: []