X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=support%2Fdoc%2Fapi%2Fopenapi.yaml;h=407f3eb10f0e6f1c780548083a36aa797761469c;hb=bfbdfc584a4f0cd078fc159b2eb59e872873f592;hp=f54df1dd0954da03c74972feed6c273a44b690ea;hpb=e2464d22a5f19168022e72c77e82019726216542;p=github%2FChocobozzz%2FPeerTube.git diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml index f54df1dd0..407f3eb10 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.2.0-rc.1 + version: 4.0.0 contact: name: PeerTube Community url: https://joinpeertube.org @@ -22,7 +22,7 @@ info: - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few - examples of using with the PeerTube API. + examples of using the PeerTube API. # Authentication @@ -38,30 +38,79 @@ info: # Errors The API uses standard HTTP status codes to indicate the success or failure - of the API call. The body of the response will be JSON in the following - formats. + of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body. ``` + HTTP 1.1 404 Not Found + Content-Type: application/problem+json; charset=utf-8 + + { + "detail": "Video not found", + "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo", + "status": 404, + "title": "Not Found", + "type": "about:blank" + } + ``` + + We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts), + but it is still optional. Types are used to disambiguate errors that bear the same status code + and are non-obvious: + + ``` + HTTP 1.1 403 Forbidden + Content-Type: application/problem+json; charset=utf-8 + { - "error": "Account not found" // error debug message + "detail": "Cannot get this video regarding follow constraints", + "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo", + "status": 403, + "title": "Forbidden", + "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints" } ``` - Validation errors benefit from a more detailed error type and return the HTTP `400 Bad Request` status code. + Here a 403 error could otherwise mean that the video is private or blocklisted. + + ### Validation errors + + Each parameter is evaluated on its own against a set of rules before the route validator + proceeds with potential testing involving parameter combinations. Errors coming from validation + errors appear earlier and benefit from a more detailed error description: ``` + HTTP 1.1 400 Bad Request + Content-Type: application/problem+json; charset=utf-8 + { - "errors": { - "id": { // where 'id' is the name of the parameter concerned by the error. - "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error. - "msg": "Should have an valid id", // error debug message + "detail": "Incorrect request parameters: id", + "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo", + "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180", + "invalid-params": { + "id": { + "location": "params", + "msg": "Invalid value", "param": "id", - "location": "params" // 'params', 'body', 'header', 'query' or 'cookies' + "value": "9c9de5e8-0a1e-484a-b099-e80766180" } - } + }, + "status": 400, + "title": "Bad Request", + "type": "about:blank" } ``` + Where `id` is the name of the field concerned by the error, within the route definition. + `invalid-params..location` can be either 'params', 'body', 'header', 'query' or 'cookies', and + `invalid-params..value` reports the value that didn't pass validation whose `invalid-params..msg` + is about. + + ### Deprecated error fields + + Some fields could be included with previous versions. They are still included but their use is deprecated: + - `error`: superseded by `detail` + - `code`: superseded by `type` (which is now an URI) + # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: @@ -90,7 +139,7 @@ info: This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/), allowing cross-domain communication from the browser for some routes: - + | Endpoint | |------------------------- ---| | `/api/*` | @@ -106,8 +155,8 @@ tags: - name: Register description: | As a visitor, you can use this API to open an account (if registrations are open on - that PeerTube instance). As an admin, you should use the dedicated [User creation - API](#operation/createUser) instead. + that PeerTube instance). As an admin, you should use the dedicated [User creation + API](#operation/addUser) instead. - name: Session x-displayName: Login/Logout description: | @@ -203,6 +252,8 @@ tags: 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: Video Captions description: Operations dealing with listing, adding and removing closed captions of a video. - name: Video Channels @@ -218,6 +269,12 @@ 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: Video Files + description: Operations on video files + - name: Video Transcoding + description: Video transcoding related operations + - name: Video stats + description: Video statistics - name: Feeds description: Server syndication feeds - name: Search @@ -229,6 +286,8 @@ tags: Administrators can also enable the use of a remote search system, indexing videos and channels not could be not federated by the instance. + - name: Homepage + description: Get and update the custom homepage - name: Video Mirroring description: | PeerTube instances can mirror videos from one another, and help distribute some videos. @@ -251,18 +310,25 @@ 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 - name: Search tags: - Search + - name: Custom pages + tags: + - Homepage - name: Moderation tags: - Abuses @@ -284,6 +350,7 @@ paths: tags: - Accounts summary: Get an account + operationId: getAccount parameters: - $ref: '#/components/parameters/name' responses: @@ -295,12 +362,14 @@ paths: $ref: '#/components/schemas/Account' '404': description: account not found + '/accounts/{name}/videos': get: tags: - Accounts - Video summary: 'List videos of an account' + operationId: getAccountVideos parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/categoryOneOf' @@ -310,7 +379,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' @@ -356,11 +429,43 @@ paths: json = r.json() print(json) + + '/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' + /accounts: get: tags: - Accounts summary: List accounts + operationId: getAccounts parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' @@ -374,11 +479,13 @@ paths: type: array items: $ref: '#/components/schemas/Account' + /config: get: tags: - Config summary: Get instance public configuration + operationId: getConfig responses: '200': description: successful operation @@ -389,9 +496,11 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/config + /config/about: get: summary: Get instance "About" information + operationId: getAbout tags: - Config responses: @@ -404,9 +513,11 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/config/about + /config/custom: get: summary: Get instance runtime configuration + operationId: getCustomConfig tags: - Config security: @@ -421,6 +532,7 @@ paths: $ref: '#/components/schemas/ServerConfigCustom' put: summary: Set instance runtime configuration + operationId: putCustomConfig tags: - Config security: @@ -437,6 +549,7 @@ paths: - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled delete: summary: Delete instance runtime configuration + operationId: delCustomConfig tags: - Config security: @@ -445,9 +558,69 @@ paths: responses: '200': description: successful operation + + /custom-pages/homepage/instance: + get: + summary: Get instance custom homepage + tags: + - Homepage + responses: + '404': + description: No homepage set + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/CustomHomepage' + put: + summary: Set instance custom homepage + tags: + - Homepage + security: + - OAuth2: + - admin + requestBody: + content: + application/json: + schema: + type: object + properties: + content: + type: string + description: content of the homepage, that will be injected in the client + responses: + '204': + description: successful operation + + /jobs/pause: + post: + summary: Pause job queue + security: + - OAuth2: + - admin + tags: + - Job + responses: + '204': + description: successful operation + + /jobs/resume: + post: + summary: Resume job queue + security: + - OAuth2: + - admin + tags: + - Job + responses: + '204': + description: successful operation + /jobs/{state}: get: summary: List instance jobs + operationId: getJobs security: - OAuth2: - admin @@ -487,66 +660,108 @@ paths: maxItems: 100 items: $ref: '#/components/schemas/Job' - '/server/following/{host}': + + /server/followers: + get: + tags: + - Instance Follows + summary: List instances following the server + parameters: + - $ref: '#/components/parameters/followState' + - $ref: '#/components/parameters/actorType' + - $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/Follow' + + '/server/followers/{nameWithHost}': delete: + summary: Remove or reject a follower to your server security: - OAuth2: - admin tags: - Instance Follows - summary: Unfollow a server parameters: - - name: host + - name: nameWithHost in: path required: true - description: 'The host to unfollow ' + description: The remote actor handle to remove from your followers schema: type: string - format: hostname + format: email responses: - '201': + '204': description: successful operation - /server/followers: - get: + '404': + description: follower not found + + '/server/followers/{nameWithHost}/reject': + post: + summary: Reject a pending follower to your server + security: + - OAuth2: + - admin tags: - Instance Follows - summary: List instance followers parameters: - - $ref: '#/components/parameters/start' - - $ref: '#/components/parameters/count' - - $ref: '#/components/parameters/sort' + - name: nameWithHost + in: path + required: true + description: The remote actor handle to remove from your followers + schema: + type: string + format: email responses: - '200': + '204': description: successful operation - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Follow' + '404': + description: follower not found + + '/server/followers/{nameWithHost}/accept': + post: + summary: Accept a pending follower to your server + security: + - OAuth2: + - admin + tags: + - Instance Follows + parameters: + - name: nameWithHost + in: path + required: true + description: The remote actor handle to remove from your followers + schema: + type: string + format: email + responses: + '204': + description: successful operation + '404': + description: follower not found + /server/following: get: tags: - Instance Follows 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/followState' + - $ref: '#/components/parameters/actorType' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' @@ -556,16 +771,22 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/Follow' + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/Follow' post: security: - OAuth2: - admin tags: - Instance Follows - summary: Follow a server + summary: Follow a list of actors (PeerTube instance, channel or account) responses: '204': description: successful operation @@ -583,10 +804,37 @@ paths: type: string format: hostname uniqueItems: true + handles: + type: array + items: + type: string + uniqueItems: true + + '/server/following/{hostOrHandle}': + delete: + summary: Unfollow an actor (PeerTube instance, channel or account) + security: + - OAuth2: + - admin + tags: + - Instance Follows + parameters: + - name: hostOrHandle + in: path + required: true + description: The hostOrHandle to unfollow + schema: + type: string + responses: + '204': + description: successful operation + '404': + description: host or handle not found + /users: post: summary: Create a user - operationId: createUser + operationId: addUser security: - OAuth2: - admin @@ -601,18 +849,18 @@ paths: $ref: '#/components/schemas/AddUserResponse' links: # GET /users/{id} - GetUserId: - operationId: getUserId + GetUser: + operationId: getUser parameters: id: '$response.body#/user/id' # PUT /users/{id} - PutUserId: - operationId: putUserId + PutUser: + operationId: putUser parameters: id: '$response.body#/user/id' # DELETE /users/{id} - DelUserId: - operationId: delUserId + DelUser: + operationId: delUser parameters: id: '$response.body#/user/id' '403': @@ -628,6 +876,7 @@ paths: required: true get: summary: List users + operationId: getUsers security: - OAuth2: - admin @@ -648,6 +897,7 @@ paths: type: array items: $ref: '#/components/schemas/User' + '/users/{id}': parameters: - $ref: '#/components/parameters/id' @@ -658,7 +908,7 @@ paths: - admin tags: - Users - operationId: delUserId + operationId: delUser responses: '204': description: successful operation @@ -668,7 +918,7 @@ paths: - OAuth2: [] tags: - Users - operationId: getUserId + operationId: getUser parameters: - name: withStats in: query @@ -693,7 +943,7 @@ paths: - OAuth2: [] tags: - Users - operationId: putUserId + operationId: putUser responses: '204': description: successful operation @@ -707,7 +957,7 @@ paths: /oauth-clients/local: get: summary: Login prerequisite - description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken). + description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken). operationId: getOAuthClient tags: - Session @@ -724,6 +974,14 @@ paths: parameters: client_id: '$response.body#/client_id' client_secret: '$response.body#/client_secret' + x-codeSamples: + - lang: Shell + source: | + API="https://peertube2.cpy.re/api/v1" + + ## AUTH + curl -s "$API/oauth-clients/local" + /users/token: post: summary: Login @@ -770,6 +1028,37 @@ paths: type: integer minimum: 0 example: 1209600 + '400': + x-summary: client or credentials are invalid + description: | + Disambiguate via `type`: + - `invalid_client` for an unmatched `client_id` + - `invalid_grant` for unmatched credentials + '401': + x-summary: token expired + description: | + Disambiguate via `type`: + - default value for a regular authentication failure + - `invalid_token` for an expired token + x-codeSamples: + - lang: Shell + source: | + ## DEPENDENCIES: jq + API="https://peertube2.cpy.re/api/v1" + USERNAME="" + PASSWORD="" + + ## AUTH + client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id") + client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret") + curl -s "$API/users/token" \ + --data client_id="$client_id" \ + --data client_secret="$client_secret" \ + --data grant_type=password \ + --data username="$USERNAME" \ + --data password="$PASSWORD" \ + | jq -r ".access_token" + /users/revoke-token: post: summary: Logout @@ -786,6 +1075,7 @@ paths: /users/register: post: summary: Register a user + operationId: registerUser tags: - Users - Register @@ -798,12 +1088,14 @@ paths: schema: $ref: '#/components/schemas/RegisterUser' required: true + /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. + containing a secret. tags: - Users - Register @@ -829,9 +1121,11 @@ paths: description: invalid verification string '404': description: user not found + /users/ask-send-verify-email: post: summary: Resend user verification link + operationId: resendEmailToVerifyUser tags: - Users - Register @@ -842,6 +1136,7 @@ paths: /users/me: get: summary: Get my user information + operationId: getUserInfo security: - OAuth2: - user @@ -858,6 +1153,7 @@ paths: $ref: '#/components/schemas/User' put: summary: Update my user information + operationId: putUserInfo security: - OAuth2: - user @@ -872,6 +1168,7 @@ paths: schema: $ref: '#/components/schemas/UpdateMe' required: true + /users/me/videos/imports: get: summary: Get video imports of my user @@ -892,6 +1189,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoImportsList' + /users/me/video-quota-used: get: summary: Get my user used quota @@ -916,6 +1214,7 @@ paths: type: number description: The user video quota used today in bytes example: 1681014151 + '/users/me/videos/{videoId}/rating': get: summary: Get rate of my user for a video @@ -938,6 +1237,7 @@ paths: application/json: schema: $ref: '#/components/schemas/GetMeVideoRating' + /users/me/videos: get: summary: Get videos of my user @@ -958,6 +1258,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + /users/me/subscriptions: get: summary: Get my user subscriptions @@ -1003,6 +1304,7 @@ paths: responses: '200': description: successful operation + /users/me/subscriptions/exist: get: summary: Get if subscriptions exist for my user @@ -1020,6 +1322,7 @@ paths: application/json: schema: type: object + /users/me/subscriptions/videos: get: summary: List videos of subscriptions of my user @@ -1037,7 +1340,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' @@ -1049,6 +1356,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + '/users/me/subscriptions/{subscriptionHandle}': get: summary: Get subscription of my user @@ -1078,6 +1386,7 @@ paths: responses: '200': description: successful operation + /users/me/notifications: get: summary: List my notifications @@ -1101,6 +1410,7 @@ paths: application/json: schema: $ref: '#/components/schemas/NotificationListResponse' + /users/me/notifications/read: post: summary: Mark notifications as read by their id @@ -1124,6 +1434,7 @@ paths: responses: '204': description: successful operation + /users/me/notifications/read-all: post: summary: Mark all my notification as read @@ -1134,6 +1445,7 @@ paths: responses: '204': description: successful operation + /users/me/notification-settings: put: summary: Update my notification settings @@ -1174,6 +1486,7 @@ paths: responses: '204': description: successful operation + /users/me/history/videos: get: summary: List watched videos history @@ -1192,6 +1505,24 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + + /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 + /users/me/history/videos/remove: post: summary: Clear video history @@ -1212,6 +1543,7 @@ paths: responses: '204': description: successful operation + /users/me/avatar/pick: post: summary: Update my user avatar @@ -1227,8 +1559,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: @@ -1250,6 +1584,7 @@ paths: encoding: avatarfile: contentType: image/png, image/jpeg + /users/me/avatar: delete: summary: Delete my avatar @@ -1271,6 +1606,7 @@ paths: responses: '200': description: successful operation + '/videos/ownership/{id}/accept': post: summary: Accept ownership change request @@ -1286,7 +1622,8 @@ 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': post: summary: Refuse ownership change request @@ -1302,7 +1639,8 @@ 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': post: summary: Request ownership change @@ -1330,9 +1668,11 @@ paths: description: changing video ownership to a remote account is not supported yet '404': description: video not found + /videos: get: summary: List videos + operationId: getVideos tags: - Video parameters: @@ -1343,7 +1683,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' @@ -1355,6 +1699,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + /videos/categories: get: summary: List available video categories @@ -1373,6 +1718,7 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/categories + /videos/licences: get: summary: List available video licences @@ -1391,6 +1737,7 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/licences + /videos/languages: get: summary: List available video languages @@ -1409,6 +1756,7 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/languages + /videos/privacies: get: summary: List available video privacy policies @@ -1427,9 +1775,11 @@ paths: examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/privacies + '/videos/{id}': put: summary: Update a video + operationId: putVideo security: - OAuth2: [] tags: @@ -1491,6 +1841,9 @@ paths: 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 @@ -1504,6 +1857,7 @@ paths: contentType: image/jpeg get: summary: Get a video + operationId: getVideo tags: - Video parameters: @@ -1517,6 +1871,7 @@ paths: $ref: '#/components/schemas/VideoDetails' delete: summary: Delete a video + operationId: delVideo security: - OAuth2: [] tags: @@ -1526,9 +1881,11 @@ paths: responses: '204': description: successful operation + '/videos/{id}/description': get: summary: Get complete video description + operationId: getVideoDesc tags: - Video parameters: @@ -1545,34 +1902,108 @@ paths: maxLength: 10000 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 + 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 - '/videos/{id}/watching': - put: - summary: Set watching progress of a video + + '/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 + + '/videos/{id}/stats/overall': + get: + summary: Get overall stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsOverall' + + '/videos/{id}/stats/retention': + get: + summary: Get retention stats of a video + tags: + - Video Stats + security: + - OAuth2: [] + parameters: + - $ref: '#/components/parameters/idOrUUID' + responses: + '200': + description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsRetention' + + '/videos/{id}/stats/timeseries/{metric}': + get: + summary: Get timeserie stats of a video tags: - - Video + - 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' responses: - '204': + '200': description: successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/VideoStatsTimeserie' + /videos/upload: post: summary: Upload a video @@ -1590,14 +2021,15 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' - '400': - description: invalid file field, schedule date or parameter '403': description: video didn't pass upload filter '408': description: upload has timed out '413': - description: video file too large, due to quota or max body size limit set by the reverse-proxy + 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 headers: X-File-Maximum-Size: schema: @@ -1629,26 +2061,27 @@ paths: FILE_PATH="" CHANNEL_ID="" NAME="" + API="https://peertube2.cpy.re/api/v1" - API_PATH="https://peertube2.cpy.re/api/v1" ## AUTH - 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" \ + client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id") + client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret") + token=$(curl -s "$API/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 - curl -s "$API_PATH/videos/upload" \ + curl -s "$API/videos/upload" \ -H "Authorization: Bearer $token" \ --max-time 600 \ --form videofile=@"$FILE_PATH" \ --form channelId=$CHANNEL_ID \ --form name="$NAME" + /videos/upload-resumable: post: summary: Initialize the resumable upload of a video @@ -1695,10 +2128,12 @@ paths: 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 + x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit + description: | + Disambiguate via `type`: + - `max_file_size_reached` for the absolute file size limit + - `quota_reached` for quota limits whether daily or global '415': description: video type unsupported put: @@ -1712,10 +2147,10 @@ paths: - Video Upload parameters: - name: upload_id - in: path + 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 @@ -1739,9 +2174,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: @@ -1774,10 +2206,21 @@ paths: 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 + '404': + description: upload not found + '409': + description: chunk doesn't match range '422': 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 @@ -1789,7 +2232,7 @@ paths: - Video Upload parameters: - name: upload_id - in: path + in: query required: true description: | Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is @@ -1810,6 +2253,9 @@ paths: schema: type: number example: 0 + '404': + description: upload not found + /videos/imports: post: summary: Import a video @@ -1818,7 +2264,7 @@ paths: security: - OAuth2: [] tags: - - Video + - Video Imports - Video Upload requestBody: content: @@ -1846,10 +2292,38 @@ paths: '409': description: HTTP or Torrent/magnetURI import not enabled + /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 + + /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 + /videos/live: post: summary: Create a live - operationId: createLive + operationId: addLive security: - OAuth2: [] tags: @@ -1862,8 +2336,20 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' + '400': + x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set + description: | + Disambiguate via `type`: + - default type for a validation error + - `live_conflicting_permanent_and_save_replay` for conflicting parameters set '403': - description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded + description: | + Disambiguate via `type`: + - `live_not_enabled` for a disabled live feature + - `live_not_allowing_replay` for a disabled replay feature + - `max_instance_lives_limit_reached` for the absolute concurrent live limit + - `max_user_lives_limit_reached` for the user concurrent live limit requestBody: content: multipart/form-data: @@ -1878,6 +2364,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 @@ -1922,7 +2411,7 @@ paths: description: Enable or disable comments for this live video/replay type: boolean downloadEnabled: - description: Enable or disable downloading for the replay of this live + description: Enable or disable downloading for the replay of this live video type: boolean required: - channelId @@ -2064,7 +2553,7 @@ paths: type: string - name: videoIs in: query - description: only list blacklisted or deleted videos + description: only list deleted or blocklisted videos schema: type: string enum: @@ -2097,7 +2586,6 @@ paths: type: array items: $ref: '#/components/schemas/Abuse' - post: summary: Report an abuse security: @@ -2151,10 +2639,21 @@ paths: required: - reason responses: - '204': + '200': description: successful operation + content: + application/json: + schema: + type: object + properties: + abuse: + type: object + properties: + id: + $ref: '#/components/schemas/id' '400': description: incorrect request parameters + '/abuses/{abuseId}': put: summary: Update an abuse @@ -2199,6 +2698,7 @@ paths: description: successful operation '404': description: block not found + '/abuses/{abuseId}/messages': get: summary: List messages of an abuse @@ -2214,10 +2714,15 @@ paths: content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/AbuseMessage' - + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/AbuseMessage' post: summary: Add message to an abuse security: @@ -2245,6 +2750,7 @@ paths: description: successful operation '400': description: incorrect request parameters + '/abuses/{abuseId}/messages/{abuseMessageId}': delete: summary: Delete an abuse message @@ -2262,6 +2768,7 @@ paths: '/videos/{id}/blacklist': post: summary: Block a video + operationId: addVideoBlock security: - OAuth2: - admin @@ -2275,6 +2782,7 @@ paths: description: successful operation delete: summary: Unblock a video by its id + operationId: delVideoBlock security: - OAuth2: - admin @@ -2288,11 +2796,13 @@ paths: description: successful operation '404': description: block not found + /videos/blacklist: get: tags: - Video Blocks summary: List video blocks + operationId: getVideoBlocks security: - OAuth2: - admin @@ -2334,9 +2844,11 @@ paths: type: array items: $ref: '#/components/schemas/VideoBlacklist' + /videos/{id}/captions: get: summary: List captions of a video + operationId: getVideoCaptions tags: - Video Captions parameters: @@ -2356,9 +2868,11 @@ paths: type: array items: $ref: '#/components/schemas/VideoCaption' + /videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption + operationId: addVideoCaption security: - OAuth2: - user @@ -2387,6 +2901,7 @@ paths: description: video or language not found delete: summary: Delete a video caption + operationId: delVideoCaption security: - OAuth2: - user @@ -2400,6 +2915,7 @@ paths: description: successful operation '404': description: video or language or caption for that language not found + /video-channels: get: summary: List video channels @@ -2419,7 +2935,7 @@ paths: $ref: '#/components/schemas/VideoChannelList' post: summary: Create a video channel - operationId: createVideoChannel + operationId: addVideoChannel security: - OAuth2: [] tags: @@ -2436,12 +2952,13 @@ 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}': get: summary: Get a video channel @@ -2459,6 +2976,7 @@ paths: $ref: '#/components/schemas/VideoChannel' put: summary: Update a video channel + operationId: putVideoChannel security: - OAuth2: [] tags: @@ -2475,6 +2993,7 @@ paths: $ref: '#/components/schemas/VideoChannelUpdate' delete: summary: Delete a video channel + operationId: delVideoChannel security: - OAuth2: [] tags: @@ -2484,9 +3003,11 @@ paths: responses: '204': description: successful operation + '/video-channels/{channelHandle}/videos': get: summary: List videos of a video channel + operationId: getVideoChannelVideos tags: - Video - Video Channels @@ -2499,7 +3020,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' @@ -2511,6 +3036,37 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoListResponse' + + '/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' + '/video-channels/{channelHandle}/avatar/pick': post: summary: Update channel avatar @@ -2528,8 +3084,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: @@ -2551,6 +3109,7 @@ paths: encoding: avatarfile: contentType: image/png, image/jpeg + '/video-channels/{channelHandle}/avatar': delete: summary: Delete channel avatar @@ -2564,7 +3123,6 @@ paths: '204': description: successful operation - '/video-channels/{channelHandle}/banner/pick': post: summary: Update channel banner @@ -2582,8 +3140,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: @@ -2605,6 +3165,7 @@ paths: encoding: bannerfile: contentType: image/png, image/jpeg + '/video-channels/{channelHandle}/banner': delete: summary: Delete channel banner @@ -2665,7 +3226,7 @@ paths: post: summary: Create a video playlist description: If the video playlist is set as public, `videoChannelId` is mandatory. - operationId: createPlaylist + operationId: addPlaylist security: - OAuth2: [] tags: @@ -2685,6 +3246,8 @@ paths: $ref: '#/components/schemas/VideoPlaylist/properties/id' uuid: $ref: '#/components/schemas/VideoPlaylist/properties/uuid' + shortUUID: + $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID' requestBody: content: multipart/form-data: @@ -2785,11 +3348,14 @@ paths: /video-playlists/{playlistId}/videos: get: summary: 'List videos of a playlist' + operationId: getVideoPlaylistVideos tags: - Videos - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' + - $ref: '#/components/parameters/start' + - $ref: '#/components/parameters/count' responses: '200': description: successful operation @@ -2799,6 +3365,7 @@ paths: $ref: '#/components/schemas/VideoListResponse' post: summary: Add a video in a playlist + operationId: addVideoPlaylistVideo security: - OAuth2: [] tags: @@ -2845,6 +3412,7 @@ paths: /video-playlists/{playlistId}/videos/reorder: post: summary: 'Reorder a playlist' + operationId: reorderVideoPlaylist security: - OAuth2: [] tags: @@ -2879,6 +3447,7 @@ paths: /video-playlists/{playlistId}/videos/{playlistElementId}: put: summary: Update a playlist element + operationId: putVideoPlaylistVideo security: - OAuth2: [] tags: @@ -2905,6 +3474,7 @@ paths: description: Stop the video at this specific timestamp delete: summary: Delete an element from a playlist + operationId: delVideoPlaylistVideo security: - OAuth2: [] tags: @@ -2979,6 +3549,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoChannelList' + '/accounts/{name}/ratings': get: summary: List ratings of an account @@ -3009,6 +3580,7 @@ paths: type: array items: $ref: '#/components/schemas/VideoRating' + '/videos/{id}/comment-threads': get: summary: List threads of a video @@ -3072,6 +3644,7 @@ paths: application/json: schema: $ref: '#/components/schemas/VideoCommentThreadTree' + '/videos/{id}/comments/{commentId}': post: summary: Reply to a thread of a video @@ -3104,7 +3677,6 @@ paths: maxLength: 10000 required: - text - delete: summary: Delete a comment or a reply security: @@ -3123,6 +3695,7 @@ paths: description: comment or video does not exist '409': description: comment is already deleted + '/videos/{id}/rate': put: summary: Like/dislike a video @@ -3150,11 +3723,76 @@ paths: description: successful operation '404': description: video does not exist + + '/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 + '/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 + + '/videos/{id}/transcoding': + post: + summary: Create a transcoding job + security: + - OAuth2: + - admin + tags: + - Video Transcoding + operationId: createVideoTranscoding + parameters: + - $ref: '#/components/parameters/idOrUUID' + requestBody: + 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: get: tags: - Search summary: Search videos + operationId: searchVideos parameters: - name: search in: query @@ -3173,7 +3811,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' @@ -3225,38 +3867,115 @@ paths: $ref: '#/components/schemas/VideoListResponse' '500': description: search index unavailable + /search/video-channels: get: tags: - Search summary: Search channels + operationId: searchChannels + parameters: + - name: search + in: query + required: true + 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/VideoChannelList' + '500': + description: search index unavailable + + /search/video-playlists: + get: + tags: + - Search + summary: Search playlists + operationId: searchPlaylists parameters: - name: search in: query - required: true - 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. + required: true + 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 playlist 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: + type: object + properties: + total: + type: integer + example: 1 + data: + type: array + items: + $ref: '#/components/schemas/VideoPlaylist' + '500': + description: search index unavailable + + /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: 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' + 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: + 'application/json': schema: - $ref: '#/components/schemas/VideoChannelList' - '500': - description: search index unavailable - /blocklist/accounts: + $ref: '#/components/schemas/BlockStatus' + + /server/blocklist/accounts: get: tags: - Account Blocks @@ -3295,7 +4014,8 @@ paths: description: successful operation '409': description: self-blocking forbidden - '/blocklist/accounts/{accountName}': + + '/server/blocklist/accounts/{accountName}': delete: tags: - Account Blocks @@ -3315,7 +4035,8 @@ paths: description: successful operation '404': description: account or account block does not exist - /blocklist/servers: + + /server/blocklist/servers: get: tags: - Server Blocks @@ -3350,11 +4071,12 @@ paths: required: - host responses: - '200': + '204': description: successful operation '409': description: self-blocking forbidden - '/blocklist/servers/{host}': + + '/server/blocklist/servers/{host}': delete: tags: - Server Blocks @@ -3371,11 +4093,12 @@ paths: type: string format: hostname responses: - '201': + '204': description: successful operation '404': description: account block does not exist - /redundancy/{host}: + + /server/redundancy/{host}: put: tags: - Instance Redundancy @@ -3407,11 +4130,13 @@ paths: description: successful operation '404': description: server is not already known - /redundancy/videos: + + /server/redundancy/videos: get: tags: - Video Mirroring summary: List videos being mirrored + operationId: getMirroredVideos security: - OAuth2: - admin @@ -3441,6 +4166,7 @@ paths: tags: - Video Mirroring summary: Mirror a video + operationId: putMirroredVideo security: - OAuth2: - admin @@ -3463,11 +4189,13 @@ paths: description: video does not exist '409': description: video is already mirrored - /redundancy/videos/{redundancyId}: + + /server/redundancy/videos/{redundancyId}: delete: tags: - Video Mirroring summary: Delete a mirror done on a video + operationId: delMirroredVideo security: - OAuth2: - admin @@ -3483,11 +4211,13 @@ paths: description: successful operation '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 @@ -3576,11 +4306,13 @@ paths: description: video, video channel or account not found '406': description: accept header unsupported + '/feeds/videos.{format}': get: tags: - Feeds summary: List videos + operationId: getSyndicatedVideos parameters: - name: format in: path @@ -3618,7 +4350,11 @@ paths: type: string - $ref: '#/components/parameters/sort' - $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' responses: '204': description: successful operation @@ -3662,12 +4398,14 @@ paths: 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 @@ -3697,7 +4435,11 @@ paths: required: true - $ref: '#/components/parameters/sort' - $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' responses: '204': description: successful operation @@ -3724,11 +4466,13 @@ paths: type: object '406': description: accept header unsupported + /plugins: get: tags: - Plugins summary: List plugins + operationId: getPlugins security: - OAuth2: - admin @@ -3751,11 +4495,13 @@ paths: application/json: schema: $ref: '#/components/schemas/PluginResponse' + /plugins/available: get: tags: - Plugins summary: List available plugins + operationId: getAvailablePlugins security: - OAuth2: - admin @@ -3784,11 +4530,13 @@ paths: $ref: '#/components/schemas/PluginResponse' '503': description: plugin index unavailable + /plugins/install: post: tags: - Plugins summary: Install a plugin + operationId: addPlugin security: - OAuth2: - admin @@ -3817,11 +4565,13 @@ paths: description: successful operation '400': description: should have either `npmName` or `path` set + /plugins/update: post: tags: - Plugins summary: Update a plugin + operationId: updatePlugin security: - OAuth2: - admin @@ -3852,11 +4602,13 @@ paths: description: should have either `npmName` or `path` set '404': description: existing plugin not found + /plugins/uninstall: post: tags: - Plugins summary: Uninstall a plugin + operationId: uninstallPlugin security: - OAuth2: - admin @@ -3877,11 +4629,13 @@ paths: description: successful operation '404': description: existing plugin not found + /plugins/{npmName}: get: tags: - Plugins summary: Get a plugin + operationId: getPlugin security: - OAuth2: - admin @@ -3896,6 +4650,7 @@ paths: $ref: '#/components/schemas/Plugin' '404': description: plugin not found + /plugins/{npmName}/settings: put: tags: @@ -3920,6 +4675,7 @@ paths: description: successful operation '404': description: plugin not found + /plugins/{npmName}/public-settings: get: tags: @@ -3937,6 +4693,7 @@ paths: additionalProperties: true '404': description: plugin not found + /plugins/{npmName}/registered-settings: get: tags: @@ -3957,6 +4714,7 @@ paths: additionalProperties: true '404': description: plugin not found + servers: - url: 'https://peertube2.cpy.re/api/v1' description: Live Test Server (live data - latest nightly version) @@ -4064,7 +4822,7 @@ components: name: sort in: query required: false - description: Sort blacklists by criteria + description: Sort blocklists by criteria schema: type: string enum: @@ -4121,6 +4879,15 @@ 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 @@ -4133,18 +4900,19 @@ components: name: id in: path required: true - description: The user id + description: Entity id schema: $ref: '#/components/schemas/id' idOrUUID: name: id in: path required: true - description: The object id or uuid + description: The object id, uuid or short uuid schema: oneOf: - $ref: '#/components/schemas/id' - $ref: '#/components/schemas/UUIDv4' + - $ref: '#/components/schemas/shortUUID' playlistId: name: playlistId in: path @@ -4202,7 +4970,7 @@ components: required: true description: The thread id (root comment id) schema: - $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id' + type: integer commentId: name: commentId in: path @@ -4304,20 +5072,58 @@ 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' + 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 @@ -4352,10 +5158,29 @@ components: - video-transcoding - video-file-import - video-import - - videos-views + - videos-views-stats - activitypub-refresher - video-redundancy - video-live-ending + followState: + name: state + in: query + schema: + type: string + enum: + - pending + - accepted + actorType: + name: actorType + in: query + schema: + type: string + enum: + - Person + - Application + - Group + - Service + - Organization securitySchemes: OAuth2: description: | @@ -4390,6 +5215,10 @@ components: pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' minLength: 36 maxLength: 36 + shortUUID: + type: string + description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid + example: 2y84q2MQUMWPbiEcxNXMgC username: type: string description: immutable name of the user, used to find or mention its actor @@ -4488,6 +5317,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: @@ -4508,9 +5360,17 @@ components: enum: - 0 - 1 - description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)' + 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`, HIght latency = `2`, Small Latency = `3`)' + VideoStateConstant: properties: id: @@ -4590,10 +5450,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: @@ -4608,10 +5468,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: @@ -4633,7 +5493,6 @@ components: 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' @@ -4719,6 +5578,9 @@ components: description: universal identifier for the video, that can be used across instances allOf: - $ref: '#/components/schemas/UUIDv4' + shortUUID: + allOf: + - $ref: '#/components/schemas/shortUUID' isLive: type: boolean createdAt: @@ -4832,6 +5694,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 @@ -4980,7 +5845,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 @@ -5098,6 +5962,9 @@ components: $ref: '#/components/schemas/id' uuid: $ref: '#/components/schemas/UUIDv4' + shortUUID: + allOf: + - $ref: '#/components/schemas/shortUUID' createdAt: type: string format: date-time @@ -5188,6 +6055,8 @@ components: properties: path: type: string + width: + type: integer createdAt: type: string format: date-time @@ -5205,12 +6074,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: @@ -5243,8 +6110,6 @@ components: updatedAt: type: string format: date-time - avatar: - $ref: '#/components/schemas/ActorImage' Account: allOf: - $ref: '#/components/schemas/Actor' @@ -5261,13 +6126,76 @@ 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 + views: + type: number + likes: + type: number + dislikes: + type: number + comments: + type: number + 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: @@ -5467,6 +6395,12 @@ components: indexUrl: type: string format: url + homepage: + type: object + properties: + enabled: + type: boolean + ServerConfigAbout: properties: instance: @@ -5594,6 +6528,8 @@ components: properties: 0p: type: boolean + 144p: + type: boolean 240p: type: boolean 360p: @@ -5657,6 +6593,12 @@ components: type: boolean manualApproval: type: boolean + + CustomHomepage: + properties: + content: + type: string + Follow: properties: id: @@ -5719,7 +6661,7 @@ components: - video-transcoding - email - video-import - - videos-views + - videos-views-stats - activitypub-refresher - video-redundancy data: @@ -5861,6 +6803,8 @@ components: $ref: '#/components/schemas/Video/properties/id' uuid: $ref: '#/components/schemas/Video/properties/uuid' + shortUUID: + $ref: '#/components/schemas/Video/properties/shortUUID' CommentThreadResponse: properties: total: @@ -5923,6 +6867,8 @@ components: format: date-time noInstanceConfigWarningModal: type: boolean + noAccountSetupWarningModal: + type: boolean noWelcomeModal: type: boolean nsfwPolicy: @@ -5952,7 +6898,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: @@ -5962,7 +6908,7 @@ components: # optionally present fields: they require WITH_STATS scope videosCount: type: integer - description: Count of videos published + description: Count of videos published abusesCount: type: integer description: Count of reports/abuses of which the user is a target @@ -6030,6 +6976,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: @@ -6053,7 +7001,7 @@ components: - 'true' - 'false' - both - webTorrentEnabled: + p2pEnabled: type: boolean description: whether to enable P2P in the player or not autoPlayVideo: @@ -6077,6 +7025,8 @@ components: type: string noInstanceConfigWarningModal: type: boolean + noAccountSetupWarningModal: + type: boolean noWelcomeModal: type: boolean GetMeVideoRating: @@ -6131,7 +7081,7 @@ components: name: $ref: '#/components/schemas/usernameChannel' displayName: - $ref: '#/components/schemas/VideoChannel/properties/displayName' + type: string required: - username - password @@ -6193,46 +7143,47 @@ 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' @@ -6462,7 +7413,7 @@ components: enum: - 0 - 1 - - 3 + - 2 Notification: properties: id: @@ -6499,6 +7450,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: @@ -6666,11 +7625,16 @@ 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 + rtmpsUrl: + type: string streamKey: type: string description: RTMP stream key to use to stream into this live video @@ -6679,8 +7643,9 @@ 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' callbacks: searchIndex: