openapi: "3.0.3"
info:
  description: |
    Interactive documentation for [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
    --------------------
      
    You can register your own OAuth app using the `/api/v1/oauth/apps/` endpoint. Proceed to the standard OAuth flow afterwards:
      
    - Our authorize URL is at `/authorize`
    - Our token acquisition and refresh URL is at `/api/v1/oauth/token`
    - The list of supported scopes is available by clicking the `Authorize` button in the Swagger UI documentation
    - Use `urn:ietf:wg:oauth:2.0:oob` as your redirect URI if you want the user to get a copy-pastable authorization code
    - At the moment, endpoints that deal with admin or moderator-level content are not accessible via OAuth, only through the Web UI
    
    You can use our demo server at `https://demo.funkwhale.audio` for testing purposes.
        
    Application token authentication
    --------------------------------
    
    If using OAuth isn't practical and you have an account on the Funkwhale pod, you can create an application by visiting `/settings`.

    Once the application is created, you can authenticate using its access token in the `Authorization` header, like this: `Authorization: Bearer <token>`. 

    Rate limiting
    -------------

    Depending on server configuration, pods running Funkwhale 0.20 and higher may rate-limit incoming
    requests to prevent abuse and improve the stability of service. Requests that are dropped because of rate-limiting
    receive a 429 HTTP response.

    The limits themselves vary depending on:

    - The client: anonymous requests are subject to lower limits than authenticated requests
    - The operation being performed: Write and delete operations, as performed with DELETE, POST, PUT and PATCH HTTP methods are subject to lower limits

    Those conditions are used to determine the scope of the request, which in turns determine the limit that is applied.
    For instance, authenticated POST requests are bound to the `authenticated-create` scope, with a default limit of
    1000 requests/hour, but anonymous POST requests are bound to the `anonymous-create` scope, with a lower limit of 1000 requests/day.

    A full list of scopes with their corresponding description, and the current usage data for the client performing the request
    is available via the `/api/v1/rate-limit` endpoint.

    Additionally, we include HTTP headers on all API response to ensure API clients can understand:

    - what scope was bound to a given request
    - what is the corresponding limit
    - how much similar requests can be sent before being limited
    - and how much time they should wait if they have been limited

    <table>
      <caption>Rate limiting headers</caption>
      <thead>
        <th>Header</th>
        <th>Example value</th>
        <th>Description value</th>
      </thead>
      <tbody>
        <tr>
          <td><code>X-RateLimit-Limit</code></td>
          <td>50</td>
          <td>The number of allowed requests whithin a given period</td>
        </tr>
        <tr>
          <td><code>X-RateLimit-Duration</code></td>
          <td>3600</td>
          <td>The time window, in seconds, during which those requests are accounted for.</td>
        </tr>
        <tr>
          <td><code>X-RateLimit-Scope</code></td>
          <td>login</td>
          <td>The name of the scope as computed for the request</td>
        </tr>
        <tr>
          <td><code>X-RateLimit-Remaining</code></td>
          <td>42</td>
          <td>How many requests can be sent with the same scope before the limit applies</td>
        </tr>
        <tr>
          <td><code>Retry-After</code> (if <code>X-RateLimit-Remaining</code> is 0)</td>
          <td>3543</td>
          <td>How many seconds to wait before a retry</td>
        </tr>
        <tr>
          <td><code>X-RateLimit-Reset</code></td>
          <td>1568126089</td>
          <td>A timestamp indicating when <code>X-RateLimit-Remaining</code> will return to its higher possible value</td>
        </tr>
        <tr>
          <td><code>X-RateLimit-ResetSeconds</code></td>
          <td>3599</td>
          <td>How many seconds to wait before <code>X-RateLimit-Remaining</code> returns to its higher possible value</td>
        </tr>
      </tbody>
    </table>


    Resources
    ---------

    For more targeted guides regarding API usage, and especially authentication, please
    refer to [https://docs.funkwhale.audio/api.html](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:
  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:
          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"
                  summary: "A human readable name for your app"
                redirect_uris:
                  type: "string"
                  example: "https://myapp/oauth2/funkwhale"
                  summary: "A list of redirect uris, separated by spaces"
                scopes:
                  type: "string"
                  summary: "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:

  /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"
              properties:
                username:
                  type: "string"
                  example: "alice"
                email:
                  type: "string"
                  format: "email"
                invitation:
                  type: "string"
                  example: "INVITECODE"
                  required: false
                  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: "#/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: "#/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:
          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:
          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:
          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:
          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"
        - allOf:
            - $ref: "./api/parameters.yml#/Ordering"
            - default: "-creation_date"
              schema:
                required: false
                type: "string"
                example: "creation_date"
                enum:
                  - creation_date
                  - id
                  - name
                  - random
        - $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:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Artist"
        404:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          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"
          default: null
          description: "Only include albums by the requested artist"
          schema:
            required: false
            type: "integer"
            format: "int64"
        - allOf:
            - $ref: "./api/parameters.yml#/Ordering"
            - default: "-creation_date"
              schema:
                required: false
                type: "string"
                example: "creation_date"
                enum:
                  - creation_date
                  - release_date
                  - title
                  - random
        - $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:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Album"
        404:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          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"
          default: null
          description: "Only include tracks by the requested artist"
          schema:
            required: false
            type: "integer"
            format: "int64"
        - name: "favorites"
          in: "query"
          default: null
          description: "filter/exclude tracks favorited by the current user"
          schema:
            required: false
            type: "boolean"
        - name: "album"
          in: "query"
          default: null
          description: "Only include tracks from the requested album"
          schema:
            required: false
            type: "integer"
            format: "int64"
        - name: "license"
          in: "query"
          description: "Only include tracks with the given license"
          default: null
          schema:
            example: "cc-by-sa-4.0"
            required: false
            type: "string"
        - allOf:
            - $ref: "./api/parameters.yml#/Ordering"
            - default: "-creation_date"
              schema:
                required: false
                type: "string"
                example: "creation_date"
                enum:
                  - creation_date
                  - release_date
                  - title
                  - random
        - $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:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Track"
        404:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/LibraryPage"
        404:
          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
          summary: An upload uuid
          description: |
            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:
          content:
            '*/*':
              description: "Audio file, as binary data"
              schema:
                type: string
                format: binary
        404:
          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:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/License"
        404:
          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:
          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: "#/responses/201"
        400:
          $ref: "#/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:
          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:
          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: "#/responses/204"

  /api/v1/channels/:
    get:
      summary: List channels
      tags:
        - "Channels and subscriptions"
      parameters:
        - allOf:
            - $ref: "./api/parameters.yml#/Ordering"
            - default: "-creation_date"
              schema:
                required: false
                type: "string"
                example: "creation_date"
                enum:
                  - creation_date
                  - modification_date
                  - random
        - $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:
          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: "#/responses/201"
        400:
          $ref: "#/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.
    tags:
      - "Channels and subscriptions"
    get:
      summary: List channels metadata options
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          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:
          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:
          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: "#/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:
          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:
          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:
          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:

  /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:
          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: "#/responses/201"
        400:
          $ref: "#/responses/400"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              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:
                  required: false
                  $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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Subscription"

  /api/v1/subscriptions/:
    get:
      summary: List subscriptions
      tags:
        - "Channels and subscriptions"
      responses:
        200:
          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:
          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:
          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:
          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: "#/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:
          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:
          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:
          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: "#/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:
          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:
          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: "#/responses/200"
        400:
          $ref: "#/responses/400"
      
  /api/v1/instance/settings:
    get:
      tags:
        - "Other"
      description:
        Retrieve pod-level configuration such as description or max playlist size
      responses:
        200:
          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: "#/responses/201"
        400:
          $ref: "#/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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Attachment"
    delete:
      summary: Delete an attachment
      tags:
        - "Other"
      responses:
        204:
          $ref: "#/responses/204"

  /api/v1/playlists/:
    get:
      summary: List playlists
      tags:
        - "Content curation"
      parameters:
        - $ref: "./api/parameters.yml#/Search"
        - allOf:
            - $ref: "./api/parameters.yml#/Ordering"
            - default: "-creation_date"
              schema:
                required: false
                type: "string"
                example: "creation_date"
                enum:
                  - creation_date
                  - modification_date
                  - id
                  - name
        - 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:
          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: "#/responses/201"
        400:
          $ref: "#/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:
          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:
          content:
            application/json:
              schema:
                $ref: "./api/definitions.yml#/Playlist"
    delete:
      description: Delete the playlist
      tags:
        - "Content curation"
      responses:
        204:
          $ref: "#/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:
          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:
          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:
  /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:
          
  /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:
  /api/v1/radios/sessions:
    post:
      tags:
        - "Content curation"
      description: Start a new radio session
      responses:
        201:
          $ref: "#/responses/201"
        400:
          $ref: "#/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: "#/responses/201"
        400:
          $ref: "#/responses/400"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./api/definitions.yml#/Track"
responses:
  200:
    description: Success
  201:
    description: Successfully created
  204:
    description: Successfully deleted
  400:
    description: Bad request