openapi: "3.0.3"
info:
  description: |
    API explorer for the [Funkwhale](https://funkwhale.audio) API.

    Backward compatibility between minor versions (1.X to 1.Y) is guaranteed for all the
    endpoints documented here.

    ## Usage

    Click on an endpoint name to inspect its properties, parameters and responses.

    Use the "Try it out" button to send a real world payload to the endpoint and inspect
    the corresponding response.

    ## OAuth Authentication

    Funkwhale uses the OAuth [authorization grant flow](https://tools.ietf.org/html/rfc6749#section-4.1) for external apps. This flow is
    a secure way to authenticate apps that requires a user's explicit consent to perform actions. You can use our demo server at <https://demo.funkwhale.audio>
    for testing purposes.

    To authenticate with the Funkwhale API:

    1. Create an application by sending a `POST` request to `api/v1/oauth/apps`. Include your scopes and redirect URI (use `urn:ietf:wg:oauth:2.0:oob`
    to get an authorization code you can copy)
    2. Send an [authorization request](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2)  to the `/authorize` endpoint to receive an authorization code
    3. [Request an access token](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3) from `/api/v1/oauth/token`
    4. Use your access token to authenticate your calls with the following format: `Authorization: Bearer <token>`
    5. Refresh your access token by sending a refresh request to `/api/v1/oauth/token`

    For more detailed instructions, see [our API authentication documentation](https://docs.funkwhale.audio/developers/authentication.html).

    ## Application token authentication

    If you have an account on your target pod, you can create an application at `/settings/applications/new`. Once you authorize the application you
    can retrieve an access token. Use your access token to authenticate your calls with the following format: `Authorization: Bearer <token>`

    ## Rate limiting

    Funkwhale supports rate-limiting as of version 0.2.0. Pod admins can choose to rate limit specific endpoints to prevent abuse and improve the stability of the service.
    If the server drops a request due to rate-limiting, it returns a `429` status code.

    Each API call returns HTTP headers to pass the following information:

    - What was the scope of the request (`X-RateLimit-Scope`)
    - What is the rate-limit associated with the request scope (`X-RateLimit-Limit`)
    - How many more requests in the scope can be made within the rate-limit timeframe (`X-RateLimit-Remaining`)
    - How much time does the client need to wait to send another request (`Retry-After`)

    For more information, check our [rate limit documentation](https://docs.funkwhale.audio/admin/configuration.html#api-configuration)

    ## Resources

    For more information about API usage, refer to [our API documentation](https://docs.funkwhale.audio/api.html).

  version: "1.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"

components:
  responses:
    200:
      description: Success
    201:
      description: Successfully created
    204:
      description: Successfully deleted
    400:
      description: Bad request
  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 favorits"
            "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"
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "You can get a token by using the /token endpoint"

security:
  - jwt: []
  - oauth2: []

tags:
  - name: Auth and security
    description: Login, logout, rate-limit and authorization endpoints
  - name: Library and metadata
    description: Information and metadata about musical and audio entities (albums, tracks, artists, etc.)
  - name: Uploads and audio content
    description: Manipulation and uploading of audio files
    externalDocs:
      url: https://docs.funkwhale.audio/users/managing.html
  - name: Channels and subscriptions
    description: Channel management and subscription
    externalDocs:
      url: https://docs.funkwhale.audio/users/upload.html#using-a-channel
  - name: Content curation
    description: Favorites, playlists, radios
  - name: User activity
    description: Listenings
  - name: Other
    description: Other endpoints that don't fit in the categories above

paths:
  /api/v1/oauth/apps/:
    post:
      tags:
        - "Auth and security"
      summary: Register an OAuth application
      security: []
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/OAuthApplication"
                  - $ref: "./api/definitions.yml#/OAuthApplicationCreation"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                name:
                  type: "string"
                  example: "My Awesome Funkwhale Client"
                  description: "A human readable name for your app"
                redirect_uris:
                  type: "string"
                  example: "https://myapp/oauth2/funkwhale"
                  description: "A list of redirect uris, separated by spaces"
                scopes:
                  type: "string"
                  description: "A list of scopes requested by your app, separated by spaces"
                  example: "read write:playlists write:favorites"
  /api/v1/oauth/token/:
    post:
      tags:
        - "Auth and security"
      summary: Request an OAuth bearer token in exchange of an authorization_code or a refresh_token
      security: []
      responses:
        200:
          $ref: "#/components/responses/200"

  /api/v1/auth/registration/:
    post:
      summary: Create an account
      description: |
        Register a new account on this instance. An invitation code will be required
        if sign up is disabled.
      tags:
        - "Auth and security"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              required:
                - username
                - email
                - password1
                - password2
              properties:
                username:
                  type: "string"
                  example: "alice"
                email:
                  type: "string"
                  format: "email"
                invitation:
                  type: "string"
                  example: "INVITECODE"
                  description: An invitation code, required if signups are closed on the instance.
                password1:
                  type: "string"
                  example: "passw0rd"
                password2:
                  type: "string"
                  description: Must be identical to password1
                  example: "passw0rd"
      responses:
        201:
          $ref: "#/components/responses/201"
  /api/v1/auth/password/reset/:
    post:
      summary: Request a password reset
      description: |
        Request a password reset. An e-mail with reset instructions will be sent to the provided e-mail address,
        if it's associated with a user account.
      tags:
        - "Auth and security"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                email:
                  type: "string"
                  format: "email"
      responses:
        200:
          $ref: "#/components/responses/200"
  /api/v1/users/me/:
    get:
      summary: Retrive profile information
      description: |
        Retrieve profile informations of the current user
      tags:
        - "Auth and security"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Me"
    delete:
      summary: Delete the user account performing the request
      tags:
        - "Auth and security"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                confirm:
                  type: "boolean"
                  description: "Must be set to true, to avoid accidental deletion"
                password:
                  type: "string"
                  description: "The current password of the account"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Me"
  /api/v1/users/users/change-email/:
    post:
      summary: Update the e-mail address associated with a user account
      tags:
        - "Auth and security"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                email:
                  type: "string"
                  format: "email"
                password:
                  type: "string"
                  description: "The current password of the account"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Me"

  /api/v1/rate-limit/:
    get:
      summary: Retrive rate-limit information and current usage status
      tags:
        - "Auth and security"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/RateLimitStatus"

  /api/v1/artists/:
    get:
      summary: List artists
      tags:
        - "Library and metadata"
      security:
        - oauth2:
            - "read:libraries"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/ArtistOrdering"
        - $ref: "./api/parameters.yml#/Playable"
        - $ref: "./api/parameters.yml#/HasAlbums"
        - $ref: "./api/parameters.yml#/Library"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Related"
        - $ref: "./api/parameters.yml#/Scope"
        - $ref: "./api/parameters.yml#/ContentCategory"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Artist"
  /api/v1/artists/{id}/:
    get:
      summary: Retrieve a single artist
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/Refresh"
      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Artist"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"
  /api/v1/artists/{id}/libraries/:
    get:
      summary: List available user libraries containing work from this artist
      security:
        - oauth2:
            - "read:libraries"
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"

      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/albums/:
    get:
      summary: List albums
      tags:
        - "Library and metadata"

      security:
        - oauth2:
            - "read:libraries"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - name: "artist"
          in: "query"
          required: false
          description: "Only include albums by the requested artist"
          schema:
            nullable: true
            type: "integer"
            format: "int64"
        - $ref: "./api/parameters.yml#/AlbumOrdering"
        - $ref: "./api/parameters.yml#/Library"
        - $ref: "./api/parameters.yml#/Playable"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Related"
        - $ref: "./api/parameters.yml#/Scope"
        - $ref: "./api/parameters.yml#/ContentCategory"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Album"
  /api/v1/albums/{id}/:
    get:
      summary: Retrieve a single album
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/Refresh"

      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Album"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/albums/{id}/libraries/:
    get:
      summary: List available user libraries containing tracks from this album
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"

      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/tracks/:
    get:
      summary: List tracks
      tags:
        - "Library and metadata"

      security:
        - oauth2:
            - "read:libraries"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - name: "artist"
          in: "query"
          required: false
          description: "Only include tracks by the requested artist"
          schema:
            nullable: true
            type: "integer"
            format: "int64"
        - name: "favorites"
          in: "query"
          required: false
          description: "filter/exclude tracks favorited by the current user"
          schema:
            nullable: true
            type: "boolean"
        - name: "album"
          in: "query"
          required: false
          description: "Only include tracks from the requested album"
          schema:
            nullable: true
            type: "integer"
            format: "int64"
        - name: "license"
          in: "query"
          description: "Only include tracks with the given license"
          required: false
          schema:
            example: "cc-by-sa-4.0"
            nullable: true
            type: "string"
        - $ref: "./api/parameters.yml#/TrackOrdering"
        - $ref: "./api/parameters.yml#/Library"
        - $ref: "./api/parameters.yml#/Playable"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Related"
        - $ref: "./api/parameters.yml#/Scope"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Track"
  /api/v1/tracks/{id}/:
    get:
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/Refresh"
      summary: Retrieve a single track

      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Track"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/tracks/{id}/libraries/:
    get:
      summary: List available user libraries containing given track
      parameters:
        - $ref: "./api/parameters.yml#/ObjectId"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"
  /api/v1/listen/{uuid}/:
    get:
      summary: Download the audio file matching the given track uuid
      description: |
        Given a track uuid (and not ID), return the first found audio file
        accessible by the user making the request.

        In case of a remote upload, this endpoint will fetch the audio file from the remote
        and cache it before sending the response.

      parameters:
        - name: uuid
          in: path
          required: true
          description: Track uuid
          schema:
            type: "string"
            format: "uuid"
        - name: to
          in: query
          required: false
          description: |
            If specified, the endpoint will return a transcoded version of the original
            audio file.

            Since transcoding happens on the fly, it can significantly increase response time,
            and it's recommended to request transcoding only for files that are not playable
            by the client.

            This endpoint support bytess-range requests.
          schema:
            $ref: "./api/properties.yml#/transcode_options"
        - name: upload
          in: query
          required: false
          description: |
            An upload uuid

            If specified, will return the audio for the given upload uuid.

            This is useful for tracks that have multiple uploads available.

          schema:
            type: string
            format: uuid
        - name: token
          in: query
          required: false
          description: |
            A listen token as returned by /users/me

            This offers an alternative authentication method for situations where HTTP headers
            can't be modified to include a Bearer token.
          schema:
            type: string

      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            "*/*":
              schema:
                description: "Audio file, as binary data"
                type: string
                format: binary
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/licenses/:
    get:
      summary: List licenses
      security:
        - oauth2:
            - "read:libraries"
      tags:
        - "Library and metadata"
      parameters:
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/License"

  /api/v1/licenses/{code}/:
    get:
      summary: Retrieve a single license
      security:
        - oauth2:
            - "read:libraries"
      parameters:
        - name: code
          in: path
          description: License code
          required: true
          schema:
            type: string
            example: cc0-1.0

      tags:
        - "Library and metadata"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/License"
        404:
          description: "Not Found"
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ResourceNotFound"

  /api/v1/libraries/:
    get:
      summary: List owned libraries
      tags:
        - "Uploads and audio content"
      parameters:
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/Scope"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/OwnedLibrary"
    post:
      tags:
        - "Uploads and audio content"
      description: Create a new library
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/OwnedLibraryCreate"

  /api/v1/libraries/{uuid}/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve a library
      tags:
        - "Uploads and audio content"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/OwnedLibrary"
    post:
      summary: Update a library
      tags:
        - "Uploads and audio content"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/OwnedLibraryCreate"
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/OwnedLibrary"
    delete:
      summary: Delete a library and all associated uploads
      description: |
        This will delete the library, all associated uploads, follows, and broadcast
        the event on the federation.
      tags:
        - "Uploads and audio content"
      responses:
        204:
          $ref: "#/components/responses/204"

  /api/v1/channels/:
    get:
      summary: List channels
      tags:
        - "Channels and subscriptions"
      parameters:
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Scope"
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/Tags"
        - $ref: "./api/parameters.yml#/Subscribed"
        - $ref: "./api/parameters.yml#/External"
        - $ref: "./api/parameters.yml#/ChannelOrdering"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Channel"
    post:
      summary: Create a new channel
      tags:
        - "Channels and subscriptions"
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/ChannelCreate"

  /api/v1/channels/metadata-choices:
    summary: List metadata (locales, itunes categories) for creating and editing channels.
    description: "Channels and subscriptions"
    get:
      summary: List channels metadata options
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  language:
                    type: "array"
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                          description: ID of the locale in ISO 639 format
                          example: "en"
                        language:
                          type: string
                          example: "English"
                  itunes_category:
                    type: "array"
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                          description: ID of the category
                          example: "Business"
                        label:
                          type: string
                          description: Readable label of the category
                          example: "Business"
                        children:
                          type: array
                          description: Some categories have subcategories
                          items:
                            type: string
                            example: "Entrepreneurship"

  /api/v1/channels/{uuid}/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve a channel
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Channel"
    post:
      summary: Update a channel
      tags:
        - "Channels and subscriptions"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/ChannelUpdate"
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Channel"
    delete:
      summary: Delete a channel and all associated uploads
      description: |
        This will delete the channel, all associated uploads, follows, and broadcast
        the event on the federation.
      tags:
        - "Channels and subscriptions"
      responses:
        204:
          $ref: "#/components/responses/204"

  /api/v1/channels/rss-suscribe/:
    post:
      summary: Subscribe to a third-party podcast via its RSS feed

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                url:
                  type: "string"
                  description: URL of the RSS feed

      tags:
        - "Channels and subscriptions"
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Subscription"

  /api/v1/channels/{uuid}/rss/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Get the RSS feed of a podcast channel. Only available for channel hosted on the pod where the API is queried.
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/rss+xml: {}

  /api/v1/channels/{uuid}/subscribe/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    post:
      summary: Subscribe to the given channel
      tags:
        - "Channels and subscriptions"
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Subscription"

  /api/v1/channels/{uuid}/unsubscribe/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    post:
      summary: Unsubscribe from the given channel
      tags:
        - "Channels and subscriptions"
      responses:
        204:
          $ref: "#/components/responses/204"

  /api/v1/uploads/:
    get:
      summary: List owned uploads
      tags:
        - "Uploads and audio content"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Scope"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/OwnedUpload"
    post:
      tags:
        - "Uploads and audio content"
      description:
        Upload a new file in a library. The event will be broadcasted on federation,
        according to the library visibility and followers.
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - library
                - import_reference
                - source
                - audio_file
                - import_status
              properties:
                library:
                  type: string
                  format: uuid
                  description: "The library in which the audio should be stored"
                import_reference:
                  type: string
                  example: "Import launched via API client on 04/19"
                source:
                  type: string
                  example: "upload://filename.mp3"
                audio_file:
                  type: string
                  format: binary
                import_status:
                  type: string
                  description: "Setting import_status to draft will prevent processing, but allow further modifications to audio and metadata. Once ready, use the PATCH method to set import_status to pending. Default to `pending` if unspecified."
                  default: "pending"
                  enum:
                    - "draft"
                    - "pending"
                import_metadata:
                  $ref: "./api/definitions.yml#/ImportMetadata"

  /api/v1/subscriptions/{uuid}/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve a subscription
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Subscription"

  /api/v1/subscriptions/:
    get:
      summary: List subscriptions
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Subscription"

  /api/v1/subscriptions/all/:
    get:
      summary: Retrieve all subscriptions in a lightweight format, without pagination
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  results:
                    type: "array"
                    items:
                      $ref: "./api/definitions.yml#/SubscriptionsAll"

  /api/v1/uploads/{uuid}/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve an upload
      tags:
        - "Uploads and audio content"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/OwnedUpload"
    patch:
      summary: Update a draft upload
      description: |
        This will update a draft upload, before it is processed.

        All fields supported for `POST /api/v1/uploads` can be updated here.

        Setting `import_status` to `pending` will trigger processing, and make future
        modifications impossible.

      tags:
        - "Uploads and audio content"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/OwnedUpload"
    delete:
      summary: Delete an upload
      description: |
        This will delete the upload from the server and broadcast the event
        on the federation.
      tags:
        - "Uploads and audio content"
      responses:
        204:
          $ref: "#/components/responses/204"

  /api/v1/uploads/{uuid}/audio-file-metadata:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve the tags embedded in the audio file
      tags:
        - "Uploads and audio content"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: "object"
                properties: {}

  /api/v1/favorites/tracks/:
    get:
      tags:
        - "Content curation"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Scope"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/TrackFavorite"
    post:
      summary: Mark the given track as favorite
      tags:
        - "Content curation"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                track:
                  type: "integer"
                  format: "int64"
                  example: 98
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                type: "object"
                properties:
                  id:
                    type: "integer"
                    format: "int64"
                    example: 876
                  track:
                    type: "integer"
                    format: "int64"
                    example: 98
                  creation_date:
                    $ref: "./api/properties.yml#/creation_date"
  /api/v1/favorites/tracks/remove/:
    post:
      summary: Remove the given track from favorites
      tags:
        - "Content curation"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                track:
                  type: "integer"
                  format: "int64"
                  example: 98
      responses:
        204:
          $ref: "#/components/responses/204"

  #################
  # User activity #
  #################

  /api/v1/history/listenings:
    get:
      tags:
        - "User activity"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
        - $ref: "./api/parameters.yml#/Scope"

      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Listening"
    post:
      summary: Record a track in your history
      tags:
        - "User activity"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
              properties:
                track:
                  type: "integer"
                  format: "int64"
                  example: 98
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/ListeningCreate"

  ##########
  # Others #
  ##########

  /api/v1/search:
    get:
      tags:
        - "Other"
      description: Search artists, tracks, albums and other resources
      parameters:
        - $ref: "./api/parameters.yml#/Search"
      responses:
        200:
          $ref: "#/components/responses/200"
        400:
          $ref: "#/components/responses/400"

  /api/v1/instance/settings:
    get:
      tags:
        - "Other"
      description: Retrieve pod-level configuration such as description or max playlist size
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                type: "array"
                description: "List of settings with their id, label and values"
                items:
                  type: object
                  properties:
                    name:
                      type: "string"
                      description: "Name of the setting"
                      example: "max_channels"
                    section:
                      type: "string"
                      description: "Group of the setting"
                      example: "audio"
                    identifier:
                      type: "string"
                      description: "Unique identifier of the setting"
                      example: "audio__max_channels"
                    default:
                      description: Default value of the setting
                    value:
                      description: Current value of the setting
                    verbose_name:
                      type: "string"
                      description: Human-readable label of the setting
                    help_text:
                      type: "string"
                      description: Human-readable description of the setting
                    field:
                      type: "object"
                      properties:
                        input_type:
                          type: string
                          description: "Input type of the setting"

  /api/v1/attachments/:
    post:
      tags:
        - "Other"
      description: Upload a new file as an attachment that can be later associated with other objects.
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary

  /api/v1/attachments/{uuid}/:
    parameters:
      - name: uuid
        in: path
        required: true
        schema:
          type: "string"
          format: "uuid"
    get:
      summary: Retrieve an attachment
      tags:
        - "Other"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Attachment"
    delete:
      summary: Delete an attachment
      tags:
        - "Other"
      responses:
        204:
          $ref: "#/components/responses/204"

  /api/v1/playlists/:
    get:
      summary: List playlists
      tags:
        - "Content curation"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - $ref: "./api/parameters.yml#/PlaylistOrdering"
        - in: query
          name: artist
          description: Restrict to playlists containing tracks from the given artist
          schema:
            type: "integer"
            format: "int64"
        - in: query
          name: album
          description: Restrict to playlists containing tracks from the given album
          schema:
            type: "integer"
            format: "int64"
        - in: query
          name: track
          description: Restrict to playlists containing the given track
          schema:
            type: "integer"
            format: "int64"
        - $ref: "./api/parameters.yml#/Playable"
        - $ref: "./api/parameters.yml#/PageNumber"
        - $ref: "./api/parameters.yml#/PageSize"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/Playlist"
    post:
      tags:
        - "Content curation"
      description: Create a new playlist
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/PlaylistCreate"
  /api/v1/playlists/{id}/:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    get:
      summary: Retrieve a playlist
      tags:
        - "Content curation"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Playlist"
    post:
      summary: Update a playlist
      tags:
        - "Content curation"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/PlaylistCreate"
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Playlist"
    delete:
      description: Delete the playlist
      tags:
        - "Content curation"
      responses:
        204:
          $ref: "#/components/responses/204"
  /api/v1/playlists/{id}/tracks:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    get:
      description: Retrieve all tracks in the playlist
      tags:
        - "Content curation"
      responses:
        200:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/PlaylistTrack"
  /api/v1/playlists/{id}/add:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    post:
      tags:
        - "Content curation"
      summary: Append one or more tracks to a playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tracks:
                  type: array
                  description: An array of track IDs
                  items:
                    type: "integer"
                    format: "int64"
                    example: 13
                allow_duplicates:
                  type: boolean
                  default: false
                  description: |
                    Wether to raise an error when the same track is added
                    multiple time in the playlist
      responses:
        201:
          description: ""
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "./api/definitions.yml#/ResultPage"
                  - type: "object"
                    properties:
                      results:
                        type: "array"
                        items:
                          $ref: "./api/definitions.yml#/PlaylistTrack"
  /api/v1/playlists/{id}/move:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    post:
      tags:
        - "Content curation"
      summary: Move a track to another index within its playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: "integer"
                  format: "int64"
                  description: Current index of the track
                to:
                  type: "integer"
                  format: "int64"
                  description: New index of the track

      responses:
        204:
          $ref: "#/components/responses/204"
  /api/v1/playlists/{id}/remove:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    post:
      tags:
        - "Content curation"
      summary: Remove a track from its playlist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                index:
                  type: "integer"
                  format: "int64"
                  description: Index of the track to remove

      responses:
        204:
          $ref: "#/components/responses/204"
  /api/v1/playlists/{id}/clear:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: "integer"
          format: "int64"
    delete:
      description: Remove all tracks in the playlist
      tags:
        - "Content curation"
      responses:
        204:
          $ref: "#/components/responses/204"
  /api/v1/radios/sessions:
    post:
      tags:
        - "Content curation"
      description: Start a new radio session
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/RadioSessionCreate"
  /api/v1/radios/tracks:
    post:
      tags:
        - "Content curation"
      description: Get a new track for a radio session
      responses:
        201:
          $ref: "#/components/responses/201"
        400:
          $ref: "#/components/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/Track"