Remove invalid info from REST API doc

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

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

-  version: 3.3.0
+  version: 4.0.0

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


@@ -252,6 +252,8 @@ tags:
 
       The import function is practical when the desired video/audio is available online. It makes PeerTube
       download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
 
       The import function is practical when the desired video/audio is available online. It makes PeerTube
       download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.

+  - name: Video Imports
+    description: Operations dealing with listing, adding and removing video imports.

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


@@ -306,6 +308,7 @@ x-tagGroups:
     tags:
       - Video
       - Video Upload
     tags:
       - Video
       - Video Upload

+      - Video Imports

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


@@ -587,6 +590,30 @@ paths:
         '204':
           description: successful operation
 
         '204':
           description: successful operation
 

+  /jobs/pause:
+    post:
+      summary: Pause job queue
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Job
+      responses:
+        '204':
+          description: successful operation
+
+  /jobs/resume:
+    post:
+      summary: Resume job queue
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Job
+      responses:
+        '204':
+          description: successful operation
+

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


@@ -1476,6 +1503,23 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 

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

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


@@ -1512,8 +1556,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

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

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


@@ -1573,7 +1619,7 @@ paths:
         '403':
           description: cannot terminate an ownership change of another user
         '404':
         '403':
           description: cannot terminate an ownership change of another user
         '404':

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

 
   '/videos/ownership/{id}/refuse':
     post:
 
   '/videos/ownership/{id}/refuse':
     post:


@@ -1590,7 +1636,7 @@ paths:
         '403':
           description: cannot terminate an ownership change of another user
         '404':
         '403':
           description: cannot terminate an ownership change of another user
         '404':

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

 
   '/videos/{id}/give-ownership':
     post:
 
   '/videos/{id}/give-ownership':
     post:


@@ -2032,7 +2078,7 @@ paths:
           in: query
           required: true
           description: |
           in: query
           required: true
           description: |

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

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


@@ -2056,9 +2102,6 @@ paths:
           description: |
             Size of the chunk that the request is sending.
 
           description: |
             Size of the chunk that the request is sending.
 

-            The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
-            doesn't mandate for chunks to have the same size throughout the upload sequence.
-

             Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
             1048576 bytes (~1MB) and increases or reduces size depending on connection health.
       requestBody:
             Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
             1048576 bytes (~1MB) and increases or reduces size depending on connection health.
       requestBody:


@@ -2149,7 +2192,7 @@ paths:
       security:
         - OAuth2: []
       tags:
       security:
         - OAuth2: []
       tags:

-        - Video
+        - Video Imports

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


@@ -2177,6 +2220,34 @@ paths:
         '409':
           description: HTTP or Torrent/magnetURI import not enabled
 
         '409':
           description: HTTP or Torrent/magnetURI import not enabled
 

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

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


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

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

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


@@ -2806,7 +2880,7 @@ paths:
                     type: object
                     properties:
                       id:
                     type: object
                     properties:
                       id:

-                        $ref: '#/components/schemas/VideoChannel/properties/id'
+                        $ref: '#/components/schemas/id'

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


@@ -2938,8 +3012,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

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

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


@@ -2992,8 +3068,10 @@ paths:
               schema:
                 type: object
                 properties:
               schema:
                 type: object
                 properties:

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

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


@@ -4750,7 +4828,7 @@ components:
       name: id
       in: path
       required: true
       name: id
       in: path
       required: true

-      description: The user id
+      description: Entity id

       schema:
         $ref: '#/components/schemas/id'
     idOrUUID:
       schema:
         $ref: '#/components/schemas/id'
     idOrUUID:


@@ -5213,6 +5291,14 @@ components:
       description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
       example: 1
 
       description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
       example: 1
 

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

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


@@ -5292,10 +5378,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

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

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


@@ -5310,10 +5396,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

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

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


@@ -5897,6 +5983,8 @@ components:
       properties:
         path:
           type: string
       properties:
         path:
           type: string

+        width:
+          type: integer

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


@@ -5914,12 +6002,10 @@ components:
         host:
           type: string
           format: hostname
         host:
           type: string
           format: hostname

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

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


@@ -5952,8 +6038,6 @@ components:
         updatedAt:
           type: string
           format: date-time
         updatedAt:
           type: string
           format: date-time

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

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


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

-        webtorrentEnabled:
+        p2pEnabled:

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


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

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

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


@@ -6780,7 +6866,7 @@ components:
             - 'true'
             - 'false'
             - both
             - 'true'
             - 'false'
             - both

-        webTorrentEnabled:
+        p2pEnabled:

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


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

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

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


@@ -6922,46 +7008,47 @@ components:
         - refresh_token
 
     VideoChannel:
         - refresh_token
 
     VideoChannel:

-      properties:
-        # GET/POST/PUT properties
-        displayName:
-          type: string
-          description: editable name of the channel, displayed in its representations
-          example: Videos of Framasoft
-          minLength: 1
-          maxLength: 120
-        description:
-          type: string
-          example: Videos made with <3 by Framasoft
-          minLength: 3
-          maxLength: 1000
-        support:
-          type: string
-          description: text shown by default on all videos of this channel, to tell the audience how to support it
-          example: Please support our work on https://soutenir.framasoft.org/en/ <3
-          minLength: 3
-          maxLength: 1000
-        # GET-only properties
-        id:
-          readOnly: true
-          allOf:
-            - $ref: '#/components/schemas/id'
-        isLocal:
-          readOnly: true
-          type: boolean
-        updatedAt:
-          readOnly: true
-          type: string
-          format: date-time
-        ownerAccount:
-          readOnly: true
-          nullable: true
-          type: object
+      allOf:
+        - $ref: '#/components/schemas/Actor'
+        - type: object

           properties:
           properties:

-            id:
-              type: integer
-            uuid:
-              $ref: '#/components/schemas/UUIDv4'
+            displayName:
+              type: string
+              description: editable name of the channel, displayed in its representations
+              example: Videos of Framasoft
+              minLength: 1
+              maxLength: 120
+            description:
+              type: string
+              example: Videos made with <3 by Framasoft
+              minLength: 3
+              maxLength: 1000
+            support:
+              type: string
+              description: text shown by default on all videos of this channel, to tell the audience how to support it
+              example: Please support our work on https://soutenir.framasoft.org/en/ <3
+              minLength: 3
+              maxLength: 1000
+            isLocal:
+              readOnly: true
+              type: boolean
+            updatedAt:
+              readOnly: true
+              type: string
+              format: date-time
+            banners:
+              type: array
+              items:
+                $ref: '#/components/schemas/ActorImage'
+            ownerAccount:
+              readOnly: true
+              nullable: true
+              type: object
+              properties:
+                id:
+                  type: integer
+                uuid:
+                  $ref: '#/components/schemas/UUIDv4'

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


@@ -7228,6 +7315,14 @@ components:
             - `13` NEW_INSTANCE_FOLLOWER
 
             - `14` AUTO_INSTANCE_FOLLOWING
             - `13` NEW_INSTANCE_FOLLOWER
 
             - `14` AUTO_INSTANCE_FOLLOWING

+
+            - `15` ABUSE_STATE_CHANGE
+
+            - `16` ABUSE_NEW_MESSAGE
+
+            - `17` NEW_PLUGIN_VERSION
+
+            - `18` NEW_PEERTUBE_VERSION

         read:
           type: boolean
         video:
         read:
           type: boolean
         video:


@@ -7395,6 +7490,9 @@ components:
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean

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

 
     LiveVideoResponse:
       properties:
 
     LiveVideoResponse:
       properties:


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

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

 
   callbacks:
     searchIndex:
 
   callbacks:
     searchIndex: