openapi: 3.0.0 info: title: PeerTube version: 6.1.0 contact: name: PeerTube Community url: https://joinpeertube.org license: name: AGPLv3.0 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE x-logo: url: https://joinpeertube.org/img/brand.png altText: PeerTube Project Homepage description: | The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice - we generate some client SDKs automatically: - [Python](https://framagit.org/framasoft/peertube/clients/python) - [Go](https://framagit.org/framasoft/peertube/clients/go) - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few examples of using the PeerTube API. # Authentication When you sign up for an account on a PeerTube instance, you are given the possibility to generate sessions on it, and authenticate there using an access token. Only __one access token can currently be used at a time__. ## Roles Accounts are given permissions based on their role. There are three roles on PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions. # Errors The API uses standard HTTP status codes to indicate the success or failure 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` (following RFC7807) and `code` (internal PeerTube code) values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/packages/models/src/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 { "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" } ``` 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 { "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", "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` # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: | Endpoint (prefix: `/api/v1`) | Calls | Time frame | |------------------------------|---------------|--------------| | `/*` | 50 | 10 seconds | | `POST /users/token` | 15 | 5 minutes | | `POST /users/register` | 2* | 5 minutes | | `POST /users/ask-send-verify-email` | 3 | 5 minutes | Depending on the endpoint, *failed requests are not taken into account. A service limit is announced by a `429 Too Many Requests` status code. You can get details about the current state of your rate limit by reading the following headers: | Header | Description | |-------------------------|------------------------------------------------------------| | `X-RateLimit-Limit` | Number of max requests allowed in the current time period | | `X-RateLimit-Remaining` | Number of remaining requests in the current time period | | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp | | `Retry-After` | Seconds to delay after the first `429` is received | # CORS 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/*` | | `/download/*` | | `/lazy-static/*` | | `/.well-known/webfinger` | In addition, all routes serving ActivityPub are CORS-enabled for all origins. externalDocs: url: https://docs.joinpeertube.org/api-rest-reference.html 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/addUser) instead. - name: Session x-displayName: Login/Logout description: | Sessions deal with access tokens over time. Only __one session token can currently be used at a time__. - name: Accounts description: > Accounts encompass remote accounts discovered across the federation, and correspond to the main Actor, along with video channels a user can create, which are also Actors. When a comment is posted, it is done with your Account's Actor. - name: Users description: > Using some features of PeerTube require authentication, for which User provide different levels of permission as well as associated user information. Each user has a corresponding local Account for federation. - name: User Exports description: > To create an archive of user data. - name: User Imports description: > To import an archive of user data. - name: My User description: > Operations related to your own User, when logged-in. - name: My Subscriptions description: > Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications! - name: My History description: > Operations related to your watch history. - name: My Notifications description: > Notifications following new videos, follows or reports. They allow you to keep track of the interactions and overall important information that concerns you. You MAY set per-notification type delivery preference, to receive the info either by mail, by in-browser notification or both. - name: Config description: > Each server exposes public information regarding supported videos and options. - name: Job description: > Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available. - name: Instance Follows description: > Managing servers which the instance interacts with is crucial to the concept of federation in PeerTube and external video indexation. The PeerTube server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints. externalDocs: url: https://docs.joinpeertube.org/admin/following-instances#instances-follows - name: Instance Redundancy description: > Redundancy is part of the inter-server solidarity that PeerTube fosters. Manage the list of instances you wish to help by seeding their videos according to the policy of video selection of your choice. Note that you have a similar functionality to mirror individual videos, see [video mirroring](#tag/Video-Mirroring). externalDocs: url: https://docs.joinpeertube.org/admin/following-instances#instances-redundancy - name: Plugins description: > Managing plugins installed from a local path or from NPM, or search for new ones. externalDocs: url: https://docs.joinpeertube.org/api/plugins - name: Abuses description: | Abuses deal with reports of local or remote videos/comments/accounts alike. - name: Video description: | Operations dealing with listing, uploading, fetching or modifying videos. - name: Video Upload description: | Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes. ### Upload - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks You can upload videos more reliably by using the resumable variant. Its protocol lets you resume an upload operation after a network interruption or other transmission failure, saving time and bandwidth in the event of network failures. Favor using resumable uploads in any of the following cases: - You are transferring large files - The likelihood of a network interruption is high - Uploads are originating from a device with a low-bandwidth or unstable Internet connection, such as a mobile device ### Import - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/) - _magnet_-based: where the URI resolves to a BitTorrent 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 Chapters description: Operations dealing with managing chapters of a video. - name: Video Channels description: Operations dealing with the creation, modification and listing of videos within a channel. - name: Video Comments description: > Operations dealing with comments to a video. Comments are organized in threads: adding a comment in response to the video starts a thread, adding a reply to a comment adds it to its root comment thread. - name: Video Blocks description: Operations dealing with blocking videos (removing them from view and preventing interactions). - name: Automatic Tags description: Automatic tags set on objects (like comments or videos) by specific rules (external link, watched words, etc.) - name: Watched Words description: Manage list of watched words to detect patterns on objects (like comments of videos) - name: Video Rates description: Like/dislike a video. - name: Video Playlists description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels. - name: 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. Videos from other instances federated by the instance (that is, instances followed by the instance) can be found via keywords and other criteria of the advanced search. 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. For importing videos as your own, refer to [video imports](#operation/importVideo). - name: Stats description: | Statistics - name: Runner Registration Token description: | Manage runner registration token - name: Video Passwords description: Operation on video passwords x-tagGroups: - name: Static endpoints tags: - Static Video Files - name: Feeds tags: - Video Feeds - name: Auth tags: - Register - Session - name: Accounts tags: - Accounts - Users - User Exports - User Imports - My User - My Subscriptions - My Notifications - My History - name: Videos tags: - Video - Video Upload - Video Imports - Video Captions - Video Chapters - Video Channels - Video Comments - Video Rates - Video Playlists - Video Stats - Video Ownership Change - Video Mirroring - Video Files - Video Transcoding - Live Videos - Channels Sync - Video Passwords - name: Search tags: - Search - name: Moderation tags: - Abuses - Video Blocks - Account Blocks - Server Blocks - Automatic Tags - Watched Words - name: Instance tags: - Config - Homepage - Instance Follows - Instance Redundancy - Plugins - Stats - Logs - Job - name: Remote Jobs tags: - Runner Registration Token - Runner Jobs - Runners paths: '/static/web-videos/{filename}': get: tags: - Static Video Files summary: Get public Web Video file description: "**PeerTube >= 6.0**" parameters: - $ref: '#/components/parameters/staticFilename' responses: '200': description: successful operation '404': description: not found '/static/web-videos/private/{filename}': get: tags: - Static Video Files summary: Get private Web Video file description: "**PeerTube >= 6.0**" 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: Comments on videos feeds 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 comments to a specific video' schema: type: string - name: accountId in: query description: 'limit listing comments to videos of a specific account' schema: type: string - name: accountName in: query description: 'limit listing comments to videos of a specific account' schema: type: string - name: videoChannelId in: query description: 'limit listing comments to videos of a specific video channel' schema: type: string - name: videoChannelName in: query description: 'limit listing comments to videos of a specific video channel' schema: type: string responses: '200': 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: Common videos feeds 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/hasWebVideoFiles' responses: '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: - Video Feeds summary: Videos of subscriptions feeds 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/hasWebVideoFiles' responses: '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' 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 '/feeds/podcast/videos.xml': get: tags: - Video Feeds summary: Videos podcast feed operationId: getVideosPodcastFeed parameters: - name: videoChannelId in: query description: 'Limit listing to a specific video channel' required: true schema: type: string responses: '200': description: successful operation headers: Cache-Control: schema: type: string default: 'max-age=900' # 15 min cache '404': description: video channel not found '/api/v1/accounts/{name}': get: tags: - Accounts summary: Get an account operationId: getAccount parameters: - $ref: '#/components/parameters/name' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Account' '404': description: account not found '/api/v1/accounts/{name}/videos': get: tags: - Accounts - Video summary: 'List videos of an account' operationId: getAccountVideos parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/autoTagOneOfVideo' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/privacyOneOf' - $ref: '#/components/parameters/hasHLSFiles' - $ref: '#/components/parameters/hasWebVideoFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' - $ref: '#/components/parameters/excludeAlreadyWatched' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' x-codeSamples: - lang: JavaScript source: | fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos') .then(function(response) { return response.json() }).then(function(data) { console.log(data) }) - lang: Shell source: | ## DEPENDENCIES: jq curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq - lang: Ruby source: | require 'net/http' require 'json' uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true response = http.get(uri.request_uri) puts JSON.parse(response.read_body) - lang: Python source: | import requests r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos") json = r.json() print(json) '/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 summary: List accounts operationId: getAccounts parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: 'application/json': schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Account' /api/v1/config: get: tags: - Config summary: Get instance public configuration operationId: getConfig responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfig' examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/config /api/v1/config/about: get: summary: Get instance "About" information operationId: getAbout tags: - Config responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfigAbout' examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/config/about /api/v1/config/custom: get: summary: Get instance runtime configuration operationId: getCustomConfig tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfigCustom' put: summary: Set instance runtime configuration operationId: putCustomConfig tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation '400': x-summary: field inconsistencies description: > Arises when: - the emailer is disabled and the instance is open to registrations - web videos and hls are disabled with transcoding enabled - you need at least one enabled delete: summary: Delete instance runtime configuration operationId: delCustomConfig tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation /api/v1/config/instance-banner/pick: post: summary: Update instance banner security: - OAuth2: - admin tags: - Config responses: '204': description: successful operation '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the banner requestBody: content: multipart/form-data: schema: type: object properties: bannerfile: description: The file to upload. type: string format: binary encoding: bannerfile: contentType: image/png, image/jpeg '/api/v1/config/instance-banner': delete: summary: Delete instance banner security: - OAuth2: - admin tags: - Config responses: '204': description: successful operation /api/v1/config/instance-avatar/pick: post: summary: Update instance avatar security: - OAuth2: - admin tags: - Config responses: '204': description: successful operation '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the avatar requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload. type: string format: binary encoding: avatarfile: contentType: image/png, image/jpeg '/api/v1/config/instance-avatar': delete: summary: Delete instance avatar security: - OAuth2: - admin tags: - Config responses: '204': description: successful operation /api/v1/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 /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 security: - OAuth2: - admin tags: - Job parameters: - name: state in: path required: true description: The state of the job ('' for for no filter) schema: type: string enum: - '' - active - completed - failed - waiting - delayed - $ref: '#/components/parameters/jobType' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Job' /api/v1/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' '/api/v1/server/followers/{nameWithHost}': delete: summary: Remove or reject a 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 '/api/v1/server/followers/{nameWithHost}/reject': post: summary: Reject 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 '/api/v1/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 /api/v1/server/following: get: tags: - Instance Follows summary: List instances followed by 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' post: security: - OAuth2: - admin tags: - Instance Follows summary: Follow a list of actors (PeerTube instance, channel or account) responses: '204': description: successful operation '500': description: cannot follow a non-HTTPS server requestBody: content: application/json: schema: type: object properties: hosts: type: array items: type: string format: hostname uniqueItems: true handles: type: array items: type: string uniqueItems: true '/api/v1/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 /api/v1/users: post: summary: Create a user operationId: addUser security: - OAuth2: - admin tags: - Users responses: '200': description: user created content: application/json: schema: $ref: '#/components/schemas/AddUserResponse' links: # GET /users/{id} GetUser: operationId: getUser parameters: id: '$response.body#/user/id' # PUT /users/{id} PutUser: operationId: putUser parameters: id: '$response.body#/user/id' # DELETE /users/{id} DelUser: operationId: delUser parameters: id: '$response.body#/user/id' '403': description: insufficient authority to create an admin or moderator requestBody: content: application/json: schema: $ref: '#/components/schemas/AddUser' description: | If the smtp server is configured, you can leave the password empty and an email will be sent asking the user to set it first. required: true get: summary: List users operationId: getUsers security: - OAuth2: - admin tags: - Users parameters: - $ref: '#/components/parameters/usersSearch' - $ref: '#/components/parameters/usersBlocked' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/usersSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/User' '/api/v1/users/{id}': parameters: - $ref: '#/components/parameters/id' delete: summary: Delete a user security: - OAuth2: - admin tags: - Users operationId: delUser responses: '204': description: successful operation get: summary: Get a user security: - OAuth2: [] tags: - Users operationId: getUser parameters: - name: withStats in: query description: include statistics about the user (only available as a moderator/admin) schema: type: boolean responses: '200': x-summary: successful operation description: | As an admin/moderator, you can request a response augmented with statistics about the user's moderation relations and videos usage, by using the `withStats` parameter. content: application/json: schema: oneOf: - $ref: '#/components/schemas/User' - $ref: '#/components/schemas/UserWithStats' put: summary: Update a user security: - OAuth2: [] tags: - Users operationId: putUser responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateUser' required: true /api/v1/oauth-clients/local: get: summary: Login prerequisite description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken). operationId: getOAuthClient tags: - Session responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/OAuthClient' links: UseOAuthClientToLogin: operationId: getOAuthToken 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" /api/v1/users/token: post: summary: Login operationId: getOAuthToken description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens. tags: - Session requestBody: content: application/x-www-form-urlencoded: schema: oneOf: - $ref: '#/components/schemas/OAuthToken-password' - $ref: '#/components/schemas/OAuthToken-refresh_token' discriminator: propertyName: grant_type mapping: password: '#/components/schemas/OAuthToken-password' refresh_token: '#/components/schemas/OAuthToken-refresh_token' responses: '200': description: successful operation content: application/json: schema: type: object properties: token_type: type: string example: Bearer access_token: type: string example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0 description: valid for 1 day refresh_token: type: string example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7 description: valid for 2 weeks expires_in: type: integer minimum: 0 example: 14399 refresh_token_expires_in: type: integer minimum: 0 example: 1209600 '400': x-summary: client or credentials are invalid description: | Disambiguate via `code`: - `invalid_client` for an unmatched `client_id` - `invalid_grant` for unmatched credentials '401': x-summary: token expired or two factor header is missing description: | Disambiguate via `code`: - default value for a regular authentication failure - `invalid_token` for an expired token - `missing_two_factor` if two factor header is missing 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-urlencode password="$PASSWORD" \ | jq -r ".access_token" /api/v1/users/revoke-token: post: summary: Logout description: Revokes your access token and its associated refresh token, destroying your current session. operationId: revokeOAuthToken tags: - Session security: - OAuth2: [] responses: '200': description: successful operation /api/v1/users/ask-send-verify-email: post: summary: Resend user verification link operationId: resendEmailToVerifyUser tags: - Users - Register requestBody: content: application/json: schema: type: object properties: email: type: string description: User email required: - 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: type: object properties: email: type: string description: Registration email required: - email responses: '204': description: successful operation /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 security: - OAuth2: [] 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 security: - OAuth2: [] tags: - Users parameters: - $ref: '#/components/parameters/id' requestBody: content: application/json: schema: type: object properties: requestToken: type: string description: Token to identify the two factor request otpToken: type: string description: OTP token generated by the app required: - requestToken - otpToken responses: '204': description: successful operation '403': description: invalid request token or OTP token '404': description: user not found /api/v1/users/{id}/two-factor/disable: post: summary: Disable two factor auth operationId: disableTwoFactor description: Disable two factor authentication of a user security: - OAuth2: [] 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: '204': description: successful operation '403': description: invalid password '404': description: user not found /api/v1/users/{userId}/imports/import-resumable: post: summary: Initialize the resumable user import description: "**PeerTube >= 6.1** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the import of the archive" operationId: userImportResumableInit security: - OAuth2: [] tags: - User Imports parameters: - $ref: '#/components/parameters/resumableUploadInitContentLengthHeader' - $ref: '#/components/parameters/resumableUploadInitContentTypeHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/UserImportResumable' responses: '201': description: created headers: Location: schema: type: string format: url Content-Length: schema: type: number example: 0 put: summary: Send chunk for the resumable user import description: "**PeerTube >= 6.1** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the import of the archive" operationId: userImportResumable security: - OAuth2: [] tags: - User Imports parameters: - $ref: '#/components/parameters/resumableUploadId' - $ref: '#/components/parameters/resumableUploadChunkContentRangeHeader' - $ref: '#/components/parameters/resumableUploadChunkContentLengthHeader' requestBody: content: application/octet-stream: schema: type: string format: binary responses: '204': description: 'last chunk received: successful operation' '308': description: resume incomplete headers: Range: schema: type: string example: bytes=0-262143 Content-Length: schema: type: number example: 0 delete: summary: Cancel the resumable user import description: "**PeerTube >= 6.1** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the resumable user import" operationId: userImportResumableCancel security: - OAuth2: [] tags: - User Imports parameters: - $ref: '#/components/parameters/resumableUploadId' - name: Content-Length in: header required: true schema: type: number example: 0 responses: '204': description: import cancelled headers: Content-Length: schema: type: number example: 0 /api/v1/users/{userId}/imports/latest: get: summary: Get latest user import description: "**PeerTube >= 6.1**" operationId: getLatestUserImport security: - OAuth2: [] tags: - User Imports parameters: - $ref: '#/components/parameters/userId' responses: '200': description: successful operation content: application/json: schema: type: object properties: id: type: integer state: type: object properties: id: $ref: '#/components/schemas/UserImportState' label: type: string createdAt: type: string format: date-time /api/v1/users/{userId}/exports/request: post: summary: Request user export operationId: requestUserExport description: Request an archive of user data. An email is sent when the archive is ready. security: - OAuth2: [] tags: - User Exports parameters: - $ref: '#/components/parameters/userId' requestBody: content: application/json: schema: type: object properties: withVideoFiles: type: boolean description: Whether to include video files in the archive responses: '200': description: successful operation content: application/json: schema: type: object properties: export: type: object properties: id: type: integer /api/v1/users/{userId}/exports: get: summary: List user exports description: "**PeerTube >= 6.1**" operationId: listUserExports security: - OAuth2: [] tags: - User Exports parameters: - $ref: '#/components/parameters/userId' responses: '200': description: successful operation content: application/json: schema: type: object properties: id: type: integer state: type: object properties: id: $ref: '#/components/schemas/UserExportState' label: type: string size: type: integer description: Size of the archive file in bytes privateDownloadUrl: type: string description: This URL already contains the JWT token, so no additional authentication credentials are required createdAt: type: string format: date-time expiresOn: type: string format: date-time /api/v1/users/{userId}/exports/{id}: delete: summary: Delete a user export description: "**PeerTube >= 6.1**" operationId: deleteUserExport security: - OAuth2: [] tags: - User Exports parameters: - $ref: '#/components/parameters/userId' - $ref: '#/components/parameters/id' responses: '204': description: successful operation /api/v1/users/me: get: summary: Get my user information operationId: getUserInfo security: - OAuth2: - user tags: - My User responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/User' put: summary: Update my user information operationId: putUserInfo security: - OAuth2: - user tags: - My User responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateMe' required: true '/api/v1/users/me/videos/comments': get: summary: List comments on user's videos description: "**PeerTube >= 6.2**" security: - OAuth2: [] tags: - Video Comments parameters: - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/searchAccountForComments' - $ref: '#/components/parameters/searchVideoForComments' - $ref: '#/components/parameters/videoId' - $ref: '#/components/parameters/videoChannelId' - $ref: '#/components/parameters/autoTagOneOfComment' - $ref: '#/components/parameters/isHeldForReview' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoCommentForOwnerOrAdmin' /api/v1/users/me/videos/imports: get: summary: Get video imports of my user security: - OAuth2: - user tags: - Videos - My User parameters: - $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 content: application/json: schema: $ref: '#/components/schemas/VideoImportsList' /api/v1/users/me/video-quota-used: get: summary: Get my user used quota security: - OAuth2: - user tags: - My User responses: '200': description: successful operation content: application/json: schema: type: object properties: videoQuotaUsed: type: number description: The user video quota used so far in bytes example: 16810141515 videoQuotaUsedDaily: type: number description: The user video quota used today in bytes example: 1681014151 '/api/v1/users/me/videos/{videoId}/rating': get: summary: Get rate of my user for a video security: - OAuth2: [] tags: - My User - Video Rates parameters: - name: videoId in: path required: true description: The video id schema: $ref: '#/components/schemas/Video/properties/id' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/GetMeVideoRating' /api/v1/users/me/videos: get: summary: List videos of my user security: - OAuth2: - user tags: - My User - Videos parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' /api/v1/users/me/subscriptions: get: summary: Get my user subscriptions security: - OAuth2: - user tags: - My Subscriptions parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannelList' post: tags: - My Subscriptions summary: Add subscription to my user security: - OAuth2: - user requestBody: content: application/json: schema: type: object properties: uri: type: string format: uri description: uri of the video channels to subscribe to required: - uri examples: default: value: uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr responses: '200': description: successful operation /api/v1/users/me/subscriptions/exist: get: summary: Get if subscriptions exist for my user security: - OAuth2: - user tags: - My Subscriptions parameters: - $ref: '#/components/parameters/subscriptionsUris' responses: '200': description: successful operation content: application/json: schema: type: object /api/v1/users/me/subscriptions/videos: get: summary: List videos of subscriptions of my user security: - OAuth2: - user tags: - My Subscriptions - Videos parameters: - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/autoTagOneOfVideo' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/privacyOneOf' - $ref: '#/components/parameters/hasHLSFiles' - $ref: '#/components/parameters/hasWebVideoFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' - $ref: '#/components/parameters/excludeAlreadyWatched' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '/api/v1/users/me/subscriptions/{subscriptionHandle}': get: summary: Get subscription of my user security: - OAuth2: - user tags: - My Subscriptions parameters: - $ref: '#/components/parameters/subscriptionHandle' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannel' delete: summary: Delete subscription of my user security: - OAuth2: - user tags: - My Subscriptions parameters: - $ref: '#/components/parameters/subscriptionHandle' responses: '200': description: successful operation /api/v1/users/me/notifications: get: summary: List my notifications security: - OAuth2: [] tags: - My Notifications parameters: - name: unread in: query description: only list unread notifications schema: type: boolean - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/NotificationListResponse' /api/v1/users/me/notifications/read: post: summary: Mark notifications as read by their id security: - OAuth2: [] tags: - My Notifications requestBody: content: application/json: schema: type: object properties: ids: type: array description: ids of the notifications to mark as read items: type: integer required: - ids responses: '204': description: successful operation /api/v1/users/me/notifications/read-all: post: summary: Mark all my notification as read security: - OAuth2: [] tags: - My Notifications responses: '204': description: successful operation /api/v1/users/me/notification-settings: put: summary: Update my notification settings security: - OAuth2: [] tags: - My Notifications requestBody: content: application/json: schema: type: object properties: newVideoFromSubscription: $ref: '#/components/schemas/NotificationSettingValue' newCommentOnMyVideo: $ref: '#/components/schemas/NotificationSettingValue' abuseAsModerator: $ref: '#/components/schemas/NotificationSettingValue' videoAutoBlacklistAsModerator: $ref: '#/components/schemas/NotificationSettingValue' blacklistOnMyVideo: $ref: '#/components/schemas/NotificationSettingValue' myVideoPublished: $ref: '#/components/schemas/NotificationSettingValue' myVideoImportFinished: $ref: '#/components/schemas/NotificationSettingValue' newFollow: $ref: '#/components/schemas/NotificationSettingValue' newUserRegistration: $ref: '#/components/schemas/NotificationSettingValue' commentMention: $ref: '#/components/schemas/NotificationSettingValue' newInstanceFollower: $ref: '#/components/schemas/NotificationSettingValue' autoInstanceFollowing: $ref: '#/components/schemas/NotificationSettingValue' responses: '204': description: successful operation /api/v1/users/me/history/videos: get: summary: List watched videos history security: - OAuth2: [] tags: - My History parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/search' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' /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: - OAuth2: [] tags: - My History requestBody: content: multipart/form-data: schema: type: object properties: beforeDate: description: history before this date will be deleted type: string format: date-time responses: '204': description: successful operation /api/v1/users/me/avatar/pick: post: summary: Update my user avatar security: - OAuth2: [] tags: - My User responses: '200': description: successful operation content: application/json: schema: type: object properties: avatars: type: array items: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the avatar requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload type: string format: binary encoding: avatarfile: contentType: image/png, image/jpeg /api/v1/users/me/avatar: delete: summary: Delete my avatar security: - OAuth2: [] tags: - My User responses: '204': description: successful operation /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: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/UserRegistration' /api/v1/videos/ownership: get: summary: List video ownership changes tags: - Video Ownership Change security: - OAuth2: [] responses: '200': description: successful operation '/api/v1/videos/ownership/{id}/accept': post: summary: Accept ownership change request tags: - Video Ownership Change security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '403': description: cannot terminate an ownership change of another user '404': description: video ownership change not found '/api/v1/videos/ownership/{id}/refuse': post: summary: Refuse ownership change request tags: - Video Ownership Change security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '403': description: cannot terminate an ownership change of another user '404': description: video ownership change not found '/api/v1/videos/{id}/give-ownership': post: summary: Request ownership change tags: - Video Ownership Change security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: username: type: string required: - username responses: '204': description: successful operation '400': description: changing video ownership to a remote account is not supported yet '404': description: video not found '/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' - $ref: '#/components/parameters/videoPasswordHeader' 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 tags: - Video parameters: - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/autoTagOneOfVideo' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/privacyOneOf' - $ref: '#/components/parameters/hasHLSFiles' - $ref: '#/components/parameters/hasWebVideoFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' - $ref: '#/components/parameters/excludeAlreadyWatched' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' /api/v1/videos/categories: get: summary: List available video categories operationId: getCategories tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/categories /api/v1/videos/licences: get: summary: List available video licences operationId: getLicences tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/licences /api/v1/videos/languages: get: summary: List available video languages operationId: getLanguages tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/languages /api/v1/videos/privacies: get: summary: List available video privacy policies operationId: getVideoPrivacyPolicies tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/videos/privacies '/api/v1/videos/{id}': put: summary: Update a video operationId: putVideo security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation requestBody: content: multipart/form-data: schema: type: object properties: thumbnailfile: description: Video thumbnail file type: string format: binary previewfile: description: Video preview file type: string format: binary category: $ref: '#/components/schemas/VideoCategorySet' licence: $ref: '#/components/schemas/VideoLicenceSet' language: $ref: '#/components/schemas/VideoLanguageSet' privacy: $ref: '#/components/schemas/VideoPrivacySet' description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: string support: description: A text tell the audience how to support the video creator example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this video contains sensitive content type: boolean name: description: Video name type: string minLength: 3 maxLength: 120 tags: description: Video tags (maximum 5 tags each between 2 and 30 characters) type: array minItems: 1 maxItems: 5 items: type: string minLength: 2 maxLength: 30 commentsEnabled: deprecated: true description: 'Deprecated in 6.2, use commentsPolicy instead' type: boolean commentsPolicy: $ref: '#/components/schemas/VideoCommentsPolicySet' downloadEnabled: description: Enable or disable downloading for this video type: boolean originallyPublishedAt: description: Date when the content was originally published type: string format: date-time nullable: true scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' videoPasswords: $ref: '#/components/schemas/AddVideoPasswords' encoding: thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg get: summary: Get a video operationId: getVideo tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoDetails' '403': description: provide a correct password to access this password protected video delete: summary: Delete a video operationId: delVideo security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '/api/v1/videos/{id}/description': get: summary: Get complete video description operationId: getVideoDesc tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: nullable: true type: string minLength: 3 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)** '/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 Stats security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoStatsRetention' '/api/v1/videos/{id}/stats/timeseries/{metric}': get: summary: Get timeserie stats of a video tags: - Video Stats security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' - name: metric in: path required: true description: The metric to get schema: type: string enum: - 'viewers' - 'aggregateWatchTime' - name: startDate in: query description: Filter stats by start date schema: type: string format: date-time - name: endDate in: query description: Filter stats by end date schema: type: string format: date-time responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoStatsTimeserie' /api/v1/videos/upload: post: summary: Upload a video description: Uses a single request to upload a video. operationId: uploadLegacy security: - OAuth2: [] tags: - Video - Video Upload responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '403': description: video didn't pass upload filter '408': description: upload has timed out '413': 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 `code`: - `quota_reached` for quota limits whether daily or global headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the video '415': description: video type unsupported '422': description: video unreadable requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/VideoUploadRequestLegacy' encoding: videofile: contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg x-codeSamples: - lang: Shell source: | ## DEPENDENCIES: jq USERNAME="" PASSWORD="" FILE_PATH="" CHANNEL_ID="" NAME="" API="https://peertube2.cpy.re/api/v1" ## 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") token=$(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") ## VIDEO UPLOAD curl -s "$API/videos/upload" \ -H "Authorization: Bearer $token" \ --max-time 600 \ --form videofile=@"$FILE_PATH" \ --form channelId=$CHANNEL_ID \ --form name="$NAME" /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 operationId: uploadResumableInit security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadInitContentLengthHeader' - $ref: '#/components/parameters/resumableUploadInitContentTypeHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoUploadRequestResumable' responses: '200': description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead '201': description: created headers: Location: schema: type: string format: url example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51 Content-Length: schema: type: number example: 0 '413': x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit description: | Disambiguate via `code`: - `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: summary: Send chunk for the resumable upload of a video description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video operationId: uploadResumable security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadId' - $ref: '#/components/parameters/resumableUploadChunkContentRangeHeader' - $ref: '#/components/parameters/resumableUploadChunkContentLengthHeader' requestBody: content: application/octet-stream: schema: type: string format: binary responses: '200': description: last chunk received headers: Content-Length: schema: type: number content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '308': description: resume incomplete headers: Range: schema: type: string example: bytes=0-262143 Content-Length: schema: type: number example: 0 '403': description: video didn't pass upload filter '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 operationId: uploadResumableCancel security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadId' - name: Content-Length in: header required: true schema: type: number example: 0 responses: '204': description: upload cancelled headers: Content-Length: schema: type: number example: 0 '404': description: upload not found /api/v1/videos/imports: post: summary: Import a video description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) operationId: importVideo security: - OAuth2: [] tags: - Video Imports - Video Upload requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/VideoCreateImport' encoding: torrentfile: contentType: application/x-bittorrent thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '400': description: '`magnetUri` or `targetUrl` or a torrent file missing' '403': description: video didn't pass pre-import filter '409': description: HTTP or Torrent/magnetURI import not enabled /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 security: - OAuth2: [] tags: - Live Videos - Video responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '400': x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set description: | Disambiguate via `code`: - default type for a validation error - `live_conflicting_permanent_and_save_replay` for conflicting parameters set '403': x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded description: | Disambiguate via `code`: - `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: schema: type: object properties: channelId: description: Channel id that will contain this live video type: integer saveReplay: type: boolean replaySettings: $ref: '#/components/schemas/LiveVideoReplaySettings' 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 format: binary previewfile: description: Live video/replay preview file type: string format: binary privacy: $ref: '#/components/schemas/VideoPrivacySet' category: $ref: '#/components/schemas/VideoCategorySet' licence: $ref: '#/components/schemas/VideoLicenceSet' language: $ref: '#/components/schemas/VideoLanguageSet' description: description: Live video/replay description type: string support: description: A text tell the audience how to support the creator example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this live video/replay contains sensitive content type: boolean name: description: Live video/replay name type: string minLength: 3 maxLength: 120 tags: description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters) type: array minItems: 1 maxItems: 5 items: type: string minLength: 2 maxLength: 30 commentsEnabled: deprecated: true description: 'Deprecated in 6.2, use commentsPolicy instead' type: boolean commentsPolicy: $ref: '#/components/schemas/VideoCommentsPolicySet' downloadEnabled: description: Enable or disable downloading for the replay of this live video type: boolean required: - channelId - name encoding: thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg /api/v1/videos/live/{id}: get: summary: Get information about a live operationId: getLiveId security: - OAuth2: [] tags: - Live Videos - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/LiveVideoResponse' put: summary: Update information about a live operationId: updateLiveId security: - OAuth2: [] tags: - Live Videos - Video parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: content: application/json: schema: $ref: '#/components/schemas/LiveVideoUpdate' responses: '204': description: successful operation '400': description: 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' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/LiveVideoSessionResponse' '/api/v1/videos/{id}/source': get: summary: Get video source file metadata operationId: getVideoSource security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoSource' '/api/v1/videos/{id}/source/file': delete: summary: Delete video source file operationId: deleteVideoSourceFile tags: - Video security: - OAuth2: - admin - moderator parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '404': description: video source not found '/api/v1/videos/{id}/source/replace-resumable': post: summary: Initialize the resumable replacement of a video description: "**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the replacement of a video" operationId: replaceVideoSourceResumableInit security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadInitContentLengthHeader' - $ref: '#/components/parameters/resumableUploadInitContentTypeHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoReplaceSourceRequestResumable' responses: '200': description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead '201': description: created headers: Location: schema: type: string format: url Content-Length: schema: type: number example: 0 '413': x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit description: | Disambiguate via `code`: - `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: summary: Send chunk for the resumable replacement of a video description: "**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the replacement of a video" operationId: replaceVideoSourceResumable security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadId' - $ref: '#/components/parameters/resumableUploadChunkContentRangeHeader' - $ref: '#/components/parameters/resumableUploadChunkContentLengthHeader' requestBody: content: application/octet-stream: schema: type: string format: binary responses: '204': description: 'last chunk received: successful operation' '308': description: resume incomplete headers: Range: schema: type: string example: bytes=0-262143 Content-Length: schema: type: number example: 0 '403': description: video didn't pass file replacement filter '404': description: replace 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 replacement of a video description: "**PeerTube >= 6.0** Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the replacement of a video" operationId: replaceVideoSourceResumableCancel security: - OAuth2: [] tags: - Video - Video Upload parameters: - $ref: '#/components/parameters/resumableUploadId' - name: Content-Length in: header required: true schema: type: number example: 0 responses: '204': description: source file replacement cancelled headers: Content-Length: schema: type: number example: 0 '404': description: source file replacement not found /api/v1/users/me/abuses: get: summary: List my abuses operationId: getMyAbuses security: - OAuth2: [] tags: - Abuses - My User parameters: - name: id in: query description: only list the report with this id schema: type: integer - name: state in: query schema: $ref: '#/components/schemas/AbuseStateSet' - $ref: '#/components/parameters/abusesSort' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Abuse' /api/v1/abuses: get: summary: List abuses operationId: getAbuses security: - OAuth2: - admin - moderator tags: - Abuses parameters: - name: id in: query description: only list the report with this id schema: type: integer - name: predefinedReason in: query description: predefined reason the listed reports should contain schema: $ref: '#/components/schemas/PredefinedAbuseReasons' - name: search in: query description: plain search that will match with video titles, reporter names and more schema: type: string - name: state in: query schema: $ref: '#/components/schemas/AbuseStateSet' - name: searchReporter in: query description: only list reports of a specific reporter schema: type: string - name: searchReportee description: only list reports of a specific reportee in: query schema: type: string - name: searchVideo in: query description: only list reports of a specific video schema: type: string - name: searchVideoChannel in: query description: only list reports of a specific video channel schema: type: string - name: videoIs in: query description: only list deleted or blocklisted videos schema: type: string enum: - 'deleted' - 'blacklisted' - name: filter in: query description: only list account, comment or video reports schema: type: string enum: - 'video' - 'comment' - 'account' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Abuse' post: summary: Report an abuse security: - OAuth2: [] tags: - Abuses requestBody: required: true content: application/json: schema: type: object properties: reason: description: Reason why the user reports this video type: string minLength: 2 maxLength: 3000 predefinedReasons: $ref: '#/components/schemas/PredefinedAbuseReasons' video: type: object properties: id: description: Video id to report allOf: - $ref: '#/components/schemas/Video/properties/id' startAt: type: integer format: seconds description: Timestamp in the video that marks the beginning of the report minimum: 0 endAt: type: integer format: seconds description: Timestamp in the video that marks the ending of the report minimum: 0 comment: type: object properties: id: description: Comment id to report allOf: - $ref: '#/components/schemas/VideoComment/properties/id' account: type: object properties: id: description: Account id to report type: integer required: - reason responses: '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 '/api/v1/abuses/{abuseId}': put: summary: Update an abuse security: - OAuth2: - admin - moderator tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' requestBody: content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/AbuseStateSet' moderationComment: type: string description: Update the report comment visible only to the moderation team minLength: 2 maxLength: 3000 responses: '204': description: successful operation '404': description: abuse not found delete: tags: - Abuses summary: Delete an abuse security: - OAuth2: - admin - moderator parameters: - $ref: '#/components/parameters/abuseId' responses: '204': description: successful operation '404': description: block not found '/api/v1/abuses/{abuseId}/messages': get: summary: List messages of an abuse security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/AbuseMessage' post: summary: Add message to an abuse security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' requestBody: required: true content: application/json: schema: type: object properties: message: description: Message to send type: string minLength: 2 maxLength: 3000 required: - message responses: '200': description: successful operation '400': description: incorrect request parameters '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}': delete: summary: Delete an abuse message security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' - $ref: '#/components/parameters/abuseMessageId' responses: '204': description: successful operation '/api/v1/videos/{id}/blacklist': post: summary: Block a video operationId: addVideoBlock security: - OAuth2: - admin - moderator tags: - Video Blocks parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation delete: summary: Unblock a video by its id operationId: delVideoBlock security: - OAuth2: - admin - moderator tags: - Video Blocks parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '404': description: block not found /api/v1/videos/blacklist: get: tags: - Video Blocks summary: List video blocks operationId: getVideoBlocks security: - OAuth2: - admin - moderator parameters: - name: type in: query description: > list only blocks that match this type: - `1`: manual block - `2`: automatic block that needs review schema: type: integer enum: - 1 - 2 - name: search in: query description: plain search that will match with video titles, and more schema: type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/blacklistsSort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoBlacklist' /api/v1/videos/{id}/storyboards: get: summary: List storyboards of a video description: "**PeerTube >= 6.0**" operationId: listVideoStoryboards tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: type: object properties: storyboards: type: array items: $ref: '#/components/schemas/Storyboard' /api/v1/videos/{id}/captions: get: summary: List captions of a video operationId: getVideoCaptions tags: - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoCaption' /api/v1/videos/{id}/captions/generate: post: summary: Generate a video caption operationId: generateVideoCaption description: "**PeerTube >= 6.2** This feature has to be enabled by the administrator" security: - OAuth2: - user tags: - Video Captions requestBody: content: application/json: schema: type: object properties: forceTranscription: type: boolean default: false responses: '204': description: successful operation '404': description: video not found /api/v1/videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption operationId: addVideoCaption security: - OAuth2: - user tags: - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/captionLanguage' requestBody: content: multipart/form-data: schema: type: object properties: captionfile: description: The file to upload. type: string format: binary encoding: captionfile: contentType: text/vtt, application/x-subrip, text/plain responses: '204': description: successful operation '404': description: video or language not found delete: summary: Delete a video caption operationId: delVideoCaption security: - OAuth2: - user tags: - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/captionLanguage' responses: '204': description: successful operation '404': description: video or language or caption for that language not found /api/v1/videos/{id}/chapters: get: summary: Get chapters of a video description: "**PeerTube >= 6.0**" operationId: getVideoChapters tags: - Video Chapters parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChapters' put: summary: Replace video chapters description: "**PeerTube >= 6.0**" operationId: replaceVideoChapters security: - OAuth2: - user tags: - Video Chapters parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: content: application/json: schema: type: object properties: chapters: type: array items: type: object properties: title: type: string timecode: type: integer responses: '204': description: successful operation '404': description: video not found /api/v1/videos/{id}/passwords: get: summary: List video passwords description: "**PeerTube >= 6.0**" security: - OAuth2: - user tags: - Video Passwords parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '204': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoPasswordList' '400': description: video is not password protected put: summary: Update video passwords description: "**PeerTube >= 6.0**" security: - OAuth2: - user tags: - Video Passwords parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: content: application/json: schema: type: object properties: passwords: $ref: '#/components/schemas/AddVideoPasswords' responses: '204': description: successful operation '400': description: video is not password protected /api/v1/videos/{id}/passwords/{videoPasswordId}: delete: summary: Delete a video password description: "**PeerTube >= 6.0**" security: - OAuth2: - user tags: - Video Passwords parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordId' responses: '204': description: successful operation '403': description: cannot delete the last password of the protected video '400': description: video is not password protected /api/v1/video-channels: get: summary: List video channels operationId: getVideoChannels tags: - Video Channels parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannelList' post: summary: Create a video channel operationId: addVideoChannel security: - OAuth2: [] tags: - Video Channels responses: '200': description: successful operation content: application/json: schema: type: object properties: videoChannel: type: object properties: id: $ref: '#/components/schemas/id' requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoChannelCreate' '/api/v1/video-channels/{channelHandle}': get: summary: Get a video channel operationId: getVideoChannel tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannel' put: summary: Update a video channel operationId: putVideoChannel security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoChannelUpdate' delete: summary: Delete a video channel operationId: delVideoChannel security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation '/api/v1/video-channels/{channelHandle}/videos': get: summary: List videos of a video channel operationId: getVideoChannelVideos tags: - Video - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/autoTagOneOfVideo' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/privacyOneOf' - $ref: '#/components/parameters/hasHLSFiles' - $ref: '#/components/parameters/hasWebVideoFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' - $ref: '#/components/parameters/excludeAlreadyWatched' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '/api/v1/video-channels/{channelHandle}/video-playlists': get: summary: List playlists of a channel tags: - Video Playlists - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/videoPlaylistType' 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' '/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: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: type: object properties: avatars: type: array items: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the avatar requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload. type: string format: binary encoding: avatarfile: contentType: image/png, image/jpeg '/api/v1/video-channels/{channelHandle}/avatar': delete: summary: Delete channel avatar security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation '/api/v1/video-channels/{channelHandle}/banner/pick': post: summary: Update channel banner security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: type: object properties: banners: type: array items: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the banner requestBody: content: multipart/form-data: schema: type: object properties: bannerfile: description: The file to upload. type: string format: binary encoding: bannerfile: contentType: image/png, image/jpeg '/api/v1/video-channels/{channelHandle}/banner': delete: summary: Delete channel banner security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation '/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 tags: - Video Playlists responses: '200': description: successful operation content: application/json: schema: type: array items: type: string examples: nightly: externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies /api/v1/video-playlists: get: summary: List video playlists operationId: getPlaylists tags: - Video Playlists parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/videoPlaylistType' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoPlaylist' post: summary: Create a video playlist description: If the video playlist is set as public, `videoChannelId` is mandatory. operationId: addPlaylist security: - OAuth2: [] tags: - Video Playlists responses: '200': description: successful operation content: application/json: schema: type: object properties: videoPlaylist: type: object properties: id: $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: schema: type: object properties: displayName: description: Video playlist display name type: string minLength: 1 maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string format: binary privacy: $ref: '#/components/schemas/VideoPlaylistPrivacySet' description: description: Video playlist description type: string minLength: 3 maxLength: 1000 videoChannelId: allOf: - $ref: '#/components/schemas/id' description: Video channel in which the playlist will be published required: - displayName encoding: thumbnailfile: contentType: image/jpeg /api/v1/video-playlists/{playlistId}: get: summary: Get a video playlist tags: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoPlaylist' put: summary: Update a video playlist description: 'If the video playlist is set as public, the playlist must have a assigned channel.' security: - OAuth2: [] tags: - Video Playlists responses: '204': description: successful operation parameters: - $ref: '#/components/parameters/playlistId' requestBody: content: multipart/form-data: schema: type: object properties: displayName: description: Video playlist display name type: string minLength: 1 maxLength: 120 thumbnailfile: description: Video playlist thumbnail file type: string format: binary privacy: $ref: '#/components/schemas/VideoPlaylistPrivacySet' description: description: Video playlist description type: string videoChannelId: allOf: - $ref: '#/components/schemas/id' description: Video channel in which the playlist will be published encoding: thumbnailfile: contentType: image/jpeg delete: summary: Delete a video playlist security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' responses: '204': description: successful operation /api/v1/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 content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' post: summary: Add a video in a playlist operationId: addVideoPlaylistVideo security: - OAuth2: [] tags: - Videos - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' responses: '200': description: successful operation content: application/json: schema: type: object properties: videoPlaylistElement: type: object properties: id: type: integer example: 2 requestBody: content: application/json: schema: type: object properties: videoId: oneOf: - $ref: '#/components/schemas/Video/properties/uuid' - $ref: '#/components/schemas/Video/properties/id' description: Video to add in the playlist startTimestamp: type: integer format: seconds description: Start the video at this specific timestamp stopTimestamp: type: integer format: seconds description: Stop the video at this specific timestamp required: - videoId /api/v1/video-playlists/{playlistId}/videos/reorder: post: summary: 'Reorder a playlist' operationId: reorderVideoPlaylist security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' responses: '204': description: successful operation requestBody: content: application/json: schema: type: object properties: startPosition: type: integer description: 'Start position of the element to reorder' minimum: 1 insertAfterPosition: type: integer description: 'New position for the block to reorder, to add the block before the first element' minimum: 0 reorderLength: type: integer description: 'How many element from `startPosition` to reorder' minimum: 1 required: - startPosition - insertAfterPosition /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}: put: summary: Update a playlist element operationId: putVideoPlaylistVideo security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' - $ref: '#/components/parameters/playlistElementId' responses: '204': description: successful operation requestBody: content: application/json: schema: type: object properties: startTimestamp: type: integer format: seconds description: Start the video at this specific timestamp stopTimestamp: type: integer format: seconds description: Stop the video at this specific timestamp delete: summary: Delete an element from a playlist operationId: delVideoPlaylistVideo security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/playlistId' - $ref: '#/components/parameters/playlistElementId' responses: '204': description: successful operation '/api/v1/users/me/video-playlists/videos-exist': get: summary: Check video exists in my playlists security: - OAuth2: [] tags: - Video Playlists parameters: - name: videoIds in: query required: true description: The video ids to check schema: type: array items: $ref: '#/components/schemas/Video/properties/id' responses: '200': description: successful operation content: application/json: schema: type: object properties: videoId: type: array items: type: object properties: playlistElementId: type: integer playlistId: type: integer startTimestamp: type: integer format: seconds stopTimestamp: type: integer '/api/v1/accounts/{name}/video-playlists': get: summary: List playlists of an account tags: - Video Playlists - Accounts parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/videoPlaylistType' 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' '/api/v1/accounts/{name}/video-channels': get: summary: List video channels of an account tags: - Video Channels - Accounts parameters: - $ref: '#/components/parameters/name' - name: withStats in: query 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' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannelList' '/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: - OAuth2: [] tags: - Accounts parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - name: rating in: query required: false description: Optionally filter which ratings to retrieve schema: type: string enum: - like - dislike responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoRating' '/api/v1/videos/{id}/comment-threads': get: summary: List threads of a video tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/commentsSort' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadResponse' post: summary: Create a thread security: - OAuth2: [] tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' '404': description: video does not exist requestBody: content: application/json: schema: type: object properties: text: allOf: - $ref: '#/components/schemas/VideoComment/properties/text' format: markdown maxLength: 10000 required: - text '/api/v1/videos/{id}/comment-threads/{threadId}': get: summary: Get a thread tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/threadId' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoCommentThreadTree' '/api/v1/videos/comments': get: summary: List instance comments security: - OAuth2: - admin - moderator tags: - Video Comments parameters: - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/searchAccountForComments' - $ref: '#/components/parameters/searchVideoForComments' - $ref: '#/components/parameters/videoId' - $ref: '#/components/parameters/videoChannelId' - $ref: '#/components/parameters/autoTagOneOfComment' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/onLocalVideo' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoCommentForOwnerOrAdmin' '/api/v1/videos/{id}/comments/{commentId}': post: summary: Reply to a thread of a video security: - OAuth2: [] tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/commentId' - $ref: '#/components/parameters/videoPasswordHeader' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' '404': description: thread or video does not exist requestBody: content: application/json: schema: type: object properties: text: allOf: - $ref: '#/components/schemas/VideoComment/properties/text' format: markdown maxLength: 10000 required: - text delete: summary: Delete a comment or a reply security: - OAuth2: [] tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/commentId' responses: '204': description: successful operation '403': description: cannot remove comment of another user '404': description: comment or video does not exist '409': description: comment is already deleted '/api/v1/videos/{id}/comments/{commentId}/approve': post: summary: Approve a comment description: "**PeerTube >= 6.2** Approve a comment that requires a review" security: - OAuth2: [] tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/commentId' responses: '204': description: successful operation '/api/v1/videos/{id}/rate': put: summary: Like/dislike a video security: - OAuth2: [] tags: - Video Rates parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/videoPasswordHeader' 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}/web-videos': delete: summary: Delete video Web Video files description: "**PeerTube >= 6.0**" security: - OAuth2: - admin tags: - Video Files operationId: delVideoWebVideos 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 Transcoding operationId: createVideoTranscoding parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: content: application/json: schema: type: object properties: transcodingType: type: string enum: - hls - web-video forceTranscoding: type: boolean default: false description: If the video is stuck in transcoding state, do it anyway required: - transcodingType responses: '204': description: successful operation '404': description: video does not exist /api/v1/search/videos: get: tags: - Search - Video summary: Search videos operationId: searchVideos parameters: - name: search in: query required: true allowEmptyValue: false description: > String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it. schema: type: string - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/autoTagOneOfVideo' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/isLocal' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/privacyOneOf' - $ref: '#/components/parameters/uuids' - $ref: '#/components/parameters/hasHLSFiles' - $ref: '#/components/parameters/hasWebVideoFiles' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/videosSearchSort' - $ref: '#/components/parameters/excludeAlreadyWatched' - $ref: '#/components/parameters/host' - name: startDate in: query description: Get videos that are published after this date schema: type: string format: date-time - name: endDate in: query description: Get videos that are published before this date schema: type: string format: date-time - name: originallyPublishedStartDate in: query description: Get videos that are originally published after this date schema: type: string format: date-time - name: originallyPublishedEndDate in: query description: Get videos that are originally published before this date schema: type: string format: date-time - name: durationMin in: query description: Get videos that have this minimum duration schema: type: integer - name: durationMax in: query description: Get videos that have this maximum duration schema: type: integer callbacks: 'searchTarget === search-index': $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '500': description: search index unavailable /api/v1/search/video-channels: get: tags: - Search - Video Channels 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' - $ref: '#/components/parameters/host' - $ref: '#/components/parameters/handles' 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 /api/v1/search/video-playlists: get: tags: - Search - Video Playlists 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 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' - $ref: '#/components/parameters/host' - $ref: '#/components/parameters/uuids' 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 /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 summary: List account blocks security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation post: tags: - Account Blocks summary: Block an account security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: accountName: type: string example: chocobozzz@example.org description: account to block, in the form `username@domain` required: - accountName responses: '200': description: successful operation '409': description: self-blocking forbidden '/api/v1/server/blocklist/accounts/{accountName}': delete: tags: - Account Blocks summary: Unblock an account by its handle security: - OAuth2: - admin parameters: - name: accountName in: path required: true description: account to unblock, in the form `username@domain` schema: type: string responses: '201': description: successful operation '404': description: account or account block does not exist /api/v1/server/blocklist/servers: get: tags: - Server Blocks summary: List server blocks security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation post: tags: - Server Blocks summary: Block a server security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: host: type: string format: hostname description: server domain to block required: - host responses: '204': description: successful operation '409': description: self-blocking forbidden '/api/v1/server/blocklist/servers/{host}': delete: tags: - Server Blocks summary: Unblock a server by its domain security: - OAuth2: - admin parameters: - name: host in: path required: true description: server domain to unblock schema: type: string format: hostname responses: '204': description: successful operation '404': description: account block does not exist /api/v1/server/redundancy/{host}: put: tags: - Instance Redundancy summary: Update a server redundancy policy security: - OAuth2: - admin parameters: - name: host in: path required: true description: server domain to mirror schema: type: string format: hostname requestBody: content: application/json: schema: type: object properties: redundancyAllowed: type: boolean description: allow mirroring of the host's local videos required: - redundancyAllowed responses: '204': description: successful operation '404': description: server is not already known /api/v1/server/redundancy/videos: get: tags: - Video Mirroring summary: List videos being mirrored operationId: getMirroredVideos security: - OAuth2: - admin parameters: - name: target in: query required: true description: direction of the mirror schema: type: string enum: - my-videos - remote-videos - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videoRedundanciesSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoRedundancy' post: tags: - Video Mirroring summary: Mirror a video operationId: putMirroredVideo security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: videoId: $ref: '#/components/schemas/Video/properties/id' required: - videoId responses: '204': description: successful operation '400': description: cannot mirror a local video '404': description: video does not exist '409': description: video is already mirrored /api/v1/server/redundancy/videos/{redundancyId}: delete: tags: - Video Mirroring summary: Delete a mirror done on a video operationId: delMirroredVideo security: - OAuth2: - admin parameters: - name: redundancyId in: path required: true description: id of an existing redundancy on a video schema: type: string responses: '204': description: successful operation '404': description: video redundancy not found /api/v1/server/stats: get: tags: - Stats summary: Get instance stats description: Get instance public statistics. This endpoint is cached. operationId: getInstanceStats responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerStats' /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 /api/v1/server/logs: get: tags: - Logs summary: Get instance logs operationId: getInstanceLogs security: - OAuth2: - admin responses: '200': description: successful operation content: application/json: schema: type: array items: type: string /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: array items: type: string /api/v1/plugins: get: tags: - Plugins summary: List plugins operationId: getPlugins security: - OAuth2: - admin parameters: - name: pluginType in: query schema: type: integer - name: uninstalled in: query schema: type: boolean - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/PluginResponse' /api/v1/plugins/available: get: tags: - Plugins summary: List available plugins operationId: getAvailablePlugins security: - OAuth2: - admin parameters: - name: search in: query schema: type: string - name: pluginType in: query schema: type: integer - name: currentPeerTubeEngine in: query schema: type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/PluginResponse' '503': description: plugin index unavailable /api/v1/plugins/install: post: tags: - Plugins summary: Install a plugin operationId: addPlugin security: - OAuth2: - admin requestBody: content: application/json: schema: oneOf: - type: object properties: npmName: type: string example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false - type: object properties: path: type: string required: - path additionalProperties: false responses: '204': description: successful operation '400': description: should have either `npmName` or `path` set /api/v1/plugins/update: post: tags: - Plugins summary: Update a plugin operationId: updatePlugin security: - OAuth2: - admin requestBody: content: application/json: schema: oneOf: - type: object properties: npmName: type: string example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false - type: object properties: path: type: string required: - path additionalProperties: false responses: '204': description: successful operation '400': description: should have either `npmName` or `path` set '404': description: existing plugin not found /api/v1/plugins/uninstall: post: tags: - Plugins summary: Uninstall a plugin operationId: uninstallPlugin security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: npmName: type: string description: name of the plugin/theme in its package.json example: peertube-plugin-auth-ldap required: - npmName responses: '204': description: successful operation '404': description: existing plugin not found /api/v1/plugins/{npmName}: get: tags: - Plugins summary: Get a plugin operationId: getPlugin security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Plugin' '404': description: plugin not found /api/v1/plugins/{npmName}/settings: put: tags: - Plugins summary: Set a plugin's settings security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' requestBody: content: application/json: schema: type: object properties: settings: type: object additionalProperties: true responses: '204': description: successful operation '404': description: plugin not found /api/v1/plugins/{npmName}/public-settings: get: tags: - Plugins summary: Get a plugin's public settings parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: type: object additionalProperties: true '404': description: plugin not found /api/v1/plugins/{npmName}/registered-settings: get: tags: - Plugins summary: Get a plugin's registered settings security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: type: object additionalProperties: true '404': description: plugin not found /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 /api/v1/runners/registration-tokens/generate: post: summary: Generate registration token description: Generate a new runner registration token security: - OAuth2: - admin tags: - Runner Registration Token responses: '204': description: successful operation /api/v1/runners/registration-tokens/{registrationTokenId}: delete: summary: Remove registration token description: Remove a registration token. Runners that used this token for their registration are automatically removed. security: - OAuth2: - admin tags: - Runner Registration Token parameters: - $ref: '#/components/parameters/registrationTokenId' responses: '204': description: successful operation /api/v1/runners/registration-tokens: get: summary: List registration tokens security: - OAuth2: - admin tags: - Runner Registration Token parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/registrationTokenSort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/RunnerRegistrationToken' /api/v1/runners/register: post: summary: Register a new runner description: API used by PeerTube runners tags: - Runners requestBody: content: application/json: schema: type: object properties: registrationToken: type: string name: type: string description: type: string required: - registrationToken - name responses: '200': description: successful operation content: application/json: schema: type: object properties: id: type: integer description: Runner id runnerToken: type: string /api/v1/runners/unregister: post: summary: Unregister a runner description: API used by PeerTube runners tags: - Runners requestBody: content: application/json: schema: type: object properties: runnerToken: type: string required: - runnerToken responses: '204': description: successful operation /api/v1/runners/{runnerId}: delete: summary: Delete a runner security: - OAuth2: - admin tags: - Runners parameters: - $ref: '#/components/parameters/runnerId' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string required: - runnerToken responses: '204': description: successful operation /api/v1/runners: get: summary: List runners security: - OAuth2: - admin tags: - Runners parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/runnerSort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/Runner' /api/v1/runners/jobs/request: post: summary: Request a new job description: API used by PeerTube runners tags: - Runner Jobs requestBody: content: application/json: schema: type: object properties: runnerToken: type: string required: - runnerToken responses: '200': description: successful operation content: application/json: schema: type: object properties: availableJobs: type: array items: type: object properties: uuid: $ref: '#/components/schemas/UUIDv4' type: $ref: '#/components/schemas/RunnerJobType' payload: $ref: '#/components/schemas/RunnerJobPayload' /api/v1/runners/jobs/{jobUUID}/accept: post: summary: Accept job description: API used by PeerTube runners tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string required: - runnerToken responses: '200': description: successful operation content: application/json: schema: type: object properties: job: allOf: - $ref: '#/components/schemas/RunnerJob' - type: object properties: jobToken: type: string /api/v1/runners/jobs/{jobUUID}/abort: post: summary: Abort job description: API used by PeerTube runners tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string jobToken: type: string reason: type: string description: Why the runner aborts this job required: - runnerToken - jobToken - reason responses: '204': description: successful operation /api/v1/runners/jobs/{jobUUID}/update: post: summary: Update job description: API used by PeerTube runners tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string jobToken: type: string progress: type: integer description: Update job progression percentage (optional) payload: anyOf: - type: object description: Provide live transcoding chunks update properties: type: type: string enum: - 'add-chunk' - 'remove-chunk' masterPlaylistFile: type: string format: binary resolutionPlaylistFile: type: string format: binary resolutionPlaylistFilename: type: string videoChunkFile: type: string format: binary videoChunkFilename: type: string required: - runnerToken - jobToken responses: '204': description: successful operation /api/v1/runners/jobs/{jobUUID}/error: post: summary: Post job error description: API used by PeerTube runners tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string jobToken: type: string message: type: string description: Why the runner failed to process this job required: - runnerToken - jobToken - message responses: '204': description: successful operation /api/v1/runners/jobs/{jobUUID}/success: post: summary: Post job success description: API used by PeerTube runners tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' requestBody: content: application/json: schema: type: object properties: runnerToken: type: string jobToken: type: string payload: anyOf: - type: object title: VOD web video transcoding properties: videoFile: type: string format: binary - type: object title: VOD HLS transcoding properties: videoFile: type: string format: binary resolutionPlaylistFile: type: string format: binary - type: object title: VOD audio merge transcoding properties: videoFile: type: string format: binary - type: object title: Live RTMP to HLS transcoding required: - runnerToken - jobToken - payload responses: '204': description: successful operation /api/v1/runners/jobs/{jobUUID}/cancel: get: summary: Cancel a job security: - OAuth2: - admin tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' responses: '204': description: successful operation /api/v1/runners/jobs/{jobUUID}: delete: summary: Delete a job description: The endpoint will first cancel the job if needed, and then remove it from the database. Children jobs will also be removed security: - OAuth2: - admin tags: - Runner Jobs parameters: - $ref: '#/components/parameters/jobUUID' responses: '204': description: successful operation /api/v1/runners/jobs: get: summary: List jobs security: - OAuth2: - admin tags: - Runner Jobs parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/runnerJobSort' - $ref: '#/components/parameters/search' - name: stateOneOf in: query required: false schema: type: array items: $ref: '#/components/schemas/RunnerJobState' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/RunnerJobAdmin' /api/v1/automatic-tags/policies/accounts/{accountName}/comments: get: tags: - Automatic Tags summary: Get account auto tag policies on comments description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true description: account name to get auto tag policies schema: type: string responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentAutoTagPolicies' put: tags: - Automatic Tags summary: Update account auto tag policies on comments description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true description: account name to update auto tag policies schema: type: string requestBody: content: application/json: schema: type: object properties: review: description: 'Auto tags that automatically set the comment in review state' type: array items: type: string responses: '204': description: successful operation /api/v1/automatic-tags/accounts/{accountName}/available: get: tags: - Automatic Tags summary: Get account available auto tags description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true description: account name to get auto tag policies schema: type: string responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/AutomaticTagAvailable' /api/v1/automatic-tags/server/available: get: tags: - Automatic Tags summary: Get server available auto tags description: "**PeerTube >= 6.2**" security: - OAuth2: - admin - moderator responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/AutomaticTagAvailable' /api/v1/watched-words/accounts/{accountName}/lists: get: tags: - Watched Words summary: List account watched words description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true description: account name to list watched words schema: type: string responses: '200': description: successful operation content: application/json: schema: properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/WatchedWordsLists' post: tags: - Watched Words summary: Add account watched words description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: listName: type: string words: type: array items: type: string responses: '200': description: successful operation content: application/json: schema: type: object properties: watchedWordsList: type: object properties: id: type: integer /api/v1/watched-words/accounts/{accountName}/lists/{listId}: put: tags: - Watched Words summary: Update account watched words description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true schema: type: string - name: listId in: path required: true description: list of watched words to update schema: type: string requestBody: content: application/json: schema: type: object properties: listName: type: string words: type: array items: type: string responses: '204': description: successful operation delete: tags: - Watched Words summary: Delete account watched words description: "**PeerTube >= 6.2**" security: - OAuth2: [] parameters: - name: accountName in: path required: true schema: type: string - name: listId in: path required: true description: list of watched words to delete schema: type: string responses: '204': description: successful operation /api/v1/watched-words/server/lists: get: tags: - Watched Words summary: List server watched words description: "**PeerTube >= 6.2**" security: - OAuth2: - admin - moderator responses: '200': description: successful operation content: application/json: schema: properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/WatchedWordsLists' post: tags: - Watched Words summary: Add server watched words description: "**PeerTube >= 6.2**" security: - OAuth2: - admin - moderator requestBody: content: application/json: schema: type: object properties: listName: type: string words: type: array items: type: string responses: '200': description: successful operation content: application/json: schema: type: object properties: watchedWordsList: type: object properties: id: type: integer /api/v1/watched-words/server/lists/{listId}: put: tags: - Watched Words summary: Update server watched words description: "**PeerTube >= 6.2**" security: - OAuth2: - admin - moderator parameters: - name: listId in: path required: true description: list of watched words to update schema: type: string requestBody: content: application/json: schema: type: object properties: listName: type: string words: type: array items: type: string responses: '204': description: successful operation delete: tags: - Watched Words summary: Delete server watched words description: "**PeerTube >= 6.2**" security: - OAuth2: - admin - moderator parameters: - name: listId in: path required: true description: list of watched words to delete schema: type: string responses: '204': description: successful operation servers: - url: 'https://peertube2.cpy.re' description: Live Test Server (live data - latest nightly version) - url: 'https://peertube3.cpy.re' description: Live Test Server (live data - latest RC version) - url: 'https://peertube.cpy.re' description: Live Test Server (live data - stable version) components: parameters: start: name: start in: query required: false description: Offset used to paginate results schema: type: integer minimum: 0 count: name: count in: query required: false description: "Number of items to return" schema: type: integer default: 15 maximum: 100 minimum: 1 sort: name: sort in: query required: false description: Sort column schema: type: string example: -createdAt search: name: search in: query required: false description: Plain text search, applied to various parts of the model depending on endpoint schema: type: string searchTarget: name: searchTarget in: query required: false description: > If the administrator enabled search index support, you can override the default search target. **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information: * If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API schema: type: string enum: - 'local' - 'search-index' videosSort: name: sort in: query required: false schema: type: string enum: - 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 (prefixing with `-` means `DESC` order): schema: type: string enum: - name - -duration - -createdAt - -publishedAt - -views - -likes - -match commentsSort: name: sort in: query required: false description: Sort comments by criteria schema: type: string enum: - -createdAt - -totalReplies blacklistsSort: name: sort in: query required: false description: Sort blocklists by criteria schema: type: string enum: - -id - name - -duration - -views - -likes - -dislikes - -uuid - -createdAt usersSearch: name: search in: query required: false description: Plain text search that will match with user usernames or emails schema: type: string usersBlocked: name: blocked in: query required: false description: Filter results down to (un)banned users schema: type: boolean usersSort: name: sort in: query required: false description: Sort users by criteria schema: type: string enum: - -id - -username - -createdAt abusesSort: name: sort in: query required: false description: Sort abuses by criteria schema: type: string enum: - -id - -createdAt - -state videoRedundanciesSort: name: sort in: query required: false description: Sort abuses by criteria schema: type: string enum: - name followersSort: name: sort in: query required: false description: Sort followers by criteria schema: type: string enum: - createdAt registrationTokenSort: name: sort in: query required: false description: Sort registration tokens by criteria schema: type: string enum: - createdAt runnerSort: name: sort in: query required: false description: Sort runners by criteria schema: type: string enum: - createdAt runnerJobSort: name: sort in: query required: false description: Sort runner jobs by criteria schema: type: string enum: - updatedAt - createdAt - priority - state - progress name: name: name in: path required: true description: The username or handle of the account schema: type: string example: chocobozzz | chocobozzz@example.org id: name: id in: path required: true description: Entity id schema: $ref: '#/components/schemas/id' userId: name: userId in: path required: true description: User id schema: $ref: '#/components/schemas/id' registrationId: name: registrationId in: path required: true description: Registration ID schema: $ref: '#/components/schemas/id' idOrUUID: name: id in: path required: true 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 required: true description: Playlist id schema: $ref: '#/components/schemas/VideoPlaylist/properties/id' playlistElementId: name: playlistElementId in: path required: true description: Playlist element id schema: $ref: '#/components/schemas/id' abuseId: name: abuseId in: path required: true description: Abuse id schema: $ref: '#/components/schemas/Abuse/properties/id' abuseMessageId: name: abuseMessageId in: path required: true description: Abuse message id schema: $ref: '#/components/schemas/AbuseMessage/properties/id' captionLanguage: name: captionLanguage in: path required: true description: The caption language schema: $ref: '#/components/schemas/VideoLanguageSet' channelHandle: name: channelHandle in: path required: true description: The video channel handle 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 required: true description: The subscription handle schema: type: string example: my_username | my_username@example.com threadId: name: threadId in: path required: true description: The thread id (root comment id) schema: type: integer commentId: name: commentId in: path required: true description: The comment id schema: $ref: '#/components/schemas/VideoComment/properties/id' isLive: name: isLive in: query required: false description: whether or not the video is a live schema: type: boolean categoryOneOf: name: categoryOneOf in: query required: false description: category id of the video (see [/videos/categories](#operation/getCategories)) schema: oneOf: - $ref: '#/components/schemas/VideoCategorySet' - type: array items: $ref: '#/components/schemas/VideoCategorySet' style: form explode: true tagsOneOf: name: tagsOneOf in: query required: false description: tag(s) of the video schema: oneOf: - type: string - type: array maxItems: 5 items: type: string style: form explode: true tagsAllOf: name: tagsAllOf in: query required: false description: tag(s) of the video, where all should be present in the video schema: oneOf: - type: string - type: array items: type: string style: form explode: true languageOneOf: name: languageOneOf in: query required: false description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language schema: oneOf: - $ref: '#/components/schemas/VideoLanguageSet' - type: array items: $ref: '#/components/schemas/VideoLanguageSet' style: form explode: true autoTagOneOfVideo: name: autoTagOneOf in: query required: false description: "**PeerTube >= 6.2** **Admins and moderators only** filter on videos that contain one of these automatic tags" schema: oneOf: - type: string - type: array items: type: string style: form explode: true autoTagOneOfComment: name: autoTagOneOf in: query required: false description: "**PeerTube >= 6.2** filter on comments that contain one of these automatic tags" schema: oneOf: - type: string - type: array items: type: string style: form explode: true isHeldForReview: name: isHeldForReview in: query required: false description: only display comments that are held for review schema: type: boolean licenceOneOf: name: licenceOneOf in: query required: false description: licence id of the video (see [/videos/licences](#operation/getLicences)) schema: oneOf: - $ref: '#/components/schemas/VideoLicenceSet' - type: array items: $ref: '#/components/schemas/VideoLicenceSet' style: form explode: true skipCount: name: skipCount in: query required: false description: if you don't need the `total` in the response schema: type: string enum: - 'true' - 'false' default: 'false' nsfw: name: nsfw in: query required: false description: whether to include nsfw videos, if any schema: type: string enum: - 'true' - 'false' isLocal: name: isLocal in: query required: false schema: type: boolean description: '**PeerTube >= 4.0** Display only local or remote objects' hasHLSFiles: name: hasHLSFiles in: query required: false schema: type: boolean description: '**PeerTube >= 4.0** Display only videos that have HLS files' hasWebVideoFiles: name: hasWebVideoFiles in: query required: false schema: type: boolean description: '**PeerTube >= 6.0** Display only videos that have Web Video 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' excludeAlreadyWatched: name: excludeAlreadyWatched in: query description: Whether or not to exclude videos that are in the user's video history schema: type: boolean uuids: name: uuids in: query required: false schema: items: type: string description: 'Find elements with specific UUIDs' host: name: host in: query required: false schema: type: string description: 'Find elements owned by this host' handles: name: handles in: query required: false schema: items: type: string description: 'Find elements with these handles' include: name: include in: query required: false schema: type: integer enum: - 0 - 1 - 2 - 4 - 8 - 16 - 32 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 - `16` CAPTIONS - `32` VIDEO SOURCE subscriptionsUris: name: uris in: query required: true description: list of uris to check if each is part of the user subscriptions schema: type: array items: type: string format: uri npmName: name: npmName in: path required: true description: name of the plugin/theme on npmjs.com or in its package.json schema: type: string example: peertube-plugin-auth-ldap jobType: name: jobType in: query required: false description: job type schema: type: string enum: - activitypub-follow - activitypub-http-broadcast - activitypub-http-fetcher - activitypub-http-unicast - email - video-transcoding - video-file-import - video-import - videos-views-stats - activitypub-refresher - video-redundancy - video-live-ending - video-channel-import 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 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 videoPlaylistType: name: playlistType in: query required: false schema: $ref: '#/components/schemas/VideoPlaylistTypeSet' registrationTokenId: name: registrationTokenId in: path required: true schema: type: integer runnerId: name: runnerId in: path required: true schema: type: integer jobUUID: name: jobUUID in: path required: true schema: $ref: '#/components/schemas/UUIDv4' videoPasswordId: name: videoPasswordId in: path required: true description: The video password id schema: $ref: '#/components/schemas/id' onLocalVideo: name: onLocalVideo in: query required: false schema: type: boolean description: 'Display only objects of local or remote videos' videoChannelId: name: videoChannelId in: query required: false schema: type: integer description: 'Limit results on this specific video channel' videoId: name: videoId in: query required: false schema: type: integer description: 'Limit results on this specific video' searchVideoForComments: name: searchVideo in: query required: false description: Filter comments by searching on the video schema: type: string searchAccountForComments: name: searchAccount in: query required: false description: Filter comments by searching on the account schema: type: string videoPasswordHeader: name: x-peertube-video-password description: Required on password protected video in: header required: false schema: type: string resumableUploadInitContentLengthHeader: name: X-Upload-Content-Length in: header schema: type: number example: 2469036 required: true description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading. resumableUploadInitContentTypeHeader: name: X-Upload-Content-Type in: header schema: type: string format: mimetype example: video/mp4 required: true description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary. resumableUploadChunkContentRangeHeader: name: Content-Range in: header schema: type: string example: bytes 0-262143/2469036 required: true description: | Specifies the bytes in the file that the request is uploading. For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first 262144 bytes (256 x 1024) in a 2,469,036 byte file. resumableUploadChunkContentLengthHeader: name: Content-Length in: header schema: type: number example: 262144 required: true description: | Size of the chunk that the request is sending. 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. resumableUploadId: name: upload_id in: query required: true description: | 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 securitySchemes: OAuth2: description: | Authenticating via OAuth requires the following steps: - Have an activated account - [Generate] an access token for that account at `/api/v1/users/token`. - Make requests with the *Authorization: Bearer * header - Profit, depending on the role assigned to the account Note that the __access token is valid for 1 day__ and is given along with a __refresh token valid for 2 weeks__. [Generate]: https://docs.joinpeertube.org/api/rest-getting-started type: oauth2 flows: password: tokenUrl: /api/v1/users/token scopes: admin: Admin scope moderator: Moderator scope user: User scope schemas: # Reusable core properties id: type: integer minimum: 1 example: 42 UUIDv4: type: string format: uuid example: 9c9de5e8-0a1e-484a-b099-e80766180a6d pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' 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 example: chocobozzz pattern: '/^[a-z0-9._]+$/' minLength: 1 maxLength: 50 usernameChannel: type: string description: immutable name of the channel, used to interact with its actor example: framasoft_videos pattern: '/^[a-zA-Z0-9\\-_.:]+$/' minLength: 1 maxLength: 50 password: type: string format: password minLength: 6 maxLength: 255 VideoCategorySet: type: integer description: category id of the video (see [/videos/categories](#operation/getCategories)) example: 15 VideoConstantNumber-Category: properties: id: $ref: '#/components/schemas/VideoCategorySet' label: type: string example: Science & Technology VideoLicenceSet: type: integer description: licence id of the video (see [/videos/licences](#operation/getLicences)) example: 2 VideoConstantNumber-Licence: properties: id: $ref: '#/components/schemas/VideoLicenceSet' label: type: string example: Attribution - Share Alike VideoLanguageSet: type: string description: language id of the video (see [/videos/languages](#operation/getLanguages)) example: en VideoConstantString-Language: properties: id: $ref: '#/components/schemas/VideoLanguageSet' label: type: string example: English VideoPlaylistPrivacySet: type: integer enum: - 1 - 2 - 3 description: Video playlist privacy policy (see [/video-playlists/privacies](#operation/getPlaylistPrivacyPolicies)) VideoPlaylistPrivacyConstant: properties: id: $ref: '#/components/schemas/VideoPlaylistPrivacySet' label: type: string VideoPlaylistTypeSet: type: integer enum: - 1 - 2 description: The video playlist type (Regular = `1`, Watch Later = `2`) VideoPlaylistTypeConstant: properties: id: $ref: '#/components/schemas/VideoPlaylistTypeSet' label: type: string VideoPrivacySet: type: integer enum: - 1 - 2 - 3 - 4 - 5 description: privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies)) VideoPrivacyConstant: properties: id: $ref: '#/components/schemas/VideoPrivacySet' label: type: string VideoCommentsPolicySet: type: integer enum: - 1 - 2 - 3 description: Comments policy of the video (Enabled = `1`, Disabled = `2`, Requires Approval = `3`) VideoCommentsPolicyConstant: properties: id: $ref: '#/components/schemas/VideoCommentsPolicySet' 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: - display - blur - do_not_list UserRole: type: integer enum: - 0 - 1 - 2 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)' example: 2 UserAdminFlags: type: integer enum: - 0 - 1 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)' example: 1 LiveVideoLatencyMode: type: integer enum: - 1 - 2 - 3 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)' LiveVideoReplaySettings: type: object properties: privacy: # description: Video playlist privacy policy (see [../video-playlists/privacies]) $ref: '#/components/schemas/VideoPrivacySet' VideoStateConstant: properties: id: type: integer enum: - 1 - 2 - 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 UserExportState: type: integer enum: - 1 - 2 - 3 - 4 description: | The user export state: - `1`: Pending - `2`: Processing - `3`: Completed - `4`: Errored UserImportState: type: integer enum: - 1 - 2 - 3 - 4 description: | The user import state: - `1`: Pending - `2`: Processing - `3`: Completed - `4`: Errored AbuseStateSet: type: integer enum: - 1 - 2 - 3 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)' AbuseStateConstant: properties: id: $ref: '#/components/schemas/AbuseStateSet' label: type: string AbusePredefinedReasons: type: array items: type: string enum: - violentOrAbusive - hatefulOrAbusive - spamOrMisleading - privacy - rights - serverRules - thumbnails - captions example: [spamOrMisleading] VideoResolutionSet: type: integer description: | Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`) `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos. example: 240 VideoResolutionConstant: description: resolutions and their labels for the video properties: id: $ref: '#/components/schemas/VideoResolutionSet' label: type: string example: 240p VideoScheduledUpdate: properties: privacy: $ref: '#/components/schemas/VideoPrivacySet' updateAt: type: string format: date-time description: When to update the video required: - updateAt AccountSummary: properties: id: type: integer name: type: string displayName: type: string url: type: string format: url host: type: string format: hostname avatars: type: array items: $ref: '#/components/schemas/ActorImage' VideoChannelSummary: properties: id: $ref: '#/components/schemas/id' name: type: string displayName: type: string url: type: string format: url host: type: string format: hostname avatars: type: array items: $ref: '#/components/schemas/ActorImage' PlaylistElement: properties: position: type: integer startTimestamp: type: integer format: seconds stopTimestamp: type: integer format: seconds video: nullable: true allOf: - $ref: '#/components/schemas/Video' 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 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i resolution: $ref: '#/components/schemas/VideoResolutionConstant' size: type: integer description: Video file size in bytes torrentUrl: type: string description: Direct URL of the torrent file format: url torrentDownloadUrl: type: string description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog) format: url fileUrl: type: string description: Direct URL of the video format: url fileDownloadUrl: type: string description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog) format: url fps: type: number description: Frames per second of the video file width: type: number description: "**PeerTube >= 6.1** Video stream width" height: type: number description: "**PeerTube >= 6.1** Video stream height" metadataUrl: type: string format: url description: URL dereferencing the output of ffprobe on the file VideoStreamingPlaylists: allOf: - type: object properties: id: $ref: '#/components/schemas/id' type: type: integer enum: - 1 description: | Playlist type: - `1`: HLS - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS' VideoStreamingPlaylists-HLS: properties: playlistUrl: type: string format: url segmentsSha256Url: type: string format: url files: type: array description: | Video files associated to this playlist. The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.) items: $ref: '#/components/schemas/VideoFile' redundancies: type: array items: type: object properties: baseUrl: type: string format: url VideoInfo: properties: id: $ref: '#/components/schemas/Video/properties/id' uuid: $ref: '#/components/schemas/Video/properties/uuid' name: $ref: '#/components/schemas/Video/properties/name' Video: properties: id: description: object id for the video allOf: - $ref: '#/components/schemas/id' uuid: 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: type: string format: date-time example: 2017-10-01T10:52:46.396Z description: time at which the video object was first drafted publishedAt: type: string format: date-time example: 2018-10-01T10:52:46.396Z description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution. updatedAt: type: string format: date-time example: 2021-05-04T08:01:01.502Z description: last time the video's metadata was modified originallyPublishedAt: type: string nullable: true format: date-time example: 2010-10-01T10:52:46.396Z description: used to represent a date of first publication, prior to the practical publication date of `publishedAt` category: allOf: - $ref: '#/components/schemas/VideoConstantNumber-Category' description: category in which the video is classified licence: allOf: - $ref: '#/components/schemas/VideoConstantNumber-Licence' description: licence under which the video is distributed language: allOf: - $ref: '#/components/schemas/VideoConstantString-Language' description: main language used in the video privacy: allOf: - $ref: '#/components/schemas/VideoPrivacyConstant' description: privacy policy used to distribute the video truncatedDescription: type: string nullable: true example: | **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr... minLength: 3 maxLength: 250 description: | truncated description of the video, written in Markdown. duration: type: integer example: 1419 format: seconds description: duration of the video in seconds aspectRatio: type: number nullable: true format: float example: 1.778 description: "**PeerTube >= 6.1** Aspect ratio of the video stream" isLocal: type: boolean name: type: string description: title of the video example: What is PeerTube? minLength: 3 maxLength: 120 thumbnailPath: type: string example: /lazy-static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg previewPath: type: string example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg embedPath: type: string example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee views: type: integer example: 1337 likes: type: integer example: 42 dislikes: type: integer example: 7 nsfw: type: boolean waitTranscoding: type: boolean nullable: true state: allOf: - $ref: '#/components/schemas/VideoStateConstant' description: represents the internal state of the video processing within the PeerTube instance scheduledUpdate: nullable: true allOf: - $ref: '#/components/schemas/VideoScheduledUpdate' blacklisted: nullable: true type: boolean blacklistedReason: nullable: true type: string account: $ref: '#/components/schemas/AccountSummary' channel: $ref: '#/components/schemas/VideoChannelSummary' userHistory: nullable: true type: object properties: currentTime: type: integer VideoDetails: allOf: - $ref: '#/components/schemas/Video' - type: object properties: viewers: type: integer description: If the video is a live, you have the amount of current viewers description: type: string nullable: true example: | "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on free/libre software!*\r\n\r\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\r\n *Directed by* Aryeom\r\n*Assistant* Jehan\r\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\r\n\r\n **Sponsored by** [Framasoft](https://framasoft.org)\r\n\r\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\r\n\r\n **Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\r\n\r\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/" minLength: 3 maxLength: 1000 description: | full description of the video, written in Markdown. support: type: string nullable: true description: A text tell the audience how to support the video creator example: Please support our work on https://soutenir.framasoft.org/en/ <3 minLength: 3 maxLength: 1000 channel: $ref: '#/components/schemas/VideoChannel' account: $ref: '#/components/schemas/Account' tags: example: [flowers, gardening] type: array minItems: 1 maxItems: 5 items: type: string minLength: 2 maxLength: 30 commentsEnabled: deprecated: true description: 'Deprecated in 6.2, use commentsPolicy instead' type: boolean commentsPolicy: $ref: '#/components/schemas/VideoCommentsPolicyConstant' downloadEnabled: type: boolean inputFileUpdatedAt: type: string format: date-time nullable: true description: Latest input file update. Null if the file has never been replaced since the original upload trackerUrls: type: array items: type: string format: url example: - https://peertube2.cpy.re/tracker/announce - wss://peertube2.cpy.re/tracker/socket files: type: array items: $ref: '#/components/schemas/VideoFile' description: | Web compatible video files. If Web Video is disabled on the server: - field will be empty - video files will be found in `streamingPlaylists[].files` field streamingPlaylists: type: array items: $ref: '#/components/schemas/VideoStreamingPlaylists' description: | HLS playlists/manifest files. If HLS is disabled on the server: - field will be empty - video files will be found in `files` field FileRedundancyInformation: properties: id: $ref: '#/components/schemas/id' fileUrl: type: string format: url strategy: type: string enum: - manual - most-views - trending - recently-added size: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time expiresOn: type: string format: date-time VideoRedundancy: properties: id: $ref: '#/components/schemas/id' name: type: string url: type: string format: url uuid: $ref: '#/components/schemas/UUIDv4' redundancies: type: object properties: files: type: array items: $ref: '#/components/schemas/FileRedundancyInformation' streamingPlaylists: type: array items: $ref: '#/components/schemas/FileRedundancyInformation' CommentAutoTagPolicies: properties: review: type: array description: 'Auto tags that automatically set the comment in review state' items: type: string AutomaticTagAvailable: properties: available: type: array description: 'Available auto tags that can be used to filter objects or set a comment in review state' items: type: object properties: name: type: string description: tag name type: type: string enum: - 'core' - 'watched-words-list' VideoImportStateConstant: properties: id: type: integer enum: - 1 - 2 - 3 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)' label: type: string example: Pending VideoCreateImport: allOf: - type: object additionalProperties: false oneOf: - properties: targetUrl: $ref: '#/components/schemas/VideoImport/properties/targetUrl' required: [targetUrl] - properties: magnetUri: $ref: '#/components/schemas/VideoImport/properties/magnetUri' required: [magnetUri] - properties: torrentfile: $ref: '#/components/schemas/VideoImport/properties/torrentfile' required: [torrentfile] - $ref: '#/components/schemas/VideoUploadRequestCommon' required: - channelId - name VideoImport: properties: id: readOnly: true allOf: - $ref: '#/components/schemas/id' targetUrl: type: string format: url description: remote URL where to find the import's source video example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d magnetUri: type: string format: uri description: magnet URI allowing to resolve the import's source video pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i torrentfile: writeOnly: true type: string format: binary description: Torrent file containing only the video file torrentName: readOnly: true type: string state: readOnly: true allOf: - $ref: '#/components/schemas/VideoImportStateConstant' error: readOnly: true type: string createdAt: readOnly: true type: string format: date-time updatedAt: readOnly: true type: string format: date-time video: readOnly: true nullable: true allOf: - $ref: '#/components/schemas/Video' VideoImportsList: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/VideoImport' Abuse: properties: id: $ref: '#/components/schemas/id' reason: type: string example: The video is a spam minLength: 2 maxLength: 3000 predefinedReasons: $ref: '#/components/schemas/AbusePredefinedReasons' reporterAccount: $ref: '#/components/schemas/Account' state: $ref: '#/components/schemas/AbuseStateConstant' moderationComment: type: string example: Decided to ban the server since it spams us regularly minLength: 2 maxLength: 3000 video: $ref: '#/components/schemas/VideoInfo' createdAt: type: string format: date-time AbuseMessage: properties: id: $ref: '#/components/schemas/id' message: type: string minLength: 2 maxLength: 3000 byModerator: type: boolean createdAt: type: string format: date-time account: $ref: '#/components/schemas/AccountSummary' VideoBlacklist: properties: id: $ref: '#/components/schemas/id' videoId: $ref: '#/components/schemas/Video/properties/id' createdAt: type: string format: date-time updatedAt: type: string format: date-time name: type: string minLength: 3 maxLength: 120 uuid: $ref: '#/components/schemas/UUIDv4' description: type: string minLength: 3 maxLength: 10000 duration: type: integer views: type: integer likes: type: integer dislikes: type: integer nsfw: type: boolean VideoPlaylist: properties: id: $ref: '#/components/schemas/id' uuid: $ref: '#/components/schemas/UUIDv4' shortUUID: allOf: - $ref: '#/components/schemas/shortUUID' createdAt: type: string format: date-time updatedAt: type: string format: date-time description: type: string minLength: 3 maxLength: 1000 displayName: type: string minLength: 1 maxLength: 120 isLocal: type: boolean videoLength: type: integer minimum: 0 thumbnailPath: type: string privacy: $ref: '#/components/schemas/VideoPlaylistPrivacyConstant' type: $ref: '#/components/schemas/VideoPlaylistTypeConstant' ownerAccount: $ref: '#/components/schemas/AccountSummary' videoChannel: $ref: '#/components/schemas/VideoChannelSummary' VideoComment: properties: id: $ref: '#/components/schemas/id' url: type: string format: url text: type: string format: html description: Text of the comment minLength: 1 example: This video is wonderful! threadId: $ref: '#/components/schemas/id' inReplyToCommentId: nullable: true allOf: - $ref: '#/components/schemas/id' videoId: $ref: '#/components/schemas/Video/properties/id' createdAt: type: string format: date-time updatedAt: type: string format: date-time deletedAt: nullable: true type: string format: date-time default: null isDeleted: type: boolean default: false heldForReview: type: boolean totalRepliesFromVideoAuthor: type: integer minimum: 0 totalReplies: type: integer minimum: 0 account: $ref: '#/components/schemas/Account' VideoCommentThreadTree: properties: comment: $ref: '#/components/schemas/VideoComment' children: type: array items: $ref: '#/components/schemas/VideoCommentThreadTree' VideoCommentForOwnerOrAdmin: properties: id: $ref: '#/components/schemas/id' url: $ref: '#/components/schemas/VideoComment/properties/url' text: $ref: '#/components/schemas/VideoComment/properties/text' heldForReview: $ref: '#/components/schemas/VideoComment/properties/heldForReview' threadId: $ref: '#/components/schemas/VideoComment/properties/threadId' inReplyToCommentId: $ref: '#/components/schemas/VideoComment/properties/inReplyToCommentId' createdAt: $ref: '#/components/schemas/VideoComment/properties/createdAt' updatedAt: $ref: '#/components/schemas/VideoComment/properties/updatedAt' account: $ref: '#/components/schemas/VideoComment/properties/account' video: $ref: '#/components/schemas/VideoInfo' automaticTags: type: array items: type: string Storyboard: properties: storyboardPath: type: string totalHeight: type: integer totalWidth: type: integer spriteHeight: type: integer spriteWidth: type: integer spriteDuration: type: integer VideoCaption: properties: language: $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string VideoChapters: properties: chapters: type: object properties: title: type: string timecode: type: integer VideoSource: properties: filename: type: string deprecated: true description: 'Deprecated in 6.1, use inputFilename instead' inputFilename: type: string description: 'Uploaded/imported filename' fileDownloadUrl: type: string description: "**PeerTube >= 6.1** If enabled by the admin, the video source file is kept on the server and can be downloaded by the owner" resolution: $ref: '#/components/schemas/VideoResolutionConstant' description: "**PeerTube >= 6.1**" size: type: integer description: "**PeerTube >= 6.1** Video file size in bytes" fps: type: number description: "**PeerTube >= 6.1** Frames per second of the video file" width: type: number description: "**PeerTube >= 6.1** Video stream width" height: type: number description: "**PeerTube >= 6.1** Video stream height" createdAt: type: string format: date-time ActorImage: properties: path: type: string width: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time ActorInfo: properties: id: $ref: '#/components/schemas/id' name: type: string displayName: type: string host: type: string format: hostname avatars: type: array items: $ref: '#/components/schemas/ActorImage' Actor: properties: id: $ref: '#/components/schemas/id' url: type: string format: url name: description: immutable name of the actor, used to find or mention it allOf: - $ref: '#/components/schemas/username' avatars: type: array items: $ref: '#/components/schemas/ActorImage' host: type: string format: hostname description: server on which the actor is resident hostRedundancyAllowed: type: boolean description: whether this actor's host allows redundancy of its videos followingCount: type: integer minimum: 0 description: number of actors subscribed to by this actor, as seen by this instance followersCount: type: integer minimum: 0 description: number of followers of this actor, as seen by this instance createdAt: type: string format: date-time updatedAt: type: string format: date-time Account: allOf: - $ref: '#/components/schemas/Actor' - properties: userId: description: object id for the user tied to this account nullable: true allOf: - $ref: '#/components/schemas/User/properties/id' displayName: type: string description: editable name of the account, displayed in its representations minLength: 3 maxLength: 120 description: type: string nullable: true description: text or bio displayed on the account's profile 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 sessionId: type: string description: > Optional param to represent the current viewer session. Used by the backend to properly count one view per session per video. PeerTube admin can configure the server to not trust this `sessionId` parameter but use the request IP address instead to identify a viewer. 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: type: object properties: name: type: string shortDescription: type: string defaultClientRoute: type: string isNSFW: type: boolean defaultNSFWPolicy: type: string customizations: type: object properties: javascript: type: string css: type: string avatars: type: array items: $ref: '#/components/schemas/ActorImage' banners: type: array items: $ref: '#/components/schemas/ActorImage' search: type: object properties: remoteUri: type: object properties: users: type: boolean anonymous: type: boolean plugin: type: object properties: registered: type: array items: type: string theme: type: object properties: registered: type: array items: type: string email: type: object properties: enabled: type: boolean contactForm: type: object properties: enabled: type: boolean serverVersion: type: string serverCommit: type: string signup: type: object properties: allowed: type: boolean allowedForCurrentIP: type: boolean requiresEmailVerification: type: boolean transcoding: type: object properties: hls: type: object properties: enabled: type: boolean web_videos: type: object properties: enabled: type: boolean enabledResolutions: type: array items: $ref: '#/components/schemas/VideoResolutionSet' import: type: object properties: videos: type: object properties: http: type: object properties: enabled: type: boolean torrent: type: object properties: enabled: type: boolean videoChannelSynchronization: type: object properties: enabled: type: boolean users: type: object properties: enabled: type: boolean export: type: object properties: users: type: object properties: enabled: type: boolean exportExpiration: type: number description: In milliseconds maxUserVideoQuota: type: number description: In bytes autoBlacklist: type: object properties: videos: type: object properties: ofUsers: type: object properties: enabled: type: boolean avatar: type: object properties: file: type: object properties: size: type: object properties: max: type: integer extensions: type: array items: type: string video: type: object properties: image: type: object properties: extensions: type: array items: type: string size: type: object properties: max: type: integer file: type: object properties: extensions: type: array items: type: string videoCaption: type: object properties: file: type: object properties: size: type: object properties: max: type: integer extensions: type: array items: type: string user: type: object properties: videoQuota: type: integer description: In bytes example: 16810141515 videoQuotaDaily: type: integer description: In bytes example: 1681014151 trending: type: object properties: videos: type: object properties: intervalDays: type: integer tracker: type: object properties: enabled: type: boolean followings: type: object properties: instance: type: object properties: autoFollowIndex: type: object properties: indexUrl: type: string format: url homepage: type: object properties: enabled: type: boolean openTelemetry: type: object description: 'PeerTube >= 6.1' properties: metrics: type: object properties: enabled: type: boolean playbackStatsInterval: type: number description: 'Milliseconds' views: type: object description: 'PeerTube >= 6.1' properties: views: type: object properties: watchingInterval: type: object properties: anonymous: type: number description: 'Milliseconds' users: type: number description: 'Milliseconds' 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 totalModerators: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled total moderators stats" totalAdmins: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled total admins stats" 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 averageRegistrationRequestResponseTimeMs: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled registration requests stats" totalRegistrationRequestsProcessed: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled registration requests stats" totalRegistrationRequests: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled registration requests stats" averageAbuseResponseTimeMs: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled abuses stats" totalAbusesProcessed: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled abuses stats" totalAbuses: type: number description: "**PeerTube >= 6.1** Value is null if the admin disabled abuses stats" ServerConfigAbout: properties: instance: type: object properties: name: type: string shortDescription: type: string description: type: string terms: type: string codeOfConduct: type: string hardwareInformation: type: string creationReason: type: string moderationInformation: type: string administrator: type: string maintenanceLifetime: type: string businessModel: type: string languages: type: array items: type: string categories: type: array items: type: integer avatars: type: array items: $ref: '#/components/schemas/ActorImage' banners: type: array items: $ref: '#/components/schemas/ActorImage' ServerConfigCustom: properties: instance: type: object properties: name: type: string shortDescription: type: string description: type: string terms: type: string defaultClientRoute: type: string isNSFW: type: boolean defaultNSFWPolicy: type: string customizations: type: object properties: javascript: type: string css: type: string theme: type: object properties: default: type: string services: type: object properties: twitter: type: object properties: username: type: string cache: type: object properties: previews: type: object properties: size: type: integer captions: type: object properties: size: type: integer signup: type: object properties: enabled: type: boolean limit: type: integer requiresEmailVerification: type: boolean admin: type: object properties: email: type: string format: email contactForm: type: object properties: enabled: type: boolean user: type: object description: Settings that apply to new users, if registration is enabled properties: videoQuota: type: integer example: 16810141515 videoQuotaDaily: type: integer example: 1681014151 transcoding: type: object description: Settings pertaining to transcoding jobs properties: enabled: type: boolean originalFile: type: object properties: keep: type: boolean allowAdditionalExtensions: type: boolean description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos allowAudioFiles: type: boolean description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file threads: type: integer description: Amount of threads used by ffmpeg for 1 transcoding job concurrency: type: number description: Amount of transcoding jobs to execute in parallel profile: type: string enum: - default description: | New profiles can be added by plugins ; available in core PeerTube: 'default'. resolutions: type: object description: Resolutions to transcode _new videos_ to properties: 0p: type: boolean 144p: type: boolean 240p: type: boolean 360p: type: boolean 480p: type: boolean 720p: type: boolean 1080p: type: boolean 1440p: type: boolean 2160p: type: boolean web_videos: type: object description: Web Video specific settings properties: enabled: type: boolean hls: type: object description: HLS specific settings properties: enabled: type: boolean import: type: object properties: videos: type: object properties: http: type: object properties: enabled: type: boolean torrent: type: object properties: enabled: type: boolean video_channel_synchronization: type: object properties: enabled: type: boolean autoBlacklist: type: object properties: videos: type: object properties: ofUsers: type: object properties: enabled: type: boolean followers: type: object properties: instance: type: object properties: enabled: type: boolean manualApproval: type: boolean CustomHomepage: properties: content: type: string Follow: properties: id: $ref: '#/components/schemas/id' follower: $ref: '#/components/schemas/Actor' following: $ref: '#/components/schemas/Actor' score: type: number description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`. state: type: string enum: - pending - accepted createdAt: type: string format: date-time updatedAt: type: string format: date-time PredefinedAbuseReasons: description: Reason categories that help triage reports type: array maxItems: 8 items: type: string enum: - violentOrAbusive - hatefulOrAbusive - spamOrMisleading - privacy - rights - serverRules - thumbnails - captions Job: properties: id: $ref: '#/components/schemas/id' state: type: string enum: - active - completed - failed - waiting - delayed type: type: string enum: - activitypub-http-unicast - activitypub-http-broadcast - activitypub-http-fetcher - activitypub-follow - video-file-import - video-transcoding - email - video-import - videos-views-stats - activitypub-refresher - video-redundancy - video-channel-import data: type: object additionalProperties: true error: type: object additionalProperties: true createdAt: type: string format: date-time finishedOn: type: string format: date-time processedOn: type: string format: date-time AddUserResponse: properties: user: type: object properties: id: $ref: '#/components/schemas/id' account: type: object properties: id: $ref: '#/components/schemas/id' VideoUploadRequestCommon: properties: name: description: Video name type: string example: What is PeerTube? minLength: 3 maxLength: 120 channelId: description: Channel id that will contain this video type: integer example: 3 minimum: 1 privacy: $ref: '#/components/schemas/VideoPrivacySet' category: $ref: '#/components/schemas/VideoCategorySet' licence: $ref: '#/components/schemas/VideoLicenceSet' language: $ref: '#/components/schemas/VideoLanguageSet' description: description: Video description type: string example: | **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)** waitTranscoding: description: Whether or not we wait transcoding before publish the video type: boolean generateTranscription: description: "**PeerTube >= 6.2** If enabled by the admin, automatically generate a subtitle of the video" type: boolean support: description: A text tell the audience how to support the video creator example: Please support our work on https://soutenir.framasoft.org/en/ <3 type: string nsfw: description: Whether or not this video contains sensitive content type: boolean tags: description: Video tags (maximum 5 tags each between 2 and 30 characters) type: array minItems: 1 maxItems: 5 uniqueItems: true example: - framasoft - peertube items: type: string minLength: 2 maxLength: 30 commentsEnabled: deprecated: true description: 'Deprecated in 6.2, use commentsPolicy instead' type: boolean commentsPolicy: $ref: '#/components/schemas/VideoCommentsPolicySet' downloadEnabled: description: Enable or disable downloading for this video type: boolean originallyPublishedAt: description: Date when the content was originally published type: string format: date-time scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' thumbnailfile: description: Video thumbnail file type: string format: binary previewfile: description: Video preview file type: string format: binary videoPasswords: $ref: '#/components/schemas/AddVideoPasswords' required: - channelId - name VideoUploadRequestLegacy: allOf: - $ref: '#/components/schemas/VideoUploadRequestCommon' - type: object required: - videofile properties: videofile: description: Video file type: string format: binary VideoUploadRequestResumable: allOf: - $ref: '#/components/schemas/VideoUploadRequestCommon' - type: object required: - filename properties: filename: description: Video filename including extension type: string format: filename example: what_is_peertube.mp4 thumbnailfile: description: Video thumbnail file type: string format: binary previewfile: description: Video preview file type: string format: binary VideoUploadResponse: properties: video: type: object properties: id: $ref: '#/components/schemas/Video/properties/id' uuid: $ref: '#/components/schemas/Video/properties/uuid' shortUUID: $ref: '#/components/schemas/Video/properties/shortUUID' VideoReplaceSourceRequestResumable: properties: filename: description: Video filename including extension type: string format: filename example: what_is_peertube.mp4 UserImportResumable: properties: filename: description: Archive filename including extension type: string format: filename example: "user-export-6-2024-02-09T10_12_11.682Z" CommentThreadResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/VideoComment' CommentThreadPostResponse: properties: comment: $ref: '#/components/schemas/VideoComment' VideoTokenResponse: properties: files: type: object properties: token: type: string expires: type: string format: date-time VideoListResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Video' User: properties: account: $ref: '#/components/schemas/Account' autoPlayNextVideo: type: boolean description: Automatically start playing the upcoming video after the currently playing video autoPlayNextVideoPlaylist: type: boolean description: Automatically start playing the video on the playlist after the currently playing video autoPlayVideo: type: boolean description: Automatically start playing the video on the watch page blocked: type: boolean blockedReason: type: string createdAt: type: string email: type: string format: email description: The user email emailVerified: type: boolean description: Has the user confirmed their email address? id: allOf: - $ref: '#/components/schemas/id' readOnly: true pluginAuth: type: string description: Auth plugin to use to authenticate the user lastLoginDate: type: string format: date-time noInstanceConfigWarningModal: type: boolean noAccountSetupWarningModal: type: boolean noWelcomeModal: type: boolean nsfwPolicy: $ref: '#/components/schemas/NSFWPolicy' role: type: object properties: id: $ref: '#/components/schemas/UserRole' label: type: string enum: - User - Moderator - Administrator theme: type: string description: Theme enabled by this user username: $ref: '#/components/schemas/username' videoChannels: type: array items: $ref: '#/components/schemas/VideoChannel' videoQuota: type: integer description: The user video quota in bytes example: -1 videoQuotaDaily: type: integer description: The user daily video quota in bytes example: -1 p2pEnabled: type: boolean description: Enable P2P in the player UserWithStats: allOf: - $ref: '#/components/schemas/User' - properties: # optionally present fields: they require WITH_STATS scope videosCount: type: integer description: Count of videos published abusesCount: type: integer description: Count of reports/abuses of which the user is a target abusesAcceptedCount: type: integer description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team abusesCreatedCount: type: integer description: Count of reports/abuses created by the user videoCommentsCount: type: integer description: Count of comments published AddUser: properties: username: $ref: '#/components/schemas/username' password: $ref: '#/components/schemas/password' email: type: string format: email description: The user email videoQuota: type: integer description: The user video quota in bytes example: -1 videoQuotaDaily: type: integer description: The user daily video quota in bytes example: -1 channelName: $ref: '#/components/schemas/usernameChannel' role: $ref: '#/components/schemas/UserRole' adminFlags: $ref: '#/components/schemas/UserAdminFlags' required: - username - password - email - role UpdateUser: properties: email: description: The updated email of the user allOf: - $ref: '#/components/schemas/User/properties/email' emailVerified: type: boolean description: Set the email as verified videoQuota: type: integer description: The updated video quota of the user in bytes videoQuotaDaily: type: integer description: The updated daily video quota of the user in bytes pluginAuth: type: string nullable: true description: The auth plugin to use to authenticate the user example: 'peertube-plugin-auth-saml2' role: $ref: '#/components/schemas/UserRole' adminFlags: $ref: '#/components/schemas/UserAdminFlags' password: $ref: '#/components/schemas/password' UpdateMe: properties: password: $ref: '#/components/schemas/password' currentPassword: $ref: '#/components/schemas/password' email: description: new email used for login and service communications allOf: - $ref: '#/components/schemas/User/properties/email' displayName: type: string description: new name of the user in its representations minLength: 3 maxLength: 120 displayNSFW: type: string description: new NSFW display policy enum: - 'true' - 'false' - both p2pEnabled: type: boolean description: whether to enable P2P in the player or not autoPlayVideo: type: boolean description: new preference regarding playing videos automatically autoPlayNextVideo: type: boolean description: new preference regarding playing following videos automatically autoPlayNextVideoPlaylist: type: boolean description: new preference regarding playing following playlist videos automatically videosHistoryEnabled: type: boolean description: whether to keep track of watched history or not videoLanguages: type: array items: type: string description: list of languages to filter videos down to theme: type: string noInstanceConfigWarningModal: type: boolean noAccountSetupWarningModal: type: boolean noWelcomeModal: type: boolean GetMeVideoRating: properties: id: $ref: '#/components/schemas/id' rating: type: string enum: - like - dislike - none description: Rating of the video required: - id - rating VideoRating: properties: video: $ref: '#/components/schemas/Video' rating: type: string enum: - like - dislike - none description: Rating of the video required: - video - rating RegisterUser: properties: username: description: immutable name of the user, used to find or mention its actor allOf: - $ref: '#/components/schemas/username' password: $ref: '#/components/schemas/password' email: type: string format: email description: email of the user, used for login or service communications displayName: type: string description: editable name of the user, displayed in its representations minLength: 1 maxLength: 120 channel: type: object description: channel base information used to create the first channel of the user properties: name: $ref: '#/components/schemas/usernameChannel' 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: type: string pattern: /^[a-z0-9]$/ maxLength: 32 minLength: 32 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf client_secret: type: string pattern: /^[a-zA-Z0-9]$/ maxLength: 32 minLength: 32 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt OAuthToken-password: allOf: - $ref: '#/components/schemas/OAuthClient' - type: object properties: grant_type: type: string enum: - password - refresh_token default: password username: $ref: '#/components/schemas/User/properties/username' password: $ref: '#/components/schemas/password' required: - client_id - client_secret - grant_type - username - password OAuthToken-refresh_token: allOf: - $ref: '#/components/schemas/OAuthClient' - type: object properties: grant_type: type: string enum: - password - refresh_token default: password refresh_token: type: string example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7 required: - client_id - client_secret - grant_type - refresh_token VideoChannel: allOf: - $ref: '#/components/schemas/Actor' - type: object 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 nullable: true example: Videos made with <3 by Framasoft minLength: 3 maxLength: 1000 support: type: string nullable: true 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: $ref: '#/components/schemas/Account' VideoChannelEdit: properties: displayName: description: Channel display name description: description: Channel description support: description: How to support/fund the channel VideoChannelCreate: allOf: - $ref: '#/components/schemas/VideoChannelEdit' - properties: name: description: username of the channel to create allOf: - $ref: '#/components/schemas/usernameChannel' required: - name - displayName VideoChannelUpdate: allOf: - $ref: '#/components/schemas/VideoChannelEdit' - properties: bulkVideosSupportUpdate: type: boolean description: Update the support field for all videos of this channel VideoChannelList: properties: total: type: integer example: 1 data: type: array items: allOf: - $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: name: 'media:peerLink' properties: href: type: string xml: attribute: true type: type: string enum: - application/x-bittorrent xml: attribute: true MRSSGroupContent: type: object xml: name: 'media:content' properties: url: type: string format: url xml: attribute: true fileSize: type: integer xml: attribute: true type: type: string xml: attribute: true framerate: type: integer xml: attribute: true duration: type: integer xml: attribute: true height: type: integer xml: attribute: true lang: type: string xml: attribute: true VideoCommentsForXML: type: array xml: wrapped: true name: 'channel' items: type: object xml: name: 'item' properties: link: type: string format: url guid: type: string pubDate: type: string format: date-time 'content:encoded': type: string 'dc:creator': type: string VideosForXML: type: array xml: wrapped: true name: 'channel' items: type: object xml: name: 'item' properties: link: type: string format: url description: video watch page URL guid: type: string description: video canonical URL pubDate: type: string format: date-time description: video publication date description: type: string description: video description 'content:encoded': type: string description: video description 'dc:creator': type: string description: publisher user name 'media:category': type: integer description: video category (MRSS) 'media:community': type: object description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS) properties: 'media:statistics': type: object properties: views: type: integer xml: attribute: true 'media:embed': type: object properties: url: type: string format: url description: video embed path, relative to the canonical URL domain (MRSS) xml: attribute: true 'media:player': type: object properties: url: type: string format: url description: video watch path, relative to the canonical URL domain (MRSS) xml: attribute: true 'media:thumbnail': type: object properties: url: type: string format: url xml: attribute: true height: type: integer xml: attribute: true width: type: integer xml: attribute: true 'media:title': type: string description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles. 'media:description': type: string 'media:rating': type: string enum: - nonadult - adult description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS) 'enclosure': type: object description: main streamable file for the video properties: url: type: string format: url xml: attribute: true type: type: string enum: - application/x-bittorrent xml: attribute: true length: type: integer xml: attribute: true 'media:group': type: array description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS) items: anyOf: - $ref: '#/components/schemas/MRSSPeerLink' - $ref: '#/components/schemas/MRSSGroupContent' NotificationSettingValue: type: integer description: > Notification type. One of the following values, or a sum of multiple values: - `0` NONE - `1` WEB - `2` EMAIL Notification: properties: id: $ref: '#/components/schemas/id' type: type: integer description: > Notification type, following the `UserNotificationType` enum: - `1` NEW_VIDEO_FROM_SUBSCRIPTION - `2` NEW_COMMENT_ON_MY_VIDEO - `3` NEW_ABUSE_FOR_MODERATORS - `4` BLACKLIST_ON_MY_VIDEO - `5` UNBLACKLIST_ON_MY_VIDEO - `6` MY_VIDEO_PUBLISHED - `7` MY_VIDEO_IMPORT_SUCCESS - `8` MY_VIDEO_IMPORT_ERROR - `9` NEW_USER_REGISTRATION - `10` NEW_FOLLOW - `11` COMMENT_MENTION - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS - `13` NEW_INSTANCE_FOLLOWER - `14` AUTO_INSTANCE_FOLLOWING - `15` ABUSE_STATE_CHANGE - `16` ABUSE_NEW_MESSAGE - `17` NEW_PLUGIN_VERSION - `18` NEW_PEERTUBE_VERSION - `19` MY_VIDEO_STUDIO_EDITION_FINISHED - `20` NEW_USER_REGISTRATION_REQUEST - `21` NEW_LIVE_FROM_SUBSCRIPTION read: type: boolean video: nullable: true allOf: - $ref: '#/components/schemas/VideoInfo' - type: object properties: channel: $ref: '#/components/schemas/ActorInfo' videoImport: nullable: true type: object properties: id: $ref: '#/components/schemas/id' video: nullable: true $ref: '#/components/schemas/VideoInfo' torrentName: type: string nullable: true magnetUri: $ref: '#/components/schemas/VideoImport/properties/magnetUri' targetUri: type: string format: uri nullable: true comment: nullable: true type: object properties: id: $ref: '#/components/schemas/id' threadId: type: integer video: $ref: '#/components/schemas/VideoInfo' account: $ref: '#/components/schemas/ActorInfo' heldForReview: type: boolean videoAbuse: nullable: true type: object properties: id: $ref: '#/components/schemas/id' video: allOf: - $ref: '#/components/schemas/VideoInfo' videoBlacklist: nullable: true type: object properties: id: $ref: '#/components/schemas/id' video: allOf: - $ref: '#/components/schemas/VideoInfo' account: nullable: true allOf: - $ref: '#/components/schemas/ActorInfo' actorFollow: type: object nullable: true properties: id: $ref: '#/components/schemas/id' follower: $ref: '#/components/schemas/ActorInfo' state: type: string enum: - pending - accepted following: type: object properties: type: type: string enum: - account - channel - instance name: type: string displayName: type: string host: type: string format: hostname createdAt: type: string format: date-time updatedAt: type: string format: date-time NotificationListResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Notification' Plugin: properties: name: type: string example: peertube-plugin-auth-ldap type: type: integer description: > - `1`: PLUGIN - `2`: THEME enum: - 1 - 2 latestVersion: type: string example: 0.0.3 version: type: string example: 0.0.1 enabled: type: boolean uninstalled: type: boolean peertubeEngine: type: string example: 2.2.0 description: type: string homepage: type: string format: url example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap settings: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time PluginResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Plugin' LiveVideoUpdate: properties: saveReplay: type: boolean replaySettings: $ref: '#/components/schemas/LiveVideoReplaySettings' 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. Included in the response if an appropriate token is provided saveReplay: type: boolean replaySettings: $ref: '#/components/schemas/LiveVideoReplaySettings' 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' - 'web-video' resolution: type: number description: Current player video resolution fps: type: number description: Current player video fps p2pEnabled: type: boolean p2pPeers: type: number description: P2P peers connected (doesn't include WebSeed peers) resolutionChanges: type: number description: How many resolution changes occurred since the last metric creation errors: type: number description: How many errors occurred 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 - p2pEnabled - videoId RunnerRegistrationToken: properties: id: type: integer registrationToken: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time registeredRunnersCount: type: integer Runner: properties: id: type: integer name: type: string description: type: string ip: type: string updatedAt: type: string format: date-time createdAt: type: string format: date-time lastContact: type: string format: date-time RunnerJobType: type: string enum: - vod-web-video-transcoding - vod-hls-transcoding - vod-audio-merge-transcoding - live-rtmp-hls-transcoding RunnerJobState: type: integer enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 description: > The runner job state: - `1` Pending - `2` Processing - `3` Completed - `4` Errored - `5` Waiting for a parent job - `6` Cancelled - `7` Parent had an error - `8` Parent has been cancelled RunnerJobStateConstant: type: object properties: id: $ref: '#/components/schemas/RunnerJobState' label: type: string example: 'Processing' RunnerJobPayload: anyOf: - type: object title: VOD web video transcoding properties: input: type: object properties: videoFileUrl: type: string output: type: object properties: resolution: type: number fps: type: number - type: object title: VOD HLS transcoding properties: input: type: object properties: videoFileUrl: type: string output: type: object properties: resolution: type: number fps: type: number - type: object title: VOD audio merge transcoding properties: input: type: object properties: audioFileUrl: type: string previewFileUrl: type: string output: type: object properties: resolution: type: number fps: type: number RunnerJob: properties: uuid: $ref: '#/components/schemas/UUIDv4' type: $ref: '#/components/schemas/RunnerJobType' state: $ref: '#/components/schemas/RunnerJobStateConstant' payload: $ref: '#/components/schemas/RunnerJobPayload' failures: type: integer description: Number of times a remote runner failed to process this job. After too many failures, the job in "error" state error: nullable: true type: string description: Error message if the job is errored progress: type: integer description: Percentage progress priority: type: integer description: Job priority (less has more priority) updatedAt: type: string format: date-time createdAt: type: string format: date-time startedAt: type: string format: date-time finishedAt: type: string format: date-time parent: nullable: true description: If job has a parent job type: object properties: type: $ref: '#/components/schemas/RunnerJobType' state: $ref: '#/components/schemas/RunnerJobStateConstant' uuid: $ref: '#/components/schemas/UUIDv4' runner: nullable: true description: If job is associated to a runner properties: id: type: number name: type: string description: type: string RunnerJobAdmin: allOf: - $ref: '#/components/schemas/RunnerJob' - type: object properties: privatePayload: type: object WatchedWordsLists: properties: id: $ref: '#/components/schemas/id' listName: type: string words: type: array items: type: string updatedAt: type: string format: date-time example: 2021-05-04T08:01:01.502Z createdAt: type: string format: date-time example: 2021-05-04T08:01:01.502Z VideoPassword: properties: id: $ref: '#/components/schemas/id' password: type: string minLength: 2 videoId: $ref: '#/components/schemas/id' VideoPasswordList: properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoPassword' AddVideoPasswords: type: array items: $ref: "#/components/schemas/VideoPassword/properties/password" uniqueItems: true callbacks: searchIndex: 'https://search.example.org/api/v1/search/videos': post: summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget` responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse'