store uploaded video filename (#4885)

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

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 407f3eb10f0e6f1c780548083a36aa797761469c..afd310c0b8e2d2f3a097ad3a18a307ac297423fb 100644 (file)
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -247,8 +247,8 @@ tags:
       ### Import
 
       - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
       ### 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.
 
       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.


@@ -1903,6 +1903,22 @@ 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)**
 
                 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: Notify user is watching a video
   '/videos/{id}/views':
     post:
       summary: Notify user is watching a video


@@ -1952,6 +1968,18 @@ paths:
         - OAuth2: []
       parameters:
         - $ref: '#/components/parameters/idOrUUID'
         - 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
       responses:
         '200':
           description: successful operation


@@ -1996,6 +2024,18 @@ paths:
             enum:
               - 'viewers'
               - 'aggregateWatchTime'
             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
       responses:
         '200':
           description: successful operation


@@ -2029,7 +2069,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`:
           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:
           headers:
             X-File-Maximum-Size:
               schema:


@@ -2462,6 +2502,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
           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:
 
   /users/me/abuses:
     get:


@@ -3536,7 +3618,7 @@ paths:
         - $ref: '#/components/parameters/name'
         - name: withStats
           in: query
         - $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'
           schema:
             type: boolean
         - $ref: '#/components/parameters/start'


@@ -4781,23 +4863,31 @@ components:
       name: sort
       in: query
       required: false
       name: sort
       in: query
       required: false

-      description: Sort videos by criteria

       schema:
         type: string
         enum:
       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
     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:
       schema:
         type: string
         enum:


@@ -5203,7 +5293,7 @@ components:
             moderator: Moderator scope
             user: User scope
   schemas:
             moderator: Moderator scope
             user: User scope
   schemas:

-    # Resuable core properties
+    # Reusable core properties

     id:
       type: integer
       minimum: 1
     id:
       type: integer
       minimum: 1


@@ -5369,7 +5459,7 @@ components:
         - 1
         - 2
         - 3
         - 1
         - 2
         - 3

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

 
     VideoStateConstant:
       properties:
 
     VideoStateConstant:
       properties:


@@ -5379,7 +5469,23 @@ components:
             - 1
             - 2
             - 3
             - 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
 
         label:
           type: string
 


@@ -6051,6 +6157,10 @@ components:
           $ref: '#/components/schemas/VideoConstantString-Language'
         captionPath:
           type: string
           $ref: '#/components/schemas/VideoConstantString-Language'
         captionPath:
           type: string

+    VideoSource:
+      properties:
+        filename:
+          type: string

     ActorImage:
       properties:
         path:
     ActorImage:
       properties:
         path:


@@ -6154,14 +6264,6 @@ components:
         viewersPeakDate:
           type: string
           format: date-time
         viewersPeakDate:
           type: string
           format: date-time

-        views:
-          type: number
-        likes:
-          type: number
-        dislikes:
-          type: number
-        comments:
-          type: number

         countries:
           type: array
           items:
         countries:
           type: array
           items:


@@ -7633,11 +7735,13 @@ components:
       properties:
         rtmpUrl:
           type: string
       properties:
         rtmpUrl:
           type: string

+          description: Included in the response if an appropriate token is provided

         rtmpsUrl:
           type: string
         rtmpsUrl:
           type: string

+          description: Included in the response if an appropriate token is provided

         streamKey:
           type: string
         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:
         saveReplay:
           type: boolean
         permanentLive:


@@ -7647,6 +7751,46 @@ components:
           description: User can select live latency mode if enabled by the instance
           $ref: '#/components/schemas/LiveVideoLatencyMode'
 
           description: User can select live latency mode if enabled by the instance
           $ref: '#/components/schemas/LiveVideoLatencyMode'
 

+    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:
       'https://search.example.org/api/v1/search/videos':
   callbacks:
     searchIndex:
       'https://search.example.org/api/v1/search/videos':