X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=74963df140cf27a97e25198e56ecde369c47606f;hb=f9079a78bd84e3745b20a6a36c5d2a8c693427b0;hp=99a725ead0b37f3bc62e436108be060d237323a5;hpb=5f26f13b3c16ac5ae0a3b0a7142d84a9528cf565;p=github%2FChocobozzz%2FPeerTube.git

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 99a725ead..74963df14 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: PeerTube
-  version: 3.3.0
+  version: 4.0.0
   contact:
     name: PeerTube Community
     url: https://joinpeertube.org
@@ -247,11 +247,13 @@ tags:
       ### Import
 
       - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
-      - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
-      - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
+      - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
+      - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
 
       The import function is practical when the desired video/audio is available online. It makes PeerTube
       download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
+  - name: Video 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
@@ -267,6 +269,12 @@ tags:
     description: Like/dislike a video.
   - name: Video Playlists
     description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
+  - name: Video Files
+    description: Operations on video files
+  - name: Video Transcoding
+    description: Video transcoding related operations
+  - name: Video stats
+    description: Video statistics
   - name: Feeds
     description: Server syndication feeds
   - name: Search
@@ -285,6 +293,10 @@ tags:
       PeerTube instances can mirror videos from one another, and help distribute some videos.
 
       For importing videos as your own, refer to [video imports](#operation/importVideo).
+  - name: Stats
+    description: |
+      Statistics
+
 x-tagGroups:
   - name: Auth
     tags:
@@ -302,35 +314,37 @@ x-tagGroups:
     tags:
       - Video
       - Video Upload
+      - Video Imports
       - Video Captions
       - Video Channels
       - Video Comments
       - Video Rates
       - Video Playlists
+      - Video Stats
       - Video Ownership Change
       - Video Mirroring
+      - Video Files
+      - Video Transcoding
       - Live Videos
       - Feeds
   - name: Search
     tags:
       - Search
-  - name: Custom pages
-    tags:
-      - Homepage
   - name: Moderation
     tags:
       - Abuses
       - Video Blocks
       - Account Blocks
       - Server Blocks
-  - name: Instance Configuration
+  - name: Instance
     tags:
       - Config
+      - Homepage
       - Instance Follows
       - Instance Redundancy
       - Plugins
-  - name: Jobs
-    tags:
+      - Stats
+      - Logs
       - Job
 paths:
   '/accounts/{name}':
@@ -367,7 +381,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -414,6 +432,36 @@ paths:
 
             print(json)
 
+  '/accounts/{name}/followers':
+    get:
+      tags:
+        - Accounts
+      summary: 'List followers of an account'
+      security:
+        - OAuth2: []
+      operationId: getAccountFollowers
+      parameters:
+        - $ref: '#/components/parameters/name'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/followersSort'
+        - $ref: '#/components/parameters/search'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'
+
   /accounts:
     get:
       tags:
@@ -547,6 +595,30 @@ paths:
         '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
@@ -716,7 +788,7 @@ paths:
           - admin
       tags:
         - Instance Follows
-      summary: Follow a list of servers
+      summary: Follow a list of actors (PeerTube instance, channel or account)
       responses:
         '204':
           description: successful operation
@@ -734,28 +806,32 @@ paths:
                     type: string
                     format: hostname
                   uniqueItems: true
+                handles:
+                  type: array
+                  items:
+                    type: string
+                  uniqueItems: true
 
-  '/server/following/{host}':
+  '/server/following/{hostOrHandle}':
     delete:
-      summary: Unfollow a server
+      summary: Unfollow an actor (PeerTube instance, channel or account)
       security:
         - OAuth2:
           - admin
       tags:
         - Instance Follows
       parameters:
-        - name: host
+        - name: hostOrHandle
           in: path
           required: true
-          description: The host to unfollow
+          description: The hostOrHandle to unfollow
           schema:
             type: string
-            format: hostname
       responses:
         '204':
           description: successful operation
         '404':
-          description: host not found
+          description: host or handle not found
 
   /users:
     post:
@@ -1266,7 +1342,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -1428,6 +1508,23 @@ paths:
               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
@@ -1464,8 +1561,10 @@ paths:
               schema:
                 type: object
                 properties:
-                  avatar:
-                    $ref: '#/components/schemas/ActorImage'
+                  avatars:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'
         '413':
           description: image file too large
           headers:
@@ -1525,7 +1624,7 @@ paths:
         '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:
@@ -1542,7 +1641,7 @@ paths:
         '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:
@@ -1572,6 +1671,31 @@ paths:
         '404':
           description: video not found
 
+  /videos/{id}/studio/edit:
+    post:
+      summary: Create a studio task
+      tags:
+        - Video Transcoding
+        - Video
+      description: Create a task to edit a video  (cut, add intro/outro etc)
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        required: true
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/VideoStudioCreateTask'
+      responses:
+        '204':
+          description: successful operation
+        '400':
+          description: incorrect parameters
+        '404':
+          description: video not found
+
   /videos:
     get:
       summary: List videos
@@ -1586,7 +1710,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -1802,14 +1930,37 @@ paths:
                 example: |
                   **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
 
+  '/videos/{id}/source':
+    post:
+      summary: Get video source file metadata
+      operationId: getVideoSource
+      tags:
+        - Video
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoSource'
+
   '/videos/{id}/views':
     post:
-      summary: Add a view to a video
+      summary: Notify user is watching a video
+      description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
       operationId: addView
       tags:
         - Video
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserViewingVideo'
+        required: true
       responses:
         '204':
           description: successful operation
@@ -1817,7 +1968,8 @@ paths:
   '/videos/{id}/watching':
     put:
       summary: Set watching progress of a video
-      operationId: setProgress
+      deprecated: true
+      description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
       tags:
         - Video
       security:
@@ -1828,12 +1980,97 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UserWatchingVideo'
+              $ref: '#/components/schemas/UserViewingVideo'
         required: true
       responses:
         '204':
           description: successful operation
 
+  '/videos/{id}/stats/overall':
+    get:
+      summary: Get overall stats of a video
+      tags:
+        - Video Stats
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        - name: startDate
+          in: query
+          description: Filter stats by start date
+          schema:
+            type: string
+            format: date-time
+        - name: endDate
+          in: query
+          description: Filter stats by end date
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoStatsOverall'
+
+  '/videos/{id}/stats/retention':
+    get:
+      summary: Get retention stats of a video
+      tags:
+        - Video Stats
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoStatsRetention'
+
+  '/videos/{id}/stats/timeseries/{metric}':
+    get:
+      summary: Get timeserie stats of a video
+      tags:
+        - Video Stats
+      security:
+        - OAuth2: []
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+        -
+          name: metric
+          in: path
+          required: true
+          description: The metric to get
+          schema:
+            type: string
+            enum:
+              - 'viewers'
+              - 'aggregateWatchTime'
+        - name: startDate
+          in: query
+          description: Filter stats by start date
+          schema:
+            type: string
+            format: date-time
+        - name: endDate
+          in: query
+          description: Filter stats by end date
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoStatsTimeserie'
+
   /videos/upload:
     post:
       summary: Upload a video
@@ -1859,7 +2096,7 @@ paths:
           x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
           description: |
             If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
-            - `quota_reached` for quota limits wether daily or global
+            - `quota_reached` for quota limits whether daily or global
           headers:
             X-File-Maximum-Size:
               schema:
@@ -1980,7 +2217,7 @@ paths:
           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
@@ -2004,9 +2241,6 @@ paths:
           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:
@@ -2047,6 +2281,13 @@ paths:
           description: video unreadable
         '429':
           description: too many concurrent requests
+        '503':
+          description: upload is already being processed
+          headers:
+            'Retry-After':
+              schema:
+                type: number
+                example: 300
     delete:
       summary: Cancel the resumable upload of a video, deleting any data uploaded so far
       description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
@@ -2090,7 +2331,7 @@ paths:
       security:
         - OAuth2: []
       tags:
-        - Video
+        - Video Imports
         - Video Upload
       requestBody:
         content:
@@ -2118,6 +2359,34 @@ paths:
         '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
@@ -2162,6 +2431,9 @@ paths:
                 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
@@ -2257,6 +2529,48 @@ paths:
           description: bad parameters or trying to update a live that has already started
         '403':
           description: trying to save replay of the live but saving replay is not enabled on the instance
+  /videos/live/{id}/sessions:
+    get:
+      summary: List live sessions
+      description: List all sessions created in a particular live
+      security:
+        - OAuth2: []
+      tags:
+        - Live Videos
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/LiveVideoSessionResponse'
+  /videos/{id}/live-session:
+    get:
+      summary: Get live session of a replay
+      description: If the video is a replay of a live, you can find the associated live session using this endpoint
+      security:
+        - OAuth2: []
+      tags:
+        - Live Videos
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LiveVideoSessionResponse'
 
   /users/me/abuses:
     get:
@@ -2747,7 +3061,7 @@ paths:
                     type: object
                     properties:
                       id:
-                        $ref: '#/components/schemas/VideoChannel/properties/id'
+                        $ref: '#/components/schemas/id'
       requestBody:
         content:
           application/json:
@@ -2815,7 +3129,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -2828,15 +3146,20 @@ paths:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
 
-  '/video-channels/{channelHandle}/avatar/pick':
-    post:
-      summary: Update channel avatar
-      security:
-        - OAuth2: []
+  '/video-channels/{channelHandle}/followers':
+    get:
       tags:
         - Video Channels
+      summary: 'List followers of a video channel'
+      security:
+        - OAuth2: []
+      operationId: getVideoChannelFollowers
       parameters:
         - $ref: '#/components/parameters/channelHandle'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
+        - $ref: '#/components/parameters/followersSort'
+        - $ref: '#/components/parameters/search'
       responses:
         '200':
           description: successful operation
@@ -2845,15 +3168,42 @@ paths:
               schema:
                 type: object
                 properties:
-                  avatar:
-                    $ref: '#/components/schemas/ActorImage'
-        '413':
-          description: image file too large
-          headers:
-            X-File-Maximum-Size:
-              schema:
-                type: string
-                format: Nginx size
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Follow'
+
+  '/video-channels/{channelHandle}/avatar/pick':
+    post:
+      summary: Update channel avatar
+      security:
+        - OAuth2: []
+      tags:
+        - Video Channels
+      parameters:
+        - $ref: '#/components/parameters/channelHandle'
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  avatars:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'
+        '413':
+          description: image file too large
+          headers:
+            X-File-Maximum-Size:
+              schema:
+                type: string
+                format: Nginx size
               description: Maximum file size for the avatar
       requestBody:
         content:
@@ -2899,8 +3249,10 @@ paths:
               schema:
                 type: object
                 properties:
-                  banner:
-                    $ref: '#/components/schemas/ActorImage'
+                  banners:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ActorImage'
         '413':
           description: image file too large
           headers:
@@ -3111,6 +3463,8 @@ paths:
         - Video Playlists
       parameters:
         - $ref: '#/components/parameters/playlistId'
+        - $ref: '#/components/parameters/start'
+        - $ref: '#/components/parameters/count'
       responses:
         '200':
           description: successful operation
@@ -3291,7 +3645,7 @@ paths:
         - $ref: '#/components/parameters/name'
         - name: withStats
           in: query
-          description: include view statistics for the last 30 days (only if authentified as the account user)
+          description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
           schema:
             type: boolean
         - $ref: '#/components/parameters/start'
@@ -3479,6 +3833,69 @@ paths:
         '404':
           description: video does not exist
 
+  '/videos/{id}/hls':
+    delete:
+      summary: Delete video HLS files
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Files
+      operationId: delVideoHLS
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+  '/videos/{id}/webtorrent':
+    delete:
+      summary: Delete video WebTorrent files
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Files
+      operationId: delVideoWebTorrent
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+
+  '/videos/{id}/transcoding':
+    post:
+      summary: Create a transcoding job
+      security:
+        - OAuth2:
+          - admin
+      tags:
+        - Video Transcoding
+      operationId: createVideoTranscoding
+      parameters:
+        - $ref: '#/components/parameters/idOrUUID'
+      requestBody:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  transcodingType:
+                    type: string
+                    enum:
+                      - hls
+                      - webtorrent
+                required:
+                  - transcodingType
+      responses:
+        '204':
+          description: successful operation
+        '404':
+          description: video does not exist
+
   /search/videos:
     get:
       tags:
@@ -3503,7 +3920,11 @@ paths:
         - $ref: '#/components/parameters/licenceOneOf'
         - $ref: '#/components/parameters/languageOneOf'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
         - $ref: '#/components/parameters/skipCount'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
@@ -3630,6 +4051,39 @@ paths:
         '500':
           description: search index unavailable
 
+  /blocklist/status:
+    get:
+      tags:
+        - Account Blocks
+        - Server Blocks
+      summary: Get block status of accounts/hosts
+      parameters:
+        -
+          name: 'accounts'
+          in: query
+          description: 'Check if these accounts are blocked'
+          example: [ 'goofy@example.com', 'donald@example.com' ]
+          schema:
+            type: array
+            items:
+              type: string
+        -
+          name: 'hosts'
+          in: query
+          description: 'Check if these hosts are blocked'
+          example: [ 'example.com' ]
+          schema:
+            type: array
+            items:
+              type: string
+      responses:
+        '200':
+          description: successful operation
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/BlockStatus'
+
   /server/blocklist/accounts:
     get:
       tags:
@@ -3867,6 +4321,74 @@ paths:
         '404':
           description: video redundancy not found
 
+  /server/stats:
+    get:
+      tags:
+        - Stats
+      summary: Get instance stats
+      description: Get instance public statistics. This endpoint is cached.
+      operationId: getInstanceStats
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServerStats'
+
+  /server/logs/client:
+    post:
+      tags:
+        - Logs
+      summary: Send client log
+      operationId: sendClientLog
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendClientLog'
+      responses:
+        '204':
+          description: successful operation
+
+  /server/logs:
+    get:
+      tags:
+        - Logs
+      summary: Get instance logs
+      operationId: getInstanceLogs
+      security:
+        - OAuth2:
+          - admin
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+
+  /server/audit-logs:
+    get:
+      tags:
+        - Logs
+      summary: Get instance audit logs
+      operationId: getInstanceAuditLogs
+      security:
+        - OAuth2:
+          - admin
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+
   '/feeds/video-comments.{format}':
     get:
       tags:
@@ -4005,7 +4527,11 @@ paths:
             type: string
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
       responses:
         '204':
           description: successful operation
@@ -4086,7 +4612,11 @@ paths:
           required: true
         - $ref: '#/components/parameters/sort'
         - $ref: '#/components/parameters/nsfw'
-        - $ref: '#/components/parameters/filter'
+        - $ref: '#/components/parameters/isLocal'
+        - $ref: '#/components/parameters/include'
+        - $ref: '#/components/parameters/privacyOneOf'
+        - $ref: '#/components/parameters/hasHLSFiles'
+        - $ref: '#/components/parameters/hasWebtorrentFiles'
       responses:
         '204':
           description: successful operation
@@ -4428,23 +4958,31 @@ components:
       name: sort
       in: query
       required: false
-      description: Sort videos by criteria
       schema:
         type: string
         enum:
-        - name
-        - -duration
-        - -createdAt
-        - -publishedAt
-        - -views
-        - -likes
-        - -trending
-        - -hot
+          - name
+          - -duration
+          - -createdAt
+          - -publishedAt
+          - -views
+          - -likes
+          - -trending
+          - -hot
+          - -best
+        description: >
+          Sort videos by criteria (prefixing with `-` means `DESC` order):
+            * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
+            * `best` - Same than `hot`, but also takes into account user video history
+            * `trending` - Sort videos by recent views ("recent" is defined by the admin)
+            * `views` - Sort videos using their `views` counter
+            * `publishedAt` - Sort by video publication date (when it became publicly available)
     videosSearchSort:
       name: sort
       in: query
       required: false
-      description: Sort videos by criteria
+      description: >
+        Sort videos by criteria (prefixing with `-` means `DESC` order):
       schema:
         type: string
         enum:
@@ -4526,6 +5064,15 @@ components:
         type: string
         enum:
         - name
+    followersSort:
+      name: sort
+      in: query
+      required: false
+      description: Sort followers by criteria
+      schema:
+        type: string
+        enum:
+        - createdAt
     name:
       name: name
       in: path
@@ -4538,7 +5085,7 @@ components:
       name: id
       in: path
       required: true
-      description: The user id
+      description: Entity id
       schema:
         $ref: '#/components/schemas/id'
     idOrUUID:
@@ -4710,20 +5257,58 @@ components:
         enum:
         - 'true'
         - 'false'
-    filter:
-      name: filter
+    isLocal:
+      name: isLocal
       in: query
       required: false
-      description: >
-        Special filters which might require special rights:
-         * `local` - only videos local to the instance
-         * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
-         * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
       schema:
-        type: string
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only local or remote videos'
+    hasHLSFiles:
+      name: hasHLSFiles
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only videos that have HLS files'
+    hasWebtorrentFiles:
+      name: hasWebtorrentFiles
+      in: query
+      required: false
+      schema:
+        type: boolean
+      description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
+    privacyOneOf:
+      name: privacyOneOf
+      in: query
+      required: false
+      schema:
+        $ref: '#/components/schemas/VideoPrivacySet'
+      description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+    include:
+      name: include
+      in: query
+      required: false
+      schema:
+        type: integer
         enum:
-        - local
-        - all-local
+        - 0
+        - 1
+        - 2
+        - 4
+        - 8
+      description: >
+        **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
+
+        - `0` NONE
+
+        - `1` NOT_PUBLISHED_STATE
+
+        - `2` BLACKLISTED
+
+        - `4` BLOCKED_OWNER
+
+        - `8` FILES
     subscriptionsUris:
       name: uris
       in: query
@@ -4758,7 +5343,7 @@ components:
           - video-transcoding
           - video-file-import
           - video-import
-          - videos-views
+          - videos-views-stats
           - activitypub-refresher
           - video-redundancy
           - video-live-ending
@@ -4803,7 +5388,7 @@ components:
             moderator: Moderator scope
             user: User scope
   schemas:
-    # Resuable core properties
+    # Reusable core properties
     id:
       type: integer
       minimum: 1
@@ -4917,6 +5502,29 @@ components:
         label:
           type: string
 
+    BlockStatus:
+      properties:
+        accounts:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: account
+            type: object
+            properties:
+              blockedByServer:
+                type: boolean
+              blockedByUser:
+                type: boolean
+        hosts:
+          type: object
+          additionalProperties:
+            x-additionalPropertiesName: host
+            type: object
+            properties:
+              blockedByServer:
+                type: boolean
+              blockedByUser:
+                type: boolean
+
     NSFWPolicy:
       type: string
       enum:
@@ -4940,6 +5548,14 @@ components:
       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`, High latency = `2`, Small Latency = `3`)'
+
     VideoStateConstant:
       properties:
         id:
@@ -4948,7 +5564,23 @@ components:
             - 1
             - 2
             - 3
-          description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
+            - 4
+            - 5
+            - 6
+            - 7
+            - 8
+            - 9
+          description: |
+            The video state:
+            - `1`: Published
+            - `2`: To transcode
+            - `3`: To import
+            - `4`: Waiting for live stream
+            - `5`: Live ended
+            - `6`: To move to an external storage (object storage...)
+            - `7`: Transcoding failed
+            - `8`: Moving to an external storage failed
+            - `9`: To edit using studio edition feature
         label:
           type: string
 
@@ -5019,10 +5651,10 @@ components:
         host:
           type: string
           format: hostname
-        avatar:
-          nullable: true
-          allOf:
-            - $ref: '#/components/schemas/ActorImage'
+        avatars:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActorImage'
     VideoChannelSummary:
       properties:
         id:
@@ -5037,10 +5669,10 @@ components:
         host:
           type: string
           format: hostname
-        avatar:
-          nullable: true
-          allOf:
-            - $ref: '#/components/schemas/ActorImage'
+        avatars:
+          type: array
+          items:
+            $ref: '#/components/schemas/ActorImage'
     PlaylistElement:
       properties:
         position:
@@ -5058,11 +5690,12 @@ components:
     VideoFile:
       readOnly: true
       properties:
+        id:
+          $ref: '#/components/schemas/id'
         magnetUri:
           type: string
           format: uri
           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
-          example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         resolution:
           $ref: '#/components/schemas/VideoResolutionConstant'
@@ -5264,6 +5897,9 @@ components:
         - $ref: '#/components/schemas/Video'
         - type: object
           properties:
+            viewers:
+              type: integer
+              description: If the video is a live, you have the amount of current viewers
             descriptionPath:
               type: string
               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
@@ -5412,7 +6048,6 @@ components:
           type: string
           format: uri
           description: magnet URI allowing to resolve the import's source video
-          example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
         torrentfile:
           writeOnly: true
@@ -5619,10 +6254,16 @@ components:
           $ref: '#/components/schemas/VideoConstantString-Language'
         captionPath:
           type: string
+    VideoSource:
+      properties:
+        filename:
+          type: string
     ActorImage:
       properties:
         path:
           type: string
+        width:
+          type: integer
         createdAt:
           type: string
           format: date-time
@@ -5640,12 +6281,10 @@ components:
         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:
@@ -5678,8 +6317,6 @@ components:
         updatedAt:
           type: string
           format: date-time
-        avatar:
-          $ref: '#/components/schemas/ActorImage'
     Account:
       allOf:
         - $ref: '#/components/schemas/Actor'
@@ -5696,13 +6333,68 @@ components:
             description:
               type: string
               description: text or bio displayed on the account's profile
-    UserWatchingVideo:
+    UserViewingVideo:
+      required:
+        - currentTime
       properties:
         currentTime:
           type: integer
           format: seconds
           description: timestamp within the video, in seconds
           example: 5
+        viewEvent:
+          type: string
+          enum:
+            - seek
+          description: >
+            Event since last viewing call:
+             * `seek` - If the user seeked the video
+
+    VideoStatsOverall:
+      properties:
+        averageWatchTime:
+          type: number
+        totalWatchTime:
+          type: number
+        viewersPeak:
+          type: number
+        viewersPeakDate:
+          type: string
+          format: date-time
+        countries:
+          type: array
+          items:
+            type: object
+            properties:
+              isoCode:
+                type: string
+              viewers:
+                type: number
+
+    VideoStatsRetention:
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+            properties:
+              second:
+                type: number
+              retentionPercent:
+                type: number
+
+    VideoStatsTimeserie:
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+            properties:
+              date:
+                type: string
+              value:
+                type: number
+
     ServerConfig:
       properties:
         instance:
@@ -5908,6 +6600,96 @@ components:
             enabled:
               type: boolean
 
+    SendClientLog:
+      properties:
+        message:
+          type: string
+        url:
+          type: string
+          description: URL of the current user page
+        level:
+          enum:
+            - error
+            - warn
+        stackTrace:
+          type: string
+          description: Stack trace of the error if there is one
+        userAgent:
+          type: string
+          description: User agent of the web browser that sends the message
+        meta:
+          type: string
+          description: Additional information regarding this log
+      required:
+        - message
+        - url
+        - level
+
+    ServerStats:
+      properties:
+        totalUsers:
+          type: number
+        totalDailyActiveUsers:
+          type: number
+        totalWeeklyActiveUsers:
+          type: number
+        totalMonthlyActiveUsers:
+          type: number
+        totalLocalVideos:
+          type: number
+        totalLocalVideoViews:
+          type: number
+          description: Total video views made on the instance
+        totalLocalVideoComments:
+          type: number
+          description: Total comments made by local users
+        totalLocalVideoFilesSize:
+          type: number
+        totalVideos:
+          type: number
+        totalVideoComments:
+          type: number
+        totalLocalVideoChannels:
+          type: number
+        totalLocalDailyActiveVideoChannels:
+          type: number
+        totalLocalWeeklyActiveVideoChannels:
+          type: number
+        totalLocalMonthlyActiveVideoChannels:
+          type: number
+        totalLocalPlaylists:
+          type: number
+        totalInstanceFollowers:
+          type: number
+        totalInstanceFollowing:
+          type: number
+        videosRedundancy:
+          type: array
+          items:
+            type: object
+            properties:
+                strategy:
+                  type: string
+                totalSize:
+                  type: number
+                totalUsed:
+                  type: number
+                totalVideoFiles:
+                  type: number
+                totalVideos:
+                  type: number
+        totalActivityPubMessagesProcessed:
+          type: number
+        totalActivityPubMessagesSuccesses:
+          type: number
+        totalActivityPubMessagesErrors:
+          type: number
+
+        activityPubMessagesProcessedPerSecond:
+          type: number
+        totalActivityPubMessagesWaiting:
+          type: number
+
     ServerConfigAbout:
       properties:
         instance:
@@ -6035,6 +6817,8 @@ components:
               properties:
                 0p:
                   type: boolean
+                144p:
+                  type: boolean
                 240p:
                   type: boolean
                 360p:
@@ -6166,7 +6950,7 @@ components:
             - video-transcoding
             - email
             - video-import
-            - videos-views
+            - videos-views-stats
             - activitypub-refresher
             - video-redundancy
         data:
@@ -6372,6 +7156,8 @@ components:
           format: date-time
         noInstanceConfigWarningModal:
           type: boolean
+        noAccountSetupWarningModal:
+          type: boolean
         noWelcomeModal:
           type: boolean
         nsfwPolicy:
@@ -6401,7 +7187,7 @@ components:
           type: integer
           description: The user daily video quota in bytes
           example: -1
-        webtorrentEnabled:
+        p2pEnabled:
           type: boolean
           description: Enable P2P in the player
     UserWithStats:
@@ -6479,6 +7265,8 @@ components:
           $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:
@@ -6502,7 +7290,7 @@ components:
             - 'true'
             - 'false'
             - both
-        webTorrentEnabled:
+        p2pEnabled:
           type: boolean
           description: whether to enable P2P in the player or not
         autoPlayVideo:
@@ -6526,6 +7314,8 @@ components:
           type: string
         noInstanceConfigWarningModal:
           type: boolean
+        noAccountSetupWarningModal:
+          type: boolean
         noWelcomeModal:
           type: boolean
     GetMeVideoRating:
@@ -6580,7 +7370,7 @@ components:
             name:
               $ref: '#/components/schemas/usernameChannel'
             displayName:
-              $ref: '#/components/schemas/VideoChannel/properties/displayName'
+              type: string
       required:
         - username
         - password
@@ -6642,46 +7432,47 @@ components:
         - 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:
-            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'
@@ -6911,7 +7702,7 @@ components:
       enum:
         - 0
         - 1
-        - 3
+        - 2
     Notification:
       properties:
         id:
@@ -6948,6 +7739,14 @@ components:
             - `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:
@@ -7115,21 +7914,131 @@ components:
         permanentLive:
           description: User can stream multiple times in a permanent live
           type: boolean
+        latencyMode:
+          description: User can select live latency mode if enabled by the instance
+          $ref: '#/components/schemas/LiveVideoLatencyMode'
 
     LiveVideoResponse:
       properties:
         rtmpUrl:
           type: string
+          description: Included in the response if an appropriate token is provided
+        rtmpsUrl:
+          type: string
+          description: Included in the response if an appropriate token is provided
         streamKey:
           type: string
-          description: RTMP stream key to use to stream into this live video
+          description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
         saveReplay:
           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'
 
+    VideoStudioCreateTask:
+      type: array
+      items:
+        anyOf:
+          -
+            title: cut
+            type: object
+            properties:
+              name:
+                type: string
+                enum:
+                  - 'cut'
+              options:
+                type: object
+                properties:
+                  start:
+                    type: integer
+                  end:
+                    type: integer
+          -
+            title: add-intro
+            type: object
+            properties:
+              name:
+                type: string
+                enum:
+                  - 'add-intro'
+              options:
+                type: object
+                properties:
+                  file:
+                    type: string
+                    format: binary
+          -
+            title: add-outro
+            type: object
+            properties:
+              name:
+                type: string
+                enum:
+                  - 'add-outro'
+              options:
+                type: object
+                properties:
+                  file:
+                    type: string
+                    format: binary
+          -
+            title: add-watermark
+            type: object
+            properties:
+              name:
+                type: string
+                enum:
+                  - 'add-watermark'
+              options:
+                type: object
+                properties:
+                  file:
+                    type: string
+                    format: binary
 
+    LiveVideoSessionResponse:
+        properties:
+          id:
+            type: integer
+          startDate:
+            type: string
+            format: date-time
+            description: Start date of the live session
+          endDate:
+            type: string
+            format: date-time
+            nullable: true
+            description: End date of the live session
+          error:
+            type: integer
+            enum:
+              - 1
+              - 2
+              - 3
+              - 4
+              - 5
+            nullable: true
+            description: >
+              Error type if an error occurred during the live session:
+                - `1`: Bad socket health (transcoding is too slow)
+                - `2`: Max duration exceeded
+                - `3`: Quota exceeded
+                - `4`: Quota FFmpeg error
+                - `5`: Video has been blacklisted during the live
+          replayVideo:
+            type: object
+            description: Video replay information
+            properties:
+              id:
+                type: number
+              uuid:
+                $ref: '#/components/schemas/UUIDv4'
+              shortUUID:
+                $ref: '#/components/schemas/shortUUID'
 
   callbacks:
     searchIndex: