X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=a71b571b87ea1cea8032e0903c5f93240ad5ef37;hb=30b40713f48f993fac6db8d4dbd712018bbde847;hp=6787679cfba64ee087cdba2a81bfc179f2ba5feb;hpb=d9cb5227803a285fde4d2ba9b1e1bac2dd64c231;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 6787679cf..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-rc.1 + version: 3.1.0 contact: name: PeerTube Community url: 'https://joinpeertube.org' @@ -12,21 +12,28 @@ 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. No official - SDK is currently provided, but the spec API is fully compatible with + 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) - which generates a client SDK in the language of your choice. + which generates a client SDK in the language of your choice - we generate some client SDKs automatically: + + - [Python](https://framagit.org/framasoft/peertube/clients/python) + - [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. # Errors @@ -40,14 +47,61 @@ 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: - name: Accounts description: > - Using some features of PeerTube require authentication, for which Accounts + Accounts encompass remote accounts discovered across the federation, + and correspond to the main Actor, along with video channels a user can create, which + are also Actors. + + When a comment is posted, it is done with your Account's Actor. + - name: Users + description: > + Using some features of PeerTube require authentication, for which User provide different levels of permission as well as associated user - information. Accounts also encompass remote accounts discovered across the federation. + information. Each user has a corresponding local Account for federation. + - name: My User + description: > + Operations related to your own User, when logged-in. + - name: My Subscriptions + 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 + to keep track of the interactions and overall important information that + concerns you. You MAY set per-notification type delivery preference, to + receive the info either by mail, by in-browser notification or both. - name: Config description: > Each server exposes public information regarding supported videos and @@ -63,37 +117,85 @@ tags: server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints. - - name: Video Abuses + externalDocs: + 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](#tag/Video-Mirroring). + externalDocs: + 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: 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_ from within the instance and beyond. + The search helps to find _videos_ or _channels_ from within the instance and beyond. Videos from other instances federated by the instance (that is, instances followed by the instance) can be found via keywords and other criteria of the advanced search. - - 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 creation, modification and video listing of a - user's channels. - - name: Video Blacklist - description: > - Operations dealing with blacklisting videos (removing them from view and - preventing interactions). - - name: Video Rates - description: > - Like/dislike a video. + + 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 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: @@ -101,27 +203,36 @@ x-tagGroups: - Users - My User - My Subscriptions + - My Notifications + - My History - name: Videos tags: - Video - - Video Caption + - Video Upload + - Video Captions - Video Channels - Video Comments - - Video Following - Video Rates - Video Playlists - Video Ownership Change + - Video Mirroring + - Live Videos + - Feeds - name: Search tags: - Search - name: Moderation tags: - - Video Abuses - - Video Blacklist + - Abuses + - Video Blocks + - Account Blocks + - Server Blocks - name: Instance Configuration tags: - Config - Instance Follows + - Instance Redundancy + - Plugins - name: Jobs tags: - Job @@ -140,6 +251,8 @@ paths: application/json: schema: $ref: '#/components/schemas/Account' + '404': + description: account not found '/accounts/{name}/videos': get: tags: @@ -149,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' @@ -177,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' @@ -249,7 +363,7 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -263,17 +377,23 @@ paths: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation + '400': + x-summary: field inconsistencies + description: > + Arises when: + - the emailer is disabled and the instance is open to registrations + - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled delete: summary: Delete instance runtime configuration tags: - Config security: - OAuth2: - - admin + - admin responses: '200': description: successful operation @@ -282,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' @@ -307,14 +429,21 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/Job' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/Job' '/server/following/{host}': delete: security: - OAuth2: - - admin + - admin tags: - Instance Follows summary: Unfollow a server @@ -325,6 +454,7 @@ paths: description: 'The host to unfollow ' schema: type: string + format: hostname responses: '201': description: successful operation @@ -350,8 +480,25 @@ paths: get: tags: - Instance Follows - summary: List instance followings + summary: List instances followed by the server parameters: + - name: state + in: query + schema: + type: string + enum: + - pending + - accepted + - name: actorType + in: query + schema: + type: string + enum: + - Person + - Application + - Group + - Service + - Organization - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' @@ -367,33 +514,60 @@ paths: post: security: - OAuth2: - - admin + - admin tags: - Instance Follows summary: Follow a server responses: '204': description: successful operation + '500': + description: cannot follow a non-HTTPS server requestBody: content: application/json: schema: - $ref: '#/components/schemas/Follow' + type: object + properties: + hosts: + type: array + items: + type: string + format: hostname + uniqueItems: true /users: post: summary: Create a user security: - OAuth2: - - admin + - admin tags: - Users responses: '200': - description: successful operation + description: user created content: application/json: schema: $ref: '#/components/schemas/AddUserResponse' + links: + # GET /users/{id} + GetUserId: + operationId: getUserId + parameters: + id: '$response.body#/user/id' + # PUT /users/{id} + PutUserId: + operationId: putUserId + parameters: + id: '$response.body#/user/id' + # DELETE /users/{id} + DelUserId: + operationId: delUserId + parameters: + id: '$response.body#/user/id' + '403': + description: insufficient authority to create an admin or moderator requestBody: content: application/json: @@ -404,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' @@ -421,15 +598,16 @@ paths: items: $ref: '#/components/schemas/User' '/users/{id}': + parameters: + - $ref: '#/components/parameters/id' delete: summary: Delete a user security: - OAuth2: - - admin + - admin tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: delUserId responses: '204': description: successful operation @@ -439,8 +617,7 @@ paths: - OAuth2: [] tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: getUserId responses: '200': description: successful operation @@ -454,8 +631,7 @@ paths: - OAuth2: [] tags: - Users - parameters: - - $ref: '#/components/parameters/id' + operationId: putUserId responses: '204': description: successful operation @@ -517,7 +693,7 @@ paths: summary: Get video imports of my user security: - OAuth2: - - user + - user tags: - Videos - My User @@ -546,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 @@ -594,7 +777,7 @@ paths: summary: Get my user subscriptions security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -605,12 +788,28 @@ paths: '200': description: successful operation post: + tags: + - My Subscriptions summary: Add subscription to my user security: - OAuth2: - - user - tags: - - My Subscriptions + - user + requestBody: + content: + application/json: + schema: + type: object + properties: + uri: + type: string + format: uri + description: uri of the video channels to subscribe to + required: + - uri + examples: + default: + value: + uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr responses: '200': description: successful operation @@ -619,7 +818,7 @@ paths: summary: Get if subscriptions exist for my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -642,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' @@ -664,7 +864,7 @@ paths: summary: Get subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -680,7 +880,7 @@ paths: summary: Delete subscription of my user security: - OAuth2: - - user + - user tags: - My Subscriptions parameters: @@ -688,6 +888,140 @@ paths: responses: '200': description: successful operation + /users/me/notifications: + get: + summary: List my notifications + security: + - OAuth2: [] + tags: + - My Notifications + parameters: + - name: unread + in: query + description: only list unread notifications + schema: + type: boolean + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/NotificationListResponse' + /users/me/notifications/read: + post: + summary: Mark notifications as read by their id + security: + - OAuth2: [] + tags: + - My Notifications + requestBody: + content: + application/json: + schema: + type: object + properties: + ids: + type: array + description: ids of the notifications to mark as read + items: + type: integer + required: + - ids + responses: + '204': + description: successful operation + /users/me/notifications/read-all: + post: + summary: Mark all my notification as read + security: + - OAuth2: [] + tags: + - My Notifications + responses: + '204': + description: successful operation + /users/me/notification-settings: + put: + summary: Update my notification settings + security: + - OAuth2: [] + tags: + - My Notifications + requestBody: + content: + application/json: + schema: + type: object + properties: + newVideoFromSubscription: + $ref: '#/components/schemas/NotificationSettingValue' + newCommentOnMyVideo: + $ref: '#/components/schemas/NotificationSettingValue' + abuseAsModerator: + $ref: '#/components/schemas/NotificationSettingValue' + videoAutoBlacklistAsModerator: + $ref: '#/components/schemas/NotificationSettingValue' + blacklistOnMyVideo: + $ref: '#/components/schemas/NotificationSettingValue' + myVideoPublished: + $ref: '#/components/schemas/NotificationSettingValue' + myVideoImportFinished: + $ref: '#/components/schemas/NotificationSettingValue' + newFollow: + $ref: '#/components/schemas/NotificationSettingValue' + newUserRegistration: + $ref: '#/components/schemas/NotificationSettingValue' + commentMention: + $ref: '#/components/schemas/NotificationSettingValue' + newInstanceFollower: + $ref: '#/components/schemas/NotificationSettingValue' + autoInstanceFollowing: + $ref: '#/components/schemas/NotificationSettingValue' + 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 @@ -701,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: @@ -715,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 @@ -737,6 +1093,10 @@ paths: responses: '204': description: successful operation + '403': + description: cannot terminate an ownership change of another user + '404': + description: video owneship change not found '/videos/ownership/{id}/refuse': post: summary: Refuse ownership change request @@ -749,6 +1109,10 @@ paths: responses: '204': description: successful operation + '403': + description: cannot terminate an ownership change of another user + '404': + description: video owneship change not found '/videos/{id}/give-ownership': post: summary: Request ownership change @@ -773,7 +1137,9 @@ paths: '204': description: successful operation '400': - description: 'Changing video ownership to a remote account is not supported yet' + description: changing video ownership to a remote account is not supported yet + '404': + description: video not found /videos: get: summary: List videos @@ -781,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' @@ -812,6 +1179,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/categories /videos/licences: get: summary: List available video licences @@ -826,6 +1196,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/licences /videos/languages: get: summary: List available video languages @@ -840,6 +1213,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/languages /videos/privacies: get: summary: List available video privacies @@ -854,6 +1230,9 @@ paths: type: array items: type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/videos/privacies '/videos/{id}': put: summary: Update a video @@ -882,10 +1261,12 @@ paths: format: binary 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 @@ -898,14 +1279,17 @@ paths: description: Whether or not we wait transcoding before publish the video type: string support: - description: Text describing how to support the video uploader + 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 @@ -917,7 +1301,7 @@ paths: maxLength: 30 commentsEnabled: description: Enable or disable comments for this video - type: string + type: boolean originallyPublishedAt: description: Date when the content was originally published type: string @@ -998,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 @@ -1009,81 +1395,29 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + description: invalid file field, schedule date or parameter '403': - description: 'The user video quota is exceeded with this video.' + description: video didn't pass upload filter '408': - description: 'Upload has timed out' + 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: number - 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: string - licence: - description: Video licence - type: string - 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: string - support: - description: Text describing how to support the video uploader - type: string - nsfw: - description: Whether or not this video contains sensitive content - type: string - 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 - items: - type: string - minLength: 2 - maxLength: 30 - commentsEnabled: - description: Enable or disable comments for this video - type: string - 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 @@ -1094,8 +1428,7 @@ paths: x-code-samples: - lang: Shell source: | - ## DEPENDENCIES: httpie, jq - # pip install httpie + ## DEPENDENCIES: jq USERNAME="" PASSWORD="" FILE_PATH="" @@ -1104,34 +1437,190 @@ 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" - /videos/imports: + 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: Import a video - description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) + 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: successful operation + 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 + description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) + security: + - OAuth2: [] + tags: + - Video + - Video Upload requestBody: content: multipart/form-data: @@ -1150,7 +1639,7 @@ paths: type: string channelId: description: Channel id that will contain this video - type: number + type: integer thumbnailfile: description: Video thumbnail file type: string @@ -1163,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 @@ -1175,16 +1666,19 @@ paths: type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video - type: string + type: boolean support: - description: Text describing how to support the video uploader + 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 @@ -1196,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: @@ -1209,131 +1706,169 @@ paths: contentType: image/jpeg previewfile: contentType: image/jpeg - /videos/abuse: - get: - summary: List video abuses - security: - - OAuth2: - - admin - - moderator - tags: - - Video Abuses - parameters: - - $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/VideoAbuse' - '/videos/{id}/abuse': + $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: Report an abuse + summary: Create a live security: - OAuth2: [] tags: - - Video Abuses - - Videos - parameters: - - $ref: '#/components/parameters/idOrUUID' - requestBody: - content: - application/json: - schema: - type: object - properties: - reason: - description: Reason why the user reports this video - type: string - responses: - '204': - description: successful operation - '/videos/{id}/abuse/{abuseId}': - put: - summary: Update an abuse - security: - - OAuth2: - - admin - - moderator - tags: - - Video Abuses + - Live Videos + - Video responses: - '204': + '200': description: successful operation - parameters: - - $ref: '#/components/parameters/idOrUUID' - - $ref: '#/components/parameters/abuseId' + 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: - application/json: + multipart/form-data: schema: type: object properties: - state: - $ref: '#/components/schemas/VideoAbuseStateSet' - moderationComment: + 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 - description: 'Update the comment of the video abuse for other admin/moderators' - delete: - summary: Delete an abuse - security: - - OAuth2: - - admin - - moderator - tags: - - Video Abuses - responses: - '204': - description: successful operation - parameters: - - $ref: '#/components/parameters/idOrUUID' - - $ref: '#/components/parameters/abuseId' + 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/{id}/blacklist': - post: - summary: Blacklist a video + /videos/live/{id}: + get: + summary: Get information about a live security: - - OAuth2: - - admin - - moderator + - OAuth2: [] tags: - - Video Blacklist + - Live Videos + - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: - '204': + '200': description: successful operation - delete: - summary: Delete an entry of the blacklist of a video by its id + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoResponse' + put: + summary: Update information about a live security: - - OAuth2: - - admin - - moderator + - OAuth2: [] tags: - - Video Blacklist + - Live Videos + - Video parameters: - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoUpdate' responses: '204': - description: successful operation - /videos/blacklist: + description: Successful operation + '400': + 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 blacklisted videos + summary: List my abuses security: - - OAuth2: - - admin - - moderator + - OAuth2: [] tags: - - Video Blacklist + - 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/blacklistsSort' + - $ref: '#/components/parameters/abusesSort' responses: '200': description: successful operation @@ -1342,24 +1877,337 @@ paths: schema: type: array items: - $ref: '#/components/schemas/VideoBlacklist' - /videos/{id}/captions: + $ref: '#/components/schemas/Abuse' + + /abuses: get: - summary: List captions of a video + summary: List abuses + security: + - OAuth2: + - admin + - moderator tags: - - Video Caption + - Abuses parameters: - - $ref: '#/components/parameters/idOrUUID' - responses: - '200': - description: successful operation - content: - application/json: + - name: id + in: query + description: only list the report with this id + schema: + type: integer + - name: predefinedReason + in: query + description: predefined reason the listed reports should contain + schema: + $ref: '#/components/schemas/PredefinedAbuseReasons' + - name: search + in: query + description: plain search that will match with video titles, reporter names and more + schema: + type: string + - name: state + in: query + schema: + $ref: '#/components/schemas/AbuseStateSet' + - name: searchReporter + in: query + description: only list reports of a specific reporter + schema: + type: string + - name: searchReportee + description: only list reports of a specific reportee + in: query + schema: + type: string + - name: searchVideo + in: query + description: only list reports of a specific video + schema: + type: string + - name: searchVideoChannel + in: query + 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' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Abuse' + + post: + summary: Report an abuse + security: + - OAuth2: [] + tags: + - Abuses + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + reason: + description: Reason why the user reports this video + type: string + minLength: 2 + maxLength: 3000 + predefinedReasons: + $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: + '204': + description: successful operation + '400': + description: incorrect request parameters + '/abuses/{abuseId}': + put: + summary: Update an abuse + security: + - OAuth2: + - admin + - moderator + tags: + - Abuses + parameters: + - $ref: '#/components/parameters/abuseId' + requestBody: + content: + application/json: + schema: + type: object + properties: + state: + $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: abuse not found + delete: + tags: + - Abuses + summary: Delete an abuse + security: + - OAuth2: + - admin + - moderator + parameters: + - $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 + tags: + - Video Blocks + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '204': + description: successful operation + delete: + summary: Unblock a video by its id + security: + - OAuth2: + - admin + - moderator + tags: + - Video Blocks + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '204': + description: successful operation + '404': + description: block not found + /videos/blacklist: + get: + tags: + - Video Blocks + summary: List video blocks + security: + - OAuth2: + - admin + - moderator + parameters: + - name: type + in: query + description: > + list only blocks that match this type: + + - `1`: manual block + + - `2`: automatic block that needs review + schema: + type: integer + enum: + - 1 + - 2 + - name: search + in: query + description: plain search that will match with video titles, and more + schema: + type: string + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/blacklistsSort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoBlacklist' + /videos/{id}/captions: + get: + summary: List captions of a video + tags: + - Video Captions + 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: @@ -1367,8 +2215,11 @@ paths: /videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption + security: + - OAuth2: + - user tags: - - Video Caption + - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/captionLanguage' @@ -1388,16 +2239,23 @@ paths: responses: '204': description: successful operation + '404': + description: video or language not found delete: summary: Delete a video caption + security: + - OAuth2: + - user tags: - - Video Caption + - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/captionLanguage' responses: '204': description: successful operation + '404': + description: video or language or caption for that language not found /video-channels: get: summary: List video channels @@ -1413,9 +2271,15 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/VideoChannel' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoChannel' post: summary: Create a video channel security: @@ -1480,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' @@ -1497,31 +2362,118 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' - - /video-playlists/privacies: - get: - summary: List available playlist privacies + '/video-channels/{channelHandle}/avatar/pick': + post: + summary: Update channel avatar + security: + - OAuth2: [] tags: - - Video Playlists + - Video Channels + parameters: + - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: - type: array - items: - type: string - - /video-playlists: - get: - summary: List video playlists - tags: - - Video Playlists - parameters: - - $ref: '#/components/parameters/start' - - $ref: '#/components/parameters/count' - - $ref: '#/components/parameters/sort' + 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: + summary: List available playlist privacies + tags: + - Video Playlists responses: '200': description: successful operation @@ -1530,7 +2482,35 @@ paths: schema: type: array items: - $ref: '#/components/schemas/VideoPlaylist' + type: string + examples: + nightly: + externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies + + /video-playlists: + get: + summary: List video playlists + tags: + - Video Playlists + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoPlaylist' post: summary: Create a video playlist description: 'If the video playlist is set as public, the videoChannelId is mandatory.' @@ -1550,9 +2530,9 @@ paths: type: object properties: id: - type: number + type: integer uuid: - type: string + $ref: '#/components/schemas/UUIDv4' requestBody: content: multipart/form-data: @@ -1562,6 +2542,8 @@ paths: displayName: description: Video playlist display name type: string + minLength: 1 + maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string @@ -1573,9 +2555,12 @@ paths: type: string videoChannelId: description: Video channel in which the playlist will be published - type: number + type: integer required: - displayName + encoding: + thumbnailfile: + contentType: image/jpeg /video-playlists/{id}: get: @@ -1612,6 +2597,8 @@ paths: displayName: description: Video playlist display name type: string + minLength: 1 + maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string @@ -1623,7 +2610,10 @@ paths: type: string videoChannelId: description: Video channel in which the playlist will be published - type: number + type: integer + encoding: + thumbnailfile: + contentType: image/jpeg delete: summary: Delete a video playlist security: @@ -1672,7 +2662,7 @@ paths: type: object properties: id: - type: number + type: integer requestBody: content: application/json: @@ -1680,13 +2670,13 @@ paths: type: object properties: videoId: - type: number + type: integer description: 'Video to add in the playlist' startTimestamp: - type: number + type: integer description: 'Start the video at this specific timestamp (in seconds)' stopTimestamp: - type: number + type: integer description: 'Stop the video at this specific timestamp (in seconds)' required: - videoId @@ -1710,14 +2700,17 @@ paths: type: object properties: startPosition: - type: number - description: 'Start position of the element to reorder (starts from 1)' + type: integer + description: 'Start position of the element to reorder' + minimum: 1 insertAfterPosition: - type: number - description: 'New position for the block to reorder (starts from 0, to add the block before the first element)' + type: integer + description: 'New position for the block to reorder, to add the block before the first element' + minimum: 0 reorderLength: - type: number - description: 'How many element from startPosition to reorder (minimum length is 1)' + type: integer + description: 'How many element from `startPosition` to reorder' + minimum: 1 required: - startPosition - insertAfterPosition @@ -1742,10 +2735,10 @@ paths: type: object properties: startTimestamp: - type: number + type: integer description: 'Start the video at this specific timestamp (in seconds)' stopTimestamp: - type: number + type: integer description: 'Stop the video at this specific timestamp (in seconds)' delete: summary: 'Delete an element from a playlist' @@ -1775,7 +2768,7 @@ paths: schema: type: array items: - type: number + type: integer responses: '200': description: successful operation @@ -1790,13 +2783,13 @@ paths: type: object properties: playlistElementId: - type: number + type: integer playlistId: - type: number + type: integer startTimestamp: - type: number + type: integer stopTimestamp: - type: number + type: integer '/accounts/{name}/video-channels': get: @@ -1806,15 +2799,28 @@ paths: - Accounts parameters: - $ref: '#/components/parameters/name' + - name: withStats + in: query + description: include view statistics for the last 30 days (only if authentified as the account user) + schema: + type: boolean + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' responses: '200': description: successful operation 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 @@ -1877,6 +2883,8 @@ paths: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' + '404': + description: video does not exist requestBody: content: application/json: @@ -1921,6 +2929,8 @@ paths: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' + '404': + description: thread or video does not exist requestBody: content: application/json: @@ -1945,6 +2955,12 @@ paths: responses: '204': description: successful operation + '403': + description: cannot remove comment of another user + '404': + description: comment or video does not exist + '409': + description: comment is already deleted '/videos/{id}/rate': put: summary: Like/dislike a video @@ -1957,13 +2973,26 @@ paths: responses: '204': description: successful operation + '404': + description: video does not exist /search/videos: get: tags: - Search summary: Search videos parameters: + - name: search + in: query + required: true + allowEmptyValue: false + description: > + String to search. If the user can make a remote URI search, and the string is an URI then the + PeerTube instance will fetch the remote object and add it to its database. Then, + you can use the REST API to fetch the complete video information and interact with it. + schema: + type: string - $ref: '#/components/parameters/categoryOneOf' + - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' @@ -1973,165 +3002,1001 @@ paths: - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/videosSearchSort' + - name: startDate + in: query + description: Get videos that are published after this date + schema: + type: string + format: date-time + - name: endDate + in: query + description: Get videos that are published before this date + schema: + type: string + format: date-time + - name: originallyPublishedStartDate + in: query + description: Get videos that are originally published after this date + schema: + type: string + format: date-time + - name: originallyPublishedEndDate + in: query + description: Get videos that are originally published before this date + schema: + type: string + format: date-time + - name: durationMin + in: query + description: Get videos that have this minimum duration + schema: + type: integer + - name: durationMax + in: query + description: Get videos that have this maximum duration + schema: + type: integer + callbacks: + 'searchTarget === search-index': + $ref: '#/components/callbacks/searchIndex' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoListResponse' + '500': + description: search index unavailable + /search/video-channels: + get: + tags: + - Search + summary: Search channels + parameters: - name: search in: query required: true - description: String to search + description: > + String to search. If the user can make a remote URI search, and the string is an URI then the + PeerTube instance will fetch the remote object and add it to its database. Then, + you can use the REST API to fetch the complete channel information and interact with it. schema: type: string + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/searchTarget' + - $ref: '#/components/parameters/sort' + callbacks: + 'searchTarget === search-index': + $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation content: application/json: schema: - $ref: '#/components/schemas/VideoListResponse' -servers: - - url: 'https://peertube.cpy.re/api/v1' - description: Live Test Server (live data - stable version) - - url: 'https://peertube2.cpy.re/api/v1' - description: Live Test Server (live data - latest nighlty version) - - url: 'https://peertube3.cpy.re/api/v1' - description: Live Test Server (live data - latest RC version) -components: - parameters: - start: - name: start - in: query - required: false - description: Offset - schema: - type: number - count: - name: count - in: query - required: false - description: "Number of items (max: 100)" - schema: - type: number - sort: - name: sort - in: query - required: false - description: Sort column (-createdAt for example) - schema: - type: string - videosSort: - name: sort - in: query - required: false - description: Sort videos by criteria - schema: - type: string - enum: - - -name - - -duration - - -createdAt - - -publishedAt - - -views - - -likes - - -trending - videosSearchSort: - name: sort - in: query - required: false - description: Sort videos by criteria - schema: - type: string - enum: - - -name - - -duration - - -createdAt - - -publishedAt - - -views - - -likes - - -match - commentsSort: - name: sort - in: query - required: false - description: Sort comments by criteria - schema: - type: string - enum: - - -createdAt - - -totalReplies - blacklistsSort: - name: sort - in: query - required: false - description: Sort blacklists by criteria - schema: - type: string - enum: - - -id - - -name - - -duration - - -views - - -likes - - -dislikes - - -uuid - - -createdAt - usersSort: - name: sort - in: query - required: false - description: Sort users by criteria - schema: - type: string - enum: - - -id - - -username - - -createdAt - abusesSort: - name: sort - in: query - required: false - description: Sort abuses by criteria - schema: - type: string - enum: - - -id - - -createdAt - - -state - name: - name: name - in: path + type: array + items: + $ref: '#/components/schemas/VideoChannel' + '500': + description: search index unavailable + /blocklist/accounts: + get: + tags: + - Account Blocks + summary: List account blocks + security: + - OAuth2: + - admin + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + post: + tags: + - Account Blocks + summary: Block an account + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + accountName: + type: string + example: chocobozzz@example.org + description: account to block, in the form `username@domain` + required: + - accountName + responses: + '200': + description: successful operation + '409': + description: self-blocking forbidden + '/blocklist/accounts/{accountName}': + delete: + tags: + - Account Blocks + summary: Unblock an account by its handle + security: + - OAuth2: + - admin + parameters: + - name: accountName + in: path + required: true + description: account to unblock, in the form `username@domain` + schema: + type: string + responses: + '201': + description: successful operation + '404': + description: account or account block does not exist + /blocklist/servers: + get: + tags: + - Server Blocks + summary: List server blocks + security: + - OAuth2: + - admin + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + post: + tags: + - Server Blocks + summary: Block a server + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + host: + type: string + format: hostname + description: server domain to block + required: + - host + responses: + '200': + description: successful operation + '409': + description: self-blocking forbidden + '/blocklist/servers/{host}': + delete: + tags: + - Server Blocks + summary: Unblock a server by its domain + security: + - OAuth2: + - admin + parameters: + - name: host + in: path + required: true + description: server domain to unblock + schema: + type: string + format: hostname + responses: + '201': + description: successful operation + '404': + description: account block does not exist + /redundancy/{host}: + put: + tags: + - Instance Redundancy + summary: Update a server redundancy policy + security: + - OAuth2: + - admin + parameters: + - name: host + in: path + required: true + description: server domain to mirror + schema: + type: string + format: hostname + requestBody: + content: + application/json: + schema: + type: object + properties: + redundancyAllowed: + type: boolean + description: allow mirroring of the host's local videos + required: + - redundancyAllowed + responses: + '204': + description: successful operation + '404': + description: server is not already known + /redundancy/videos: + get: + tags: + - Video Mirroring + summary: List videos being mirrored + security: + - OAuth2: + - admin + parameters: + - name: target + in: query + required: true + description: direction of the mirror + schema: + type: string + enum: + - my-videos + - remote-videos + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/videoRedundanciesSort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/VideoRedundancy' + post: + tags: + - Video Mirroring + summary: Mirror a video + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + videoId: + type: integer + required: + - videoId + responses: + '204': + description: successful operation + '400': + description: cannot mirror a local video + '404': + description: video does not exist + '409': + description: video is already mirrored + /redundancy/videos/{redundancyId}: + delete: + tags: + - Video Mirroring + summary: Delete a mirror done on a video + security: + - OAuth2: + - admin + parameters: + - name: redundancyId + in: path + required: true + description: id of an existing redundancy on a video + schema: + type: string + responses: + '204': + description: successful operation + '404': + description: video redundancy not found + '/feeds/video-comments.{format}': + get: + tags: + - Feeds + summary: List comments on 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: videoId + in: query + description: 'limit listing to a specific video' + schema: + type: string + - 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 + 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/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/VideosForXML' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local + application/atom+xml: + schema: + $ref: '#/components/schemas/VideosForXML' + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local + application/json: + schema: + type: object + examples: + nightly: + externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local + '404': + description: video channel or account not found + '406': + description: accept header unsupported + '/feeds/subscriptions.{format}': + get: + tags: + - Feeds + - Account + summary: List videos of subscriptions tied to a token + parameters: + - name: format + in: path + required: true + description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))' + schema: + type: string + enum: + - xml + - rss + - rss2 + - atom + - atom1 + - json + - json1 + - name: accountId + in: query + description: limit listing to a specific account + schema: + type: string + required: true + - name: token + in: query + description: private token allowing access + schema: + type: string + required: true + - $ref: '#/components/parameters/sort' + - $ref: '#/components/parameters/nsfw' + - $ref: '#/components/parameters/filter' + responses: + '204': + description: successful operation + headers: + Cache-Control: + schema: + type: string + default: 'max-age=900' # 15 min cache + content: + application/xml: + schema: + $ref: '#/components/schemas/VideosForXML' + application/rss+xml: + schema: + $ref: '#/components/schemas/VideosForXML' + text/xml: + schema: + $ref: '#/components/schemas/VideosForXML' + application/atom+xml: + schema: + $ref: '#/components/schemas/VideosForXML' + application/json: + schema: + type: object + '406': + description: accept header unsupported + /plugins: + get: + tags: + - Plugins + summary: List plugins + security: + - OAuth2: + - admin + parameters: + - name: pluginType + in: query + schema: + type: integer + - name: uninstalled + in: query + schema: + type: boolean + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/PluginResponse' + /plugins/available: + get: + tags: + - Plugins + summary: List available plugins + security: + - OAuth2: + - admin + parameters: + - name: search + in: query + schema: + type: string + - name: pluginType + in: query + schema: + type: integer + - name: currentPeerTubeEngine + in: query + schema: + type: string + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/PluginResponse' + '503': + description: plugin index unavailable + /plugins/install: + post: + tags: + - Plugins + summary: Install a plugin + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + oneOf: + - type: object + properties: + npmName: + type: string + example: peertube-plugin-auth-ldap + required: + - npmName + additionalProperties: false + - type: object + properties: + path: + type: string + required: + - path + additionalProperties: false + responses: + '204': + description: successful operation + '400': + description: should have either `npmName` or `path` set + /plugins/update: + post: + tags: + - Plugins + summary: Update a plugin + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + oneOf: + - type: object + properties: + npmName: + type: string + example: peertube-plugin-auth-ldap + required: + - npmName + additionalProperties: false + - type: object + properties: + path: + type: string + required: + - path + additionalProperties: false + responses: + '204': + description: successful operation + '400': + description: should have either `npmName` or `path` set + '404': + description: existing plugin not found + /plugins/uninstall: + post: + tags: + - Plugins + summary: Uninstall a plugin + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + npmName: + type: string + description: name of the plugin/theme in its package.json + example: peertube-plugin-auth-ldap + required: + - npmName + responses: + '204': + description: successful operation + '404': + description: existing plugin not found + /plugins/{npmName}: + get: + tags: + - Plugins + summary: Get a plugin + security: + - OAuth2: + - admin + parameters: + - $ref: '#/components/parameters/npmName' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + '404': + description: plugin not found + /plugins/{npmName}/settings: + put: + tags: + - Plugins + summary: Set a plugin's settings + security: + - OAuth2: + - admin + parameters: + - $ref: '#/components/parameters/npmName' + requestBody: + content: + application/json: + schema: + type: object + properties: + settings: + type: object + additionalProperties: true + responses: + '204': + description: successful operation + '404': + description: plugin not found + /plugins/{npmName}/public-settings: + get: + tags: + - Plugins + summary: Get a plugin's public settings + parameters: + - $ref: '#/components/parameters/npmName' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + additionalProperties: true + '404': + description: plugin not found + /plugins/{npmName}/registered-settings: + get: + tags: + - Plugins + summary: Get a plugin's registered settings + security: + - OAuth2: + - admin + parameters: + - $ref: '#/components/parameters/npmName' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + additionalProperties: true + '404': + description: plugin not found +servers: + - url: 'https://peertube2.cpy.re/api/v1' + description: Live Test Server (live data - latest nightly version) + - url: 'https://peertube3.cpy.re/api/v1' + description: Live Test Server (live data - latest RC version) + - url: 'https://peertube.cpy.re/api/v1' + description: Live Test Server (live data - stable version) +components: + parameters: + start: + name: start + in: query + required: false + description: Offset used to paginate results + schema: + type: integer + minimum: 0 + count: + name: count + in: query + required: false + description: "Number of items to return" + schema: + type: integer + default: 15 + maximum: 100 + minimum: 1 + sort: + name: sort + in: query + required: false + description: Sort column + 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 + required: false + description: > + If the administrator enabled search index support, you can override the default search target. + + + **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. + It means the instance may not yet know the objects you fetched. If you want to load video/channel information: + * If the current user has the ability to make a remote URI search (this information is available in the config endpoint), + then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. + After that, you can use the classic REST API endpoints to fetch the complete object or interact with it + * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch + the data from the origin instance API + schema: + type: string + enum: + - 'local' + - 'search-index' + videosSort: + name: sort + in: query + required: false + description: Sort videos by criteria + schema: + type: string + enum: + - name + - -duration + - -createdAt + - -publishedAt + - -views + - -likes + - -trending + - -hot + videosSearchSort: + name: sort + in: query + required: false + description: Sort videos by criteria + schema: + type: string + enum: + - name + - -duration + - -createdAt + - -publishedAt + - -views + - -likes + - -match + commentsSort: + name: sort + in: query + required: false + description: Sort comments by criteria + schema: + type: string + enum: + - -createdAt + - -totalReplies + blacklistsSort: + name: sort + in: query + required: false + description: Sort blacklists by criteria + schema: + type: string + enum: + - -id + - name + - -duration + - -views + - -likes + - -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 + required: false + description: Sort users by criteria + schema: + type: string + enum: + - -id + - -username + - -createdAt + abusesSort: + name: sort + in: query + required: false + description: Sort abuses by criteria + schema: + type: string + enum: + - -id + - -createdAt + - -state + videoRedundanciesSort: + name: sort + in: query + required: false + description: Sort abuses by criteria + schema: + type: string + enum: + - name + name: + name: name + in: path required: true - description: >- - The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for - example) + description: The username or handle of the account schema: type: string + example: chocobozzz | chocobozzz@example.org id: name: id in: path required: true description: The user id schema: - type: number + type: integer + minimum: 0 + example: 42 idOrUUID: name: id in: path required: true description: The object id or uuid schema: - type: string + oneOf: + - type: integer + minimum: 0 + example: 42 + - $ref: '#/components/schemas/UUIDv4' playlistElementId: name: playlistElementId in: path required: true description: Playlist element id schema: - type: number + type: integer abuseId: 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: number + type: integer captionLanguage: name: captionLanguage in: path @@ -2143,41 +4008,50 @@ components: name: channelHandle in: path required: true - description: "The video channel handle (example: 'my_username@example.com' or 'my_username')" + description: The video channel handle schema: type: string + example: my_username | my_username@example.com subscriptionHandle: name: subscriptionHandle in: path required: true - description: "The subscription handle (example: 'my_username@example.com' or 'my_username')" + description: The subscription handle schema: type: string + example: my_username | my_username@example.com threadId: name: threadId in: path required: true description: The thread id (root comment id) schema: - type: number + type: integer commentId: name: commentId in: path required: true description: The comment id schema: - type: number + 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 required: false - description: category id of the video (see /videos/categories) + description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) schema: oneOf: - - type: number + - type: integer - type: array items: - type: number + type: integer style: form explode: false tagsOneOf: @@ -2189,6 +4063,7 @@ components: oneOf: - type: string - type: array + maxItems: 5 items: type: string style: form @@ -2210,7 +4085,7 @@ components: name: languageOneOf in: query required: false - description: language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language + description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language schema: oneOf: - type: string @@ -2223,13 +4098,13 @@ components: name: licenceOneOf in: query required: false - description: licence id of the video (see /videos/licences) + description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) schema: oneOf: - - type: number + - type: integer - type: array items: - type: number + type: integer style: form explode: false skipCount: @@ -2242,6 +4117,7 @@ components: enum: - 'true' - 'false' + default: 'false' nsfw: name: nsfw in: query @@ -2257,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: @@ -2274,21 +4151,47 @@ components: type: array items: type: string + format: uri + npmName: + name: npmName + in: path + required: true + description: name of the plugin/theme on npmjs.com or in its package.json + 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: @@ -2298,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: number + type: integer + description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) + label: + type: string + 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: + VideoConstantString-Language: properties: id: type: string + description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)) label: type: string @@ -2317,7 +4239,7 @@ components: - 1 - 2 - 3 - description: 'The video playlist privacy (Public = 1, Unlisted = 2, Private = 3)' + description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)' VideoPlaylistPrivacyConstant: properties: id: @@ -2330,7 +4252,7 @@ components: enum: - 1 - 2 - description: 'The video playlist type (Regular = 1, Watch Later = 2)' + description: 'The video playlist type (Regular = `1`, Watch Later = `2`)' VideoPlaylistTypeConstant: properties: id: @@ -2345,7 +4267,7 @@ components: - 2 - 3 - 4 - description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3, Internal = 4)' + description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)' VideoPrivacyConstant: properties: id: @@ -2361,12 +4283,20 @@ components: - do_not_list UserRole: - type: number + type: integer enum: - 0 - 1 - 2 - description: 'The user role (Admin = 0, Moderator = 1, User = 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: @@ -2376,31 +4306,47 @@ components: - 1 - 2 - 3 - description: 'The video state (Published = 1, to transcode = 2, to import = 3)' + description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)' 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 + AbusePredefinedReasons: + type: array + items: + type: string + enum: + - violentOrAbusive + - hatefulOrAbusive + - spamOrMisleading + - privacy + - rights + - serverRules + - thumbnails + - captions + example: [spamOrMisleading] VideoResolutionConstant: 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 + example: 240p VideoScheduledUpdate: properties: privacy: @@ -2414,43 +4360,47 @@ components: AccountSummary: properties: id: - type: number + type: integer name: type: string displayName: type: string url: type: string + format: url host: type: string + format: hostname avatar: nullable: true allOf: - - $ref: '#/components/schemas/Avatar' + - $ref: '#/components/schemas/ActorImage' VideoChannelSummary: properties: id: - type: number + type: integer name: type: string displayName: type: string url: type: string + format: url host: type: string + format: hostname avatar: nullable: true allOf: - - $ref: '#/components/schemas/Avatar' + - $ref: '#/components/schemas/ActorImage' PlaylistElement: properties: position: - type: number + type: integer startTimestamp: - type: number + type: integer stopTimestamp: - type: number + type: integer video: nullable: true allOf: @@ -2462,35 +4412,57 @@ components: resolution: $ref: '#/components/schemas/VideoResolutionConstant' size: - type: number + type: integer 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 metadataUrl: 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: number - type: - type: number - enum: - - 1 - description: 'Playlist type (HLS = 1)' playlistUrl: type: string + format: url segmentsSha256Url: type: string + 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: @@ -2500,48 +4472,93 @@ components: properties: baseUrl: type: string - Video: + format: url + VideoInfo: properties: id: - type: number + type: integer uuid: + $ref: '#/components/schemas/UUIDv4' + name: type: string + minLength: 3 + maxLength: 120 + Video: + properties: + id: + type: integer + example: 8 + uuid: + $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: number + 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: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg embedPath: type: string + example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee views: - type: number + type: integer + example: 1337 likes: - type: number + type: integer + example: 42 dislikes: - type: number + type: integer + example: 7 nsfw: type: boolean waitTranscoding: @@ -2568,7 +4585,7 @@ components: type: object properties: currentTime: - type: number + type: integer VideoDetails: allOf: - $ref: '#/components/schemas/Video' @@ -2576,20 +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: + example: [flowers, gardening] type: array + minItems: 1 + maxItems: 5 items: type: string - files: - type: array - items: - $ref: '#/components/schemas/VideoFile' + minLength: 2 + maxLength: 30 commentsEnabled: type: boolean downloadEnabled: @@ -2598,10 +4622,72 @@ components: type: array 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: + type: integer + fileUrl: + type: string + format: url + strategy: + type: string + enum: + - manual + - most-views + - trending + - recently-added + size: + type: integer + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + expiresOn: + type: string + format: date-time + VideoRedundancy: + properties: + id: + type: integer + name: + type: string + url: + type: string + format: url + uuid: + $ref: '#/components/schemas/UUIDv4' + redundancies: + type: object + properties: + files: + type: array + items: + $ref: '#/components/schemas/FileRedundancyInformation' + streamingPlaylists: + type: array + items: + $ref: '#/components/schemas/FileRedundancyInformation' VideoImportStateConstant: properties: id: @@ -2610,116 +4696,153 @@ components: - 1 - 2 - 3 - description: 'The video import state (Pending = 1, Success = 2, Failed = 3)' + description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)' label: type: string + example: Pending VideoImport: properties: id: - type: number + type: integer + example: 2 targetUrl: type: string + format: url + example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d magnetUri: type: string + format: uri + example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 torrentName: - type: string - state: - type: object - properties: - id: - $ref: '#/components/schemas/VideoImportStateConstant' - label: - type: string + type: string + state: + $ref: '#/components/schemas/VideoImportStateConstant' error: type: string createdAt: type: string + format: date-time updatedAt: type: string + format: date-time video: $ref: '#/components/schemas/Video' - VideoAbuse: + Abuse: properties: id: - type: number + type: integer + example: 7 reason: type: string + example: The video is a spam + minLength: 2 + maxLength: 3000 + predefinedReasons: + $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: number - name: - type: string - uuid: - type: string + $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: - type: number + type: integer videoId: - type: number + type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time name: type: string + minLength: 3 + maxLength: 120 uuid: - type: string + $ref: '#/components/schemas/UUIDv4' description: type: string + minLength: 3 + maxLength: 10000 duration: - type: number + type: integer views: - type: number + type: integer likes: - type: number + type: integer dislikes: - type: number + type: integer nsfw: type: boolean VideoChannel: properties: displayName: type: string + minLength: 1 + maxLength: 120 description: type: string + minLength: 3 + maxLength: 1000 isLocal: type: boolean ownerAccount: type: object properties: id: - type: number + type: integer uuid: - type: string + $ref: '#/components/schemas/UUIDv4' VideoPlaylist: properties: id: - type: number + type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time description: type: string + minLength: 3 + maxLength: 1000 uuid: - type: string + $ref: '#/components/schemas/UUIDv4' displayName: type: string + minLength: 1 + maxLength: 120 isLocal: type: boolean videoLength: - type: number + type: integer thumbnailPath: type: string privacy: @@ -2733,25 +4856,30 @@ components: VideoComment: properties: id: - type: number + type: integer url: type: string + format: url text: type: string + minLength: 1 + maxLength: 10000 threadId: - type: number + type: integer inReplyToCommentId: - type: number + type: integer videoId: - type: number + type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time totalRepliesFromVideoAuthor: - type: number + type: integer totalReplies: - type: number + type: integer account: $ref: '#/components/schemas/Account' VideoCommentThreadTree: @@ -2765,109 +4893,79 @@ components: VideoCaption: properties: language: - $ref: '#/components/schemas/VideoConstantString' + $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string - Avatar: + ActorImage: properties: path: type: string createdAt: type: string + format: date-time updatedAt: type: string + format: date-time + ActorInfo: + properties: + id: + type: integer + example: 11 + name: + type: string + displayName: + type: string + host: + type: string + format: hostname + avatar: + nullable: true + type: object + properties: + path: + type: string Actor: properties: id: - type: number + type: integer + example: 11 url: type: string + format: url name: type: string host: type: string + format: hostname followingCount: - type: number + type: integer followersCount: - type: number + type: integer createdAt: type: string + format: date-time updatedAt: type: string + format: date-time avatar: - $ref: '#/components/schemas/Avatar' + $ref: '#/components/schemas/ActorImage' Account: allOf: - $ref: '#/components/schemas/Actor' - properties: userId: type: string + example: 2 displayName: type: string description: type: string - User: - properties: - id: - type: number - username: - type: string - email: - type: string - theme: - type: string - description: 'Theme enabled by this user' - emailVerified: - type: boolean - description: 'Is email verified?' - nsfwPolicy: - $ref: '#/components/schemas/NSFWPolicy' - webtorrentEnabled: - type: boolean - autoPlayVideo: - type: boolean - role: - $ref: '#/components/schemas/UserRole' - roleLabel: - type: string - enum: - - User - - Moderator - - Administrator - videoQuota: - type: number - videoQuotaDaily: - type: number - videosCount: - type: number - videoAbusesCount: - type: number - videoAbusesAcceptedCount: - type: number - videoAbusesCreatedCount: - type: number - videoCommentsCount: - type: number - noInstanceConfigWarningModal: - type: boolean - noWelcomeModal: - type: boolean - blocked: - type: boolean - blockedReason: - type: string - createdAt: - type: string - account: - $ref: '#/components/schemas/Account' - videoChannels: - type: array - items: - $ref: '#/components/schemas/VideoChannel' UserWatchingVideo: properties: currentTime: - type: number + type: integer + description: timestamp within the video, in seconds + example: 5 ServerConfig: properties: instance: @@ -2953,7 +5051,7 @@ components: enabledResolutions: type: array items: - type: number + type: integer import: type: object properties: @@ -2991,7 +5089,7 @@ components: type: object properties: max: - type: number + type: integer extensions: type: array items: @@ -3010,7 +5108,7 @@ components: type: object properties: max: - type: number + type: integer file: type: object properties: @@ -3028,7 +5126,7 @@ components: type: object properties: max: - type: number + type: integer extensions: type: array items: @@ -3037,9 +5135,9 @@ components: type: object properties: videoQuota: - type: number + type: integer videoQuotaDaily: - type: number + type: integer trending: type: object properties: @@ -3047,7 +5145,7 @@ components: type: object properties: intervalDays: - type: number + type: integer tracker: type: object properties: @@ -3064,6 +5162,7 @@ components: properties: indexUrl: type: string + format: url ServerConfigAbout: properties: instance: @@ -3125,19 +5224,19 @@ components: type: object properties: size: - type: number + type: integer captions: type: object properties: size: - type: number + type: integer signup: type: object properties: enabled: type: boolean limit: - type: number + type: integer requiresEmailVerification: type: boolean admin: @@ -3145,6 +5244,7 @@ components: properties: email: type: string + format: email contactForm: type: object properties: @@ -3154,9 +5254,9 @@ components: type: object properties: videoQuota: - type: number + type: integer videoQuotaDaily: - type: number + type: integer transcoding: type: object properties: @@ -3167,7 +5267,7 @@ components: allowAudioFiles: type: boolean threads: - type: number + type: integer resolutions: type: object properties: @@ -3181,6 +5281,8 @@ components: type: boolean 1080p: type: boolean + 1440p: + type: boolean 2160p: type: boolean hls: @@ -3228,13 +5330,14 @@ components: Follow: properties: id: - type: number + type: integer follower: $ref: '#/components/schemas/Actor' following: $ref: '#/components/schemas/Actor' score: type: number + description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`. state: type: string enum: @@ -3242,86 +5345,316 @@ components: - accepted createdAt: type: string + format: date-time 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: - type: number + type: integer + minimum: 0 + example: 42 state: type: string enum: - - pending - - processing - - error - - success - category: + - active + - completed + - failed + - waiting + - delayed + type: type: string enum: - - transcoding - - activitypub-http - handlerName: + - activitypub-http-unicast + - activitypub-http-broadcast + - activitypub-http-fetcher + - activitypub-follow + - video-file-import + - video-transcoding + - email + - video-import + - videos-views + - activitypub-refresher + - video-redundancy + data: + type: object + additionalProperties: true + error: + type: object + additionalProperties: true + createdAt: + type: string + format: date-time + finishedOn: + type: string + format: date-time + processedOn: + type: string + format: date-time + AddUserResponse: + properties: + user: + type: object + properties: + id: + type: integer + example: 8 + account: + type: object + properties: + 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: + type: object + properties: + id: + type: integer + example: 8 + uuid: + $ref: '#/components/schemas/UUIDv4' + CommentThreadResponse: + properties: + total: + type: integer + example: 1 + data: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/VideoComment' + CommentThreadPostResponse: + properties: + comment: + $ref: '#/components/schemas/VideoComment' + VideoListResponse: + properties: + total: + type: integer + example: 1 + data: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/Video' + User: + properties: + id: + type: integer + readOnly: true + username: + type: string + description: The user username + minLength: 1 + maxLength: 50 + email: + 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 + emailVerified: + type: boolean + description: Has the user confirmed their email address? + nsfwPolicy: + $ref: '#/components/schemas/NSFWPolicy' + webtorrentEnabled: + type: boolean + description: Enable P2P in the player + autoPlayVideo: + type: boolean + description: Automatically start playing the video on the watch page + role: + $ref: '#/components/schemas/UserRole' + roleLabel: type: string - handlerInputData: + enum: + - User + - Moderator + - Administrator + videoQuota: + type: integer + description: The user video quota + videoQuotaDaily: + type: integer + description: The user daily video quota + videosCount: + type: integer + abusesCount: + type: integer + abusesAcceptedCount: + type: integer + abusesCreatedCount: + type: integer + videoCommentsCount: + type: integer + noInstanceConfigWarningModal: + type: boolean + noWelcomeModal: + type: boolean + blocked: + type: boolean + blockedReason: type: string createdAt: type: string - updatedAt: - type: string - AddUserResponse: - properties: - id: - type: number - uuid: - type: string - VideoUploadResponse: - properties: - video: - type: object - properties: - id: - type: number - uuid: - type: string - CommentThreadResponse: - properties: - total: - type: number - data: - type: array - items: - $ref: '#/components/schemas/VideoComment' - CommentThreadPostResponse: - properties: - comment: - $ref: '#/components/schemas/VideoComment' - VideoListResponse: - properties: - total: - type: number - data: + account: + $ref: '#/components/schemas/Account' + videoChannels: type: array items: - $ref: '#/components/schemas/Video' + $ref: '#/components/schemas/VideoChannel' AddUser: properties: username: type: string - description: 'The user username ' + description: The user username + minLength: 1 + maxLength: 50 password: type: string - description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent ' + format: password + description: The user password. If the smtp server is configured, you can leave empty and an email will be sent + minLength: 6 + maxLength: 255 email: type: string - description: 'The user email ' + format: email + description: The user email videoQuota: - type: string - description: 'The user videoQuota ' + type: integer + description: The user video quota videoQuotaDaily: + type: integer + description: The user daily video quota + channelName: type: string - description: 'The user daily video quota ' + description: The user default channel username role: $ref: '#/components/schemas/UserRole' + adminFlags: + $ref: '#/components/schemas/UserAdminFlags' required: - username - password @@ -3333,38 +5666,53 @@ components: properties: id: type: string - description: 'The user id ' + description: The user id email: type: string - description: 'The updated email of the user ' + format: email + description: The updated email of the user + emailVerified: + type: boolean + description: Set the email as verified videoQuota: - type: string - description: 'The updated videoQuota of the user ' + 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 - description: 'The updated daily video quota of the user ' + 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: type: string - description: 'Your new password ' + format: password + description: Your new password + minLength: 6 + maxLength: 255 email: type: string - description: 'Your new email ' + format: email + description: Your new email displayNSFW: type: string - description: 'Your new displayNSFW ' + description: Your new displayNSFW + enum: + - 'true' + - 'false' + - both autoPlayVideo: - type: string - description: 'Your new autoPlayVideo ' + type: boolean + description: Your new autoPlayVideo required: - password - email @@ -3374,10 +5722,14 @@ components: properties: id: type: string - description: 'Id of the video ' + description: Id of the video rating: - type: number - description: 'Rating of the video ' + type: string + enum: + - like + - dislike + - none + description: Rating of the video required: - id - rating @@ -3386,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 @@ -3395,52 +5751,507 @@ components: properties: username: type: string - description: 'The username of the user ' + description: The username of the user + minLength: 1 + maxLength: 50 + pattern: '/^[a-z0-9._]{1,50}$/' password: type: string - description: 'The password of the user ' + format: password + description: The password of the user + minLength: 6 + maxLength: 255 email: type: string - description: 'The email of the user ' + format: email + description: The email of the user displayName: type: string - description: 'The user display name' + description: The user display name + minLength: 1 + maxLength: 120 channel: type: object properties: name: type: string - description: 'The default channel name' + description: The username for the default channel + pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' displayName: type: string - description: 'The default channel display name' - + description: The display name for the default channel + minLength: 1 + maxLength: 120 required: - 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: + allOf: + - $ref: '#/components/schemas/VideoChannelCommon' + - properties: + bulkVideosSupportUpdate: + type: boolean + description: 'Update the support field for all videos of this channel' + + MRSSPeerLink: + type: object + xml: + name: 'media:peerLink' properties: - displayName: + href: + type: string + xml: + attribute: true + type: + type: string + enum: + - application/x-bittorrent + xml: + attribute: true + MRSSGroupContent: + type: object + xml: + name: 'media:content' + properties: + url: + type: string + format: url + xml: + attribute: true + fileSize: + type: integer + xml: + attribute: true + type: + type: string + xml: + attribute: true + framerate: + type: integer + xml: + attribute: true + duration: + type: integer + xml: + attribute: true + height: + type: integer + xml: + attribute: true + lang: + type: string + xml: + attribute: true + VideoCommentsForXML: + type: array + xml: + wrapped: true + name: 'channel' + items: + type: object + xml: + name: 'item' + properties: + link: + type: string + format: url + guid: + type: string + pubDate: + type: string + format: date-time + 'content:encoded': + type: string + 'dc:creator': + type: string + VideosForXML: + type: array + xml: + wrapped: true + name: 'channel' + items: + type: object + xml: + name: 'item' + properties: + link: + type: string + format: url + description: video watch page URL + guid: + type: string + description: video canonical URL + pubDate: + type: string + format: date-time + description: video publication date + description: + type: string + description: video description + 'content:encoded': + type: string + description: video description + 'dc:creator': + type: string + description: publisher user name + 'media:category': + type: integer + description: video category (MRSS) + 'media:community': + type: object + description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS) + properties: + 'media:statistics': + type: object + properties: + views: + type: integer + xml: + attribute: true + 'media:embed': + type: object + properties: + url: + type: string + format: url + description: video embed path, relative to the canonical URL domain (MRSS) + xml: + attribute: true + 'media:player': + type: object + properties: + url: + type: string + format: url + description: video watch path, relative to the canonical URL domain (MRSS) + xml: + attribute: true + 'media:thumbnail': + type: object + properties: + url: + type: string + format: url + xml: + attribute: true + height: + type: integer + xml: + attribute: true + width: + type: integer + xml: + attribute: true + 'media:title': + type: string + description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles. + 'media:description': + type: string + 'media:rating': + type: string + enum: + - nonadult + - adult + description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS) + 'enclosure': + type: object + description: main streamable file for the video + properties: + url: + type: string + format: url + xml: + attribute: true + type: + type: string + enum: + - application/x-bittorrent + xml: + attribute: true + length: + type: integer + xml: + attribute: true + 'media:group': + type: array + description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS) + items: + anyOf: + - $ref: '#/components/schemas/MRSSPeerLink' + - $ref: '#/components/schemas/MRSSGroupContent' + NotificationSettingValue: + type: integer + description: > + Notification type + + - `0` NONE + + - `1` WEB + + - `2` EMAIL + enum: + - 0 + - 1 + - 3 + Notification: + properties: + id: + type: integer + type: + type: integer + description: > + Notification type, following the `UserNotificationType` enum: + + - `1` NEW_VIDEO_FROM_SUBSCRIPTION + + - `2` NEW_COMMENT_ON_MY_VIDEO + + - `3` NEW_ABUSE_FOR_MODERATORS + + - `4` BLACKLIST_ON_MY_VIDEO + + - `5` UNBLACKLIST_ON_MY_VIDEO + + - `6` MY_VIDEO_PUBLISHED + + - `7` MY_VIDEO_IMPORT_SUCCESS + + - `8` MY_VIDEO_IMPORT_ERROR + + - `9` NEW_USER_REGISTRATION + + - `10` NEW_FOLLOW + + - `11` COMMENT_MENTION + + - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS + + - `13` NEW_INSTANCE_FOLLOWER + + - `14` AUTO_INSTANCE_FOLLOWING + read: + type: boolean + video: + nullable: true + allOf: + - $ref: '#/components/schemas/VideoInfo' + - type: object + properties: + channel: + $ref: '#/components/schemas/ActorInfo' + videoImport: + nullable: true + type: object + properties: + id: + type: integer + video: + nullable: true + $ref: '#/components/schemas/VideoInfo' + torrentName: + type: string + nullable: true + magnetUri: + type: string + format: uri + nullable: true + targetUri: + type: string + format: uri + nullable: true + comment: + nullable: true + type: object + properties: + id: + type: integer + threadId: + type: integer + video: + $ref: '#/components/schemas/VideoInfo' + account: + $ref: '#/components/schemas/ActorInfo' + videoAbuse: + nullable: true + type: object + properties: + id: + type: integer + video: + allOf: + - $ref: '#/components/schemas/VideoInfo' + videoBlacklist: + nullable: true + type: object + properties: + id: + type: integer + video: + allOf: + - $ref: '#/components/schemas/VideoInfo' + account: + nullable: true + allOf: + - $ref: '#/components/schemas/ActorInfo' + actorFollow: + type: object + nullable: true + properties: + id: + type: integer + follower: + $ref: '#/components/schemas/ActorInfo' + state: + type: string + enum: + - pending + - accepted + following: + type: object + properties: + type: + type: string + enum: + - account + - channel + - instance + name: + type: string + displayName: + type: string + host: + type: string + format: hostname + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + NotificationListResponse: + properties: + total: + type: integer + example: 1 + data: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/Notification' + Plugin: + properties: + name: + type: string + example: peertube-plugin-auth-ldap + type: + type: integer + description: > + - `1`: PLUGIN + + - `2`: THEME + enum: + - 1 + - 2 + latestVersion: + type: string + example: 0.0.3 + version: + type: string + example: 0.0.1 + enabled: + type: boolean + uninstalled: + type: boolean + peertubeEngine: type: string + example: 2.2.0 description: type: string - support: + homepage: + type: string + format: url + example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap + settings: + type: object + additionalProperties: true + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + PluginResponse: + properties: + total: + type: integer + example: 1 + data: + type: array + 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 - bulkVideosSupportUpdate: + 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 - description: 'Update all videos support field of this channel' + + + callbacks: + searchIndex: + '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: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoListResponse'