X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=f90b7f575f1a8c7440c80040d1f2b0b2377def73;hb=a2be43f5700460d3afdc194abc788690b79e66cd;hp=76e78fe53a65fc12f4b51a754a18c76ed0de97d4;hpb=4d029ef8ec3d5274eeaa3ee6d808eb7035e7faef;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index 76e78fe53..f90b7f575 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: 3.3.0 + version: 5.1.0 contact: name: PeerTube Community url: https://joinpeertube.org @@ -145,7 +145,6 @@ info: | `/api/*` | | `/download/*` | | `/lazy-static/*` | - | `/live/segments-sha256/*` | | `/.well-known/webfinger` | In addition, all routes serving ActivityPub are CORS-enabled for all origins. @@ -247,11 +246,15 @@ tags: ### Import - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/) - - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file - - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file + - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file + - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file The import function is practical when the desired video/audio is available online. It makes PeerTube download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have. + - name: Video Imports + description: Operations dealing with listing, adding and removing video imports. + - name: Channels Sync + description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms - name: Video Captions description: Operations dealing with listing, adding and removing closed captions of a video. - name: Video Channels @@ -267,8 +270,14 @@ tags: 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: Video Files + description: Operations on video files + - name: Video Transcoding + description: Video transcoding related operations + - name: Video stats + description: Video statistics + - name: Video Feeds + description: Server syndication feeds of videos - name: Search description: | The search helps to find _videos_ or _channels_ from within the instance and beyond. @@ -285,7 +294,17 @@ tags: PeerTube instances can mirror videos from one another, and help distribute some videos. For importing videos as your own, refer to [video imports](#operation/importVideo). + - name: Stats + description: | + Statistics + x-tagGroups: + - name: Static endpoints + tags: + - Static Video Files + - name: Feeds + tags: + - Video Feeds - name: Auth tags: - Register @@ -302,38 +321,360 @@ x-tagGroups: tags: - Video - Video Upload + - Video Imports - Video Captions - Video Channels - Video Comments - Video Rates - Video Playlists + - Video Stats - Video Ownership Change - Video Mirroring + - Video Files + - Video Transcoding - Live Videos - - Feeds + - Channels Sync - name: Search tags: - Search - - name: Custom pages - tags: - - Homepage - name: Moderation tags: - Abuses - Video Blocks - Account Blocks - Server Blocks - - name: Instance Configuration + - name: Instance tags: - Config + - Homepage - Instance Follows - Instance Redundancy - Plugins - - name: Jobs - tags: + - Stats + - Logs - Job paths: - '/accounts/{name}': + '/static/webseed/{filename}': + get: + tags: + - Static Video Files + summary: Get public WebTorrent video file + parameters: + - $ref: '#/components/parameters/staticFilename' + responses: + '200': + description: successful operation + '404': + description: not found + '/static/webseed/private/{filename}': + get: + tags: + - Static Video Files + summary: Get private WebTorrent video file + parameters: + - $ref: '#/components/parameters/staticFilename' + - $ref: '#/components/parameters/videoFileToken' + security: + - OAuth2: [] + responses: + '200': + description: successful operation + '403': + description: invalid auth + '404': + description: not found + + '/static/streaming-playlists/hls/{filename}': + get: + tags: + - Static Video Files + summary: Get public HLS video file + parameters: + - $ref: '#/components/parameters/staticFilename' + security: + - OAuth2: [] + responses: + '200': + description: successful operation + '403': + description: invalid auth + '404': + description: not found + '/static/streaming-playlists/hls/private/{filename}': + get: + tags: + - Static Video Files + summary: Get private HLS video file + parameters: + - $ref: '#/components/parameters/staticFilename' + - $ref: '#/components/parameters/videoFileToken' + - $ref: '#/components/parameters/reinjectVideoFileToken' + security: + - OAuth2: [] + responses: + '200': + description: successful operation + '403': + description: invalid auth + '404': + description: not found + + + '/feeds/video-comments.{format}': + get: + tags: + - Video Feeds + summary: List comments on videos + operationId: getSyndicatedComments + 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: + - Video Feeds + summary: List videos + operationId: getSyndicatedVideos + 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/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' + 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: + - Video Feeds + summary: List videos of subscriptions tied to a token + operationId: getSyndicatedSubscriptionVideos + 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/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' + 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 + + '/api/v1/accounts/{name}': get: tags: - Accounts @@ -351,7 +692,7 @@ paths: '404': description: account not found - '/accounts/{name}/videos': + '/api/v1/accounts/{name}/videos': get: tags: - Accounts @@ -367,7 +708,11 @@ paths: - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -414,7 +759,37 @@ paths: print(json) - /accounts: + '/api/v1/accounts/{name}/followers': + get: + tags: + - Accounts + summary: 'List followers of an account' + security: + - OAuth2: [] + operationId: getAccountFollowers + parameters: + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/followersSort' + - $ref: '#/components/parameters/search' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/Follow' + + /api/v1/accounts: get: tags: - Accounts @@ -434,7 +809,7 @@ paths: items: $ref: '#/components/schemas/Account' - /config: + /api/v1/config: get: tags: - Config @@ -451,7 +826,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/config - /config/about: + /api/v1/config/about: get: summary: Get instance "About" information operationId: getAbout @@ -468,7 +843,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/config/about - /config/custom: + /api/v1/config/custom: get: summary: Get instance runtime configuration operationId: getCustomConfig @@ -513,7 +888,7 @@ paths: '200': description: successful operation - /custom-pages/homepage/instance: + /api/v1/custom-pages/homepage/instance: get: summary: Get instance custom homepage tags: @@ -547,7 +922,31 @@ paths: '204': description: successful operation - /jobs/{state}: + /api/v1/jobs/pause: + post: + summary: Pause job queue + security: + - OAuth2: + - admin + tags: + - Job + responses: + '204': + description: successful operation + + /api/v1/jobs/resume: + post: + summary: Resume job queue + security: + - OAuth2: + - admin + tags: + - Job + responses: + '204': + description: successful operation + + /api/v1/jobs/{state}: get: summary: List instance jobs operationId: getJobs @@ -591,7 +990,7 @@ paths: items: $ref: '#/components/schemas/Job' - /server/followers: + /api/v1/server/followers: get: tags: - Instance Follows @@ -618,7 +1017,7 @@ paths: items: $ref: '#/components/schemas/Follow' - '/server/followers/{nameWithHost}': + '/api/v1/server/followers/{nameWithHost}': delete: summary: Remove or reject a follower to your server security: @@ -640,7 +1039,7 @@ paths: '404': description: follower not found - '/server/followers/{nameWithHost}/reject': + '/api/v1/server/followers/{nameWithHost}/reject': post: summary: Reject a pending follower to your server security: @@ -662,7 +1061,7 @@ paths: '404': description: follower not found - '/server/followers/{nameWithHost}/accept': + '/api/v1/server/followers/{nameWithHost}/accept': post: summary: Accept a pending follower to your server security: @@ -684,7 +1083,7 @@ paths: '404': description: follower not found - /server/following: + /api/v1/server/following: get: tags: - Instance Follows @@ -740,7 +1139,7 @@ paths: type: string uniqueItems: true - '/server/following/{hostOrHandle}': + '/api/v1/server/following/{hostOrHandle}': delete: summary: Unfollow an actor (PeerTube instance, channel or account) security: @@ -761,7 +1160,7 @@ paths: '404': description: host or handle not found - /users: + /api/v1/users: post: summary: Create a user operationId: addUser @@ -828,7 +1227,7 @@ paths: items: $ref: '#/components/schemas/User' - '/users/{id}': + '/api/v1/users/{id}': parameters: - $ref: '#/components/parameters/id' delete: @@ -884,7 +1283,7 @@ paths: $ref: '#/components/schemas/UpdateUser' required: true - /oauth-clients/local: + /api/v1/oauth-clients/local: get: summary: Login prerequisite description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken). @@ -912,7 +1311,7 @@ paths: ## AUTH curl -s "$API/oauth-clients/local" - /users/token: + /api/v1/users/token: post: summary: Login operationId: getOAuthToken @@ -989,7 +1388,7 @@ paths: --data password="$PASSWORD" \ | jq -r ".access_token" - /users/revoke-token: + /api/v1/users/revoke-token: post: summary: Logout description: Revokes your access token and its associated refresh token, destroying your current session. @@ -1002,33 +1401,148 @@ paths: '200': description: successful operation - /users/register: + /api/v1/users/ask-send-verify-email: post: - summary: Register a user - operationId: registerUser + summary: Resend user verification link + operationId: resendEmailToVerifyUser tags: - Users - Register + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + description: User email responses: '204': description: successful operation + + /api/v1/users/registrations/ask-send-verify-email: + post: + summary: Resend verification link to registration email + operationId: resendEmailToVerifyRegistration + tags: + - Register requestBody: content: application/json: schema: - $ref: '#/components/schemas/RegisterUser' - required: true + type: object + properties: + email: + type: string + description: Registration email + responses: + '204': + description: successful operation - /users/{id}/verify-email: + /api/v1/users/{id}/verify-email: post: summary: Verify a user operationId: verifyUser description: | Following a user registration, the new user will receive an email asking to click a link containing a secret. + This endpoint can also be used to verify a new email set in the user account. + tags: + - Users + - Register + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + verificationString: + type: string + format: url + isPendingEmail: + type: boolean + required: + - verificationString + responses: + '204': + description: successful operation + '403': + description: invalid verification string + '404': + description: user not found + + /api/v1/users/registrations/{registrationId}/verify-email: + post: + summary: Verify a registration email + operationId: verifyRegistrationEmail + description: | + Following a user registration request, the user will receive an email asking to click a link + containing a secret. + tags: + - Register + parameters: + - $ref: '#/components/parameters/registrationId' + requestBody: + content: + application/json: + schema: + type: object + properties: + verificationString: + type: string + format: url + required: + - verificationString + responses: + '204': + description: successful operation + '403': + description: invalid verification string + '404': + description: registration not found + + /api/v1/users/{id}/two-factor/request: + post: + summary: Request two factor auth + operationId: requestTwoFactor + description: Request two factor authentication for a user + tags: + - Users + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + currentPassword: + type: string + description: Password of the currently authenticated user + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/RequestTwoFactorResponse' + '403': + description: invalid password + '404': + description: user not found + + /api/v1/users/{id}/two-factor/confirm-request: + post: + summary: Confirm two factor auth + operationId: confirmTwoFactorRequest + description: Confirm a two factor authentication request tags: - Users - - Register parameters: - $ref: '#/components/parameters/id' requestBody: @@ -1037,33 +1551,50 @@ paths: schema: type: object properties: - verificationString: + requestToken: type: string - format: url - isPendingEmail: - type: boolean + description: Token to identify the two factor request + otpToken: + type: string + description: OTP token generated by the app required: - - verificationString + - requestToken + - otpToken responses: '204': description: successful operation '403': - description: invalid verification string + description: invalid request token or OTP token '404': description: user not found - /users/ask-send-verify-email: + /api/v1/users/{id}/two-factor/disable: post: - summary: Resend user verification link - operationId: resendEmailToVerifyUser + summary: Disable two factor auth + operationId: disableTwoFactor + description: Disable two factor authentication of a user tags: - Users - - Register + parameters: + - $ref: '#/components/parameters/id' + requestBody: + content: + application/json: + schema: + type: object + properties: + currentPassword: + type: string + description: Password of the currently authenticated user responses: '204': description: successful operation + '403': + description: invalid password + '404': + description: user not found - /users/me: + /api/v1/users/me: get: summary: Get my user information operationId: getUserInfo @@ -1099,7 +1630,7 @@ paths: $ref: '#/components/schemas/UpdateMe' required: true - /users/me/videos/imports: + /api/v1/users/me/videos/imports: get: summary: Get video imports of my user security: @@ -1112,6 +1643,27 @@ paths: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' + - + name: targetUrl + in: query + required: false + description: Filter on import target URL + schema: + type: string + - + name: videoChannelSyncId + in: query + required: false + description: Filter on imports created by a specific channel synchronization + schema: + type: number + - + name: search + in: query + required: false + description: Search in video names + schema: + type: string responses: '200': description: successful operation @@ -1120,7 +1672,7 @@ paths: schema: $ref: '#/components/schemas/VideoImportsList' - /users/me/video-quota-used: + /api/v1/users/me/video-quota-used: get: summary: Get my user used quota security: @@ -1145,7 +1697,7 @@ paths: description: The user video quota used today in bytes example: 1681014151 - '/users/me/videos/{videoId}/rating': + '/api/v1/users/me/videos/{videoId}/rating': get: summary: Get rate of my user for a video security: @@ -1168,7 +1720,7 @@ paths: schema: $ref: '#/components/schemas/GetMeVideoRating' - /users/me/videos: + /api/v1/users/me/videos: get: summary: Get videos of my user security: @@ -1189,7 +1741,7 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' - /users/me/subscriptions: + /api/v1/users/me/subscriptions: get: summary: Get my user subscriptions security: @@ -1235,7 +1787,7 @@ paths: '200': description: successful operation - /users/me/subscriptions/exist: + /api/v1/users/me/subscriptions/exist: get: summary: Get if subscriptions exist for my user security: @@ -1253,7 +1805,7 @@ paths: schema: type: object - /users/me/subscriptions/videos: + /api/v1/users/me/subscriptions/videos: get: summary: List videos of subscriptions of my user security: @@ -1270,7 +1822,11 @@ paths: - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -1283,7 +1839,7 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' - '/users/me/subscriptions/{subscriptionHandle}': + '/api/v1/users/me/subscriptions/{subscriptionHandle}': get: summary: Get subscription of my user security: @@ -1313,7 +1869,7 @@ paths: '200': description: successful operation - /users/me/notifications: + /api/v1/users/me/notifications: get: summary: List my notifications security: @@ -1337,7 +1893,7 @@ paths: schema: $ref: '#/components/schemas/NotificationListResponse' - /users/me/notifications/read: + /api/v1/users/me/notifications/read: post: summary: Mark notifications as read by their id security: @@ -1361,7 +1917,7 @@ paths: '204': description: successful operation - /users/me/notifications/read-all: + /api/v1/users/me/notifications/read-all: post: summary: Mark all my notification as read security: @@ -1372,7 +1928,7 @@ paths: '204': description: successful operation - /users/me/notification-settings: + /api/v1/users/me/notification-settings: put: summary: Update my notification settings security: @@ -1413,7 +1969,7 @@ paths: '204': description: successful operation - /users/me/history/videos: + /api/v1/users/me/history/videos: get: summary: List watched videos history security: @@ -1432,7 +1988,24 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' - /users/me/history/videos/remove: + /api/v1/users/me/history/videos/{videoId}: + delete: + summary: Delete history element + security: + - OAuth2: [] + tags: + - My History + parameters: + - name: videoId + in: path + required: true + schema: + $ref: '#/components/schemas/Video/properties/id' + responses: + '204': + description: successful operation + + /api/v1/users/me/history/videos/remove: post: summary: Clear video history security: @@ -1453,7 +2026,7 @@ paths: '204': description: successful operation - /users/me/avatar/pick: + /api/v1/users/me/avatar/pick: post: summary: Update my user avatar security: @@ -1468,8 +2041,10 @@ paths: schema: type: object properties: - avatar: - $ref: '#/components/schemas/ActorImage' + avatars: + type: array + items: + $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: @@ -1492,7 +2067,7 @@ paths: avatarfile: contentType: image/png, image/jpeg - /users/me/avatar: + /api/v1/users/me/avatar: delete: summary: Delete my avatar security: @@ -1503,7 +2078,147 @@ paths: '204': description: successful operation - /videos/ownership: + /api/v1/users/register: + post: + summary: Register a user + operationId: registerUser + description: Signup has to be enabled and signup approval is not required + tags: + - Register + responses: + '204': + description: successful operation + '400': + description: request error + '403': + description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin + '409': + description: 'a user with this username, channel name or email already exists' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterUser' + required: true + + /api/v1/users/registrations/request: + post: + summary: Request registration + description: Signup has to be enabled and require approval on the instance + operationId: requestRegistration + tags: + - Register + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/UserRegistration' + '400': + description: request error or signup approval is not enabled on the instance + '403': + description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin + '409': + description: 'a user or registration with this username, channel name or email already exists' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserRegistrationRequest' + + /api/v1/users/registrations/{registrationId}/accept: + post: + security: + - OAuth2: + - admin + - moderator + summary: Accept registration + operationId: acceptRegistration + tags: + - Register + parameters: + - $ref: '#/components/parameters/registrationId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserRegistrationAcceptOrReject' + responses: + '204': + description: successful operation + + /api/v1/users/registrations/{registrationId}/reject: + post: + security: + - OAuth2: + - admin + - moderator + summary: Reject registration + operationId: rejectRegistration + tags: + - Register + parameters: + - $ref: '#/components/parameters/registrationId' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserRegistrationAcceptOrReject' + responses: + '204': + description: successful operation + + /api/v1/users/registrations/{registrationId}: + delete: + security: + - OAuth2: + - admin + - moderator + summary: Delete registration + description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)' + operationId: deleteRegistration + tags: + - Register + parameters: + - $ref: '#/components/parameters/registrationId' + responses: + '204': + description: successful operation + + /api/v1/users/registrations: + get: + security: + - OAuth2: + - admin + - moderator + summary: List registrations + operationId: listRegistrations + tags: + - Register + parameters: + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - name: search + in: query + required: false + schema: + type: string + - name: sort + in: query + required: false + schema: + type: string + enum: + - -createdAt + - createdAt + - state + - -state + responses: + '204': + description: successful operation + + /api/v1/videos/ownership: get: summary: List video ownership changes tags: @@ -1514,7 +2229,7 @@ paths: '200': description: successful operation - '/videos/ownership/{id}/accept': + '/api/v1/videos/ownership/{id}/accept': post: summary: Accept ownership change request tags: @@ -1529,9 +2244,9 @@ paths: '403': description: cannot terminate an ownership change of another user '404': - description: video owneship change not found + description: video ownership change not found - '/videos/ownership/{id}/refuse': + '/api/v1/videos/ownership/{id}/refuse': post: summary: Refuse ownership change request tags: @@ -1546,9 +2261,9 @@ paths: '403': description: cannot terminate an ownership change of another user '404': - description: video owneship change not found + description: video ownership change not found - '/videos/{id}/give-ownership': + '/api/v1/videos/{id}/give-ownership': post: summary: Request ownership change tags: @@ -1576,7 +2291,55 @@ paths: '404': description: video not found - /videos: + '/api/v1/videos/{id}/token': + post: + summary: Request video token + operationId: requestVideoToken + description: Request special tokens that expire quickly to use them in some context (like accessing private static files) + tags: + - Video + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoTokenResponse' + '400': + description: incorrect parameters + '404': + description: video not found + + /api/v1/videos/{id}/studio/edit: + post: + summary: Create a studio task + tags: + - Video Transcoding + - Video + description: Create a task to edit a video (cut, add intro/outro etc) + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + required: true + content: + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/VideoStudioCreateTask' + responses: + '204': + description: successful operation + '400': + description: incorrect parameters + '404': + description: video not found + + /api/v1/videos: get: summary: List videos operationId: getVideos @@ -1590,7 +2353,11 @@ paths: - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -1603,7 +2370,7 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' - /videos/categories: + /api/v1/videos/categories: get: summary: List available video categories operationId: getCategories @@ -1622,7 +2389,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/categories - /videos/licences: + /api/v1/videos/licences: get: summary: List available video licences operationId: getLicences @@ -1641,7 +2408,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/licences - /videos/languages: + /api/v1/videos/languages: get: summary: List available video languages operationId: getLanguages @@ -1660,7 +2427,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/languages - /videos/privacies: + /api/v1/videos/privacies: get: summary: List available video privacy policies operationId: getPrivacyPolicies @@ -1679,7 +2446,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/privacies - '/videos/{id}': + '/api/v1/videos/{id}': put: summary: Update a video operationId: putVideo @@ -1785,7 +2552,7 @@ paths: '204': description: successful operation - '/videos/{id}/description': + '/api/v1/videos/{id}/description': get: summary: Get complete video description operationId: getVideoDesc @@ -1806,39 +2573,148 @@ paths: example: | **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)** - '/videos/{id}/views': - post: - summary: Add a view to a video - operationId: addView + '/api/v1/videos/{id}/source': + post: + summary: Get video source file metadata + operationId: getVideoSource + tags: + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoSource' + + '/api/v1/videos/{id}/views': + post: + summary: Notify user is watching a video + description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time. + operationId: addView + tags: + - Video + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserViewingVideo' + required: true + responses: + '204': + description: successful operation + + '/api/v1/videos/{id}/watching': + put: + summary: Set watching progress of a video + deprecated: true + description: This endpoint has been deprecated. Use `/videos/{id}/views` instead + tags: + - Video + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UserViewingVideo' + required: true + responses: + '204': + description: successful operation + + '/api/v1/videos/{id}/stats/overall': + get: + summary: Get overall stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + - name: startDate + in: query + description: Filter stats by start date + schema: + type: string + format: date-time + - name: endDate + in: query + description: Filter stats by end date + schema: + type: string + format: date-time + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsOverall' + + '/api/v1/videos/{id}/stats/retention': + get: + summary: Get retention stats of a video tags: - - Video + - Video Stats + security: + - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' responses: - '204': + '200': description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsRetention' - '/videos/{id}/watching': - put: - summary: Set watching progress of a video - operationId: setProgress + '/api/v1/videos/{id}/stats/timeseries/{metric}': + get: + summary: Get timeserie stats of a video tags: - - Video + - Video Stats security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/UserWatchingVideo' - required: true + - + name: metric + in: path + required: true + description: The metric to get + schema: + type: string + enum: + - 'viewers' + - 'aggregateWatchTime' + - name: startDate + in: query + description: Filter stats by start date + schema: + type: string + format: date-time + - name: endDate + in: query + description: Filter stats by end date + schema: + type: string + format: date-time responses: - '204': + '200': description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsTimeserie' - /videos/upload: + /api/v1/videos/upload: post: summary: Upload a video description: Uses a single request to upload a video. @@ -1863,7 +2739,7 @@ paths: x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy description: | If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`: - - `quota_reached` for quota limits wether daily or global + - `quota_reached` for quota limits whether daily or global headers: X-File-Maximum-Size: schema: @@ -1916,7 +2792,7 @@ paths: --form channelId=$CHANNEL_ID \ --form name="$NAME" - /videos/upload-resumable: + /api/v1/videos/upload-resumable: post: summary: Initialize the resumable upload of a video description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video @@ -1984,7 +2860,7 @@ paths: in: query required: true description: | - Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is + Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload. schema: type: string @@ -2008,9 +2884,6 @@ paths: description: | Size of the chunk that the request is sending. - The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) - doesn't mandate for chunks to have the same size throughout the upload sequence. - Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health. requestBody: @@ -2051,6 +2924,13 @@ paths: description: video unreadable '429': description: too many concurrent requests + '503': + description: upload is already being processed + headers: + 'Retry-After': + schema: + type: number + example: 300 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 @@ -2086,7 +2966,7 @@ paths: '404': description: upload not found - /videos/imports: + /api/v1/videos/imports: post: summary: Import a video description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) @@ -2094,7 +2974,7 @@ paths: security: - OAuth2: [] tags: - - Video + - Video Imports - Video Upload requestBody: content: @@ -2122,7 +3002,35 @@ paths: '409': description: HTTP or Torrent/magnetURI import not enabled - /videos/live: + /api/v1/videos/imports/{id}/cancel: + post: + summary: Cancel video import + description: Cancel a pending video import + security: + - OAuth2: [] + tags: + - Video Imports + parameters: + - $ref: '#/components/parameters/id' + responses: + '204': + description: successful operation + + /api/v1/videos/imports/{id}: + delete: + summary: Delete video import + description: Delete ended video import + security: + - OAuth2: [] + tags: + - Video Imports + parameters: + - $ref: '#/components/parameters/id' + responses: + '204': + description: successful operation + + /api/v1/videos/live: post: summary: Create a live operationId: addLive @@ -2166,6 +3074,9 @@ paths: permanentLive: description: User can stream multiple times in a permanent live type: boolean + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' thumbnailfile: description: Live video/replay thumbnail file type: string @@ -2221,7 +3132,7 @@ paths: previewfile: contentType: image/jpeg - /videos/live/{id}: + /api/v1/videos/live/{id}: get: summary: Get information about a live operationId: getLiveId @@ -2261,8 +3172,50 @@ paths: description: bad parameters or trying to update a live that has already started '403': description: trying to save replay of the live but saving replay is not enabled on the instance + /api/v1/videos/live/{id}/sessions: + get: + summary: List live sessions + description: List all sessions created in a particular live + security: + - OAuth2: [] + tags: + - Live Videos + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/LiveVideoSessionResponse' + /api/v1/videos/{id}/live-session: + get: + summary: Get live session of a replay + description: If the video is a replay of a live, you can find the associated live session using this endpoint + security: + - OAuth2: [] + tags: + - Live Videos + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/LiveVideoSessionResponse' - /users/me/abuses: + /api/v1/users/me/abuses: get: summary: List my abuses operationId: getMyAbuses @@ -2300,7 +3253,7 @@ paths: items: $ref: '#/components/schemas/Abuse' - /abuses: + /api/v1/abuses: get: summary: List abuses operationId: getAbuses @@ -2453,7 +3406,7 @@ paths: '400': description: incorrect request parameters - '/abuses/{abuseId}': + '/api/v1/abuses/{abuseId}': put: summary: Update an abuse security: @@ -2498,7 +3451,7 @@ paths: '404': description: block not found - '/abuses/{abuseId}/messages': + '/api/v1/abuses/{abuseId}/messages': get: summary: List messages of an abuse security: @@ -2550,7 +3503,7 @@ paths: '400': description: incorrect request parameters - '/abuses/{abuseId}/messages/{abuseMessageId}': + '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}': delete: summary: Delete an abuse message security: @@ -2564,7 +3517,7 @@ paths: '204': description: successful operation - '/videos/{id}/blacklist': + '/api/v1/videos/{id}/blacklist': post: summary: Block a video operationId: addVideoBlock @@ -2596,7 +3549,7 @@ paths: '404': description: block not found - /videos/blacklist: + /api/v1/videos/blacklist: get: tags: - Video Blocks @@ -2644,7 +3597,7 @@ paths: items: $ref: '#/components/schemas/VideoBlacklist' - /videos/{id}/captions: + /api/v1/videos/{id}/captions: get: summary: List captions of a video operationId: getVideoCaptions @@ -2668,7 +3621,7 @@ paths: items: $ref: '#/components/schemas/VideoCaption' - /videos/{id}/captions/{captionLanguage}: + /api/v1/videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption operationId: addVideoCaption @@ -2715,7 +3668,7 @@ paths: '404': description: video or language or caption for that language not found - /video-channels: + /api/v1/video-channels: get: summary: List video channels operationId: getVideoChannels @@ -2740,7 +3693,7 @@ paths: tags: - Video Channels responses: - '204': + '200': description: successful operation content: application/json: @@ -2751,14 +3704,14 @@ paths: type: object properties: id: - $ref: '#/components/schemas/VideoChannel/properties/id' + $ref: '#/components/schemas/id' requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoChannelCreate' - '/video-channels/{channelHandle}': + '/api/v1/video-channels/{channelHandle}': get: summary: Get a video channel operationId: getVideoChannel @@ -2803,7 +3756,7 @@ paths: '204': description: successful operation - '/video-channels/{channelHandle}/videos': + '/api/v1/video-channels/{channelHandle}/videos': get: summary: List videos of a video channel operationId: getVideoChannelVideos @@ -2819,7 +3772,11 @@ paths: - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -2832,7 +3789,37 @@ paths: schema: $ref: '#/components/schemas/VideoListResponse' - '/video-channels/{channelHandle}/avatar/pick': + '/api/v1/video-channels/{channelHandle}/followers': + get: + tags: + - Video Channels + summary: 'List followers of a video channel' + security: + - OAuth2: [] + operationId: getVideoChannelFollowers + parameters: + - $ref: '#/components/parameters/channelHandle' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/followersSort' + - $ref: '#/components/parameters/search' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/Follow' + + '/api/v1/video-channels/{channelHandle}/avatar/pick': post: summary: Update channel avatar security: @@ -2849,8 +3836,10 @@ paths: schema: type: object properties: - avatar: - $ref: '#/components/schemas/ActorImage' + avatars: + type: array + items: + $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: @@ -2873,7 +3862,7 @@ paths: avatarfile: contentType: image/png, image/jpeg - '/video-channels/{channelHandle}/avatar': + '/api/v1/video-channels/{channelHandle}/avatar': delete: summary: Delete channel avatar security: @@ -2886,7 +3875,7 @@ paths: '204': description: successful operation - '/video-channels/{channelHandle}/banner/pick': + '/api/v1/video-channels/{channelHandle}/banner/pick': post: summary: Update channel banner security: @@ -2903,8 +3892,10 @@ paths: schema: type: object properties: - banner: - $ref: '#/components/schemas/ActorImage' + banners: + type: array + items: + $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: @@ -2927,7 +3918,7 @@ paths: bannerfile: contentType: image/png, image/jpeg - '/video-channels/{channelHandle}/banner': + '/api/v1/video-channels/{channelHandle}/banner': delete: summary: Delete channel banner security: @@ -2940,7 +3931,80 @@ paths: '204': description: successful operation - /video-playlists/privacies: + '/api/v1/video-channels/{channelHandle}/import-videos': + post: + summary: Import videos in channel + description: Import a remote channel/playlist videos into a channel + security: + - OAuth2: [] + tags: + - Video Channels + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelHandle' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ImportVideosInChannelCreate' + responses: + '204': + description: successful operation + + '/api/v1/video-channel-syncs': + post: + summary: Create a synchronization for a video channel + operationId: addVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/VideoChannelSyncCreate' + responses: + '200': + description: successful operation + content: + application/json: + schema: + type: object + properties: + videoChannelSync: + $ref: "#/components/schemas/VideoChannelSync" + + '/api/v1/video-channel-syncs/{channelSyncId}': + delete: + summary: Delete a video channel synchronization + operationId: delVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelSyncId' + responses: + '204': + description: successful operation + + '/api/v1/video-channel-syncs/{channelSyncId}/sync': + post: + summary: Triggers the channel synchronization job, fetching all the videos from the remote channel + operationId: triggerVideoChannelSync + security: + - OAuth2: [] + tags: + - Channels Sync + parameters: + - $ref: '#/components/parameters/channelSyncId' + responses: + '204': + description: successful operation + + + /api/v1/video-playlists/privacies: get: summary: List available playlist privacy policies operationId: getPlaylistPrivacyPolicies @@ -2959,7 +4023,7 @@ paths: nightly: externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies - /video-playlists: + /api/v1/video-playlists: get: summary: List video playlists operationId: getPlaylists @@ -3041,7 +4105,7 @@ paths: thumbnailfile: contentType: image/jpeg - /video-playlists/{playlistId}: + /api/v1/video-playlists/{playlistId}: get: summary: Get a video playlist tags: @@ -3106,7 +4170,7 @@ paths: '204': description: successful operation - /video-playlists/{playlistId}/videos: + /api/v1/video-playlists/{playlistId}/videos: get: summary: 'List videos of a playlist' operationId: getVideoPlaylistVideos @@ -3115,6 +4179,8 @@ paths: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' responses: '200': description: successful operation @@ -3168,7 +4234,7 @@ paths: required: - videoId - /video-playlists/{playlistId}/videos/reorder: + /api/v1/video-playlists/{playlistId}/videos/reorder: post: summary: 'Reorder a playlist' operationId: reorderVideoPlaylist @@ -3203,7 +4269,7 @@ paths: - startPosition - insertAfterPosition - /video-playlists/{playlistId}/videos/{playlistElementId}: + /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}: put: summary: Update a playlist element operationId: putVideoPlaylistVideo @@ -3245,7 +4311,7 @@ paths: '204': description: successful operation - '/users/me/video-playlists/videos-exist': + '/api/v1/users/me/video-playlists/videos-exist': get: summary: Check video exists in my playlists security: @@ -3285,7 +4351,7 @@ paths: type: integer format: seconds - '/accounts/{name}/video-channels': + '/api/v1/accounts/{name}/video-channels': get: summary: List video channels of an account tags: @@ -3295,7 +4361,7 @@ paths: - $ref: '#/components/parameters/name' - name: withStats in: query - description: include view statistics for the last 30 days (only if authentified as the account user) + description: include daily view statistics for the last 30 days and total views (only if authentified as the account user) schema: type: boolean - $ref: '#/components/parameters/start' @@ -3309,7 +4375,27 @@ paths: schema: $ref: '#/components/schemas/VideoChannelList' - '/accounts/{name}/ratings': + '/api/v1/accounts/{name}/video-channel-syncs': + get: + summary: List the synchronizations of video channels of an account + tags: + - Video Channels + - Channels Sync + - Accounts + parameters: + - $ref: '#/components/parameters/name' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' + - $ref: '#/components/parameters/sort' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoChannelSyncList' + + '/api/v1/accounts/{name}/ratings': get: summary: List ratings of an account security: @@ -3340,7 +4426,7 @@ paths: items: $ref: '#/components/schemas/VideoRating' - '/videos/{id}/comment-threads': + '/api/v1/videos/{id}/comment-threads': get: summary: List threads of a video tags: @@ -3388,7 +4474,7 @@ paths: required: - text - '/videos/{id}/comment-threads/{threadId}': + '/api/v1/videos/{id}/comment-threads/{threadId}': get: summary: Get a thread tags: @@ -3404,7 +4490,7 @@ paths: schema: $ref: '#/components/schemas/VideoCommentThreadTree' - '/videos/{id}/comments/{commentId}': + '/api/v1/videos/{id}/comments/{commentId}': post: summary: Reply to a thread of a video security: @@ -3455,35 +4541,98 @@ paths: '409': description: comment is already deleted - '/videos/{id}/rate': + '/api/v1/videos/{id}/rate': put: summary: Like/dislike a video security: - - OAuth2: [] + - OAuth2: [] + tags: + - Video Rates + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + content: + application/json: + schema: + type: object + properties: + rating: + type: string + enum: + - like + - dislike + required: + - rating + responses: + '204': + description: successful operation + '404': + description: video does not exist + + '/api/v1/videos/{id}/hls': + delete: + summary: Delete video HLS files + security: + - OAuth2: + - admin + tags: + - Video Files + operationId: delVideoHLS + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '204': + description: successful operation + '404': + description: video does not exist + '/api/v1/videos/{id}/webtorrent': + delete: + summary: Delete video WebTorrent files + security: + - OAuth2: + - admin + tags: + - Video Files + operationId: delVideoWebTorrent + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '204': + description: successful operation + '404': + description: video does not exist + + '/api/v1/videos/{id}/transcoding': + post: + summary: Create a transcoding job + security: + - OAuth2: + - admin tags: - - Video Rates + - Video Transcoding + operationId: createVideoTranscoding parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: - content: - application/json: - schema: - type: object - properties: - rating: - type: string - enum: - - like - - dislike - required: - - rating + content: + application/json: + schema: + type: object + properties: + transcodingType: + type: string + enum: + - hls + - webtorrent + required: + - transcodingType responses: '204': description: successful operation '404': description: video does not exist - /search/videos: + /api/v1/search/videos: get: tags: - Search @@ -3507,7 +4656,12 @@ paths: - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/isLocal' + - $ref: '#/components/parameters/include' + - $ref: '#/components/parameters/privacyOneOf' + - $ref: '#/components/parameters/uuids' + - $ref: '#/components/parameters/hasHLSFiles' + - $ref: '#/components/parameters/hasWebtorrentFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -3560,7 +4714,7 @@ paths: '500': description: search index unavailable - /search/video-channels: + /api/v1/search/video-channels: get: tags: - Search @@ -3593,7 +4747,7 @@ paths: '500': description: search index unavailable - /search/video-playlists: + /api/v1/search/video-playlists: get: tags: - Search @@ -3634,7 +4788,40 @@ paths: '500': description: search index unavailable - /server/blocklist/accounts: + /api/v1/blocklist/status: + get: + tags: + - Account Blocks + - Server Blocks + summary: Get block status of accounts/hosts + parameters: + - + name: 'accounts' + in: query + description: 'Check if these accounts are blocked' + example: [ 'goofy@example.com', 'donald@example.com' ] + schema: + type: array + items: + type: string + - + name: 'hosts' + in: query + description: 'Check if these hosts are blocked' + example: [ 'example.com' ] + schema: + type: array + items: + type: string + responses: + '200': + description: successful operation + content: + 'application/json': + schema: + $ref: '#/components/schemas/BlockStatus' + + /api/v1/server/blocklist/accounts: get: tags: - Account Blocks @@ -3674,7 +4861,7 @@ paths: '409': description: self-blocking forbidden - '/server/blocklist/accounts/{accountName}': + '/api/v1/server/blocklist/accounts/{accountName}': delete: tags: - Account Blocks @@ -3695,7 +4882,7 @@ paths: '404': description: account or account block does not exist - /server/blocklist/servers: + /api/v1/server/blocklist/servers: get: tags: - Server Blocks @@ -3735,7 +4922,7 @@ paths: '409': description: self-blocking forbidden - '/server/blocklist/servers/{host}': + '/api/v1/server/blocklist/servers/{host}': delete: tags: - Server Blocks @@ -3757,7 +4944,7 @@ paths: '404': description: account block does not exist - /server/redundancy/{host}: + /api/v1/server/redundancy/{host}: put: tags: - Instance Redundancy @@ -3790,7 +4977,7 @@ paths: '404': description: server is not already known - /server/redundancy/videos: + /api/v1/server/redundancy/videos: get: tags: - Video Mirroring @@ -3849,7 +5036,7 @@ paths: '409': description: video is already mirrored - /server/redundancy/videos/{redundancyId}: + /api/v1/server/redundancy/videos/{redundancyId}: delete: tags: - Video Mirroring @@ -3871,254 +5058,75 @@ paths: '404': description: video redundancy not found - '/feeds/video-comments.{format}': - get: - tags: - - Feeds - summary: List comments on videos - operationId: getSyndicatedComments - 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}': + /api/v1/server/stats: get: tags: - - Feeds - summary: List videos - operationId: getSyndicatedVideos - 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' + - Stats + summary: Get instance stats + description: Get instance public statistics. This endpoint is cached. + operationId: getInstanceStats responses: - '204': + '200': 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 - operationId: getSyndicatedSubscriptionVideos - 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' + content: + application/json: + schema: + $ref: '#/components/schemas/ServerStats' + + /api/v1/server/logs/client: + post: + tags: + - Logs + summary: Send client log + operationId: sendClientLog + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SendClientLog' responses: '204': description: successful operation - headers: - Cache-Control: - schema: - type: string - default: 'max-age=900' # 15 min cache + + /api/v1/server/logs: + get: + tags: + - Logs + summary: Get instance logs + operationId: getInstanceLogs + security: + - OAuth2: + - admin + responses: + '200': + description: successful operation 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: + application/json: schema: - $ref: '#/components/schemas/VideosForXML' + type: array + items: + type: string + + /api/v1/server/audit-logs: + get: + tags: + - Logs + summary: Get instance audit logs + operationId: getInstanceAuditLogs + security: + - OAuth2: + - admin + responses: + '200': + description: successful operation + content: application/json: schema: - type: object - '406': - description: accept header unsupported + type: array + items: + type: string - /plugins: + /api/v1/plugins: get: tags: - Plugins @@ -4147,7 +5155,7 @@ paths: schema: $ref: '#/components/schemas/PluginResponse' - /plugins/available: + /api/v1/plugins/available: get: tags: - Plugins @@ -4182,7 +5190,7 @@ paths: '503': description: plugin index unavailable - /plugins/install: + /api/v1/plugins/install: post: tags: - Plugins @@ -4217,7 +5225,7 @@ paths: '400': description: should have either `npmName` or `path` set - /plugins/update: + /api/v1/plugins/update: post: tags: - Plugins @@ -4254,7 +5262,7 @@ paths: '404': description: existing plugin not found - /plugins/uninstall: + /api/v1/plugins/uninstall: post: tags: - Plugins @@ -4281,7 +5289,7 @@ paths: '404': description: existing plugin not found - /plugins/{npmName}: + /api/v1/plugins/{npmName}: get: tags: - Plugins @@ -4302,7 +5310,7 @@ paths: '404': description: plugin not found - /plugins/{npmName}/settings: + /api/v1/plugins/{npmName}/settings: put: tags: - Plugins @@ -4327,7 +5335,7 @@ paths: '404': description: plugin not found - /plugins/{npmName}/public-settings: + /api/v1/plugins/{npmName}/public-settings: get: tags: - Plugins @@ -4345,7 +5353,7 @@ paths: '404': description: plugin not found - /plugins/{npmName}/registered-settings: + /api/v1/plugins/{npmName}/registered-settings: get: tags: - Plugins @@ -4366,12 +5374,27 @@ paths: '404': description: plugin not found + /api/v1/metrics/playback: + post: + summary: Create playback metrics + description: These metrics are exposed by OpenTelemetry metrics exporter if enabled. + tags: + - Stats + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PlaybackMetricCreate' + responses: + '204': + description: successful operation + servers: - - url: 'https://peertube2.cpy.re/api/v1' + - url: 'https://peertube2.cpy.re' description: Live Test Server (live data - latest nightly version) - - url: 'https://peertube3.cpy.re/api/v1' + - url: 'https://peertube3.cpy.re' description: Live Test Server (live data - latest RC version) - - url: 'https://peertube.cpy.re/api/v1' + - url: 'https://peertube.cpy.re' description: Live Test Server (live data - stable version) components: parameters: @@ -4432,23 +5455,31 @@ components: name: sort in: query required: false - description: Sort videos by criteria schema: type: string enum: - - name - - -duration - - -createdAt - - -publishedAt - - -views - - -likes - - -trending - - -hot + - name + - -duration + - -createdAt + - -publishedAt + - -views + - -likes + - -trending + - -hot + - -best + description: > + Sort videos by criteria (prefixing with `-` means `DESC` order): + * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date + * `best` - Same than `hot`, but also takes into account user video history + * `trending` - Sort videos by recent views ("recent" is defined by the admin) + * `views` - Sort videos using their `views` counter + * `publishedAt` - Sort by video publication date (when it became publicly available) videosSearchSort: name: sort in: query required: false - description: Sort videos by criteria + description: > + Sort videos by criteria (prefixing with `-` means `DESC` order): schema: type: string enum: @@ -4530,6 +5561,16 @@ components: type: string enum: - name + followersSort: + name: sort + in: query + required: false + description: Sort followers by criteria + schema: + type: string + enum: + - createdAt + name: name: name in: path @@ -4542,7 +5583,14 @@ components: name: id in: path required: true - description: The user id + description: Entity id + schema: + $ref: '#/components/schemas/id' + registrationId: + name: registrationId + in: path + required: true + description: Registration ID schema: $ref: '#/components/schemas/id' idOrUUID: @@ -4598,6 +5646,13 @@ components: schema: type: string example: my_username | my_username@example.com + channelSyncId: + name: channelSyncId + in: path + required: true + description: Channel Sync id + schema: + $ref: '#/components/schemas/Abuse/properties/id' subscriptionHandle: name: subscriptionHandle in: path @@ -4714,20 +5769,66 @@ components: enum: - 'true' - 'false' - filter: - name: filter + isLocal: + name: isLocal in: query required: false - description: > - 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 + type: boolean + description: '**PeerTube >= 4.0** Display only local or remote videos' + hasHLSFiles: + name: hasHLSFiles + in: query + required: false + schema: + type: boolean + description: '**PeerTube >= 4.0** Display only videos that have HLS files' + hasWebtorrentFiles: + name: hasWebtorrentFiles + in: query + required: false + schema: + type: boolean + description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files' + privacyOneOf: + name: privacyOneOf + in: query + required: false + schema: + $ref: '#/components/schemas/VideoPrivacySet' + description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies' + uuids: + name: uuids + in: query + required: false + schema: + items: + type: string + description: 'Find videos with specific UUIDs' + include: + name: include + in: query + required: false + schema: + type: integer enum: - - local - - all-local + - 0 + - 1 + - 2 + - 4 + - 8 + description: > + **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator) + + - `0` NONE + + - `1` NOT_PUBLISHED_STATE + + - `2` BLACKLISTED + + - `4` BLOCKED_OWNER + + - `8` FILES subscriptionsUris: name: uris in: query @@ -4762,10 +5863,11 @@ components: - video-transcoding - video-file-import - video-import - - videos-views + - videos-views-stats - activitypub-refresher - video-redundancy - video-live-ending + - video-channel-import followState: name: state in: query @@ -4785,6 +5887,28 @@ components: - Group - Service - Organization + staticFilename: + name: filename + in: path + required: true + description: Filename + schema: + type: string + videoFileToken: + name: videoFileToken + in: query + required: false + description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header. + schema: + type: string + reinjectVideoFileToken: + name: reinjectVideoFileToken + in: query + required: false + description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist + schema: + type: boolean + securitySchemes: OAuth2: description: | @@ -4807,7 +5931,7 @@ components: moderator: Moderator scope user: User scope schemas: - # Resuable core properties + # Reusable core properties id: type: integer minimum: 1 @@ -4921,6 +6045,29 @@ components: label: type: string + BlockStatus: + properties: + accounts: + type: object + additionalProperties: + x-additionalPropertiesName: account + type: object + properties: + blockedByServer: + type: boolean + blockedByUser: + type: boolean + hosts: + type: object + additionalProperties: + x-additionalPropertiesName: host + type: object + properties: + blockedByServer: + type: boolean + blockedByUser: + type: boolean + NSFWPolicy: type: string enum: @@ -4944,6 +6091,14 @@ components: description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)' example: 1 + LiveVideoLatencyMode: + type: integer + enum: + - 1 + - 2 + - 3 + description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)' + VideoStateConstant: properties: id: @@ -4952,7 +6107,23 @@ components: - 1 - 2 - 3 - description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)' + - 4 + - 5 + - 6 + - 7 + - 8 + - 9 + description: | + The video state: + - `1`: Published + - `2`: To transcode + - `3`: To import + - `4`: Waiting for live stream + - `5`: Live ended + - `6`: To move to an external storage (object storage...) + - `7`: Transcoding failed + - `8`: Moving to an external storage failed + - `9`: To edit using studio edition feature label: type: string @@ -5023,10 +6194,10 @@ components: host: type: string format: hostname - avatar: - nullable: true - allOf: - - $ref: '#/components/schemas/ActorImage' + avatars: + type: array + items: + $ref: '#/components/schemas/ActorImage' VideoChannelSummary: properties: id: @@ -5041,10 +6212,10 @@ components: host: type: string format: hostname - avatar: - nullable: true - allOf: - - $ref: '#/components/schemas/ActorImage' + avatars: + type: array + items: + $ref: '#/components/schemas/ActorImage' PlaylistElement: properties: position: @@ -5062,11 +6233,12 @@ components: VideoFile: readOnly: true properties: + id: + $ref: '#/components/schemas/id' magnetUri: type: string format: uri description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file - 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 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i resolution: $ref: '#/components/schemas/VideoResolutionConstant' @@ -5268,6 +6440,9 @@ components: - $ref: '#/components/schemas/Video' - type: object properties: + viewers: + type: integer + description: If the video is a live, you have the amount of current viewers descriptionPath: type: string example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description @@ -5416,7 +6591,6 @@ components: type: string format: uri description: magnet URI allowing to resolve the import's source video - 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 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i torrentfile: writeOnly: true @@ -5623,10 +6797,16 @@ components: $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string + VideoSource: + properties: + filename: + type: string ActorImage: properties: path: type: string + width: + type: integer createdAt: type: string format: date-time @@ -5644,12 +6824,10 @@ components: host: type: string format: hostname - avatar: - nullable: true - type: object - properties: - path: - type: string + avatars: + type: array + items: + $ref: '#/components/schemas/ActorImage' Actor: properties: id: @@ -5682,8 +6860,6 @@ components: updatedAt: type: string format: date-time - avatar: - $ref: '#/components/schemas/ActorImage' Account: allOf: - $ref: '#/components/schemas/Actor' @@ -5700,13 +6876,68 @@ components: description: type: string description: text or bio displayed on the account's profile - UserWatchingVideo: + UserViewingVideo: + required: + - currentTime properties: currentTime: type: integer format: seconds description: timestamp within the video, in seconds example: 5 + viewEvent: + type: string + enum: + - seek + description: > + Event since last viewing call: + * `seek` - If the user seeked the video + + VideoStatsOverall: + properties: + averageWatchTime: + type: number + totalWatchTime: + type: number + viewersPeak: + type: number + viewersPeakDate: + type: string + format: date-time + countries: + type: array + items: + type: object + properties: + isoCode: + type: string + viewers: + type: number + + VideoStatsRetention: + properties: + data: + type: array + items: + type: object + properties: + second: + type: number + retentionPercent: + type: number + + VideoStatsTimeserie: + properties: + data: + type: array + items: + type: object + properties: + date: + type: string + value: + type: number + ServerConfig: properties: instance: @@ -5809,6 +7040,11 @@ components: properties: enabled: type: boolean + videoChannelSynchronization: + type: object + properties: + enabled: + type: boolean autoBlacklist: type: object properties: @@ -5912,6 +7148,96 @@ components: enabled: type: boolean + SendClientLog: + properties: + message: + type: string + url: + type: string + description: URL of the current user page + level: + enum: + - error + - warn + stackTrace: + type: string + description: Stack trace of the error if there is one + userAgent: + type: string + description: User agent of the web browser that sends the message + meta: + type: string + description: Additional information regarding this log + required: + - message + - url + - level + + ServerStats: + properties: + totalUsers: + type: number + totalDailyActiveUsers: + type: number + totalWeeklyActiveUsers: + type: number + totalMonthlyActiveUsers: + type: number + totalLocalVideos: + type: number + totalLocalVideoViews: + type: number + description: Total video views made on the instance + totalLocalVideoComments: + type: number + description: Total comments made by local users + totalLocalVideoFilesSize: + type: number + totalVideos: + type: number + totalVideoComments: + type: number + totalLocalVideoChannels: + type: number + totalLocalDailyActiveVideoChannels: + type: number + totalLocalWeeklyActiveVideoChannels: + type: number + totalLocalMonthlyActiveVideoChannels: + type: number + totalLocalPlaylists: + type: number + totalInstanceFollowers: + type: number + totalInstanceFollowing: + type: number + videosRedundancy: + type: array + items: + type: object + properties: + strategy: + type: string + totalSize: + type: number + totalUsed: + type: number + totalVideoFiles: + type: number + totalVideos: + type: number + totalActivityPubMessagesProcessed: + type: number + totalActivityPubMessagesSuccesses: + type: number + totalActivityPubMessagesErrors: + type: number + + activityPubMessagesProcessedPerSecond: + type: number + totalActivityPubMessagesWaiting: + type: number + ServerConfigAbout: properties: instance: @@ -6039,6 +7365,8 @@ components: properties: 0p: type: boolean + 144p: + type: boolean 240p: type: boolean 360p: @@ -6081,6 +7409,11 @@ components: properties: enabled: type: boolean + video_channel_synchronization: + type: object + properties: + enabled: + type: boolean autoBlacklist: type: object properties: @@ -6170,9 +7503,10 @@ components: - video-transcoding - email - video-import - - videos-views + - videos-views-stats - activitypub-refresher - video-redundancy + - video-channel-import data: type: object additionalProperties: true @@ -6328,6 +7662,16 @@ components: properties: comment: $ref: '#/components/schemas/VideoComment' + VideoTokenResponse: + properties: + files: + type: object + properties: + token: + type: string + expires: + type: string + format: date-time VideoListResponse: properties: total: @@ -6376,18 +7720,23 @@ components: format: date-time noInstanceConfigWarningModal: type: boolean + noAccountSetupWarningModal: + type: boolean noWelcomeModal: type: boolean nsfwPolicy: $ref: '#/components/schemas/NSFWPolicy' role: - $ref: '#/components/schemas/UserRole' - roleLabel: - type: string - enum: - - User - - Moderator - - Administrator + type: object + properties: + id: + $ref: '#/components/schemas/UserRole' + label: + type: string + enum: + - User + - Moderator + - Administrator theme: type: string description: Theme enabled by this user @@ -6405,7 +7754,7 @@ components: type: integer description: The user daily video quota in bytes example: -1 - webtorrentEnabled: + p2pEnabled: type: boolean description: Enable P2P in the player UserWithStats: @@ -6483,6 +7832,8 @@ components: $ref: '#/components/schemas/UserRole' adminFlags: $ref: '#/components/schemas/UserAdminFlags' + password: + $ref: '#/components/schemas/password' UpdateMe: # see shared/models/users/user-update-me.model.ts: properties: @@ -6506,7 +7857,7 @@ components: - 'true' - 'false' - both - webTorrentEnabled: + p2pEnabled: type: boolean description: whether to enable P2P in the player or not autoPlayVideo: @@ -6530,6 +7881,8 @@ components: type: string noInstanceConfigWarningModal: type: boolean + noAccountSetupWarningModal: + type: boolean noWelcomeModal: type: boolean GetMeVideoRating: @@ -6560,6 +7913,7 @@ components: required: - video - rating + RegisterUser: properties: username: @@ -6584,12 +7938,83 @@ components: name: $ref: '#/components/schemas/usernameChannel' displayName: - $ref: '#/components/schemas/VideoChannel/properties/displayName' + type: string required: - username - password - email + UserRegistrationRequest: + allOf: + - $ref: '#/components/schemas/RegisterUser' + - type: object + properties: + registrationReason: + type: string + description: reason for the user to register on the instance + required: + - registrationReason + + UserRegistrationAcceptOrReject: + type: object + properties: + moderationResponse: + type: string + description: Moderation response to send to the user + preventEmailDelivery: + type: boolean + description: Set it to true if you don't want PeerTube to send an email to the user + required: + - moderationResponse + + UserRegistration: + properties: + id: + $ref: '#/components/schemas/id' + state: + type: object + properties: + id: + type: integer + enum: + - 1 + - 2 + - 3 + description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)' + label: + type: string + registrationReason: + type: string + moderationResponse: + type: string + nullable: true + username: + type: string + email: + type: string + format: email + emailVerified: + type: boolean + accountDisplayName: + type: string + channelHandle: + type: string + channelDisplayName: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + user: + type: object + nullable: true + description: If the registration has been accepted, this is a partial user object created by the registration + properties: + id: + $ref: '#/components/schemas/id' + OAuthClient: properties: client_id: @@ -6646,46 +8071,48 @@ components: - refresh_token VideoChannel: - properties: - # GET/POST/PUT properties - displayName: - type: string - description: editable name of the channel, displayed in its representations - example: Videos of Framasoft - minLength: 1 - maxLength: 120 - description: - type: string - example: Videos made with <3 by Framasoft - minLength: 3 - maxLength: 1000 - support: - type: string - description: text shown by default on all videos of this channel, to tell the audience how to support it - example: Please support our work on https://soutenir.framasoft.org/en/ <3 - minLength: 3 - maxLength: 1000 - # GET-only properties - id: - readOnly: true - allOf: - - $ref: '#/components/schemas/id' - isLocal: - readOnly: true - type: boolean - updatedAt: - readOnly: true - type: string - format: date-time - ownerAccount: - readOnly: true - nullable: true - type: object + allOf: + - $ref: '#/components/schemas/Actor' + - type: object properties: - id: - type: integer - uuid: - $ref: '#/components/schemas/UUIDv4' + displayName: + type: string + description: editable name of the channel, displayed in its representations + example: Videos of Framasoft + minLength: 1 + maxLength: 120 + description: + type: string + example: Videos made with <3 by Framasoft + minLength: 3 + maxLength: 1000 + support: + type: string + description: text shown by default on all videos of this channel, to tell the audience how to support it + example: Please support our work on https://soutenir.framasoft.org/en/ <3 + minLength: 3 + maxLength: 1000 + isLocal: + readOnly: true + type: boolean + updatedAt: + readOnly: true + type: string + format: date-time + banners: + type: array + items: + $ref: '#/components/schemas/ActorImage' + ownerAccount: + readOnly: true + nullable: true + type: object + properties: + id: + type: integer + uuid: + $ref: '#/components/schemas/UUIDv4' + VideoChannelCreate: allOf: - $ref: '#/components/schemas/VideoChannel' @@ -6716,6 +8143,63 @@ components: - $ref: '#/components/schemas/VideoChannel' - $ref: '#/components/schemas/Actor' + ImportVideosInChannelCreate: + type: object + properties: + externalChannelUrl: + type: string + example: https://youtube.com/c/UC_myfancychannel + videoChannelSyncId: + type: integer + description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization + required: + - 'externalChannelUrl' + + VideoChannelSync: + type: object + properties: + id: + $ref: '#/components/schemas/id' + state: + type: object + properties: + id: + type: integer + example: 2 + label: + type: string + example: PROCESSING + externalChannelUrl: + type: string + example: 'https://youtube.com/c/UC_myfancychannel' + createdAt: + type: string + format: date-time + lastSyncAt: + type: string + format: date-time + nullable: true + channel: + $ref: '#/components/schemas/VideoChannel' + VideoChannelSyncList: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + allOf: + - $ref: '#/components/schemas/VideoChannelSync' + VideoChannelSyncCreate: + type: object + properties: + externalChannelUrl: + type: string + example: https://youtube.com/c/UC_myfancychannel + videoChannelId: + $ref: '#/components/schemas/id' MRSSPeerLink: type: object xml: @@ -6905,17 +8389,13 @@ components: NotificationSettingValue: type: integer description: > - Notification type + Notification type. One of the following values, or a sum of multiple values: - `0` NONE - `1` WEB - `2` EMAIL - enum: - - 0 - - 1 - - 3 Notification: properties: id: @@ -6952,6 +8432,14 @@ components: - `13` NEW_INSTANCE_FOLLOWER - `14` AUTO_INSTANCE_FOLLOWING + + - `15` ABUSE_STATE_CHANGE + + - `16` ABUSE_NEW_MESSAGE + + - `17` NEW_PLUGIN_VERSION + + - `18` NEW_PEERTUBE_VERSION read: type: boolean video: @@ -7119,21 +8607,188 @@ components: permanentLive: description: User can stream multiple times in a permanent live type: boolean + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' LiveVideoResponse: properties: rtmpUrl: type: string + description: Included in the response if an appropriate token is provided + rtmpsUrl: + type: string + description: Included in the response if an appropriate token is provided streamKey: type: string - description: RTMP stream key to use to stream into this live video + description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided saveReplay: type: boolean permanentLive: description: User can stream multiple times in a permanent live type: boolean + latencyMode: + description: User can select live latency mode if enabled by the instance + $ref: '#/components/schemas/LiveVideoLatencyMode' + + RequestTwoFactorResponse: + properties: + otpRequest: + type: object + properties: + requestToken: + type: string + description: The token to send to confirm this request + secret: + type: string + description: The OTP secret + uri: + type: string + description: The OTP URI + + VideoStudioCreateTask: + type: array + items: + anyOf: + - + title: cut + type: object + properties: + name: + type: string + enum: + - 'cut' + options: + type: object + properties: + start: + type: integer + end: + type: integer + - + title: add-intro + type: object + properties: + name: + type: string + enum: + - 'add-intro' + options: + type: object + properties: + file: + type: string + format: binary + - + title: add-outro + type: object + properties: + name: + type: string + enum: + - 'add-outro' + options: + type: object + properties: + file: + type: string + format: binary + - + title: add-watermark + type: object + properties: + name: + type: string + enum: + - 'add-watermark' + options: + type: object + properties: + file: + type: string + format: binary + LiveVideoSessionResponse: + properties: + id: + type: integer + startDate: + type: string + format: date-time + description: Start date of the live session + endDate: + type: string + format: date-time + nullable: true + description: End date of the live session + error: + type: integer + enum: + - 1 + - 2 + - 3 + - 4 + - 5 + nullable: true + description: > + Error type if an error occurred during the live session: + - `1`: Bad socket health (transcoding is too slow) + - `2`: Max duration exceeded + - `3`: Quota exceeded + - `4`: Quota FFmpeg error + - `5`: Video has been blacklisted during the live + replayVideo: + type: object + description: Video replay information + properties: + id: + type: number + uuid: + $ref: '#/components/schemas/UUIDv4' + shortUUID: + $ref: '#/components/schemas/shortUUID' + PlaybackMetricCreate: + properties: + playerMode: + type: string + enum: + - 'p2p-media-loader' + - 'webtorrent' + resolution: + type: number + description: Current player video resolution + fps: + type: number + description: Current player video fps + resolutionChanges: + type: number + description: How many resolution changes occured since the last metric creation + errors: + type: number + description: How many errors occured since the last metric creation + downloadedBytesP2P: + type: number + description: How many bytes were downloaded with P2P since the last metric creation + downloadedBytesHTTP: + type: number + description: How many bytes were downloaded with HTTP since the last metric creation + uploadedBytesP2P: + type: number + description: How many bytes were uploaded with P2P since the last metric creation + videoId: + oneOf: + - $ref: '#/components/schemas/id' + - $ref: '#/components/schemas/UUIDv4' + - $ref: '#/components/schemas/shortUUID' + required: + - playerMode + - resolutionChanges + - errors + - downloadedBytesP2P + - downloadedBytesHTTP + - uploadedBytesP2P + - videoId callbacks: searchIndex: