openapi: 3.0.0
info:
title: PeerTube
- version: 3.2.0-rc.1
+ version: 3.2.1
contact:
name: PeerTube Community
url: https://joinpeertube.org
- [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
- examples of using with the PeerTube API.
+ examples of using the PeerTube API.
# Authentication
# Errors
The API uses standard HTTP status codes to indicate the success or failure
- of the API call.
+ of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
```
HTTP 1.1 404 Not Found
- Content-Type: application/json
+ Content-Type: application/problem+json; charset=utf-8
{
- "errorCode": 1
- "error": "Account not found"
+ "detail": "Video not found",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 404,
+ "title": "Not Found",
+ "type": "about:blank"
}
```
- We provide error codes for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
- but it is still optional.
+ We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
+ but it is still optional. Types are used to disambiguate errors that bear the same status code
+ and are non-obvious:
+
+ ```
+ HTTP 1.1 403 Forbidden
+ Content-Type: application/problem+json; charset=utf-8
+
+ {
+ "detail": "Cannot get this video regarding follow constraints",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 403,
+ "title": "Forbidden",
+ "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+ }
+ ```
+
+ Here a 403 error could otherwise mean that the video is private or blocklisted.
### Validation errors
Each parameter is evaluated on its own against a set of rules before the route validator
- proceeds with potential testing involving parameter combinations. Errors coming from Validation
- errors appear earlier and benefit from a more detailed error type:
+ proceeds with potential testing involving parameter combinations. Errors coming from validation
+ errors appear earlier and benefit from a more detailed error description:
```
HTTP 1.1 400 Bad Request
- Content-Type: application/json
+ Content-Type: application/problem+json; charset=utf-8
{
- "errors": {
- "id": { //
- "value": "a117eb-c6a9-4756-bb09-2a956239f",
- "msg": "Should have a valid id",
+ "detail": "Incorrect request parameters: id",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
+ "invalid-params": {
+ "id": {
+ "location": "params",
+ "msg": "Invalid value",
"param": "id",
- "location": "params"
+ "value": "9c9de5e8-0a1e-484a-b099-e80766180"
}
- }
+ },
+ "status": 400,
+ "title": "Bad Request",
+ "type": "about:blank"
}
```
Where `id` is the name of the field concerned by the error, within the route definition.
- `errors.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
- `errors.<field>.value` reports the value that didn't pass validation whose `errors.<field>.msg`
+ `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
+ `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
is about.
+ ### Deprecated error fields
+
+ Some fields could be included with previous versions. They are still included but their use is deprecated:
+ - `error`: superseded by `detail`
+ - `code`: superseded by `type` (which is now an URI)
+
# Rate limits
We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
allowing cross-domain communication from the browser for some routes:
-
+
| Endpoint |
|------------------------- ---|
| `/api/*` |
- name: Register
description: |
As a visitor, you can use this API to open an account (if registrations are open on
- that PeerTube instance). As an admin, you should use the dedicated [User creation
- API](#operation/createUser) instead.
+ that PeerTube instance). As an admin, you should use the dedicated [User creation
+ API](#operation/addUser) instead.
- name: Session
x-displayName: Login/Logout
description: |
Administrators can also enable the use of a remote search system, indexing
videos and channels not could be not federated by the instance.
+ - name: Homepage
+ description: Get and update the custom homepage
- name: Video Mirroring
description: |
PeerTube instances can mirror videos from one another, and help distribute some videos.
- name: Search
tags:
- Search
+ - name: Custom pages
+ tags:
+ - Homepage
- name: Moderation
tags:
- Abuses
tags:
- Accounts
summary: Get an account
+ operationId: getAccount
parameters:
- $ref: '#/components/parameters/name'
responses:
$ref: '#/components/schemas/Account'
'404':
description: account not found
+
'/accounts/{name}/videos':
get:
tags:
- Accounts
- Video
summary: 'List videos of an account'
+ operationId: getAccountVideos
parameters:
- $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/categoryOneOf'
json = r.json()
print(json)
+
/accounts:
get:
tags:
- Accounts
summary: List accounts
+ operationId: getAccounts
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
type: array
items:
$ref: '#/components/schemas/Account'
+
/config:
get:
tags:
- Config
summary: Get instance public configuration
+ operationId: getConfig
responses:
'200':
description: successful operation
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/config
+
/config/about:
get:
summary: Get instance "About" information
+ operationId: getAbout
tags:
- Config
responses:
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/config/about
+
/config/custom:
get:
summary: Get instance runtime configuration
+ operationId: getCustomConfig
tags:
- Config
security:
$ref: '#/components/schemas/ServerConfigCustom'
put:
summary: Set instance runtime configuration
+ operationId: putCustomConfig
tags:
- Config
security:
- webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
delete:
summary: Delete instance runtime configuration
+ operationId: delCustomConfig
tags:
- Config
security:
responses:
'200':
description: successful operation
+
+ /custom-pages/homepage/instance:
+ get:
+ summary: Get instance custom homepage
+ tags:
+ - Homepage
+ responses:
+ '404':
+ description: No homepage set
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CustomHomepage'
+ put:
+ summary: Set instance custom homepage
+ tags:
+ - Homepage
+ security:
+ - OAuth2:
+ - admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ content:
+ type: string
+ description: content of the homepage, that will be injected in the client
+ responses:
+ '204':
+ description: successful operation
+
/jobs/{state}:
get:
summary: List instance jobs
+ operationId: getJobs
security:
- OAuth2:
- admin
maxItems: 100
items:
$ref: '#/components/schemas/Job'
- '/server/following/{host}':
+
+ /server/followers:
+ get:
+ tags:
+ - Instance Follows
+ summary: List instances following the server
+ parameters:
+ - $ref: '#/components/parameters/followState'
+ - $ref: '#/components/parameters/actorType'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
+
+ '/server/followers/{nameWithHost}':
delete:
+ summary: Remove or reject a follower to your server
security:
- OAuth2:
- admin
tags:
- Instance Follows
- summary: Unfollow a server
parameters:
- - name: host
+ - name: nameWithHost
in: path
required: true
- description: 'The host to unfollow '
+ description: The remote actor handle to remove from your followers
schema:
type: string
- format: hostname
+ format: email
responses:
- '201':
+ '204':
description: successful operation
- /server/followers:
- get:
+ '404':
+ description: follower not found
+
+ '/server/followers/{nameWithHost}/reject':
+ post:
+ summary: Reject a pending follower to your server
+ security:
+ - OAuth2:
+ - admin
tags:
- Instance Follows
- summary: List instance followers
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - name: nameWithHost
+ in: path
+ required: true
+ description: The remote actor handle to remove from your followers
+ schema:
+ type: string
+ format: email
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/Follow'
+ '404':
+ description: follower not found
+
+ '/server/followers/{nameWithHost}/accept':
+ post:
+ summary: Accept a pending follower to your server
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Instance Follows
+ parameters:
+ - name: nameWithHost
+ in: path
+ required: true
+ description: The remote actor handle to remove from your followers
+ schema:
+ type: string
+ format: email
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: follower not found
+
/server/following:
get:
tags:
- Instance Follows
summary: List instances followed by the server
parameters:
- - name: state
- in: query
- schema:
- type: string
- enum:
- - pending
- - accepted
- - name: actorType
- in: query
- schema:
- type: string
- enum:
- - Person
- - Application
- - Group
- - Service
- - Organization
+ - $ref: '#/components/parameters/followState'
+ - $ref: '#/components/parameters/actorType'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/Follow'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
post:
security:
- OAuth2:
- admin
tags:
- Instance Follows
- summary: Follow a server
+ summary: Follow a list of servers
responses:
'204':
description: successful operation
type: string
format: hostname
uniqueItems: true
+
+ '/server/following/{host}':
+ delete:
+ summary: Unfollow a server
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Instance Follows
+ parameters:
+ - name: host
+ in: path
+ required: true
+ description: The host to unfollow
+ schema:
+ type: string
+ format: hostname
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: host not found
+
/users:
post:
summary: Create a user
- operationId: createUser
+ operationId: addUser
security:
- OAuth2:
- admin
$ref: '#/components/schemas/AddUserResponse'
links:
# GET /users/{id}
- GetUserId:
- operationId: getUserId
+ GetUser:
+ operationId: getUser
parameters:
id: '$response.body#/user/id'
# PUT /users/{id}
- PutUserId:
- operationId: putUserId
+ PutUser:
+ operationId: putUser
parameters:
id: '$response.body#/user/id'
# DELETE /users/{id}
- DelUserId:
- operationId: delUserId
+ DelUser:
+ operationId: delUser
parameters:
id: '$response.body#/user/id'
'403':
required: true
get:
summary: List users
+ operationId: getUsers
security:
- OAuth2:
- admin
type: array
items:
$ref: '#/components/schemas/User'
+
'/users/{id}':
parameters:
- $ref: '#/components/parameters/id'
- admin
tags:
- Users
- operationId: delUserId
+ operationId: delUser
responses:
'204':
description: successful operation
- OAuth2: []
tags:
- Users
- operationId: getUserId
+ operationId: getUser
parameters:
- name: withStats
in: query
- OAuth2: []
tags:
- Users
- operationId: putUserId
+ operationId: putUser
responses:
'204':
description: successful operation
/oauth-clients/local:
get:
summary: Login prerequisite
- description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken).
+ description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
operationId: getOAuthClient
tags:
- Session
parameters:
client_id: '$response.body#/client_id'
client_secret: '$response.body#/client_secret'
+ x-codeSamples:
+ - lang: Shell
+ source: |
+ API="https://peertube2.cpy.re/api/v1"
+
+ ## AUTH
+ curl -s "$API/oauth-clients/local"
+
/users/token:
post:
summary: Login
type: integer
minimum: 0
example: 1209600
+ '400':
+ x-summary: client or credentials are invalid
+ description: |
+ Disambiguate via `type`:
+ - `invalid_client` for an unmatched `client_id`
+ - `invalid_grant` for unmatched credentials
+ '401':
+ x-summary: token expired
+ description: |
+ Disambiguate via `type`:
+ - default value for a regular authentication failure
+ - `invalid_token` for an expired token
+ x-codeSamples:
+ - lang: Shell
+ source: |
+ ## DEPENDENCIES: jq
+ API="https://peertube2.cpy.re/api/v1"
+ USERNAME="<your_username>"
+ PASSWORD="<your_password>"
+
+ ## AUTH
+ client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+ client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+ curl -s "$API/users/token" \
+ --data client_id="$client_id" \
+ --data client_secret="$client_secret" \
+ --data grant_type=password \
+ --data username="$USERNAME" \
+ --data password="$PASSWORD" \
+ | jq -r ".access_token"
+
/users/revoke-token:
post:
summary: Logout
/users/register:
post:
summary: Register a user
+ operationId: registerUser
tags:
- Users
- Register
schema:
$ref: '#/components/schemas/RegisterUser'
required: true
+
/users/{id}/verify-email:
post:
summary: Verify a user
+ operationId: verifyUser
description: |
Following a user registration, the new user will receive an email asking to click a link
- containing a secret.
+ containing a secret.
tags:
- Users
- Register
description: invalid verification string
'404':
description: user not found
+
/users/ask-send-verify-email:
post:
summary: Resend user verification link
+ operationId: resendEmailToVerifyUser
tags:
- Users
- Register
/users/me:
get:
summary: Get my user information
+ operationId: getUserInfo
security:
- OAuth2:
- user
$ref: '#/components/schemas/User'
put:
summary: Update my user information
+ operationId: putUserInfo
security:
- OAuth2:
- user
schema:
$ref: '#/components/schemas/UpdateMe'
required: true
+
/users/me/videos/imports:
get:
summary: Get video imports of my user
application/json:
schema:
$ref: '#/components/schemas/VideoImportsList'
+
/users/me/video-quota-used:
get:
summary: Get my user used quota
type: number
description: The user video quota used today in bytes
example: 1681014151
+
'/users/me/videos/{videoId}/rating':
get:
summary: Get rate of my user for a video
application/json:
schema:
$ref: '#/components/schemas/GetMeVideoRating'
+
/users/me/videos:
get:
summary: Get videos of my user
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
/users/me/subscriptions:
get:
summary: Get my user subscriptions
responses:
'200':
description: successful operation
+
/users/me/subscriptions/exist:
get:
summary: Get if subscriptions exist for my user
application/json:
schema:
type: object
+
/users/me/subscriptions/videos:
get:
summary: List videos of subscriptions of my user
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
'/users/me/subscriptions/{subscriptionHandle}':
get:
summary: Get subscription of my user
responses:
'200':
description: successful operation
+
/users/me/notifications:
get:
summary: List my notifications
application/json:
schema:
$ref: '#/components/schemas/NotificationListResponse'
+
/users/me/notifications/read:
post:
summary: Mark notifications as read by their id
responses:
'204':
description: successful operation
+
/users/me/notifications/read-all:
post:
summary: Mark all my notification as read
responses:
'204':
description: successful operation
+
/users/me/notification-settings:
put:
summary: Update my notification settings
responses:
'204':
description: successful operation
+
/users/me/history/videos:
get:
summary: List watched videos history
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
/users/me/history/videos/remove:
post:
summary: Clear video history
responses:
'204':
description: successful operation
+
/users/me/avatar/pick:
post:
summary: Update my user avatar
encoding:
avatarfile:
contentType: image/png, image/jpeg
+
/users/me/avatar:
delete:
summary: Delete my avatar
responses:
'200':
description: successful operation
+
'/videos/ownership/{id}/accept':
post:
summary: Accept ownership change request
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
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
description: changing video ownership to a remote account is not supported yet
'404':
description: video not found
+
/videos:
get:
summary: List videos
+ operationId: getVideos
tags:
- Video
parameters:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
/videos/categories:
get:
summary: List available video categories
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/categories
+
/videos/licences:
get:
summary: List available video licences
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/licences
+
/videos/languages:
get:
summary: List available video languages
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/languages
+
/videos/privacies:
get:
summary: List available video privacy policies
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
+
'/videos/{id}':
put:
summary: Update a video
+ operationId: putVideo
security:
- OAuth2: []
tags:
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
contentType: image/jpeg
get:
summary: Get a video
+ operationId: getVideo
tags:
- Video
parameters:
$ref: '#/components/schemas/VideoDetails'
delete:
summary: Delete a video
+ operationId: delVideo
security:
- OAuth2: []
tags:
responses:
'204':
description: successful operation
+
'/videos/{id}/description':
get:
summary: Get complete video description
+ operationId: getVideoDesc
tags:
- Video
parameters:
maxLength: 10000
example: |
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
+
'/videos/{id}/views':
post:
summary: Add a view to a video
+ operationId: addView
tags:
- Video
parameters:
responses:
'204':
description: successful operation
+
'/videos/{id}/watching':
put:
summary: Set watching progress of a video
+ operationId: setProgress
tags:
- Video
security:
responses:
'204':
description: successful operation
+
/videos/upload:
post:
summary: Upload a video
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
- '400':
- description: invalid file field, schedule date or parameter
'403':
description: video didn't pass upload filter
'408':
description: upload has timed out
'413':
- description: video file too large, due to quota or max body size limit set by the reverse-proxy
+ x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
+ description: |
+ If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
+ - `quota_reached` for quota limits wether daily or global
headers:
X-File-Maximum-Size:
schema:
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_name>"
+ API="https://peertube2.cpy.re/api/v1"
- API_PATH="https://peertube2.cpy.re/api/v1"
## AUTH
- client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
- client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
- token=$(curl -s "$API_PATH/users/token" \
+ client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+ client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+ token=$(curl -s "$API/users/token" \
--data client_id="$client_id" \
--data client_secret="$client_secret" \
--data grant_type=password \
- --data response_type=code \
--data username="$USERNAME" \
--data password="$PASSWORD" \
| jq -r ".access_token")
+
## VIDEO UPLOAD
- curl -s "$API_PATH/videos/upload" \
+ curl -s "$API/videos/upload" \
-H "Authorization: Bearer $token" \
--max-time 600 \
--form videofile=@"$FILE_PATH" \
--form channelId=$CHANNEL_ID \
--form name="$NAME"
+
/videos/upload-resumable:
post:
summary: Initialize the resumable upload of a video
schema:
type: number
example: 0
- '400':
- description: invalid file field, schedule date or parameter
'413':
- description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+ x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+ description: |
+ Disambiguate via `type`:
+ - `max_file_size_reached` for the absolute file size limit
+ - `quota_reached` for quota limits whether daily or global
'415':
description: video type unsupported
put:
- Video Upload
parameters:
- name: upload_id
- in: path
+ in: query
required: true
description: |
Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
example: 0
'403':
description: video didn't pass upload filter
- '413':
- description: video file too large, due to quota or max body size limit set by the reverse-proxy
+ '404':
+ description: upload not found
+ '409':
+ description: chunk doesn't match range
'422':
description: video unreadable
+ '429':
+ description: too many concurrent requests
delete:
summary: Cancel the resumable upload of a video, deleting any data uploaded so far
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
- Video Upload
parameters:
- name: upload_id
- in: path
+ in: query
required: true
description: |
Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
schema:
type: number
example: 0
+ '404':
+ description: upload not found
+
/videos/imports:
post:
summary: Import a video
/videos/live:
post:
summary: Create a live
- operationId: createLive
+ operationId: addLive
security:
- OAuth2: []
tags:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
+ '400':
+ x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
+ description: |
+ Disambiguate via `type`:
+ - default type for a validation error
+ - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
'403':
- description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+ x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+ description: |
+ Disambiguate via `type`:
+ - `live_not_enabled` for a disabled live feature
+ - `live_not_allowing_replay` for a disabled replay feature
+ - `max_instance_lives_limit_reached` for the absolute concurrent live limit
+ - `max_user_lives_limit_reached` for the user concurrent live limit
requestBody:
content:
multipart/form-data:
description: Enable or disable comments for this live video/replay
type: boolean
downloadEnabled:
- description: Enable or disable downloading for the replay of this live
+ description: Enable or disable downloading for the replay of this live video
type: boolean
required:
- channelId
type: string
- name: videoIs
in: query
- description: only list blacklisted or deleted videos
+ description: only list deleted or blocklisted videos
schema:
type: string
enum:
type: array
items:
$ref: '#/components/schemas/Abuse'
-
post:
summary: Report an abuse
security:
required:
- reason
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ abuse:
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
'400':
description: incorrect request parameters
+
'/abuses/{abuseId}':
put:
summary: Update an abuse
description: successful operation
'404':
description: block not found
+
'/abuses/{abuseId}/messages':
get:
summary: List messages of an abuse
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/AbuseMessage'
-
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/AbuseMessage'
post:
summary: Add message to an abuse
security:
description: successful operation
'400':
description: incorrect request parameters
+
'/abuses/{abuseId}/messages/{abuseMessageId}':
delete:
summary: Delete an abuse message
'/videos/{id}/blacklist':
post:
summary: Block a video
+ operationId: addVideoBlock
security:
- OAuth2:
- admin
description: successful operation
delete:
summary: Unblock a video by its id
+ operationId: delVideoBlock
security:
- OAuth2:
- admin
description: successful operation
'404':
description: block not found
+
/videos/blacklist:
get:
tags:
- Video Blocks
summary: List video blocks
+ operationId: getVideoBlocks
security:
- OAuth2:
- admin
type: array
items:
$ref: '#/components/schemas/VideoBlacklist'
+
/videos/{id}/captions:
get:
summary: List captions of a video
+ operationId: getVideoCaptions
tags:
- Video Captions
parameters:
type: array
items:
$ref: '#/components/schemas/VideoCaption'
+
/videos/{id}/captions/{captionLanguage}:
put:
summary: Add or replace a video caption
+ operationId: addVideoCaption
security:
- OAuth2:
- user
description: video or language not found
delete:
summary: Delete a video caption
+ operationId: delVideoCaption
security:
- OAuth2:
- user
description: successful operation
'404':
description: video or language or caption for that language not found
+
/video-channels:
get:
summary: List video channels
$ref: '#/components/schemas/VideoChannelList'
post:
summary: Create a video channel
- operationId: createVideoChannel
+ operationId: addVideoChannel
security:
- OAuth2: []
tags:
application/json:
schema:
$ref: '#/components/schemas/VideoChannelCreate'
+
'/video-channels/{channelHandle}':
get:
summary: Get a video channel
$ref: '#/components/schemas/VideoChannel'
put:
summary: Update a video channel
+ operationId: putVideoChannel
security:
- OAuth2: []
tags:
$ref: '#/components/schemas/VideoChannelUpdate'
delete:
summary: Delete a video channel
+ operationId: delVideoChannel
security:
- OAuth2: []
tags:
responses:
'204':
description: successful operation
+
'/video-channels/{channelHandle}/videos':
get:
summary: List videos of a video channel
+ operationId: getVideoChannelVideos
tags:
- Video
- Video Channels
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
'/video-channels/{channelHandle}/avatar/pick':
post:
summary: Update channel avatar
encoding:
avatarfile:
contentType: image/png, image/jpeg
+
'/video-channels/{channelHandle}/avatar':
delete:
summary: Delete channel avatar
'204':
description: successful operation
-
'/video-channels/{channelHandle}/banner/pick':
post:
summary: Update channel banner
encoding:
bannerfile:
contentType: image/png, image/jpeg
+
'/video-channels/{channelHandle}/banner':
delete:
summary: Delete channel banner
post:
summary: Create a video playlist
description: If the video playlist is set as public, `videoChannelId` is mandatory.
- operationId: createPlaylist
+ operationId: addPlaylist
security:
- OAuth2: []
tags:
/video-playlists/{playlistId}/videos:
get:
summary: 'List videos of a playlist'
+ operationId: getVideoPlaylistVideos
tags:
- Videos
- Video Playlists
$ref: '#/components/schemas/VideoListResponse'
post:
summary: Add a video in a playlist
+ operationId: addVideoPlaylistVideo
security:
- OAuth2: []
tags:
/video-playlists/{playlistId}/videos/reorder:
post:
summary: 'Reorder a playlist'
+ operationId: reorderVideoPlaylist
security:
- OAuth2: []
tags:
/video-playlists/{playlistId}/videos/{playlistElementId}:
put:
summary: Update a playlist element
+ operationId: putVideoPlaylistVideo
security:
- OAuth2: []
tags:
description: Stop the video at this specific timestamp
delete:
summary: Delete an element from a playlist
+ operationId: delVideoPlaylistVideo
security:
- OAuth2: []
tags:
application/json:
schema:
$ref: '#/components/schemas/VideoChannelList'
+
'/accounts/{name}/ratings':
get:
summary: List ratings of an account
type: array
items:
$ref: '#/components/schemas/VideoRating'
+
'/videos/{id}/comment-threads':
get:
summary: List threads of a video
application/json:
schema:
$ref: '#/components/schemas/VideoCommentThreadTree'
+
'/videos/{id}/comments/{commentId}':
post:
summary: Reply to a thread of a video
maxLength: 10000
required:
- text
-
delete:
summary: Delete a comment or a reply
security:
description: comment or video does not exist
'409':
description: comment is already deleted
+
'/videos/{id}/rate':
put:
summary: Like/dislike a video
description: successful operation
'404':
description: video does not exist
+
/search/videos:
get:
tags:
- Search
summary: Search videos
+ operationId: searchVideos
parameters:
- name: search
in: query
$ref: '#/components/schemas/VideoListResponse'
'500':
description: search index unavailable
+
/search/video-channels:
get:
tags:
- Search
summary: Search channels
+ operationId: searchChannels
parameters:
- name: search
in: query
$ref: '#/components/schemas/VideoChannelList'
'500':
description: search index unavailable
- /blocklist/accounts:
+
+ /search/video-playlists:
+ get:
+ tags:
+ - Search
+ summary: Search playlists
+ operationId: searchPlaylists
+ parameters:
+ - name: search
+ in: query
+ required: true
+ description: >
+ String to search. If the user can make a remote URI search, and the string is an URI then the
+ PeerTube instance will fetch the remote object and add it to its database. Then,
+ you can use the REST API to fetch the complete playlist information and interact with it.
+ schema:
+ type: string
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/searchTarget'
+ - $ref: '#/components/parameters/sort'
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
+ '500':
+ description: search index unavailable
+
+ /server/blocklist/accounts:
get:
tags:
- Account Blocks
description: successful operation
'409':
description: self-blocking forbidden
- '/blocklist/accounts/{accountName}':
+
+ '/server/blocklist/accounts/{accountName}':
delete:
tags:
- Account Blocks
description: successful operation
'404':
description: account or account block does not exist
- /blocklist/servers:
+
+ /server/blocklist/servers:
get:
tags:
- Server Blocks
required:
- host
responses:
- '200':
+ '204':
description: successful operation
'409':
description: self-blocking forbidden
- '/blocklist/servers/{host}':
+
+ '/server/blocklist/servers/{host}':
delete:
tags:
- Server Blocks
type: string
format: hostname
responses:
- '201':
+ '204':
description: successful operation
'404':
description: account block does not exist
- /redundancy/{host}:
+
+ /server/redundancy/{host}:
put:
tags:
- Instance Redundancy
description: successful operation
'404':
description: server is not already known
- /redundancy/videos:
+
+ /server/redundancy/videos:
get:
tags:
- Video Mirroring
summary: List videos being mirrored
+ operationId: getMirroredVideos
security:
- OAuth2:
- admin
tags:
- Video Mirroring
summary: Mirror a video
+ operationId: putMirroredVideo
security:
- OAuth2:
- admin
description: video does not exist
'409':
description: video is already mirrored
- /redundancy/videos/{redundancyId}:
+
+ /server/redundancy/videos/{redundancyId}:
delete:
tags:
- Video Mirroring
summary: Delete a mirror done on a video
+ operationId: delMirroredVideo
security:
- OAuth2:
- admin
description: successful operation
'404':
description: video redundancy not found
+
'/feeds/video-comments.{format}':
get:
tags:
- Feeds
summary: List comments on videos
+ operationId: getSyndicatedComments
parameters:
- name: format
in: path
description: video, video channel or account not found
'406':
description: accept header unsupported
+
'/feeds/videos.{format}':
get:
tags:
- Feeds
summary: List videos
+ operationId: getSyndicatedVideos
parameters:
- name: format
in: path
description: video channel or account not found
'406':
description: accept header unsupported
+
'/feeds/subscriptions.{format}':
get:
tags:
- Feeds
- Account
summary: List videos of subscriptions tied to a token
+ operationId: getSyndicatedSubscriptionVideos
parameters:
- name: format
in: path
type: object
'406':
description: accept header unsupported
+
/plugins:
get:
tags:
- Plugins
summary: List plugins
+ operationId: getPlugins
security:
- OAuth2:
- admin
application/json:
schema:
$ref: '#/components/schemas/PluginResponse'
+
/plugins/available:
get:
tags:
- Plugins
summary: List available plugins
+ operationId: getAvailablePlugins
security:
- OAuth2:
- admin
$ref: '#/components/schemas/PluginResponse'
'503':
description: plugin index unavailable
+
/plugins/install:
post:
tags:
- Plugins
summary: Install a plugin
+ operationId: addPlugin
security:
- OAuth2:
- admin
description: successful operation
'400':
description: should have either `npmName` or `path` set
+
/plugins/update:
post:
tags:
- Plugins
summary: Update a plugin
+ operationId: updatePlugin
security:
- OAuth2:
- admin
description: should have either `npmName` or `path` set
'404':
description: existing plugin not found
+
/plugins/uninstall:
post:
tags:
- Plugins
summary: Uninstall a plugin
+ operationId: uninstallPlugin
security:
- OAuth2:
- admin
description: successful operation
'404':
description: existing plugin not found
+
/plugins/{npmName}:
get:
tags:
- Plugins
summary: Get a plugin
+ operationId: getPlugin
security:
- OAuth2:
- admin
$ref: '#/components/schemas/Plugin'
'404':
description: plugin not found
+
/plugins/{npmName}/settings:
put:
tags:
description: successful operation
'404':
description: plugin not found
+
/plugins/{npmName}/public-settings:
get:
tags:
additionalProperties: true
'404':
description: plugin not found
+
/plugins/{npmName}/registered-settings:
get:
tags:
additionalProperties: true
'404':
description: plugin not found
+
servers:
- url: 'https://peertube2.cpy.re/api/v1'
description: Live Test Server (live data - latest nightly version)
name: sort
in: query
required: false
- description: Sort blacklists by criteria
+ description: Sort blocklists by criteria
schema:
type: string
enum:
required: true
description: The thread id (root comment id)
schema:
- $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
+ type: integer
commentId:
name: commentId
in: path
- activitypub-refresher
- video-redundancy
- video-live-ending
+ followState:
+ name: state
+ in: query
+ schema:
+ type: string
+ enum:
+ - pending
+ - accepted
+ actorType:
+ name: actorType
+ in: query
+ schema:
+ type: string
+ enum:
+ - Person
+ - Application
+ - Group
+ - Service
+ - Organization
securitySchemes:
OAuth2:
description: |
enum:
- 0
- 1
- description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
+ description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
example: 1
VideoStateConstant:
indexUrl:
type: string
format: url
+ homepage:
+ type: object
+ properties:
+ enabled:
+ type: boolean
+
ServerConfigAbout:
properties:
instance:
type: boolean
manualApproval:
type: boolean
+
+ CustomHomepage:
+ properties:
+ content:
+ type: string
+
Follow:
properties:
id:
# optionally present fields: they require WITH_STATS scope
videosCount:
type: integer
- description: Count of videos published
+ description: Count of videos published
abusesCount:
type: integer
description: Count of reports/abuses of which the user is a target
projects / github / Chocobozzz / PeerTube.git / blobdiff