openapi: 3.0.0
info:
title: PeerTube
version: 2.2.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 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: Video Abuses
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_ 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
- name: Videos
tags:
- Video
- Video Captions
- Video Channels
- Video Comments
- Video Rates
- Video Playlists
- Video Ownership Change
- Video Mirroring
- Feeds
- name: Search
tags:
- Search
- name: Moderation
tags:
- Video 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/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: |
# pip install httpie
http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
- 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
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: 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: []
tags:
- Users
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}':
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/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'
videoAbuseAsModerator:
$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/avatar/pick:
post:
summary: Update my user avatar
security:
- OAuth2: []
tags:
- My 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:
avatarfile:
contentType: image/png, image/jpeg
/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/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 <insert crowdfunding plateform>! <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: boolean
name:
description: Video name
type: string
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'
'403':
description: user video quota is exceeded with this video
'408':
description: upload has timed out
'422':
description: invalid input file
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: string
language:
description: Video language
type: integer
example: 2
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 <insert crowdfunding plateform>! <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: boolean
name:
description: Video name
type: string
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
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: httpie, jq
# pip install httpie
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_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 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: 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: A text tell the audience how to support the video creator
example: Please support my work on <insert crowdfunding plateform>! <3
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
minItems: 1
maxItems: 5
items:
type: string
minLength: 2
maxLength: 30
commentsEnabled:
description: Enable or disable comments for this video
type: string
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'
'409':
description: HTTP or Torrent/magnetURI import not enabled
'400':
description: '`magnetUri` or `targetUrl` or a torrent file missing'
/videos/abuse:
get:
deprecated: true
summary: List video abuses
security:
- OAuth2:
- admin
- moderator
tags:
- Video 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:
type: string
enum:
- violentOrAbusive
- hatefulOrAbusive
- spamOrMisleading
- privacy
- rights
- serverRules
- thumbnails
- captions
- name: search
in: query
description: plain search that will match with video titles, reporter names and more
schema:
type: string
- name: state
in: query
description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
schema:
type: integer
enum:
- 1
- 2
- 3
- 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
- $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:
deprecated: true
summary: Report an abuse
security:
- OAuth2: []
tags:
- Video Abuses
- Videos
parameters:
- $ref: '#/components/parameters/idOrUUID'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
description: Reason why the user reports this video
type: string
minLength: 4
predefinedReasons:
description: Reason categories that help triage reports
type: array
items:
type: string
enum:
- violentOrAbusive
- hatefulOrAbusive
- spamOrMisleading
- privacy
- rights
- serverRules
- thumbnails
- captions
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
required:
- reason
responses:
'204':
description: successful operation
'400':
description: incorrect request parameters
'/videos/{id}/abuse/{abuseId}':
put:
deprecated: true
summary: Update an abuse
security:
- OAuth2:
- admin
- moderator
tags:
- Video Abuses
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/abuseId'
requestBody:
content:
application/json:
schema:
type: object
properties:
state:
$ref: '#/components/schemas/VideoAbuseStateSet'
moderationComment:
type: string
description: Update the report comment visible only to the moderation team
responses:
'204':
description: successful operation
'404':
description: video abuse not found
delete:
deprecated: true
tags:
- Video Abuses
summary: Delete an abuse
security:
- OAuth2:
- admin
- moderator
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/abuseId'
responses:
'204':
description: successful operation
'404':
description: block not found
'/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
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
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/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-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:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
displayName:
description: Video playlist display name
type: string
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
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:
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/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
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
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
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 name 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
- type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
playlistElementId:
name: playlistElementId
in: path
required: true
description: Playlist element id
schema:
type: integer
abuseId:
name: abuseId
in: path
required: true
description: Video abuse 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
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 (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
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
securitySchemes:
OAuth2:
description: >
In the header: *Authorization: Bearer <token\>*
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:
VideoConstantNumber:
properties:
id:
type: integer
label:
type: string
VideoConstantString:
properties:
id:
type: string
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
VideoStateConstant:
properties:
id:
type: integer
enum:
- 1
- 2
- 3
description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
label:
type: string
VideoAbuseStateSet:
type: integer
enum:
- 1
- 2
- 3
description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
VideoAbuseStateConstant:
properties:
id:
$ref: '#/components/schemas/VideoAbuseStateSet'
label:
type: string
VideoAbusePredefinedReasons:
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 ...)'
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/Avatar'
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/Avatar'
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
format: url
torrentDownloadUrl:
type: string
format: url
fileUrl:
type: string
format: url
fileDownloadUrl:
type: string
format: url
fps:
type: number
metadataUrl:
type: string
format: url
VideoStreamingPlaylists:
properties:
id:
type: integer
type:
type: integer
enum:
- 1
description: 'Playlist type (HLS = `1`)'
playlistUrl:
type: string
format: url
segmentsSha256Url:
type: string
format: url
files:
type: array
items:
$ref: '#/components/schemas/VideoFile'
redundancies:
type: array
items:
type: object
properties:
baseUrl:
type: string
format: url
VideoInfo:
properties:
id:
type: integer
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
name:
type: string
Video:
properties:
id:
type: integer
example: 8
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
createdAt:
type: string
format: date-time
publishedAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
originallyPublishedAt:
type: string
format: date-time
category:
$ref: '#/components/schemas/VideoConstantNumber'
licence:
$ref: '#/components/schemas/VideoConstantNumber'
language:
$ref: '#/components/schemas/VideoConstantString'
privacy:
$ref: '#/components/schemas/VideoPrivacyConstant'
description:
type: string
duration:
type: integer
example: 1419
isLocal:
type: boolean
name:
type: string
example: What is PeerTube?
thumbnailPath:
type: string
example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
previewPath:
type: string
example: /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
support:
type: string
description: A text tell the audience how to support the video creator
example: Please support my work on <insert crowdfunding plateform>! <3
channel:
$ref: '#/components/schemas/VideoChannel'
account:
$ref: '#/components/schemas/Account'
tags:
type: array
items:
type: string
example: [flowers, gardening]
files:
type: array
items:
$ref: '#/components/schemas/VideoFile'
commentsEnabled:
type: boolean
downloadEnabled:
type: boolean
trackerUrls:
type: array
items:
type: string
format: url
streamingPlaylists:
type: array
items:
$ref: '#/components/schemas/VideoStreamingPlaylists'
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:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
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'
VideoAbuse:
properties:
id:
type: integer
example: 7
reason:
type: string
example: The video is a spam
predefinedReasons:
$ref: '#/components/schemas/VideoAbusePredefinedReasons'
reporterAccount:
$ref: '#/components/schemas/Account'
state:
$ref: '#/components/schemas/VideoAbuseStateConstant'
moderationComment:
type: string
example: Decided to ban the server since it spams us regularly
video:
type: object
properties:
id:
type: integer
name:
type: string
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
createdAt:
type: string
format: date-time
VideoBlacklist:
properties:
id:
type: integer
videoId:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
description:
type: string
duration:
type: integer
views:
type: integer
likes:
type: integer
dislikes:
type: integer
nsfw:
type: boolean
VideoChannel:
properties:
displayName:
type: string
description:
type: string
isLocal:
type: boolean
ownerAccount:
type: object
properties:
id:
type: integer
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
VideoPlaylist:
properties:
id:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
description:
type: string
uuid:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
displayName:
type: string
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
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'
captionPath:
type: string
Avatar:
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/Avatar'
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
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
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:
type: string
format: uuid
example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
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
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
videoAbusesCount:
type: integer
videoAbusesAcceptedCount:
type: integer
videoAbusesCreatedCount:
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
role:
$ref: '#/components/schemas/UserRole'
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
videoQuota:
type: integer
description: The updated video quota of the user
videoQuotaDaily:
type: integer
description: The updated daily video quota of the user
role:
$ref: '#/components/schemas/UserRole'
required:
- id
- email
- videoQuota
- videoQuotaDaily
- role
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 name 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
VideoChannelCreate:
properties:
name:
type: string
displayName:
type: string
description:
type: string
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 <insert crowdfunding plateform>! <3
required:
- name
- displayName
VideoChannelUpdate:
properties:
displayName:
type: string
description:
type: string
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 <insert crowdfunding plateform>! <3
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_VIDEO_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'
callbacks:
searchIndex:
'{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/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'