projects / oweals / peertube.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Bumped to version v2.2.0-rc.1
[oweals/peertube.git] / support / doc / api / openapi.yaml
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index b1e5f90f861e935870786b6bd71a74a57ad20151..6787679cfba64ee087cdba2a81bfc179f2ba5feb 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: 2.1.0
+  version: 2.2.0-rc.1
   contact:
     name: PeerTube Community
     url: 'https://joinpeertube.org'
   contact:
     name: PeerTube Community
     url: 'https://joinpeertube.org'
@@ -13,20 +13,23 @@ info:
     altText: PeerTube Project Homepage
   description: |
     # Introduction
     altText: PeerTube Project Homepage
   description: |
     # Introduction
-    The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
-    resource URLs. It returns HTTP response codes to indicate errors. It also
-    accepts and returns JSON in the HTTP body. You can use your favorite
+
+    The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
     HTTP/REST library for your programming language to use PeerTube. No official
     SDK is currently provided, but the spec API is fully compatible with
     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
     which generates a client SDK in the language of your choice.
 
     HTTP/REST library for your programming language to use PeerTube. No official
     SDK is currently provided, but the spec API is fully compatible with
     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
     which generates a client SDK in the language of your choice.
 
+    See the [Quick Start guide](https://docs.joinpeertube.org/#/api-rest-getting-started) so you can play with the PeerTube API.
+
     # Authentication
     # Authentication
+
     When you sign up for an account, you are given the possibility to generate
     sessions, and authenticate using this session token. One session token can
     currently be used at a time.
 
     # Errors
     When you sign up for an account, you are given the possibility to generate
     sessions, and authenticate using this session token. One session token can
     currently be used at a time.
 
     # Errors
+
     The API uses standard HTTP status codes to indicate the success or failure
     of the API call. The body of the response will be JSON in the following
     format.
     The API uses standard HTTP status codes to indicate the success or failure
     of the API call. The body of the response will be JSON in the following
     format.
@@ -53,14 +56,14 @@ tags:
     description: >
       Jobs are long-running tasks enqueued and processed by the instance
       itself. No additional worker registration is currently available.
     description: >
       Jobs are long-running tasks enqueued and processed by the instance
       itself. No additional worker registration is currently available.
-  - name: Server Following
+  - name: Instance Follows
     description: >
       Managing servers which the instance interacts with is crucial to the
       concept of federation in PeerTube and external video indexation. The PeerTube
       server then deals with inter-server ActivityPub operations and propagates
       information across its social graph by posting activities to actors' inbox
       endpoints.
     description: >
       Managing servers which the instance interacts with is crucial to the
       concept of federation in PeerTube and external video indexation. The PeerTube
       server then deals with inter-server ActivityPub operations and propagates
       information across its social graph by posting activities to actors' inbox
       endpoints.
-  - name: Video Abuse
+  - name: Video Abuses
     description: |
       Video abuses deal with reports of local or remote videos alike.
   - name: Video
     description: |
       Video abuses deal with reports of local or remote videos alike.
   - name: Video
@@ -72,15 +75,15 @@ tags:
       Videos from other instances federated by the instance (that is, instances
       followed by the instance) can be found via keywords and other criteria of
       the advanced search.
       Videos from other instances federated by the instance (that is, instances
       followed by the instance) can be found via keywords and other criteria of
       the advanced search.
-  - name: Video Comment
+  - name: Video Comments
     description: >
       Operations dealing with comments to a video. Comments are organized in
       threads.
     description: >
       Operations dealing with comments to a video. Comments are organized in
       threads.
-  - name: Video Playlist
+  - name: Video Playlists
     description: >
       Operations dealing with playlists of videos. Playlists are bound to users
       and/or channels.
     description: >
       Operations dealing with playlists of videos. Playlists are bound to users
       and/or channels.
-  - name: Video Channel
+  - name: Video Channels
     description: >
       Operations dealing with creation, modification and video listing of a
       user's channels.
     description: >
       Operations dealing with creation, modification and video listing of a
       user's channels.
@@ -88,43 +91,46 @@ tags:
     description: >
       Operations dealing with blacklisting videos (removing them from view and
       preventing interactions).
     description: >
       Operations dealing with blacklisting videos (removing them from view and
       preventing interactions).
-  - name: Video Rate
+  - name: Video Rates
     description: >
     description: >
-      Voting for a video.
+      Like/dislike a video.
 x-tagGroups:
   - name: Accounts
     tags:
       - Accounts
 x-tagGroups:
   - name: Accounts
     tags:
       - Accounts
-      - User
+      - Users
       - My User
       - My User
+      - My Subscriptions
   - name: Videos
     tags:
       - Video
       - Video Caption
   - name: Videos
     tags:
       - Video
       - Video Caption
-      - Video Channel
-      - Video Comment
+      - Video Channels
+      - Video Comments
       - Video Following
       - Video Following
-      - Video Rate
+      - Video Rates
+      - Video Playlists
+      - Video Ownership Change
+  - name: Search
+    tags:
+      - Search
   - name: Moderation
     tags:
   - name: Moderation
     tags:
-      - Video Abuse
+      - Video Abuses
       - Video Blacklist
   - name: Instance Configuration
     tags:
       - Config
       - Video Blacklist
   - name: Instance Configuration
     tags:
       - Config
-      - Server Following
+      - Instance Follows
   - name: Jobs
     tags:
       - Job
   - name: Jobs
     tags:
       - Job
-  - name: Search
-    tags:
-      - Search
 paths:
   '/accounts/{name}':
     get:
       tags:
         - Accounts
 paths:
   '/accounts/{name}':
     get:
       tags:
         - Accounts
-      summary: Get the account by name
+      summary: Get an account
       parameters:
         - $ref: '#/components/parameters/name'
       responses:
       parameters:
         - $ref: '#/components/parameters/name'
       responses:
@@ -139,9 +145,20 @@ paths:
       tags:
         - Accounts
         - Video
       tags:
         - Accounts
         - Video
-      summary: 'Get videos for an account, provided the name of that account'
+      summary: 'List videos of an account'
       parameters:
         - $ref: '#/components/parameters/name'
       parameters:
         - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/categoryOneOf'
+        - $ref: '#/components/parameters/tagsOneOf'
+        - $ref: '#/components/parameters/tagsAllOf'
+        - $ref: '#/components/parameters/licenceOneOf'
+        - $ref: '#/components/parameters/languageOneOf'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/skipCount'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/videosSort'
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation
@@ -187,7 +204,7 @@ paths:
     get:
       tags:
         - Accounts
     get:
       tags:
         - Accounts
-      summary: Get all accounts
+      summary: List accounts
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -205,7 +222,7 @@ paths:
     get:
       tags:
         - Config
     get:
       tags:
         - Config
-      summary: Get the public configuration of the server
+      summary: Get instance public configuration
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation
@@ -215,7 +232,7 @@ paths:
                 $ref: '#/components/schemas/ServerConfig'
   /config/about:
     get:
                 $ref: '#/components/schemas/ServerConfig'
   /config/about:
     get:
-      summary: Get the instance about page content
+      summary: Get instance "About" information
       tags:
         - Config
       responses:
       tags:
         - Config
       responses:
@@ -227,7 +244,7 @@ paths:
                 $ref: '#/components/schemas/ServerConfigAbout'
   /config/custom:
     get:
                 $ref: '#/components/schemas/ServerConfigAbout'
   /config/custom:
     get:
-      summary: Get the runtime configuration of the server
+      summary: Get instance runtime configuration
       tags:
         - Config
       security:
       tags:
         - Config
       security:
@@ -241,7 +258,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/ServerConfigCustom'
     put:
               schema:
                 $ref: '#/components/schemas/ServerConfigCustom'
     put:
-      summary: Set the runtime configuration of the server
+      summary: Set instance runtime configuration
       tags:
         - Config
       security:
       tags:
         - Config
       security:
@@ -251,7 +268,7 @@ paths:
         '200':
           description: successful operation
     delete:
         '200':
           description: successful operation
     delete:
-      summary: Delete the runtime configuration of the server
+      summary: Delete instance runtime configuration
       tags:
         - Config
       security:
       tags:
         - Config
       security:
@@ -262,7 +279,7 @@ paths:
           description: successful operation
   /jobs/{state}:
     get:
           description: successful operation
   /jobs/{state}:
     get:
-      summary: Get list of jobs
+      summary: List instance jobs
       security:
         - OAuth2:
             - admin
       security:
         - OAuth2:
             - admin
@@ -299,8 +316,8 @@ paths:
         - OAuth2:
             - admin
       tags:
         - OAuth2:
             - admin
       tags:
-        - Server Following
-      summary: Unfollow a server by hostname
+        - Instance Follows
+      summary: Unfollow a server
       parameters:
         - name: host
           in: path
       parameters:
         - name: host
           in: path
@@ -314,8 +331,8 @@ paths:
   /server/followers:
     get:
       tags:
   /server/followers:
     get:
       tags:
-        - Server Following
-      summary: Get followers of the server
+        - Instance Follows
+      summary: List instance followers
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -332,8 +349,8 @@ paths:
   /server/following:
     get:
       tags:
   /server/following:
     get:
       tags:
-        - Server Following
-      summary: Get servers followed by the server
+        - Instance Follows
+      summary: List instance followings
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -352,11 +369,11 @@ paths:
         - OAuth2:
             - admin
       tags:
         - OAuth2:
             - admin
       tags:
-        - Server Following
+        - Instance Follows
       summary: Follow a server
       responses:
         '204':
       summary: Follow a server
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:
@@ -364,12 +381,12 @@ paths:
               $ref: '#/components/schemas/Follow'
   /users:
     post:
               $ref: '#/components/schemas/Follow'
   /users:
     post:
-      summary: Creates user
+      summary: Create a user
       security:
         - OAuth2:
             - admin
       tags:
       security:
         - OAuth2:
             - admin
       tags:
-        - User
+        - Users
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation
@@ -385,11 +402,11 @@ paths:
         description: User to create
         required: true
     get:
         description: User to create
         required: true
     get:
-      summary: Get a list of users
+      summary: List users
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - User
+        - Users
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -405,23 +422,23 @@ paths:
                   $ref: '#/components/schemas/User'
   '/users/{id}':
     delete:
                   $ref: '#/components/schemas/User'
   '/users/{id}':
     delete:
-      summary: Delete a user by its id
+      summary: Delete a user
       security:
         - OAuth2:
             - admin
       tags:
       security:
         - OAuth2:
             - admin
       tags:
-        - User
+        - Users
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
         '204':
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
     get:
     get:
-      summary: Get user by its id
+      summary: Get a user
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - User
+        - Users
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
@@ -432,16 +449,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/User'
     put:
               schema:
                 $ref: '#/components/schemas/User'
     put:
-      summary: Update user profile by its id
+      summary: Update a user
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - User
+        - Users
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
         '204':
       parameters:
         - $ref: '#/components/parameters/id'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:
@@ -452,10 +469,10 @@ paths:
     post:
       summary: Register a user
       tags:
     post:
       summary: Register a user
       tags:
-        - User
+        - Users
       responses:
         '204':
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
       requestBody:
         content:
           application/json:
       requestBody:
         content:
           application/json:
@@ -464,7 +481,7 @@ paths:
         required: true
   /users/me:
     get:
         required: true
   /users/me:
     get:
-      summary: Get current user information
+      summary: Get my user information
       security:
         - OAuth2:
           - user
       security:
         - OAuth2:
           - user
@@ -480,7 +497,7 @@ paths:
                 items:
                   $ref: '#/components/schemas/User'
     put:
                 items:
                   $ref: '#/components/schemas/User'
     put:
-      summary: Update current user information
+      summary: Update my user information
       security:
         - OAuth2:
           - user
       security:
         - OAuth2:
           - user
@@ -497,11 +514,12 @@ paths:
         required: true
   /users/me/videos/imports:
     get:
         required: true
   /users/me/videos/imports:
     get:
-      summary: Get video imports of current user
+      summary: Get video imports of my user
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
+        - Videos
         - My User
       parameters:
         - $ref: '#/components/parameters/start'
         - My User
       parameters:
         - $ref: '#/components/parameters/start'
@@ -516,7 +534,7 @@ paths:
                 $ref: '#/components/schemas/VideoImport'
   /users/me/video-quota-used:
     get:
                 $ref: '#/components/schemas/VideoImport'
   /users/me/video-quota-used:
     get:
-      summary: Get current user used quota
+      summary: Get my user used quota
       security:
         - OAuth2:
           - user
       security:
         - OAuth2:
           - user
@@ -531,11 +549,12 @@ paths:
                 type: number
   '/users/me/videos/{videoId}/rating':
     get:
                 type: number
   '/users/me/videos/{videoId}/rating':
     get:
-      summary: 'Get rating of video by its id, among those of the current user'
+      summary: Get rate of my user for a video
       security:
         - OAuth2: []
       tags:
         - My User
       security:
         - OAuth2: []
       tags:
         - My User
+        - Video Rates
       parameters:
         - name: videoId
           in: path
       parameters:
         - name: videoId
           in: path
@@ -552,12 +571,13 @@ paths:
                 $ref: '#/components/schemas/GetMeVideoRating'
   /users/me/videos:
     get:
                 $ref: '#/components/schemas/GetMeVideoRating'
   /users/me/videos:
     get:
-      summary: Get videos of the current user
+      summary: Get videos of my user
       security:
         - OAuth2:
           - user
       tags:
         - My User
       security:
         - OAuth2:
           - user
       tags:
         - My User
+        - Videos
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -571,12 +591,12 @@ paths:
                 $ref: '#/components/schemas/VideoListResponse'
   /users/me/subscriptions:
     get:
                 $ref: '#/components/schemas/VideoListResponse'
   /users/me/subscriptions:
     get:
-      summary: Get subscriptions of the current user
+      summary: Get my user subscriptions
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
-        - My User
+        - My Subscriptions
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -585,23 +605,23 @@ paths:
         '200':
           description: successful operation
     post:
         '200':
           description: successful operation
     post:
-      summary: Add subscription to the current user
+      summary: Add subscription to my user
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
-        - My User
+        - My Subscriptions
       responses:
         '200':
           description: successful operation
   /users/me/subscriptions/exist:
     get:
       responses:
         '200':
           description: successful operation
   /users/me/subscriptions/exist:
     get:
-      summary: Get if subscriptions exist for the current user
+      summary: Get if subscriptions exist for my user
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
-        - My User
+        - My Subscriptions
       parameters:
         - $ref: '#/components/parameters/subscriptionsUris'
       responses:
       parameters:
         - $ref: '#/components/parameters/subscriptionsUris'
       responses:
@@ -613,16 +633,25 @@ paths:
                 type: object
   /users/me/subscriptions/videos:
     get:
                 type: object
   /users/me/subscriptions/videos:
     get:
-      summary: Get videos of subscriptions of the current user
+      summary: List videos of subscriptions of my user
       security:
         - OAuth2:
           - user
       tags:
       security:
         - OAuth2:
           - user
       tags:
-        - My User
+        - My Subscriptions
+        - Videos
       parameters:
       parameters:
+        - $ref: '#/components/parameters/categoryOneOf'
+        - $ref: '#/components/parameters/tagsOneOf'
+        - $ref: '#/components/parameters/tagsAllOf'
+        - $ref: '#/components/parameters/licenceOneOf'
+        - $ref: '#/components/parameters/languageOneOf'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/videosSort'
       responses:
         '200':
           description: successful operation
       responses:
         '200':
           description: successful operation
@@ -632,12 +661,12 @@ paths:
                 $ref: '#/components/schemas/VideoListResponse'
   '/users/me/subscriptions/{subscriptionHandle}':
     get:
                 $ref: '#/components/schemas/VideoListResponse'
   '/users/me/subscriptions/{subscriptionHandle}':
     get:
-      summary: Get subscription of the current user for a given uri
+      summary: Get subscription of my user
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
-        - My User
+        - My Subscriptions
       parameters:
         - $ref: '#/components/parameters/subscriptionHandle'
       responses:
       parameters:
         - $ref: '#/components/parameters/subscriptionHandle'
       responses:
@@ -648,12 +677,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoChannel'
     delete:
               schema:
                 $ref: '#/components/schemas/VideoChannel'
     delete:
-      summary: Delete subscription of the current user for a given uri
+      summary: Delete subscription of my user
       security:
         - OAuth2:
             - user
       tags:
       security:
         - OAuth2:
             - user
       tags:
-        - My User
+        - My Subscriptions
       parameters:
         - $ref: '#/components/parameters/subscriptionHandle'
       responses:
       parameters:
         - $ref: '#/components/parameters/subscriptionHandle'
       responses:
@@ -661,7 +690,7 @@ paths:
           description: successful operation
   /users/me/avatar/pick:
     post:
           description: successful operation
   /users/me/avatar/pick:
     post:
-      summary: Update current user avatar
+      summary: Update my user avatar
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
@@ -686,9 +715,68 @@ paths:
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg
             encoding:
               avatarfile:
                 contentType: image/png, image/jpeg
+  /videos/ownership:
+    get:
+      summary: List video ownership changes
+      tags:
+        - Video Ownership Change
+      security:
+        - OAuth2: []
+      responses:
+        '200':
+          description: successful operation
+  '/videos/ownership/{id}/accept':
+    post:
+      summary: Accept ownership change request
+      tags:
+        - Video Ownership Change
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+  '/videos/ownership/{id}/refuse':
+    post:
+      summary: Refuse ownership change request
+      tags:
+        - Video Ownership Change
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+  '/videos/{id}/give-ownership':
+    post:
+      summary: Request ownership change
+      tags:
+        - Video Ownership Change
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                username:
+                  type: string
+              required:
+                - username
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: 'Changing video ownership to a remote account is not supported yet'
   /videos:
     get:
   /videos:
     get:
-      summary: Get list of videos
+      summary: List videos
       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:
@@ -699,6 +787,7 @@ paths:
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/filter'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
         - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/videosSort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/videosSort'
@@ -711,7 +800,7 @@ paths:
                 $ref: '#/components/schemas/VideoListResponse'
   /videos/categories:
     get:
                 $ref: '#/components/schemas/VideoListResponse'
   /videos/categories:
     get:
-      summary: Get list of video categories known by the server
+      summary: List available video categories
       tags:
         - Video
       responses:
       tags:
         - Video
       responses:
@@ -725,7 +814,7 @@ paths:
                   type: string
   /videos/licences:
     get:
                   type: string
   /videos/licences:
     get:
-      summary: Get list of video licences known by the server
+      summary: List available video licences
       tags:
         - Video
       responses:
       tags:
         - Video
       responses:
@@ -739,7 +828,7 @@ paths:
                   type: string
   /videos/languages:
     get:
                   type: string
   /videos/languages:
     get:
-      summary: Get list of languages known by the server
+      summary: List available video languages
       tags:
         - Video
       responses:
       tags:
         - Video
       responses:
@@ -753,7 +842,7 @@ paths:
                   type: string
   /videos/privacies:
     get:
                   type: string
   /videos/privacies:
     get:
-      summary: Get list of privacy policies supported by the server
+      summary: List available video privacies
       tags:
         - Video
       responses:
       tags:
         - Video
       responses:
@@ -767,7 +856,7 @@ paths:
                   type: string
   '/videos/{id}':
     put:
                   type: string
   '/videos/{id}':
     put:
-      summary: Update metadata for a video by its id
+      summary: Update a video
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
@@ -800,6 +889,8 @@ paths:
                 language:
                   description: Video language
                   type: string
                 language:
                   description: Video language
                   type: string
+                privacy:
+                  $ref: '#/components/schemas/VideoPrivacySet'
                 description:
                   description: Video description
                   type: string
                 description:
                   description: Video description
                   type: string
@@ -839,7 +930,7 @@ paths:
               previewfile:
                 contentType: image/jpeg
     get:
               previewfile:
                 contentType: image/jpeg
     get:
-      summary: Get a video by its id
+      summary: Get a video
       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:
@@ -852,7 +943,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoDetails'
     delete:
               schema:
                 $ref: '#/components/schemas/VideoDetails'
     delete:
-      summary: Delete a video by its id
+      summary: Delete a video
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
@@ -861,10 +952,10 @@ paths:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
   '/videos/{id}/description':
     get:
   '/videos/{id}/description':
     get:
-      summary: Get a video description by its id
+      summary: Get complete video description
       tags:
         - Video
       parameters:
       tags:
         - Video
       parameters:
@@ -878,17 +969,17 @@ paths:
                 type: string
   '/videos/{id}/views':
     post:
                 type: string
   '/videos/{id}/views':
     post:
-      summary: Add a view to the video by its id
+      summary: Add a view to a video
       tags:
         - Video
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
       tags:
         - Video
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
   '/videos/{id}/watching':
     put:
   '/videos/{id}/watching':
     put:
-      summary: Set watching progress of a video by its id for a user
+      summary: Set watching progress of a video
       tags:
         - Video
       security:
       tags:
         - Video
       security:
@@ -903,69 +994,10 @@ paths:
         required: true
       responses:
         '204':
         required: true
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-  /videos/ownership:
-    get:
-      summary: Get list of video ownership changes requests
-      tags:
-        - Video
-      security:
-        - OAuth2: []
-      responses:
-        '200':
           description: successful operation
           description: successful operation
-  '/videos/ownership/{id}/accept':
-    post:
-      summary: Refuse ownership change request for video by its id
-      tags:
-        - Video
-      security:
-        - OAuth2: []
-      parameters:
-        - $ref: '#/components/parameters/idOrUUID'
-      responses:
-        '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-  '/videos/ownership/{id}/refuse':
-    post:
-      summary: Accept ownership change request for video by its id
-      tags:
-        - Video
-      security:
-        - OAuth2: []
-      parameters:
-        - $ref: '#/components/parameters/idOrUUID'
-      responses:
-        '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-  '/videos/{id}/give-ownership':
-    post:
-      summary: Request change of ownership for a video you own, by its id
-      tags:
-        - Video
-      security:
-        - OAuth2: []
-      parameters:
-        - $ref: '#/components/parameters/idOrUUID'
-      requestBody:
-        required: true
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                username:
-                  type: string
-              required:
-                - username
-      responses:
-        '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-        '400':
-          description: 'Changing video ownership to a remote account is not supported yet'
   /videos/upload:
     post:
   /videos/upload:
     post:
-      summary: Upload a video file with its metadata
+      summary: Upload a video
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
@@ -1087,7 +1119,8 @@ paths:
               "Authorization:Bearer $token"
   /videos/imports:
     post:
               "Authorization:Bearer $token"
   /videos/imports:
     post:
-      summary: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
+      summary: Import a video
+      description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
@@ -1178,11 +1211,13 @@ paths:
                 contentType: image/jpeg
   /videos/abuse:
     get:
                 contentType: image/jpeg
   /videos/abuse:
     get:
-      summary: Get list of reported video abuses
+      summary: List video abuses
       security:
       security:
-        - OAuth2: []
+        - OAuth2:
+            - admin
+            - moderator
       tags:
       tags:
-        - Video Abuse
+        - Video Abuses
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
       parameters:
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -1198,19 +1233,70 @@ paths:
                   $ref: '#/components/schemas/VideoAbuse'
   '/videos/{id}/abuse':
     post:
                   $ref: '#/components/schemas/VideoAbuse'
   '/videos/{id}/abuse':
     post:
-      summary: 'Report an abuse, on a video by its id'
+      summary: Report an abuse
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Abuse
+        - Video Abuses
+        - Videos
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  description: Reason why the user reports this video
+                  type: string
+      responses:
+        '204':
+          description: successful operation
+  '/videos/{id}/abuse/{abuseId}':
+    put:
+      summary: Update an abuse
+      security:
+        - OAuth2:
+          - admin
+          - moderator
+      tags:
+        - Video Abuses
       responses:
         '204':
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/abuseId'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                state:
+                  $ref: '#/components/schemas/VideoAbuseStateSet'
+                moderationComment:
+                  type: string
+                  description: 'Update the comment of the video abuse for other admin/moderators'
+    delete:
+      summary: Delete an abuse
+      security:
+        - OAuth2:
+            - admin
+            - moderator
+      tags:
+        - Video Abuses
+      responses:
+        '204':
+          description: successful operation
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/abuseId'
+
   '/videos/{id}/blacklist':
     post:
   '/videos/{id}/blacklist':
     post:
-      summary: Put on blacklist a video by its id
+      summary: Blacklist a video
       security:
         - OAuth2:
             - admin
       security:
         - OAuth2:
             - admin
@@ -1221,7 +1307,7 @@ paths:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
     delete:
       summary: Delete an entry of the blacklist of a video by its id
       security:
     delete:
       summary: Delete an entry of the blacklist of a video by its id
       security:
@@ -1234,10 +1320,10 @@ paths:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
   /videos/blacklist:
     get:
   /videos/blacklist:
     get:
-      summary: Get list of videos on blacklist
+      summary: List blacklisted videos
       security:
         - OAuth2:
             - admin
       security:
         - OAuth2:
             - admin
@@ -1259,7 +1345,7 @@ paths:
                   $ref: '#/components/schemas/VideoBlacklist'
   /videos/{id}/captions:
     get:
                   $ref: '#/components/schemas/VideoBlacklist'
   /videos/{id}/captions:
     get:
-      summary: Get list of video's captions
+      summary: List captions of a video
       tags:
         - Video Caption
       parameters:
       tags:
         - Video Caption
       parameters:
@@ -1301,128 +1387,423 @@ paths:
                 contentType: text/vtt, application/x-subrip, text/plain
       responses:
         '204':
                 contentType: text/vtt, application/x-subrip, text/plain
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
     delete:
       summary: Delete a video caption
       tags:
     delete:
       summary: Delete a video caption
       tags:
-        - Video Caption
+        - Video Caption
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/captionLanguage'
+      responses:
+        '204':
+          description: successful operation
+  /video-channels:
+    get:
+      summary: List video channels
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/VideoChannel'
+    post:
+      summary: Create a video channel
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      responses:
+        '204':
+          description: successful operation
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelCreate'
+  '/video-channels/{channelHandle}':
+    get:
+      summary: Get a video channel
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoChannel'
+    put:
+      summary: Update a video channel
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '204':
+          description: successful operation
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoChannelUpdate'
+    delete:
+      summary: Delete a video channel
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '204':
+          description: successful operation
+  '/video-channels/{channelHandle}/videos':
+    get:
+      summary: List videos of a video channel
+      tags:
+        - Video
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/categoryOneOf'
+        - $ref: '#/components/parameters/tagsOneOf'
+        - $ref: '#/components/parameters/tagsAllOf'
+        - $ref: '#/components/parameters/licenceOneOf'
+        - $ref: '#/components/parameters/languageOneOf'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/skipCount'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/videosSort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoListResponse'
+
+  /video-playlists/privacies:
+    get:
+      summary: List available playlist privacies
+      tags:
+        - Video Playlists
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+
+  /video-playlists:
+    get:
+      summary: List video playlists
+      tags:
+        - Video Playlists
+      parameters:
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/sort'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/VideoPlaylist'
+    post:
+      summary: Create a video playlist
+      description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
+      security:
+        - OAuth2: []
+      tags:
+        - Video Playlists
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  videoPlaylist:
+                    type: object
+                    properties:
+                      id:
+                        type: number
+                      uuid:
+                        type: string
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                displayName:
+                  description: Video playlist display name
+                  type: string
+                thumbnailfile:
+                  description: Video playlist thumbnail file
+                  type: string
+                  format: binary
+                privacy:
+                  $ref: '#/components/schemas/VideoPlaylistPrivacySet'
+                description:
+                  description: Video playlist description
+                  type: string
+                videoChannelId:
+                  description: Video channel in which the playlist will be published
+                  type: number
+              required:
+                - displayName
+
+  /video-playlists/{id}:
+    get:
+      summary: Get a video playlist
+      tags:
+        - Video Playlists
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoPlaylist'
+    put:
+      summary: Update a video playlist
+      description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
+      security:
+        - OAuth2: []
+      tags:
+        - Video Playlists
+      responses:
+        '204':
+          description: successful operation
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              properties:
+                displayName:
+                  description: Video playlist display name
+                  type: string
+                thumbnailfile:
+                  description: Video playlist thumbnail file
+                  type: string
+                  format: binary
+                privacy:
+                  $ref: '#/components/schemas/VideoPlaylistPrivacySet'
+                description:
+                  description: Video playlist description
+                  type: string
+                videoChannelId:
+                  description: Video channel in which the playlist will be published
+                  type: number
+    delete:
+      summary: Delete a video playlist
+      security:
+        - OAuth2: []
+      tags:
+        - Video Playlists
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
-        - $ref: '#/components/parameters/captionLanguage'
       responses:
         '204':
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-  /video-channels:
+          description: successful operation
+
+  /video-playlists/{id}/videos:
     get:
     get:
-      summary: Get list of video channels
+      summary: 'List videos of a playlist'
       tags:
       tags:
-        - Video Channel
+        - Videos
+        - Video Playlists
       parameters:
       parameters:
-        - $ref: '#/components/parameters/start'
-        - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoListResponse'
     post:
     post:
-      summary: Creates a video channel for the current user
+      summary: 'Add a video in a playlist'
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Channel
+        - Videos
+        - Video Playlists
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
       responses:
-        '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  videoPlaylistElement:
+                    type: object
+                    properties:
+                      id:
+                        type: number
       requestBody:
         content:
           application/json:
             schema:
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/VideoChannelCreate'
-  '/video-channels/{channelHandle}':
-    get:
-      summary: Get a video channel by its id
+              type: object
+              properties:
+                videoId:
+                  type: number
+                  description: 'Video to add in the playlist'
+                startTimestamp:
+                  type: number
+                  description: 'Start the video at this specific timestamp (in seconds)'
+                stopTimestamp:
+                  type: number
+                  description: 'Stop the video at this specific timestamp (in seconds)'
+              required:
+                - videoId
+
+  /video-playlists/{id}/videos/reorder:
+    post:
+      summary: 'Reorder a playlist'
+      security:
+        - OAuth2: []
       tags:
       tags:
-        - Video Channel
+        - Video Playlists
       parameters:
       parameters:
-        - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/idOrUUID'
       responses:
       responses:
-        '200':
+        '204':
           description: successful operation
           description: successful operation
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/VideoChannel'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                startPosition:
+                  type: number
+                  description: 'Start position of the element to reorder (starts from 1)'
+                insertAfterPosition:
+                  type: number
+                  description: 'New position for the block to reorder (starts from 0, to add the block before the first element)'
+                reorderLength:
+                  type: number
+                  description: 'How many element from startPosition to reorder (minimum length is 1)'
+              required:
+                - startPosition
+                - insertAfterPosition
+
+  /video-playlists/{id}/videos/{playlistElementId}:
     put:
     put:
-      summary: Update a video channel by its id
+      summary: 'Update a playlist element'
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Channel
+        - Video Playlists
       parameters:
       parameters:
-        - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
       requestBody:
         content:
           application/json:
             schema:
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/VideoChannelUpdate'
+              type: object
+              properties:
+                startTimestamp:
+                  type: number
+                  description: 'Start the video at this specific timestamp (in seconds)'
+                stopTimestamp:
+                  type: number
+                  description: 'Stop the video at this specific timestamp (in seconds)'
     delete:
     delete:
-      summary: Delete a video channel by its id
+      summary: 'Delete an element from a playlist'
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Channel
+        - Video Playlists
       parameters:
       parameters:
-        - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/idOrUUID'
+        - $ref: '#/components/parameters/playlistElementId'
       responses:
         '204':
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
-  '/video-channels/{channelHandle}/videos':
-    get:
-      summary: Get videos of a video channel by its id
-      tags:
-        - Video
-        - Video Channel
-      parameters:
-        - $ref: '#/components/parameters/channelHandle'
-      responses:
-        '200':
           description: successful operation
           description: successful operation
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/VideoListResponse'
-  /video-playlists:
+
+  '/users/me/video-playlists/videos-exist':
     get:
     get:
-      summary: Get list of video playlists
+      summary: 'Check video exists in my playlists'
+      security:
+        - OAuth2: []
       tags:
       tags:
-        - Video Playlist
+        - Video Playlists
       parameters:
       parameters:
-        - $ref: '#/components/parameters/start'
-        - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/sort'
+        - name: videoIds
+          in: query
+          required: true
+          description: The video ids to check
+          schema:
+            type: array
+            items:
+              type: number
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoPlaylist'
+                type: object
+                properties:
+                  videoId:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        playlistElementId:
+                          type: number
+                        playlistId:
+                          type: number
+                        startTimestamp:
+                          type: number
+                        stopTimestamp:
+                          type: number
+
   '/accounts/{name}/video-channels':
     get:
   '/accounts/{name}/video-channels':
     get:
-      summary: Get video channels of an account by its name
+      summary: List video channels of an account
       tags:
       tags:
-        - Video Channel
+        - Video Channels
+        - Accounts
       parameters:
         - $ref: '#/components/parameters/name'
       responses:
       parameters:
         - $ref: '#/components/parameters/name'
       responses:
@@ -1436,11 +1817,11 @@ paths:
                   $ref: '#/components/schemas/VideoChannel'
   '/accounts/{name}/ratings':
     get:
                   $ref: '#/components/schemas/VideoChannel'
   '/accounts/{name}/ratings':
     get:
-      summary: Get ratings of an account by its name
+      summary: List ratings of an account
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - User
+        - Accounts
       parameters:
         - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/start'
       parameters:
         - $ref: '#/components/parameters/name'
         - $ref: '#/components/parameters/start'
@@ -1466,9 +1847,9 @@ paths:
                   $ref: '#/components/schemas/VideoRating'
   '/videos/{id}/comment-threads':
     get:
                   $ref: '#/components/schemas/VideoRating'
   '/videos/{id}/comment-threads':
     get:
-      summary: Get the comment threads of a video by its id
+      summary: List threads of a video
       tags:
       tags:
-        - Video Comment
+        - Video Comments
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/start'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/start'
@@ -1482,11 +1863,11 @@ paths:
               schema:
                 $ref: '#/components/schemas/CommentThreadResponse'
     post:
               schema:
                 $ref: '#/components/schemas/CommentThreadResponse'
     post:
-      summary: 'Creates a comment thread, on a video by its id'
+      summary: Create a thread
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Comment
+        - Video Comments
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
@@ -1496,11 +1877,23 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                text:
+                  type: string
+                  description: 'Text comment'
+              required:
+                - text
+
   '/videos/{id}/comment-threads/{threadId}':
     get:
   '/videos/{id}/comment-threads/{threadId}':
     get:
-      summary: 'Get the comment thread by its id, of a video by its id'
+      summary: Get a thread
       tags:
       tags:
-        - Video Comment
+        - Video Comments
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/threadId'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/threadId'
@@ -1513,11 +1906,11 @@ paths:
                 $ref: '#/components/schemas/VideoCommentThreadTree'
   '/videos/{id}/comments/{commentId}':
     post:
                 $ref: '#/components/schemas/VideoCommentThreadTree'
   '/videos/{id}/comments/{commentId}':
     post:
-      summary: 'Creates a comment in a comment thread by its id, of a video by its id'
+      summary: Reply to a thread of a video
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Comment
+        - Video Comments
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
@@ -1528,36 +1921,56 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
             application/json:
               schema:
                 $ref: '#/components/schemas/CommentThreadPostResponse'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                text:
+                  type: string
+                  description: 'Text comment'
+              required:
+                - text
+
     delete:
     delete:
-      summary: 'Delete a comment in a comment thread by its id, of a video by its id'
+      summary: Delete a comment or a reply
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Comment
+        - Video Comments
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       responses:
         '204':
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - $ref: '#/components/parameters/commentId'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
   '/videos/{id}/rate':
     put:
   '/videos/{id}/rate':
     put:
-      summary: Vote for a video by its id
+      summary: Like/dislike a video
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:
-        - Video Rate
+        - Video Rates
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
       responses:
         '204':
-          $ref: '#/paths/~1users~1me/put/responses/204'
+          description: successful operation
   /search/videos:
     get:
       tags:
         - Search
   /search/videos:
     get:
       tags:
         - Search
-      summary: Get the videos corresponding to a given query
+      summary: Search videos
       parameters:
       parameters:
+        - $ref: '#/components/parameters/categoryOneOf'
+        - $ref: '#/components/parameters/tagsOneOf'
+        - $ref: '#/components/parameters/tagsAllOf'
+        - $ref: '#/components/parameters/licenceOneOf'
+        - $ref: '#/components/parameters/languageOneOf'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/videosSearchSort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
         - $ref: '#/components/parameters/videosSearchSort'
@@ -1578,9 +1991,9 @@ servers:
   - url: 'https://peertube.cpy.re/api/v1'
     description: Live Test Server (live data - stable version)
   - url: 'https://peertube2.cpy.re/api/v1'
   - url: 'https://peertube.cpy.re/api/v1'
     description: Live Test Server (live data - stable version)
   - url: 'https://peertube2.cpy.re/api/v1'
-    description: Live Test Server (live data - bleeding edge version)
+    description: Live Test Server (live data - latest nighlty version)
   - url: 'https://peertube3.cpy.re/api/v1'
   - url: 'https://peertube3.cpy.re/api/v1'
-    description: Live Test Server (live data - bleeding edge version)
+    description: Live Test Server (live data - latest RC version)
 components:
   parameters:
     start:
 components:
   parameters:
     start:
@@ -1594,7 +2007,7 @@ components:
       name: count
       in: query
       required: false
       name: count
       in: query
       required: false
-      description: Number of items
+      description: "Number of items (max: 100)"
       schema:
         type: number
     sort:
       schema:
         type: number
     sort:
@@ -1702,9 +2115,23 @@ components:
       name: id
       in: path
       required: true
       name: id
       in: path
       required: true
-      description: The video id or uuid
+      description: The object id or uuid
       schema:
         type: string
       schema:
         type: string
+    playlistElementId:
+      name: playlistElementId
+      in: path
+      required: true
+      description: Playlist element id
+      schema:
+        type: number
+    abuseId:
+      name: abuseId
+      in: path
+      required: true
+      description: Video abuse id
+      schema:
+        type: number
     captionLanguage:
       name: captionLanguage
       in: path
     captionLanguage:
       name: captionLanguage
       in: path
@@ -1744,7 +2171,7 @@ components:
       name: categoryOneOf
       in: query
       required: false
       name: categoryOneOf
       in: query
       required: false
-      description: category id of the video
+      description: category id of the video (see /videos/categories)
       schema:
         oneOf:
         - type: number
       schema:
         oneOf:
         - type: number
@@ -1783,7 +2210,7 @@ components:
       name: languageOneOf
       in: query
       required: false
       name: languageOneOf
       in: query
       required: false
-      description: language id of the video
+      description: language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language
       schema:
         oneOf:
         - type: string
       schema:
         oneOf:
         - type: string
@@ -1796,7 +2223,7 @@ components:
       name: licenceOneOf
       in: query
       required: false
       name: licenceOneOf
       in: query
       required: false
-      description: licence id of the video
+      description: licence id of the video (see /videos/licences)
       schema:
         oneOf:
         - type: number
       schema:
         oneOf:
         - type: number
@@ -1805,6 +2232,16 @@ components:
             type: number
       style: form
       explode: false
             type: number
       style: form
       explode: false
+    skipCount:
+      name: skipCount
+      in: query
+      required: false
+      description: if you don't need the `total` in the response
+      schema:
+        type: string
+        enum:
+          - 'true'
+          - 'false'
     nsfw:
       name: nsfw
       in: query
     nsfw:
       name: nsfw
       in: query
@@ -1873,23 +2310,64 @@ components:
           type: string
         label:
           type: string
           type: string
         label:
           type: string
+
+    VideoPlaylistPrivacySet:
+      type: integer
+      enum:
+        - 1
+        - 2
+        - 3
+      description: 'The video playlist privacy (Public = 1, Unlisted = 2, Private = 3)'
+    VideoPlaylistPrivacyConstant:
+      properties:
+        id:
+          $ref: '#/components/schemas/VideoPlaylistPrivacySet'
+        label:
+          type: string
+
+    VideoPlaylistTypeSet:
+      type: integer
+      enum:
+        - 1
+        - 2
+      description: 'The video playlist type (Regular = 1, Watch Later = 2)'
+    VideoPlaylistTypeConstant:
+      properties:
+        id:
+          $ref: '#/components/schemas/VideoPlaylistTypeSet'
+        label:
+          type: string
+
     VideoPrivacySet:
       type: integer
       enum:
         - 1
         - 2
         - 3
     VideoPrivacySet:
       type: integer
       enum:
         - 1
         - 2
         - 3
-      description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
+        - 4
+      description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3, Internal = 4)'
     VideoPrivacyConstant:
       properties:
         id:
     VideoPrivacyConstant:
       properties:
         id:
-          type: integer
-          enum:
-            - 1
-            - 2
-            - 3
+          $ref: '#/components/schemas/VideoPrivacySet'
         label:
           type: string
         label:
           type: string
+
+    NSFWPolicy:
+      type: string
+      enum:
+        - display
+        - blur
+        - do_not_list
+
+    UserRole:
+      type: number
+      enum:
+        - 0
+        - 1
+        - 2
+      description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+
     VideoStateConstant:
       properties:
         id:
     VideoStateConstant:
       properties:
         id:
@@ -1901,6 +2379,21 @@ components:
           description: 'The video state (Published = 1, to transcode = 2, to import = 3)'
         label:
           type: string
           description: 'The video state (Published = 1, to transcode = 2, to import = 3)'
         label:
           type: string
+
+    VideoAbuseStateSet:
+      type: integer
+      enum:
+        - 1
+        - 2
+        - 3
+      description: 'The video playlist privacy (Pending = 1, Rejected = 2, Accepted = 3)'
+    VideoAbuseStateConstant:
+      properties:
+        id:
+          $ref: '#/components/schemas/VideoAbuseStateSet'
+        label:
+          type: string
+
     VideoResolutionConstant:
       properties:
         id:
     VideoResolutionConstant:
       properties:
         id:
@@ -1912,14 +2405,13 @@ components:
       properties:
         privacy:
           $ref: '#/components/schemas/VideoPrivacySet'
       properties:
         privacy:
           $ref: '#/components/schemas/VideoPrivacySet'
