5 files changed, 685 insertions, 252 deletions

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index d4fe15664..4fbf5b055 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -12,8 +12,6 @@ info:
     url: 'https://joinpeertube.org/img/brand.png'
     altText: PeerTube Project Homepage
   description: |
-    # Introduction
-
     The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
     HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
@@ -23,13 +21,14 @@ info:
     - [Go](https://framagit.org/framasoft/peertube/clients/go)
     - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
 
-    See the [Quick Start guide](https://docs.joinpeertube.org/api-rest-getting-started) so you can play with the PeerTube API.
+    See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
+    examples of using with the PeerTube API.
 
     # Authentication
 
-    When you sign up for an account, you are given the possibility to generate
-    sessions, and authenticate using this session token. One session token can
-    currently be used at a time.
+    When you sign up for an account on a PeerTube instance, you are given the possibility
+    to generate sessions on it, and authenticate there using a session token. Only __one
+    session token can currently be used at a time__.
 
     ## Roles
 
@@ -48,6 +47,30 @@ info:
       "error": "Token is invalid." // example exposed error message
     }
     ```
+
+    # Rate limits
+
+    We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
+
+    | Endpoint                | Calls            | Time frame                |
+    |-------------------------|------------------|---------------------------|
+    | `/*`                    | 50               | 10 seconds                |
+    | `POST /users/token`     | 15               | 5 minutes                 |
+    | `POST /users/register`  | 2¹               | 5 minutes                 |
+    | `POST /users/ask-send-verify-email` | 3    | 5 minutes                 |
+
+    Depending on the endpoint, ¹failed requests are not taken into account. A service
+    limit is announced by a `429 Too Many Requests` status code.
+
+    You can get details about the current state of your rate limit by reading the
+    following headers:
+
+    | Header                  | Description                                                |
+    |-------------------------|------------------------------------------------------------|
+    | X-RateLimit-Limit       | Number of max requests allowed in the current time period  |
+    | X-RateLimit-Remaining   | Number of remaining requests in the current time period    |
+    | X-RateLimit-Reset       | Timestamp of end of current time period as UNIX timestamp  |
+    | Retry-After             | Seconds to delay after the first `429` is received         |
 externalDocs:
   url: https://docs.joinpeertube.org/api-rest-reference.html
 tags:
@@ -101,7 +124,7 @@ tags:
       Redundancy is part of the inter-server solidarity that PeerTube fosters.
       Manage the list of instances you wish to help by seeding their videos according
       to the policy of video selection of your choice. Note that you have a similar functionality
-      to mirror individual videos, see `Video Mirroring`.
+      to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
     externalDocs:
       url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
   - name: Plugins
@@ -115,6 +138,50 @@ tags:
   - name: Video
     description: |
       Operations dealing with listing, uploading, fetching or modifying videos.
+  - name: Video Upload
+    description: |
+      Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
+
+      ### Upload
+
+      - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
+      - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
+
+      You can upload videos more reliably by using the resumable variant. Its protocol lets
+      you resume an upload operation after a network interruption or other transmission failure,
+      saving time and bandwidth in the event of network failures.
+
+      Favor using resumable uploads in any of the following cases:
+      - You are transferring large files
+      - The likelihood of a network interruption is high
+      - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
+        such as a mobile device
+
+      ### 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
+
+      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 Captions
+    description: Operations dealing with listing, adding and removing closed captions of a video.
+  - name: Video Channels
+    description: Operations dealing with the creation, modification and listing of videos within a channel.
+  - name: Video Comments
+    description: >
+      Operations dealing with comments to a video. Comments are organized in threads: adding a
+      comment in response to the video starts a thread, adding a reply to a comment adds it to
+      its root comment thread.
+  - name: Video Blocks
+    description: Operations dealing with blocking videos (removing them from view and preventing interactions).
+  - name: Video Rates
+    description: Like/dislike a video.
+  - name: Video Playlists
+    description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
+  - name: Feeds
+    description: Server syndication feeds
   - name: Search
     description: |
       The search helps to find _videos_ or _channels_ from within the instance and beyond.
@@ -124,27 +191,11 @@ tags:
 
       Administrators can also enable the use of a remote search system, indexing
       videos and channels not could be not federated by the instance.
-  - name: Video Comments
-    description: >
-      Operations dealing with comments to a video. Comments are organized in
-      threads.
-  - name: Video Playlists
-    description: >
-      Operations dealing with playlists of videos. Playlists are bound to users
-      and/or channels.
-  - name: Video Channels
-    description: >
-      Operations dealing with the creation, modification and listing of videos within a channel.
-  - name: Video Blocks
-    description: >
-      Operations dealing with blocking videos (removing them from view and
-      preventing interactions).
-  - name: Video Rates
-    description: >
-      Like/dislike a video.
-  - name: Feeds
-    description: >
-      Server syndication feeds
+  - name: Video Mirroring
+    description: |
+      PeerTube instances can mirror videos from one another, and help distribute some videos.
+
+      For importing videos as your own, refer to [video imports](#tag/Video-Upload/paths/~1videos~1imports/post).
 x-tagGroups:
   - name: Accounts
     tags:
@@ -157,6 +208,7 @@ x-tagGroups:
   - name: Videos
     tags:
       - Video
+      - Video Upload
       - Video Captions
       - Video Channels
       - Video Comments
@@ -228,7 +280,7 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoListResponse'
-      x-code-samples:
+      x-codeSamples:
         - lang: JavaScript
           source: |
             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
@@ -292,6 +344,9 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfig'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/config
   /config/about:
     get:
       summary: Get instance "About" information
@@ -304,6 +359,9 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ServerConfigAbout'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/api/v1/config/about
   /config/custom:
     get:
       summary: Get instance runtime configuration
@@ -566,13 +624,24 @@ paths:
       tags:
         - Users
       operationId: getUserId
+      parameters:
+        - name: withStats
+          in: query
+          description: include statistics about the user (only available as a moderator/admin)
+          schema:
+            type: boolean
       responses:
         '200':
-          description: successful operation
+          x-summary: successful operation
+          description: |
+            As an admin/moderator, you can request a response augmented with statistics about the user's
+            moderation relations and videos usage, by using the `withStats` parameter.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/User'
+                oneOf:
+                  - $ref: '#/components/schemas/User'
+                  - $ref: '#/components/schemas/UserWithStats'
     put:
       summary: Update a user
       security:
@@ -655,7 +724,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/VideoImport'
+                $ref: '#/components/schemas/VideoImportsList'
   /users/me/video-quota-used:
     get:
       summary: Get my user used quota
@@ -670,7 +739,14 @@ paths:
           content:
             application/json:
               schema:
-                type: number
+                type: object
+                properties:
+                  videoQuotaUsed:
+                    type: number
+                    example: 16810141515
+                  videoQuotaUsedDaily:
+                    type: number
+                    example: 1681014151
   '/users/me/videos/{videoId}/rating':
     get:
       summary: Get rate of my user for a video
@@ -728,6 +804,10 @@ paths:
       responses:
         '200':
           description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoChannelList'
     post:
       tags:
         - My Subscriptions
@@ -1109,6 +1189,7 @@ paths:
   /videos/categories:
     get:
       summary: List available video categories
+      operationId: getCategories
       tags:
         - Video
       responses:
@@ -1126,6 +1207,7 @@ paths:
   /videos/licences:
     get:
       summary: List available video licences
+      operationId: getLicences
       tags:
         - Video
       responses:
@@ -1143,6 +1225,7 @@ paths:
   /videos/languages:
     get:
       summary: List available video languages
+      operationId: getLanguages
       tags:
         - Video
       responses:
@@ -1159,7 +1242,8 @@ paths:
                   externalValue: https://peertube2.cpy.re/api/v1/videos/languages
   /videos/privacies:
     get:
-      summary: List available video privacies
+      summary: List available video privacy policies
+      operationId: getPrivacyPolicies
       tags:
         - Video
       responses:
@@ -1201,16 +1285,11 @@ paths:
                   type: string
                   format: binary
                 category:
-                  description: Video category
-                  type: integer
-                  example: 4
+                  $ref: '#/components/schemas/VideoCategorySet'
                 licence:
-                  description: Video licence
-                  type: integer
-                  example: 2
+                  $ref: '#/components/schemas/VideoLicenceSet'
                 language:
-                  description: Video language
-                  type: string
+                  $ref: '#/components/schemas/VideoLanguageSet'
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 description:
@@ -1323,10 +1402,13 @@ paths:
   /videos/upload:
     post:
       summary: Upload a video
+      description: Uses a single request to upload a video.
+      operationId: uploadLegacy
       security:
         - OAuth2: []
       tags:
         - Video
+        - Video Upload
       responses:
         '200':
           description: successful operation
@@ -1356,80 +1438,7 @@ paths:
         content:
           multipart/form-data:
             schema:
-              type: object
-              properties:
-                videofile:
-                  description: Video file
-                  type: string
-                  format: binary
-                channelId:
-                  description: Channel id that will contain this video
-                  type: integer
-                thumbnailfile:
-                  description: Video thumbnail file
-                  type: string
-                  format: binary
-                previewfile:
-                  description: Video preview file
-                  type: string
-                  format: binary
-                privacy:
-                  $ref: '#/components/schemas/VideoPrivacySet'
-                category:
-                  description: Video category
-                  type: integer
-                  example: 4
-                licence:
-                  description: Video licence
-                  type: integer
-                  example: 2
-                language:
-                  description: Video language
-                  type: string
-                description:
-                  description: Video description
-                  type: string
-                waitTranscoding:
-                  description: Whether or not we wait transcoding before publish the video
-                  type: boolean
-                support:
-                  description: A text tell the audience how to support the video creator
-                  example: Please support my work on <insert crowdfunding plateform>! <3
-                  type: string
-                nsfw:
-                  description: Whether or not this video contains sensitive content
-                  type: boolean
-                name:
-                  description: Video name
-                  type: string
-                  minLength: 3
-                  maxLength: 120
-                tags:
-                  description: Video tags (maximum 5 tags each between 2 and 30 characters)
-                  type: array
-                  minItems: 1
-                  maxItems: 5
-                  uniqueItems: true
-                  items:
-                    type: string
-                    minLength: 2
-                    maxLength: 30
-                commentsEnabled:
-                  description: Enable or disable comments for this video
-                  type: boolean
-                downloadEnabled:
-                  description: Enable or disable downloading for this video
-                  type: boolean
-                originallyPublishedAt:
-                  description: Date when the content was originally published
-                  type: string
-                  format: date-time
-                scheduleUpdate:
-                  $ref: '#/components/schemas/VideoScheduledUpdate'
-              required:
-                - videofile
-                - channelId
-                - name
+              $ref: '#/components/schemas/VideoUploadRequestLegacy'
             encoding:
               videofile:
                 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
@@ -1437,7 +1446,7 @@ paths:
                 contentType: image/jpeg
               previewfile:
                 contentType: image/jpeg
-      x-code-samples:
+      x-codeSamples:
         - lang: Shell
           source: |
             ## DEPENDENCIES: jq
@@ -1466,14 +1475,177 @@ paths:
               --form videofile=@"$FILE_PATH" \
               --form channelId=$CHANNEL_ID \
               --form name="$NAME"
+  /videos/upload-resumable:
+    post:
+      summary: Initialize the resumable upload of a video
+      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
+      operationId: uploadResumableInit
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: X-Upload-Content-Length
+          in: header
+          schema:
+            type: number
+            example: 2469036
+          required: true
+          description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
+        - name: X-Upload-Content-Type
+          in: header
+          schema:
+            type: string
+            format: mimetype
+            example: video/mp4
+          required: true
+          description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VideoUploadRequestResumable'
+      responses:
+        '200':
+          description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
+        '201':
+          description: created
+          headers:
+            Location:
+              schema:
+                type: string
+                format: url
+                example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
+            Content-Length:
+              schema:
+                type: number
+                example: 0
+        '400':
+          description: invalid file field, schedule date or parameter
+        '413':
+          description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+        '415':
+          description: video type unsupported
+    put:
+      summary: Send chunk for the resumable upload of a video
+      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
+      operationId: uploadResumable
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: upload_id
+          in: path
+          required: true
+          description: |
+            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+            not valid anymore and you need to initialize a new upload.
+          schema:
+            type: string
+        - name: Content-Range
+          in: header
+          schema:
+            type: string
+            example: bytes 0-262143/2469036
+          required: true
+          description: |
+            Specifies the bytes in the file that the request is uploading.
+
+            For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
+            262144 bytes (256 x 1024) in a 2,469,036 byte file.
+        - name: Content-Length
+          in: header
+          schema:
+            type: number
+            example: 262144
+          required: true
+          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:
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        '200':
+          description: last chunk received
+          headers:
+            Content-Length:
+              schema:
+                type: number
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/VideoUploadResponse'
+        '308':
+          description: resume incomplete
+          headers:
+            Range:
+              schema:
+                type: string
+                example: bytes=0-262143
+            Content-Length:
+              schema:
+                type: number
+                example: 0
+        '403':
+          description: video didn't pass upload filter
+        '413':
+          description: video file too large, due to quota or max body size limit set by the reverse-proxy
+        '422':
+          description: video unreadable
+    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
+      operationId: uploadResumableCancel
+      security:
+        - OAuth2: []
+      tags:
+        - Video
+        - Video Upload
+      parameters:
+        - name: upload_id
+          in: path
+          required: true
+          description: |
+            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+            not valid anymore and the upload session has already been deleted with its data ;-)
+          schema:
+            type: string
+        - name: Content-Length
+          in: header
+          required: true
+          schema:
+            type: number
+            example: 0
+      responses:
+        '204':
+          description: upload cancelled
+          headers:
+            Content-Length:
+              schema:
+                type: number
+                example: 0
   /videos/imports:
     post:
       summary: Import a video
       description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
+      operationId: importVideo
       security:
         - OAuth2: []
       tags:
         - Video
+        - Video Upload
       requestBody:
         content:
           multipart/form-data:
@@ -1504,16 +1676,11 @@ paths:
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 category:
-                  description: Video category
-                  type: integer
-                  example: 4
+                  $ref: '#/components/schemas/VideoCategorySet'
                 licence:
-                  description: Video licence
-                  type: integer
-                  example: 2
+                  $ref: '#/components/schemas/VideoLicenceSet'
                 language:
-                  description: Video language
-                  type: string
+                  $ref: '#/components/schemas/VideoLanguageSet'
                 description:
                   description: Video description
                   type: string
@@ -1576,6 +1743,7 @@ paths:
   /videos/live:
     post:
       summary: Create a live
+      operationId: createLive
       security:
         - OAuth2: []
       tags:
@@ -1615,14 +1783,11 @@ paths:
                 privacy:
                   $ref: '#/components/schemas/VideoPrivacySet'
                 category:
-                  description: Live video/replay category
-                  type: string
+                  $ref: '#/components/schemas/VideoCategorySet'
                 licence:
-                  description: Live video/replay licence
-                  type: string
+                  $ref: '#/components/schemas/VideoLicenceSet'
                 language:
-                  description: Live video/replay language
-                  type: string
+                  $ref: '#/components/schemas/VideoLanguageSet'
                 description:
                   description: Live video/replay description
                   type: string
@@ -1664,7 +1829,8 @@ paths:
 
   /videos/live/{id}:
     get:
-      summary: Get a live information
+      summary: Get information about a live
+      operationId: getLiveId
       security:
         - OAuth2: []
       tags:
@@ -1680,7 +1846,8 @@ paths:
               schema:
                 $ref: '#/components/schemas/LiveVideoResponse'
     put:
-      summary: Update a live information
+      summary: Update information about a live
+      operationId: updateLiveId
       security:
         - OAuth2: []
       tags:
@@ -1704,6 +1871,7 @@ paths:
   /users/me/abuses:
     get:
       summary: List my abuses
+      operationId: getMyAbuses
       security:
         - OAuth2: []
       tags:
@@ -1719,22 +1887,29 @@ paths:
           in: query
           schema:
             $ref: '#/components/schemas/AbuseStateSet'
+        - $ref: '#/components/parameters/abusesSort'
         - $ref: '#/components/parameters/start'
         - $ref: '#/components/parameters/count'
-        - $ref: '#/components/parameters/abusesSort'
       responses:
         '200':
           description: successful operation
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Abuse'
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Abuse'
 
   /abuses:
     get:
       summary: List abuses
+      operationId: getAbuses
       security:
         - OAuth2:
           - admin
@@ -1807,9 +1982,15 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/Abuse'
+                type: object
+                properties:
+                  total:
+                    type: integer
+                    example: 1
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Abuse'
 
     post:
       summary: Report an abuse
@@ -2124,15 +2305,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  total:
-                    type: integer
-                    example: 1
-                  data:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoChannelList'
     post:
       summary: Create a video channel
       security:
@@ -2324,7 +2497,8 @@ paths:
 
   /video-playlists/privacies:
     get:
-      summary: List available playlist privacies
+      summary: List available playlist privacy policies
+      operationId: getPlaylistPrivacyPolicies
       tags:
         - Video Playlists
       responses:
@@ -2343,6 +2517,7 @@ paths:
   /video-playlists:
     get:
       summary: List video playlists
+      operationId: getPlaylists
       tags:
         - Video Playlists
       parameters:
@@ -2367,6 +2542,7 @@ paths:
     post:
       summary: Create a video playlist
       description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
+      operationId: createPlaylist
       security:
         - OAuth2: []
       tags:
@@ -2666,14 +2842,7 @@ paths:
           content:
             application/json:
               schema:
-                properties:
-                  total:
-                    type: integer
-                    example: 1
-                  data:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoChannelList'
   '/accounts/{name}/ratings':
     get:
       summary: List ratings of an account
@@ -2931,9 +3100,7 @@ paths:
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/VideoChannel'
+                $ref: '#/components/schemas/VideoChannelList'
         '500':
           description: search index unavailable
   /blocklist/accounts:
@@ -3168,13 +3335,6 @@ paths:
       tags:
         - Feeds
       summary: List comments on videos
-      servers:
-        - url: 'https://peertube2.cpy.re'
-          description: Live Test Server (live data - latest nightly version)
-        - url: 'https://peertube3.cpy.re'
-          description: Live Test Server (live data - latest RC version)
-        - url: 'https://peertube.cpy.re'
-          description: Live Test Server (live data - stable version)
       parameters:
         - name: format
           in: path
@@ -3227,18 +3387,33 @@ paths:
             application/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
             application/rss+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
             text/xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
             application/atom+xml:
               schema:
                 $ref: '#/components/schemas/VideoCommentsForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
             application/json:
               schema:
                 type: object
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
         '400':
           x-summary: field inconsistencies
           description: >
@@ -3253,13 +3428,6 @@ paths:
       tags:
         - Feeds
       summary: List videos
-      servers:
-        - url: 'https://peertube2.cpy.re'
-          description: Live Test Server (live data - latest nightly version)
-        - url: 'https://peertube3.cpy.re'
-          description: Live Test Server (live data - latest RC version)
-        - url: 'https://peertube.cpy.re'
-          description: Live Test Server (live data - stable version)
       parameters:
         - name: format
           in: path
@@ -3316,19 +3484,93 @@ paths:
             application/rss+xml:
               schema:
                 $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
             text/xml:
               schema:
                 $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
             application/atom+xml:
               schema:
                 $ref: '#/components/schemas/VideosForXML'
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
             application/json:
               schema:
                 type: object
+              examples:
+                nightly:
+                  externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
         '404':
           description: video channel or account not found
         '406':
           description: accept header unsupported
+  '/feeds/subscriptions.{format}':
+    get:
+      tags:
+        - Feeds
+        - Account
+      summary: List videos of subscriptions tied to a token
+      parameters:
+        - name: format
+          in: path
+          required: true
+          description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
+          schema:
+            type: string
+            enum:
+              - xml
+              - rss
+              - rss2
+              - atom
+              - atom1
+              - json
+              - json1
+        - name: accountId
+          in: query
+          description: limit listing to a specific account
+          schema:
+            type: string
+          required: true
+        - name: token
+          in: query
+          description: private token allowing access
+          schema:
+            type: string
+          required: true
+        - $ref: '#/components/parameters/sort'
+        - $ref: '#/components/parameters/nsfw'
+        - $ref: '#/components/parameters/filter'
+      responses:
+        '204':
+          description: successful operation
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+                default: 'max-age=900' # 15 min cache
+          content:
+            application/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/rss+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            text/xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/atom+xml:
+              schema:
+                $ref: '#/components/schemas/VideosForXML'
+            application/json:
+              schema:
+                type: object
+        '406':
+          description: accept header unsupported
   /plugins:
     get:
       tags:
@@ -3823,7 +4065,7 @@ components:
       name: categoryOneOf
       in: query
       required: false
-      description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
+      description: category id of the video (see [/videos/categories](#operation/getCategories))
       schema:
         oneOf:
         - type: integer
@@ -3841,6 +4083,7 @@ components:
         oneOf:
         - type: string
         - type: array
+          maxItems: 5
           items:
             type: string
       style: form
@@ -3862,7 +4105,7 @@ components:
       name: languageOneOf
       in: query
       required: false
-      description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language
+      description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
       schema:
         oneOf:
         - type: string
@@ -3875,7 +4118,7 @@ components:
       name: licenceOneOf
       in: query
       required: false
-      description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
+      description: licence id of the video (see [/videos/licences](#operation/getLicences))
       schema:
         oneOf:
         - type: integer
@@ -3959,19 +4202,16 @@ components:
           - video-live-ending
   securitySchemes:
     OAuth2:
-      description: >
-        In the header: *Authorization: Bearer <token\>*
-
-
+      description: |
         Authenticating via OAuth requires the following steps:
-
-
-        - Have an account with sufficient authorization levels
-
+        - Have an activated account
         - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
-        Bearer Token
+        Bearer Token for that account at `/api/v1/users/token`
+        - Make authenticated requests, putting *Authorization: Bearer <token\>*
+        - Profit, depending on the role assigned to the account
 
-        - Make Authenticated Requests
+        Note that the __access token is valid for 1 day__ and, and is given
+        along with a __refresh token valid for 2 weeks__.
       type: oauth2
       flows:
         password:
@@ -3991,25 +4231,33 @@ components:
       minLength: 36
       maxLength: 36
 
+    VideoCategorySet:
+      type: integer
+      description: category id of the video (see [/videos/categories](#operation/getCategories))
     VideoConstantNumber-Category:
       properties:
         id:
-          type: integer
-          description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
+          $ref: '#/components/schemas/VideoCategorySet'
         label:
           type: string
+
+    VideoLicenceSet:
+      type: integer
+      description: licence id of the video (see [/videos/licences](#operation/getLicences))
     VideoConstantNumber-Licence:
       properties:
         id:
-          type: integer
-          description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
+          $ref: '#/components/schemas/VideoLicenceSet'
         label:
           type: string
+    
+    VideoLanguageSet:
+      type: string
+      description: language id of the video (see [/videos/languages](#operation/getLanguages))
     VideoConstantString-Language:
       properties:
         id:
-          type: string
-          description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
+          $ref: '#/components/schemas/VideoLanguageSet'
         label:
           type: string
 
@@ -4019,7 +4267,7 @@ components:
         - 1
         - 2
         - 3
-      description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
+      description: Video playlist privacy policy (see [/video-playlists/privacies])
     VideoPlaylistPrivacyConstant:
       properties:
         id:
@@ -4032,7 +4280,7 @@ components:
       enum:
         - 1
         - 2
-      description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
+      description: The video playlist type (Regular = `1`, Watch Later = `2`)
     VideoPlaylistTypeConstant:
       properties:
         id:
@@ -4047,7 +4295,7 @@ components:
         - 2
         - 3
         - 4
-      description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
+      description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
     VideoPrivacyConstant:
       properties:
         id:
@@ -4118,12 +4366,17 @@ components:
         - captions
       example: [spamOrMisleading]
 
+    VideoResolutionSet:
+      type: integer
+      description: |
+        Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
+
+        `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
+      example: 240
     VideoResolutionConstant:
       properties:
         id:
-          type: integer
-          description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
-          example: 240
+          $ref: '#/components/schemas/VideoResolutionSet'
         label:
           type: string
           example: 240p
@@ -4507,6 +4760,16 @@ components:
           format: date-time
         video:
           $ref: '#/components/schemas/Video'
+    VideoImportsList:
+      properties:
+        total:
+          type: integer
+          example: 1
+        data:
+          type: array
+          maxItems: 100
+          items:
+            $ref: '#/components/schemas/VideoImport'
     Abuse:
       properties:
         id:
@@ -4540,7 +4803,7 @@ components:
         message:
           type: string
           minLength: 2
-          maxLength: 3000 
+          maxLength: 3000
         byModerator:
           type: boolean
         createdAt:
@@ -4717,6 +4980,8 @@ components:
         host:
           type: string
           format: hostname
+        hostRedundancyAllowed:
+          type: boolean
         followingCount:
           type: integer
         followersCount:
@@ -4831,7 +5096,7 @@ components:
             enabledResolutions:
               type: array
               items:
-                type: integer
+                $ref: '#/components/schemas/VideoResolutionSet'
         import:
           type: object
           properties:
@@ -5032,6 +5297,7 @@ components:
               type: boolean
         user:
           type: object
+          description: Settings that apply to new users, if registration is enabled
           properties:
             videoQuota:
               type: integer
@@ -5039,18 +5305,34 @@ components:
               type: integer
         transcoding:
           type: object
+          description: Settings pertaining to transcoding jobs
           properties:
             enabled:
               type: boolean
             allowAdditionalExtensions:
               type: boolean
+              description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
             allowAudioFiles:
               type: boolean
+              description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
             threads:
               type: integer
+              description: Amount of threads used by ffmpeg for 1 transcoding job
+            concurrency:
+              type: number
+              description: Amount of transcoding jobs to execute in parallel
+            profile:
+              type: string
+              enum:
+                - default
+              description: |
+                New profiles can be added by plugins ; available in core PeerTube: 'default'.
             resolutions:
               type: object
+              description: Resolutions to transcode _new videos_ to
               properties:
+                0p:
+                  type: boolean
                 240p:
                   type: boolean
                 360p:
@@ -5065,8 +5347,15 @@ components:
                   type: boolean
                 2160p:
                   type: boolean
+            webtorrent:
+              type: object
+              description: WebTorrent-specific settings
+              properties:
+                enabled:
+                  type: boolean
             hls:
               type: object
+              description: HLS-specific settings
               properties:
                 enabled:
                   type: boolean
@@ -5133,6 +5422,7 @@ components:
     PredefinedAbuseReasons:
       description: Reason categories that help triage reports
       type: array
+      maxItems: 8
       items:
         type: string
         enum:
@@ -5202,6 +5492,98 @@ components:
                 id:
                   type: integer
                   example: 37
+    VideoUploadRequestCommon:
+      properties:
+        name:
+          description: Video name
+          type: string
+        channelId:
+          description: Channel id that will contain this video
+          type: integer
+        privacy:
+          $ref: '#/components/schemas/VideoPrivacySet'
+        category:
+          $ref: '#/components/schemas/VideoCategorySet'
+        licence:
+          $ref: '#/components/schemas/VideoLicenceSet'
+        language:
+          $ref: '#/components/schemas/VideoLanguageSet'
+        description:
+          description: Video description
+          type: string
+        waitTranscoding:
+          description: Whether or not we wait transcoding before publish the video
+          type: boolean
+        support:
+          description: A text tell the audience how to support the video creator
+          example: Please support my work on <insert crowdfunding plateform>! <3
+          type: string
+        nsfw:
+          description: Whether or not this video contains sensitive content
+          type: boolean
+        tags:
+          description: Video tags (maximum 5 tags each between 2 and 30 characters)
+          type: array
+          minItems: 1
+          maxItems: 5
+          uniqueItems: true
+          items:
+            type: string
+            minLength: 2
+            maxLength: 30
+        commentsEnabled:
+          description: Enable or disable comments for this video
+          type: boolean
+        downloadEnabled:
+          description: Enable or disable downloading for this video
+          type: boolean
+        originallyPublishedAt:
+          description: Date when the content was originally published
+          type: string
+          format: date-time
+        scheduleUpdate:
+          $ref: '#/components/schemas/VideoScheduledUpdate'
+        thumbnailfile:
+          description: Video thumbnail file
+          type: string
+          format: binary
+        previewfile:
+          description: Video preview file
+          type: string
+          format: binary
+      required:
+        - channelId
+        - name
+    VideoUploadRequestLegacy:
+      allOf:
+        - $ref: '#/components/schemas/VideoUploadRequestCommon'
+        - type: object
+          required:
+            - videofile
+          properties:
+            videofile:
+              description: Video file
+              type: string
+              format: binary
+    VideoUploadRequestResumable:
+      allOf:
+        - $ref: '#/components/schemas/VideoUploadRequestCommon'
+        - type: object
+          required:
+            - filename
+          properties:
+            filename:
+              description: Video filename including extension
+              type: string
+              format: filename
+            thumbnailfile:
+              description: Video thumbnail file
+              type: string
+              format: binary
+            previewfile:
+              description: Video preview file
+              type: string
+              format: binary
     VideoUploadResponse:
       properties:
         video:
@@ -5238,35 +5620,45 @@ components:
             $ref: '#/components/schemas/Video'
     User:
       properties:
-        id:
-          type: integer
-          readOnly: true
-        username:
+        account:
+          $ref: '#/components/schemas/Account'
+        autoPlayNextVideo:
+          type: boolean
+          description: Automatically start playing the upcoming video after the currently playing video
+        autoPlayNextVideoPlaylist:
+          type: boolean
+          description: Automatically start playing the video on the playlist after the currently playing video
+        autoPlayVideo:
+          type: boolean
+          description: Automatically start playing the video on the watch page
+        blocked:
+          type: boolean
+        blockedReason:
+          type: string
+        createdAt:
           type: string
-          description: The user username
-          minLength: 1
-          maxLength: 50
         email:
           type: string
           format: email
           description: The user email
+        emailVerified:
+          type: boolean
+          description: Has the user confirmed their email address?
+        id:
+          type: integer
+          readOnly: true
         pluginAuth:
           type: string
           description: Auth plugin to use to authenticate the user
-        theme:
+        lastLoginDate:
           type: string
-          description: Theme enabled by this user
-        emailVerified:
+          format: date-time
+        noInstanceConfigWarningModal:
+          type: boolean
+        noWelcomeModal:
           type: boolean
-          description: Has the user confirmed their email address?
         nsfwPolicy:
           $ref: '#/components/schemas/NSFWPolicy'
-        webtorrentEnabled:
-          type: boolean
-          description: Enable P2P in the player
-        autoPlayVideo:
-          type: boolean
-          description: Automatically start playing the video on the watch page
         role:
           $ref: '#/components/schemas/UserRole'
         roleLabel:
@@ -5275,38 +5667,49 @@ components:
             - User
             - Moderator
             - Administrator
-        videoQuota:
-          type: integer
-          description: The user video quota
-        videoQuotaDaily:
-          type: integer
-          description: The user daily video quota
-        videosCount:
-          type: integer
-        abusesCount:
-          type: integer
-        abusesAcceptedCount:
-          type: integer
-        abusesCreatedCount:
-          type: integer
-        videoCommentsCount:
-          type: integer
-        noInstanceConfigWarningModal:
-          type: boolean
-        noWelcomeModal:
-          type: boolean
-        blocked:
-          type: boolean
-        blockedReason:
+        theme:
           type: string
-        createdAt:
+          description: Theme enabled by this user
+        username:
           type: string
-        account:
-          $ref: '#/components/schemas/Account'
+          description: The user username
+          minLength: 1
+          maxLength: 50
         videoChannels:
           type: array
           items:
             $ref: '#/components/schemas/VideoChannel'
+        videoQuota:
+          type: integer
+          description: The user video quota in bytes
+          example: -1
+        videoQuotaDaily:
+          type: integer
+          description: The user daily video quota in bytes
+          example: -1
+        webtorrentEnabled:
+          type: boolean
+          description: Enable P2P in the player
+    UserWithStats:
+      allOf:
+        - $ref: '#/components/schemas/User'
+        - properties:
+            # optionally present fields: they require WITH_STATS scope
+            videosCount:
+              type: integer
+              description: Count of videos published 
+            abusesCount:
+              type: integer
+              description: Count of reports/abuses of which the user is a target
+            abusesAcceptedCount:
+              type: integer
+              description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
+            abusesCreatedCount:
+              type: integer
+              description: Count of reports/abuses created by the user
+            videoCommentsCount:
+              type: integer
+              description: Count of comments published
     AddUser:
       properties:
         username:
@@ -5314,6 +5717,7 @@ components:
           description: The user username
           minLength: 1
           maxLength: 50
+          pattern: '/^[a-z0-9._]{1,50}$/'
         password:
           type: string
           format: password
@@ -5333,6 +5737,7 @@ components:
         channelName:
           type: string
           description: The user default channel username
+          pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
         role:
           $ref: '#/components/schemas/UserRole'
         adminFlags:
@@ -5406,7 +5811,11 @@ components:
           type: string
           description: Id of the video
         rating:
-          type: number
+          type: string
+          enum:
+            - like
+            - dislike
+            - none
           description: Rating of the video
       required:
         - id
@@ -5416,8 +5825,12 @@ components:
         video:
           $ref: '#/components/schemas/Video'
         rating:
-          type: number
-          description: 'Rating of the video'
+          type: string
+          enum:
+            - like
+            - dislike
+            - none
+          description: Rating of the video
       required:
         - video
         - rating
@@ -5495,6 +5908,17 @@ components:
             bulkVideosSupportUpdate:
               type: boolean
               description: 'Update the support field for all videos of this channel'
+    VideoChannelList:
+      properties:
+        total:
+          type: integer
+          example: 1
+        data:
+          type: array
+          items:
+            allOf:
+              - $ref: '#/components/schemas/VideoChannel'
+              - $ref: '#/components/schemas/Actor'
 
     MRSSPeerLink:
       type: object
diff --git a/support/doc/dependencies.md b/support/doc/dependencies.md
index 9666d72af..939772a9d 100644
--- a/support/doc/dependencies.md
+++ b/support/doc/dependencies.md
@@ -307,7 +307,7 @@ brew services run redis
 ```
 
 On macOS, the `postgresql` user can be `_postgres` instead of `postgres`.
-If `sudo -u postgres createuser -P peertube` gives you an error, you can try `sudo -u _postgres createuser -U peertube`.
+If `sudo -u postgres createuser -P peertube` gives you an `unknown user: postgres` error, you can try `sudo -u _postgres createuser -U peertube`.
 
 ## Gentoo
 
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index 53d53c26d..5b7d1cb31 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -261,8 +261,8 @@ function register ({
   router.get('/ping', (req, res) => res.json({ message: 'pong' }))
 
   // Users are automatically authenticated
-  router.get('/auth', (res, res) => {
-    const user = peertubeHelpers.user.getAuthUser(res)
+  router.get('/auth', async (res, res) => {
+    const user = await peertubeHelpers.user.getAuthUser(res)
 
     const isAdmin = user.role === 0
     const isModerator = user.role === 1
diff --git a/support/docker/production/Dockerfile.buster b/support/docker/production/Dockerfile.buster
index b3822964d..2ff0591f9 100644
--- a/support/docker/production/Dockerfile.buster
+++ b/support/docker/production/Dockerfile.buster
@@ -7,7 +7,7 @@ ARG NPM_RUN_BUILD_OPTS
 
 # Install dependencies
 RUN apt update \
- && apt install -y --no-install-recommends openssl ffmpeg python ca-certificates gnupg gosu build-essential \
+ && apt install -y --no-install-recommends openssl ffmpeg python ca-certificates gnupg gosu build-essential curl \
  && gosu nobody true \
  && rm /var/lib/apt/lists/* -fR
 
diff --git a/support/nginx/peertube b/support/nginx/peertube
index 00ce1d0dc..d03f14613 100644
--- a/support/nginx/peertube
+++ b/support/nginx/peertube
@@ -78,6 +78,15 @@ server {
     try_files /dev/null @api;
   }
 
+  location = /api/v1/videos/upload-resumable {
+    if ($request_method = 'PUT') {
+      client_max_body_size    0;
+      proxy_request_buffering off;
+    }
+
+    try_files /dev/null @api;
+  }
+
   location = /api/v1/videos/upload {
     limit_except POST HEAD { deny all; }