Add event doc to view endpoint

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

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index fad0173e3b3370752c0b796274456e6bc8422eca..407f3eb10f0e6f1c780548083a36aa797761469c 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: PeerTube
 openapi: 3.0.0
 info:
   title: PeerTube

-  version: 3.2.0-rc.1
+  version: 4.0.0

   contact:
     name: PeerTube Community
     url: https://joinpeertube.org
   contact:
     name: PeerTube Community
     url: https://joinpeertube.org


@@ -22,7 +22,7 @@ info:
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 
     See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 
     See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few

-    examples of using with the PeerTube API.
+    examples of using the PeerTube API.

 
     # Authentication
 
 
     # Authentication
 


@@ -38,48 +38,79 @@ info:
     # 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.
+    of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.

 
     ```
     HTTP 1.1 404 Not Found
 
     ```
     HTTP 1.1 404 Not Found

-    Content-Type: application/json
+    Content-Type: application/problem+json; charset=utf-8

 
     {
 
     {

-      "errorCode": 1
-      "error": "Account not found"
+      "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 codes 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.
+    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
 
     ### 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 type:
+    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
 
     ```
     HTTP 1.1 400 Bad Request

-    Content-Type: application/json
+    Content-Type: application/problem+json; charset=utf-8

 
     {
 
     {

-      "errors": {
-        "id": { // 
-          "value": "a117eb-c6a9-4756-bb09-2a956239f",
-          "msg": "Should have a valid id",
+      "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",
           "param": "id",

-          "location": "params"
+          "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.
     }
     ```
 
     Where `id` is the name of the field concerned by the error, within the route definition.

-    `errors.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
-    `errors.<field>.value` reports the value that didn't pass validation whose `errors.<field>.msg`
+    `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.
 
     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:
     # Rate limits
 
     We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:


@@ -108,7 +139,7 @@ info:
 
     This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
     allowing cross-domain communication from the browser for some routes:
 
     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/*`                    |
     | Endpoint                    |
     |------------------------- ---|
     | `/api/*`                    |


@@ -124,8 +155,8 @@ tags:
   - name: Register
     description: |
       As a visitor, you can use this API to open an account (if registrations are open on
   - 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/createUser) instead.
+      that PeerTube instance). As an admin, you should use the dedicated [User creation
+      API](#operation/addUser) instead.

   - name: Session
     x-displayName: Login/Logout
     description: |
   - name: Session
     x-displayName: Login/Logout
     description: |


@@ -221,6 +252,8 @@ tags:
 
       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.
 
       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 Imports
+    description: Operations dealing with listing, adding and removing video imports.

   - name: Video Captions
     description: Operations dealing with listing, adding and removing closed captions of a video.
   - name: Video Channels
   - name: Video Captions
     description: Operations dealing with listing, adding and removing closed captions of a video.
   - name: Video Channels


@@ -236,6 +269,12 @@ tags:
     description: Like/dislike a video.
   - name: Video Playlists
     description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
     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: Video stats
+    description: Video statistics

   - name: Feeds
     description: Server syndication feeds
   - name: Search
   - name: Feeds
     description: Server syndication feeds
   - name: Search


@@ -247,6 +286,8 @@ 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: 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.
   - name: Video Mirroring
     description: |
       PeerTube instances can mirror videos from one another, and help distribute some videos.


@@ -269,18 +310,25 @@ x-tagGroups:
     tags:
       - Video
       - Video Upload
     tags:
       - Video
       - Video Upload

+      - Video Imports

       - Video Captions
       - Video Channels
       - Video Comments
       - Video Rates
       - Video Playlists
       - Video Captions
       - Video Channels
       - Video Comments
       - Video Rates
       - Video Playlists

+      - Video Stats

       - Video Ownership Change
       - Video Mirroring
       - Video Ownership Change
       - Video Mirroring

+      - Video Files
+      - Video Transcoding

       - Live Videos
       - Feeds
   - name: Search
     tags:
       - Search
       - Live Videos
       - Feeds
   - name: Search
     tags:
       - Search

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

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


@@ -302,6 +350,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:


@@ -313,12 +362,14 @@ 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'


@@ -328,7 +379,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $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'


@@ -374,11 +429,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'


@@ -392,11 +479,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


@@ -407,9 +496,11 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/config
               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:


@@ -422,9 +513,11 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/config/about
               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:
       tags:
         - Config
       security:


@@ -439,6 +532,7 @@ 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:
       tags:
         - Config
       security:


@@ -455,6 +549,7 @@ paths:
               - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
     delete:
       summary: Delete instance runtime configuration
               - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
     delete:
       summary: Delete instance runtime configuration

+      operationId: delCustomConfig

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


@@ -463,9 +558,69 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+
+  /custom-pages/homepage/instance:
+    get:
+      summary: Get instance custom homepage
+      tags:
+        - Homepage
+      responses:
+        '404':
+          description: No homepage set
+        '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/pause:
+    post:
+      summary: Pause job queue
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Job
+      responses:
+        '204':
+          description: successful operation
+
+  /jobs/resume:
+    post:
+      summary: Resume job queue
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Job
+      responses:
+        '204':
+          description: successful operation
+

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

+      operationId: getJobs

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -505,66 +660,108 @@ paths:
                     maxItems: 100
                     items:
                       $ref: '#/components/schemas/Job'
                     maxItems: 100
                     items:
                       $ref: '#/components/schemas/Job'

-  '/server/following/{host}':
+
+  /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: hostname
+            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
       summary: List instances followed by the server
       parameters:
   /server/following:
     get:
       tags:
         - Instance Follows
       summary: List instances followed by the server
       parameters:

-        - name: state
-          in: query
-          schema:
-            type: string
-            enum:
-              - pending
-              - accepted
-        - name: actorType
-          in: query
-          schema:
-            type: string
-            enum:
-              - Person
-              - Application
-              - Group
-              - Service
-              - Organization
+        - $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'


@@ -574,16 +771,22 @@ 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:
           - admin
       tags:
         - Instance Follows
     post:
       security:
         - OAuth2:
           - admin
       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


@@ -601,10 +804,37 @@ paths:
                     type: string
                     format: hostname
                   uniqueItems: true
                     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: createUser
+      operationId: addUser

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -619,18 +849,18 @@ paths:
                 $ref: '#/components/schemas/AddUserResponse'
           links:
             # GET /users/{id}
                 $ref: '#/components/schemas/AddUserResponse'
           links:
             # GET /users/{id}

-            GetUserId:
-              operationId: getUserId
+            GetUser:
+              operationId: getUser

               parameters:
                 id: '$response.body#/user/id'
             # PUT /users/{id}
               parameters:
                 id: '$response.body#/user/id'
             # PUT /users/{id}

-            PutUserId:
-              operationId: putUserId
+            PutUser:
+              operationId: putUser

               parameters:
                 id: '$response.body#/user/id'
             # DELETE /users/{id}
               parameters:
                 id: '$response.body#/user/id'
             # DELETE /users/{id}

-            DelUserId:
-              operationId: delUserId
+            DelUser:
+              operationId: delUser

               parameters:
                 id: '$response.body#/user/id'
         '403':
               parameters:
                 id: '$response.body#/user/id'
         '403':


@@ -646,6 +876,7 @@ paths:
         required: true
     get:
       summary: List users
         required: true
     get:
       summary: List users

+      operationId: getUsers

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -666,6 +897,7 @@ paths:
                 type: array
                 items:
                   $ref: '#/components/schemas/User'
                 type: array
                 items:
                   $ref: '#/components/schemas/User'

+

   '/users/{id}':
     parameters:
       - $ref: '#/components/parameters/id'
   '/users/{id}':
     parameters:
       - $ref: '#/components/parameters/id'


@@ -676,7 +908,7 @@ paths:
           - admin
       tags:
         - Users
           - admin
       tags:
         - Users

-      operationId: delUserId
+      operationId: delUser

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


@@ -686,7 +918,7 @@ paths:
         - OAuth2: []
       tags:
         - Users
         - OAuth2: []
       tags:
         - Users

-      operationId: getUserId
+      operationId: getUser

       parameters:
         - name: withStats
           in: query
       parameters:
         - name: withStats
           in: query


@@ -711,7 +943,7 @@ paths:
         - OAuth2: []
       tags:
         - Users
         - OAuth2: []
       tags:
         - Users

-      operationId: putUserId
+      operationId: putUser

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


@@ -725,7 +957,7 @@ paths:
   /oauth-clients/local:
     get:
       summary: Login prerequisite
   /oauth-clients/local:
     get:
       summary: Login prerequisite

-      description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken).
+      description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).

       operationId: getOAuthClient
       tags:
         - Session
       operationId: getOAuthClient
       tags:
         - Session


@@ -742,6 +974,14 @@ paths:
               parameters:
                 client_id: '$response.body#/client_id'
                 client_secret: '$response.body#/client_secret'
               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
   /users/token:
     post:
       summary: Login


@@ -788,6 +1028,37 @@ paths:
                     type: integer
                     minimum: 0
                     example: 1209600
                     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
   /users/revoke-token:
     post:
       summary: Logout


@@ -804,6 +1075,7 @@ paths:
   /users/register:
     post:
       summary: Register a user
   /users/register:
     post:
       summary: Register a user

+      operationId: registerUser

       tags:
         - Users
         - Register
       tags:
         - Users
         - Register


@@ -816,12 +1088,14 @@ paths:
             schema:
               $ref: '#/components/schemas/RegisterUser'
         required: true
             schema:
               $ref: '#/components/schemas/RegisterUser'
         required: true

+

   /users/{id}/verify-email:
     post:
       summary: Verify a user
   /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
       description: |
         Following a user registration, the new user will receive an email asking to click a link

-        containing a secret. 
+        containing a secret.

       tags:
         - Users
         - Register
       tags:
         - Users
         - Register


@@ -847,9 +1121,11 @@ paths:
           description: invalid verification string
         '404':
           description: user not found
           description: invalid verification string
         '404':
           description: user not found

+

   /users/ask-send-verify-email:
     post:
       summary: Resend user verification link
   /users/ask-send-verify-email:
     post:
       summary: Resend user verification link

+      operationId: resendEmailToVerifyUser

       tags:
         - Users
         - Register
       tags:
         - Users
         - Register


@@ -860,6 +1136,7 @@ paths:
   /users/me:
     get:
       summary: Get my user information
   /users/me:
     get:
       summary: Get my user information

+      operationId: getUserInfo

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


@@ -876,6 +1153,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


@@ -890,6 +1168,7 @@ 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
   /users/me/videos/imports:
     get:
       summary: Get video imports of my user


@@ -910,6 +1189,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoImportsList'
             application/json:
               schema:
                 $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


@@ -934,6 +1214,7 @@ paths:
                     type: number
                     description: The user video quota used today in bytes
                     example: 1681014151
                     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


@@ -956,6 +1237,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


@@ -976,6 +1258,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+

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


@@ -1021,6 +1304,7 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+

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


@@ -1038,6 +1322,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


@@ -1055,7 +1340,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $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'


@@ -1067,6 +1356,7 @@ 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
   '/users/me/subscriptions/{subscriptionHandle}':
     get:
       summary: Get subscription of my user


@@ -1096,6 +1386,7 @@ paths:
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation

+

   /users/me/notifications:
     get:
       summary: List my notifications
   /users/me/notifications:
     get:
       summary: List my notifications


@@ -1119,6 +1410,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NotificationListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/NotificationListResponse'

+

   /users/me/notifications/read:
     post:
       summary: Mark notifications as read by their id
   /users/me/notifications/read:
     post:
       summary: Mark notifications as read by their id


@@ -1142,6 +1434,7 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   /users/me/notifications/read-all:
     post:
       summary: Mark all my notification as read
   /users/me/notifications/read-all:
     post:
       summary: Mark all my notification as read


@@ -1152,6 +1445,7 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   /users/me/notification-settings:
     put:
       summary: Update my notification settings
   /users/me/notification-settings:
     put:
       summary: Update my notification settings


@@ -1192,6 +1486,7 @@ paths:
       responses:
         '204':
           description: successful operation
       responses:
         '204':
           description: successful operation

+

   /users/me/history/videos:
     get:
       summary: List watched videos history
   /users/me/history/videos:
     get:
       summary: List watched videos history


@@ -1210,6 +1505,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+
+  /users/me/history/videos/{videoId}:
+    delete:
+      summary: Delete history element
+      security:
+        - OAuth2: []
+      tags:
+        - My History
+      parameters:
+        - name: videoId
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/Video/properties/id'
+      responses:
+        '204':
+          description: successful operation
+

   /users/me/history/videos/remove:
     post:
       summary: Clear video history
   /users/me/history/videos/remove:
     post:
       summary: Clear video history


@@ -1230,6 +1543,7 @@ paths:
       responses:
         '204':
           description: successful operation
       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


@@ -1245,8 +1559,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

-                  avatar:
-                    $ref: '#/components/schemas/ActorImage'
+                  avatars:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'

         '413':
           description: image file too large
           headers:
         '413':
           description: image file too large
           headers:


@@ -1268,6 +1584,7 @@ paths:
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg

+

   /users/me/avatar:
     delete:
       summary: Delete my avatar
   /users/me/avatar:
     delete:
       summary: Delete my avatar


@@ -1289,6 +1606,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


@@ -1304,7 +1622,8 @@ paths:
         '403':
           description: cannot terminate an ownership change of another user
         '404':
         '403':
           description: cannot terminate an ownership change of another user
         '404':

-          description: video owneship change not found
+          description: video ownership change not found
+

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


@@ -1320,7 +1639,8 @@ paths:
         '403':
           description: cannot terminate an ownership change of another user
         '404':
         '403':
           description: cannot terminate an ownership change of another user
         '404':

-          description: video owneship change not found
+          description: video ownership change not found
+

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


@@ -1348,9 +1668,11 @@ 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:
       tags:
         - Video
       parameters:


@@ -1361,7 +1683,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $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'


@@ -1373,6 +1699,7 @@ 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


@@ -1391,6 +1718,7 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/categories
               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


@@ -1409,6 +1737,7 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/licences
               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


@@ -1427,6 +1756,7 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/languages
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/languages

+

   /videos/privacies:
     get:
       summary: List available video privacy policies
   /videos/privacies:
     get:
       summary: List available video privacy policies


@@ -1445,9 +1775,11 @@ paths:
               examples:
                 nightly:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
               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:


@@ -1509,6 +1841,9 @@ paths:
                 commentsEnabled:
                   description: Enable or disable comments for this video
                   type: boolean
                 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
                 originallyPublishedAt:
                   description: Date when the content was originally published
                   type: string


@@ -1522,6 +1857,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:


@@ -1535,6 +1871,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:


@@ -1544,9 +1881,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:


@@ -1563,34 +1902,108 @@ paths:
                 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)**
                 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:
   '/videos/{id}/views':
     post:

-      summary: Add a view to a video
+      summary: Notify user is watching a video
+      description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
+      operationId: addView
+      tags:
+        - Video
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserViewingVideo'
+        required: true
+      responses:
+        '204':
+          description: successful operation
+
+  '/videos/{id}/watching':
+    put:
+      summary: Set watching progress of a video
+      deprecated: true
+      description: This endpoint has been deprecated. Use `/videos/{id}/views` instead

       tags:
         - Video
       tags:
         - Video

+      security:
+        - OAuth2: []

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

+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserViewingVideo'
+        required: true

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

-  '/videos/{id}/watching':
-    put:
-      summary: Set watching progress of a video
+
+  '/videos/{id}/stats/overall':
+    get:
+      summary: Get overall stats of a video
+      tags:
+        - Video Stats
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoStatsOverall'
+
+  '/videos/{id}/stats/retention':
+    get:
+      summary: Get retention stats of a video
+      tags:
+        - Video Stats
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoStatsRetention'
+
+  '/videos/{id}/stats/timeseries/{metric}':
+    get:
+      summary: Get timeserie stats of a video

       tags:
       tags:

-        - Video
+        - Video Stats

       security:
         - OAuth2: []
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       security:
         - OAuth2: []
       parameters:
         - $ref: '#/components/parameters/idOrUUID'

-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/UserWatchingVideo'
-        required: true
+        -
+          name: metric
+          in: path
+          required: true
+          description: The metric to get
+          schema:
+            type: string
+            enum:
+              - 'viewers'
+              - 'aggregateWatchTime'

       responses:
       responses:

-        '204':
+        '200':

           description: successful operation
           description: successful operation

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

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


@@ -1608,14 +2021,15 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'

-        '400':
-          description: invalid file field, schedule date or parameter

         '403':
           description: video didn't pass upload filter
         '408':
           description: upload has timed out
         '413':
         '403':
           description: video didn't pass upload filter
         '408':
           description: upload has timed out
         '413':

-          description: video file too large, due to quota or max body size limit set by the reverse-proxy
+          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:
           headers:
             X-File-Maximum-Size:
               schema:


@@ -1647,26 +2061,27 @@ paths:
             FILE_PATH="<your_file_path>"
             CHANNEL_ID="<your_channel_id>"
             NAME="<video_name>"
             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=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
-            client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
-            token=$(curl -s "$API_PATH/users/token" \
+            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 client_id="$client_id" \
               --data client_secret="$client_secret" \
               --data grant_type=password \

-              --data response_type=code \

               --data username="$USERNAME" \
               --data password="$PASSWORD" \
               | jq -r ".access_token")
               --data username="$USERNAME" \
               --data password="$PASSWORD" \
               | jq -r ".access_token")

+

             ## VIDEO UPLOAD
             ## VIDEO UPLOAD

-            curl -s "$API_PATH/videos/upload" \
+            curl -s "$API/videos/upload" \

               -H "Authorization: Bearer $token" \
               --max-time 600 \
               --form videofile=@"$FILE_PATH" \
               --form channelId=$CHANNEL_ID \
               --form name="$NAME"
               -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
   /videos/upload-resumable:
     post:
       summary: Initialize the resumable upload of a video


@@ -1713,10 +2128,12 @@ paths:
               schema:
                 type: number
                 example: 0
               schema:
                 type: number
                 example: 0

-        '400':
-          description: invalid file field, schedule date or parameter

         '413':
         '413':

-          description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+          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:
         '415':
           description: video type unsupported
     put:


@@ -1730,10 +2147,10 @@ paths:
         - Video Upload
       parameters:
         - name: upload_id
         - Video Upload
       parameters:
         - name: upload_id

-          in: path
+          in: query

           required: true
           description: |
           required: true
           description: |

-            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+            Created session id to proceed with. If you didn't send chunks in the last hour, it is

             not valid anymore and you need to initialize a new upload.
           schema:
             type: string
             not valid anymore and you need to initialize a new upload.
           schema:
             type: string


@@ -1757,9 +2174,6 @@ paths:
           description: |
             Size of the chunk that the request is sending.
 
           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:
             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:


@@ -1792,10 +2206,21 @@ paths:
                 example: 0
         '403':
           description: video didn't pass upload filter
                 example: 0
         '403':
           description: video didn't pass upload filter

-        '413':
-          description: video file too large, due to quota or max body size limit set by the reverse-proxy
+        '404':
+          description: upload not found
+        '409':
+          description: chunk doesn't match range

         '422':
           description: video unreadable
         '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
     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


@@ -1807,7 +2232,7 @@ paths:
         - Video Upload
       parameters:
         - name: upload_id
         - Video Upload
       parameters:
         - name: upload_id

-          in: path
+          in: query

           required: true
           description: |
             Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
           required: true
           description: |
             Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is


@@ -1828,6 +2253,9 @@ paths:
               schema:
                 type: number
                 example: 0
               schema:
                 type: number
                 example: 0

+        '404':
+          description: upload not found
+

   /videos/imports:
     post:
       summary: Import a video
   /videos/imports:
     post:
       summary: Import a video


@@ -1836,7 +2264,7 @@ paths:
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:

-        - Video
+        - Video Imports

         - Video Upload
       requestBody:
         content:
         - Video Upload
       requestBody:
         content:


@@ -1864,10 +2292,38 @@ paths:
         '409':
           description: HTTP or Torrent/magnetURI import not enabled
 
         '409':
           description: HTTP or Torrent/magnetURI import not enabled
 

+  /videos/imports/{id}/cancel:
+    post:
+      summary: Cancel video import
+      description: Cancel a pending video import
+      security:
+        - OAuth2: []
+      tags:
+        - Video Imports
+      parameters:
+        - $ref: '#/components/parameters/id'
+      responses:
+        '204':
+          description: successful operation
+
+  /videos/imports/{id}:
+    delete:
+      summary: Delete video import
+      description: Delete ended video import
+      security:
+        - OAuth2: []
+      tags:
+        - Video Imports
+      parameters:
+        - $ref: '#/components/parameters/id'
+      responses:
+        '204':
+          description: successful operation
+

   /videos/live:
     post:
       summary: Create a live
   /videos/live:
     post:
       summary: Create a live

-      operationId: createLive
+      operationId: addLive

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


@@ -1880,8 +2336,20 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
             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':
         '403':

-          description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+          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:
       requestBody:
         content:
           multipart/form-data:


@@ -1896,6 +2364,9 @@ paths:
                 permanentLive:
                   description: User can stream multiple times in a permanent live
                   type: boolean
                 permanentLive:
                   description: User can stream multiple times in a permanent live
                   type: boolean

+                latencyMode:
+                  description: User can select live latency mode if enabled by the instance
+                  $ref: '#/components/schemas/LiveVideoLatencyMode'

                 thumbnailfile:
                   description: Live video/replay thumbnail file
                   type: string
                 thumbnailfile:
                   description: Live video/replay thumbnail file
                   type: string


@@ -1940,7 +2411,7 @@ paths:
                   description: Enable or disable comments for this live video/replay
                   type: boolean
                 downloadEnabled:
                   description: Enable or disable comments for this live video/replay
                   type: boolean
                 downloadEnabled:

-                  description: Enable or disable downloading for the replay of this live
+                  description: Enable or disable downloading for the replay of this live video

                   type: boolean
               required:
                 - channelId
                   type: boolean
               required:
                 - channelId


@@ -2082,7 +2553,7 @@ paths:
             type: string
         - name: videoIs
           in: query
             type: string
         - name: videoIs
           in: query

-          description: only list blacklisted or deleted videos
+          description: only list deleted or blocklisted videos

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


@@ -2115,7 +2586,6 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Abuse'
                     type: array
                     items:
                       $ref: '#/components/schemas/Abuse'

-

     post:
       summary: Report an abuse
       security:
     post:
       summary: Report an abuse
       security:


@@ -2169,10 +2639,21 @@ paths:
               required:
                 - reason
       responses:
               required:
                 - reason
       responses:

-        '204':
+        '200':

           description: successful operation
           description: successful operation

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

         '400':
           description: incorrect request parameters
         '400':
           description: incorrect request parameters

+

   '/abuses/{abuseId}':
     put:
       summary: Update an abuse
   '/abuses/{abuseId}':
     put:
       summary: Update an abuse


@@ -2217,6 +2698,7 @@ paths:
           description: successful operation
         '404':
           description: block not found
           description: successful operation
         '404':
           description: block not found

+

   '/abuses/{abuseId}/messages':
     get:
       summary: List messages of an abuse
   '/abuses/{abuseId}/messages':
     get:
       summary: List messages of an abuse


@@ -2232,10 +2714,15 @@ paths:
           content:
             application/json:
               schema:
           content:
             application/json:
               schema:

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

     post:
       summary: Add message to an abuse
       security:
     post:
       summary: Add message to an abuse
       security:


@@ -2263,6 +2750,7 @@ paths:
           description: successful operation
         '400':
           description: incorrect request parameters
           description: successful operation
         '400':
           description: incorrect request parameters

+

   '/abuses/{abuseId}/messages/{abuseMessageId}':
     delete:
       summary: Delete an abuse message
   '/abuses/{abuseId}/messages/{abuseMessageId}':
     delete:
       summary: Delete an abuse message


@@ -2280,6 +2768,7 @@ paths:
   '/videos/{id}/blacklist':
     post:
       summary: Block a video
   '/videos/{id}/blacklist':
     post:
       summary: Block a video

+      operationId: addVideoBlock

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -2293,6 +2782,7 @@ 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:
           - admin
       security:
         - OAuth2:
           - admin


@@ -2306,11 +2796,13 @@ paths:
           description: successful operation
         '404':
           description: block not found
           description: successful operation
         '404':
           description: block not found

+

   /videos/blacklist:
     get:
       tags:
         - Video Blocks
       summary: List video blocks
   /videos/blacklist:
     get:
       tags:
         - Video Blocks
       summary: List video blocks

+      operationId: getVideoBlocks

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -2352,9 +2844,11 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/VideoBlacklist'
                     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:
         - Video Captions
       parameters:
       tags:
         - Video Captions
       parameters:


@@ -2374,9 +2868,11 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/VideoCaption'
                     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
       security:
         - OAuth2:
           - user


@@ -2405,6 +2901,7 @@ 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
       security:
         - OAuth2:
           - user


@@ -2418,6 +2915,7 @@ 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


@@ -2437,7 +2935,7 @@ paths:
                 $ref: '#/components/schemas/VideoChannelList'
     post:
       summary: Create a video channel
                 $ref: '#/components/schemas/VideoChannelList'
     post:
       summary: Create a video channel

-      operationId: createVideoChannel
+      operationId: addVideoChannel

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


@@ -2454,12 +2952,13 @@ paths:
                     type: object
                     properties:
                       id:
                     type: object
                     properties:
                       id:

-                        $ref: '#/components/schemas/VideoChannel/properties/id'
+                        $ref: '#/components/schemas/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


@@ -2477,6 +2976,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:


@@ -2493,6 +2993,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:


@@ -2502,9 +3003,11 @@ 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
       tags:
         - Video
         - Video Channels


@@ -2517,7 +3020,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $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'


@@ -2529,6 +3036,37 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'

+
+  '/video-channels/{channelHandle}/followers':
+    get:
+      tags:
+        - Video Channels
+      summary: 'List followers of a video channel'
+      security:
+        - OAuth2: []
+      operationId: getVideoChannelFollowers
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+        - $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'
+

   '/video-channels/{channelHandle}/avatar/pick':
     post:
       summary: Update channel avatar
   '/video-channels/{channelHandle}/avatar/pick':
     post:
       summary: Update channel avatar


@@ -2546,8 +3084,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

-                  avatar:
-                    $ref: '#/components/schemas/ActorImage'
+                  avatars:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'

         '413':
           description: image file too large
           headers:
         '413':
           description: image file too large
           headers:


@@ -2569,6 +3109,7 @@ paths:
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg

+

   '/video-channels/{channelHandle}/avatar':
     delete:
       summary: Delete channel avatar
   '/video-channels/{channelHandle}/avatar':
     delete:
       summary: Delete channel avatar


@@ -2582,7 +3123,6 @@ paths:
         '204':
           description: successful operation
 
         '204':
           description: successful operation
 

-

   '/video-channels/{channelHandle}/banner/pick':
     post:
       summary: Update channel banner
   '/video-channels/{channelHandle}/banner/pick':
     post:
       summary: Update channel banner


@@ -2600,8 +3140,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

-                  banner:
-                    $ref: '#/components/schemas/ActorImage'
+                  banners:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'

         '413':
           description: image file too large
           headers:
         '413':
           description: image file too large
           headers:


@@ -2623,6 +3165,7 @@ paths:
             encoding:
               bannerfile:
                 contentType: image/png, image/jpeg
             encoding:
               bannerfile:
                 contentType: image/png, image/jpeg

+

   '/video-channels/{channelHandle}/banner':
     delete:
       summary: Delete channel banner
   '/video-channels/{channelHandle}/banner':
     delete:
       summary: Delete channel banner


@@ -2683,7 +3226,7 @@ paths:
     post:
       summary: Create a video playlist
       description: If the video playlist is set as public, `videoChannelId` is mandatory.
     post:
       summary: Create a video playlist
       description: If the video playlist is set as public, `videoChannelId` is mandatory.

-      operationId: createPlaylist
+      operationId: addPlaylist

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


@@ -2703,6 +3246,8 @@ paths:
                         $ref: '#/components/schemas/VideoPlaylist/properties/id'
                       uuid:
                         $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
                         $ref: '#/components/schemas/VideoPlaylist/properties/id'
                       uuid:
                         $ref: '#/components/schemas/VideoPlaylist/properties/uuid'

+                      shortUUID:
+                        $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'

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


@@ -2803,11 +3348,14 @@ paths:
   /video-playlists/{playlistId}/videos:
     get:
       summary: 'List videos of a playlist'
   /video-playlists/{playlistId}/videos:
     get:
       summary: 'List videos of a playlist'

+      operationId: getVideoPlaylistVideos

       tags:
         - Videos
         - Video Playlists
       parameters:
         - $ref: '#/components/parameters/playlistId'
       tags:
         - Videos
         - Video Playlists
       parameters:
         - $ref: '#/components/parameters/playlistId'

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

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


@@ -2817,6 +3365,7 @@ paths:
                 $ref: '#/components/schemas/VideoListResponse'
     post:
       summary: Add a video in a playlist
                 $ref: '#/components/schemas/VideoListResponse'
     post:
       summary: Add a video in a playlist

+      operationId: addVideoPlaylistVideo

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


@@ -2863,6 +3412,7 @@ paths:
   /video-playlists/{playlistId}/videos/reorder:
     post:
       summary: 'Reorder a playlist'
   /video-playlists/{playlistId}/videos/reorder:
     post:
       summary: 'Reorder a playlist'

+      operationId: reorderVideoPlaylist

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


@@ -2897,6 +3447,7 @@ paths:
   /video-playlists/{playlistId}/videos/{playlistElementId}:
     put:
       summary: Update a playlist element
   /video-playlists/{playlistId}/videos/{playlistElementId}:
     put:
       summary: Update a playlist element

+      operationId: putVideoPlaylistVideo

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


@@ -2923,6 +3474,7 @@ paths:
                   description: Stop the video at this specific timestamp
     delete:
       summary: Delete an element from a playlist
                   description: Stop the video at this specific timestamp
     delete:
       summary: Delete an element from a playlist

+      operationId: delVideoPlaylistVideo

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


@@ -2997,6 +3549,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoChannelList'
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoChannelList'

+

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


@@ -3027,6 +3580,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


@@ -3090,6 +3644,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


@@ -3122,7 +3677,6 @@ paths:
                   maxLength: 10000
               required:
                 - text
                   maxLength: 10000
               required:
                 - text

-

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


@@ -3141,6 +3695,7 @@ paths:
           description: comment or video does not exist
         '409':
           description: comment is already deleted
           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


@@ -3168,11 +3723,76 @@ paths:
           description: successful operation
         '404':
           description: video does not exist
           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
+        '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:
         - name: search
           in: query
       parameters:
         - name: search
           in: query


@@ -3191,7 +3811,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $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'


@@ -3243,38 +3867,115 @@ paths:
                 $ref: '#/components/schemas/VideoListResponse'
         '500':
           description: search index unavailable
                 $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:
+        - 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 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:
+                $ref: '#/components/schemas/VideoChannelList'
+        '500':
+          description: search index unavailable
+
+  /search/video-playlists:
+    get:
+      tags:
+        - Search
+      summary: Search playlists
+      operationId: searchPlaylists

       parameters:
         - name: search
           in: query
       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 channel information and interact with it.
+          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:
           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'
+            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:
       responses:
         '200':
           description: successful operation
           content:

-            application/json:
+            'application/json':

               schema:
               schema:

-                $ref: '#/components/schemas/VideoChannelList'
-        '500':
-          description: search index unavailable
-  /blocklist/accounts:
+                $ref: '#/components/schemas/BlockStatus'
+
+  /server/blocklist/accounts:

     get:
       tags:
         - Account Blocks
     get:
       tags:
         - Account Blocks


@@ -3313,7 +4014,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


@@ -3333,7 +4035,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


@@ -3368,11 +4071,12 @@ paths:
               required:
                 - host
       responses:
               required:
                 - host
       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


@@ -3389,10 +4093,11 @@ paths:
             type: string
             format: hostname
       responses:
             type: string
             format: hostname
       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:
   /server/redundancy/{host}:
     put:
       tags:


@@ -3425,11 +4130,13 @@ paths:
           description: successful operation
         '404':
           description: server is not already known
           description: successful operation
         '404':
           description: server is not already known

+

   /server/redundancy/videos:
     get:
       tags:
         - Video Mirroring
       summary: List videos being mirrored
   /server/redundancy/videos:
     get:
       tags:
         - Video Mirroring
       summary: List videos being mirrored

+      operationId: getMirroredVideos

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3459,6 +4166,7 @@ paths:
       tags:
         - Video Mirroring
       summary: Mirror a video
       tags:
         - Video Mirroring
       summary: Mirror a video

+      operationId: putMirroredVideo

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3481,11 +4189,13 @@ paths:
           description: video does not exist
         '409':
           description: video is already mirrored
           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
   /server/redundancy/videos/{redundancyId}:
     delete:
       tags:
         - Video Mirroring
       summary: Delete a mirror done on a video

+      operationId: delMirroredVideo

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3501,11 +4211,13 @@ paths:
           description: successful operation
         '404':
           description: video redundancy not found
           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
       parameters:
         - name: format
           in: path


@@ -3594,11 +4306,13 @@ paths:
           description: video, video channel or account not found
         '406':
           description: accept header unsupported
           description: video, video channel or account not found
         '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
       parameters:
         - name: format
           in: path


@@ -3636,7 +4350,11 @@ paths:
             type: string
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/nsfw'
             type: string
         - $ref: '#/components/parameters/sort'
         - $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'

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


@@ -3680,12 +4398,14 @@ paths:
           description: video channel or account not found
         '406':
           description: accept header unsupported
           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
   '/feeds/subscriptions.{format}':
     get:
       tags:
         - Feeds
         - Account
       summary: List videos of subscriptions tied to a token

+      operationId: getSyndicatedSubscriptionVideos

       parameters:
         - name: format
           in: path
       parameters:
         - name: format
           in: path


@@ -3715,7 +4435,11 @@ paths:
           required: true
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/nsfw'
           required: true
         - $ref: '#/components/parameters/sort'
         - $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'

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


@@ -3742,11 +4466,13 @@ paths:
                 type: object
         '406':
           description: accept header unsupported
                 type: object
         '406':
           description: accept header unsupported

+

   /plugins:
     get:
       tags:
         - Plugins
       summary: List plugins
   /plugins:
     get:
       tags:
         - Plugins
       summary: List plugins

+      operationId: getPlugins

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3769,11 +4495,13 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PluginResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/PluginResponse'

+

   /plugins/available:
     get:
       tags:
         - Plugins
       summary: List available plugins
   /plugins/available:
     get:
       tags:
         - Plugins
       summary: List available plugins

+      operationId: getAvailablePlugins

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3802,11 +4530,13 @@ paths:
                 $ref: '#/components/schemas/PluginResponse'
         '503':
           description: plugin index unavailable
                 $ref: '#/components/schemas/PluginResponse'
         '503':
           description: plugin index unavailable

+

   /plugins/install:
     post:
       tags:
         - Plugins
       summary: Install a plugin
   /plugins/install:
     post:
       tags:
         - Plugins
       summary: Install a plugin

+      operationId: addPlugin

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3835,11 +4565,13 @@ paths:
           description: successful operation
         '400':
           description: should have either `npmName` or `path` set
           description: successful operation
         '400':
           description: should have either `npmName` or `path` set

+

   /plugins/update:
     post:
       tags:
         - Plugins
       summary: Update a plugin
   /plugins/update:
     post:
       tags:
         - Plugins
       summary: Update a plugin

+      operationId: updatePlugin

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3870,11 +4602,13 @@ paths:
           description: should have either `npmName` or `path` set
         '404':
           description: existing plugin not found
           description: should have either `npmName` or `path` set
         '404':
           description: existing plugin not found

+

   /plugins/uninstall:
     post:
       tags:
         - Plugins
       summary: Uninstall a plugin
   /plugins/uninstall:
     post:
       tags:
         - Plugins
       summary: Uninstall a plugin

+      operationId: uninstallPlugin

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3895,11 +4629,13 @@ paths:
           description: successful operation
         '404':
           description: existing plugin not found
           description: successful operation
         '404':
           description: existing plugin not found

+

   /plugins/{npmName}:
     get:
       tags:
         - Plugins
       summary: Get a plugin
   /plugins/{npmName}:
     get:
       tags:
         - Plugins
       summary: Get a plugin

+      operationId: getPlugin

       security:
         - OAuth2:
           - admin
       security:
         - OAuth2:
           - admin


@@ -3914,6 +4650,7 @@ paths:
                 $ref: '#/components/schemas/Plugin'
         '404':
           description: plugin not found
                 $ref: '#/components/schemas/Plugin'
         '404':
           description: plugin not found

+

   /plugins/{npmName}/settings:
     put:
       tags:
   /plugins/{npmName}/settings:
     put:
       tags:


@@ -3938,6 +4675,7 @@ paths:
           description: successful operation
         '404':
           description: plugin not found
           description: successful operation
         '404':
           description: plugin not found

+

   /plugins/{npmName}/public-settings:
     get:
       tags:
   /plugins/{npmName}/public-settings:
     get:
       tags:


@@ -3955,6 +4693,7 @@ paths:
                 additionalProperties: true
         '404':
           description: plugin not found
                 additionalProperties: true
         '404':
           description: plugin not found

+

   /plugins/{npmName}/registered-settings:
     get:
       tags:
   /plugins/{npmName}/registered-settings:
     get:
       tags:


@@ -3975,6 +4714,7 @@ paths:
                 additionalProperties: true
         '404':
           description: plugin not found
                 additionalProperties: true
         '404':
           description: plugin not found

+

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


@@ -4082,7 +4822,7 @@ 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:
       schema:
         type: string
         enum:


@@ -4139,6 +4879,15 @@ components:
         type: string
         enum:
         - name
         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
     name:
       name: name
       in: path


@@ -4151,18 +4900,19 @@ components:
       name: id
       in: path
       required: true
       name: id
       in: path
       required: true

-      description: The user id
+      description: Entity id

       schema:
         $ref: '#/components/schemas/id'
     idOrUUID:
       name: id
       in: path
       required: true
       schema:
         $ref: '#/components/schemas/id'
     idOrUUID:
       name: id
       in: path
       required: true

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

       schema:
         oneOf:
           - $ref: '#/components/schemas/id'
           - $ref: '#/components/schemas/UUIDv4'
       schema:
         oneOf:
           - $ref: '#/components/schemas/id'
           - $ref: '#/components/schemas/UUIDv4'

+          - $ref: '#/components/schemas/shortUUID'

     playlistId:
       name: playlistId
       in: path
     playlistId:
       name: playlistId
       in: path


@@ -4220,7 +4970,7 @@ components:
       required: true
       description: The thread id (root comment id)
       schema:
       required: true
       description: The thread id (root comment id)
       schema:

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

     commentId:
       name: commentId
       in: path
     commentId:
       name: commentId
       in: path


@@ -4322,20 +5072,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 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)
-         * `all` - all videos, 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


@@ -4370,10 +5158,29 @@ components:
           - video-transcoding
           - video-file-import
           - video-import
           - video-transcoding
           - video-file-import
           - video-import

-          - videos-views
+          - videos-views-stats

           - activitypub-refresher
           - video-redundancy
           - video-live-ending
           - 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:
       description: |
   securitySchemes:
     OAuth2:
       description: |


@@ -4408,6 +5215,10 @@ components:
       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
       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
     username:
       type: string
       description: immutable name of the user, used to find or mention its actor


@@ -4506,6 +5317,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:


@@ -4526,9 +5360,17 @@ components:
       enum:
         - 0
         - 1
       enum:
         - 0
         - 1

-      description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
+      description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'

       example: 1
 
       example: 1
 

+    LiveVideoLatencyMode:
+      type: integer
+      enum:
+        - 1
+        - 2
+        - 3
+      description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
+

     VideoStateConstant:
       properties:
         id:
     VideoStateConstant:
       properties:
         id:


@@ -4608,10 +5450,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

-        avatar:
-          nullable: true
-          allOf:
-            - $ref: '#/components/schemas/ActorImage'
+        avatars:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActorImage'

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


@@ -4626,10 +5468,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

-        avatar:
-          nullable: true
-          allOf:
-            - $ref: '#/components/schemas/ActorImage'
+        avatars:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActorImage'

     PlaylistElement:
       properties:
         position:
     PlaylistElement:
       properties:
         position:


@@ -4651,7 +5493,6 @@ components:
           type: string
           format: uri
           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
           type: string
           format: uri
           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file

-          example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4

           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         resolution:
           $ref: '#/components/schemas/VideoResolutionConstant'
           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         resolution:
           $ref: '#/components/schemas/VideoResolutionConstant'


@@ -4737,6 +5578,9 @@ components:
           description: universal identifier for the video, that can be used across instances
           allOf:
             - $ref: '#/components/schemas/UUIDv4'
           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:
         isLive:
           type: boolean
         createdAt:


@@ -4850,6 +5694,9 @@ 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
               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
             descriptionPath:
               type: string
               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description


@@ -4998,7 +5845,6 @@ components:
           type: string
           format: uri
           description: magnet URI allowing to resolve the import's source video
           type: string
           format: uri
           description: magnet URI allowing to resolve the import's source video

-          example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4

           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         torrentfile:
           writeOnly: true
           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         torrentfile:
           writeOnly: true


@@ -5116,6 +5962,9 @@ components:
           $ref: '#/components/schemas/id'
         uuid:
           $ref: '#/components/schemas/UUIDv4'
           $ref: '#/components/schemas/id'
         uuid:
           $ref: '#/components/schemas/UUIDv4'

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

         createdAt:
           type: string
           format: date-time
         createdAt:
           type: string
           format: date-time


@@ -5206,6 +6055,8 @@ components:
       properties:
         path:
           type: string
       properties:
         path:
           type: string

+        width:
+          type: integer

         createdAt:
           type: string
           format: date-time
         createdAt:
           type: string
           format: date-time


@@ -5223,12 +6074,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

-        avatar:
-          nullable: true
-          type: object
-          properties:
-            path:
-              type: string
+        avatars:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActorImage'

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


@@ -5261,8 +6110,6 @@ components:
         updatedAt:
           type: string
           format: date-time
         updatedAt:
           type: string
           format: date-time

-        avatar:
-          $ref: '#/components/schemas/ActorImage'

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


@@ -5279,13 +6126,76 @@ components:
             description:
               type: string
               description: text or bio displayed on the account's profile
             description:
               type: string
               description: text or bio displayed on the account's profile

-    UserWatchingVideo:
+    UserViewingVideo:
+      required:
+        - currentTime

       properties:
         currentTime:
           type: integer
           format: seconds
           description: timestamp within the video, in seconds
           example: 5
       properties:
         currentTime:
           type: integer
           format: seconds
           description: timestamp within the video, in seconds
           example: 5

+        viewEvent:
+          type: string
+          enum:
+            - seek
+          description: >
+            Event since last viewing call:
+             * `seek` - If the user seeked the video
+
+    VideoStatsOverall:
+      properties:
+        averageWatchTime:
+          type: number
+        totalWatchTime:
+          type: number
+        viewersPeak:
+          type: number
+        viewersPeakDate:
+          type: string
+          format: date-time
+        views:
+          type: number
+        likes:
+          type: number
+        dislikes:
+          type: number
+        comments:
+          type: number
+        countries:
+          type: array
+          items:
+            type: object
+            properties:
+              isoCode:
+                type: string
+              viewers:
+                type: number
+
+    VideoStatsRetention:
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+            properties:
+              second:
+                type: number
+              retentionPercent:
+                type: number
+
+    VideoStatsTimeserie:
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+            properties:
+              date:
+                type: string
+              value:
+                type: number
+

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


@@ -5485,6 +6395,12 @@ components:
                     indexUrl:
                       type: string
                       format: url
                     indexUrl:
                       type: string
                       format: url

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

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


@@ -5612,6 +6528,8 @@ components:
               properties:
                 0p:
                   type: boolean
               properties:
                 0p:
                   type: boolean

+                144p:
+                  type: boolean

                 240p:
                   type: boolean
                 360p:
                 240p:
                   type: boolean
                 360p:


@@ -5675,6 +6593,12 @@ components:
                   type: boolean
                 manualApproval:
                   type: boolean
                   type: boolean
                 manualApproval:
                   type: boolean

+
+    CustomHomepage:
+      properties:
+        content:
+          type: string
+

     Follow:
       properties:
         id:
     Follow:
       properties:
         id:


@@ -5737,7 +6661,7 @@ components:
             - video-transcoding
             - email
             - video-import
             - video-transcoding
             - email
             - video-import

-            - videos-views
+            - videos-views-stats

             - activitypub-refresher
             - video-redundancy
         data:
             - activitypub-refresher
             - video-redundancy
         data:


@@ -5879,6 +6803,8 @@ components:
               $ref: '#/components/schemas/Video/properties/id'
             uuid:
               $ref: '#/components/schemas/Video/properties/uuid'
               $ref: '#/components/schemas/Video/properties/id'
             uuid:
               $ref: '#/components/schemas/Video/properties/uuid'

+            shortUUID:
+              $ref: '#/components/schemas/Video/properties/shortUUID'

     CommentThreadResponse:
       properties:
         total:
     CommentThreadResponse:
       properties:
         total:


@@ -5941,6 +6867,8 @@ components:
           format: date-time
         noInstanceConfigWarningModal:
           type: boolean
           format: date-time
         noInstanceConfigWarningModal:
           type: boolean

+        noAccountSetupWarningModal:
+          type: boolean

         noWelcomeModal:
           type: boolean
         nsfwPolicy:
         noWelcomeModal:
           type: boolean
         nsfwPolicy:


@@ -5970,7 +6898,7 @@ components:
           type: integer
           description: The user daily video quota in bytes
           example: -1
           type: integer
           description: The user daily video quota in bytes
           example: -1

-        webtorrentEnabled:
+        p2pEnabled:

           type: boolean
           description: Enable P2P in the player
     UserWithStats:
           type: boolean
           description: Enable P2P in the player
     UserWithStats:


@@ -5980,7 +6908,7 @@ components:
             # optionally present fields: they require WITH_STATS scope
             videosCount:
               type: integer
             # optionally present fields: they require WITH_STATS scope
             videosCount:
               type: integer

-              description: Count of videos published 
+              description: Count of videos published

             abusesCount:
               type: integer
               description: Count of reports/abuses of which the user is a target
             abusesCount:
               type: integer
               description: Count of reports/abuses of which the user is a target


@@ -6048,6 +6976,8 @@ components:
           $ref: '#/components/schemas/UserRole'
         adminFlags:
           $ref: '#/components/schemas/UserAdminFlags'
           $ref: '#/components/schemas/UserRole'
         adminFlags:
           $ref: '#/components/schemas/UserAdminFlags'

+        password:
+          $ref: '#/components/schemas/password'

     UpdateMe:
       # see shared/models/users/user-update-me.model.ts:
       properties:
     UpdateMe:
       # see shared/models/users/user-update-me.model.ts:
       properties:


@@ -6071,7 +7001,7 @@ components:
             - 'true'
             - 'false'
             - both
             - 'true'
             - 'false'
             - both

-        webTorrentEnabled:
+        p2pEnabled:

           type: boolean
           description: whether to enable P2P in the player or not
         autoPlayVideo:
           type: boolean
           description: whether to enable P2P in the player or not
         autoPlayVideo:


@@ -6095,6 +7025,8 @@ components:
           type: string
         noInstanceConfigWarningModal:
           type: boolean
           type: string
         noInstanceConfigWarningModal:
           type: boolean

+        noAccountSetupWarningModal:
+          type: boolean

         noWelcomeModal:
           type: boolean
     GetMeVideoRating:
         noWelcomeModal:
           type: boolean
     GetMeVideoRating:


@@ -6149,7 +7081,7 @@ components:
             name:
               $ref: '#/components/schemas/usernameChannel'
             displayName:
             name:
               $ref: '#/components/schemas/usernameChannel'
             displayName:

-              $ref: '#/components/schemas/VideoChannel/properties/displayName'
+              type: string

       required:
         - username
         - password
       required:
         - username
         - password


@@ -6211,46 +7143,47 @@ components:
         - refresh_token
 
     VideoChannel:
         - refresh_token
 
     VideoChannel:

-      properties:
-        # GET/POST/PUT properties
-        displayName:
-          type: string
-          description: editable name of the channel, displayed in its representations
-          example: Videos of Framasoft
-          minLength: 1
-          maxLength: 120
-        description:
-          type: string
-          example: Videos made with <3 by Framasoft
-          minLength: 3
-          maxLength: 1000
-        support:
-          type: string
-          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
+      allOf:
+        - $ref: '#/components/schemas/Actor'
+        - type: object

           properties:
           properties:

-            id:
-              type: integer
-            uuid:
-              $ref: '#/components/schemas/UUIDv4'
+            displayName:
+              type: string
+              description: editable name of the channel, displayed in its representations
+              example: Videos of Framasoft
+              minLength: 1
+              maxLength: 120
+            description:
+              type: string
+              example: Videos made with <3 by Framasoft
+              minLength: 3
+              maxLength: 1000
+            support:
+              type: string
+              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
+            isLocal:
+              readOnly: true
+              type: boolean
+            updatedAt:
+              readOnly: true
+              type: string
+              format: date-time
+            banners:
+              type: array
+              items:
+                $ref: '#/components/schemas/ActorImage'
+            ownerAccount:
+              readOnly: true
+              nullable: true
+              type: object
+              properties:
+                id:
+                  type: integer
+                uuid:
+                  $ref: '#/components/schemas/UUIDv4'

     VideoChannelCreate:
       allOf:
         - $ref: '#/components/schemas/VideoChannel'
     VideoChannelCreate:
       allOf:
         - $ref: '#/components/schemas/VideoChannel'


@@ -6480,7 +7413,7 @@ components:
       enum:
         - 0
         - 1
       enum:
         - 0
         - 1

-        - 3
+        - 2

     Notification:
       properties:
         id:
     Notification:
       properties:
         id:


@@ -6517,6 +7450,14 @@ components:
             - `13` NEW_INSTANCE_FOLLOWER
 
             - `14` AUTO_INSTANCE_FOLLOWING
             - `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:
         read:
           type: boolean
         video:


@@ -6684,11 +7625,16 @@ components:
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean

+        latencyMode:
+          description: User can select live latency mode if enabled by the instance
+          $ref: '#/components/schemas/LiveVideoLatencyMode'

 
     LiveVideoResponse:
       properties:
         rtmpUrl:
           type: string
 
     LiveVideoResponse:
       properties:
         rtmpUrl:
           type: string

+        rtmpsUrl:
+          type: string

         streamKey:
           type: string
           description: RTMP stream key to use to stream into this live video
         streamKey:
           type: string
           description: RTMP stream key to use to stream into this live video


@@ -6697,8 +7643,9 @@ components:
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean

-
-
+        latencyMode:
+          description: User can select live latency mode if enabled by the instance
+          $ref: '#/components/schemas/LiveVideoLatencyMode'

 
   callbacks:
     searchIndex:
 
   callbacks:
     searchIndex: