openapi: 3.0.0 info: title: PeerTube version: 3.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: | # Introduction The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice - we generate some client SDKs automatically: - [Python](https://framagit.org/framasoft/peertube/clients/python) - [Go](https://framagit.org/framasoft/peertube/clients/go) - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) See the [Quick Start guide](https://docs.joinpeertube.org/api-rest-getting-started) so you can play with the PeerTube API. # Authentication When you sign up for an account, you are given the possibility to generate sessions, and authenticate using this session token. One session token can currently be used at a time. ## Roles Accounts are given permissions based on their role. There are three roles on PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format. ``` { "code": "unauthorized_request", // example inner error code "error": "Token is invalid." // example exposed error message } ``` externalDocs: url: https://docs.joinpeertube.org/api-rest-reference.html tags: - 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: 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?id=instances-follows - name: Instance Redundancy description: > Redundancy is part of the inter-server solidarity that PeerTube fosters. Manage the list of instances you wish to help by seeding their videos according to the policy of video selection of your choice. Note that you have a similar functionality to mirror individual videos, see `Video Mirroring`. externalDocs: url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy - name: Plugins description: > Managing plugins installed from a local path or from NPM, or search for new ones. externalDocs: url: https://docs.joinpeertube.org/api-plugins - name: Abuses description: | 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: 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: Video Comments description: > Operations dealing with comments to a video. Comments are organized in threads. - name: Video Playlists description: > Operations dealing with playlists of videos. Playlists are bound to users and/or channels. - name: Video Channels description: > Operations dealing with the creation, modification and listing of videos within a channel. - name: Video Blocks description: > Operations dealing with blocking videos (removing them from view and preventing interactions). - name: Video Rates description: > Like/dislike a video. - name: Feeds description: > Server syndication feeds x-tagGroups: - name: Accounts tags: - Accounts - Users - My User - My Subscriptions - My Notifications - My History - name: Videos tags: - Video - Video Captions - Video Channels - Video Comments - Video Rates - Video Playlists - Video Ownership Change - Video Mirroring - Live Videos - Feeds - name: Search tags: - Search - name: Moderation tags: - Abuses - Video Blocks - Account Blocks - Server Blocks - name: Instance Configuration tags: - Config - Instance Follows - Instance Redundancy - Plugins - name: Jobs tags: - Job paths: '/accounts/{name}': get: tags: - Accounts summary: Get an account parameters: - $ref: '#/components/parameters/name' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Account' '404': description: account not found '/accounts/{name}/videos': get: tags: - Accounts - Video summary: 'List videos of an account' 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/nsfw' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' x-code-samples: - 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) /accounts: get: tags: - Accounts summary: List accounts parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: 'application/json': schema: type: array items: $ref: '#/components/schemas/Account' /config: get: tags: - Config summary: Get instance public configuration responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfig' /config/about: get: summary: Get instance "About" information tags: - Config responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfigAbout' /config/custom: get: summary: Get instance runtime configuration tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfigCustom' put: summary: Set instance runtime configuration 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 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled delete: summary: Delete instance runtime configuration tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation /jobs/{state}: get: summary: List instance jobs 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' '/server/following/{host}': delete: security: - OAuth2: - admin tags: - Instance Follows summary: Unfollow a server parameters: - name: host in: path required: true description: 'The host to unfollow ' schema: type: string format: hostname responses: '201': description: successful operation /server/followers: get: tags: - Instance Follows summary: List instance followers parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Follow' /server/following: get: tags: - Instance Follows summary: List instances followed by the server parameters: - name: state in: query schema: type: string enum: - pending - accepted - name: actorType in: query schema: type: string enum: - Person - Application - Group - Service - Organization - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Follow' post: security: - OAuth2: - admin tags: - Instance Follows summary: Follow a server responses: '204': description: successful operation '500': description: cannot follow a non-HTTPS server requestBody: content: application/json: schema: type: object properties: hosts: type: array items: type: string format: hostname uniqueItems: true /users: post: summary: Create a user security: - OAuth2: - admin tags: - Users responses: '200': description: user created content: application/json: schema: $ref: '#/components/schemas/AddUserResponse' links: # GET /users/{id} GetUserId: operationId: getUserId parameters: id: '$response.body#/user/id' # PUT /users/{id} PutUserId: operationId: putUserId parameters: id: '$response.body#/user/id' # DELETE /users/{id} DelUserId: operationId: delUserId parameters: id: '$response.body#/user/id' '403': description: insufficient authority to create an admin or moderator requestBody: content: application/json: schema: $ref: '#/components/schemas/AddUser' description: User to create required: true get: summary: List users 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' '/users/{id}': parameters: - $ref: '#/components/parameters/id' delete: summary: Delete a user security: - OAuth2: - admin tags: - Users operationId: delUserId responses: '204': description: successful operation get: summary: Get a user security: - OAuth2: [] tags: - Users operationId: getUserId responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/User' put: summary: Update a user security: - OAuth2: [] tags: - Users operationId: putUserId responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateUser' required: true /users/register: post: summary: Register a user tags: - Users responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/RegisterUser' required: true /users/me: get: summary: Get my user information 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 security: - OAuth2: - user tags: - My User responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateMe' required: true /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' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoImport' /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: number '/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: type: string responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/GetMeVideoRating' /users/me/videos: get: summary: Get 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' /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 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 /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 /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/nsfw' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '/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 /users/me/notifications: get: summary: List my notifications security: - OAuth2: [] tags: - My Notifications parameters: - name: unread in: query description: only list unread notifications schema: type: boolean - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/NotificationListResponse' /users/me/notifications/read: post: summary: Mark notifications as read by their id security: - OAuth2: [] tags: - My Notifications requestBody: content: application/json: schema: type: object properties: ids: type: array description: ids of the notifications to mark as read items: type: integer required: - ids responses: '204': description: successful operation /users/me/notifications/read-all: post: summary: Mark all my notification as read security: - OAuth2: [] tags: - My Notifications responses: '204': description: successful operation /users/me/notification-settings: put: summary: Update my notification settings security: - OAuth2: [] tags: - My Notifications requestBody: content: application/json: schema: type: object properties: newVideoFromSubscription: $ref: '#/components/schemas/NotificationSettingValue' newCommentOnMyVideo: $ref: '#/components/schemas/NotificationSettingValue' abuseAsModerator: $ref: '#/components/schemas/NotificationSettingValue' videoAutoBlacklistAsModerator: $ref: '#/components/schemas/NotificationSettingValue' blacklistOnMyVideo: $ref: '#/components/schemas/NotificationSettingValue' myVideoPublished: $ref: '#/components/schemas/NotificationSettingValue' myVideoImportFinished: $ref: '#/components/schemas/NotificationSettingValue' newFollow: $ref: '#/components/schemas/NotificationSettingValue' newUserRegistration: $ref: '#/components/schemas/NotificationSettingValue' commentMention: $ref: '#/components/schemas/NotificationSettingValue' newInstanceFollower: $ref: '#/components/schemas/NotificationSettingValue' autoInstanceFollowing: $ref: '#/components/schemas/NotificationSettingValue' responses: '204': description: successful operation /users/me/history/videos: get: summary: List watched videos history security: - OAuth2: [] tags: - My History parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/search' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' /users/me/history/videos/remove: post: summary: Clear video history security: - OAuth2: [] tags: - My History requestBody: content: multipart/form-data: schema: type: object properties: beforeDate: description: history before this date will be deleted type: string format: date-time responses: '204': description: successful operation /users/me/avatar/pick: post: summary: Update my user avatar security: - OAuth2: [] tags: - My User responses: '200': description: successful operation content: application/json: schema: type: object properties: avatar: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the avatar requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload. type: string format: binary encoding: avatarfile: contentType: image/png, image/jpeg /users/me/avatar: delete: summary: Delete my avatar security: - OAuth2: [] tags: - My User responses: '204': description: successful operation /videos/ownership: get: summary: List video ownership changes tags: - Video Ownership Change security: - OAuth2: [] responses: '200': description: successful operation '/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 owneship change not found '/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 owneship change not found '/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 /videos: get: summary: List videos 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/nsfw' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' /videos/categories: get: summary: List available video categories 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 /videos/licences: get: summary: List available video licences 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 /videos/languages: get: summary: List available video languages 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 /videos/privacies: get: summary: List available video privacies 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 '/videos/{id}': put: summary: Update a video 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: description: Video category type: integer example: 4 licence: description: Video licence type: integer example: 2 language: description: Video language type: string 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 my work on ! <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: description: Enable or disable comments for this video type: boolean originallyPublishedAt: description: Date when the content was originally published type: string format: date-time scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' encoding: thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg get: summary: Get a video tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoDetails' delete: summary: Delete a video security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '/videos/{id}/description': get: summary: Get complete video description tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: type: string '/videos/{id}/views': post: summary: Add a view to a video tags: - Video parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '/videos/{id}/watching': put: summary: Set watching progress of a video tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/idOrUUID' requestBody: content: application/json: schema: $ref: '#/components/schemas/UserWatchingVideo' required: true responses: '204': description: successful operation /videos/upload: post: summary: Upload a video security: - OAuth2: [] tags: - Video responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '400': description: invalid file field, schedule date or parameter '403': description: video didn't pass upload filter '408': description: upload has timed out '413': description: video file too large, due to quota or max body size limit set by the reverse-proxy 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: type: object properties: videofile: description: Video file type: string format: binary channelId: description: Channel id that will contain this video type: integer thumbnailfile: description: Video thumbnail file type: string format: binary previewfile: description: Video preview file type: string format: binary privacy: $ref: '#/components/schemas/VideoPrivacySet' category: description: Video category type: integer example: 4 licence: description: Video licence type: integer example: 2 language: description: Video language type: string description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: boolean support: description: A text tell the audience how to support the video creator example: Please support my work on ! <3 type: string nsfw: description: Whether or not this video contains sensitive content type: boolean 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 uniqueItems: true items: type: string minLength: 2 maxLength: 30 commentsEnabled: description: Enable or disable comments for this video type: boolean downloadEnabled: description: Enable or disable downloading for this video type: boolean originallyPublishedAt: description: Date when the content was originally published type: string format: date-time scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' required: - videofile - channelId - name 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-code-samples: - lang: Shell source: | ## DEPENDENCIES: jq USERNAME="" PASSWORD="" FILE_PATH="" CHANNEL_ID="" NAME="" API_PATH="https://peertube2.cpy.re/api/v1" ## AUTH client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id") client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret") token=$(curl -s "$API_PATH/users/token" \ --data client_id="$client_id" \ --data client_secret="$client_secret" \ --data grant_type=password \ --data response_type=code \ --data username="$USERNAME" \ --data password="$PASSWORD" \ | jq -r ".access_token") ## VIDEO UPLOAD curl -s "$API_PATH/videos/upload" \ -H "Authorization: Bearer $token" \ --max-time 600 \ --form videofile=@"$FILE_PATH" \ --form channelId=$CHANNEL_ID \ --form name="$NAME" /videos/imports: post: summary: Import a video description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) security: - OAuth2: [] tags: - Video requestBody: content: multipart/form-data: schema: type: object properties: torrentfile: description: Torrent File type: string format: binary targetUrl: description: HTTP target URL type: string magnetUri: description: Magnet URI type: string channelId: description: Channel id that will contain this video type: integer thumbnailfile: description: Video thumbnail file type: string format: binary previewfile: description: Video preview file type: string format: binary privacy: $ref: '#/components/schemas/VideoPrivacySet' category: description: Video category type: integer example: 4 licence: description: Video licence type: integer example: 2 language: description: Video language type: string description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: boolean support: description: A text tell the audience how to support the video creator example: Please support my work on ! <3 type: string nsfw: description: Whether or not this video contains sensitive content type: boolean 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: description: Enable or disable comments for this video type: boolean downloadEnabled: description: Enable or disable downloading for this video type: boolean scheduleUpdate: $ref: '#/components/schemas/VideoScheduledUpdate' required: - channelId - name 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 /videos/live: post: summary: Create a live security: - OAuth2: [] tags: - Live Videos - Video responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' '403': description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded requestBody: content: multipart/form-data: schema: type: object properties: channelId: description: Channel id that will contain this live video type: integer saveReplay: type: boolean permanentLive: description: User can stream multiple times in a permanent live type: boolean thumbnailfile: description: Live video/replay thumbnail file type: string format: binary previewfile: description: Live video/replay preview file type: string format: binary privacy: $ref: '#/components/schemas/VideoPrivacySet' category: description: Live video/replay category type: string licence: description: Live video/replay licence type: string language: description: Live video/replay language type: string description: description: Live video/replay description type: string support: description: A text tell the audience how to support the creator example: Please support my work on ! <3 type: string nsfw: description: Whether or not this live video/replay contains sensitive content type: boolean name: description: Live video/replay name type: string minLength: 3 maxLength: 120 tags: description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters) type: array minItems: 1 maxItems: 5 items: type: string minLength: 2 maxLength: 30 commentsEnabled: description: Enable or disable comments for this live video/replay type: boolean downloadEnabled: description: Enable or disable downloading for the replay of this live type: boolean required: - channelId - name encoding: thumbnailfile: contentType: image/jpeg previewfile: contentType: image/jpeg /videos/live/{id}: get: summary: Get a live information 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 a live information 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 /users/me/abuses: get: summary: List my abuses security: - OAuth2: [] tags: - Abuses - My User parameters: - name: id in: query description: only list the report with this id schema: type: integer - name: state in: query schema: $ref: '#/components/schemas/AbuseStateSet' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Abuse' /abuses: get: summary: List abuses security: - OAuth2: - admin - moderator tags: - 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 blacklisted or deleted videos schema: type: string enum: - 'deleted' - 'blacklisted' - name: filter in: query description: only list account, comment or video reports schema: type: string enum: - 'video' - 'comment' - 'account' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Abuse' post: summary: Report an abuse security: - OAuth2: [] tags: - Abuses requestBody: required: true content: application/json: schema: type: object properties: reason: description: Reason why the user reports this video type: string minLength: 2 maxLength: 3000 predefinedReasons: $ref: '#/components/schemas/PredefinedAbuseReasons' video: type: object properties: id: description: Video id to report type: number startAt: type: integer description: Timestamp in the video that marks the beginning of the report minimum: 0 endAt: type: integer description: Timestamp in the video that marks the ending of the report minimum: 0 comment: type: object properties: id: description: Comment id to report type: number account: type: object properties: id: description: Account id to report type: number required: - reason responses: '204': description: successful operation '400': description: incorrect request parameters '/abuses/{abuseId}': put: summary: Update an abuse security: - OAuth2: - admin - moderator tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' requestBody: content: application/json: schema: type: object properties: state: $ref: '#/components/schemas/AbuseStateSet' moderationComment: type: string description: Update the report comment visible only to the moderation team minLength: 2 maxLength: 3000 responses: '204': description: successful operation '404': description: abuse not found delete: tags: - Abuses summary: Delete an abuse security: - OAuth2: - admin - moderator parameters: - $ref: '#/components/parameters/abuseId' responses: '204': description: successful operation '404': description: block not found '/abuses/{abuseId}/messages': get: summary: List messages of an abuse security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/AbuseMessage' post: summary: Add message to an abuse security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' requestBody: required: true content: application/json: schema: type: object properties: message: description: Message to send type: string minLength: 2 maxLength: 3000 required: - message responses: '200': description: successful operation '400': description: incorrect request parameters '/abuses/{abuseId}/messages/{abuseMessageId}': delete: summary: Delete an abuse message security: - OAuth2: [] tags: - Abuses parameters: - $ref: '#/components/parameters/abuseId' - $ref: '#/components/parameters/abuseMessageId' responses: '204': description: successful operation '/videos/{id}/blacklist': post: summary: Block a video security: - OAuth2: - admin - moderator tags: - Video Blocks parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation delete: summary: Unblock a video by its id security: - OAuth2: - admin - moderator tags: - Video Blocks parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '404': description: block not found /videos/blacklist: get: tags: - Video Blocks summary: List video blocks security: - OAuth2: - admin - moderator parameters: - name: type in: query description: > list only blocks that match this type: - `1`: manual block - `2`: automatic block that needs review schema: type: integer enum: - 1 - 2 - name: search in: query description: plain search that will match with video titles, and more schema: type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/blacklistsSort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoBlacklist' /videos/{id}/captions: get: summary: List captions of a video tags: - Video Captions parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoCaption' /videos/{id}/captions/{captionLanguage}: put: summary: Add or replace a video caption 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 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 /video-channels: get: summary: List video channels 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: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoChannel' post: summary: Create a video channel security: - OAuth2: [] tags: - Video Channels responses: '204': description: successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/VideoChannelCreate' '/video-channels/{channelHandle}': get: summary: Get a video channel 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 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 security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation '/video-channels/{channelHandle}/videos': get: summary: List videos of a video channel 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/nsfw' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '/video-channels/{channelHandle}/avatar/pick': post: summary: Update channel avatar security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: type: object properties: avatar: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the avatar requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload. type: string format: binary encoding: avatarfile: contentType: image/png, image/jpeg '/video-channels/{channelHandle}/avatar': delete: summary: Delete channel avatar security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation '/video-channels/{channelHandle}/banner/pick': post: summary: Update channel banner security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: type: object properties: banner: $ref: '#/components/schemas/ActorImage' '413': description: image file too large headers: X-File-Maximum-Size: schema: type: string format: Nginx size description: Maximum file size for the banner requestBody: content: multipart/form-data: schema: type: object properties: bannerfile: description: The file to upload. type: string format: binary encoding: bannerfile: contentType: image/png, image/jpeg '/video-channels/{channelHandle}/banner': delete: summary: Delete channel banner security: - OAuth2: [] tags: - Video Channels parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': description: successful operation /video-playlists/privacies: get: summary: List available playlist privacies 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 /video-playlists: get: summary: List video playlists tags: - Video Playlists parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: type: object properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoPlaylist' post: summary: Create a video playlist description: 'If the video playlist is set as public, the videoChannelId is mandatory.' security: - OAuth2: [] tags: - Video Playlists responses: '200': description: successful operation content: application/json: schema: type: object properties: videoPlaylist: type: object properties: id: type: integer uuid: $ref: '#/components/schemas/UUIDv4' 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: description: Video channel in which the playlist will be published type: integer required: - displayName encoding: thumbnailfile: contentType: image/jpeg /video-playlists/{id}: get: summary: Get a video playlist tags: - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' 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/idOrUUID' 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: description: Video channel in which the playlist will be published type: integer encoding: thumbnailfile: contentType: image/jpeg delete: summary: Delete a video playlist security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation /video-playlists/{id}/videos: get: summary: 'List videos of a playlist' tags: - Videos - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' post: summary: 'Add a video in a playlist' security: - OAuth2: [] tags: - Videos - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' responses: '200': description: successful operation content: application/json: schema: type: object properties: videoPlaylistElement: type: object properties: id: type: integer requestBody: content: application/json: schema: type: object properties: videoId: type: integer description: 'Video to add in the playlist' startTimestamp: type: integer description: 'Start the video at this specific timestamp (in seconds)' stopTimestamp: type: integer description: 'Stop the video at this specific timestamp (in seconds)' required: - videoId /video-playlists/{id}/videos/reorder: post: summary: 'Reorder a playlist' security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' 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 /video-playlists/{id}/videos/{playlistElementId}: put: summary: 'Update a playlist element' security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/playlistElementId' responses: '204': description: successful operation requestBody: content: application/json: schema: type: object properties: startTimestamp: type: integer description: 'Start the video at this specific timestamp (in seconds)' stopTimestamp: type: integer description: 'Stop the video at this specific timestamp (in seconds)' delete: summary: 'Delete an element from a playlist' security: - OAuth2: [] tags: - Video Playlists parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/playlistElementId' responses: '204': description: successful operation '/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: type: integer 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 stopTimestamp: type: integer '/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 view statistics for the last 30 days (only if authentified as the account user) schema: type: boolean - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: properties: total: type: integer example: 1 data: type: array items: $ref: '#/components/schemas/VideoChannel' '/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' '/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' 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: type: string description: 'Text comment' required: - text '/videos/{id}/comment-threads/{threadId}': get: summary: Get a thread tags: - Video Comments parameters: - $ref: '#/components/parameters/idOrUUID' - $ref: '#/components/parameters/threadId' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoCommentThreadTree' '/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' 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: type: string description: 'Text comment' 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 '/videos/{id}/rate': put: summary: Like/dislike a video security: - OAuth2: [] tags: - Video Rates parameters: - $ref: '#/components/parameters/idOrUUID' responses: '204': description: successful operation '404': description: video does not exist /search/videos: get: tags: - Search summary: Search videos parameters: - name: search in: query required: true allowEmptyValue: false description: > String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it. schema: type: string - $ref: '#/components/parameters/categoryOneOf' - $ref: '#/components/parameters/isLive' - $ref: '#/components/parameters/tagsOneOf' - $ref: '#/components/parameters/tagsAllOf' - $ref: '#/components/parameters/licenceOneOf' - $ref: '#/components/parameters/languageOneOf' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/skipCount' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/videosSearchSort' - name: startDate in: query description: Get videos that are published after this date schema: type: string format: date-time - name: endDate in: query description: Get videos that are published before this date schema: type: string format: date-time - name: originallyPublishedStartDate in: query description: Get videos that are originally published after this date schema: type: string format: date-time - name: originallyPublishedEndDate in: query description: Get videos that are originally published before this date schema: type: string format: date-time - name: durationMin in: query description: Get videos that have this minimum duration schema: type: integer - name: durationMax in: query description: Get videos that have this maximum duration schema: type: integer callbacks: 'searchTarget === search-index': $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoListResponse' '500': description: search index unavailable /search/video-channels: get: tags: - Search summary: Search channels parameters: - name: search in: query required: true description: > String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete channel information and interact with it. schema: type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/searchTarget' - $ref: '#/components/parameters/sort' callbacks: 'searchTarget === search-index': $ref: '#/components/callbacks/searchIndex' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoChannel' '500': description: search index unavailable /blocklist/accounts: get: tags: - Account Blocks summary: List account blocks security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation post: tags: - Account Blocks summary: Block an account security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: accountName: type: string example: chocobozzz@example.org description: account to block, in the form `username@domain` required: - accountName responses: '200': description: successful operation '409': description: self-blocking forbidden '/blocklist/accounts/{accountName}': delete: tags: - Account Blocks summary: Unblock an account by its handle security: - OAuth2: - admin parameters: - name: accountName in: path required: true description: account to unblock, in the form `username@domain` schema: type: string responses: '201': description: successful operation '404': description: account or account block does not exist /blocklist/servers: get: tags: - Server Blocks summary: List server blocks security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation post: tags: - Server Blocks summary: Block a server security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: host: type: string format: hostname description: server domain to block required: - host responses: '200': description: successful operation '409': description: self-blocking forbidden '/blocklist/servers/{host}': delete: tags: - Server Blocks summary: Unblock a server by its domain security: - OAuth2: - admin parameters: - name: host in: path required: true description: server domain to unblock schema: type: string format: hostname responses: '201': description: successful operation '404': description: account block does not exist /redundancy/{host}: put: tags: - Instance Redundancy summary: Update a server redundancy policy security: - OAuth2: - admin parameters: - name: host in: path required: true description: server domain to mirror schema: type: string format: hostname requestBody: content: application/json: schema: type: object properties: redundancyAllowed: type: boolean description: allow mirroring of the host's local videos required: - redundancyAllowed responses: '204': description: successful operation '404': description: server is not already known /redundancy/videos: get: tags: - Video Mirroring summary: List videos being mirrored security: - OAuth2: - admin parameters: - name: target in: query required: true description: direction of the mirror schema: type: string enum: - my-videos - remote-videos - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videoRedundanciesSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoRedundancy' post: tags: - Video Mirroring summary: Mirror a video security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: videoId: type: integer required: - videoId responses: '204': description: successful operation '400': description: cannot mirror a local video '404': description: video does not exist '409': description: video is already mirrored /redundancy/videos/{redundancyId}: delete: tags: - Video Mirroring summary: Delete a mirror done on a video security: - OAuth2: - admin parameters: - name: redundancyId in: path required: true description: id of an existing redundancy on a video schema: type: string responses: '204': description: successful operation '404': description: video redundancy not found '/feeds/video-comments.{format}': get: tags: - Feeds summary: List comments on videos servers: - url: 'https://peertube2.cpy.re' description: Live Test Server (live data - latest nightly version) - url: 'https://peertube3.cpy.re' description: Live Test Server (live data - latest RC version) - url: 'https://peertube.cpy.re' description: Live Test Server (live data - stable version) parameters: - name: format in: path required: true description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))' schema: type: string enum: - xml - rss - rss2 - atom - atom1 - json - json1 - name: videoId in: query description: 'limit listing to a specific video' schema: type: string - name: accountId in: query description: 'limit listing to a specific account' schema: type: string - name: accountName in: query description: 'limit listing to a specific account' schema: type: string - name: videoChannelId in: query description: 'limit listing to a specific video channel' schema: type: string - name: videoChannelName in: query description: 'limit listing to a specific video channel' schema: type: string responses: '204': description: successful operation headers: Cache-Control: schema: type: string default: 'max-age=900' # 15 min cache content: application/xml: schema: $ref: '#/components/schemas/VideoCommentsForXML' application/rss+xml: schema: $ref: '#/components/schemas/VideoCommentsForXML' text/xml: schema: $ref: '#/components/schemas/VideoCommentsForXML' application/atom+xml: schema: $ref: '#/components/schemas/VideoCommentsForXML' application/json: schema: type: object '400': x-summary: field inconsistencies description: > Arises when: - videoId filter is mixed with a channel filter '404': description: video, video channel or account not found '406': description: accept header unsupported '/feeds/videos.{format}': get: tags: - Feeds summary: List videos servers: - url: 'https://peertube2.cpy.re' description: Live Test Server (live data - latest nightly version) - url: 'https://peertube3.cpy.re' description: Live Test Server (live data - latest RC version) - url: 'https://peertube.cpy.re' description: Live Test Server (live data - stable version) parameters: - name: format in: path required: true description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))' schema: type: string enum: - xml - rss - rss2 - atom - atom1 - json - json1 - name: accountId in: query description: 'limit listing to a specific account' schema: type: string - name: accountName in: query description: 'limit listing to a specific account' schema: type: string - name: videoChannelId in: query description: 'limit listing to a specific video channel' schema: type: string - name: videoChannelName in: query description: 'limit listing to a specific video channel' schema: type: string - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/nsfw' - $ref: '#/components/parameters/filter' responses: '204': description: successful operation headers: Cache-Control: schema: type: string default: 'max-age=900' # 15 min cache content: application/xml: schema: $ref: '#/components/schemas/VideosForXML' examples: nightly: externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local application/rss+xml: schema: $ref: '#/components/schemas/VideosForXML' text/xml: schema: $ref: '#/components/schemas/VideosForXML' application/atom+xml: schema: $ref: '#/components/schemas/VideosForXML' application/json: schema: type: object '404': description: video channel or account not found '406': description: accept header unsupported /plugins: get: tags: - Plugins summary: List plugins security: - OAuth2: - admin parameters: - name: pluginType in: query schema: type: integer - name: uninstalled in: query schema: type: boolean - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/PluginResponse' /plugins/available: get: tags: - Plugins summary: List available plugins security: - OAuth2: - admin parameters: - name: search in: query schema: type: string - name: pluginType in: query schema: type: integer - name: currentPeerTubeEngine in: query schema: type: string - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/PluginResponse' '503': description: plugin index unavailable /plugins/install: post: tags: - Plugins summary: Install a plugin security: - OAuth2: - admin requestBody: content: application/json: schema: oneOf: - type: object properties: npmName: type: string example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false - type: object properties: path: type: string required: - path additionalProperties: false responses: '204': description: successful operation '400': description: should have either `npmName` or `path` set /plugins/update: post: tags: - Plugins summary: Update a plugin security: - OAuth2: - admin requestBody: content: application/json: schema: oneOf: - type: object properties: npmName: type: string example: peertube-plugin-auth-ldap required: - npmName additionalProperties: false - type: object properties: path: type: string required: - path additionalProperties: false responses: '204': description: successful operation '400': description: should have either `npmName` or `path` set '404': description: existing plugin not found /plugins/uninstall: post: tags: - Plugins summary: Uninstall a plugin security: - OAuth2: - admin requestBody: content: application/json: schema: type: object properties: npmName: type: string description: name of the plugin/theme in its package.json example: peertube-plugin-auth-ldap required: - npmName responses: '204': description: successful operation '404': description: existing plugin not found /plugins/{npmName}: get: tags: - Plugins summary: Get a plugin security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Plugin' '404': description: plugin not found /plugins/{npmName}/settings: put: tags: - Plugins summary: Set a plugin's settings security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' requestBody: content: application/json: schema: type: object properties: settings: type: object additionalProperties: true responses: '204': description: successful operation '404': description: plugin not found /plugins/{npmName}/public-settings: get: tags: - Plugins summary: Get a plugin's public settings parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: type: object additionalProperties: true '404': description: plugin not found /plugins/{npmName}/registered-settings: get: tags: - Plugins summary: Get a plugin's registered settings security: - OAuth2: - admin parameters: - $ref: '#/components/parameters/npmName' responses: '200': description: successful operation content: application/json: schema: type: object additionalProperties: true '404': description: plugin not found servers: - url: 'https://peertube2.cpy.re/api/v1' description: Live Test Server (live data - latest nightly version) - url: 'https://peertube3.cpy.re/api/v1' description: Live Test Server (live data - latest RC version) - url: 'https://peertube.cpy.re/api/v1' description: Live Test Server (live data - stable version) components: parameters: start: name: start in: query required: false description: Offset used to paginate results schema: type: integer minimum: 0 count: name: count in: query required: false description: "Number of items to return" schema: type: integer default: 15 maximum: 100 minimum: 1 sort: name: sort in: query required: false description: Sort column schema: type: string example: -createdAt search: name: search in: query required: false description: Plain text search, applied to various parts of the model depending on endpoint schema: type: string searchTarget: name: searchTarget in: query required: false description: > If the administrator enabled search index support, you can override the default search target. **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information: * If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API schema: type: string enum: - 'local' - 'search-index' videosSort: name: sort in: query required: false description: Sort videos by criteria schema: type: string enum: - name - -duration - -createdAt - -publishedAt - -views - -likes - -trending - -hot videosSearchSort: name: sort in: query required: false description: Sort videos by criteria schema: type: string enum: - name - -duration - -createdAt - -publishedAt - -views - -likes - -match commentsSort: name: sort in: query required: false description: Sort comments by criteria schema: type: string enum: - -createdAt - -totalReplies blacklistsSort: name: sort in: query required: false description: Sort blacklists by criteria schema: type: string enum: - -id - name - -duration - -views - -likes - -dislikes - -uuid - -createdAt usersSearch: name: search in: query required: false description: Plain text search that will match with user usernames or emails schema: type: string usersBlocked: name: blocked in: query required: false description: Filter results down to (un)banned users schema: type: boolean usersSort: name: sort in: query required: false description: Sort users by criteria schema: type: string enum: - -id - -username - -createdAt abusesSort: name: sort in: query required: false description: Sort abuses by criteria schema: type: string enum: - -id - -createdAt - -state videoRedundanciesSort: name: sort in: query required: false description: Sort abuses by criteria schema: type: string enum: - name name: name: name in: path required: true description: The username or handle of the account schema: type: string example: chocobozzz | chocobozzz@example.org id: name: id in: path required: true description: The user id schema: type: integer minimum: 0 example: 42 idOrUUID: name: id in: path required: true description: The object id or uuid schema: oneOf: - type: integer minimum: 0 example: 42 - $ref: '#/components/schemas/UUIDv4' playlistElementId: name: playlistElementId in: path required: true description: Playlist element id schema: type: integer abuseId: name: abuseId in: path required: true description: Abuse id schema: type: integer abuseMessageId: name: abuseMessageId in: path required: true description: Abuse message id schema: type: integer captionLanguage: name: captionLanguage in: path required: true description: The caption language schema: type: string channelHandle: name: channelHandle in: path required: true description: The video channel handle schema: type: string example: my_username | my_username@example.com subscriptionHandle: name: subscriptionHandle in: path required: true description: The subscription handle 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: type: integer isLive: name: isLive in: query required: false description: whether or not the video is a live schema: type: boolean categoryOneOf: name: categoryOneOf in: query required: false description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) schema: oneOf: - type: integer - type: array items: type: integer style: form explode: false tagsOneOf: name: tagsOneOf in: query required: false description: tag(s) of the video schema: oneOf: - type: string - type: array items: type: string style: form explode: false 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: false languageOneOf: name: languageOneOf in: query required: false description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language schema: oneOf: - type: string - type: array items: type: string style: form explode: false licenceOneOf: name: licenceOneOf in: query required: false description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) schema: oneOf: - type: integer - type: array items: type: integer style: form explode: false 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' filter: name: filter in: query required: false description: > Special filters which might require special rights: * `local` - only videos local to the instance * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges) * `all` - all videos, showing private and unlisted videos (requires Admin privileges) schema: type: string enum: - local - all-local 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 - activitypub-refresher - video-redundancy - video-live-ending securitySchemes: OAuth2: description: > In the header: *Authorization: Bearer * Authenticating via OAuth requires the following steps: - Have an account with sufficient authorization levels - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a Bearer Token - Make Authenticated Requests type: oauth2 flows: password: tokenUrl: 'https://peertube.example.com/api/v1/users/token' scopes: admin: Admin scope moderator: Moderator scope user: User scope schemas: UUIDv4: type: string format: uuid example: 9c9de5e8-0a1e-484a-b099-e80766180a6d pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' # the regex above limits the length; # however, some tools might require explicit settings: minLength: 36 maxLength: 36 VideoConstantNumber-Category: properties: id: type: integer description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get)) label: type: string VideoConstantNumber-Licence: properties: id: type: integer description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get)) label: type: string VideoConstantString-Language: properties: id: type: string description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)) label: type: string VideoPlaylistPrivacySet: type: integer enum: - 1 - 2 - 3 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)' 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 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)' VideoPrivacyConstant: properties: id: $ref: '#/components/schemas/VideoPrivacySet' label: type: string 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 blacklist = `1`)' example: 1 VideoStateConstant: properties: id: type: integer enum: - 1 - 2 - 3 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)' label: type: string 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] VideoResolutionConstant: properties: id: type: integer description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)' example: 240 label: type: string example: 240p VideoScheduledUpdate: properties: privacy: $ref: '#/components/schemas/VideoPrivacySet' updateAt: type: string format: date 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 avatar: nullable: true allOf: - $ref: '#/components/schemas/ActorImage' VideoChannelSummary: properties: id: type: integer name: type: string displayName: type: string url: type: string format: url host: type: string format: hostname avatar: nullable: true allOf: - $ref: '#/components/schemas/ActorImage' PlaylistElement: properties: position: type: integer startTimestamp: type: integer stopTimestamp: type: integer video: nullable: true allOf: - $ref: '#/components/schemas/Video' VideoFile: properties: magnetUri: type: string 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 metadataUrl: type: string format: url VideoStreamingPlaylists: allOf: - type: object properties: id: type: integer type: type: integer enum: - 1 description: | Playlist type: - `1`: HLS - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS' VideoStreamingPlaylists-HLS: properties: 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: type: integer uuid: $ref: '#/components/schemas/UUIDv4' name: type: string minLength: 3 maxLength: 120 Video: properties: id: type: integer example: 8 uuid: $ref: '#/components/schemas/UUIDv4' isLive: type: boolean createdAt: type: string format: date-time example: 2017-10-01T10:52:46.396Z description: time at which the video object was first drafted publishedAt: type: string format: date-time example: 2018-10-01T10:52:46.396Z description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution. updatedAt: type: string format: date-time example: 2021-05-04T08:01:01.502Z description: last time the video's metadata was modified originallyPublishedAt: type: string format: date-time example: 2010-10-01T10:52:46.396Z description: used to represent a date of first publication, prior to the practical publication date of `publishedAt` category: $ref: '#/components/schemas/VideoConstantNumber-Category' licence: $ref: '#/components/schemas/VideoConstantNumber-Licence' language: $ref: '#/components/schemas/VideoConstantString-Language' privacy: $ref: '#/components/schemas/VideoPrivacyConstant' description: type: string example: | **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr... minLength: 3 maxLength: 250 description: | truncated description of the video, written in Markdown. Resolve `descriptionPath` to get the full description of maximum `10000` characters. duration: type: integer example: 1419 description: duration of the video in seconds isLocal: type: boolean name: type: string example: What is PeerTube? minLength: 3 maxLength: 120 thumbnailPath: type: string example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg previewPath: type: string example: /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: $ref: '#/components/schemas/VideoStateConstant' 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: descriptionPath: type: string example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description description: path at which to get the full description of maximum `10000` characters support: type: string description: A text tell the audience how to support the video creator example: Please support my work on ! <3 minLength: 3 maxLength: 1000 channel: $ref: '#/components/schemas/VideoChannel' account: $ref: '#/components/schemas/Account' tags: example: [flowers, gardening] type: array minItems: 1 maxItems: 5 items: type: string minLength: 2 maxLength: 30 commentsEnabled: type: boolean downloadEnabled: type: boolean trackerUrls: type: array items: type: string format: url files: type: array items: $ref: '#/components/schemas/VideoFile' description: | WebTorrent/raw video files. If WebTorrent is disabled on the server: - field will be empty - video files will be found in `streamingPlaylists[].files` field streamingPlaylists: type: array items: $ref: '#/components/schemas/VideoStreamingPlaylists' description: | HLS playlists/manifest files. If HLS is disabled on the server: - field will be empty - video files will be found in `files` field FileRedundancyInformation: properties: id: type: integer fileUrl: type: string format: url strategy: type: string enum: - manual - most-views - trending - recently-added size: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time expiresOn: type: string format: date-time VideoRedundancy: properties: id: type: integer name: type: string url: type: string format: url uuid: $ref: '#/components/schemas/UUIDv4' redundancies: type: object properties: files: type: array items: $ref: '#/components/schemas/FileRedundancyInformation' streamingPlaylists: type: array items: $ref: '#/components/schemas/FileRedundancyInformation' VideoImportStateConstant: properties: id: type: integer enum: - 1 - 2 - 3 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)' label: type: string example: Pending VideoImport: properties: id: type: integer example: 2 targetUrl: type: string format: url example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d magnetUri: type: string format: uri example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 torrentName: type: string state: $ref: '#/components/schemas/VideoImportStateConstant' error: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time video: $ref: '#/components/schemas/Video' Abuse: properties: id: type: integer example: 7 reason: type: string example: The video is a spam minLength: 2 maxLength: 3000 predefinedReasons: $ref: '#/components/schemas/AbusePredefinedReasons' reporterAccount: $ref: '#/components/schemas/Account' state: $ref: '#/components/schemas/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: type: integer message: type: string minLength: 2 maxLength: 3000 byModerator: type: boolean createdAt: type: string format: date-time account: $ref: '#/components/schemas/AccountSummary' VideoBlacklist: properties: id: type: integer videoId: type: integer 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 VideoChannel: properties: displayName: type: string minLength: 1 maxLength: 120 description: type: string minLength: 3 maxLength: 1000 isLocal: type: boolean ownerAccount: type: object properties: id: type: integer uuid: $ref: '#/components/schemas/UUIDv4' VideoPlaylist: properties: id: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time description: type: string minLength: 3 maxLength: 1000 uuid: $ref: '#/components/schemas/UUIDv4' displayName: type: string minLength: 1 maxLength: 120 isLocal: type: boolean videoLength: type: integer 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: type: integer url: type: string format: url text: type: string minLength: 1 maxLength: 10000 threadId: type: integer inReplyToCommentId: type: integer videoId: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time totalRepliesFromVideoAuthor: type: integer totalReplies: type: integer account: $ref: '#/components/schemas/Account' VideoCommentThreadTree: properties: comment: $ref: '#/components/schemas/VideoComment' children: type: array items: $ref: '#/components/schemas/VideoCommentThreadTree' VideoCaption: properties: language: $ref: '#/components/schemas/VideoConstantString-Language' captionPath: type: string ActorImage: properties: path: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time ActorInfo: properties: id: type: integer example: 11 name: type: string displayName: type: string host: type: string format: hostname avatar: nullable: true type: object properties: path: type: string Actor: properties: id: type: integer example: 11 url: type: string format: url name: type: string host: type: string format: hostname followingCount: type: integer followersCount: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time avatar: $ref: '#/components/schemas/ActorImage' Account: allOf: - $ref: '#/components/schemas/Actor' - properties: userId: type: string example: 2 displayName: type: string description: type: string UserWatchingVideo: properties: currentTime: type: integer description: timestamp within the video, in seconds example: 5 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 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 webtorrent: type: object properties: enabled: type: boolean enabledResolutions: type: array items: type: integer import: type: object properties: videos: type: object properties: http: type: object properties: enabled: type: boolean torrent: type: object properties: enabled: type: boolean 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 videoQuotaDaily: type: integer 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 ServerConfigAbout: properties: instance: type: object properties: name: type: string shortDescription: type: string description: type: string terms: type: string 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 whitelisted: type: boolean 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 properties: videoQuota: type: integer videoQuotaDaily: type: integer transcoding: type: object properties: enabled: type: boolean allowAdditionalExtensions: type: boolean allowAudioFiles: type: boolean threads: type: integer resolutions: type: object properties: 240p: type: boolean 360p: type: boolean 480p: type: boolean 720p: type: boolean 1080p: type: boolean 1440p: type: boolean 2160p: type: boolean hls: type: object 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 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 Follow: properties: id: type: integer follower: $ref: '#/components/schemas/Actor' following: $ref: '#/components/schemas/Actor' score: type: number description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`. state: type: string enum: - pending - accepted createdAt: type: string format: date-time updatedAt: type: string format: date-time PredefinedAbuseReasons: description: Reason categories that help triage reports type: array items: type: string enum: - violentOrAbusive - hatefulOrAbusive - spamOrMisleading - privacy - rights - serverRules - thumbnails - captions Job: properties: id: type: integer minimum: 0 example: 42 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 - activitypub-refresher - video-redundancy data: type: object additionalProperties: true error: type: object additionalProperties: true createdAt: type: string format: date-time finishedOn: type: string format: date-time processedOn: type: string format: date-time AddUserResponse: properties: user: type: object properties: id: type: integer example: 8 account: type: object properties: id: type: integer example: 37 VideoUploadResponse: properties: video: type: object properties: id: type: integer example: 8 uuid: $ref: '#/components/schemas/UUIDv4' CommentThreadResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/VideoComment' CommentThreadPostResponse: properties: comment: $ref: '#/components/schemas/VideoComment' VideoListResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Video' User: properties: id: type: integer readOnly: true username: type: string description: The user username minLength: 1 maxLength: 50 email: type: string format: email description: The user email pluginAuth: type: string description: Auth plugin to use to authenticate the user theme: type: string description: Theme enabled by this user emailVerified: type: boolean description: Has the user confirmed their email address? nsfwPolicy: $ref: '#/components/schemas/NSFWPolicy' webtorrentEnabled: type: boolean description: Enable P2P in the player autoPlayVideo: type: boolean description: Automatically start playing the video on the watch page role: $ref: '#/components/schemas/UserRole' roleLabel: type: string enum: - User - Moderator - Administrator videoQuota: type: integer description: The user video quota videoQuotaDaily: type: integer description: The user daily video quota videosCount: type: integer abusesCount: type: integer abusesAcceptedCount: type: integer abusesCreatedCount: type: integer videoCommentsCount: type: integer noInstanceConfigWarningModal: type: boolean noWelcomeModal: type: boolean blocked: type: boolean blockedReason: type: string createdAt: type: string account: $ref: '#/components/schemas/Account' videoChannels: type: array items: $ref: '#/components/schemas/VideoChannel' AddUser: properties: username: type: string description: The user username minLength: 1 maxLength: 50 password: type: string format: password description: The user password. If the smtp server is configured, you can leave empty and an email will be sent minLength: 6 maxLength: 255 email: type: string format: email description: The user email videoQuota: type: integer description: The user video quota videoQuotaDaily: type: integer description: The user daily video quota channelName: type: string description: The user default channel username role: $ref: '#/components/schemas/UserRole' adminFlags: $ref: '#/components/schemas/UserAdminFlags' required: - username - password - email - videoQuota - videoQuotaDaily - role UpdateUser: properties: id: type: string description: The user id email: type: string format: email description: The updated email of the user emailVerified: type: boolean description: Set the email as verified videoQuota: type: integer description: The updated video quota of the user videoQuotaDaily: type: integer description: The updated daily video quota of the user pluginAuth: type: string nullable: true description: The auth plugin to use to authenticate the user example: 'peertube-plugin-auth-saml2' role: $ref: '#/components/schemas/UserRole' adminFlags: $ref: '#/components/schemas/UserAdminFlags' required: - id UpdateMe: properties: password: type: string format: password description: Your new password minLength: 6 maxLength: 255 email: type: string format: email description: Your new email displayNSFW: type: string description: Your new displayNSFW enum: - 'true' - 'false' - both autoPlayVideo: type: boolean description: Your new autoPlayVideo required: - password - email - displayNSFW - autoPlayVideo GetMeVideoRating: properties: id: type: string description: Id of the video rating: type: number description: Rating of the video required: - id - rating VideoRating: properties: video: $ref: '#/components/schemas/Video' rating: type: number description: 'Rating of the video' required: - video - rating RegisterUser: properties: username: type: string description: The username of the user minLength: 1 maxLength: 50 pattern: '/^[a-z0-9._]{1,50}$/' password: type: string format: password description: The password of the user minLength: 6 maxLength: 255 email: type: string format: email description: The email of the user displayName: type: string description: The user display name minLength: 1 maxLength: 120 channel: type: object properties: name: type: string description: The username for the default channel pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' displayName: type: string description: The display name for the default channel minLength: 1 maxLength: 120 required: - username - password - email VideoChannelCommon: properties: displayName: type: string minLength: 1 maxLength: 120 description: type: string minLength: 3 maxLength: 1000 support: type: string description: 'A text shown by default on all videos of this channel, to tell the audience how to support it' example: Please support my work on ! <3 minLength: 3 maxLength: 1000 VideoChannelCreate: allOf: - $ref: '#/components/schemas/VideoChannelCommon' - properties: name: type: string minLength: 1 maxLength: 120 required: - name - displayName VideoChannelUpdate: allOf: - $ref: '#/components/schemas/VideoChannelCommon' - properties: bulkVideosSupportUpdate: type: boolean description: 'Update the support field for all videos of this channel' MRSSPeerLink: type: object xml: name: 'media:peerLink' properties: href: type: string xml: attribute: true type: type: string enum: - application/x-bittorrent xml: attribute: true MRSSGroupContent: type: object xml: name: 'media:content' properties: url: type: string format: url xml: attribute: true fileSize: type: integer xml: attribute: true type: type: string xml: attribute: true framerate: type: integer xml: attribute: true duration: type: integer xml: attribute: true height: type: integer xml: attribute: true lang: type: string xml: attribute: true VideoCommentsForXML: type: array xml: wrapped: true name: 'channel' items: type: object xml: name: 'item' properties: link: type: string format: url guid: type: string pubDate: type: string format: date-time 'content:encoded': type: string 'dc:creator': type: string VideosForXML: type: array xml: wrapped: true name: 'channel' items: type: object xml: name: 'item' properties: link: type: string format: url description: video watch page URL guid: type: string description: video canonical URL pubDate: type: string format: date-time description: video publication date description: type: string description: video description 'content:encoded': type: string description: video description 'dc:creator': type: string description: publisher user name 'media:category': type: integer description: video category (MRSS) 'media:community': type: object description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS) properties: 'media:statistics': type: object properties: views: type: integer xml: attribute: true 'media:embed': type: object properties: url: type: string format: url description: video embed path, relative to the canonical URL domain (MRSS) xml: attribute: true 'media:player': type: object properties: url: type: string format: url description: video watch path, relative to the canonical URL domain (MRSS) xml: attribute: true 'media:thumbnail': type: object properties: url: type: string format: url xml: attribute: true height: type: integer xml: attribute: true width: type: integer xml: attribute: true 'media:title': type: string description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles. 'media:description': type: string 'media:rating': type: string enum: - nonadult - adult description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS) 'enclosure': type: object description: main streamable file for the video properties: url: type: string format: url xml: attribute: true type: type: string enum: - application/x-bittorrent xml: attribute: true length: type: integer xml: attribute: true 'media:group': type: array description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS) items: anyOf: - $ref: '#/components/schemas/MRSSPeerLink' - $ref: '#/components/schemas/MRSSGroupContent' NotificationSettingValue: type: integer description: > Notification type - `0` NONE - `1` WEB - `2` EMAIL enum: - 0 - 1 - 3 Notification: properties: id: type: integer type: type: integer description: > Notification type, following the `UserNotificationType` enum: - `1` NEW_VIDEO_FROM_SUBSCRIPTION - `2` NEW_COMMENT_ON_MY_VIDEO - `3` NEW_ABUSE_FOR_MODERATORS - `4` BLACKLIST_ON_MY_VIDEO - `5` UNBLACKLIST_ON_MY_VIDEO - `6` MY_VIDEO_PUBLISHED - `7` MY_VIDEO_IMPORT_SUCCESS - `8` MY_VIDEO_IMPORT_ERROR - `9` NEW_USER_REGISTRATION - `10` NEW_FOLLOW - `11` COMMENT_MENTION - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS - `13` NEW_INSTANCE_FOLLOWER - `14` AUTO_INSTANCE_FOLLOWING read: type: boolean video: nullable: true allOf: - $ref: '#/components/schemas/VideoInfo' - type: object properties: channel: $ref: '#/components/schemas/ActorInfo' videoImport: nullable: true type: object properties: id: type: integer video: nullable: true $ref: '#/components/schemas/VideoInfo' torrentName: type: string nullable: true magnetUri: type: string format: uri nullable: true targetUri: type: string format: uri nullable: true comment: nullable: true type: object properties: id: type: integer threadId: type: integer video: $ref: '#/components/schemas/VideoInfo' account: $ref: '#/components/schemas/ActorInfo' videoAbuse: nullable: true type: object properties: id: type: integer video: allOf: - $ref: '#/components/schemas/VideoInfo' videoBlacklist: nullable: true type: object properties: id: type: integer video: allOf: - $ref: '#/components/schemas/VideoInfo' account: nullable: true allOf: - $ref: '#/components/schemas/ActorInfo' actorFollow: type: object nullable: true properties: id: type: integer follower: $ref: '#/components/schemas/ActorInfo' state: type: string enum: - pending - accepted following: type: object properties: type: type: string enum: - account - channel - instance name: type: string displayName: type: string host: type: string format: hostname createdAt: type: string format: date-time updatedAt: type: string format: date-time NotificationListResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Notification' Plugin: properties: name: type: string example: peertube-plugin-auth-ldap type: type: integer description: > - `1`: PLUGIN - `2`: THEME enum: - 1 - 2 latestVersion: type: string example: 0.0.3 version: type: string example: 0.0.1 enabled: type: boolean uninstalled: type: boolean peertubeEngine: type: string example: 2.2.0 description: type: string homepage: type: string format: url example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap settings: type: object additionalProperties: true createdAt: type: string format: date-time updatedAt: type: string format: date-time PluginResponse: properties: total: type: integer example: 1 data: type: array maxItems: 100 items: $ref: '#/components/schemas/Plugin' LiveVideoUpdate: properties: saveReplay: type: boolean permanentLive: description: User can stream multiple times in a permanent live type: boolean LiveVideoResponse: properties: rtmpUrl: type: string streamKey: type: string description: RTMP stream key to use to stream into this live video saveReplay: type: boolean permanentLive: description: User can stream multiple times in a permanent live type: boolean callbacks: searchIndex: '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'