-          description: Video privacy target
         updateAt:
           type: string
           format: date
           description: When to update the video
       required:
         - updateAt
         updateAt:
           type: string
           format: date
           description: When to update the video
       required:
         - updateAt
-    VideoAccountSummary:
+    AccountSummary:
       properties:
         id:
           type: number
       properties:
         id:
           type: number
@@ -1933,7 +2425,8 @@ components:
           type: string
         avatar:
           nullable: true
           type: string
         avatar:
           nullable: true
-          $ref: '#/components/schemas/Avatar'
+          allOf:
+            - $ref: '#/components/schemas/Avatar'
     VideoChannelSummary:
       properties:
         id:
     VideoChannelSummary:
       properties:
         id:
@@ -1948,7 +2441,8 @@ components:
           type: string
         avatar:
           nullable: true
           type: string
         avatar:
           nullable: true
-          $ref: '#/components/schemas/Avatar'
+          allOf:
+            - $ref: '#/components/schemas/Avatar'
     PlaylistElement:
       properties:
         position:
     PlaylistElement:
       properties:
         position:
@@ -1959,7 +2453,8 @@ components:
           type: number
         video:
           nullable: true
           type: number
         video:
           nullable: true
-          $ref: '#/components/schemas/Video'
+          allOf:
+            - $ref: '#/components/schemas/Video'
     VideoFile:
       properties:
         magnetUri:
     VideoFile:
       properties:
         magnetUri:
@@ -1979,6 +2474,8 @@ components:
           type: string
         fps:
           type: number
           type: string
         fps:
           type: number
+        metadataUrl:
+          type: string
     VideoStreamingPlaylists:
       properties:
         id:
     VideoStreamingPlaylists:
       properties:
         id:
@@ -1992,6 +2489,10 @@ components:
           type: string
         segmentsSha256Url:
           type: string
           type: string
         segmentsSha256Url:
           type: string
+        files:
+          type: array
+          items:
+            $ref: '#/components/schemas/VideoFile'
         redundancies:
           type: array
           items:
         redundancies:
           type: array
           items:
@@ -2050,7 +2551,8 @@ components:
           $ref: '#/components/schemas/VideoStateConstant'
         scheduledUpdate:
           nullable: true
           $ref: '#/components/schemas/VideoStateConstant'
         scheduledUpdate:
           nullable: true
-          $ref: '#/components/schemas/VideoScheduledUpdate'
+          allOf:
+            - $ref: '#/components/schemas/VideoScheduledUpdate'
         blacklisted:
           nullable: true
           type: boolean
         blacklisted:
           nullable: true
           type: boolean
@@ -2058,7 +2560,7 @@ components:
           nullable: true
           type: string
         account:
           nullable: true
           type: string
         account:
-          $ref: '#/components/schemas/VideoAccountSummary'
+          $ref: '#/components/schemas/AccountSummary'
         channel:
           $ref: '#/components/schemas/VideoChannelSummary'
         userHistory:
         channel:
           $ref: '#/components/schemas/VideoChannelSummary'
         userHistory:
@@ -2144,6 +2646,10 @@ components:
           type: string
         reporterAccount:
           $ref: '#/components/schemas/Account'
           type: string
         reporterAccount:
           $ref: '#/components/schemas/Account'
+        state:
+          $ref: '#/components/schemas/VideoAbuseStateConstant'
+        moderationComment:
+          type: string
         video:
           type: object
           properties:
         video:
           type: object
           properties:
@@ -2153,8 +2659,6 @@ components:
               type: string
             uuid:
               type: string
               type: string
             uuid:
               type: string
-            url:
-              type: string
         createdAt:
           type: string
     VideoBlacklist:
         createdAt:
           type: string
     VideoBlacklist:
@@ -2219,32 +2723,13 @@ components:
         thumbnailPath:
           type: string
         privacy:
         thumbnailPath:
           type: string
         privacy:
-          type: object
-          properties:
-            id:
-              type: number
-            label:
-              type: string
+          $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
         type:
         type:
-          type: object
-          properties:
-            id:
-              type: number
-            label:
-              type: string
+          $ref: '#/components/schemas/VideoPlaylistTypeConstant'
         ownerAccount:
         ownerAccount:
-          type: object
-          properties:
-            id:
-              type: number
-            name:
-              type: string
-            displayName:
-              type: string
-            url:
-              type: string
-            host:
-              type: string
+          $ref: '#/components/schemas/AccountSummary'
+        videoChannel:
+          $ref: '#/components/schemas/VideoChannelSummary'
     VideoComment:
       properties:
         id:
     VideoComment:
       properties:
         id:
@@ -2329,17 +2814,20 @@ components:
           type: string
         email:
           type: string
           type: string
         email:
           type: string
-        displayNSFW:
+        theme:
+          type: string
+          description: 'Theme enabled by this user'
+        emailVerified:
+          type: boolean
+          description: 'Is email verified?'
+        nsfwPolicy:
+          $ref: '#/components/schemas/NSFWPolicy'
+        webtorrentEnabled:
           type: boolean
         autoPlayVideo:
           type: boolean
         role:
           type: boolean
         autoPlayVideo:
           type: boolean
         role:
-          type: integer
-          enum:
-            - 0
-            - 1
-            - 2
-          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+          $ref: '#/components/schemas/UserRole'
         roleLabel:
           type: string
           enum:
         roleLabel:
           type: string
           enum:
@@ -2350,6 +2838,24 @@ components:
           type: number
         videoQuotaDaily:
           type: number
           type: number
         videoQuotaDaily:
           type: number
+        videosCount:
+          type: number
+        videoAbusesCount:
+          type: number
+        videoAbusesAcceptedCount:
+          type: number
+        videoAbusesCreatedCount:
+          type: number
+        videoCommentsCount:
+          type: number
+        noInstanceConfigWarningModal:
+          type: boolean
+        noWelcomeModal:
+          type: boolean
+        blocked:
+          type: boolean
+        blockedReason:
+          type: string
         createdAt:
           type: string
         account:
         createdAt:
           type: string
         account:
@@ -2384,6 +2890,16 @@ components:
                   type: string
                 css:
                   type: string
                   type: string
                 css:
                   type: string
+        search:
+          type: object
+          properties:
+            remoteUri:
+              type: object
+              properties:
+                users:
+                  type: boolean
+                anonymous:
+                  type: boolean
         plugin:
           type: object
           properties:
         plugin:
           type: object
           properties:
@@ -2429,6 +2945,11 @@ components:
               properties:
                 enabled:
                   type: boolean
               properties:
                 enabled:
                   type: boolean
+            webtorrent:
+              type: object
+              properties:
+                enabled:
+                  type: boolean
             enabledResolutions:
               type: array
               items:
             enabledResolutions:
               type: array
               items:
@@ -2532,6 +3053,17 @@ components:
           properties:
             enabled:
               type: boolean
           properties:
             enabled:
               type: boolean
+        followings:
+          type: object
+          properties:
+            instance:
+              type: object
+              properties:
+                autoFollowIndex:
+                  type: object
+                  properties:
+                    indexUrl:
+                      type: string
     ServerConfigAbout:
       properties:
         instance:
     ServerConfigAbout:
       properties:
         instance:
@@ -2778,7 +3310,7 @@ components:
           description: 'The user username '
         password:
           type: string
           description: 'The user username '
         password:
           type: string
-          description: 'The user password '
+          description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent '
         email:
           type: string
           description: 'The user email '
         email:
           type: string
           description: 'The user email '
@@ -2789,12 +3321,7 @@ components:
           type: string
           description: 'The user daily video quota '
         role:
           type: string
           description: 'The user daily video quota '
         role:
-          type: integer
-          enum:
-            - 0
-            - 1
-            - 2
-          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+          $ref: '#/components/schemas/UserRole'
       required:
         - username
         - password
       required:
         - username
         - password
@@ -2817,12 +3344,7 @@ components:
           type: string
           description: 'The updated daily video quota of the user '
         role:
           type: string
           description: 'The updated daily video quota of the user '
         role:
-          type: integer
-          enum:
-            - 0
-            - 1
-            - 2
-          description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+          $ref: '#/components/schemas/UserRole'
       required:
         - id
         - email
       required:
         - id
         - email
Unnamed repository; edit this file 'description' to name the repository.