X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=a71b571b87ea1cea8032e0903c5f93240ad5ef37;hb=30b40713f48f993fac6db8d4dbd712018bbde847;hp=eec4e0248649bcce80b755592e12682bb6613271;hpb=1e904cde34ba41a16256da1073336dd652368592;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index eec4e0248..a71b571b8 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: 2.2.0 + version: 3.1.0 contact: name: PeerTube Community url: 'https://joinpeertube.org' @@ -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,18 +21,19 @@ 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 Accounts are given permissions based on their role. There are three roles on - PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/#/admin-managing-users?id=roles) for a detail of their permissions. + PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions. # Errors @@ -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: @@ -70,6 +93,9 @@ tags: description: > Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications! + - name: My History + description: > + Operations related to your watch history. - name: My Notifications description: > Notifications following new videos, follows or reports. They allow you @@ -92,26 +118,70 @@ tags: information across its social graph by posting activities to actors' inbox endpoints. externalDocs: - url: https://docs.joinpeertube.org/#/admin-following-instances?id=instances-follows + url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows - name: Instance Redundancy description: > 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 + url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy - name: Plugins description: > Managing plugins installed from a local path or from NPM, or search for new ones. externalDocs: - url: https://docs.joinpeertube.org/#/api-plugins - - name: Video Abuses + url: https://docs.joinpeertube.org/api-plugins + - name: Abuses description: | - Video abuses deal with reports of local or remote videos alike. + Abuses deal with reports of local or remote videos/comments/accounts alike. - 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_](#tag/Video-Upload/paths/~1videos~1upload/post), where the video file is sent in a single request + - [_resumable_](#tag/Video-Upload/paths/~1videos~1upload-resumable/post), 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. @@ -121,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: @@ -150,9 +204,11 @@ x-tagGroups: - My User - My Subscriptions - My Notifications + - My History - name: Videos tags: - Video + - Video Upload - Video Captions - Video Channels - Video Comments @@ -160,13 +216,14 @@ x-tagGroups: - Video Playlists - Video Ownership Change - Video Mirroring + - Live Videos - Feeds - name: Search tags: - Search - name: Moderation tags: - - Video Abuses + - Abuses - Video Blocks - Account Blocks - Server Blocks @@ -205,6 +262,7 @@ paths: parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -233,8 +291,8 @@ paths: }) - lang: Shell source: | - # pip install httpie - http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos + ## DEPENDENCIES: jq + curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq - lang: Ruby source: | require 'net/http' @@ -305,7 +363,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -319,7 +377,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -335,7 +393,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -344,22 +402,24 @@ paths: summary: List instance jobs security: - OAuth2: - - admin + - admin tags: - Job parameters: - name: state in: path required: true - description: The state of the job + description: The state of the job ('' for for no filter) schema: type: string enum: + - '' - active - completed - failed - waiting - delayed + - $ref: '#/components/parameters/jobType' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' @@ -454,7 +514,7 @@ paths: post: security: - OAuth2: - - admin + - admin tags: - Instance Follows summary: Follow a server @@ -480,7 +540,7 @@ paths: summary: Create a user security: - OAuth2: - - admin + - admin tags: - Users responses: @@ -518,10 +578,13 @@ paths: get: summary: List users security: - - OAuth2: [] + - OAuth2: + - admin tags: - Users parameters: + - $ref: '#/components/parameters/usersSearch' + - $ref: '#/components/parameters/usersBlocked' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/usersSort' @@ -541,7 +604,7 @@ paths: summary: Delete a user security: - OAuth2: - - admin + - admin tags: - Users operationId: delUserId @@ -630,7 +693,7 @@ paths: summary: Get video imports of my user security: - OAuth2: - - user + - user tags: - Videos - My User @@ -659,7 +722,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 @@ -707,7 +777,7 @@ paths: summary: Get my user subscriptions security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -723,7 +793,7 @@ paths: summary: Add subscription to my user security: - OAuth2: - - user + - user requestBody: content: application/json: @@ -748,7 +818,7 @@ paths: summary: Get if subscriptions exist for my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -771,6 +841,7 @@ paths: - Videos parameters: - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -793,7 +864,7 @@ paths: summary: Get subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -809,7 +880,7 @@ paths: summary: Delete subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -890,7 +961,7 @@ paths: $ref: '#/components/schemas/NotificationSettingValue' newCommentOnMyVideo: $ref: '#/components/schemas/NotificationSettingValue' - videoAbuseAsModerator: + abuseAsModerator: $ref: '#/components/schemas/NotificationSettingValue' videoAutoBlacklistAsModerator: $ref: '#/components/schemas/NotificationSettingValue' @@ -913,6 +984,44 @@ paths: responses: '204': description: successful operation + /users/me/history/videos: + get: + summary: List watched videos history + security: + - OAuth2: [] + tags: + - My History + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/search' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoListResponse' + /users/me/history/videos/remove: + post: + summary: Clear video history + security: + - OAuth2: [] + tags: + - My History + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + beforeDate: + description: history before this date will be deleted + type: string + format: date-time + responses: + '204': + description: successful operation /users/me/avatar/pick: post: summary: Update my user avatar @@ -926,7 +1035,18 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Avatar' + 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 + description: Maximum file size for the avatar requestBody: content: multipart/form-data: @@ -940,6 +1060,17 @@ paths: encoding: avatarfile: contentType: image/png, image/jpeg + /users/me/avatar: + delete: + summary: Delete my avatar + security: + - OAuth2: [] + tags: + - My User + responses: + '204': + description: successful operation + /videos/ownership: get: summary: List video ownership changes @@ -1016,6 +1147,7 @@ paths: - Video parameters: - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -1156,6 +1288,8 @@ paths: 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 @@ -1248,10 +1382,12 @@ paths: /videos/upload: post: summary: Upload a video + description: Uses a single request to upload a video. security: - OAuth2: [] tags: - Video + - Video Upload responses: '200': description: successful operation @@ -1259,85 +1395,29 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + description: invalid file field, schedule date or parameter '403': - description: user video quota is exceeded with this video + description: video didn't pass upload filter '408': description: upload has timed out + '413': + description: video file too large, due to quota or max body size limit set by the reverse-proxy + headers: + X-File-Maximum-Size: + schema: + type: string + format: Nginx size + description: Maximum file size for the video + '415': + description: video type unsupported '422': - description: invalid input file + description: video unreadable requestBody: 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: string - language: - description: Video language - type: integer - example: 2 - description: - description: Video description - type: string - waitTranscoding: - description: Whether or not we wait transcoding before publish the video - type: string - support: - description: A text tell the audience how to support the video creator - example: Please support my work on ! <3 - type: string - nsfw: - description: Whether or not this video contains sensitive content - type: boolean - name: - description: Video name - type: string - 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 - 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 @@ -1348,8 +1428,7 @@ paths: x-code-samples: - lang: Shell source: | - ## DEPENDENCIES: httpie, jq - # pip install httpie + ## DEPENDENCIES: jq USERNAME="" PASSWORD="" FILE_PATH="" @@ -1358,19 +1437,181 @@ paths: API_PATH="https://peertube2.cpy.re/api/v1" ## AUTH - client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id") - client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret") - token=$(http -b --form POST "$API_PATH/users/token" \ - client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \ - username=$USERNAME \ - password=$PASSWORD \ + client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id") + client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret") + token=$(curl -s "$API_PATH/users/token" \ + --data client_id="$client_id" \ + --data client_secret="$client_secret" \ + --data grant_type=password \ + --data response_type=code \ + --data username="$USERNAME" \ + --data password="$PASSWORD" \ | jq -r ".access_token") ## VIDEO UPLOAD - http -b --form POST "$API_PATH/videos/upload" \ - videofile@$FILE_PATH \ - channelId=$CHANNEL_ID \ - name=$NAME \ - "Authorization:Bearer $token" + curl -s "$API_PATH/videos/upload" \ + -H "Authorization: Bearer $token" \ + --max-time 600 \ + --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 + 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 + 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 + 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 @@ -1379,6 +1620,7 @@ paths: - OAuth2: [] tags: - Video + - Video Upload requestBody: content: multipart/form-data: @@ -1410,10 +1652,12 @@ paths: $ref: '#/components/schemas/VideoPrivacySet' category: description: Video category - type: string + type: integer + example: 4 licence: description: Video licence - type: string + type: integer + example: 2 language: description: Video language type: string @@ -1422,17 +1666,19 @@ paths: type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video - type: string + type: boolean support: description: A text tell the audience how to support the video creator example: Please support my work on ! <3 type: string nsfw: description: Whether or not this video contains sensitive content - type: string + 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 @@ -1444,7 +1690,10 @@ paths: maxLength: 30 commentsEnabled: description: Enable or disable comments for this video - type: string + type: boolean + downloadEnabled: + description: Enable or disable downloading for this video + type: boolean scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' required: @@ -1464,19 +1713,181 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + description: '`magnetUri` or `targetUrl` or a torrent file missing' + '403': + description: video didn't pass pre-import filter '409': description: HTTP or Torrent/magnetURI import not enabled + + /videos/live: + post: + summary: Create a live + security: + - OAuth2: [] + tags: + - Live Videos + - Video + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoUploadResponse' + '403': + description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + channelId: + description: Channel id that will contain this live video + type: integer + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + thumbnailfile: + description: Live video/replay thumbnail file + type: string + format: binary + previewfile: + description: Live video/replay preview file + type: string + format: binary + privacy: + $ref: '#/components/schemas/VideoPrivacySet' + category: + description: Live video/replay category + type: string + licence: + description: Live video/replay licence + type: string + language: + description: Live video/replay language + type: string + description: + description: Live video/replay description + type: string + support: + description: A text tell the audience how to support the creator + example: Please support my work on ! <3 + type: string + nsfw: + description: Whether or not this live video/replay contains sensitive content + type: boolean + name: + description: Live video/replay name + type: string + minLength: 3 + maxLength: 120 + tags: + description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters) + type: array + minItems: 1 + maxItems: 5 + items: + type: string + minLength: 2 + maxLength: 30 + commentsEnabled: + description: Enable or disable comments for this live video/replay + type: boolean + downloadEnabled: + description: Enable or disable downloading for the replay of this live + type: boolean + required: + - channelId + - name + encoding: + thumbnailfile: + contentType: image/jpeg + previewfile: + contentType: image/jpeg + + /videos/live/{id}: + get: + summary: Get information about a live + security: + - OAuth2: [] + tags: + - Live Videos + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoResponse' + put: + summary: Update information about a live + security: + - OAuth2: [] + tags: + - Live Videos + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoUpdate' + responses: + '204': + description: Successful operation '400': - description: '`magnetUri` or `targetUrl` or a torrent file missing' - /videos/abuse: + 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 + + /users/me/abuses: get: - summary: List video abuses + summary: List my abuses + security: + - OAuth2: [] + tags: + - Abuses + - My User + parameters: + - name: id + in: query + description: only list the report with this id + schema: + type: integer + - name: state + in: query + schema: + $ref: '#/components/schemas/AbuseStateSet' + - $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' + + /abuses: + get: + summary: List abuses security: - OAuth2: - admin - moderator tags: - - Video Abuses + - Abuses parameters: - name: id in: query @@ -1487,16 +1898,7 @@ paths: in: query description: predefined reason the listed reports should contain schema: - type: string - enum: - - violentOrAbusive - - hatefulOrAbusive - - spamOrMisleading - - privacy - - rights - - serverRules - - thumbnails - - captions + $ref: '#/components/schemas/PredefinedAbuseReasons' - name: search in: query description: plain search that will match with video titles, reporter names and more @@ -1504,13 +1906,8 @@ paths: type: string - name: state in: query - description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)' schema: - type: integer - enum: - - 1 - - 2 - - 3 + $ref: '#/components/schemas/AbuseStateSet' - name: searchReporter in: query description: only list reports of a specific reporter @@ -1531,6 +1928,23 @@ paths: description: only list reports of a specific video channel schema: type: string + - name: videoIs + in: query + description: only list blacklisted or deleted videos + schema: + type: string + enum: + - 'deleted' + - 'blacklisted' + - name: filter + in: query + description: only list account, comment or video reports + schema: + type: string + enum: + - 'video' + - 'comment' + - 'account' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' @@ -1542,17 +1956,14 @@ paths: schema: type: array items: - $ref: '#/components/schemas/VideoAbuse' - '/videos/{id}/abuse': + $ref: '#/components/schemas/Abuse' + post: summary: Report an abuse security: - OAuth2: [] tags: - - Video Abuses - - Videos - parameters: - - $ref: '#/components/parameters/idOrUUID' + - Abuses requestBody: required: true content: @@ -1563,29 +1974,36 @@ paths: reason: description: Reason why the user reports this video type: string - minLength: 4 + minLength: 2 + maxLength: 3000 predefinedReasons: - description: Reason categories that help triage reports - type: array - items: - type: string - enum: - - violentOrAbusive - - hatefulOrAbusive - - spamOrMisleading - - privacy - - rights - - serverRules - - thumbnails - - captions - startAt: - type: integer - description: Timestamp in the video that marks the beginning of the report - minimum: 0 - endAt: - type: integer - description: Timestamp in the video that marks the ending of the report - minimum: 0 + $ref: '#/components/schemas/PredefinedAbuseReasons' + video: + type: object + properties: + id: + description: Video id to report + type: number + startAt: + type: integer + description: Timestamp in the video that marks the beginning of the report + minimum: 0 + endAt: + type: integer + description: Timestamp in the video that marks the ending of the report + minimum: 0 + comment: + type: object + properties: + id: + description: Comment id to report + type: number + account: + type: object + properties: + id: + description: Account id to report + type: number required: - reason responses: @@ -1593,7 +2011,7 @@ paths: description: successful operation '400': description: incorrect request parameters - '/videos/{id}/abuse/{abuseId}': + '/abuses/{abuseId}': put: summary: Update an abuse security: @@ -1601,9 +2019,8 @@ paths: - admin - moderator tags: - - Video Abuses + - Abuses parameters: - - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/abuseId' requestBody: content: @@ -1612,39 +2029,99 @@ paths: type: object properties: state: - $ref: '#/components/schemas/VideoAbuseStateSet' + $ref: '#/components/schemas/AbuseStateSet' moderationComment: type: string description: Update the report comment visible only to the moderation team + minLength: 2 + maxLength: 3000 responses: '204': description: successful operation '404': - description: video abuse not found + description: abuse not found delete: tags: - - Video Abuses + - Abuses summary: Delete an abuse security: - OAuth2: - - admin - - moderator + - admin + - moderator parameters: - - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/abuseId' responses: '204': description: successful operation '404': description: block not found + '/abuses/{abuseId}/messages': + get: + summary: List messages of an abuse + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AbuseMessage' + + post: + summary: Add message to an abuse + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + message: + description: Message to send + type: string + minLength: 2 + maxLength: 3000 + required: + - message + responses: + '200': + description: successful operation + '400': + description: incorrect request parameters + '/abuses/{abuseId}/messages/{abuseMessageId}': + delete: + summary: Delete an abuse message + security: + - OAuth2: [] + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + - $ref: '#/components/parameters/abuseMessageId' + responses: + '204': + description: successful operation '/videos/{id}/blacklist': post: summary: Block a video security: - OAuth2: - - admin - - moderator + - admin + - moderator tags: - Video Blocks parameters: @@ -1656,8 +2133,8 @@ paths: summary: Unblock a video by its id security: - OAuth2: - - admin - - moderator + - admin + - moderator tags: - Video Blocks parameters: @@ -1674,8 +2151,8 @@ paths: summary: List video blocks security: - OAuth2: - - admin - - moderator + - admin + - moderator parameters: - name: type in: query @@ -1738,6 +2215,9 @@ paths: /videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption + security: + - OAuth2: + - user tags: - Video Captions parameters: @@ -1763,6 +2243,9 @@ paths: description: video or language not found delete: summary: Delete a video caption + security: + - OAuth2: + - user tags: - Video Captions parameters: @@ -1861,6 +2344,7 @@ paths: parameters: - $ref: '#/components/parameters/channelHandle' - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -1878,6 +2362,112 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + '/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: + avatar: + $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: + multipart/form-data: + schema: + type: object + properties: + avatarfile: + description: The file to upload. + type: string + format: binary + encoding: + avatarfile: + contentType: image/png, image/jpeg + '/video-channels/{channelHandle}/avatar': + delete: + summary: Delete channel avatar + security: + - OAuth2: [] + tags: + - Video Channels + parameters: + - $ref: '#/components/parameters/channelHandle' + responses: + '204': + description: successful operation + + + '/video-channels/{channelHandle}/banner/pick': + post: + summary: Update channel banner + security: + - OAuth2: [] + tags: + - Video Channels + parameters: + - $ref: '#/components/parameters/channelHandle' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + banner: + $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 banner + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + bannerfile: + description: The file to upload. + type: string + format: binary + encoding: + bannerfile: + contentType: image/png, image/jpeg + '/video-channels/{channelHandle}/banner': + delete: + summary: Delete channel banner + security: + - OAuth2: [] + tags: + - Video Channels + parameters: + - $ref: '#/components/parameters/channelHandle' + responses: + '204': + description: successful operation /video-playlists/privacies: get: @@ -1942,7 +2532,7 @@ paths: id: type: integer uuid: - type: string + $ref: '#/components/schemas/UUIDv4' requestBody: content: multipart/form-data: @@ -1952,6 +2542,8 @@ paths: displayName: description: Video playlist display name type: string + minLength: 1 + maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string @@ -2005,6 +2597,8 @@ paths: displayName: description: Video playlist display name type: string + minLength: 1 + maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string @@ -2219,9 +2813,14 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/VideoChannel' + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoChannel' '/accounts/{name}/ratings': get: summary: List ratings of an account @@ -2393,6 +2992,7 @@ paths: schema: type: string - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -2715,13 +3315,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 @@ -2774,39 +3367,134 @@ 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: > + Arises when: + - videoId filter is mixed with a channel filter + '404': + description: video, video channel or account not found + '406': + description: accept header unsupported + '/feeds/videos.{format}': + get: + tags: + - Feeds + summary: List videos + 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 + - name: accountName + in: query + description: 'limit listing to a specific account' + schema: + type: string + - name: videoChannelId + in: query + description: 'limit listing to a specific video channel' + schema: + type: string + - name: videoChannelName + in: query + description: 'limit listing to a specific video channel' + schema: + type: string + - $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' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local + 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/VideoCommentsForXML' + $ref: '#/components/schemas/VideosForXML' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local application/atom+xml: schema: - $ref: '#/components/schemas/VideoCommentsForXML' + $ref: '#/components/schemas/VideosForXML' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local application/json: schema: type: object - '400': - x-summary: field inconsistencies - description: > - Arises when: - - videoId filter is mixed with a channel filter + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local '404': - description: video, video channel or account not found + description: video channel or account not found '406': description: accept header unsupported - '/feeds/videos.{format}': + '/feeds/subscriptions.{format}': get: 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) + - Account + summary: List videos of subscriptions tied to a token parameters: - name: format in: path @@ -2824,24 +3512,16 @@ paths: - json1 - name: accountId in: query - description: 'limit listing to a specific account' - schema: - type: string - - name: accountName - in: query - description: 'limit listing to a specific account' - schema: - type: string - - name: videoChannelId - in: query - description: 'limit listing to a specific video channel' + description: limit listing to a specific account schema: type: string - - name: videoChannelName + required: true + - name: token in: query - description: 'limit listing to a specific video channel' + description: private token allowing access schema: type: string + required: true - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/filter' @@ -2857,9 +3537,6 @@ paths: application/xml: schema: $ref: '#/components/schemas/VideosForXML' - examples: - nightly: - externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local application/rss+xml: schema: $ref: '#/components/schemas/VideosForXML' @@ -2872,8 +3549,6 @@ paths: application/json: schema: type: object - '404': - description: video channel or account not found '406': description: accept header unsupported /plugins: @@ -3144,6 +3819,13 @@ components: schema: type: string example: -createdAt + search: + name: search + in: query + required: false + description: Plain text search, applied to various parts of the model depending on endpoint + schema: + type: string searchTarget: name: searchTarget in: query @@ -3179,6 +3861,7 @@ components: - -views - -likes - -trending + - -hot videosSearchSort: name: sort in: query @@ -3220,6 +3903,20 @@ components: - -dislikes - -uuid - -createdAt + usersSearch: + name: search + in: query + required: false + description: Plain text search that will match with user usernames or emails + schema: + type: string + usersBlocked: + name: blocked + in: query + required: false + description: Filter results down to (un)banned users + schema: + type: boolean usersSort: name: sort in: query @@ -3255,7 +3952,7 @@ components: name: name in: path required: true - description: The name of the account + description: The username or handle of the account schema: type: string example: chocobozzz | chocobozzz@example.org @@ -3278,9 +3975,7 @@ components: - type: integer minimum: 0 example: 42 - - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + - $ref: '#/components/schemas/UUIDv4' playlistElementId: name: playlistElementId in: path @@ -3292,7 +3987,14 @@ components: name: abuseId in: path required: true - description: Video abuse id + description: Abuse id + schema: + type: integer + abuseMessageId: + name: abuseMessageId + in: path + required: true + description: Abuse message id schema: type: integer captionLanguage: @@ -3332,6 +4034,13 @@ components: description: The comment id schema: type: integer + isLive: + name: isLive + in: query + required: false + description: whether or not the video is a live + schema: + type: boolean categoryOneOf: name: categoryOneOf in: query @@ -3354,6 +4063,7 @@ components: oneOf: - type: string - type: array + maxItems: 5 items: type: string style: form @@ -3423,9 +4133,10 @@ components: in: query required: false description: > - Special filters (local for instance) which might require special rights: + 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 enum: @@ -3449,21 +4160,38 @@ components: schema: type: string example: peertube-plugin-auth-ldap + jobType: + name: jobType + in: query + required: false + description: job type + schema: + type: string + enum: + - activitypub-follow + - activitypub-http-broadcast + - activitypub-http-fetcher + - activitypub-http-unicast + - email + - video-transcoding + - video-file-import + - video-import + - videos-views + - activitypub-refresher + - video-redundancy + - video-live-ending securitySchemes: OAuth2: - description: > - In the header: *Authorization: Bearer * - - + description: | Authenticating via OAuth requires the following steps: + - Have an activated account + - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a + Bearer Token for that account at `/api/v1/users/token` + - Make authenticated requests, putting *Authorization: Bearer * + - Profit, depending on the role assigned to the account - - - Have an account with sufficient authorization levels - - - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a - Bearer Token - - - 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: @@ -3473,16 +4201,35 @@ components: moderator: Moderator scope user: User scope schemas: - VideoConstantNumber: + UUIDv4: + type: string + format: uuid + example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' + # the regex above limits the length; + # however, some tools might require explicit settings: + minLength: 36 + maxLength: 36 + + VideoConstantNumber-Category: properties: id: type: integer + description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) label: type: string - VideoConstantString: + VideoConstantNumber-Licence: + properties: + id: + type: integer + description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) + label: + type: string + VideoConstantString-Language: properties: id: type: string + description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)) label: type: string @@ -3543,6 +4290,13 @@ components: - 2 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)' example: 2 + UserAdminFlags: + type: integer + enum: + - 0 + - 1 + description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)' + example: 1 VideoStateConstant: properties: @@ -3556,20 +4310,20 @@ components: label: type: string - VideoAbuseStateSet: + AbuseStateSet: type: integer enum: - 1 - 2 - 3 - description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)' - VideoAbuseStateConstant: + description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)' + AbuseStateConstant: properties: id: - $ref: '#/components/schemas/VideoAbuseStateSet' + $ref: '#/components/schemas/AbuseStateSet' label: type: string - VideoAbusePredefinedReasons: + AbusePredefinedReasons: type: array items: type: string @@ -3588,7 +4342,7 @@ components: properties: id: type: integer - description: 'Video resolution (240, 360, 720 ...)' + description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)' example: 240 label: type: string @@ -3620,7 +4374,7 @@ components: avatar: nullable: true allOf: - - $ref: '#/components/schemas/Avatar' + - $ref: '#/components/schemas/ActorImage' VideoChannelSummary: properties: id: @@ -3638,7 +4392,7 @@ components: avatar: nullable: true allOf: - - $ref: '#/components/schemas/Avatar' + - $ref: '#/components/schemas/ActorImage' PlaylistElement: properties: position: @@ -3662,15 +4416,19 @@ components: description: 'Video file size in bytes' torrentUrl: type: string + description: Direct URL of the torrent file format: url torrentDownloadUrl: type: string + description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog) format: url fileUrl: type: string + description: Direct URL of the video format: url fileDownloadUrl: type: string + description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog) format: url fps: type: number @@ -3678,14 +4436,21 @@ components: type: string format: url VideoStreamingPlaylists: + allOf: + - type: object + properties: + id: + type: integer + type: + type: integer + enum: + - 1 + description: | + Playlist type: + - `1`: HLS + - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS' + VideoStreamingPlaylists-HLS: properties: - id: - type: integer - type: - type: integer - enum: - - 1 - description: 'Playlist type (HLS = `1`)' playlistUrl: type: string format: url @@ -3694,6 +4459,10 @@ components: format: url files: type: array + description: | + Video files associated to this playlist. + + The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.) items: $ref: '#/components/schemas/VideoFile' redundancies: @@ -3709,56 +4478,75 @@ components: id: type: integer uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' name: type: string + minLength: 3 + maxLength: 120 Video: properties: id: type: integer example: 8 uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' + isLive: + type: boolean createdAt: type: string format: date-time + example: 2017-10-01T10:52:46.396Z + description: time at which the video object was first drafted publishedAt: type: string format: date-time + example: 2018-10-01T10:52:46.396Z + description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution. updatedAt: type: string format: date-time + example: 2021-05-04T08:01:01.502Z + description: last time the video's metadata was modified originallyPublishedAt: type: string format: date-time + example: 2010-10-01T10:52:46.396Z + description: used to represent a date of first publication, prior to the practical publication date of `publishedAt` category: - $ref: '#/components/schemas/VideoConstantNumber' + $ref: '#/components/schemas/VideoConstantNumber-Category' licence: - $ref: '#/components/schemas/VideoConstantNumber' + $ref: '#/components/schemas/VideoConstantNumber-Licence' language: - $ref: '#/components/schemas/VideoConstantString' + $ref: '#/components/schemas/VideoConstantString-Language' privacy: $ref: '#/components/schemas/VideoPrivacyConstant' description: type: string + 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)**\r\n*A decentralized video hosting network, based on fr... + minLength: 3 + maxLength: 250 + description: | + truncated description of the video, written in Markdown. + Resolve `descriptionPath` to get the full description of maximum `10000` characters. duration: type: integer example: 1419 + description: duration of the video in seconds isLocal: type: boolean name: type: string example: What is PeerTube? + minLength: 3 + maxLength: 120 thumbnailPath: type: string example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg previewPath: type: string - example: /static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg + example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg embedPath: type: string example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee @@ -3805,23 +4593,27 @@ components: properties: descriptionPath: type: string + example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description + description: path at which to get the full description of maximum `10000` characters support: type: string description: A text tell the audience how to support the video creator example: Please support my work on ! <3 + minLength: 3 + maxLength: 1000 channel: $ref: '#/components/schemas/VideoChannel' account: $ref: '#/components/schemas/Account' tags: - type: array - items: - type: string example: [flowers, gardening] - files: type: array + minItems: 1 + maxItems: 5 items: - $ref: '#/components/schemas/VideoFile' + type: string + minLength: 2 + maxLength: 30 commentsEnabled: type: boolean downloadEnabled: @@ -3831,10 +4623,24 @@ components: items: type: string format: url + files: + type: array + items: + $ref: '#/components/schemas/VideoFile' + description: | + WebTorrent/raw video files. If WebTorrent is disabled on the server: + + - field will be empty + - video files will be found in `streamingPlaylists[].files` field streamingPlaylists: type: array items: $ref: '#/components/schemas/VideoStreamingPlaylists' + description: | + HLS playlists/manifest files. If HLS is disabled on the server: + + - field will be empty + - video files will be found in `files` field FileRedundancyInformation: properties: id: @@ -3870,9 +4676,7 @@ components: type: string format: url uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' redundancies: type: object properties: @@ -3923,7 +4727,7 @@ components: format: date-time video: $ref: '#/components/schemas/Video' - VideoAbuse: + Abuse: properties: id: type: integer @@ -3931,29 +4735,39 @@ components: reason: type: string example: The video is a spam + minLength: 2 + maxLength: 3000 predefinedReasons: - $ref: '#/components/schemas/VideoAbusePredefinedReasons' + $ref: '#/components/schemas/AbusePredefinedReasons' reporterAccount: $ref: '#/components/schemas/Account' state: - $ref: '#/components/schemas/VideoAbuseStateConstant' + $ref: '#/components/schemas/AbuseStateConstant' moderationComment: type: string example: Decided to ban the server since it spams us regularly + minLength: 2 + maxLength: 3000 video: - type: object - properties: - id: - type: integer - name: - type: string - uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/VideoInfo' + createdAt: + type: string + format: date-time + AbuseMessage: + properties: + id: + type: integer + message: + type: string + minLength: 2 + maxLength: 3000 + byModerator: + type: boolean createdAt: type: string format: date-time + account: + $ref: '#/components/schemas/AccountSummary' VideoBlacklist: properties: id: @@ -3968,12 +4782,14 @@ components: format: date-time name: type: string + minLength: 3 + maxLength: 120 uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' description: type: string + minLength: 3 + maxLength: 10000 duration: type: integer views: @@ -3988,8 +4804,12 @@ components: properties: displayName: type: string + minLength: 1 + maxLength: 120 description: type: string + minLength: 3 + maxLength: 1000 isLocal: type: boolean ownerAccount: @@ -3998,9 +4818,7 @@ components: id: type: integer uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' VideoPlaylist: properties: id: @@ -4013,12 +4831,14 @@ components: format: date-time description: type: string + minLength: 3 + maxLength: 1000 uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' displayName: type: string + minLength: 1 + maxLength: 120 isLocal: type: boolean videoLength: @@ -4042,6 +4862,8 @@ components: format: url text: type: string + minLength: 1 + maxLength: 10000 threadId: type: integer inReplyToCommentId: @@ -4071,10 +4893,10 @@ components: VideoCaption: properties: language: - $ref: '#/components/schemas/VideoConstantString' + $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string - Avatar: + ActorImage: properties: path: type: string @@ -4126,7 +4948,7 @@ components: type: string format: date-time avatar: - $ref: '#/components/schemas/Avatar' + $ref: '#/components/schemas/ActorImage' Account: allOf: - $ref: '#/components/schemas/Actor' @@ -4459,6 +5281,8 @@ components: type: boolean 1080p: type: boolean + 1440p: + type: boolean 2160p: type: boolean hls: @@ -4525,6 +5349,23 @@ components: updatedAt: type: string format: date-time + + PredefinedAbuseReasons: + description: Reason categories that help triage reports + type: array + maxItems: 8 + items: + type: string + enum: + - violentOrAbusive + - hatefulOrAbusive + - spamOrMisleading + - privacy + - rights + - serverRules + - thumbnails + - captions + Job: properties: id: @@ -4582,6 +5423,103 @@ 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: + 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 ! <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: @@ -4591,9 +5529,7 @@ components: type: integer example: 8 uuid: - type: string - format: uuid - example: 9c9de5e8-0a1e-484a-b099-e80766180a6d + $ref: '#/components/schemas/UUIDv4' CommentThreadResponse: properties: total: @@ -4632,6 +5568,9 @@ components: type: string format: email description: The user email + pluginAuth: + type: string + description: Auth plugin to use to authenticate the user theme: type: string description: Theme enabled by this user @@ -4662,11 +5601,11 @@ components: description: The user daily video quota videosCount: type: integer - videoAbusesCount: + abusesCount: type: integer - videoAbusesAcceptedCount: + abusesAcceptedCount: type: integer - videoAbusesCreatedCount: + abusesCreatedCount: type: integer videoCommentsCount: type: integer @@ -4709,8 +5648,13 @@ components: videoQuotaDaily: type: integer description: The user daily video quota + channelName: + type: string + description: The user default channel username role: $ref: '#/components/schemas/UserRole' + adminFlags: + $ref: '#/components/schemas/UserAdminFlags' required: - username - password @@ -4727,20 +5671,26 @@ components: type: string format: email description: The updated email of the user + emailVerified: + type: boolean + description: Set the email as verified videoQuota: type: integer description: The updated video quota of the user videoQuotaDaily: type: integer description: The updated daily video quota of the user + pluginAuth: + type: string + nullable: true + description: The auth plugin to use to authenticate the user + example: 'peertube-plugin-auth-saml2' role: $ref: '#/components/schemas/UserRole' + adminFlags: + $ref: '#/components/schemas/UserAdminFlags' required: - id - - email - - videoQuota - - videoQuotaDaily - - role UpdateMe: properties: password: @@ -4774,7 +5724,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 @@ -4784,8 +5738,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 @@ -4817,7 +5775,7 @@ components: properties: name: type: string - description: The name for the default channel + description: The username for the default channel pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' displayName: type: string @@ -4828,34 +5786,41 @@ components: - username - password - email - VideoChannelCreate: + + VideoChannelCommon: properties: - name: - type: string displayName: type: string + minLength: 1 + maxLength: 120 description: type: string + minLength: 3 + maxLength: 1000 support: type: string description: 'A text shown by default on all videos of this channel, to tell the audience how to support it' example: Please support my work on ! <3 + minLength: 3 + maxLength: 1000 + VideoChannelCreate: + allOf: + - $ref: '#/components/schemas/VideoChannelCommon' + - properties: + name: + type: string + minLength: 1 + maxLength: 120 required: - name - displayName VideoChannelUpdate: - properties: - displayName: - type: string - description: - type: string - support: - type: string - description: 'A text shown by default on all videos of this channel, to tell the audience how to support it' - example: Please support my work on ! <3 - bulkVideosSupportUpdate: - type: boolean - description: 'Update the support field for all videos of this channel' + allOf: + - $ref: '#/components/schemas/VideoChannelCommon' + - properties: + bulkVideosSupportUpdate: + type: boolean + description: 'Update the support field for all videos of this channel' MRSSPeerLink: type: object @@ -5070,7 +6035,7 @@ components: - `2` NEW_COMMENT_ON_MY_VIDEO - - `3` NEW_VIDEO_ABUSE_FOR_MODERATORS + - `3` NEW_ABUSE_FOR_MODERATORS - `4` BLACKLIST_ON_MY_VIDEO @@ -5254,9 +6219,33 @@ components: maxItems: 100 items: $ref: '#/components/schemas/Plugin' + + LiveVideoUpdate: + properties: + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + + LiveVideoResponse: + properties: + rtmpUrl: + type: string + streamKey: + type: string + description: RTMP stream key to use to stream into this live video + saveReplay: + type: boolean + permanentLive: + description: User can stream multiple times in a permanent live + type: boolean + + + callbacks: searchIndex: - '{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/api/v1/search/videos/': + 'https://search.example.org/api/v1/search/videos': post: summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget` responses: