Try to improve remote tools explanation

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

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index bcb0c511e209ceba2986b30a5372934e55361d60..59ca8b29a9305f16a8fe3af1fd50fac86c05fff9 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,10 +1,22 @@
 swagger: '2.0'
 info:
   title: PeerTube
-  version: 0.0.15-alpha
+  version: 1.0.0-beta
   description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular.
+host: peertube.example.com
+securityDefinitions:
+  OAuth2:
+    description: 'In the header: *Authorization: Bearer mytoken*'
+    type: oauth2
+    flow: password
+    # Not implemented yet
+    # authorizationUrl: https://example.com/oauth/authorize
+    tokenUrl: https://peertube.example.com/api/v1/users/token
+basePath: '/api/v1'
+schemes:
+  - https
 paths:
-  '/accounts/{id}':
+  '/accounts/{name}':
     get:
       tags:
         - Accounts
@@ -13,31 +25,30 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The id of the account'
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "accounts.yaml#/parameters/name"
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/Account'
+  '/accounts/{name}/videos':
+    get:
+      tags:
+        - Accounts
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - $ref: "accounts.yaml#/parameters/name"
+      responses:
+        '200':
+          description: successful operation
+          schema:
+            $ref: '#/definitions/Video'
   /accounts:
     get:
       tags:
@@ -65,45 +76,66 @@ paths:
         '200':
           description: successful operation
           schema:
-            $ref: '#/definitions/ServerConfig' 
-  /jobs:
+            $ref: '#/definitions/ServerConfig'
+  /feeds/videos.{format}:
     get:
       tags:
-        - Job
-      consumes:
-        - application/json
+        - Feeds
       produces:
+        - application/atom+xml
+        - application/rss+xml
         - application/json
       parameters:
-        - name: state
+        - name: format
           in: path
           required: true
           type: string
-          description: 'The id of the account'
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: count
+          enum: [ 'xml', 'atom', 'json']
+          default: 'xml'
+          description: 'The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and json to JSON FEED 1.0'
+        - name: accountId
           in: query
           required: false
           type: number
-          description: ''
-        - name: sort
+          description: 'The id of the local account to filter to (beware, users IDs and not actors IDs which will return empty feeds'
+        - name: accountName
           in: query
           required: false
-          type: number
-          description: 'sorting'
+          type: string
+          description: 'The name of the local account to filter to'
+      responses:
+        '200':
+          description: successful operation
+  /jobs:
+    get:
+      security:
+        - OAuth2: [ ]
+      tags:
+        - Job
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - name: state
+          in: path
+          required: true
+          type: string
+          description: 'The state of the job'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
           schema:
             type: array
             items:
-              $ref: '#/definitions/Job' 
+              $ref: '#/definitions/Job'
   '/server/following/{host}':
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - ServerFollowing
       consumes:
@@ -128,21 +160,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -159,21 +179,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -182,6 +190,8 @@ paths:
             items:
               $ref: '#/definitions/Follow'
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - ServerFollowing
       consumes:
@@ -195,9 +205,11 @@ paths:
             $ref: '#/definitions/Follow'
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /users:
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -208,6 +220,7 @@ paths:
         - in: body
           name: body
           required: true
+          description: 'User to create'
           schema:
             $ref: '#/definitions/AddUser'
       responses:
@@ -216,6 +229,8 @@ paths:
           schema:
             $ref: '#/definitions/AddUserResponse'
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -223,21 +238,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -247,6 +250,8 @@ paths:
               $ref: '#/definitions/User'
   '/users/{id}':
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -254,15 +259,13 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The user id '
+        - $ref: "users.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -270,17 +273,15 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The user id '
+        - $ref: "users.yaml#/parameters/id"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/User'
     put:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -288,11 +289,7 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The user id '
+        - $ref: "users.yaml#/parameters/id"
         - in: body
           name: body
           required: true
@@ -300,9 +297,11 @@ paths:
             $ref: '#/definitions/UpdateUser'
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /users/me:
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -317,6 +316,8 @@ paths:
             items:
               $ref: '#/definitions/User'
     put:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -331,9 +332,11 @@ paths:
             $ref: '#/definitions/UpdateMe'
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /users/me/video-quota-used:
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -348,6 +351,8 @@ paths:
             type: number
   '/users/me/videos/{videoId}/rating':
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -367,6 +372,8 @@ paths:
             $ref: '#/definitions/GetMeVideoRating'
   /users/me/videos:
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -374,21 +381,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -412,9 +407,11 @@ paths:
             $ref: '#/definitions/RegisterUser'
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /users/me/avatar/pick:
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - User
       consumes:
@@ -440,21 +437,14 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
+        - name: category
           in: query
           required: false
           type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+          description: category id of the video
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -522,51 +512,32 @@ paths:
             type: array
             items:
               type: string
-  /videos/search:
-    get:
-      tags:
-        - Video
-      consumes:
-        - application/json
-      produces:
-        - application/json
-      parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
-      responses:
-        '200':
-          description: successful operation
-          schema:
-            type: array
-            items:
-              $ref: '#/definitions/Video'
   "/videos/{id}":
     put:
+      security:
+        - OAuth2: [ ]
       tags:
         - Video
       consumes:
-        - application/json
+        - multipart/form-data
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
+        - $ref: "videos.yaml#/parameters/thumbnailfile"
+        - $ref: "videos.yaml#/parameters/previewfile"
+        - $ref: "videos.yaml#/parameters/category"
+        - $ref: "videos.yaml#/parameters/licence"
+        - $ref: "videos.yaml#/parameters/language"
+        - $ref: "videos.yaml#/parameters/description"
+        - $ref: "videos.yaml#/parameters/waitTranscoding"
+        - $ref: "videos.yaml#/parameters/support"
+        - $ref: "videos.yaml#/parameters/nsfw"
+        - $ref: "videos.yaml#/parameters/name"
+        - $ref: "videos.yaml#/parameters/tags"
+        - $ref: "videos.yaml#/parameters/commentsEnabled"
+        - $ref: "videos.yaml#/parameters/privacy"
+        - $ref: "videos.yaml#/parameters/scheduleUpdate"
       responses:
         '200':
           description: successful operation
@@ -580,17 +551,15 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/Video'
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - Video
       consumes:
@@ -598,14 +567,10 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   "/videos/{id}/description":
     get:
       tags:
@@ -615,11 +580,7 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '200':
           description: successful operation
@@ -634,16 +595,14 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /videos/upload:
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - Video
       consumes:
@@ -651,10 +610,30 @@ paths:
       produces:
         - application/json
       parameters:
-        - in: formData
-          name: videofile
+        - name: videofile
+          in: formData
           type: file
-          description: The file to upload.
+          required: true
+          description: 'Video file'
+        - name: channelId
+          in: formData
+          required: true
+          type: number
+          description: 'Channel id that will contain this video'
+        - $ref: "videos.yaml#/parameters/thumbnailfile"
+        - $ref: "videos.yaml#/parameters/previewfile"
+        - $ref: "videos.yaml#/parameters/category"
+        - $ref: "videos.yaml#/parameters/licence"
+        - $ref: "videos.yaml#/parameters/language"
+        - $ref: "videos.yaml#/parameters/description"
+        - $ref: "videos.yaml#/parameters/waitTranscoding"
+        - $ref: "videos.yaml#/parameters/support"
+        - $ref: "videos.yaml#/parameters/nsfw"
+        - $ref: "videos.yaml#/parameters/name"
+        - $ref: "videos.yaml#/parameters/tags"
+        - $ref: "videos.yaml#/parameters/commentsEnabled"
+        - $ref: "videos.yaml#/parameters/privacy"
+        - $ref: "videos.yaml#/parameters/scheduleUpdate"
       responses:
         '200':
           description: successful operation
@@ -662,6 +641,8 @@ paths:
             $ref: '#/definitions/VideoUploadResponse'
   /videos/abuse:
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoAbuse
       consumes:
@@ -669,21 +650,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -693,6 +662,8 @@ paths:
               $ref: '#/definitions/VideoAbuse'
   "/videos/{id}/abuse":
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoAbuse
       consumes:
@@ -700,16 +671,14 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
-  "/videos/{videoId}/blacklist":
+          $ref: "commons.yaml#/responses/emptySuccess"
+  "/videos/{id}/blacklist":
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoBlacklist
       consumes:
@@ -717,15 +686,13 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoBlacklist
       consumes:
@@ -733,16 +700,14 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   /videos/blacklist:
     get:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoBlacklist
       consumes:
@@ -750,21 +715,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -772,7 +725,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/VideoBlacklist'
-  /videos/channels:
+  /video-channels:
     get:
       tags:
         - VideoChannel
@@ -781,21 +734,9 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
@@ -804,6 +745,8 @@ paths:
             items:
               $ref: '#/definitions/VideoChannel'
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoChannel
       consumes:
@@ -817,8 +760,8 @@ paths:
             $ref: '#/definitions/VideoChannelInput'
       responses:
         '204':
-          description: successful operation
-  "/videos/channels/{id}":
+          $ref: "commons.yaml#/responses/emptySuccess"
+  "/video-channels/{id}":
     get:
       tags:
         - VideoChannel
@@ -827,17 +770,15 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "video-channels.yaml#/parameters/id"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/VideoChannel'
     put:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoChannel
       consumes:
@@ -845,19 +786,17 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "video-channels.yaml#/parameters/id"
         - in: body
           name: body
           schema:
             $ref: '#/definitions/VideoChannelInput'
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoChannel
       consumes:
@@ -865,15 +804,26 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "video-channels.yaml#/parameters/id"
       responses:
         '204':
+          $ref: "commons.yaml#/responses/emptySuccess"
+  "/video-channels/{id}/videos":
+    get:
+      tags:
+        - VideoChannel
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - $ref: "video-channels.yaml#/parameters/id"
+      responses:
+        '200':
           description: successful operation
-  /videos/accounts/{accountId}/channels:
+          schema:
+            $ref: '#/definitions/Video'
+  /accounts/{name}/video-channels:
     get:
       tags:
         - VideoChannel
@@ -882,11 +832,7 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: accountId
-          in: path
-          required: true
-          type: string
-          description: 'The account id '
+        - $ref: "accounts.yaml#/parameters/name"
       responses:
         '200':
           description: successful operation
@@ -894,7 +840,7 @@ paths:
             type: array
             items:
               $ref: '#/definitions/VideoChannel'
-  "/videos/{videoId}/comment-threads":
+  "/videos/{id}/comment-threads":
     get:
       tags:
         - VideoComment
@@ -903,32 +849,18 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
-        - name: start
-          in: query
-          required: false
-          type: number
-          description: 'starting page'
-        - name: stop
-          in: query
-          required: false
-          type: number
-          description: 'stoping page'
-        - name: sort
-          in: query
-          required: false
-          type: number
-          description: 'sorting'
+        - $ref: "videos.yaml#/parameters/id"
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/CommentThreadResponse'
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoComment
       consumes:
@@ -936,17 +868,13 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
+        - $ref: "videos.yaml#/parameters/id"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/CommentThreadPostResponse'
-  "/videos/{videoId}/comment-threads/{threadId}":
+  "/videos/{id}/comment-threads/{threadId}":
     get:
       tags:
         - VideoComment
@@ -955,23 +883,17 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
-        - name: threadId
-          in: path
-          required: true
-          type: string
-          description: 'The thread id '
+        - $ref: "videos.yaml#/parameters/id"
+        - $ref: "video-comments.yaml#/parameters/threadId"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/VideoCommentThreadTree'
-  "/videos/{videoId}/comments/{commentId}":
+  "/videos/{id}/comments/{commentId}":
     post:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoComment
       consumes:
@@ -979,22 +901,16 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
-        - name: commentId
-          in: path
-          required: true
-          type: string
-          description: 'The comment id '
+        - $ref: "videos.yaml#/parameters/id"
+        - $ref: "video-comments.yaml#/parameters/commentId"
       responses:
         '200':
           description: successful operation
           schema:
             $ref: '#/definitions/CommentThreadPostResponse'
     delete:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoComment
       consumes:
@@ -1002,21 +918,15 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: videoId
-          in: path
-          required: true
-          type: string
-          description: 'The video id '
-        - name: commentId
-          in: path
-          required: true
-          type: string
-          description: 'The comment id '
+        - $ref: "videos.yaml#/parameters/id"
+        - $ref: "video-comments.yaml#/parameters/commentId"
       responses:
         '204':
-          description: successful operation
+          $ref: "commons.yaml#/responses/emptySuccess"
   "/videos/{id}/rate":
     put:
+      security:
+        - OAuth2: [ ]
       tags:
         - VideoRate
       consumes:
@@ -1024,39 +934,70 @@ paths:
       produces:
         - application/json
       parameters:
-        - name: id
-          in: path
+        - $ref: "videos.yaml#/parameters/id"
+      responses:
+        '204':
+          $ref: "commons.yaml#/responses/emptySuccess"
+  /search/videos:
+    get:
+      tags:
+        - Search
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - $ref: "commons.yaml#/parameters/start"
+        - $ref: "commons.yaml#/parameters/count"
+        - $ref: "commons.yaml#/parameters/sort"
+        - name: search
+          in: query
           required: true
           type: string
-          description: 'The video id '
+          description: 'String to search'
       responses:
-        '204':
+        '200':
           description: successful operation
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Video'
 definitions:
+  VideoConstantNumber:
+    properties:
+      id:
+        type: number
+      label:
+        type: string
+  VideoConstantString:
+    properties:
+      id:
+        type: string
+      label:
+        type: string
+  VideoPrivacy:
+    type: string
+    enum: [Public, Unlisted, Private]
   Video:
     properties:
       id:
         type: number
       uuid:
         type: string
-      accountName:
-        type: string
       createdAt:
         type: string
-      updatedAt:
+      publishedAt:
         type: string
-      categoryLabel:
+      updatedAt:
         type: string
       category:
-        type: number
-      licenceLabel:
-        type: string
+        $ref: "#/definitions/VideoConstantNumber"
       licence:
-        type: number
-      languageLabel:
-        type: string
+        $ref: "#/definitions/VideoConstantNumber"
       language:
-        type: number
+        $ref: "#/definitions/VideoConstantString"
+      privacy:
+        $ref: "#/definitions/VideoPrivacy"
       description:
         type: string
       duration:
@@ -1065,8 +1006,6 @@ definitions:
         type: boolean
       name:
         type: string
-      serverHost:
-        type: string
       thumbnailPath:
         type: string
       previewPath:
@@ -1081,22 +1020,38 @@ definitions:
         type: number
       nsfw:
         type: boolean
+      account:
+        type: object
+        properties:
+          name:
+            type: string
+          displayName:
+            type: string
+          url:
+            type: string
+          host:
+            type: string
+          avatar:
+            $ref: "#/definitions/Avatar"
   VideoAbuse:
     properties:
       id:
         type: number
       reason:
         type: string
-      reporterUsername:
-        type: string
-      reporterServerHost:
-        type: string
-      videoId:
-        type: number
-      videoUUID:
-        type: string
-      videoName:
-        type: string
+      reporterAccount:
+        $ref: "#/definitions/Account"
+      video:
+        type: object
+        properties:
+          id:
+            type: number
+          name:
+            type: string
+          uuid:
+            type: string
+          url:
+            type: string
       createdAt:
         type: string
   VideoBlacklist:
@@ -1133,17 +1088,13 @@ definitions:
         type: string
       isLocal:
         type: boolean
-      owner:
+      ownerAccount:
         type: object
-        properties: 
-          name: 
-            type: string
-          uuid: 
+        properties:
+          id:
+            type: number
+          uuid:
             type: string
-      videos:
-        type: array
-        items: 
-          $ref: "#/definitions/Video"
   VideoComment:
     properties:
       id:
@@ -1224,7 +1175,7 @@ definitions:
         type: boolean
       role:
         type: string
-        enum: [User, Moderator, Administrator] 
+        enum: [User, Moderator, Administrator]
       videoQuota:
         type: number
       createdAt:
@@ -1237,7 +1188,7 @@ definitions:
           $ref: "#/definitions/VideoChannel"
   ServerConfig:
     properties:
-      signup: 
+      signup:
         type: object
         properties:
           allowed:
@@ -1260,7 +1211,7 @@ definitions:
                 properties:
                   max:
                     type: number
-          extensions: 
+          extensions:
             type: array
             items:
               type: string
@@ -1269,8 +1220,8 @@ definitions:
         properties:
           file:
             type: object
-            properties: 
-              extensions: 
+            properties:
+              extensions:
                 type: array
                 items:
                   type: string
@@ -1310,7 +1261,7 @@ definitions:
       updatedAt:
         type: string
 
-#Api responses
+# Api responses
   AddUserResponse:
     properties:
       id:
@@ -1319,10 +1270,13 @@ definitions:
         type: string
   VideoUploadResponse:
     properties:
-      id:
-        type: number
-      uuid:
-        type: string
+      video:
+        type: object
+        properties:
+          id:
+            type: number
+          uuid:
+            type: string
   CommentThreadResponse:
     properties:
       total:
@@ -1336,7 +1290,7 @@ definitions:
       comment:
         $ref: "#/definitions/VideoComment"
 
-#request bodies
+# Request bodies
   AddUser:
     properties:
       username:
@@ -1429,4 +1383,4 @@ definitions:
       name:
         type: string
       description:
-        type: string
+        type: string
\ No newline at end of file