Updated notification types in openapi reference

[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 1dc7a4321b92f093545988216e4d914e2e4959fa..9bf5024bb02610df5ea3a5a3f21e3acbcb510060 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,19 +1,17 @@
 openapi: 3.0.0
 info:
   title: PeerTube
 openapi: 3.0.0
 info:
   title: PeerTube

-  version: 2.2.0
+  version: 4.0.0

   contact:
     name: PeerTube Community
   contact:
     name: PeerTube Community

-    url: 'https://joinpeertube.org'
+    url: https://joinpeertube.org

   license:
     name: AGPLv3.0
   license:
     name: AGPLv3.0

-    url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
+    url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE

   x-logo:
   x-logo:

-    url: 'https://joinpeertube.org/img/brand.png'
+    url: https://joinpeertube.org/img/brand.png

     altText: PeerTube Project Homepage
   description: |
     altText: PeerTube Project Homepage
   description: |

-    # Introduction
-

     The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
     HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
     The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
     HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)


@@ -23,34 +21,174 @@ info:
     - [Go](https://framagit.org/framasoft/peertube/clients/go)
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 
     - [Go](https://framagit.org/framasoft/peertube/clients/go)
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 

-    See the [Quick Start guide](https://docs.joinpeertube.org/#/api-rest-getting-started) so you can play with the PeerTube API.
+    See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
+    examples of using the PeerTube API.

 
     # Authentication
 
 
     # Authentication
 

-    When you sign up for an account, you are given the possibility to generate
-    sessions, and authenticate using this session token. One session token can
-    currently be used at a time.
+    When you sign up for an account on a PeerTube instance, you are given the possibility
+    to generate sessions on it, and authenticate there using an access token. Only __one
+    access token can currently be used at a time__.
+
+    ## Roles
+
+    Accounts are given permissions based on their role. There are three roles on
+    PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.

 
     # Errors
 
     The API uses standard HTTP status codes to indicate the success or failure
 
     # Errors
 
     The API uses standard HTTP status codes to indicate the success or failure

-    of the API call. The body of the response will be JSON in the following
-    format.
+    of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
+
+    ```
+    HTTP 1.1 404 Not Found
+    Content-Type: application/problem+json; charset=utf-8
+
+    {
+      "detail": "Video not found",
+      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "status": 404,
+      "title": "Not Found",
+      "type": "about:blank"
+    }
+    ```
+
+    We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
+    but it is still optional. Types are used to disambiguate errors that bear the same status code
+    and are non-obvious:
+
+    ```
+    HTTP 1.1 403 Forbidden
+    Content-Type: application/problem+json; charset=utf-8
+
+    {
+      "detail": "Cannot get this video regarding follow constraints",
+      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "status": 403,
+      "title": "Forbidden",
+      "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+    }
+    ```
+
+    Here a 403 error could otherwise mean that the video is private or blocklisted.
+
+    ### Validation errors
+
+    Each parameter is evaluated on its own against a set of rules before the route validator
+    proceeds with potential testing involving parameter combinations. Errors coming from validation
+    errors appear earlier and benefit from a more detailed error description:

 
     ```
 
     ```

+    HTTP 1.1 400 Bad Request
+    Content-Type: application/problem+json; charset=utf-8
+

     {
     {

-      "code": "unauthorized_request", // example inner error code
-      "error": "Token is invalid." // example exposed error message
+      "detail": "Incorrect request parameters: id",
+      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
+      "invalid-params": {
+        "id": {
+          "location": "params",
+          "msg": "Invalid value",
+          "param": "id",
+          "value": "9c9de5e8-0a1e-484a-b099-e80766180"
+        }
+      },
+      "status": 400,
+      "title": "Bad Request",
+      "type": "about:blank"

     }
     ```
     }
     ```

+
+    Where `id` is the name of the field concerned by the error, within the route definition.
+    `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
+    `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
+    is about.
+
+    ### Deprecated error fields
+
+    Some fields could be included with previous versions. They are still included but their use is deprecated:
+    - `error`: superseded by `detail`
+    - `code`: superseded by `type` (which is now an URI)
+
+    # Rate limits
+
+    We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
+
+    | Endpoint (prefix: `/api/v1`) | Calls         | Time frame   |
+    |------------------------------|---------------|--------------|
+    | `/*`                         | 50            | 10 seconds   |
+    | `POST /users/token`          | 15            | 5 minutes    |
+    | `POST /users/register`       | 2<sup>*</sup> | 5 minutes    |
+    | `POST /users/ask-send-verify-email` | 3      | 5 minutes    |
+
+    Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
+    limit is announced by a `429 Too Many Requests` status code.
+
+    You can get details about the current state of your rate limit by reading the
+    following headers:
+
+    | Header                  | Description                                                |
+    |-------------------------|------------------------------------------------------------|
+    | `X-RateLimit-Limit`     | Number of max requests allowed in the current time period  |
+    | `X-RateLimit-Remaining` | Number of remaining requests in the current time period    |
+    | `X-RateLimit-Reset`     | Timestamp of end of current time period as UNIX timestamp  |
+    | `Retry-After`           | Seconds to delay after the first `429` is received         |
+
+    # CORS
+
+    This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
+    allowing cross-domain communication from the browser for some routes:
+
+    | Endpoint                    |
+    |------------------------- ---|
+    | `/api/*`                    |
+    | `/download/*`               |
+    | `/lazy-static/*`            |
+    | `/live/segments-sha256/*`   |
+    | `/.well-known/webfinger`    |
+
+    In addition, all routes serving ActivityPub are CORS-enabled for all origins.

 externalDocs:
   url: https://docs.joinpeertube.org/api-rest-reference.html
 tags:
 externalDocs:
   url: https://docs.joinpeertube.org/api-rest-reference.html
 tags:

+  - name: Register
+    description: |
+      As a visitor, you can use this API to open an account (if registrations are open on
+      that PeerTube instance). As an admin, you should use the dedicated [User creation
+      API](#operation/addUser) instead.
+  - name: Session
+    x-displayName: Login/Logout
+    description: |
+      Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.

   - name: Accounts
     description: >
   - name: Accounts
     description: >

-      Using some features of PeerTube require authentication, for which Accounts
+      Accounts encompass remote accounts discovered across the federation,
+      and correspond to the main Actor, along with video channels a user can create, which
+      are also Actors.
+
+      When a comment is posted, it is done with your Account's Actor.
+  - name: Users
+    description: >
+      Using some features of PeerTube require authentication, for which User

       provide different levels of permission as well as associated user
       provide different levels of permission as well as associated user

-      information. Accounts also encompass remote accounts discovered across the federation.
+      information. Each user has a corresponding local Account for federation.
+  - name: My User
+    description: >
+      Operations related to your own User, when logged-in.
+  - name: My Subscriptions
+    description: >
+      Operations related to your subscriptions to video channels, their
+      new videos, and how to keep up to date with their latest publications!
+  - name: My History
+    description: >
+      Operations related to your watch history.
+  - name: My Notifications
+    description: >
+      Notifications following new videos, follows or reports. They allow you
+      to keep track of the interactions and overall important information that
+      concerns you. You MAY set per-notification type delivery preference, to
+      receive the info either by mail, by in-browser notification or both.

   - name: Config
     description: >
       Each server exposes public information regarding supported videos and
   - name: Config
     description: >
       Each server exposes public information regarding supported videos and


@@ -66,12 +204,75 @@ tags:
       server then deals with inter-server ActivityPub operations and propagates
       information across its social graph by posting activities to actors' inbox
       endpoints.
       server then deals with inter-server ActivityPub operations and propagates
       information across its social graph by posting activities to actors' inbox
       endpoints.

-  - name: Video Abuses
+    externalDocs:
+      url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
+  - name: Instance Redundancy
+    description: >
+      Redundancy is part of the inter-server solidarity that PeerTube fosters.
+      Manage the list of instances you wish to help by seeding their videos according
+      to the policy of video selection of your choice. Note that you have a similar functionality
+      to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
+    externalDocs:
+      url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
+  - name: Plugins
+    description: >
+      Managing plugins installed from a local path or from NPM, or search for new ones.
+    externalDocs:
+      url: https://docs.joinpeertube.org/api-plugins
+  - name: Abuses

     description: |
     description: |

-      Video abuses deal with reports of local or remote videos alike.
+      Abuses deal with reports of local or remote videos/comments/accounts alike.

   - name: Video
     description: |
       Operations dealing with listing, uploading, fetching or modifying videos.
   - name: Video
     description: |
       Operations dealing with listing, uploading, fetching or modifying videos.

+  - name: Video Upload
+    description: |
+      Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
+
+      ### Upload
+
+      - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
+      - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
+
+      You can upload videos more reliably by using the resumable variant. Its protocol lets
+      you resume an upload operation after a network interruption or other transmission failure,
+      saving time and bandwidth in the event of network failures.
+
+      Favor using resumable uploads in any of the following cases:
+      - You are transferring large files
+      - The likelihood of a network interruption is high
+      - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
+        such as a mobile device
+
+      ### Import
+
+      - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
+      - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
+      - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
+
+      The import function is practical when the desired video/audio is available online. It makes PeerTube
+      download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
+  - name: Video Captions
+    description: Operations dealing with listing, adding and removing closed captions of a video.
+  - name: Video Channels
+    description: Operations dealing with the creation, modification and listing of videos within a channel.
+  - name: Video Comments
+    description: >
+      Operations dealing with comments to a video. Comments are organized in threads: adding a
+      comment in response to the video starts a thread, adding a reply to a comment adds it to
+      its root comment thread.
+  - name: Video Blocks
+    description: Operations dealing with blocking videos (removing them from view and preventing interactions).
+  - name: Video Rates
+    description: Like/dislike a video.
+  - name: Video Playlists
+    description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
+  - name: Video Files
+    description: Operations on video files
+  - name: Video Transcoding
+    description: Video transcoding related operations
+  - name: Feeds
+    description: Server syndication feeds

   - name: Search
     description: |
       The search helps to find _videos_ or _channels_ from within the instance and beyond.
   - name: Search
     description: |
       The search helps to find _videos_ or _channels_ from within the instance and beyond.


@@ -81,52 +282,50 @@ tags:
 
       Administrators can also enable the use of a remote search system, indexing
       videos and channels not could be not federated by the instance.
 
       Administrators can also enable the use of a remote search system, indexing
       videos and channels not could be not federated by the instance.

-  - name: Video Comments
-    description: >
-      Operations dealing with comments to a video. Comments are organized in
-      threads.
-  - name: Video Playlists
-    description: >
-      Operations dealing with playlists of videos. Playlists are bound to users
-      and/or channels.
-  - name: Video Channels
-    description: >
-      Operations dealing with creation, modification and video listing of a
-      user's channels.
-  - name: Video Blocks
-    description: >
-      Operations dealing with blacklisting videos (removing them from view and
-      preventing interactions).
-  - name: Video Rates
-    description: >
-      Like/dislike a video.
-  - name: Feeds
-    description: >
-      Server syndication feeds
+  - name: Homepage
+    description: Get and update the custom homepage
+  - name: Video Mirroring
+    description: |
+      PeerTube instances can mirror videos from one another, and help distribute some videos.
+
+      For importing videos as your own, refer to [video imports](#operation/importVideo).

 x-tagGroups:
 x-tagGroups:

+  - name: Auth
+    tags:
+      - Register
+      - Session

   - name: Accounts
     tags:
       - Accounts
       - Users
       - My User
       - My Subscriptions
   - name: Accounts
     tags:
       - Accounts
       - Users
       - My User
       - My Subscriptions

+      - My Notifications
+      - My History

   - name: Videos
     tags:
       - Video
   - name: Videos
     tags:
       - Video

-      - Video Caption
+      - Video Upload
+      - Video Captions

       - Video Channels
       - Video Comments
       - Video Channels
       - Video Comments

-      - Video Following

       - Video Rates
       - Video Playlists
       - Video Ownership Change
       - Video Rates
       - Video Playlists
       - Video Ownership Change

+      - Video Mirroring
+      - Video Files
+      - Video Transcoding
+      - Live Videos

       - Feeds
   - name: Search
     tags:
       - Search
       - Feeds
   - name: Search
     tags:
       - Search

+  - name: Custom pages
+    tags:
+      - Homepage

   - name: Moderation
     tags:
   - name: Moderation
     tags:

-      - Video Abuses
+      - Abuses

       - Video Blocks
       - Account Blocks
       - Server Blocks
       - Video Blocks
       - Account Blocks
       - Server Blocks


@@ -134,6 +333,8 @@ x-tagGroups:
     tags:
       - Config
       - Instance Follows
     tags:
       - Config
       - Instance Follows

+      - Instance Redundancy
+      - Plugins

   - name: Jobs
     tags:
       - Job
   - name: Jobs
     tags:
       - Job


@@ -143,6 +344,7 @@ paths:
       tags:
         - Accounts
       summary: Get an account
       tags:
         - Accounts
       summary: Get an account

+      operationId: getAccount

       parameters:
         - $ref: '#/components/parameters/name'
       responses:
       parameters:
         - $ref: '#/components/parameters/name'
       responses:


@@ -154,21 +356,28 @@ paths:
                 $ref: '#/components/schemas/Account'
         '404':
           description: account not found
                 $ref: '#/components/schemas/Account'
         '404':
           description: account not found

+

   '/accounts/{name}/videos':
     get:
       tags:
         - Accounts
         - Video
       summary: 'List videos of an account'
   '/accounts/{name}/videos':
     get:
       tags:
         - Accounts
         - Video
       summary: 'List videos of an account'

+      operationId: getAccountVideos

       parameters:
         - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/categoryOneOf'
       parameters:
         - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/categoryOneOf'

+        - $ref: '#/components/parameters/isLive'

         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'

-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'

         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'


@@ -180,7 +389,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

-      x-code-samples:
+      x-codeSamples:

         - lang: JavaScript
           source: |
             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
         - lang: JavaScript
           source: |
             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')


@@ -191,8 +400,8 @@ paths:
             })
         - lang: Shell
           source: |
             })
         - lang: Shell
           source: |

-            # pip install httpie
-            http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
+            ## DEPENDENCIES: jq
+            curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq

         - lang: Ruby
           source: |
             require 'net/http'
         - lang: Ruby
           source: |
             require 'net/http'


@@ -214,11 +423,43 @@ paths:
             json = r.json()
 
             print(json)
             json = r.json()
 
             print(json)

+
+  '/accounts/{name}/followers':
+    get:
+      tags:
+        - Accounts
+      summary: 'List followers of an account'
+      security:
+        - OAuth2: []
+      operationId: getAccountFollowers
+      parameters:
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/followersSort'
+        - $ref: '#/components/parameters/search'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'
+

   /accounts:
     get:
       tags:
         - Accounts
       summary: List accounts
   /accounts:
     get:
       tags:
         - Accounts
       summary: List accounts

+      operationId: getAccounts

       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'


@@ -232,11 +473,13 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/Account'
                 type: array
                 items:
                   $ref: '#/components/schemas/Account'

+

   /config:
     get:
       tags:
         - Config
       summary: Get instance public configuration
   /config:
     get:
       tags:
         - Config
       summary: Get instance public configuration

+      operationId: getConfig

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -244,9 +487,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfig'
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfig'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/config
+

   /config/about:
     get:
       summary: Get instance "About" information
   /config/about:
     get:
       summary: Get instance "About" information

+      operationId: getAbout

       tags:
         - Config
       responses:
       tags:
         - Config
       responses:


@@ -256,14 +504,19 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfigAbout'
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfigAbout'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/config/about
+

   /config/custom:
     get:
       summary: Get instance runtime configuration
   /config/custom:
     get:
       summary: Get instance runtime configuration

+      operationId: getCustomConfig

       tags:
         - Config
       security:
         - OAuth2:
       tags:
         - Config
       security:
         - OAuth2:

-            - admin
+          - admin

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -273,45 +526,91 @@ paths:
                 $ref: '#/components/schemas/ServerConfigCustom'
     put:
       summary: Set instance runtime configuration
                 $ref: '#/components/schemas/ServerConfigCustom'
     put:
       summary: Set instance runtime configuration

+      operationId: putCustomConfig

       tags:
         - Config
       security:
         - OAuth2:
       tags:
         - Config
       security:
         - OAuth2:

-            - admin
+          - admin

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+        '400':
+          x-summary: field inconsistencies
+          description: >
+            Arises when:
+              - the emailer is disabled and the instance is open to registrations
+              - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled

     delete:
       summary: Delete instance runtime configuration
     delete:
       summary: Delete instance runtime configuration

+      operationId: delCustomConfig

       tags:
         - Config
       security:
         - OAuth2:
       tags:
         - Config
       security:
         - OAuth2:

-            - admin
+          - admin
+      responses:
+        '200':
+          description: successful operation
+
+  /custom-pages/homepage/instance:
+    get:
+      summary: Get instance custom homepage
+      tags:
+        - Homepage

       responses:
       responses:

+        '404':
+          description: No homepage set

         '200':
           description: successful operation
         '200':
           description: successful operation

+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CustomHomepage'
+    put:
+      summary: Set instance custom homepage
+      tags:
+        - Homepage
+      security:
+        - OAuth2:
+          - admin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                content:
+                  type: string
+                  description: content of the homepage, that will be injected in the client
+      responses:
+        '204':
+          description: successful operation
+

   /jobs/{state}:
     get:
       summary: List instance jobs
   /jobs/{state}:
     get:
       summary: List instance jobs

+      operationId: getJobs

       security:
         - OAuth2:
       security:
         - OAuth2:

-            - admin
+          - admin

       tags:
         - Job
       parameters:
         - name: state
           in: path
           required: true
       tags:
         - Job
       parameters:
         - name: state
           in: path
           required: true

-          description: The state of the job
+          description: The state of the job ('' for for no filter)

           schema:
             type: string
             enum:
           schema:
             type: string
             enum:

+              - ''

               - active
               - completed
               - failed
               - waiting
               - delayed
               - active
               - completed
               - failed
               - waiting
               - delayed

+        - $ref: '#/components/parameters/jobType'

         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'


@@ -321,51 +620,118 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/Job'
-  '/server/following/{host}':
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    maxItems: 100
+                    items:
+                      $ref: '#/components/schemas/Job'
+
+  /server/followers:
+    get:
+      tags:
+        - Instance Follows
+      summary: List instances following the server
+      parameters:
+        - $ref: '#/components/parameters/followState'
+        - $ref: '#/components/parameters/actorType'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'
+
+  '/server/followers/{nameWithHost}':

     delete:
     delete:

+      summary: Remove or reject a follower to your server

       security:
         - OAuth2:
           - admin
       tags:
         - Instance Follows
       security:
         - OAuth2:
           - admin
       tags:
         - Instance Follows

-      summary: Unfollow a server

       parameters:
       parameters:

-        - name: host
+        - name: nameWithHost

           in: path
           required: true
           in: path
           required: true

-          description: 'The host to unfollow '
+          description: The remote actor handle to remove from your followers

           schema:
             type: string
           schema:
             type: string

+            format: email

       responses:
       responses:

-        '201':
+        '204':

           description: successful operation
           description: successful operation

-  /server/followers:
-    get:
+        '404':
+          description: follower not found
+
+  '/server/followers/{nameWithHost}/reject':
+    post:
+      summary: Reject a pending follower to your server
+      security:
+        - OAuth2:
+          - admin

       tags:
         - Instance Follows
       tags:
         - Instance Follows

-      summary: List instance followers

       parameters:
       parameters:

-        - $ref: '#/components/parameters/start'
-        - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/sort'
+        - name: nameWithHost
+          in: path
+          required: true
+          description: The remote actor handle to remove from your followers
+          schema:
+            type: string
+            format: email

       responses:
       responses:

-        '200':
+        '204':

           description: successful operation
           description: successful operation

-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Follow'
+        '404':
+          description: follower not found
+
+  '/server/followers/{nameWithHost}/accept':
+    post:
+      summary: Accept a pending follower to your server
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Instance Follows
+      parameters:
+        - name: nameWithHost
+          in: path
+          required: true
+          description: The remote actor handle to remove from your followers
+          schema:
+            type: string
+            format: email
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: follower not found
+

   /server/following:
     get:
       tags:
         - Instance Follows
   /server/following:
     get:
       tags:
         - Instance Follows

-      summary: List instance followings
+      summary: List instances followed by the server

       parameters:
       parameters:

+        - $ref: '#/components/parameters/followState'
+        - $ref: '#/components/parameters/actorType'

         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/sort'


@@ -375,53 +741,120 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/Follow'
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'

     post:
       security:
         - OAuth2:
     post:
       security:
         - OAuth2:

-            - admin
+          - admin

       tags:
         - Instance Follows
       tags:
         - Instance Follows

-      summary: Follow a server
+      summary: Follow a list of actors (PeerTube instance, channel or account)

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+        '500':
+          description: cannot follow a non-HTTPS server

       requestBody:
         content:
           application/json:
             schema:
       requestBody:
         content:
           application/json:
             schema:

-              $ref: '#/components/schemas/Follow'
+              type: object
+              properties:
+                hosts:
+                  type: array
+                  items:
+                    type: string
+                    format: hostname
+                  uniqueItems: true
+                handles:
+                  type: array
+                  items:
+                    type: string
+                  uniqueItems: true
+
+  '/server/following/{hostOrHandle}':
+    delete:
+      summary: Unfollow an actor (PeerTube instance, channel or account)
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Instance Follows
+      parameters:
+        - name: hostOrHandle
+          in: path
+          required: true
+          description: The hostOrHandle to unfollow
+          schema:
+            type: string
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: host or handle not found
+

   /users:
     post:
       summary: Create a user
   /users:
     post:
       summary: Create a user

+      operationId: addUser

       security:
         - OAuth2:
       security:
         - OAuth2:

-            - admin
+          - admin

       tags:
         - Users
       responses:
         '200':
       tags:
         - Users
       responses:
         '200':

-          description: successful operation
+          description: user created

           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AddUserResponse'
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AddUserResponse'

+          links:
+            # GET /users/{id}
+            GetUser:
+              operationId: getUser
+              parameters:
+                id: '$response.body#/user/id'
+            # PUT /users/{id}
+            PutUser:
+              operationId: putUser
+              parameters:
+                id: '$response.body#/user/id'
+            # DELETE /users/{id}
+            DelUser:
+              operationId: delUser
+              parameters:
+                id: '$response.body#/user/id'
+        '403':
+          description: insufficient authority to create an admin or moderator

       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/AddUser'
       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/AddUser'

-        description: User to create
+        description: |
+          If the smtp server is configured, you can leave the password empty and an email will be sent
+          asking the user to set it first.

         required: true
     get:
       summary: List users
         required: true
     get:
       summary: List users

+      operationId: getUsers

       security:
       security:

-        - OAuth2: []
+        - OAuth2:
+          - admin

       tags:
         - Users
       parameters:
       tags:
         - Users
       parameters:

+        - $ref: '#/components/parameters/usersSearch'
+        - $ref: '#/components/parameters/usersBlocked'

         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/usersSort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/usersSort'


@@ -434,16 +867,18 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/User'
                 type: array
                 items:
                   $ref: '#/components/schemas/User'

+

   '/users/{id}':
   '/users/{id}':

+    parameters:
+      - $ref: '#/components/parameters/id'

     delete:
       summary: Delete a user
       security:
         - OAuth2:
     delete:
       summary: Delete a user
       security:
         - OAuth2:

-            - admin
+          - admin

       tags:
         - Users
       tags:
         - Users

-      parameters:
-        - $ref: '#/components/parameters/id'
+      operationId: delUser

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation


@@ -453,23 +888,32 @@ paths:
         - OAuth2: []
       tags:
         - Users
         - OAuth2: []
       tags:
         - Users

+      operationId: getUser

       parameters:
       parameters:

-        - $ref: '#/components/parameters/id'
+        - name: withStats
+          in: query
+          description: include statistics about the user (only available as a moderator/admin)
+          schema:
+            type: boolean

       responses:
         '200':
       responses:
         '200':

-          description: successful operation
+          x-summary: successful operation
+          description: |
+            As an admin/moderator, you can request a response augmented with statistics about the user's
+            moderation relations and videos usage, by using the `withStats` parameter.

           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                $ref: '#/components/schemas/User'
+                oneOf:
+                  - $ref: '#/components/schemas/User'
+                  - $ref: '#/components/schemas/UserWithStats'

     put:
       summary: Update a user
       security:
         - OAuth2: []
       tags:
         - Users
     put:
       summary: Update a user
       security:
         - OAuth2: []
       tags:
         - Users

-      parameters:
-        - $ref: '#/components/parameters/id'
+      operationId: putUser

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation


@@ -479,11 +923,132 @@ paths:
             schema:
               $ref: '#/components/schemas/UpdateUser'
         required: true
             schema:
               $ref: '#/components/schemas/UpdateUser'
         required: true

+
+  /oauth-clients/local:
+    get:
+      summary: Login prerequisite
+      description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
+      operationId: getOAuthClient
+      tags:
+        - Session
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthClient'
+          links:
+            UseOAuthClientToLogin:
+              operationId: getOAuthToken
+              parameters:
+                client_id: '$response.body#/client_id'
+                client_secret: '$response.body#/client_secret'
+      x-codeSamples:
+        - lang: Shell
+          source: |
+            API="https://peertube2.cpy.re/api/v1"
+
+            ## AUTH
+            curl -s "$API/oauth-clients/local"
+
+  /users/token:
+    post:
+      summary: Login
+      operationId: getOAuthToken
+      description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
+      tags:
+        - Session
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              oneOf:
+                - $ref: '#/components/schemas/OAuthToken-password'
+                - $ref: '#/components/schemas/OAuthToken-refresh_token'
+              discriminator:
+                propertyName: grant_type
+                mapping:
+                  password: '#/components/schemas/OAuthToken-password'
+                  refresh_token: '#/components/schemas/OAuthToken-refresh_token'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token_type:
+                    type: string
+                    example: Bearer
+                  access_token:
+                    type: string
+                    example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
+                    description: valid for 1 day
+                  refresh_token:
+                    type: string
+                    example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
+                    description: valid for 2 weeks
+                  expires_in:
+                    type: integer
+                    minimum: 0
+                    example: 14399
+                  refresh_token_expires_in:
+                    type: integer
+                    minimum: 0
+                    example: 1209600
+        '400':
+          x-summary: client or credentials are invalid
+          description: |
+            Disambiguate via `type`:
+            - `invalid_client` for an unmatched `client_id`
+            - `invalid_grant` for unmatched credentials
+        '401':
+          x-summary: token expired
+          description: |
+            Disambiguate via `type`:
+            - default value for a regular authentication failure
+            - `invalid_token` for an expired token
+      x-codeSamples:
+        - lang: Shell
+          source: |
+            ## DEPENDENCIES: jq
+            API="https://peertube2.cpy.re/api/v1"
+            USERNAME="<your_username>"
+            PASSWORD="<your_password>"
+
+            ## AUTH
+            client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+            client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+            curl -s "$API/users/token" \
+              --data client_id="$client_id" \
+              --data client_secret="$client_secret" \
+              --data grant_type=password \
+              --data username="$USERNAME" \
+              --data password="$PASSWORD" \
+              | jq -r ".access_token"
+
+  /users/revoke-token:
+    post:
+      summary: Logout
+      description: Revokes your access token and its associated refresh token, destroying your current session.
+      operationId: revokeOAuthToken
+      tags:
+        - Session
+      security:
+        - OAuth2: []
+      responses:
+        '200':
+          description: successful operation
+

   /users/register:
     post:
       summary: Register a user
   /users/register:
     post:
       summary: Register a user

+      operationId: registerUser

       tags:
         - Users
       tags:
         - Users

+        - Register

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation


@@ -493,9 +1058,55 @@ paths:
             schema:
               $ref: '#/components/schemas/RegisterUser'
         required: true
             schema:
               $ref: '#/components/schemas/RegisterUser'
         required: true

+
+  /users/{id}/verify-email:
+    post:
+      summary: Verify a user
+      operationId: verifyUser
+      description: |
+        Following a user registration, the new user will receive an email asking to click a link
+        containing a secret.
+      tags:
+        - Users
+        - Register
+      parameters:
+        - $ref: '#/components/parameters/id'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                verificationString:
+                  type: string
+                  format: url
+                isPendingEmail:
+                  type: boolean
+              required:
+                - verificationString
+      responses:
+        '204':
+          description: successful operation
+        '403':
+          description: invalid verification string
+        '404':
+          description: user not found
+
+  /users/ask-send-verify-email:
+    post:
+      summary: Resend user verification link
+      operationId: resendEmailToVerifyUser
+      tags:
+        - Users
+        - Register
+      responses:
+        '204':
+          description: successful operation
+

   /users/me:
     get:
       summary: Get my user information
   /users/me:
     get:
       summary: Get my user information

+      operationId: getUserInfo

       security:
         - OAuth2:
           - user
       security:
         - OAuth2:
           - user


@@ -512,6 +1123,7 @@ paths:
                   $ref: '#/components/schemas/User'
     put:
       summary: Update my user information
                   $ref: '#/components/schemas/User'
     put:
       summary: Update my user information

+      operationId: putUserInfo

       security:
         - OAuth2:
           - user
       security:
         - OAuth2:
           - user


@@ -526,12 +1138,13 @@ paths:
             schema:
               $ref: '#/components/schemas/UpdateMe'
         required: true
             schema:
               $ref: '#/components/schemas/UpdateMe'
         required: true

+

   /users/me/videos/imports:
     get:
       summary: Get video imports of my user
       security:
         - OAuth2:
   /users/me/videos/imports:
     get:
       summary: Get video imports of my user
       security:
         - OAuth2:

-            - user
+          - user

       tags:
         - Videos
         - My User
       tags:
         - Videos
         - My User


@@ -545,7 +1158,8 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                $ref: '#/components/schemas/VideoImport'
+                $ref: '#/components/schemas/VideoImportsList'
+

   /users/me/video-quota-used:
     get:
       summary: Get my user used quota
   /users/me/video-quota-used:
     get:
       summary: Get my user used quota


@@ -560,7 +1174,17 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                type: number
+                type: object
+                properties:
+                  videoQuotaUsed:
+                    type: number
+                    description: The user video quota used so far in bytes
+                    example: 16810141515
+                  videoQuotaUsedDaily:
+                    type: number
+                    description: The user video quota used today in bytes
+                    example: 1681014151
+

   '/users/me/videos/{videoId}/rating':
     get:
       summary: Get rate of my user for a video
   '/users/me/videos/{videoId}/rating':
     get:
       summary: Get rate of my user for a video


@@ -573,9 +1197,9 @@ paths:
         - name: videoId
           in: path
           required: true
         - name: videoId
           in: path
           required: true

-          description: 'The video id '
+          description: The video id

           schema:
           schema:

-            type: string
+            $ref: '#/components/schemas/Video/properties/id'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -583,6 +1207,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/GetMeVideoRating'
             application/json:
               schema:
                 $ref: '#/components/schemas/GetMeVideoRating'

+

   /users/me/videos:
     get:
       summary: Get videos of my user
   /users/me/videos:
     get:
       summary: Get videos of my user


@@ -603,12 +1228,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+

   /users/me/subscriptions:
     get:
       summary: Get my user subscriptions
       security:
         - OAuth2:
   /users/me/subscriptions:
     get:
       summary: Get my user subscriptions
       security:
         - OAuth2:

-            - user
+          - user

       tags:
         - My Subscriptions
       parameters:
       tags:
         - My Subscriptions
       parameters:


@@ -618,22 +1244,43 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoChannelList'

     post:
     post:

+      tags:
+        - My Subscriptions

       summary: Add subscription to my user
       security:
         - OAuth2:
       summary: Add subscription to my user
       security:
         - OAuth2:

-            - user
-      tags:
-        - My Subscriptions
+          - user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                uri:
+                  type: string
+                  format: uri
+                  description: uri of the video channels to subscribe to
+              required:
+                - uri
+            examples:
+              default:
+                value:
+                  uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+

   /users/me/subscriptions/exist:
     get:
       summary: Get if subscriptions exist for my user
       security:
         - OAuth2:
   /users/me/subscriptions/exist:
     get:
       summary: Get if subscriptions exist for my user
       security:
         - OAuth2:

-            - user
+          - user

       tags:
         - My Subscriptions
       parameters:
       tags:
         - My Subscriptions
       parameters:


@@ -645,6 +1292,7 @@ paths:
             application/json:
               schema:
                 type: object
             application/json:
               schema:
                 type: object

+

   /users/me/subscriptions/videos:
     get:
       summary: List videos of subscriptions of my user
   /users/me/subscriptions/videos:
     get:
       summary: List videos of subscriptions of my user


@@ -656,12 +1304,17 @@ paths:
         - Videos
       parameters:
         - $ref: '#/components/parameters/categoryOneOf'
         - Videos
       parameters:
         - $ref: '#/components/parameters/categoryOneOf'

+        - $ref: '#/components/parameters/isLive'

         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'

-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'

         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'


@@ -673,12 +1326,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+

   '/users/me/subscriptions/{subscriptionHandle}':
     get:
       summary: Get subscription of my user
       security:
         - OAuth2:
   '/users/me/subscriptions/{subscriptionHandle}':
     get:
       summary: Get subscription of my user
       security:
         - OAuth2:

-            - user
+          - user

       tags:
         - My Subscriptions
       parameters:
       tags:
         - My Subscriptions
       parameters:


@@ -694,7 +1348,7 @@ paths:
       summary: Delete subscription of my user
       security:
         - OAuth2:
       summary: Delete subscription of my user
       security:
         - OAuth2:

-            - user
+          - user

       tags:
         - My Subscriptions
       parameters:
       tags:
         - My Subscriptions
       parameters:


@@ -702,6 +1356,147 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+
+  /users/me/notifications:
+    get:
+      summary: List my notifications
+      security:
+        - OAuth2: []
+      tags:
+        - My Notifications
+      parameters:
+        - name: unread
+          in: query
+          description: only list unread notifications
+          schema:
+            type: boolean
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotificationListResponse'
+
+  /users/me/notifications/read:
+    post:
+      summary: Mark notifications as read by their id
+      security:
+        - OAuth2: []
+      tags:
+        - My Notifications
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                ids:
+                  type: array
+                  description: ids of the notifications to mark as read
+                  items:
+                    type: integer
+              required:
+                - ids
+      responses:
+        '204':
+          description: successful operation
+
+  /users/me/notifications/read-all:
+    post:
+      summary: Mark all my notification as read
+      security:
+        - OAuth2: []
+      tags:
+        - My Notifications
+      responses:
+        '204':
+          description: successful operation
+
+  /users/me/notification-settings:
+    put:
+      summary: Update my notification settings
+      security:
+        - OAuth2: []
+      tags:
+        - My Notifications
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                newVideoFromSubscription:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                newCommentOnMyVideo:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                abuseAsModerator:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                videoAutoBlacklistAsModerator:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                blacklistOnMyVideo:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                myVideoPublished:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                myVideoImportFinished:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                newFollow:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                newUserRegistration:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                commentMention:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                newInstanceFollower:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+                autoInstanceFollowing:
+                  $ref: '#/components/schemas/NotificationSettingValue'
+      responses:
+        '204':
+          description: successful operation
+
+  /users/me/history/videos:
+    get:
+      summary: List watched videos history
+      security:
+        - OAuth2: []
+      tags:
+        - My History
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/search'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoListResponse'
+
+  /users/me/history/videos/remove:
+    post:
+      summary: Clear video history
+      security:
+        - OAuth2: []
+      tags:
+        - My History
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                beforeDate:
+                  description: history before this date will be deleted
+                  type: string
+                  format: date-time
+      responses:
+        '204':
+          description: successful operation
+

   /users/me/avatar/pick:
     post:
       summary: Update my user avatar
   /users/me/avatar/pick:
     post:
       summary: Update my user avatar


@@ -715,7 +1510,18 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                $ref: '#/components/schemas/Avatar'
+                type: object
+                properties:
+                  avatar:
+                    $ref: '#/components/schemas/ActorImage'
+        '413':
+          description: image file too large
+          headers:
+            X-File-Maximum-Size:
+              schema:
+                type: string
+                format: Nginx size
+              description: Maximum file size for the avatar

       requestBody:
         content:
           multipart/form-data:
       requestBody:
         content:
           multipart/form-data:


@@ -723,12 +1529,24 @@ paths:
               type: object
               properties:
                 avatarfile:
               type: object
               properties:
                 avatarfile:

-                  description: The file to upload.
+                  description: The file to upload

                   type: string
                   format: binary
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg
                   type: string
                   format: binary
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg

+
+  /users/me/avatar:
+    delete:
+      summary: Delete my avatar
+      security:
+        - OAuth2: []
+      tags:
+        - My User
+      responses:
+        '204':
+          description: successful operation
+

   /videos/ownership:
     get:
       summary: List video ownership changes
   /videos/ownership:
     get:
       summary: List video ownership changes


@@ -739,6 +1557,7 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+

   '/videos/ownership/{id}/accept':
     post:
       summary: Accept ownership change request
   '/videos/ownership/{id}/accept':
     post:
       summary: Accept ownership change request


@@ -755,6 +1574,7 @@ paths:
           description: cannot terminate an ownership change of another user
         '404':
           description: video owneship change not found
           description: cannot terminate an ownership change of another user
         '404':
           description: video owneship change not found

+

   '/videos/ownership/{id}/refuse':
     post:
       summary: Refuse ownership change request
   '/videos/ownership/{id}/refuse':
     post:
       summary: Refuse ownership change request


@@ -771,6 +1591,7 @@ paths:
           description: cannot terminate an ownership change of another user
         '404':
           description: video owneship change not found
           description: cannot terminate an ownership change of another user
         '404':
           description: video owneship change not found

+

   '/videos/{id}/give-ownership':
     post:
       summary: Request ownership change
   '/videos/{id}/give-ownership':
     post:
       summary: Request ownership change


@@ -798,19 +1619,26 @@ paths:
           description: changing video ownership to a remote account is not supported yet
         '404':
           description: video not found
           description: changing video ownership to a remote account is not supported yet
         '404':
           description: video not found

+

   /videos:
     get:
       summary: List videos
   /videos:
     get:
       summary: List videos

+      operationId: getVideos

       tags:
         - Video
       parameters:
         - $ref: '#/components/parameters/categoryOneOf'
       tags:
         - Video
       parameters:
         - $ref: '#/components/parameters/categoryOneOf'

+        - $ref: '#/components/parameters/isLive'

         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'

-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'

         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'


@@ -822,9 +1650,11 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+

   /videos/categories:
     get:
       summary: List available video categories
   /videos/categories:
     get:
       summary: List available video categories

+      operationId: getCategories

       tags:
         - Video
       responses:
       tags:
         - Video
       responses:


@@ -836,9 +1666,14 @@ paths:
                 type: array
                 items:
                   type: string
                 type: array
                 items:
                   type: string

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/videos/categories
+

   /videos/licences:
     get:
       summary: List available video licences
   /videos/licences:
     get:
       summary: List available video licences

+      operationId: getLicences

       tags:
         - Video
       responses:
       tags:
         - Video
       responses:


@@ -850,9 +1685,14 @@ paths:
                 type: array
                 items:
                   type: string
                 type: array
                 items:
                   type: string

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/videos/licences
+

   /videos/languages:
     get:
       summary: List available video languages
   /videos/languages:
     get:
       summary: List available video languages

+      operationId: getLanguages

       tags:
         - Video
       responses:
       tags:
         - Video
       responses:


@@ -864,9 +1704,14 @@ paths:
                 type: array
                 items:
                   type: string
                 type: array
                 items:
                   type: string

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/videos/languages
+

   /videos/privacies:
     get:
   /videos/privacies:
     get:

-      summary: List available video privacies
+      summary: List available video privacy policies
+      operationId: getPrivacyPolicies

       tags:
         - Video
       responses:
       tags:
         - Video
       responses:


@@ -878,9 +1723,14 @@ paths:
                 type: array
                 items:
                   type: string
                 type: array
                 items:
                   type: string

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
+

   '/videos/{id}':
     put:
       summary: Update a video
   '/videos/{id}':
     put:
       summary: Update a video

+      operationId: putVideo

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -905,14 +1755,11 @@ paths:
                   type: string
                   format: binary
                 category:
                   type: string
                   format: binary
                 category:

-                  description: Video category
-                  type: string
+                  $ref: '#/components/schemas/VideoCategorySet'

                 licence:
                 licence:

-                  description: Video licence
-                  type: string
+                  $ref: '#/components/schemas/VideoLicenceSet'

                 language:
                 language:

-                  description: Video language
-                  type: string
+                  $ref: '#/components/schemas/VideoLanguageSet'

                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 description:
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 description:


@@ -922,14 +1769,17 @@ paths:
                   description: Whether or not we wait transcoding before publish the video
                   type: string
                 support:
                   description: Whether or not we wait transcoding before publish the video
                   type: string
                 support:

-                  description: Text describing how to support the video uploader
+                  description: A text tell the audience how to support the video creator
+                  example: Please support our work on https://soutenir.framasoft.org/en/ <3

                   type: string
                 nsfw:
                   description: Whether or not this video contains sensitive content
                   type: string
                 nsfw:
                   description: Whether or not this video contains sensitive content

-                  type: string
+                  type: boolean

                 name:
                   description: Video name
                   type: string
                 name:
                   description: Video name
                   type: string

+                  minLength: 3
+                  maxLength: 120

                 tags:
                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
                   type: array
                 tags:
                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
                   type: array


@@ -941,7 +1791,10 @@ paths:
                     maxLength: 30
                 commentsEnabled:
                   description: Enable or disable comments for this video
                     maxLength: 30
                 commentsEnabled:
                   description: Enable or disable comments for this video

-                  type: string
+                  type: boolean
+                downloadEnabled:
+                  description: Enable or disable downloading for this video
+                  type: boolean

                 originallyPublishedAt:
                   description: Date when the content was originally published
                   type: string
                 originallyPublishedAt:
                   description: Date when the content was originally published
                   type: string


@@ -955,6 +1808,7 @@ paths:
                 contentType: image/jpeg
     get:
       summary: Get a video
                 contentType: image/jpeg
     get:
       summary: Get a video

+      operationId: getVideo

       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:


@@ -968,6 +1822,7 @@ paths:
                 $ref: '#/components/schemas/VideoDetails'
     delete:
       summary: Delete a video
                 $ref: '#/components/schemas/VideoDetails'
     delete:
       summary: Delete a video

+      operationId: delVideo

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -977,9 +1832,11 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   '/videos/{id}/description':
     get:
       summary: Get complete video description
   '/videos/{id}/description':
     get:
       summary: Get complete video description

+      operationId: getVideoDesc

       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:


@@ -990,10 +1847,17 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

+                nullable: true

                 type: string
                 type: string

+                minLength: 3
+                maxLength: 10000
+                example: |
+                  **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
+

   '/videos/{id}/views':
     post:
       summary: Add a view to a video
   '/videos/{id}/views':
     post:
       summary: Add a view to a video

+      operationId: addView

       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:


@@ -1001,9 +1865,11 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   '/videos/{id}/watching':
     put:
       summary: Set watching progress of a video
   '/videos/{id}/watching':
     put:
       summary: Set watching progress of a video

+      operationId: setProgress

       tags:
         - Video
       security:
       tags:
         - Video
       security:


@@ -1019,13 +1885,17 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   /videos/upload:
     post:
       summary: Upload a video
   /videos/upload:
     post:
       summary: Upload a video

+      description: Uses a single request to upload a video.
+      operationId: uploadLegacy

       security:
         - OAuth2: []
       tags:
         - Video
       security:
         - OAuth2: []
       tags:
         - Video

+        - Video Upload

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1034,81 +1904,29 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
         '403':
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
         '403':

-          description: 'The user video quota is exceeded with this video.'
+          description: video didn't pass upload filter

         '408':
         '408':

-          description: 'Upload has timed out'
+          description: upload has timed out
+        '413':
+          x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
+          description: |
+            If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
+            - `quota_reached` for quota limits wether daily or global
+          headers:
+            X-File-Maximum-Size:
+              schema:
+                type: string
+                format: Nginx size
+              description: Maximum file size for the video
+        '415':
+          description: video type unsupported

         '422':
         '422':

-          description: 'Invalid input file.'
+          description: video unreadable

       requestBody:
         content:
           multipart/form-data:
             schema:
       requestBody:
         content:
           multipart/form-data:
             schema:

-              type: object
-              properties:
-                videofile:
-                  description: Video file
-                  type: string
-                  format: binary
-                channelId:
-                  description: Channel id that will contain this video
-                  type: integer
-                thumbnailfile:
-                  description: Video thumbnail file
-                  type: string
-                  format: binary
-                previewfile:
-                  description: Video preview file
-                  type: string
-                  format: binary
-                privacy:
-                  $ref: '#/components/schemas/VideoPrivacySet'
-                category:
-                  description: Video category
-                  type: string
-                licence:
-                  description: Video licence
-                  type: string
-                language:
-                  description: Video language
-                  type: string
-                description:
-                  description: Video description
-                  type: string
-                waitTranscoding:
-                  description: Whether or not we wait transcoding before publish the video
-                  type: string
-                support:
-                  description: Text describing how to support the video uploader
-                  type: string
-                nsfw:
-                  description: Whether or not this video contains sensitive content
-                  type: string
-                name:
-                  description: Video name
-                  type: string
-                tags:
-                  description: Video tags (maximum 5 tags each between 2 and 30 characters)
-                  type: array
-                  minItems: 1
-                  maxItems: 5
-                  uniqueItems: true
-                  items:
-                    type: string
-                    minLength: 2
-                    maxLength: 30
-                commentsEnabled:
-                  description: Enable or disable comments for this video
-                  type: string
-                originallyPublishedAt:
-                  description: Date when the content was originally published
-                  type: string
-                  format: date-time
-                scheduleUpdate:
-                  $ref: '#/components/schemas/VideoScheduledUpdate'
-              required:
-                - videofile
-                - channelId
-                - name
+              $ref: '#/components/schemas/VideoUploadRequestLegacy'

             encoding:
               videofile:
                 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
             encoding:
               videofile:
                 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream


@@ -1116,95 +1934,326 @@ paths:
                 contentType: image/jpeg
               previewfile:
                 contentType: image/jpeg
                 contentType: image/jpeg
               previewfile:
                 contentType: image/jpeg

-      x-code-samples:
+      x-codeSamples:

         - lang: Shell
           source: |
         - lang: Shell
           source: |

-            ## DEPENDENCIES: httpie, jq
-            # pip install httpie
+            ## DEPENDENCIES: jq

             USERNAME="<your_username>"
             PASSWORD="<your_password>"
             FILE_PATH="<your_file_path>"
             CHANNEL_ID="<your_channel_id>"
             NAME="<video_name>"
             USERNAME="<your_username>"
             PASSWORD="<your_password>"
             FILE_PATH="<your_file_path>"
             CHANNEL_ID="<your_channel_id>"
             NAME="<video_name>"

+            API="https://peertube2.cpy.re/api/v1"

 
 

-            API_PATH="https://peertube2.cpy.re/api/v1"

             ## AUTH
             ## AUTH

-            client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
-            client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
-            token=$(http -b --form POST "$API_PATH/users/token" \
-              client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
-              username=$USERNAME \
-              password=$PASSWORD \
+            client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+            client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+            token=$(curl -s "$API/users/token" \
+              --data client_id="$client_id" \
+              --data client_secret="$client_secret" \
+              --data grant_type=password \
+              --data username="$USERNAME" \
+              --data password="$PASSWORD" \

               | jq -r ".access_token")
               | jq -r ".access_token")

+

             ## VIDEO UPLOAD
             ## VIDEO UPLOAD

-            http -b --form POST "$API_PATH/videos/upload" \
-              videofile@$FILE_PATH \
-              channelId=$CHANNEL_ID \
-              name=$NAME \
-              "Authorization:Bearer $token"
+            curl -s "$API/videos/upload" \
+              -H "Authorization: Bearer $token" \
+              --max-time 600 \
+              --form videofile=@"$FILE_PATH" \
+              --form channelId=$CHANNEL_ID \
+              --form name="$NAME"
+
+  /videos/upload-resumable:
+    post:
+      summary: Initialize the resumable upload of a video
+      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
+      operationId: uploadResumableInit
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: X-Upload-Content-Length
+          in: header
+          schema:
+            type: number
+            example: 2469036
+          required: true
+          description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
+        - name: X-Upload-Content-Type
+          in: header
+          schema:
+            type: string
+            format: mimetype
+            example: video/mp4
+          required: true
+          description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoUploadRequestResumable'
+      responses:
+        '200':
+          description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
+        '201':
+          description: created
+          headers:
+            Location:
+              schema:
+                type: string
+                format: url
+                example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
+            Content-Length:
+              schema:
+                type: number
+                example: 0
+        '413':
+          x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+          description: |
+            Disambiguate via `type`:
+            - `max_file_size_reached` for the absolute file size limit
+            - `quota_reached` for quota limits whether daily or global
+        '415':
+          description: video type unsupported
+    put:
+      summary: Send chunk for the resumable upload of a video
+      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
+      operationId: uploadResumable
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: upload_id
+          in: query
+          required: true
+          description: |
+            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+            not valid anymore and you need to initialize a new upload.
+          schema:
+            type: string
+        - name: Content-Range
+          in: header
+          schema:
+            type: string
+            example: bytes 0-262143/2469036
+          required: true
+          description: |
+            Specifies the bytes in the file that the request is uploading.
+
+            For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
+            262144 bytes (256 x 1024) in a 2,469,036 byte file.
+        - name: Content-Length
+          in: header
+          schema:
+            type: number
+            example: 262144
+          required: true
+          description: |
+            Size of the chunk that the request is sending.
+
+            The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
+            doesn't mandate for chunks to have the same size throughout the upload sequence.
+
+            Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
+            1048576 bytes (~1MB) and increases or reduces size depending on connection health.
+      requestBody:
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        '200':
+          description: last chunk received
+          headers:
+            Content-Length:
+              schema:
+                type: number
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoUploadResponse'
+        '308':
+          description: resume incomplete
+          headers:
+            Range:
+              schema:
+                type: string
+                example: bytes=0-262143
+            Content-Length:
+              schema:
+                type: number
+                example: 0
+        '403':
+          description: video didn't pass upload filter
+        '404':
+          description: upload not found
+        '409':
+          description: chunk doesn't match range
+        '422':
+          description: video unreadable
+        '429':
+          description: too many concurrent requests
+        '503':
+          description: upload is already being processed
+          headers:
+            'Retry-After':
+              schema:
+                type: number
+                example: 300
+    delete:
+      summary: Cancel the resumable upload of a video, deleting any data uploaded so far
+      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
+      operationId: uploadResumableCancel
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: upload_id
+          in: query
+          required: true
+          description: |
+            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+            not valid anymore and the upload session has already been deleted with its data ;-)
+          schema:
+            type: string
+        - name: Content-Length
+          in: header
+          required: true
+          schema:
+            type: number
+            example: 0
+      responses:
+        '204':
+          description: upload cancelled
+          headers:
+            Content-Length:
+              schema:
+                type: number
+                example: 0
+        '404':
+          description: upload not found
+

   /videos/imports:
     post:
       summary: Import a video
       description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
   /videos/imports:
     post:
       summary: Import a video
       description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)

+      operationId: importVideo
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/VideoCreateImport'
+            encoding:
+              torrentfile:
+                contentType: application/x-bittorrent
+              thumbnailfile:
+                contentType: image/jpeg
+              previewfile:
+                contentType: image/jpeg
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoUploadResponse'
+        '400':
+          description: '`magnetUri` or `targetUrl` or a torrent file missing'
+        '403':
+          description: video didn't pass pre-import filter
+        '409':
+          description: HTTP or Torrent/magnetURI import not enabled
+
+  /videos/live:
+    post:
+      summary: Create a live
+      operationId: addLive

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:

+        - Live Videos

         - Video
         - Video

+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoUploadResponse'
+        '400':
+          x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
+          description: |
+            Disambiguate via `type`:
+            - default type for a validation error
+            - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
+        '403':
+          x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+          description: |
+            Disambiguate via `type`:
+            - `live_not_enabled` for a disabled live feature
+            - `live_not_allowing_replay` for a disabled replay feature
+            - `max_instance_lives_limit_reached` for the absolute concurrent live limit
+            - `max_user_lives_limit_reached` for the user concurrent live limit

       requestBody:
         content:
           multipart/form-data:
             schema:
               type: object
               properties:
       requestBody:
         content:
           multipart/form-data:
             schema:
               type: object
               properties:

-                torrentfile:
-                  description: Torrent File
-                  type: string
-                  format: binary
-                targetUrl:
-                  description: HTTP target URL
-                  type: string
-                magnetUri:
-                  description: Magnet URI
-                  type: string

                 channelId:
                 channelId:

-                  description: Channel id that will contain this video
+                  description: Channel id that will contain this live video

                   type: integer
                   type: integer

+                saveReplay:
+                  type: boolean
+                permanentLive:
+                  description: User can stream multiple times in a permanent live
+                  type: boolean

                 thumbnailfile:
                 thumbnailfile:

-                  description: Video thumbnail file
+                  description: Live video/replay thumbnail file

                   type: string
                   format: binary
                 previewfile:
                   type: string
                   format: binary
                 previewfile:

-                  description: Video preview file
+                  description: Live video/replay preview file

                   type: string
                   format: binary
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 category:
                   type: string
                   format: binary
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 category:

-                  description: Video category
-                  type: string
+                  $ref: '#/components/schemas/VideoCategorySet'

                 licence:
                 licence:

-                  description: Video licence
-                  type: string
+                  $ref: '#/components/schemas/VideoLicenceSet'

                 language:
                 language:

-                  description: Video language
-                  type: string
+                  $ref: '#/components/schemas/VideoLanguageSet'

                 description:
                 description:

-                  description: Video description
-                  type: string
-                waitTranscoding:
-                  description: Whether or not we wait transcoding before publish the video
+                  description: Live video/replay description

                   type: string
                 support:
                   type: string
                 support:

-                  description: Text describing how to support the video uploader
+                  description: A text tell the audience how to support the creator
+                  example: Please support our work on https://soutenir.framasoft.org/en/ <3

                   type: string
                 nsfw:
                   type: string
                 nsfw:

-                  description: Whether or not this video contains sensitive content
-                  type: string
+                  description: Whether or not this live video/replay contains sensitive content
+                  type: boolean

                 name:
                 name:

-                  description: Video name
+                  description: Live video/replay name

                   type: string
                   type: string

+                  minLength: 3
+                  maxLength: 120

                 tags:
                 tags:

-                  description: Video tags (maximum 5 tags each between 2 and 30 characters)
+                  description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)

                   type: array
                   minItems: 1
                   maxItems: 5
                   type: array
                   minItems: 1
                   maxItems: 5


@@ -1213,114 +2262,262 @@ paths:
                     minLength: 2
                     maxLength: 30
                 commentsEnabled:
                     minLength: 2
                     maxLength: 30
                 commentsEnabled:

-                  description: Enable or disable comments for this video
-                  type: string
-                scheduleUpdate:
-                  $ref: '#/components/schemas/VideoScheduledUpdate'
+                  description: Enable or disable comments for this live video/replay
+                  type: boolean
+                downloadEnabled:
+                  description: Enable or disable downloading for the replay of this live video
+                  type: boolean

               required:
                 - channelId
                 - name
             encoding:
               required:
                 - channelId
                 - name
             encoding:

-              torrentfile:
-                contentType: application/x-bittorrent

               thumbnailfile:
                 contentType: image/jpeg
               previewfile:
                 contentType: image/jpeg
               thumbnailfile:
                 contentType: image/jpeg
               previewfile:
                 contentType: image/jpeg

-      responses:
-        '200':
-          description: successful operation
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/VideoUploadResponse'
-        '409':
-          description: HTTP or Torrent/magnetURI import not enabled
-        '400':
-          description: '`magnetUri` or `targetUrl` or a torrent file missing'
-  /videos/abuse:
+
+  /videos/live/{id}:

     get:
     get:

-      summary: List video abuses
+      summary: Get information about a live
+      operationId: getLiveId

       security:
       security:

-        - OAuth2:
-          - admin
-          - moderator
+        - OAuth2: []

       tags:
       tags:

-        - Video Abuses
+        - Live Videos
+        - Video

       parameters:
       parameters:

-        - $ref: '#/components/parameters/start'
-        - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/abusesSort'
+        - $ref: '#/components/parameters/idOrUUID'

       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoAbuse'
-  '/videos/{id}/abuse':
-    post:
-      summary: Report an abuse
+                $ref: '#/components/schemas/LiveVideoResponse'
+    put:
+      summary: Update information about a live
+      operationId: updateLiveId

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:

-        - Video Abuses
-        - Videos
+        - Live Videos
+        - Video

       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       requestBody:
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       requestBody:

-        required: true

         content:
           application/json:
             schema:
         content:
           application/json:
             schema:

-              type: object
-              properties:
-                reason:
-                  description: Reason why the user reports this video
-                  type: string
-                predefinedReasons:
-                  description: Reason categories that help triage reports
-                  type: array
-                  items:
-                    type: string
-                    enum:
-                    - violentOrAbusive
-                    - hatefulOrAbusive
-                    - spamOrMisleading
-                    - privacy
-                    - rights
-                    - serverRules
-                    - thumbnails
-                    - captions
-                startAt:
-                  type: integer
-                  description: Timestamp in the video that marks the beginning of the report
-                endAt:
-                  type: integer
-                  description: Timestamp in the video that marks the ending of the report
-              required:
-                - reason
+              $ref: '#/components/schemas/LiveVideoUpdate'

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

-  '/videos/{id}/abuse/{abuseId}':
-    put:
-      summary: Update an abuse
+        '400':
+          description: bad parameters or trying to update a live that has already started
+        '403':
+          description: trying to save replay of the live but saving replay is not enabled on the instance
+
+  /users/me/abuses:
+    get:
+      summary: List my abuses
+      operationId: getMyAbuses

       security:
       security:

-        - OAuth2:
-          - admin
-          - moderator
+        - OAuth2: []

       tags:
       tags:

-        - Video Abuses
+        - Abuses
+        - My User
+      parameters:
+        - name: id
+          in: query
+          description: only list the report with this id
+          schema:
+            type: integer
+        - name: state
+          in: query
+          schema:
+            $ref: '#/components/schemas/AbuseStateSet'
+        - $ref: '#/components/parameters/abusesSort'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'

       responses:
       responses:

-        '204':
+        '200':

           description: successful operation
           description: successful operation

-        '404':
-          description: video abuse not found
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Abuse'
+
+  /abuses:
+    get:
+      summary: List abuses
+      operationId: getAbuses
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      tags:
+        - Abuses
+      parameters:
+        - name: id
+          in: query
+          description: only list the report with this id
+          schema:
+            type: integer
+        - name: predefinedReason
+          in: query
+          description: predefined reason the listed reports should contain
+          schema:
+            $ref: '#/components/schemas/PredefinedAbuseReasons'
+        - name: search
+          in: query
+          description: plain search that will match with video titles, reporter names and more
+          schema:
+            type: string
+        - name: state
+          in: query
+          schema:
+            $ref: '#/components/schemas/AbuseStateSet'
+        - name: searchReporter
+          in: query
+          description: only list reports of a specific reporter
+          schema:
+            type: string
+        - name: searchReportee
+          description: only list reports of a specific reportee
+          in: query
+          schema:
+            type: string
+        - name: searchVideo
+          in: query
+          description: only list reports of a specific video
+          schema:
+            type: string
+        - name: searchVideoChannel
+          in: query
+          description: only list reports of a specific video channel
+          schema:
+            type: string
+        - name: videoIs
+          in: query
+          description: only list deleted or blocklisted videos
+          schema:
+            type: string
+            enum:
+            - 'deleted'
+            - 'blacklisted'
+        - name: filter
+          in: query
+          description: only list account, comment or video reports
+          schema:
+            type: string
+            enum:
+            - 'video'
+            - 'comment'
+            - 'account'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/abusesSort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Abuse'
+    post:
+      summary: Report an abuse
+      security:
+        - OAuth2: []
+      tags:
+        - Abuses
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  description: Reason why the user reports this video
+                  type: string
+                  minLength: 2
+                  maxLength: 3000
+                predefinedReasons:
+                  $ref: '#/components/schemas/PredefinedAbuseReasons'
+                video:
+                  type: object
+                  properties:
+                    id:
+                      description: Video id to report
+                      allOf:
+                        - $ref: '#/components/schemas/Video/properties/id'
+                    startAt:
+                      type: integer
+                      format: seconds
+                      description: Timestamp in the video that marks the beginning of the report
+                      minimum: 0
+                    endAt:
+                      type: integer
+                      format: seconds
+                      description: Timestamp in the video that marks the ending of the report
+                      minimum: 0
+                comment:
+                  type: object
+                  properties:
+                    id:
+                      description: Comment id to report
+                      allOf:
+                        - $ref: '#/components/schemas/VideoComment/properties/id'
+                account:
+                  type: object
+                  properties:
+                    id:
+                      description: Account id to report
+                      type: integer
+              required:
+                - reason
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  abuse:
+                    type: object
+                    properties:
+                      id:
+                        $ref: '#/components/schemas/id'
+        '400':
+          description: incorrect request parameters
+
+  '/abuses/{abuseId}':
+    put:
+      summary: Update an abuse
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      tags:
+        - Abuses

       parameters:
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'

         - $ref: '#/components/parameters/abuseId'
       requestBody:
         content:
         - $ref: '#/components/parameters/abuseId'
       requestBody:
         content:


@@ -1329,34 +2526,107 @@ paths:
               type: object
               properties:
                 state:
               type: object
               properties:
                 state:

-                  $ref: '#/components/schemas/VideoAbuseStateSet'
+                  $ref: '#/components/schemas/AbuseStateSet'

                 moderationComment:
                   type: string
                 moderationComment:
                   type: string

-                  description: 'Update the comment of the video abuse for other admin/moderators'
+                  description: Update the report comment visible only to the moderation team
+                  minLength: 2
+                  maxLength: 3000
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: abuse not found

     delete:
     delete:

+      tags:
+        - Abuses

       summary: Delete an abuse
       security:
         - OAuth2:
       summary: Delete an abuse
       security:
         - OAuth2:

-            - admin
-            - moderator
-      tags:
-        - Video Abuses
+          - admin
+          - moderator
+      parameters:
+        - $ref: '#/components/parameters/abuseId'

       responses:
         '204':
           description: successful operation
         '404':
           description: block not found
       responses:
         '204':
           description: successful operation
         '404':
           description: block not found

+
+  '/abuses/{abuseId}/messages':
+    get:
+      summary: List messages of an abuse
+      security:
+        - OAuth2: []
+      tags:
+        - Abuses
+      parameters:
+        - $ref: '#/components/parameters/abuseId'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/AbuseMessage'
+    post:
+      summary: Add message to an abuse
+      security:
+        - OAuth2: []
+      tags:
+        - Abuses
+      parameters:
+        - $ref: '#/components/parameters/abuseId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                message:
+                  description: Message to send
+                  type: string
+                  minLength: 2
+                  maxLength: 3000
+              required:
+                - message
+      responses:
+        '200':
+          description: successful operation
+        '400':
+          description: incorrect request parameters
+
+  '/abuses/{abuseId}/messages/{abuseMessageId}':
+    delete:
+      summary: Delete an abuse message
+      security:
+        - OAuth2: []
+      tags:
+        - Abuses

       parameters:
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'

         - $ref: '#/components/parameters/abuseId'
         - $ref: '#/components/parameters/abuseId'

+        - $ref: '#/components/parameters/abuseMessageId'
+      responses:
+        '204':
+          description: successful operation

 
   '/videos/{id}/blacklist':
     post:
       summary: Block a video
 
   '/videos/{id}/blacklist':
     post:
       summary: Block a video

+      operationId: addVideoBlock

       security:
         - OAuth2:
       security:
         - OAuth2:

-            - admin
-            - moderator
+          - admin
+          - moderator

       tags:
         - Video Blocks
       parameters:
       tags:
         - Video Blocks
       parameters:


@@ -1366,10 +2636,11 @@ paths:
           description: successful operation
     delete:
       summary: Unblock a video by its id
           description: successful operation
     delete:
       summary: Unblock a video by its id

+      operationId: delVideoBlock

       security:
         - OAuth2:
       security:
         - OAuth2:

-            - admin
-            - moderator
+          - admin
+          - moderator

       tags:
         - Video Blocks
       parameters:
       tags:
         - Video Blocks
       parameters:


@@ -1379,16 +2650,36 @@ paths:
           description: successful operation
         '404':
           description: block not found
           description: successful operation
         '404':
           description: block not found

+

   /videos/blacklist:
     get:
       tags:
         - Video Blocks
   /videos/blacklist:
     get:
       tags:
         - Video Blocks

-      summary: List blocked videos
+      summary: List video blocks
+      operationId: getVideoBlocks

       security:
         - OAuth2:
       security:
         - OAuth2:

-            - admin
-            - moderator
+          - admin
+          - moderator

       parameters:
       parameters:

+        - name: type
+          in: query
+          description: >
+            list only blocks that match this type:
+
+            - `1`: manual block
+
+            - `2`: automatic block that needs review
+          schema:
+            type: integer
+            enum:
+              - 1
+              - 2
+        - name: search
+          in: query
+          description: plain search that will match with video titles, and more
+          schema:
+            type: string

         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/blacklistsSort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/blacklistsSort'


@@ -1398,14 +2689,22 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoBlacklist'
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoBlacklist'
+

   /videos/{id}/captions:
     get:
       summary: List captions of a video
   /videos/{id}/captions:
     get:
       summary: List captions of a video

+      operationId: getVideoCaptions

       tags:
       tags:

-        - Video Caption
+        - Video Captions

       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:


@@ -1418,15 +2717,21 @@ paths:
                 properties:
                   total:
                     type: integer
                 properties:
                   total:
                     type: integer

+                    example: 1

                   data:
                     type: array
                     items:
                       $ref: '#/components/schemas/VideoCaption'
                   data:
                     type: array
                     items:
                       $ref: '#/components/schemas/VideoCaption'

+

   /videos/{id}/captions/{captionLanguage}:
     put:
       summary: Add or replace a video caption
   /videos/{id}/captions/{captionLanguage}:
     put:
       summary: Add or replace a video caption

+      operationId: addVideoCaption
+      security:
+        - OAuth2:
+          - user

       tags:
       tags:

-        - Video Caption
+        - Video Captions

       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'


@@ -1450,8 +2755,12 @@ paths:
           description: video or language not found
     delete:
       summary: Delete a video caption
           description: video or language not found
     delete:
       summary: Delete a video caption

+      operationId: delVideoCaption
+      security:
+        - OAuth2:
+          - user

       tags:
       tags:

-        - Video Caption
+        - Video Captions

       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/captionLanguage'


@@ -1460,9 +2769,11 @@ paths:
           description: successful operation
         '404':
           description: video or language or caption for that language not found
           description: successful operation
         '404':
           description: video or language or caption for that language not found

+

   /video-channels:
     get:
       summary: List video channels
   /video-channels:
     get:
       summary: List video channels

+      operationId: getVideoChannels

       tags:
         - Video Channels
       parameters:
       tags:
         - Video Channels
       parameters:


@@ -1475,11 +2786,10 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoChannelList'

     post:
       summary: Create a video channel
     post:
       summary: Create a video channel

+      operationId: addVideoChannel

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -1487,14 +2797,26 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  videoChannel:
+                    type: object
+                    properties:
+                      id:
+                        $ref: '#/components/schemas/VideoChannel/properties/id'

       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/VideoChannelCreate'
       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/VideoChannelCreate'

+

   '/video-channels/{channelHandle}':
     get:
       summary: Get a video channel
   '/video-channels/{channelHandle}':
     get:
       summary: Get a video channel

+      operationId: getVideoChannel

       tags:
         - Video Channels
       parameters:
       tags:
         - Video Channels
       parameters:


@@ -1508,6 +2830,7 @@ paths:
                 $ref: '#/components/schemas/VideoChannel'
     put:
       summary: Update a video channel
                 $ref: '#/components/schemas/VideoChannel'
     put:
       summary: Update a video channel

+      operationId: putVideoChannel

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -1524,6 +2847,7 @@ paths:
               $ref: '#/components/schemas/VideoChannelUpdate'
     delete:
       summary: Delete a video channel
               $ref: '#/components/schemas/VideoChannelUpdate'
     delete:
       summary: Delete a video channel

+      operationId: delVideoChannel

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -1533,21 +2857,28 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   '/video-channels/{channelHandle}/videos':
     get:
       summary: List videos of a video channel
   '/video-channels/{channelHandle}/videos':
     get:
       summary: List videos of a video channel

+      operationId: getVideoChannelVideos

       tags:
         - Video
         - Video Channels
       parameters:
         - $ref: '#/components/parameters/channelHandle'
         - $ref: '#/components/parameters/categoryOneOf'
       tags:
         - Video
         - Video Channels
       parameters:
         - $ref: '#/components/parameters/channelHandle'
         - $ref: '#/components/parameters/categoryOneOf'

+        - $ref: '#/components/parameters/isLive'

         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'

-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'

         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'


@@ -1560,30 +2891,150 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 

-  /video-playlists/privacies:
-    get:
-      summary: List available playlist privacies
-      tags:
-        - Video Playlists
-      responses:
-        '200':
-          description: successful operation
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  type: string
-
-  /video-playlists:
+  '/video-channels/{channelHandle}/followers':

     get:
     get:

-      summary: List video playlists

       tags:
       tags:

-        - Video Playlists
+        - Video Channels
+      summary: 'List followers of a video channel'
+      security:
+        - OAuth2: []
+      operationId: getVideoChannelFollowers

       parameters:
       parameters:

+        - $ref: '#/components/parameters/channelHandle'

         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'

-        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/followersSort'
+        - $ref: '#/components/parameters/search'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'
+
+  '/video-channels/{channelHandle}/avatar/pick':
+    post:
+      summary: Update channel avatar
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  avatar:
+                    $ref: '#/components/schemas/ActorImage'
+        '413':
+          description: image file too large
+          headers:
+            X-File-Maximum-Size:
+              schema:
+                type: string
+                format: Nginx size
+              description: Maximum file size for the avatar
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                avatarfile:
+                  description: The file to upload.
+                  type: string
+                  format: binary
+            encoding:
+              avatarfile:
+                contentType: image/png, image/jpeg
+
+  '/video-channels/{channelHandle}/avatar':
+    delete:
+      summary: Delete channel avatar
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '204':
+          description: successful operation
+
+  '/video-channels/{channelHandle}/banner/pick':
+    post:
+      summary: Update channel banner
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  banner:
+                    $ref: '#/components/schemas/ActorImage'
+        '413':
+          description: image file too large
+          headers:
+            X-File-Maximum-Size:
+              schema:
+                type: string
+                format: Nginx size
+              description: Maximum file size for the banner
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                bannerfile:
+                  description: The file to upload.
+                  type: string
+                  format: binary
+            encoding:
+              bannerfile:
+                contentType: image/png, image/jpeg
+
+  '/video-channels/{channelHandle}/banner':
+    delete:
+      summary: Delete channel banner
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '204':
+          description: successful operation
+
+  /video-playlists/privacies:
+    get:
+      summary: List available playlist privacy policies
+      operationId: getPlaylistPrivacyPolicies
+      tags:
+        - Video Playlists

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1592,10 +3043,40 @@ paths:
               schema:
                 type: array
                 items:
               schema:
                 type: array
                 items:

-                  $ref: '#/components/schemas/VideoPlaylist'
+                  type: string
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
+
+  /video-playlists:
+    get:
+      summary: List video playlists
+      operationId: getPlaylists
+      tags:
+        - Video Playlists
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoPlaylist'

     post:
       summary: Create a video playlist
     post:
       summary: Create a video playlist

-      description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
+      description: If the video playlist is set as public, `videoChannelId` is mandatory.
+      operationId: addPlaylist

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -1612,9 +3093,11 @@ paths:
                     type: object
                     properties:
                       id:
                     type: object
                     properties:
                       id:

-                        type: integer
+                        $ref: '#/components/schemas/VideoPlaylist/properties/id'

                       uuid:
                       uuid:

-                        type: string
+                        $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
+                      shortUUID:
+                        $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'

       requestBody:
         content:
           multipart/form-data:
       requestBody:
         content:
           multipart/form-data:


@@ -1624,6 +3107,8 @@ paths:
                 displayName:
                   description: Video playlist display name
                   type: string
                 displayName:
                   description: Video playlist display name
                   type: string

+                  minLength: 1
+                  maxLength: 120

                 thumbnailfile:
                   description: Video playlist thumbnail file
                   type: string
                 thumbnailfile:
                   description: Video playlist thumbnail file
                   type: string


@@ -1633,19 +3118,25 @@ paths:
                 description:
                   description: Video playlist description
                   type: string
                 description:
                   description: Video playlist description
                   type: string

+                  minLength: 3
+                  maxLength: 1000

                 videoChannelId:
                 videoChannelId:

+                  allOf:
+                    - $ref: '#/components/schemas/id'

                   description: Video channel in which the playlist will be published
                   description: Video channel in which the playlist will be published

-                  type: integer

               required:
                 - displayName
               required:
                 - displayName

+            encoding:
+              thumbnailfile:
+                contentType: image/jpeg

 
 

-  /video-playlists/{id}:
+  /video-playlists/{playlistId}:

     get:
       summary: Get a video playlist
       tags:
         - Video Playlists
       parameters:
     get:
       summary: Get a video playlist
       tags:
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1664,7 +3155,7 @@ paths:
         '204':
           description: successful operation
       parameters:
         '204':
           description: successful operation
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

       requestBody:
         content:
           multipart/form-data:
       requestBody:
         content:
           multipart/form-data:


@@ -1674,6 +3165,8 @@ paths:
                 displayName:
                   description: Video playlist display name
                   type: string
                 displayName:
                   description: Video playlist display name
                   type: string

+                  minLength: 1
+                  maxLength: 120

                 thumbnailfile:
                   description: Video playlist thumbnail file
                   type: string
                 thumbnailfile:
                   description: Video playlist thumbnail file
                   type: string


@@ -1684,8 +3177,12 @@ paths:
                   description: Video playlist description
                   type: string
                 videoChannelId:
                   description: Video playlist description
                   type: string
                 videoChannelId:

+                  allOf:
+                    - $ref: '#/components/schemas/id'

                   description: Video channel in which the playlist will be published
                   description: Video channel in which the playlist will be published

-                  type: integer
+            encoding:
+              thumbnailfile:
+                contentType: image/jpeg

     delete:
       summary: Delete a video playlist
       security:
     delete:
       summary: Delete a video playlist
       security:


@@ -1693,19 +3190,22 @@ paths:
       tags:
         - Video Playlists
       parameters:
       tags:
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

       responses:
         '204':
           description: successful operation
 
       responses:
         '204':
           description: successful operation
 

-  /video-playlists/{id}/videos:
+  /video-playlists/{playlistId}/videos:

     get:
       summary: 'List videos of a playlist'
     get:
       summary: 'List videos of a playlist'

+      operationId: getVideoPlaylistVideos

       tags:
         - Videos
         - Video Playlists
       parameters:
       tags:
         - Videos
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1714,14 +3214,15 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
     post:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
     post:

-      summary: 'Add a video in a playlist'
+      summary: Add a video in a playlist
+      operationId: addVideoPlaylistVideo

       security:
         - OAuth2: []
       tags:
         - Videos
         - Video Playlists
       parameters:
       security:
         - OAuth2: []
       tags:
         - Videos
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1735,6 +3236,7 @@ paths:
                     properties:
                       id:
                         type: integer
                     properties:
                       id:
                         type: integer

+                        example: 2

       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:


@@ -1742,26 +3244,31 @@ paths:
               type: object
               properties:
                 videoId:
               type: object
               properties:
                 videoId:

-                  type: integer
-                  description: 'Video to add in the playlist'
+                  oneOf:
+                    - $ref: '#/components/schemas/Video/properties/uuid'
+                    - $ref: '#/components/schemas/Video/properties/id'
+                  description: Video to add in the playlist

                 startTimestamp:
                   type: integer
                 startTimestamp:
                   type: integer

-                  description: 'Start the video at this specific timestamp (in seconds)'
+                  format: seconds
+                  description: Start the video at this specific timestamp

                 stopTimestamp:
                   type: integer
                 stopTimestamp:
                   type: integer

-                  description: 'Stop the video at this specific timestamp (in seconds)'
+                  format: seconds
+                  description: Stop the video at this specific timestamp

               required:
                 - videoId
 
               required:
                 - videoId
 

-  /video-playlists/{id}/videos/reorder:
+  /video-playlists/{playlistId}/videos/reorder:

     post:
       summary: 'Reorder a playlist'
     post:
       summary: 'Reorder a playlist'

+      operationId: reorderVideoPlaylist

       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:
       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation


@@ -1787,15 +3294,16 @@ paths:
                 - startPosition
                 - insertAfterPosition
 
                 - startPosition
                 - insertAfterPosition
 

-  /video-playlists/{id}/videos/{playlistElementId}:
+  /video-playlists/{playlistId}/videos/{playlistElementId}:

     put:
     put:

-      summary: 'Update a playlist element'
+      summary: Update a playlist element
+      operationId: putVideoPlaylistVideo

       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:
       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

         - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':
         - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':


@@ -1808,18 +3316,21 @@ paths:
               properties:
                 startTimestamp:
                   type: integer
               properties:
                 startTimestamp:
                   type: integer

-                  description: 'Start the video at this specific timestamp (in seconds)'
+                  format: seconds
+                  description: Start the video at this specific timestamp

                 stopTimestamp:
                   type: integer
                 stopTimestamp:
                   type: integer

-                  description: 'Stop the video at this specific timestamp (in seconds)'
+                  format: seconds
+                  description: Stop the video at this specific timestamp

     delete:
     delete:

-      summary: 'Delete an element from a playlist'
+      summary: Delete an element from a playlist
+      operationId: delVideoPlaylistVideo

       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:
       security:
         - OAuth2: []
       tags:
         - Video Playlists
       parameters:

-        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistId'

         - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':
         - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':


@@ -1827,7 +3338,7 @@ paths:
 
   '/users/me/video-playlists/videos-exist':
     get:
 
   '/users/me/video-playlists/videos-exist':
     get:

-      summary: 'Check video exists in my playlists'
+      summary: Check video exists in my playlists

       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:


@@ -1840,7 +3351,7 @@ paths:
           schema:
             type: array
             items:
           schema:
             type: array
             items:

-              type: integer
+              $ref: '#/components/schemas/Video/properties/id'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -1860,8 +3371,10 @@ paths:
                           type: integer
                         startTimestamp:
                           type: integer
                           type: integer
                         startTimestamp:
                           type: integer

+                          format: seconds

                         stopTimestamp:
                           type: integer
                         stopTimestamp:
                           type: integer

+                          format: seconds

 
   '/accounts/{name}/video-channels':
     get:
 
   '/accounts/{name}/video-channels':
     get:


@@ -1871,15 +3384,22 @@ paths:
         - Accounts
       parameters:
         - $ref: '#/components/parameters/name'
         - Accounts
       parameters:
         - $ref: '#/components/parameters/name'

+        - name: withStats
+          in: query
+          description: include view statistics for the last 30 days (only if authentified as the account user)
+          schema:
+            type: boolean
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'

       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoChannelList'
+

   '/accounts/{name}/ratings':
     get:
       summary: List ratings of an account
   '/accounts/{name}/ratings':
     get:
       summary: List ratings of an account


@@ -1910,6 +3430,7 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/VideoRating'
                 type: array
                 items:
                   $ref: '#/components/schemas/VideoRating'

+

   '/videos/{id}/comment-threads':
     get:
       summary: List threads of a video
   '/videos/{id}/comment-threads':
     get:
       summary: List threads of a video


@@ -1942,6 +3463,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'

+        '404':
+          description: video does not exist

       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:


@@ -1949,8 +3472,10 @@ paths:
               type: object
               properties:
                 text:
               type: object
               properties:
                 text:

-                  type: string
-                  description: 'Text comment'
+                  allOf:
+                    - $ref: '#/components/schemas/VideoComment/properties/text'
+                  format: markdown
+                  maxLength: 10000

               required:
                 - text
 
               required:
                 - text
 


@@ -1969,6 +3494,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoCommentThreadTree'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoCommentThreadTree'

+

   '/videos/{id}/comments/{commentId}':
     post:
       summary: Reply to a thread of a video
   '/videos/{id}/comments/{commentId}':
     post:
       summary: Reply to a thread of a video


@@ -1986,6 +3512,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'

+        '404':
+          description: thread or video does not exist

       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:


@@ -1993,11 +3521,12 @@ paths:
               type: object
               properties:
                 text:
               type: object
               properties:
                 text:

-                  type: string
-                  description: 'Text comment'
+                  allOf:
+                    - $ref: '#/components/schemas/VideoComment/properties/text'
+                  format: markdown
+                  maxLength: 10000

               required:
                 - text
               required:
                 - text

-

     delete:
       summary: Delete a comment or a reply
       security:
     delete:
       summary: Delete a comment or a reply
       security:


@@ -2010,6 +3539,13 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+        '403':
+          description: cannot remove comment of another user
+        '404':
+          description: comment or video does not exist
+        '409':
+          description: comment is already deleted
+

   '/videos/{id}/rate':
     put:
       summary: Like/dislike a video
   '/videos/{id}/rate':
     put:
       summary: Like/dislike a video


@@ -2019,76 +3555,159 @@ paths:
         - Video Rates
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - Video Rates
       parameters:
         - $ref: '#/components/parameters/idOrUUID'

+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                rating:
+                  type: string
+                  enum:
+                    - like
+                    - dislike
+              required:
+                - rating
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+
+  '/videos/{id}/hls':
+    delete:
+      summary: Delete video HLS files
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Files
+      operationId: delVideoHLS
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+  '/videos/{id}/webtorrent':
+    delete:
+      summary: Delete video WebTorrent files
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Files
+      operationId: delVideoWebTorrent
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+
+  '/videos/{id}/transcoding':
+    post:
+      summary: Create a transcoding job
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Transcoding
+      operationId: createVideoTranscoding
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  transcodingType:
+                    type: string
+                    enum:
+                      - hls
+                      - webtorrent
+                required:
+                  - transcodingType

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+        '404':
+          description: video does not exist
+

   /search/videos:
     get:
       tags:
         - Search
       summary: Search videos
   /search/videos:
     get:
       tags:
         - Search
       summary: Search videos

+      operationId: searchVideos

       parameters:
       parameters:

+        - name: search
+          in: query
+          required: true
+          allowEmptyValue: false
+          description: >
+            String to search. If the user can make a remote URI search, and the string is an URI then the
+            PeerTube instance will fetch the remote object and add it to its database. Then,
+            you can use the REST API to fetch the complete video information and interact with it.
+          schema:
+            type: string

         - $ref: '#/components/parameters/categoryOneOf'
         - $ref: '#/components/parameters/categoryOneOf'

+        - $ref: '#/components/parameters/isLive'

         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/tagsOneOf'
         - $ref: '#/components/parameters/tagsAllOf'
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'

-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'

         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/searchTarget'
         - $ref: '#/components/parameters/videosSearchSort'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/searchTarget'
         - $ref: '#/components/parameters/videosSearchSort'

-        - name: search
-          in: query
-          required: true
-          description: >
-            String to search. If the user can make a remote URI search, and the string is an URI then the
-            PeerTube instance will fetch the remote object and add it to its database. Then,
-            you can use the REST API to fetch the complete video information and interact with it.
-          schema:
-            type: string

         - name: startDate
           in: query
         - name: startDate
           in: query

-          required: true

           description: Get videos that are published after this date
           schema:
             type: string
             format: date-time
         - name: endDate
           in: query
           description: Get videos that are published after this date
           schema:
             type: string
             format: date-time
         - name: endDate
           in: query

-          required: true

           description: Get videos that are published before this date
           schema:
             type: string
             format: date-time
         - name: originallyPublishedStartDate
           in: query
           description: Get videos that are published before this date
           schema:
             type: string
             format: date-time
         - name: originallyPublishedStartDate
           in: query

-          required: true

           description: Get videos that are originally published after this date
           schema:
             type: string
             format: date-time
         - name: originallyPublishedEndDate
           in: query
           description: Get videos that are originally published after this date
           schema:
             type: string
             format: date-time
         - name: originallyPublishedEndDate
           in: query

-          required: true

           description: Get videos that are originally published before this date
           schema:
             type: string
             format: date-time
         - name: durationMin
           in: query
           description: Get videos that are originally published before this date
           schema:
             type: string
             format: date-time
         - name: durationMin
           in: query

-          required: true

           description: Get videos that have this minimum duration
           schema:
             type: integer
         - name: durationMax
           in: query
           description: Get videos that have this minimum duration
           schema:
             type: integer
         - name: durationMax
           in: query

-          required: true

           description: Get videos that have this maximum duration
           schema:
             type: integer
           description: Get videos that have this maximum duration
           schema:
             type: integer

+      callbacks:
+        'searchTarget === search-index':
+          $ref: '#/components/callbacks/searchIndex'

       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation


@@ -2096,16 +3715,16 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+        '500':
+          description: search index unavailable
+

   /search/video-channels:
     get:
       tags:
         - Search
       summary: Search channels
   /search/video-channels:
     get:
       tags:
         - Search
       summary: Search channels

+      operationId: searchChannels

       parameters:
       parameters:

-        - $ref: '#/components/parameters/start'
-        - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/searchTarget'
-        - $ref: '#/components/parameters/sort'

         - name: search
           in: query
           required: true
         - name: search
           in: query
           required: true


@@ -2115,19 +3734,101 @@ paths:
             you can use the REST API to fetch the complete channel information and interact with it.
           schema:
             type: string
             you can use the REST API to fetch the complete channel information and interact with it.
           schema:
             type: string

+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/searchTarget'
+        - $ref: '#/components/parameters/sort'
+      callbacks:
+        'searchTarget === search-index':
+          $ref: '#/components/callbacks/searchIndex'

       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:

-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoChannel'
-  /blocklist/accounts:
+                $ref: '#/components/schemas/VideoChannelList'
+        '500':
+          description: search index unavailable
+
+  /search/video-playlists:

     get:
       tags:
     get:
       tags:

-        - Account Blocks
+        - Search
+      summary: Search playlists
+      operationId: searchPlaylists
+      parameters:
+        - name: search
+          in: query
+          required: true
+          description: >
+            String to search. If the user can make a remote URI search, and the string is an URI then the
+            PeerTube instance will fetch the remote object and add it to its database. Then,
+            you can use the REST API to fetch the complete playlist information and interact with it.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/searchTarget'
+        - $ref: '#/components/parameters/sort'
+      callbacks:
+        'searchTarget === search-index':
+          $ref: '#/components/callbacks/searchIndex'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/VideoPlaylist'
+        '500':
+          description: search index unavailable
+
+  /blocklist/status:
+    get:
+      tags:
+        - Account Blocks
+        - Server Blocks
+      summary: Get block status of accounts/hosts
+      parameters:
+        -
+          name: 'accounts'
+          in: query
+          description: 'Check if these accounts are blocked'
+          example: [ 'goofy@example.com', 'donald@example.com' ]
+          schema:
+            type: array
+            items:
+              type: string
+        -
+          name: 'hosts'
+          in: query
+          description: 'Check if these hosts are blocked'
+          example: [ 'example.com' ]
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        '200':
+          description: successful operation
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/BlockStatus'
+
+  /server/blocklist/accounts:
+    get:
+      tags:
+        - Account Blocks

       summary: List account blocks
       security:
         - OAuth2:
       summary: List account blocks
       security:
         - OAuth2:


@@ -2154,6 +3855,7 @@ paths:
               properties:
                 accountName:
                   type: string
               properties:
                 accountName:
                   type: string

+                  example: chocobozzz@example.org

                   description: account to block, in the form `username@domain`
               required:
                 - accountName
                   description: account to block, in the form `username@domain`
               required:
                 - accountName


@@ -2162,7 +3864,8 @@ paths:
           description: successful operation
         '409':
           description: self-blocking forbidden
           description: successful operation
         '409':
           description: self-blocking forbidden

-  '/blocklist/accounts/{accountName}':
+
+  '/server/blocklist/accounts/{accountName}':

     delete:
       tags:
         - Account Blocks
     delete:
       tags:
         - Account Blocks


@@ -2182,7 +3885,8 @@ paths:
           description: successful operation
         '404':
           description: account or account block does not exist
           description: successful operation
         '404':
           description: account or account block does not exist

-  /blocklist/servers:
+
+  /server/blocklist/servers:

     get:
       tags:
         - Server Blocks
     get:
       tags:
         - Server Blocks


@@ -2210,17 +3914,19 @@ paths:
             schema:
               type: object
               properties:
             schema:
               type: object
               properties:

-                accountName:
+                host:

                   type: string
                   type: string

+                  format: hostname

                   description: server domain to block
               required:
                   description: server domain to block
               required:

-                - accountName
+                - host

       responses:
       responses:

-        '200':
+        '204':

           description: successful operation
         '409':
           description: self-blocking forbidden
           description: successful operation
         '409':
           description: self-blocking forbidden

-  '/blocklist/servers/{host}':
+
+  '/server/blocklist/servers/{host}':

     delete:
       tags:
         - Server Blocks
     delete:
       tags:
         - Server Blocks


@@ -2235,21 +3941,138 @@ paths:
           description: server domain to unblock
           schema:
             type: string
           description: server domain to unblock
           schema:
             type: string

+            format: hostname

       responses:
       responses:

-        '201':
+        '204':

           description: successful operation
         '404':
           description: account block does not exist
           description: successful operation
         '404':
           description: account block does not exist

+
+  /server/redundancy/{host}:
+    put:
+      tags:
+        - Instance Redundancy
+      summary: Update a server redundancy policy
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - name: host
+          in: path
+          required: true
+          description: server domain to mirror
+          schema:
+            type: string
+            format: hostname
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                redundancyAllowed:
+                  type: boolean
+                  description: allow mirroring of the host's local videos
+              required:
+                - redundancyAllowed
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: server is not already known
+
+  /server/redundancy/videos:
+    get:
+      tags:
+        - Video Mirroring
+      summary: List videos being mirrored
+      operationId: getMirroredVideos
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - name: target
+          in: query
+          required: true
+          description: direction of the mirror
+          schema:
+            type: string
+            enum:
+              - my-videos
+              - remote-videos
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/videoRedundanciesSort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/VideoRedundancy'
+    post:
+      tags:
+        - Video Mirroring
+      summary: Mirror a video
+      operationId: putMirroredVideo
+      security:
+        - OAuth2:
+          - admin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                videoId:
+                  $ref: '#/components/schemas/Video/properties/id'
+              required:
+                - videoId
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: cannot mirror a local video
+        '404':
+          description: video does not exist
+        '409':
+          description: video is already mirrored
+
+  /server/redundancy/videos/{redundancyId}:
+    delete:
+      tags:
+        - Video Mirroring
+      summary: Delete a mirror done on a video
+      operationId: delMirroredVideo
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - name: redundancyId
+          in: path
+          required: true
+          description: id of an existing redundancy on a video
+          schema:
+            type: string
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video redundancy not found
+

   '/feeds/video-comments.{format}':
     get:
       tags:
         - Feeds
       summary: List comments on videos
   '/feeds/video-comments.{format}':
     get:
       tags:
         - Feeds
       summary: List comments on videos

+      operationId: getSyndicatedComments

       parameters:
         - name: format
           in: path
           required: true
       parameters:
         - name: format
           in: path
           required: true

-          description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'

           schema:
             type: string
             enum:
           schema:
             type: string
             enum:


@@ -2261,10 +4084,30 @@ paths:
               - json
               - json1
         - name: videoId
               - json
               - json1
         - name: videoId

-          in: path
+          in: query

           description: 'limit listing to a specific video'
           schema:
             type: string
           description: 'limit listing to a specific video'
           schema:
             type: string

+        - name: accountId
+          in: query
+          description: 'limit listing to a specific account'
+          schema:
+            type: string
+        - name: accountName
+          in: query
+          description: 'limit listing to a specific account'
+          schema:
+            type: string
+        - name: videoChannelId
+          in: query
+          description: 'limit listing to a specific video channel'
+          schema:
+            type: string
+        - name: videoChannelName
+          in: query
+          description: 'limit listing to a specific video channel'
+          schema:
+            type: string

       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation


@@ -2277,30 +4120,54 @@ paths:
             application/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
             application/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local

             application/rss+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
             application/rss+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local

             text/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
             text/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local

             application/atom+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
             application/atom+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local

             application/json:
               schema:
                 type: object
             application/json:
               schema:
                 type: object

+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
+        '400':
+          x-summary: field inconsistencies
+          description: >
+            Arises when:
+              - videoId filter is mixed with a channel filter
+        '404':
+          description: video, video channel or account not found

         '406':
           description: accept header unsupported
         '406':
           description: accept header unsupported

+

   '/feeds/videos.{format}':
     get:
       tags:
         - Feeds
       summary: List videos
   '/feeds/videos.{format}':
     get:
       tags:
         - Feeds
       summary: List videos

+      operationId: getSyndicatedVideos

       parameters:
         - name: format
           in: path
           required: true
       parameters:
         - name: format
           in: path
           required: true

-          description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'

           schema:
             type: string
             enum:
           schema:
             type: string
             enum:


@@ -2312,58 +4179,399 @@ paths:
               - json
               - json1
         - name: accountId
               - json
               - json1
         - name: accountId

-          in: path
+          in: query

           description: 'limit listing to a specific account'
           schema:
             type: string
         - name: accountName
           description: 'limit listing to a specific account'
           schema:
             type: string
         - name: accountName

-          in: path
+          in: query

           description: 'limit listing to a specific account'
           schema:
             type: string
         - name: videoChannelId
           description: 'limit listing to a specific account'
           schema:
             type: string
         - name: videoChannelId

-          in: path
+          in: query

           description: 'limit listing to a specific video channel'
           schema:
             type: string
         - name: videoChannelName
           description: 'limit listing to a specific video channel'
           schema:
             type: string
         - name: videoChannelName

-          in: path
+          in: query

           description: 'limit listing to a specific video channel'
           schema:
             type: string
           description: 'limit listing to a specific video channel'
           schema:
             type: string

+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
+      responses:
+        '204':
+          description: successful operation
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+                default: 'max-age=900' # 15 min cache
+          content:
+            application/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
+            application/rss+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
+            text/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
+            application/atom+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
+            application/json:
+              schema:
+                type: object
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
+        '404':
+          description: video channel or account not found
+        '406':
+          description: accept header unsupported
+
+  '/feeds/subscriptions.{format}':
+    get:
+      tags:
+        - Feeds
+        - Account
+      summary: List videos of subscriptions tied to a token
+      operationId: getSyndicatedSubscriptionVideos
+      parameters:
+        - name: format
+          in: path
+          required: true
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
+          schema:
+            type: string
+            enum:
+              - xml
+              - rss
+              - rss2
+              - atom
+              - atom1
+              - json
+              - json1
+        - name: accountId
+          in: query
+          description: limit listing to a specific account
+          schema:
+            type: string
+          required: true
+        - name: token
+          in: query
+          description: private token allowing access
+          schema:
+            type: string
+          required: true
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
+      responses:
+        '204':
+          description: successful operation
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+                default: 'max-age=900' # 15 min cache
+          content:
+            application/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/rss+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            text/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/atom+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/json:
+              schema:
+                type: object
+        '406':
+          description: accept header unsupported
+
+  /plugins:
+    get:
+      tags:
+        - Plugins
+      summary: List plugins
+      operationId: getPlugins
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - name: pluginType
+          in: query
+          schema:
+            type: integer
+        - name: uninstalled
+          in: query
+          schema:
+            type: boolean
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PluginResponse'
+
+  /plugins/available:
+    get:
+      tags:
+        - Plugins
+      summary: List available plugins
+      operationId: getAvailablePlugins
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - name: search
+          in: query
+          schema:
+            type: string
+        - name: pluginType
+          in: query
+          schema:
+            type: integer
+        - name: currentPeerTubeEngine
+          in: query
+          schema:
+            type: string
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PluginResponse'
+        '503':
+          description: plugin index unavailable
+
+  /plugins/install:
+    post:
+      tags:
+        - Plugins
+      summary: Install a plugin
+      operationId: addPlugin
+      security:
+        - OAuth2:
+          - admin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - type: object
+                  properties:
+                    npmName:
+                      type: string
+                      example: peertube-plugin-auth-ldap
+                  required:
+                    - npmName
+                  additionalProperties: false
+                - type: object
+                  properties:
+                    path:
+                      type: string
+                  required:
+                    - path
+                  additionalProperties: false
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: should have either `npmName` or `path` set
+
+  /plugins/update:
+    post:
+      tags:
+        - Plugins
+      summary: Update a plugin
+      operationId: updatePlugin
+      security:
+        - OAuth2:
+          - admin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              oneOf:
+                - type: object
+                  properties:
+                    npmName:
+                      type: string
+                      example: peertube-plugin-auth-ldap
+                  required:
+                    - npmName
+                  additionalProperties: false
+                - type: object
+                  properties:
+                    path:
+                      type: string
+                  required:
+                    - path
+                  additionalProperties: false
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: should have either `npmName` or `path` set
+        '404':
+          description: existing plugin not found
+
+  /plugins/uninstall:
+    post:
+      tags:
+        - Plugins
+      summary: Uninstall a plugin
+      operationId: uninstallPlugin
+      security:
+        - OAuth2:
+          - admin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                npmName:
+                  type: string
+                  description: name of the plugin/theme in its package.json
+                  example: peertube-plugin-auth-ldap
+              required:
+                - npmName
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: existing plugin not found
+
+  /plugins/{npmName}:
+    get:
+      tags:
+        - Plugins
+      summary: Get a plugin
+      operationId: getPlugin
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - $ref: '#/components/parameters/npmName'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Plugin'
+        '404':
+          description: plugin not found
+
+  /plugins/{npmName}/settings:
+    put:
+      tags:
+        - Plugins
+      summary: Set a plugin's settings
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - $ref: '#/components/parameters/npmName'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                settings:
+                  type: object
+                  additionalProperties: true
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: plugin not found
+
+  /plugins/{npmName}/public-settings:
+    get:
+      tags:
+        - Plugins
+      summary: Get a plugin's public settings
+      parameters:
+        - $ref: '#/components/parameters/npmName'

       responses:
       responses:

-        '204':
+        '200':

           description: successful operation
           description: successful operation

-          headers:
-            Cache-Control:
-              schema:
-                type: string
-                default: 'max-age=900' # 15 min cache

           content:
           content:

-            application/xml:
-              schema:
-                $ref: '#/components/schemas/VideosForXML'
-            application/rss+xml:
-              schema:
-                $ref: '#/components/schemas/VideosForXML'
-            text/xml:
-              schema:
-                $ref: '#/components/schemas/VideosForXML'
-            application/atom+xml:
+            application/json:

               schema:
               schema:

-                $ref: '#/components/schemas/VideosForXML'
+                type: object
+                additionalProperties: true
+        '404':
+          description: plugin not found
+
+  /plugins/{npmName}/registered-settings:
+    get:
+      tags:
+        - Plugins
+      summary: Get a plugin's registered settings
+      security:
+        - OAuth2:
+          - admin
+      parameters:
+        - $ref: '#/components/parameters/npmName'
+      responses:
+        '200':
+          description: successful operation
+          content:

             application/json:
               schema:
                 type: object
             application/json:
               schema:
                 type: object

-        '406':
-          description: accept header unsupported
+                additionalProperties: true
+        '404':
+          description: plugin not found
+

 servers:
 servers:

-  - url: 'https://peertube.cpy.re/api/v1'
-    description: Live Test Server (live data - stable version)

   - url: 'https://peertube2.cpy.re/api/v1'
   - url: 'https://peertube2.cpy.re/api/v1'

-    description: Live Test Server (live data - latest nighlty version)
+    description: Live Test Server (live data - latest nightly version)

   - url: 'https://peertube3.cpy.re/api/v1'
     description: Live Test Server (live data - latest RC version)
   - url: 'https://peertube3.cpy.re/api/v1'
     description: Live Test Server (live data - latest RC version)

+  - url: 'https://peertube.cpy.re/api/v1'
+    description: Live Test Server (live data - stable version)

 components:
   parameters:
     start:
 components:
   parameters:
     start:


@@ -2373,6 +4581,7 @@ components:
       description: Offset used to paginate results
       schema:
         type: integer
       description: Offset used to paginate results
       schema:
         type: integer

+        minimum: 0

     count:
       name: count
       in: query
     count:
       name: count
       in: query


@@ -2380,13 +4589,22 @@ components:
       description: "Number of items to return"
       schema:
         type: integer
       description: "Number of items to return"
       schema:
         type: integer

+        default: 15

         maximum: 100
         minimum: 1
     sort:
       name: sort
       in: query
       required: false
         maximum: 100
         minimum: 1
     sort:
       name: sort
       in: query
       required: false

-      description: Sort column (`-createdAt` for example)
+      description: Sort column
+      schema:
+        type: string
+        example: -createdAt
+    search:
+      name: search
+      in: query
+      required: false
+      description: Plain text search, applied to various parts of the model depending on endpoint

       schema:
         type: string
     searchTarget:
       schema:
         type: string
     searchTarget:


@@ -2398,11 +4616,11 @@ components:
 
 
         **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
 
 
         **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.

-        It means the instance may not know the objects you fetched. If you want to load video/channel information:
+        It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

           * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
           then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
           After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
           * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
           then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
           After that, you can use the classic REST API endpoints to fetch the complete object or interact with it

-          * If the current user has not the ability to make a remote URI search, then redirect the user on the origin instance or fetch
+          * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch

           the data from the origin instance API
       schema:
         type: string
           the data from the origin instance API
       schema:
         type: string


@@ -2417,13 +4635,14 @@ components:
       schema:
         type: string
         enum:
       schema:
         type: string
         enum:

-        - -name
+        - name

         - -duration
         - -createdAt
         - -publishedAt
         - -views
         - -likes
         - -trending
         - -duration
         - -createdAt
         - -publishedAt
         - -views
         - -likes
         - -trending

+        - -hot

     videosSearchSort:
       name: sort
       in: query
     videosSearchSort:
       name: sort
       in: query


@@ -2432,7 +4651,7 @@ components:
       schema:
         type: string
         enum:
       schema:
         type: string
         enum:

-        - -name
+        - name

         - -duration
         - -createdAt
         - -publishedAt
         - -duration
         - -createdAt
         - -publishedAt


@@ -2453,18 +4672,32 @@ components:
       name: sort
       in: query
       required: false
       name: sort
       in: query
       required: false

-      description: Sort blacklists by criteria
+      description: Sort blocklists by criteria

       schema:
         type: string
         enum:
         - -id
       schema:
         type: string
         enum:
         - -id

-        - -name
+        - name

         - -duration
         - -views
         - -likes
         - -dislikes
         - -uuid
         - -createdAt
         - -duration
         - -views
         - -likes
         - -dislikes
         - -uuid
         - -createdAt

+    usersSearch:
+      name: search
+      in: query
+      required: false
+      description: Plain text search that will match with user usernames or emails
+      schema:
+        type: string
+    usersBlocked:
+      name: blocked
+      in: query
+      required: false
+      description: Filter results down to (un)banned users
+      schema:
+        type: boolean

     usersSort:
       name: sort
       in: query
     usersSort:
       name: sort
       in: query


@@ -2487,64 +4720,100 @@ components:
         - -id
         - -createdAt
         - -state
         - -id
         - -createdAt
         - -state

+    videoRedundanciesSort:
+      name: sort
+      in: query
+      required: false
+      description: Sort abuses by criteria
+      schema:
+        type: string
+        enum:
+        - name
+    followersSort:
+      name: sort
+      in: query
+      required: false
+      description: Sort followers by criteria
+      schema:
+        type: string
+        enum:
+        - createdAt

     name:
       name: name
       in: path
       required: true
     name:
       name: name
       in: path
       required: true

-      description: >-
-        The name of the account (`chocobozzz` or `chocobozzz@example.org` for
-        example)
+      description: The username or handle of the account

       schema:
         type: string
       schema:
         type: string

+        example: chocobozzz | chocobozzz@example.org

     id:
       name: id
       in: path
       required: true
       description: The user id
       schema:
     id:
       name: id
       in: path
       required: true
       description: The user id
       schema:

-        type: integer
+        $ref: '#/components/schemas/id'

     idOrUUID:
       name: id
       in: path
       required: true
     idOrUUID:
       name: id
       in: path
       required: true

-      description: The object id or uuid
+      description: The object id, uuid or short uuid

       schema:
       schema:

-        type: string
+        oneOf:
+          - $ref: '#/components/schemas/id'
+          - $ref: '#/components/schemas/UUIDv4'
+          - $ref: '#/components/schemas/shortUUID'
+    playlistId:
+      name: playlistId
+      in: path
+      required: true
+      description: Playlist id
+      schema:
+        $ref: '#/components/schemas/VideoPlaylist/properties/id'

     playlistElementId:
       name: playlistElementId
       in: path
       required: true
       description: Playlist element id
       schema:
     playlistElementId:
       name: playlistElementId
       in: path
       required: true
       description: Playlist element id
       schema:

-        type: integer
+        $ref: '#/components/schemas/id'

     abuseId:
       name: abuseId
       in: path
       required: true
     abuseId:
       name: abuseId
       in: path
       required: true

-      description: Video abuse id
+      description: Abuse id

       schema:
       schema:

-        type: integer
+        $ref: '#/components/schemas/Abuse/properties/id'
+    abuseMessageId:
+      name: abuseMessageId
+      in: path
+      required: true
+      description: Abuse message id
+      schema:
+        $ref: '#/components/schemas/AbuseMessage/properties/id'

     captionLanguage:
       name: captionLanguage
       in: path
       required: true
       description: The caption language
       schema:
     captionLanguage:
       name: captionLanguage
       in: path
       required: true
       description: The caption language
       schema:

-        type: string
+        $ref: '#/components/schemas/VideoLanguageSet'

     channelHandle:
       name: channelHandle
       in: path
       required: true
     channelHandle:
       name: channelHandle
       in: path
       required: true

-      description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
+      description: The video channel handle

       schema:
         type: string
       schema:
         type: string

+        example: my_username | my_username@example.com

     subscriptionHandle:
       name: subscriptionHandle
       in: path
       required: true
     subscriptionHandle:
       name: subscriptionHandle
       in: path
       required: true

-      description: "The subscription handle (example: 'my_username@example.com' or 'my_username')"
+      description: The subscription handle

       schema:
         type: string
       schema:
         type: string

+        example: my_username | my_username@example.com

     threadId:
       name: threadId
       in: path
     threadId:
       name: threadId
       in: path


@@ -2558,18 +4827,25 @@ components:
       required: true
       description: The comment id
       schema:
       required: true
       description: The comment id
       schema:

-        type: integer
+        $ref: '#/components/schemas/VideoComment/properties/id'
+    isLive:
+      name: isLive
+      in: query
+      required: false
+      description: whether or not the video is a live
+      schema:
+        type: boolean

     categoryOneOf:
       name: categoryOneOf
       in: query
       required: false
     categoryOneOf:
       name: categoryOneOf
       in: query
       required: false

-      description: category id of the video (see /videos/categories)
+      description: category id of the video (see [/videos/categories](#operation/getCategories))

       schema:
         oneOf:
       schema:
         oneOf:

-        - type: integer
+        - $ref: '#/components/schemas/VideoCategorySet'

         - type: array
           items:
         - type: array
           items:

-            type: integer
+            $ref: '#/components/schemas/VideoCategorySet'

       style: form
       explode: false
     tagsOneOf:
       style: form
       explode: false
     tagsOneOf:


@@ -2581,6 +4857,7 @@ components:
         oneOf:
         - type: string
         - type: array
         oneOf:
         - type: string
         - type: array

+          maxItems: 5

           items:
             type: string
       style: form
           items:
             type: string
       style: form


@@ -2602,26 +4879,26 @@ components:
       name: languageOneOf
       in: query
       required: false
       name: languageOneOf
       in: query
       required: false

-      description: language id of the video (see /videos/languages). Use `_unknown` to filter on videos that don't have a video language
+      description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language

       schema:
         oneOf:
       schema:
         oneOf:

-        - type: string
+        - $ref: '#/components/schemas/VideoLanguageSet'

         - type: array
           items:
         - type: array
           items:

-            type: string
+            $ref: '#/components/schemas/VideoLanguageSet'

       style: form
       explode: false
     licenceOneOf:
       name: licenceOneOf
       in: query
       required: false
       style: form
       explode: false
     licenceOneOf:
       name: licenceOneOf
       in: query
       required: false

-      description: licence id of the video (see /videos/licences)
+      description: licence id of the video (see [/videos/licences](#operation/getLicences))

       schema:
         oneOf:
       schema:
         oneOf:

-        - type: integer
+        - $ref: '#/components/schemas/VideoLicenceSet'

         - type: array
           items:
         - type: array
           items:

-            type: integer
+            $ref: '#/components/schemas/VideoLicenceSet'

       style: form
       explode: false
     skipCount:
       style: form
       explode: false
     skipCount:


@@ -2645,19 +4922,58 @@ components:
         enum:
         - 'true'
         - 'false'
         enum:
         - 'true'
         - 'false'

-    filter:
-      name: filter
+    isLocal:
+      name: isLocal

       in: query
       required: false
       in: query
       required: false

-      description: >
-        Special filters (local for instance) which might require special rights:
-         * `local` - only videos local to the instance
-         * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)

       schema:
       schema:

-        type: string
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only local or remote videos'
+    hasHLSFiles:
+      name: hasHLSFiles
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only videos that have HLS files'
+    hasWebtorrentFiles:
+      name: hasWebtorrentFiles
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
+    privacyOneOf:
+      name: privacyOneOf
+      in: query
+      required: false
+      schema:
+        $ref: '#/components/schemas/VideoPrivacySet'
+      description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+    include:
+      name: include
+      in: query
+      required: false
+      schema:
+        type: integer

         enum:
         enum:

-        - local
-        - all-local
+        - 0
+        - 1
+        - 2
+        - 4
+        - 8
+      description: >
+        **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
+
+        - `0` NONE
+
+        - `1` NOT_PUBLISHED_STATE
+
+        - `2` BLACKLISTED
+
+        - `4` BLOCKED_OWNER
+
+        - `8` FILES

     subscriptionsUris:
       name: uris
       in: query
     subscriptionsUris:
       name: uris
       in: query


@@ -2667,42 +4983,147 @@ components:
         type: array
         items:
           type: string
         type: array
         items:
           type: string

+          format: uri
+    npmName:
+      name: npmName
+      in: path
+      required: true
+      description: name of the plugin/theme on npmjs.com or in its package.json
+      schema:
+        type: string
+        example: peertube-plugin-auth-ldap
+    jobType:
+      name: jobType
+      in: query
+      required: false
+      description: job type
+      schema:
+        type: string
+        enum:
+          - activitypub-follow
+          - activitypub-http-broadcast
+          - activitypub-http-fetcher
+          - activitypub-http-unicast
+          - email
+          - video-transcoding
+          - video-file-import
+          - video-import
+          - videos-views-stats
+          - activitypub-refresher
+          - video-redundancy
+          - video-live-ending
+    followState:
+      name: state
+      in: query
+      schema:
+        type: string
+        enum:
+          - pending
+          - accepted
+    actorType:
+      name: actorType
+      in: query
+      schema:
+        type: string
+        enum:
+          - Person
+          - Application
+          - Group
+          - Service
+          - Organization

   securitySchemes:
     OAuth2:
   securitySchemes:
     OAuth2:

-      description: >
-        In the header: *Authorization: Bearer <token\>*
-
-
+      description: |

         Authenticating via OAuth requires the following steps:
         Authenticating via OAuth requires the following steps:

+        - Have an activated account
+        - [Generate] an access token for that account at `/api/v1/users/token`.
+        - Make requests with the *Authorization: Bearer <token\>* header
+        - Profit, depending on the role assigned to the account

 
 

+        Note that the __access token is valid for 1 day__ and is given
+        along with a __refresh token valid for 2 weeks__.

 
 

-        - Have an account with sufficient authorization levels
-
-        - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
-        Bearer Token
-
-        - Make Authenticated Requests
+        [Generate]: https://docs.joinpeertube.org/api-rest-getting-started

       type: oauth2
       flows:
         password:
       type: oauth2
       flows:
         password:

-          tokenUrl: 'https://peertube.example.com/api/v1/users/token'
+          tokenUrl: /api/v1/users/token

           scopes:
             admin: Admin scope
             moderator: Moderator scope
             user: User scope
   schemas:
           scopes:
             admin: Admin scope
             moderator: Moderator scope
             user: User scope
   schemas:

-    VideoConstantNumber:
+    # Resuable core properties
+    id:
+      type: integer
+      minimum: 1
+      example: 42
+    UUIDv4:
+      type: string
+      format: uuid
+      example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+      minLength: 36
+      maxLength: 36
+    shortUUID:
+      type: string
+      description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
+      example: 2y84q2MQUMWPbiEcxNXMgC
+    username:
+      type: string
+      description: immutable name of the user, used to find or mention its actor
+      example: chocobozzz
+      pattern: '/^[a-z0-9._]+$/'
+      minLength: 1
+      maxLength: 50
+    usernameChannel:
+      type: string
+      description: immutable name of the channel, used to interact with its actor
+      example: framasoft_videos
+      pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
+      minLength: 1
+      maxLength: 50
+    password:
+      type: string
+      format: password
+      minLength: 6
+      maxLength: 255
+
+    VideoCategorySet:
+      type: integer
+      description: category id of the video (see [/videos/categories](#operation/getCategories))
+      example: 15
+    VideoConstantNumber-Category:

       properties:
         id:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/VideoCategorySet'

         label:
           type: string
         label:
           type: string

-    VideoConstantString:
+          example: Science & Technology
+
+    VideoLicenceSet:
+      type: integer
+      description: licence id of the video (see [/videos/licences](#operation/getLicences))
+      example: 2
+    VideoConstantNumber-Licence:

       properties:
         id:
       properties:
         id:

+          $ref: '#/components/schemas/VideoLicenceSet'
+        label:

           type: string
           type: string

+          example: Attribution - Share Alike
+
+    VideoLanguageSet:
+      type: string
+      description: language id of the video (see [/videos/languages](#operation/getLanguages))
+      example: en
+    VideoConstantString-Language:
+      properties:
+        id:
+          $ref: '#/components/schemas/VideoLanguageSet'

         label:
           type: string
         label:
           type: string

+          example: English

 
     VideoPlaylistPrivacySet:
       type: integer
 
     VideoPlaylistPrivacySet:
       type: integer


@@ -2710,7 +5131,7 @@ components:
         - 1
         - 2
         - 3
         - 1
         - 2
         - 3

-      description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
+      description: Video playlist privacy policy (see [/video-playlists/privacies])

     VideoPlaylistPrivacyConstant:
       properties:
         id:
     VideoPlaylistPrivacyConstant:
       properties:
         id:


@@ -2723,7 +5144,7 @@ components:
       enum:
         - 1
         - 2
       enum:
         - 1
         - 2

-      description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
+      description: The video playlist type (Regular = `1`, Watch Later = `2`)

     VideoPlaylistTypeConstant:
       properties:
         id:
     VideoPlaylistTypeConstant:
       properties:
         id:


@@ -2738,7 +5159,7 @@ components:
         - 2
         - 3
         - 4
         - 2
         - 3
         - 4

-      description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
+      description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))

     VideoPrivacyConstant:
       properties:
         id:
     VideoPrivacyConstant:
       properties:
         id:


@@ -2746,6 +5167,29 @@ components:
         label:
           type: string
 
         label:
           type: string
 

+    BlockStatus:
+      properties:
+        accounts:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: account
+            type: object
+            properties:
+              blockedByServer:
+                type: boolean
+              blockedByUser:
+                type: boolean
+        hosts:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: host
+            type: object
+            properties:
+              blockedByServer:
+                type: boolean
+              blockedByUser:
+                type: boolean
+

     NSFWPolicy:
       type: string
       enum:
     NSFWPolicy:
       type: string
       enum:


@@ -2760,6 +5204,14 @@ components:
         - 1
         - 2
       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
         - 1
         - 2
       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'

+      example: 2
+    UserAdminFlags:
+      type: integer
+      enum:
+        - 0
+        - 1
+      description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
+      example: 1

 
     VideoStateConstant:
       properties:
 
     VideoStateConstant:
       properties:


@@ -2773,20 +5225,20 @@ components:
         label:
           type: string
 
         label:
           type: string
 

-    VideoAbuseStateSet:
+    AbuseStateSet:

       type: integer
       enum:
         - 1
         - 2
         - 3
       type: integer
       enum:
         - 1
         - 2
         - 3

-      description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
-    VideoAbuseStateConstant:
+      description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+    AbuseStateConstant:

       properties:
         id:
       properties:
         id:

-          $ref: '#/components/schemas/VideoAbuseStateSet'
+          $ref: '#/components/schemas/AbuseStateSet'

         label:
           type: string
         label:
           type: string

-    VideoAbusePredefinedReasons:
+    AbusePredefinedReasons:

       type: array
       items:
         type: string
       type: array
       items:
         type: string


@@ -2799,14 +5251,23 @@ components:
         - serverRules
         - thumbnails
         - captions
         - serverRules
         - thumbnails
         - captions

+      example: [spamOrMisleading]
+
+    VideoResolutionSet:
+      type: integer
+      description: |
+        Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)

 
 

+        `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
+      example: 240

     VideoResolutionConstant:
     VideoResolutionConstant:

+      description: resolutions and their labels for the video

       properties:
         id:
       properties:
         id:

-          type: integer
-          description: 'Video resolution (240, 360, 720 ...)'
+          $ref: '#/components/schemas/VideoResolutionSet'

         label:
           type: string
         label:
           type: string

+          example: 240p

     VideoScheduledUpdate:
       properties:
         privacy:
     VideoScheduledUpdate:
       properties:
         privacy:


@@ -2827,76 +5288,110 @@ components:
           type: string
         url:
           type: string
           type: string
         url:
           type: string

+          format: url

         host:
           type: string
         host:
           type: string

+          format: hostname

         avatar:
           nullable: true
           allOf:
         avatar:
           nullable: true
           allOf:

-            - $ref: '#/components/schemas/Avatar'
+            - $ref: '#/components/schemas/ActorImage'

     VideoChannelSummary:
       properties:
         id:
     VideoChannelSummary:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         name:
           type: string
         displayName:
           type: string
         url:
           type: string
         name:
           type: string
         displayName:
           type: string
         url:
           type: string

+          format: url

         host:
           type: string
         host:
           type: string

+          format: hostname

         avatar:
           nullable: true
           allOf:
         avatar:
           nullable: true
           allOf:

-            - $ref: '#/components/schemas/Avatar'
+            - $ref: '#/components/schemas/ActorImage'

     PlaylistElement:
       properties:
         position:
           type: integer
         startTimestamp:
           type: integer
     PlaylistElement:
       properties:
         position:
           type: integer
         startTimestamp:
           type: integer

+          format: seconds

         stopTimestamp:
           type: integer
         stopTimestamp:
           type: integer

+          format: seconds

         video:
           nullable: true
           allOf:
             - $ref: '#/components/schemas/Video'
     VideoFile:
         video:
           nullable: true
           allOf:
             - $ref: '#/components/schemas/Video'
     VideoFile:

+      readOnly: true

       properties:
         magnetUri:
           type: string
       properties:
         magnetUri:
           type: string

+          format: uri
+          description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
+          pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i

         resolution:
           $ref: '#/components/schemas/VideoResolutionConstant'
         size:
           type: integer
         resolution:
           $ref: '#/components/schemas/VideoResolutionConstant'
         size:
           type: integer

-          description: 'Video file size in bytes'
+          description: Video file size in bytes

         torrentUrl:
           type: string
         torrentUrl:
           type: string

+          description: Direct URL of the torrent file
+          format: url

         torrentDownloadUrl:
           type: string
         torrentDownloadUrl:
           type: string

+          description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
+          format: url

         fileUrl:
           type: string
         fileUrl:
           type: string

+          description: Direct URL of the video
+          format: url

         fileDownloadUrl:
           type: string
         fileDownloadUrl:
           type: string

+          description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
+          format: url

         fps:
           type: number
         fps:
           type: number

+          description: Frames per second of the video file

         metadataUrl:
           type: string
         metadataUrl:
           type: string

+          format: url
+          description: URL dereferencing the output of ffprobe on the file

     VideoStreamingPlaylists:
     VideoStreamingPlaylists:

+      allOf:
+        - type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            type:
+              type: integer
+              enum:
+                - 1
+              description: |
+                Playlist type:
+                - `1`: HLS
+        - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
+    VideoStreamingPlaylists-HLS:

       properties:
       properties:

-        id:
-          type: integer
-        type:
-          type: integer
-          enum:
-            - 1
-          description: 'Playlist type (HLS = `1`)'

         playlistUrl:
           type: string
         playlistUrl:
           type: string

+          format: url

         segmentsSha256Url:
           type: string
         segmentsSha256Url:
           type: string

+          format: url

         files:
           type: array
         files:
           type: array

+          description: |
+            Video files associated to this playlist.
+
+            The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)

           items:
             $ref: '#/components/schemas/VideoFile'
         redundancies:
           items:
             $ref: '#/components/schemas/VideoFile'
         redundancies:


@@ -2906,55 +5401,116 @@ components:
             properties:
               baseUrl:
                 type: string
             properties:
               baseUrl:
                 type: string

+                format: url
+    VideoInfo:
+      properties:
+        id:
+          $ref: '#/components/schemas/Video/properties/id'
+        uuid:
+          $ref: '#/components/schemas/Video/properties/uuid'
+        name:
+          $ref: '#/components/schemas/Video/properties/name'

     Video:
       properties:
         id:
     Video:
       properties:
         id:

-          type: integer
+          description: object id for the video
+          allOf:
+            - $ref: '#/components/schemas/id'

         uuid:
         uuid:

-          type: string
+          description: universal identifier for the video, that can be used across instances
+          allOf:
+            - $ref: '#/components/schemas/UUIDv4'
+        shortUUID:
+          allOf:
+            - $ref: '#/components/schemas/shortUUID'
+        isLive:
+          type: boolean

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time
+          example: 2017-10-01T10:52:46.396Z
+          description: time at which the video object was first drafted

         publishedAt:
           type: string
         publishedAt:
           type: string

+          format: date-time
+          example: 2018-10-01T10:52:46.396Z
+          description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time
+          example: 2021-05-04T08:01:01.502Z
+          description: last time the video's metadata was modified

         originallyPublishedAt:
           type: string
         originallyPublishedAt:
           type: string

+          format: date-time
+          example: 2010-10-01T10:52:46.396Z
+          description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`

         category:
         category:

-          $ref: '#/components/schemas/VideoConstantNumber'
+          allOf:
+            - $ref: '#/components/schemas/VideoConstantNumber-Category'
+          description: category in which the video is classified

         licence:
         licence:

-          $ref: '#/components/schemas/VideoConstantNumber'
+          allOf:
+            - $ref: '#/components/schemas/VideoConstantNumber-Licence'
+          description: licence under which the video is distributed

         language:
         language:

-          $ref: '#/components/schemas/VideoConstantString'
+          allOf:
+            - $ref: '#/components/schemas/VideoConstantString-Language'
+          description: main language used in the video

         privacy:
         privacy:

-          $ref: '#/components/schemas/VideoPrivacyConstant'
+          allOf:
+            - $ref: '#/components/schemas/VideoPrivacyConstant'
+          description: privacy policy used to distribute the video

         description:
           type: string
         description:
           type: string

+          example: |
+            **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
+            **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
+          minLength: 3
+          maxLength: 250
+          description: |
+            truncated description of the video, written in Markdown.
+            Resolve `descriptionPath` to get the full description of maximum `10000` characters.

         duration:
           type: integer
         duration:
           type: integer

+          example: 1419
+          format: seconds
+          description: duration of the video in seconds

         isLocal:
           type: boolean
         name:
           type: string
         isLocal:
           type: boolean
         name:
           type: string

+          description: title of the video
+          example: What is PeerTube?
+          minLength: 3
+          maxLength: 120

         thumbnailPath:
           type: string
         thumbnailPath:
           type: string

+          example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg

         previewPath:
           type: string
         previewPath:
           type: string

+          example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg

         embedPath:
           type: string
         embedPath:
           type: string

+          example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee

         views:
           type: integer
         views:
           type: integer

+          example: 1337

         likes:
           type: integer
         likes:
           type: integer

+          example: 42

         dislikes:
           type: integer
         dislikes:
           type: integer

+          example: 7

         nsfw:
           type: boolean
         waitTranscoding:
           type: boolean
           nullable: true
         state:
         nsfw:
           type: boolean
         waitTranscoding:
           type: boolean
           nullable: true
         state:

-          $ref: '#/components/schemas/VideoStateConstant'
+          allOf:
+            - $ref: '#/components/schemas/VideoStateConstant'
+          description: represents the internal state of the video processing within the PeerTube instance

         scheduledUpdate:
           nullable: true
           allOf:
         scheduledUpdate:
           nullable: true
           allOf:


@@ -2980,22 +5536,32 @@ components:
         - $ref: '#/components/schemas/Video'
         - type: object
           properties:
         - $ref: '#/components/schemas/Video'
         - type: object
           properties:

+            viewers:
+              type: integer
+              description: If the video is a live, you have the amount of current viewers

             descriptionPath:
               type: string
             descriptionPath:
               type: string

+              example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
+              description: path at which to get the full description of maximum `10000` characters

             support:
               type: string
             support:
               type: string

+              description: A text tell the audience how to support the video creator
+              example: Please support our work on https://soutenir.framasoft.org/en/ <3
+              minLength: 3
+              maxLength: 1000

             channel:
               $ref: '#/components/schemas/VideoChannel'
             account:
               $ref: '#/components/schemas/Account'
             tags:
             channel:
               $ref: '#/components/schemas/VideoChannel'
             account:
               $ref: '#/components/schemas/Account'
             tags:

+              example: [flowers, gardening]

               type: array
               type: array

+              minItems: 1
+              maxItems: 5

               items:
                 type: string
               items:
                 type: string

-            files:
-              type: array
-              items:
-                $ref: '#/components/schemas/VideoFile'
+                minLength: 2
+                maxLength: 30

             commentsEnabled:
               type: boolean
             downloadEnabled:
             commentsEnabled:
               type: boolean
             downloadEnabled:


@@ -3004,10 +5570,75 @@ components:
               type: array
               items:
                 type: string
               type: array
               items:
                 type: string

+                format: url
+              example:
+                - https://peertube2.cpy.re/tracker/announce
+                - wss://peertube2.cpy.re/tracker/socket
+            files:
+              type: array
+              items:
+                $ref: '#/components/schemas/VideoFile'
+              description: |
+                WebTorrent/raw video files. If WebTorrent is disabled on the server:
+
+                - field will be empty
+                - video files will be found in `streamingPlaylists[].files` field

             streamingPlaylists:
               type: array
               items:
                 $ref: '#/components/schemas/VideoStreamingPlaylists'
             streamingPlaylists:
               type: array
               items:
                 $ref: '#/components/schemas/VideoStreamingPlaylists'

+              description: |
+                HLS playlists/manifest files. If HLS is disabled on the server:
+
+                - field will be empty
+                - video files will be found in `files` field
+    FileRedundancyInformation:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        fileUrl:
+          type: string
+          format: url
+        strategy:
+          type: string
+          enum:
+            - manual
+            - most-views
+            - trending
+            - recently-added
+        size:
+          type: integer
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        expiresOn:
+          type: string
+          format: date-time
+    VideoRedundancy:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        name:
+          type: string
+        url:
+          type: string
+          format: url
+        uuid:
+          $ref: '#/components/schemas/UUIDv4'
+        redundancies:
+          type: object
+          properties:
+            files:
+              type: array
+              items:
+                $ref: '#/components/schemas/FileRedundancyInformation'
+            streamingPlaylists:
+              type: array
+              items:
+                $ref: '#/components/schemas/FileRedundancyInformation'

     VideoImportStateConstant:
       properties:
         id:
     VideoImportStateConstant:
       properties:
         id:


@@ -3019,72 +5650,144 @@ components:
           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
         label:
           type: string
           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
         label:
           type: string

+          example: Pending
+    VideoCreateImport:
+      allOf:
+        - type: object
+          additionalProperties: false
+          oneOf:
+            - properties:
+                targetUrl:
+                  $ref: '#/components/schemas/VideoImport/properties/targetUrl'
+              required: [targetUrl]
+            - properties:
+                magnetUri:
+                  $ref: '#/components/schemas/VideoImport/properties/magnetUri'
+              required: [magnetUri]
+            - properties:
+                torrentfile:
+                  $ref: '#/components/schemas/VideoImport/properties/torrentfile'
+              required: [torrentfile]
+        - $ref: '#/components/schemas/VideoUploadRequestCommon'
+      required:
+        - channelId
+        - name

     VideoImport:
       properties:
         id:
     VideoImport:
       properties:
         id:

-          type: integer
+          readOnly: true
+          allOf:
+            - $ref: '#/components/schemas/id'

         targetUrl:
           type: string
         targetUrl:
           type: string

+          format: url
+          description: remote URL where to find the import's source video
+          example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d

         magnetUri:
           type: string
         magnetUri:
           type: string

+          format: uri
+          description: magnet URI allowing to resolve the import's source video
+          pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
+        torrentfile:
+          writeOnly: true
+          type: string
+          format: binary
+          description: Torrent file containing only the video file

         torrentName:
         torrentName:

+          readOnly: true

           type: string
         state:
           type: string
         state:

-          type: object
-          properties:
-            id:
-              $ref: '#/components/schemas/VideoImportStateConstant'
-            label:
-              type: string
+          readOnly: true
+          allOf:
+            - $ref: '#/components/schemas/VideoImportStateConstant'

         error:
         error:

+          readOnly: true

           type: string
         createdAt:
           type: string
         createdAt:

+          readOnly: true

           type: string
           type: string

+          format: date-time

         updatedAt:
         updatedAt:

+          readOnly: true

           type: string
           type: string

+          format: date-time

         video:
         video:

-          $ref: '#/components/schemas/Video'
-    VideoAbuse:
+          readOnly: true
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/Video'
+    VideoImportsList:

       properties:
       properties:

-        id:
+        total:

           type: integer
           type: integer

+          example: 1
+        data:
+          type: array
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/VideoImport'
+    Abuse:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'

         reason:
           type: string
         reason:
           type: string

+          example: The video is a spam
+          minLength: 2
+          maxLength: 3000

         predefinedReasons:
         predefinedReasons:

-          $ref: '#/components/schemas/VideoAbusePredefinedReasons'
+          $ref: '#/components/schemas/AbusePredefinedReasons'

         reporterAccount:
           $ref: '#/components/schemas/Account'
         state:
         reporterAccount:
           $ref: '#/components/schemas/Account'
         state:

-          $ref: '#/components/schemas/VideoAbuseStateConstant'
+          $ref: '#/components/schemas/AbuseStateConstant'

         moderationComment:
           type: string
         moderationComment:
           type: string

+          example: Decided to ban the server since it spams us regularly
+          minLength: 2
+          maxLength: 3000

         video:
         video:

-          type: object
-          properties:
-            id:
-              type: integer
-            name:
-              type: string
-            uuid:
-              type: string
+          $ref: '#/components/schemas/VideoInfo'

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time
+    AbuseMessage:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        message:
+          type: string
+          minLength: 2
+          maxLength: 3000
+        byModerator:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        account:
+          $ref: '#/components/schemas/AccountSummary'

     VideoBlacklist:
       properties:
         id:
     VideoBlacklist:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         videoId:
         videoId:

-          type: integer
+          $ref: '#/components/schemas/Video/properties/id'

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time

         name:
           type: string
         name:
           type: string

+          minLength: 3
+          maxLength: 120

         uuid:
         uuid:

-          type: string
+          $ref: '#/components/schemas/UUIDv4'

         description:
           type: string
         description:
           type: string

+          minLength: 3
+          maxLength: 10000

         duration:
           type: integer
         views:
         duration:
           type: integer
         views:


@@ -3095,39 +5798,34 @@ components:
           type: integer
         nsfw:
           type: boolean
           type: integer
         nsfw:
           type: boolean

-    VideoChannel:
-      properties:
-        displayName:
-          type: string
-        description:
-          type: string
-        isLocal:
-          type: boolean
-        ownerAccount:
-          type: object
-          properties:
-            id:
-              type: integer
-            uuid:
-              type: string

     VideoPlaylist:
       properties:
         id:
     VideoPlaylist:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'
+        uuid:
+          $ref: '#/components/schemas/UUIDv4'
+        shortUUID:
+          allOf:
+            - $ref: '#/components/schemas/shortUUID'

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time

         description:
           type: string
         description:
           type: string

-        uuid:
-          type: string
+          minLength: 3
+          maxLength: 1000

         displayName:
           type: string
         displayName:
           type: string

+          minLength: 1
+          maxLength: 120

         isLocal:
           type: boolean
         videoLength:
           type: integer
         isLocal:
           type: boolean
         videoLength:
           type: integer

+          minimum: 0

         thumbnailPath:
           type: string
         privacy:
         thumbnailPath:
           type: string
         privacy:


@@ -3141,25 +5839,44 @@ components:
     VideoComment:
       properties:
         id:
     VideoComment:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         url:
           type: string
         url:
           type: string

+          format: url

         text:
           type: string
         text:
           type: string

+          format: html
+          description: Text of the comment
+          minLength: 1
+          example: This video is wonderful!

         threadId:
         threadId:

-          type: integer
+          $ref: '#/components/schemas/id'

         inReplyToCommentId:
         inReplyToCommentId:

-          type: integer
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/id'

         videoId:
         videoId:

-          type: integer
+          $ref: '#/components/schemas/Video/properties/id'

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time
+        deletedAt:
+          nullable: true
+          type: string
+          format: date-time
+          default: null
+        isDeleted:
+          type: boolean
+          default: false

         totalRepliesFromVideoAuthor:
           type: integer
         totalRepliesFromVideoAuthor:
           type: integer

+          minimum: 0

         totalReplies:
           type: integer
         totalReplies:
           type: integer

+          minimum: 0

         account:
           $ref: '#/components/schemas/Account'
     VideoCommentThreadTree:
         account:
           $ref: '#/components/schemas/Account'
     VideoCommentThreadTree:


@@ -3173,110 +5890,93 @@ components:
     VideoCaption:
       properties:
         language:
     VideoCaption:
       properties:
         language:

-          $ref: '#/components/schemas/VideoConstantString'
+          $ref: '#/components/schemas/VideoConstantString-Language'

         captionPath:
           type: string
         captionPath:
           type: string

-    Avatar:
+    ActorImage:

       properties:
         path:
           type: string
         createdAt:
           type: string
       properties:
         path:
           type: string
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time
+    ActorInfo:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        name:
+          type: string
+        displayName:
+          type: string
+        host:
+          type: string
+          format: hostname
+        avatar:
+          nullable: true
+          type: object
+          properties:
+            path:
+              type: string

     Actor:
       properties:
         id:
     Actor:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         url:
           type: string
         url:
           type: string

+          format: url

         name:
         name:

-          type: string
+          description: immutable name of the actor, used to find or mention it
+          allOf:
+            - $ref: '#/components/schemas/username'

         host:
           type: string
         host:
           type: string

+          format: hostname
+          description: server on which the actor is resident
+        hostRedundancyAllowed:
+          type: boolean
+          description: whether this actor's host allows redundancy of its videos

         followingCount:
           type: integer
         followingCount:
           type: integer

+          minimum: 0
+          description: number of actors subscribed to by this actor, as seen by this instance

         followersCount:
           type: integer
         followersCount:
           type: integer

+          minimum: 0
+          description: number of followers of this actor, as seen by this instance

         createdAt:
           type: string
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time

         avatar:
         avatar:

-          $ref: '#/components/schemas/Avatar'
+          $ref: '#/components/schemas/ActorImage'

     Account:
       allOf:
         - $ref: '#/components/schemas/Actor'
         - properties:
             userId:
     Account:
       allOf:
         - $ref: '#/components/schemas/Actor'
         - properties:
             userId:

-              type: string
+              description: object id for the user tied to this account
+              allOf:
+                - $ref: '#/components/schemas/User/properties/id'

             displayName:
               type: string
             displayName:
               type: string

+              description: editable name of the account, displayed in its representations
+              minLength: 3
+              maxLength: 120

             description:
               type: string
             description:
               type: string

-    User:
-      properties:
-        id:
-          type: integer
-        username:
-          type: string
-        email:
-          type: string
-        theme:
-          type: string
-          description: 'Theme enabled by this user'
-        emailVerified:
-          type: boolean
-          description: 'Has the user confirmed their email address?'
-        nsfwPolicy:
-          $ref: '#/components/schemas/NSFWPolicy'
-        webtorrentEnabled:
-          type: boolean
-        autoPlayVideo:
-          type: boolean
-          description: 'Automatically start playing the video on the watch page'
-        role:
-          $ref: '#/components/schemas/UserRole'
-        roleLabel:
-          type: string
-          enum:
-            - User
-            - Moderator
-            - Administrator
-        videoQuota:
-          type: integer
-        videoQuotaDaily:
-          type: integer
-        videosCount:
-          type: integer
-        videoAbusesCount:
-          type: integer
-        videoAbusesAcceptedCount:
-          type: integer
-        videoAbusesCreatedCount:
-          type: integer
-        videoCommentsCount:
-          type: integer
-        noInstanceConfigWarningModal:
-          type: boolean
-        noWelcomeModal:
-          type: boolean
-        blocked:
-          type: boolean
-        blockedReason:
-          type: string
-        createdAt:
-          type: string
-        account:
-          $ref: '#/components/schemas/Account'
-        videoChannels:
-          type: array
-          items:
-            $ref: '#/components/schemas/VideoChannel'
+              description: text or bio displayed on the account's profile

     UserWatchingVideo:
       properties:
         currentTime:
           type: integer
     UserWatchingVideo:
       properties:
         currentTime:
           type: integer

+          format: seconds
+          description: timestamp within the video, in seconds
+          example: 5

     ServerConfig:
       properties:
         instance:
     ServerConfig:
       properties:
         instance:


@@ -3362,7 +6062,7 @@ components:
             enabledResolutions:
               type: array
               items:
             enabledResolutions:
               type: array
               items:

-                type: integer
+                $ref: '#/components/schemas/VideoResolutionSet'

         import:
           type: object
           properties:
         import:
           type: object
           properties:


@@ -3447,8 +6147,10 @@ components:
           properties:
             videoQuota:
               type: integer
           properties:
             videoQuota:
               type: integer

+              example: 16810141515

             videoQuotaDaily:
               type: integer
             videoQuotaDaily:
               type: integer

+              example: 1681014151

         trending:
           type: object
           properties:
         trending:
           type: object
           properties:


@@ -3473,6 +6175,13 @@ components:
                   properties:
                     indexUrl:
                       type: string
                   properties:
                     indexUrl:
                       type: string

+                      format: url
+        homepage:
+          type: object
+          properties:
+            enabled:
+              type: boolean
+

     ServerConfigAbout:
       properties:
         instance:
     ServerConfigAbout:
       properties:
         instance:


@@ -3554,6 +6263,7 @@ components:
           properties:
             email:
               type: string
           properties:
             email:
               type: string

+              format: email

         contactForm:
           type: object
           properties:
         contactForm:
           type: object
           properties:


@@ -3561,25 +6271,46 @@ components:
               type: boolean
         user:
           type: object
               type: boolean
         user:
           type: object

+          description: Settings that apply to new users, if registration is enabled

           properties:
             videoQuota:
               type: integer
           properties:
             videoQuota:
               type: integer

+              example: 16810141515

             videoQuotaDaily:
               type: integer
             videoQuotaDaily:
               type: integer

+              example: 1681014151

         transcoding:
           type: object
         transcoding:
           type: object

+          description: Settings pertaining to transcoding jobs

           properties:
             enabled:
               type: boolean
             allowAdditionalExtensions:
               type: boolean
           properties:
             enabled:
               type: boolean
             allowAdditionalExtensions:
               type: boolean

+              description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos

             allowAudioFiles:
               type: boolean
             allowAudioFiles:
               type: boolean

+              description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file

             threads:
               type: integer
             threads:
               type: integer

+              description: Amount of threads used by ffmpeg for 1 transcoding job
+            concurrency:
+              type: number
+              description: Amount of transcoding jobs to execute in parallel
+            profile:
+              type: string
+              enum:
+                - default
+              description: |
+                New profiles can be added by plugins ; available in core PeerTube: 'default'.

             resolutions:
               type: object
             resolutions:
               type: object

+              description: Resolutions to transcode _new videos_ to

               properties:
               properties:

+                0p:
+                  type: boolean
+                144p:
+                  type: boolean

                 240p:
                   type: boolean
                 360p:
                 240p:
                   type: boolean
                 360p:


@@ -3590,10 +6321,19 @@ components:
                   type: boolean
                 1080p:
                   type: boolean
                   type: boolean
                 1080p:
                   type: boolean

+                1440p:
+                  type: boolean

                 2160p:
                   type: boolean
                 2160p:
                   type: boolean

+            webtorrent:
+              type: object
+              description: WebTorrent-specific settings
+              properties:
+                enabled:
+                  type: boolean

             hls:
               type: object
             hls:
               type: object

+              description: HLS-specific settings

               properties:
                 enabled:
                   type: boolean
               properties:
                 enabled:
                   type: boolean


@@ -3634,16 +6374,23 @@ components:
                   type: boolean
                 manualApproval:
                   type: boolean
                   type: boolean
                 manualApproval:
                   type: boolean

+
+    CustomHomepage:
+      properties:
+        content:
+          type: string
+

     Follow:
       properties:
         id:
     Follow:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         follower:
           $ref: '#/components/schemas/Actor'
         following:
           $ref: '#/components/schemas/Actor'
         score:
           type: number
         follower:
           $ref: '#/components/schemas/Actor'
         following:
           $ref: '#/components/schemas/Actor'
         score:
           type: number

+          description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.

         state:
           type: string
           enum:
         state:
           type: string
           enum:


@@ -3651,53 +6398,202 @@ components:
             - accepted
         createdAt:
           type: string
             - accepted
         createdAt:
           type: string

+          format: date-time

         updatedAt:
           type: string
         updatedAt:
           type: string

+          format: date-time
+
+    PredefinedAbuseReasons:
+      description: Reason categories that help triage reports
+      type: array
+      maxItems: 8
+      items:
+        type: string
+        enum:
+        - violentOrAbusive
+        - hatefulOrAbusive
+        - spamOrMisleading
+        - privacy
+        - rights
+        - serverRules
+        - thumbnails
+        - captions
+

     Job:
       properties:
         id:
     Job:
       properties:
         id:

-          type: integer
+          $ref: '#/components/schemas/id'

         state:
           type: string
           enum:
         state:
           type: string
           enum:

-            - pending
-            - processing
-            - error
-            - success
-        category:
+            - active
+            - completed
+            - failed
+            - waiting
+            - delayed
+        type:

           type: string
           enum:
           type: string
           enum:

-            - transcoding
-            - activitypub-http
-        handlerName:
-          type: string
-        handlerInputData:
-          type: string
+            - activitypub-http-unicast
+            - activitypub-http-broadcast
+            - activitypub-http-fetcher
+            - activitypub-follow
+            - video-file-import
+            - video-transcoding
+            - email
+            - video-import
+            - videos-views-stats
+            - activitypub-refresher
+            - video-redundancy
+        data:
+          type: object
+          additionalProperties: true
+        error:
+          type: object
+          additionalProperties: true

         createdAt:
           type: string
         createdAt:
           type: string

-        updatedAt:
+          format: date-time
+        finishedOn:

           type: string
           type: string

+          format: date-time
+        processedOn:
+          type: string
+          format: date-time

     AddUserResponse:
       properties:
     AddUserResponse:
       properties:

-        id:
+        user:
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            account:
+              type: object
+              properties:
+                id:
+                  $ref: '#/components/schemas/id'
+    VideoUploadRequestCommon:
+      properties:
+        name:
+          description: Video name
+          type: string
+          example: What is PeerTube?
+          minLength: 3
+          maxLength: 120
+        channelId:
+          description: Channel id that will contain this video

           type: integer
           type: integer

-        uuid:
+          example: 3
+          minimum: 1
+        privacy:
+          $ref: '#/components/schemas/VideoPrivacySet'
+        category:
+          $ref: '#/components/schemas/VideoCategorySet'
+        licence:
+          $ref: '#/components/schemas/VideoLicenceSet'
+        language:
+          $ref: '#/components/schemas/VideoLanguageSet'
+        description:
+          description: Video description
+          type: string
+          example: |
+            **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
+        waitTranscoding:
+          description: Whether or not we wait transcoding before publish the video
+          type: boolean
+        support:
+          description: A text tell the audience how to support the video creator
+          example: Please support our work on https://soutenir.framasoft.org/en/ <3
+          type: string
+        nsfw:
+          description: Whether or not this video contains sensitive content
+          type: boolean
+        tags:
+          description: Video tags (maximum 5 tags each between 2 and 30 characters)
+          type: array
+          minItems: 1
+          maxItems: 5
+          uniqueItems: true
+          example:
+            - framasoft
+            - peertube
+          items:
+            type: string
+            minLength: 2
+            maxLength: 30
+        commentsEnabled:
+          description: Enable or disable comments for this video
+          type: boolean
+        downloadEnabled:
+          description: Enable or disable downloading for this video
+          type: boolean
+        originallyPublishedAt:
+          description: Date when the content was originally published

           type: string
           type: string

+          format: date-time
+        scheduleUpdate:
+          $ref: '#/components/schemas/VideoScheduledUpdate'
+        thumbnailfile:
+          description: Video thumbnail file
+          type: string
+          format: binary
+        previewfile:
+          description: Video preview file
+          type: string
+          format: binary
+      required:
+        - channelId
+        - name
+    VideoUploadRequestLegacy:
+      allOf:
+        - $ref: '#/components/schemas/VideoUploadRequestCommon'
+        - type: object
+          required:
+            - videofile
+          properties:
+            videofile:
+              description: Video file
+              type: string
+              format: binary
+    VideoUploadRequestResumable:
+      allOf:
+        - $ref: '#/components/schemas/VideoUploadRequestCommon'
+        - type: object
+          required:
+            - filename
+          properties:
+            filename:
+              description: Video filename including extension
+              type: string
+              format: filename
+              example: what_is_peertube.mp4
+            thumbnailfile:
+              description: Video thumbnail file
+              type: string
+              format: binary
+            previewfile:
+              description: Video preview file
+              type: string
+              format: binary

     VideoUploadResponse:
       properties:
         video:
           type: object
           properties:
             id:
     VideoUploadResponse:
       properties:
         video:
           type: object
           properties:
             id:

-              type: integer
+              $ref: '#/components/schemas/Video/properties/id'

             uuid:
             uuid:

-              type: string
+              $ref: '#/components/schemas/Video/properties/uuid'
+            shortUUID:
+              $ref: '#/components/schemas/Video/properties/shortUUID'

     CommentThreadResponse:
       properties:
         total:
           type: integer
     CommentThreadResponse:
       properties:
         total:
           type: integer

+          example: 1

         data:
           type: array
         data:
           type: array

+          maxItems: 100

           items:
             $ref: '#/components/schemas/VideoComment'
     CommentThreadPostResponse:
           items:
             $ref: '#/components/schemas/VideoComment'
     CommentThreadPostResponse:


@@ -3708,33 +6604,128 @@ components:
       properties:
         total:
           type: integer
       properties:
         total:
           type: integer

+          example: 1

         data:
         data:

+          type: array
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/Video'
+    User:
+      properties:
+        account:
+          $ref: '#/components/schemas/Account'
+        autoPlayNextVideo:
+          type: boolean
+          description: Automatically start playing the upcoming video after the currently playing video
+        autoPlayNextVideoPlaylist:
+          type: boolean
+          description: Automatically start playing the video on the playlist after the currently playing video
+        autoPlayVideo:
+          type: boolean
+          description: Automatically start playing the video on the watch page
+        blocked:
+          type: boolean
+        blockedReason:
+          type: string
+        createdAt:
+          type: string
+        email:
+          type: string
+          format: email
+          description: The user email
+        emailVerified:
+          type: boolean
+          description: Has the user confirmed their email address?
+        id:
+          allOf:
+            - $ref: '#/components/schemas/id'
+          readOnly: true
+        pluginAuth:
+          type: string
+          description: Auth plugin to use to authenticate the user
+        lastLoginDate:
+          type: string
+          format: date-time
+        noInstanceConfigWarningModal:
+          type: boolean
+        noAccountSetupWarningModal:
+          type: boolean
+        noWelcomeModal:
+          type: boolean
+        nsfwPolicy:
+          $ref: '#/components/schemas/NSFWPolicy'
+        role:
+          $ref: '#/components/schemas/UserRole'
+        roleLabel:
+          type: string
+          enum:
+            - User
+            - Moderator
+            - Administrator
+        theme:
+          type: string
+          description: Theme enabled by this user
+        username:
+          $ref: '#/components/schemas/username'
+        videoChannels:

           type: array
           items:
           type: array
           items:

-            $ref: '#/components/schemas/Video'
+            $ref: '#/components/schemas/VideoChannel'
+        videoQuota:
+          type: integer
+          description: The user video quota in bytes
+          example: -1
+        videoQuotaDaily:
+          type: integer
+          description: The user daily video quota in bytes
+          example: -1
+        p2pEnabled:
+          type: boolean
+          description: Enable P2P in the player
+    UserWithStats:
+      allOf:
+        - $ref: '#/components/schemas/User'
+        - properties:
+            # optionally present fields: they require WITH_STATS scope
+            videosCount:
+              type: integer
+              description: Count of videos published
+            abusesCount:
+              type: integer
+              description: Count of reports/abuses of which the user is a target
+            abusesAcceptedCount:
+              type: integer
+              description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
+            abusesCreatedCount:
+              type: integer
+              description: Count of reports/abuses created by the user
+            videoCommentsCount:
+              type: integer
+              description: Count of comments published

     AddUser:
       properties:
         username:
     AddUser:
       properties:
         username:

-          type: string
-          description: 'The user username'
-          minLength: 1
-          maxLength: 50
+          $ref: '#/components/schemas/username'

         password:
         password:

-          type: string
-          description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent'
-          minLength: 6
-          maxLength: 255
+          $ref: '#/components/schemas/password'

         email:
           type: string
         email:
           type: string

-          description: 'The user email. MUST be in the format of an email address.'
+          format: email
+          description: The user email

         videoQuota:
         videoQuota:

-          type: string
-          description: 'The user video quota'
+          type: integer
+          description: The user video quota in bytes
+          example: -1

         videoQuotaDaily:
         videoQuotaDaily:

-          type: string
-          description: 'The user daily video quota'
+          type: integer
+          description: The user daily video quota in bytes
+          example: -1
+        channelName:
+          $ref: '#/components/schemas/usernameChannel'

         role:
           $ref: '#/components/schemas/UserRole'
         role:
           $ref: '#/components/schemas/UserRole'

+        adminFlags:
+          $ref: '#/components/schemas/UserAdminFlags'

       required:
         - username
         - password
       required:
         - username
         - password


@@ -3744,53 +6735,90 @@ components:
         - role
     UpdateUser:
       properties:
         - role
     UpdateUser:
       properties:

-        id:
-          type: string
-          description: 'The user id'

         email:
         email:

-          type: string
-          description: 'The updated email of the user'
+          description: The updated email of the user
+          allOf:
+            - $ref: '#/components/schemas/User/properties/email'
+        emailVerified:
+          type: boolean
+          description: Set the email as verified

         videoQuota:
         videoQuota:

-          type: string
-          description: 'The updated video quota of the user'
+          type: integer
+          description: The updated video quota of the user in bytes

         videoQuotaDaily:
         videoQuotaDaily:

+          type: integer
+          description: The updated daily video quota of the user in bytes
+        pluginAuth:

           type: string
           type: string

-          description: 'The updated daily video quota of the user'
+          nullable: true
+          description: The auth plugin to use to authenticate the user
+          example: 'peertube-plugin-auth-saml2'

         role:
           $ref: '#/components/schemas/UserRole'
         role:
           $ref: '#/components/schemas/UserRole'

-      required:
-        - id
-        - email
-        - videoQuota
-        - videoQuotaDaily
-        - role
+        adminFlags:
+          $ref: '#/components/schemas/UserAdminFlags'

     UpdateMe:
     UpdateMe:

+      # see shared/models/users/user-update-me.model.ts:

       properties:
         password:
       properties:
         password:

-          type: string
-          description: 'Your new password'
+          $ref: '#/components/schemas/password'
+        currentPassword:
+          $ref: '#/components/schemas/password'

         email:
         email:

+          description: new email used for login and service communications
+          allOf:
+            - $ref: '#/components/schemas/User/properties/email'
+        displayName:

           type: string
           type: string

-          description: 'Your new email'
+          description: new name of the user in its representations
+          minLength: 3
+          maxLength: 120

         displayNSFW:
           type: string
         displayNSFW:
           type: string

-          description: 'Your new displayNSFW'
+          description: new NSFW display policy
+          enum:
+            - 'true'
+            - 'false'
+            - both
+        p2pEnabled:
+          type: boolean
+          description: whether to enable P2P in the player or not

         autoPlayVideo:
         autoPlayVideo:

+          type: boolean
+          description: new preference regarding playing videos automatically
+        autoPlayNextVideo:
+          type: boolean
+          description: new preference regarding playing following videos automatically
+        autoPlayNextVideoPlaylist:
+          type: boolean
+          description: new preference regarding playing following playlist videos automatically
+        videosHistoryEnabled:
+          type: boolean
+          description: whether to keep track of watched history or not
+        videoLanguages:
+          type: array
+          items:
+            type: string
+          description: list of languages to filter videos down to
+        theme:

           type: string
           type: string

-          description: 'Your new autoPlayVideo'
-      required:
-        - password
-        - email
-        - displayNSFW
-        - autoPlayVideo
+        noInstanceConfigWarningModal:
+          type: boolean
+        noAccountSetupWarningModal:
+          type: boolean
+        noWelcomeModal:
+          type: boolean

     GetMeVideoRating:
       properties:
         id:
     GetMeVideoRating:
       properties:
         id:

-          type: string
-          description: 'Id of the video'
+          $ref: '#/components/schemas/id'

         rating:
         rating:

-          type: number
-          description: 'Rating of the video'
+          type: string
+          enum:
+            - like
+            - dislike
+            - none
+          description: Rating of the video

       required:
         - id
         - rating
       required:
         - id
         - rating


@@ -3799,65 +6827,170 @@ components:
         video:
           $ref: '#/components/schemas/Video'
         rating:
         video:
           $ref: '#/components/schemas/Video'
         rating:

-          type: number
-          description: 'Rating of the video'
+          type: string
+          enum:
+            - like
+            - dislike
+            - none
+          description: Rating of the video

       required:
         - video
         - rating
     RegisterUser:
       properties:
         username:
       required:
         - video
         - rating
     RegisterUser:
       properties:
         username:

-          type: string
-          description: 'The username of the user'
+          description: immutable name of the user, used to find or mention its actor
+          allOf:
+            - $ref: '#/components/schemas/username'

         password:
         password:

-          type: string
-          description: 'The password of the user'
+          $ref: '#/components/schemas/password'

         email:
           type: string
         email:
           type: string

-          description: 'The email of the user'
+          format: email
+          description: email of the user, used for login or service communications

         displayName:
           type: string
         displayName:
           type: string

-          description: 'The user display name'
+          description: editable name of the user, displayed in its representations
+          minLength: 1
+          maxLength: 120

         channel:
           type: object
         channel:
           type: object

+          description: channel base information used to create the first channel of the user

           properties:
             name:
           properties:
             name:

-              type: string
-              description: 'The name for the default channel'
+              $ref: '#/components/schemas/usernameChannel'

             displayName:
             displayName:

-              type: string
-              description: 'The display name for the default channel'
-
+              $ref: '#/components/schemas/VideoChannel/properties/displayName'

       required:
         - username
         - password
         - email
       required:
         - username
         - password
         - email

-    VideoChannelCreate:
+
+    OAuthClient:

       properties:
       properties:

-        name:
+        client_id:
+          type: string
+          pattern: /^[a-z0-9]$/
+          maxLength: 32
+          minLength: 32
+          example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
+        client_secret:

           type: string
           type: string

+          pattern: /^[a-zA-Z0-9]$/
+          maxLength: 32
+          minLength: 32
+          example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
+    OAuthToken-password:
+      allOf:
+        - $ref: '#/components/schemas/OAuthClient'
+        - type: object
+          properties:
+            grant_type:
+              type: string
+              enum:
+                - password
+                - refresh_token
+              default: password
+            username:
+              $ref: '#/components/schemas/User/properties/username'
+            password:
+              $ref: '#/components/schemas/password'
+      required:
+        - client_id
+        - client_secret
+        - grant_type
+        - username
+        - password
+    OAuthToken-refresh_token:
+      allOf:
+        - $ref: '#/components/schemas/OAuthClient'
+        - type: object
+          properties:
+            grant_type:
+              type: string
+              enum:
+                - password
+                - refresh_token
+              default: password
+            refresh_token:
+              type: string
+              example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
+      required:
+        - client_id
+        - client_secret
+        - grant_type
+        - refresh_token
+
+    VideoChannel:
+      properties:
+        # GET/POST/PUT properties

         displayName:
           type: string
         displayName:
           type: string

+          description: editable name of the channel, displayed in its representations
+          example: Videos of Framasoft
+          minLength: 1
+          maxLength: 120

         description:
           type: string
         description:
           type: string

+          example: Videos made with <3 by Framasoft
+          minLength: 3
+          maxLength: 1000

         support:
           type: string
         support:
           type: string

-          description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+          description: text shown by default on all videos of this channel, to tell the audience how to support it
+          example: Please support our work on https://soutenir.framasoft.org/en/ <3
+          minLength: 3
+          maxLength: 1000
+        # GET-only properties
+        id:
+          readOnly: true
+          allOf:
+            - $ref: '#/components/schemas/id'
+        isLocal:
+          readOnly: true
+          type: boolean
+        updatedAt:
+          readOnly: true
+          type: string
+          format: date-time
+        ownerAccount:
+          readOnly: true
+          nullable: true
+          type: object
+          properties:
+            id:
+              type: integer
+            uuid:
+              $ref: '#/components/schemas/UUIDv4'
+    VideoChannelCreate:
+      allOf:
+        - $ref: '#/components/schemas/VideoChannel'
+        - properties:
+            name:
+              description: username of the channel to create
+              allOf:
+                - $ref: '#/components/schemas/usernameChannel'

       required:
         - name
         - displayName
     VideoChannelUpdate:
       required:
         - name
         - displayName
     VideoChannelUpdate:

+      allOf:
+        - $ref: '#/components/schemas/VideoChannel'
+        - properties:
+            bulkVideosSupportUpdate:
+              type: boolean
+              description: Update the support field for all videos of this channel
+    VideoChannelList:

       properties:
       properties:

-        displayName:
-          type: string
-        description:
-          type: string
-        support:
-          type: string
-          description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
-        bulkVideosSupportUpdate:
-          type: boolean
-          description: 'Update the support field for all videos of this channel'
+        total:
+          type: integer
+          example: 1
+        data:
+          type: array
+          items:
+            allOf:
+              - $ref: '#/components/schemas/VideoChannel'
+              - $ref: '#/components/schemas/Actor'

 
     MRSSPeerLink:
       type: object
 
     MRSSPeerLink:
       type: object


@@ -3881,6 +7014,7 @@ components:
       properties:
         url:
           type: string
       properties:
         url:
           type: string

+          format: url

           xml:
             attribute: true
         fileSize:
           xml:
             attribute: true
         fileSize:


@@ -3919,6 +7053,7 @@ components:
         properties:
           link:
             type: string
         properties:
           link:
             type: string

+            format: url

           guid:
             type: string
           pubDate:
           guid:
             type: string
           pubDate:


@@ -3940,6 +7075,7 @@ components:
         properties:
           link:
             type: string
         properties:
           link:
             type: string

+            format: url

             description: video watch page URL
           guid:
             type: string
             description: video watch page URL
           guid:
             type: string


@@ -3976,6 +7112,7 @@ components:
             properties:
               url:
                 type: string
             properties:
               url:
                 type: string

+                format: url

                 description: video embed path, relative to the canonical URL domain (MRSS)
                 xml:
                   attribute: true
                 description: video embed path, relative to the canonical URL domain (MRSS)
                 xml:
                   attribute: true


@@ -3984,6 +7121,7 @@ components:
             properties:
               url:
                 type: string
             properties:
               url:
                 type: string

+                format: url

                 description: video watch path, relative to the canonical URL domain (MRSS)
                 xml:
                   attribute: true
                 description: video watch path, relative to the canonical URL domain (MRSS)
                 xml:
                   attribute: true


@@ -3992,6 +7130,7 @@ components:
             properties:
               url:
                 type: string
             properties:
               url:
                 type: string

+                format: url

                 xml:
                   attribute: true
               height:
                 xml:
                   attribute: true
               height:


@@ -4019,6 +7158,7 @@ components:
             properties:
               url:
                 type: string
             properties:
               url:
                 type: string

+                format: url

                 xml:
                   attribute: true
               type:
                 xml:
                   attribute: true
               type:


@@ -4037,4 +7177,259 @@ components:
             items:
               anyOf:
                 - $ref: '#/components/schemas/MRSSPeerLink'
             items:
               anyOf:
                 - $ref: '#/components/schemas/MRSSPeerLink'

-                - $ref: '#/components/schemas/MRSSGroupContent'
\ No newline at end of file
+                - $ref: '#/components/schemas/MRSSGroupContent'
+    NotificationSettingValue:
+      type: integer
+      description: >
+        Notification type
+
+        - `0` NONE
+
+        - `1` WEB
+
+        - `2` EMAIL
+      enum:
+        - 0
+        - 1
+        - 2
+    Notification:
+      properties:
+        id:
+          $ref: '#/components/schemas/id'
+        type:
+          type: integer
+          description: >
+            Notification type, following the `UserNotificationType` enum:
+
+            - `1` NEW_VIDEO_FROM_SUBSCRIPTION
+
+            - `2` NEW_COMMENT_ON_MY_VIDEO
+
+            - `3` NEW_ABUSE_FOR_MODERATORS
+
+            - `4` BLACKLIST_ON_MY_VIDEO
+
+            - `5` UNBLACKLIST_ON_MY_VIDEO
+
+            - `6` MY_VIDEO_PUBLISHED
+
+            - `7` MY_VIDEO_IMPORT_SUCCESS
+
+            - `8` MY_VIDEO_IMPORT_ERROR
+
+            - `9` NEW_USER_REGISTRATION
+
+            - `10` NEW_FOLLOW
+
+            - `11` COMMENT_MENTION
+
+            - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
+
+            - `13` NEW_INSTANCE_FOLLOWER
+
+            - `14` AUTO_INSTANCE_FOLLOWING
+            
+            - `15` ABUSE_STATE_CHANGE
+            
+            - `16` ABUSE_NEW_MESSAGE
+            
+            - `17` NEW_PLUGIN_VERSION
+            
+            - `18` NEW_PEERTUBE_VERSION
+        read:
+          type: boolean
+        video:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/VideoInfo'
+            - type: object
+              properties:
+                channel:
+                  $ref: '#/components/schemas/ActorInfo'
+        videoImport:
+          nullable: true
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            video:
+              nullable: true
+              $ref: '#/components/schemas/VideoInfo'
+            torrentName:
+              type: string
+              nullable: true
+            magnetUri:
+              $ref: '#/components/schemas/VideoImport/properties/magnetUri'
+            targetUri:
+              type: string
+              format: uri
+              nullable: true
+        comment:
+          nullable: true
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            threadId:
+              type: integer
+            video:
+              $ref: '#/components/schemas/VideoInfo'
+            account:
+              $ref: '#/components/schemas/ActorInfo'
+        videoAbuse:
+          nullable: true
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            video:
+              allOf:
+                - $ref: '#/components/schemas/VideoInfo'
+        videoBlacklist:
+          nullable: true
+          type: object
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            video:
+              allOf:
+                - $ref: '#/components/schemas/VideoInfo'
+        account:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/ActorInfo'
+        actorFollow:
+          type: object
+          nullable: true
+          properties:
+            id:
+              $ref: '#/components/schemas/id'
+            follower:
+              $ref: '#/components/schemas/ActorInfo'
+            state:
+              type: string
+              enum:
+                - pending
+                - accepted
+            following:
+              type: object
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - account
+                    - channel
+                    - instance
+                name:
+                  type: string
+                displayName:
+                  type: string
+                host:
+                  type: string
+                  format: hostname
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    NotificationListResponse:
+      properties:
+        total:
+          type: integer
+          example: 1
+        data:
+          type: array
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/Notification'
+    Plugin:
+      properties:
+        name:
+          type: string
+          example: peertube-plugin-auth-ldap
+        type:
+          type: integer
+          description: >
+            - `1`: PLUGIN
+
+            - `2`: THEME
+          enum:
+            - 1
+            - 2
+        latestVersion:
+          type: string
+          example: 0.0.3
+        version:
+          type: string
+          example: 0.0.1
+        enabled:
+          type: boolean
+        uninstalled:
+          type: boolean
+        peertubeEngine:
+          type: string
+          example: 2.2.0
+        description:
+          type: string
+        homepage:
+          type: string
+          format: url
+          example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
+        settings:
+          type: object
+          additionalProperties: true
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+    PluginResponse:
+      properties:
+        total:
+          type: integer
+          example: 1
+        data:
+          type: array
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/Plugin'
+
+    LiveVideoUpdate:
+      properties:
+        saveReplay:
+          type: boolean
+        permanentLive:
+          description: User can stream multiple times in a permanent live
+          type: boolean
+
+    LiveVideoResponse:
+      properties:
+        rtmpUrl:
+          type: string
+        rtmpsUrl:
+          type: string
+        streamKey:
+          type: string
+          description: RTMP stream key to use to stream into this live video
+        saveReplay:
+          type: boolean
+        permanentLive:
+          description: User can stream multiple times in a permanent live
+          type: boolean
+
+
+
+  callbacks:
+    searchIndex:
+      'https://search.example.org/api/v1/search/videos':
+        post:
+          summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
+          responses:
+            '200':
+              description: successful operation
+              content:
+                application/json:
+                  schema:
+                    $ref: '#/components/schemas/VideoListResponse'