X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=74963df140cf27a97e25198e56ecde369c47606f;hb=f9079a78bd84e3745b20a6a36c5d2a8c693427b0;hp=70f2d97f55f81d90f832262c7b1e05c084a556a2;hpb=7b51ede977c299a74728171d8c124bcc4cbba6ea;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 70f2d97f5..74963df14 100644 --- 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/) - - _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. @@ -273,6 +273,8 @@ tags: 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 @@ -291,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: @@ -314,6 +320,7 @@ x-tagGroups: - Video Comments - Video Rates - Video Playlists + - Video Stats - Video Ownership Change - Video Mirroring - Video Files @@ -323,23 +330,21 @@ x-tagGroups: - 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}': @@ -1666,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 @@ -1900,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 @@ -1915,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: @@ -1926,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 @@ -1957,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: @@ -2078,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 @@ -2102,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: @@ -2295,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 @@ -2390,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: @@ -3464,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' @@ -4140,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: @@ -4709,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: @@ -5131,7 +5388,7 @@ components: moderator: Moderator scope user: User scope schemas: - # Resuable core properties + # Reusable core properties id: type: integer minimum: 1 @@ -5291,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: @@ -5299,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 @@ -5409,6 +5690,8 @@ components: VideoFile: readOnly: true properties: + id: + $ref: '#/components/schemas/id' magnetUri: type: string format: uri @@ -5971,6 +6254,10 @@ components: $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string + VideoSource: + properties: + filename: + type: string ActorImage: properties: path: @@ -6046,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: @@ -6258,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: @@ -7482,23 +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: