openapi: "3.1.0"
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: getCollection
      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: "#/components/schemas/Collection"
  /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: "#/components/schemas/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"
        - 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"
        - name: artist
          in: query
          required: false
          description: Filter releases by artist
          schema:
            type: integer
        - name: id
          in: query
          required: false
          description: Filter releases by ID
          schema:
            type: array
            items:
              type: string
        - 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:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SimpleRelease"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /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: "#/components/schemas/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"
    Category:
      type: object
      properties:
        category:
          type: string
        created_date:
          type: string
          format: date-time
        tagged_items:
          type: number
        results_page:
          type: string
          format: url
    Collection:
      allOf:
        - $ref: "#/components/schemas/SimpleCollection"
        - type: object
          properties:
            items:
              type: integer
    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
        createdDate:
          type: string
          format: date-time
        recording:
          $ref: "#/components/schemas/SimpleRecording"
        user:
          $ref: "#/components/schemas/SimpleUser"
    Nodeinfo:
      type: object
      required:
        - version
        - software
        - protocols
        - services
        - openRegistrations
        - usage
        - metadata
      properties:
        version:
          type: string
          enum:
            - "2.1"
        software:
          type: object
          required:
            - name
            - version
          properties:
            name:
              type: string
              enum:
                - "Funkwhale"
            version:
              type: string
              examples:
                - "1.4.0"
            repository:
              type: string
              format: url
              enum:
                - "https://dev.funkwhale.audio/funkwhale/funkwhale"
            homepage:
              type: string
              format: url
              enum:
                - "https://funkwhale.audio"
        protocols:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - "activitypub"
              - "buddycloud"
              - "dfrn"
              - "diaspora"
              - "libertree"
              - "ostatus"
              - "pumpio"
              - "tent"
              - "xmpp"
              - "zot"
          examples:
            - "activitypub"
        services:
          type: object
          required:
            - inbound
            - outbound
          properties:
            inbound:
              type: array
              items:
                type: string
                enum:
                  - "atom1.0"
                  - "gnusocial"
                  - "imap"
                  - "pnut"
                  - "pop3"
                  - "pumpio"
                  - "rss2.0"
                  - "twitter"
            outbound:
              type: array
              items:
                type: string
                enum:
                  - "atom1.0"
                  - "blogger"
                  - "buddycloud"
                  - "diaspora"
                  - "dreamwidth"
                  - "drupal"
                  - "facebook"
                  - "friendica"
                  - "gnusocial"
                  - "google"
                  - "insanejournal"
                  - "libertree"
                  - "linkedin"
                  - "livejournal"
                  - "mediagoblin"
                  - "myspace"
                  - "pinterest"
                  - "pnut"
                  - "posterous"
                  - "pumpio"
                  - "redmatrix"
                  - "rss2.0"
                  - "smtp"
                  - "tent"
                  - "tumblr"
                  - "twitter"
                  - "wordpress"
                  - "xmpp"
        openRegistrations:
          type: boolean
        usage:
          type: object
          required:
            - users
          properties:
            users:
              type: object
              properties:
                total:
                  type: integer
                  minimum: 0
                activeHalfYear:
                  type: integer
                  minimum: 0
                activeMonth:
                  type: integer
                  minimum: 0
            localPosts:
              type: integer
              minimum: 0
            localComments:
              type: integer
              minimum: 0
        metadata:
          type: object
          properties:
            actorId:
              type: string
              format: url
            private:
              type: boolean
            shortDescription:
              type: string
            longDescription:
              type: string
            contactEmail:
              type: string
              format: email
            nodeName:
              type: string
            banner:
              type: string
              format: url
              nullable: true
            defaultUploadQuota:
              type: integer
            supportedUploadExtensions:
              type: array
              items:
                type: string
            allowList:
              type: object
              properties:
                enabled:
                  type: boolean
                domains:
                  type: array
                  nullable: true
                  items:
                    type: string
            funkwhaleSupportMessageEnabled:
              type: boolean
            instanceSupportMessage:
              type: string
            languages:
              type: array
              items:
                type: string
            location:
              type: string
            content:
              type: object
              properties:
                local:
                  type: object
                  properties:
                    artists:
                      type: number
                    releases:
                      type: number
                    recordings:
                      type: number
                    hoursOfContent:
                      type: number
                  examples:
                    - artists: 1000
                      releases: 10000
                      recordings: 150000
                      hoursOfContent: 7500
                topMusicCategories:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                        minimum: 0
                  example:
                    - name: "rock"
                      count: 1256
                    - name: "jazz"
                      count: 604
                    - name: "classical"
                      count: 308
                topPodcastCategories:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      count:
                        type: integer
                        minimum: 0
                  example:
                    - name: "comedy"
                      count: 12
                    - name: "politics"
                      count: 4
                    - name: "nature"
                      count: 1
                federation:
                  type: object
                  properties:
                    followedInstances:
                      type: integer
                    followingInstances:
                      type: integer
            usage:
              type: object
              properties:
                listenings:
                  type: integer
                  minimum: 0
                downloads:
                  type: integer
                  minimum: 0
                favorites:
                  type: object
                  properties:
                    tracks:
                      type: integer
                      minimum: 0
            features:
              type: array
              items:
                type: string
              examples:
                - "channels"
                - "podcasts"
                - "collections"
                - "audiobooks"
                - "federation"
                - "anonymousCanListen"
    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: "#/components/schemas/SimpleCollection"
    Release:
      allOf:
        - $ref: "#/components/schemas/SimpleRelease"
        - type: object
          properties:
            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
            recordings:
              type: array
              items:
                $ref: "#/components/schemas/SimpleRecording"
    ReleaseGroup:
      type: object
      required:
        - guid
        - artist
        - primaryType
      properties:
        guid:
          type: string
          format: uuid
        artist:
          $ref: "#/components/schemas/SimpleArtist"
        primaryType:
          $ref: "#/components/schemas/ReleaseTypeEnum"
        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
    SimpleCollection:
      type: object
      required:
        - uuid
        - name
        - local
        - owner
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        local:
          type: boolean
        owner:
          $ref: "#/components/schemas/SimpleActor"
    SimpleRecording:
      type: object
      required:
        - id
        - fid
        - name
        - playable
        - local
        - release
        - artist
        - cover
      properties:
        id:
          type: integer
        fid:
          type: string
          format: url
        name:
          type: string
        playable:
          type: boolean
        local:
          type: boolean
        release:
          $ref: "#/components/schemas/SimpleRelease"
        artist:
          $ref: "#/components/schemas/SimpleArtist"
        cover:
          $ref: "#/components/schemas/CoverUrls"
    SimpleRelease:
      type: object
      required:
        - id
        - fid
        - name
        - local
      properties:
        id:
          type: integer
        fid:
          type: string
          format: url
        mbid:
          type: string
          format: uuid
        name:
          type: string
        playable:
          type: boolean
        releaseGroup:
          type: string
          format: uuid
        cover:
          $ref: "#/components/schemas/CoverUrls"
    SimpleUser:
      type: object
      required:
        - id
        - username
        - fullUsername
        - avatar
      properties:
        id:
          type: integer
        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: []