openapi: 3.0.0 info: title: PeerTube version: 1.3.1 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). Our API is RESTful. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use PeerTube. No official SDK is currently provided, but the spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice. # 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. # 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.html tags: - name: Accounts description: > Using some features of PeerTube require authentication, for which Accounts provide different levels of permission as well as associated user information. Accounts also encompass remote accounts discovered across the federation. - name: Config description: > Each server exposes public information regarding supported videos and options. - name: Feeds description: | Feeds of videos and feeds of comments allow to see updates and get them in an aggregator or script of your choice. - name: Job description: > Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available. - name: Server Following 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. - name: Video Abuse description: | Video abuses deal with reports of local or remote videos alike. - name: Video description: | Operations dealing with listing, uploading, fetching or modifying videos. - name: Search description: | The search helps to find _videos_ from within the instance and beyond. Videos from other instances federated by the instance (that is, instances followed by the instance) can be found via keywords and other criteria of the advanced search. - name: Video Comment description: > Operations dealing with comments to a video. Comments are organized in threads. - name: Video Channel description: > Operations dealing with creation, modification and video listing of a user's channels. - name: Video Blacklist description: > Operations dealing with blacklisting videos (removing them from view and preventing interactions). - name: Video Rate description: > Voting for a video. x-tagGroups: - name: Accounts tags: - Accounts - User - name: Videos tags: - Video - Video Channel - Video Comment - Video Following - Video Rate - name: Moderation tags: - Video Abuse - Video Blacklist - name: Instance Configuration tags: - Config - Server Following - name: Notifications tags: - Feeds - name: Jobs tags: - Job - name: Search tags: - Search paths: '/accounts/{name}': get: tags: - Accounts summary: Get the account by name parameters: - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Account' '/accounts/{name}/videos': get: tags: - Accounts - Video summary: 'Get videos for an account, provided the name of that account' parameters: - $ref: '#/components/parameters/name' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Video' 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: | # pip install httpie http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos - lang: Ruby source: | require 'uri' require 'net/http' url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Post.new(url) request["content-type"] = 'application/json' response = http.request(request) puts response.read_body - lang: Python source: | import http.client conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1") headers = { 'content-type': "application/json" } conn.request("POST", "/accounts/{name}/videos", None, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) /accounts: get: tags: - Accounts summary: Get all accounts responses: '200': description: successful operation content: 'application/json': schema: type: array items: $ref: '#/components/schemas/Account' /config: get: tags: - Config summary: Get the public configuration of the server responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/ServerConfig' /config/about: get: summary: Get the instance about page content tags: - Config responses: '200': description: successful operation /config/custom: get: summary: Get the runtime configuration of the server tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation put: summary: Set the runtime configuration of the server tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation delete: summary: Delete the runtime configuration of the server tags: - Config security: - OAuth2: - admin responses: '200': description: successful operation '/feeds/videos.{format}': get: summary: >- Get the feed of videos for the server, with optional filter by account name or id tags: - Feeds parameters: - name: format in: path required: true description: >- The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and json to JSON FEED 1.0 schema: type: string enum: - xml - atom - json default: xml - name: accountId in: query required: false description: >- The id of the local account to filter to (beware, users IDs and not actors IDs which will return empty feeds schema: type: number - name: accountName in: query required: false description: The name of the local account to filter to schema: type: string responses: '200': description: successful operation /jobs/{state}: get: summary: Get list of jobs security: - OAuth2: - admin tags: - Job parameters: - name: state in: path required: true description: The state of the job schema: type: string enum: - active - completed - failed - waiting - delayed - $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/Job' '/server/following/{host}': delete: security: - OAuth2: - admin tags: - Server Following summary: Unfollow a server by hostname parameters: - name: host in: path required: true description: 'The host to unfollow ' schema: type: string responses: '201': description: successful operation /server/followers: get: tags: - Server Following summary: Get followers of the server 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: - Server Following summary: Get servers followed by the server 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' post: security: - OAuth2: - admin tags: - Server Following summary: Follow a server responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' requestBody: content: application/json: schema: $ref: '#/components/schemas/Follow' /users: post: summary: Creates user security: - OAuth2: - admin tags: - User responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/AddUserResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/AddUser' description: User to create required: true get: summary: Get a list of users security: - OAuth2: [] tags: - User parameters: - $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}': delete: summary: Delete a user by its id security: - OAuth2: - admin tags: - User parameters: - $ref: '#/components/parameters/id' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' get: summary: Get user by its id security: - OAuth2: [] tags: - User parameters: - $ref: '#/components/parameters/id' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/User' put: summary: Update user profile by its id security: - OAuth2: [] tags: - User parameters: - $ref: '#/components/parameters/id' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateUser' required: true /users/me: get: summary: Get current user information security: - OAuth2: - user tags: - User responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/User' put: summary: Update current user information security: - OAuth2: - user tags: - User responses: '204': description: Successful operation requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateMe' required: true /users/me/video-quota-used: get: summary: Get current user used quota security: - OAuth2: - user tags: - User responses: '200': description: successful operation content: application/json: schema: type: number '/users/me/videos/{videoId}/rating': get: summary: 'Get rating of video by its id, among those of the current user' security: - OAuth2: [] tags: - User 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 the current user security: - OAuth2: - user tags: - User 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/Video' /users/me/subscriptions: get: summary: Get subscriptions of the current user security: - OAuth2: - user tags: - User parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation post: summary: Add subscription to the current user security: - OAuth2: - user tags: - User responses: '200': description: successful operation /users/me/subscriptions/exist: get: summary: Get if subscriptions exist for the current user security: - OAuth2: - user tags: - User parameters: - $ref: '#/components/parameters/subscriptionsUris' responses: '200': description: successful operation content: application/json: schema: type: object /users/me/subscriptions/videos: get: summary: Get videos of subscriptions of the current user security: - OAuth2: - user tags: - User 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/Video' '/users/me/subscriptions/{uri}': get: summary: Get subscription of the current user for a given uri security: - OAuth2: - user tags: - User responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannel' delete: summary: Delete subscription of the current user for a given uri security: - OAuth2: - user tags: - User responses: '200': description: successful operation /users/register: post: summary: Register a user tags: - User responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' requestBody: content: application/json: schema: $ref: '#/components/schemas/RegisterUser' required: true /users/me/avatar/pick: post: summary: Update current user avatar security: - OAuth2: [] tags: - User responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Avatar' requestBody: content: multipart/form-data: schema: type: object properties: avatarfile: description: The file to upload. type: string format: binary encoding: profileImage: # only accept png/jpeg contentType: image/png, image/jpeg /videos: get: summary: Get list of videos tags: - Video parameters: - $ref: '#/components/parameters/categoryOneOf' - $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/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Video' /videos/categories: get: summary: Get list of video licences known by the server tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string /videos/licences: get: summary: Get list of video licences known by the server tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string /videos/languages: get: summary: Get list of languages known by the server tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string /videos/privacies: get: summary: Get list of privacy policies supported by the server tags: - Video responses: '200': description: successful operation content: application/json: schema: type: array items: type: string '/videos/{id}': put: summary: Update metadata for a video by its id security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/id2' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Video' requestBody: content: multipart/form-data: schema: type: object properties: thumbnailfile: description: Video thumbnail file type: string previewfile: description: Video preview file type: string category: description: Video category type: string licence: description: Video licence type: string language: description: Video language type: string description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: string support: description: Text describing how to support the video uploader type: string nsfw: description: Whether or not this video contains sensitive content type: string name: description: Video name type: string tags: description: Video tags (maximum 5 tags each between 2 and 30 characters) type: array items: type: string commentsEnabled: description: Enable or disable comments for this video type: string scheduleUpdate: &ref_0 type: object properties: privacy: type: string enum: - Public - Unlisted description: Video privacy target updateAt: type: string format: date description: When to update the video required: - updateAt get: summary: Get a video by its id tags: - Video parameters: - $ref: '#/components/parameters/id2' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Video' delete: summary: Delete a video by its id security: - OAuth2: [] tags: - Video parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/{id}/description': get: summary: Get a video description by its id tags: - Video parameters: - $ref: '#/components/parameters/id2' responses: '200': description: successful operation content: application/json: schema: type: string '/videos/{id}/views': post: summary: Add a view to the video by its id tags: - Video parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/{id}/watching': put: summary: Set watching progress of a video by its id for a user tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/id2' requestBody: content: application/json: schema: $ref: '#/components/schemas/UserWatchingVideo' required: true responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' /videos/ownership: get: summary: Get list of video ownership changes requests tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/id2' responses: '200': description: successful operation '/videos/ownership/{id}/accept': post: summary: Refuse ownership change request for video by its id tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/ownership/{id}/refuse': post: summary: Accept ownership change request for video by its id tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/{id}/give-ownership': post: summary: Request change of ownership for a video you own, by its id tags: - Video security: - OAuth2: [] parameters: - $ref: '#/components/parameters/id2' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: username: type: string required: - username responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '400': description: 'Changing video ownership to a remote account is not supported yet' /videos/upload: post: summary: Upload a video file with its metadata security: - OAuth2: [] tags: - Video responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' requestBody: content: multipart/form-data: schema: type: object properties: videofile: description: Video file type: string format: binary channelId: description: Channel id that will contain this video type: number thumbnailfile: description: Video thumbnail file type: string previewfile: description: Video preview file type: string privacy: $ref: '#/components/schemas/VideoPrivacy' category: description: Video category type: string licence: description: Video licence type: string language: description: Video language type: string description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: string support: description: Text describing how to support the video uploader type: string nsfw: description: Whether or not this video contains sensitive content type: string name: description: Video name type: string tags: description: Video tags type: array items: type: string commentsEnabled: description: Enable or disable comments for this video type: string scheduleUpdate: *ref_0 required: - videofile - channelId - name x-code-samples: - lang: Shell source: | ## DEPENDENCIES: httpie, jq # pip install httpie USERNAME="" PASSWORD="" FILE_PATH="" CHANNEL_ID="" NAME="" API_PATH="https://peertube2.cpy.re/api/v1" ## AUTH client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id") client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret") token=$(http -b --form POST "$API_PATH/users/token" \ client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \ username=$USERNAME \ password=$PASSWORD \ | jq -r ".access_token") ## VIDEO UPLOAD http -b --form POST "$API_PATH/videos/upload" \ videofile@$FILE_PATH \ channelId=$CHANNEL_ID \ name=$NAME \ "Authorization:Bearer $token" /videos/imports: post: summary: Import a torrent or magnetURI or HTTP ressource (if enabled by the instance administrator) security: - OAuth2: [] tags: - Video responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoUploadResponse' 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: number thumbnailfile: description: Video thumbnail file type: string previewfile: description: Video preview file type: string privacy: $ref: '#/components/schemas/VideoPrivacy' category: description: Video category type: string licence: description: Video licence type: string language: description: Video language type: string description: description: Video description type: string waitTranscoding: description: Whether or not we wait transcoding before publish the video type: string support: description: Text describing how to support the video uploader type: string nsfw: description: Whether or not this video contains sensitive content type: string name: description: Video name type: string tags: description: Video tags type: array items: type: string commentsEnabled: description: Enable or disable comments for this video type: string scheduleUpdate: *ref_0 required: - channelId - name /videos/abuse: get: summary: Get list of reported video abuses security: - OAuth2: [] tags: - Video Abuse parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/abusesSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoAbuse' '/videos/{id}/abuse': post: summary: 'Report an abuse, on a video by its id' security: - OAuth2: [] tags: - Video Abuse parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/{id}/blacklist': post: summary: Put on blacklist a video by its id security: - OAuth2: - admin - moderator tags: - Video Blacklist parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' delete: summary: Delete an entry of the blacklist of a video by its id security: - OAuth2: - admin - moderator tags: - Video Blacklist parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' /videos/blacklist: get: summary: Get list of videos on blacklist security: - OAuth2: - admin - moderator tags: - Video Blacklist parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/blacklistsSort' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoBlacklist' /video-channels: get: summary: Get list of video channels tags: - Video Channel 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/VideoChannel' post: summary: Creates a video channel for the current user security: - OAuth2: [] tags: - Video Channel responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' requestBody: $ref: '#/components/requestBodies/VideoChannelInput' '/video-channels/{channelHandle}': get: summary: Get a video channel by its id tags: - Video Channel parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoChannel' put: summary: Update a video channel by its id security: - OAuth2: [] tags: - Video Channel parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' requestBody: $ref: '#/components/requestBodies/VideoChannelInput' delete: summary: Delete a video channel by its id security: - OAuth2: [] tags: - Video Channel parameters: - $ref: '#/components/parameters/channelHandle' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/video-channels/{channelHandle}/videos': get: summary: Get videos of a video channel by its id tags: - Video Channel parameters: - $ref: '#/components/parameters/channelHandle' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Video' '/accounts/{name}/video-channels': get: summary: Get video channels of an account by its name tags: - Video Channel parameters: - $ref: '#/components/parameters/name' responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/VideoChannel' '/accounts/{name}/ratings': get: summary: Get ratings of an account by its name security: - OAuth2: [] tags: - User parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' - name: rating in: query required: false description: Optionaly 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: Get the comment threads of a video by its id tags: - Video Comment parameters: - $ref: '#/components/parameters/id2' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/sort' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadResponse' post: summary: 'Creates a comment thread, on a video by its id' security: - OAuth2: [] tags: - Video Comment parameters: - $ref: '#/components/parameters/id2' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' '/videos/{id}/comment-threads/{threadId}': get: summary: 'Get the comment thread by its id, of a video by its id' tags: - Video Comment parameters: - $ref: '#/components/parameters/id2' - name: threadId in: path required: true description: The thread id (root comment id) schema: type: number responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/VideoCommentThreadTree' '/videos/{id}/comments/{commentId}': post: summary: 'Creates a comment in a comment thread by its id, of a video by its id' security: - OAuth2: [] tags: - Video Comment parameters: - $ref: '#/components/parameters/id2' - $ref: '#/components/parameters/commentId' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/CommentThreadPostResponse' delete: summary: 'Delete a comment in a comment therad by its id, of a video by its id' security: - OAuth2: [] tags: - Video Comment parameters: - $ref: '#/components/parameters/id2' - $ref: '#/components/parameters/commentId' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' '/videos/{id}/rate': put: summary: Vote for a video by its id security: - OAuth2: [] tags: - Video Rate parameters: - $ref: '#/components/parameters/id2' responses: '204': $ref: '#/paths/~1users~1me/put/responses/204' /search/videos: get: tags: - Search summary: Get the videos corresponding to a given query parameters: - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/videosSearchSort' - name: search in: query required: true description: String to search schema: type: string responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Video' servers: - url: 'https://peertube.cpy.re/api/v1' description: Live Test Server (live data - stable version) - url: 'https://peertube2.cpy.re/api/v1' description: Live Test Server (live data - bleeding edge version) - url: 'https://peertube3.cpy.re/api/v1' description: Live Test Server (live data - bleeding edge version) components: parameters: start: name: start in: query required: false description: Offset schema: type: number count: name: count in: query required: false description: Number of items schema: type: number sort: name: sort in: query required: false description: Sort column (-createdAt for example) schema: type: string videosSort: name: sort in: query required: false description: Sort videos by criteria schema: type: string enum: - -name - -duration - -createdAt - -publishedAt - -views - -likes - -trending videosSearchSort: name: sort in: query required: false description: Sort videos by criteria schema: type: string enum: - -name - -duration - -createdAt - -publishedAt - -views - -likes - -match blacklistsSort: name: sort in: query required: false description: Sort blacklists by criteria schema: type: string enum: - -id - -name - -duration - -views - -likes - -dislikes - -uuid - -createdAt usersSort: name: sort in: query required: false description: Sort users by criteria schema: type: string enum: - -id - -username - -createdAt abusesSort: name: sort in: query required: false description: Sort abuses by criteria schema: type: string enum: - -id - -createdAt - -state name: name: name in: path required: true description: >- The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for example) schema: type: string id: name: id in: path required: true description: The user id schema: type: number id2: name: id in: path required: true description: The video id or uuid schema: type: string channelHandle: name: channelHandle in: path required: true description: "The video channel handle (example: 'my_username@example.com' or 'my_username')" schema: type: string commentId: name: threadId in: path required: true description: The comment id schema: type: number categoryOneOf: name: categoryOneOf in: query required: false description: category id of the video schema: oneOf: - type: number - type: array items: type: number 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 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 schema: oneOf: - type: number - type: array items: type: number style: form explode: 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 (local for instance) 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) 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 requestBodies: VideoChannelInput: content: application/json: schema: $ref: '#/components/schemas/VideoChannelInput' 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/lang/en/devdocs/rest.html) 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: VideoConstantNumber: properties: id: type: number label: type: string VideoConstantString: properties: id: type: string label: type: string VideoPrivacy: type: string enum: - Public - Unlisted - Private Video: properties: id: type: number uuid: type: string createdAt: type: string publishedAt: type: string updatedAt: type: string category: $ref: '#/components/schemas/VideoConstantNumber' licence: $ref: '#/components/schemas/VideoConstantNumber' language: $ref: '#/components/schemas/VideoConstantString' privacy: $ref: '#/components/schemas/VideoPrivacy' description: type: string duration: type: number isLocal: type: boolean name: type: string thumbnailPath: type: string previewPath: type: string embedPath: type: string views: type: number likes: type: number dislikes: type: number nsfw: type: boolean account: type: object properties: name: type: string displayName: type: string url: type: string host: type: string avatar: $ref: '#/components/schemas/Avatar' VideoAbuse: properties: id: type: number reason: type: string reporterAccount: $ref: '#/components/schemas/Account' video: type: object properties: id: type: number name: type: string uuid: type: string url: type: string createdAt: type: string VideoBlacklist: properties: id: type: number videoId: type: number createdAt: type: string updatedAt: type: string name: type: string uuid: type: string description: type: string duration: type: number views: type: number likes: type: number dislikes: type: number nsfw: type: boolean VideoChannel: properties: displayName: type: string description: type: string isLocal: type: boolean ownerAccount: type: object properties: id: type: number uuid: type: string VideoComment: properties: id: type: number url: type: string text: type: string threadId: type: number inReplyToCommentId: type: number videoId: type: number createdAt: type: string updatedAt: type: string totalReplies: type: number account: $ref: '#/components/schemas/Account' VideoCommentThreadTree: properties: comment: $ref: '#/components/schemas/VideoComment' children: type: array items: $ref: '#/components/schemas/VideoCommentThreadTree' Avatar: properties: path: type: string createdAt: type: string updatedAt: type: string Actor: properties: id: type: number uuid: type: string url: type: string name: type: string host: type: string followingCount: type: number followersCount: type: number createdAt: type: string updatedAt: type: string avatar: $ref: '#/components/schemas/Avatar' Account: allOf: - $ref: '#/components/schemas/Actor' - properties: displayName: type: string User: properties: id: type: number username: type: string email: type: string displayNSFW: type: boolean autoPlayVideo: type: boolean role: type: string enum: - User - Moderator - Administrator videoQuota: type: number videoQuotaDaily: type: number createdAt: type: string account: $ref: '#/components/schemas/Account' videoChannels: type: array items: $ref: '#/components/schemas/VideoChannel' UserWatchingVideo: properties: currentTime: type: number ServerConfig: properties: signup: type: object properties: allowed: type: boolean transcoding: type: object properties: enabledResolutions: type: array items: type: number avatar: type: object properties: file: type: object properties: size: type: object properties: max: type: number extensions: type: array items: type: string video: type: object properties: file: type: object properties: extensions: type: array items: type: string Follow: properties: id: type: number follower: $ref: '#/components/schemas/Actor' following: $ref: '#/components/schemas/Actor' score: type: number state: type: string enum: - pending - accepted createdAt: type: string updatedAt: type: string Job: properties: id: type: number state: type: string enum: - pending - processing - error - success category: type: string enum: - transcoding - activitypub-http handlerName: type: string handlerInputData: type: string createdAt: type: string updatedAt: type: string AddUserResponse: properties: id: type: number uuid: type: string VideoUploadResponse: properties: video: type: object properties: id: type: number uuid: type: string CommentThreadResponse: properties: total: type: number data: type: array items: $ref: '#/components/schemas/VideoComment' CommentThreadPostResponse: properties: comment: $ref: '#/components/schemas/VideoComment' AddUser: properties: username: type: string description: 'The user username ' password: type: string description: 'The user password ' email: type: string description: 'The user email ' videoQuota: type: string description: 'The user videoQuota ' videoQuotaDaily: type: string description: 'The user daily video quota ' role: type: integer format: int32 enum: - 0 - 1 - 2 description: 'The user role ' required: - username - password - email - videoQuota - videoQuotaDaily - role UpdateUser: properties: id: type: string description: 'The user id ' email: type: string description: 'The updated email of the user ' videoQuota: type: string description: 'The updated videoQuota of the user ' videoQuotaDaily: type: string description: 'The updated daily video quota of the user ' role: type: string description: 'The updated role of the user ' required: - id - email - videoQuota - videoQuotaDaily - role UpdateMe: properties: password: type: string description: 'Your new password ' email: type: string description: 'Your new email ' displayNSFW: type: string description: 'Your new displayNSFW ' autoPlayVideo: type: string 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 ' password: type: string description: 'The password of the user ' email: type: string description: 'The email of the user ' required: - username - password - email VideoChannelInput: properties: name: type: string description: type: string