openapi: 3.0.0
info:
title: PeerTube
- version: 2.1.0
+ version: 2.2.0-rc.1
contact:
name: PeerTube Community
url: 'https://joinpeertube.org'
altText: PeerTube Project Homepage
description: |
# Introduction
- The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
- resource URLs. It returns HTTP response codes to indicate errors. It also
- accepts and returns JSON in the HTTP body. You can use your favorite
+
+ 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. No official
SDK is currently provided, but the spec API is fully compatible with
[openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
which generates a client SDK in the language of your choice.
+ 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.
# 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.
description: >
Jobs are long-running tasks enqueued and processed by the instance
itself. No additional worker registration is currently available.
- - name: Server Following
+ - 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.
- - name: Video Abuse
+ - name: Video Abuses
description: |
Video abuses deal with reports of local or remote videos alike.
- name: Video
Videos from other instances federated by the instance (that is, instances
followed by the instance) can be found via keywords and other criteria of
the advanced search.
- - name: Video Comment
+ - name: Video Comments
description: >
Operations dealing with comments to a video. Comments are organized in
threads.
- - name: Video Playlist
+ - name: Video Playlists
description: >
Operations dealing with playlists of videos. Playlists are bound to users
and/or channels.
- - name: Video Channel
+ - name: Video Channels
description: >
Operations dealing with creation, modification and video listing of a
user's channels.
description: >
Operations dealing with blacklisting videos (removing them from view and
preventing interactions).
- - name: Video Rate
+ - name: Video Rates
description: >
- Voting for a video.
+ Like/dislike a video.
x-tagGroups:
- name: Accounts
tags:
- Accounts
- - User
+ - Users
- My User
+ - My Subscriptions
- name: Videos
tags:
- Video
- Video Caption
- - Video Channel
- - Video Comment
+ - Video Channels
+ - Video Comments
- Video Following
- - Video Rate
+ - Video Rates
+ - Video Playlists
+ - Video Ownership Change
+ - name: Search
+ tags:
+ - Search
- name: Moderation
tags:
- - Video Abuse
+ - Video Abuses
- Video Blacklist
- name: Instance Configuration
tags:
- Config
- - Server Following
+ - Instance Follows
- name: Jobs
tags:
- Job
- - name: Search
- tags:
- - Search
paths:
'/accounts/{name}':
get:
tags:
- Accounts
- summary: Get the account by name
+ summary: Get an account
parameters:
- $ref: '#/components/parameters/name'
responses:
tags:
- Accounts
- Video
- summary: 'Get videos for an account, provided the name of that account'
+ 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
get:
tags:
- Accounts
- summary: Get all accounts
+ summary: List accounts
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
get:
tags:
- Config
- summary: Get the public configuration of the server
+ summary: Get instance public configuration
responses:
'200':
description: successful operation
$ref: '#/components/schemas/ServerConfig'
/config/about:
get:
- summary: Get the instance about page content
+ summary: Get instance "About" information
tags:
- Config
responses:
$ref: '#/components/schemas/ServerConfigAbout'
/config/custom:
get:
- summary: Get the runtime configuration of the server
+ summary: Get instance runtime configuration
tags:
- Config
security:
schema:
$ref: '#/components/schemas/ServerConfigCustom'
put:
- summary: Set the runtime configuration of the server
+ summary: Set instance runtime configuration
tags:
- Config
security:
'200':
description: successful operation
delete:
- summary: Delete the runtime configuration of the server
+ summary: Delete instance runtime configuration
tags:
- Config
security:
description: successful operation
/jobs/{state}:
get:
- summary: Get list of jobs
+ summary: List instance jobs
security:
- OAuth2:
- admin
- OAuth2:
- admin
tags:
- - Server Following
- summary: Unfollow a server by hostname
+ - Instance Follows
+ summary: Unfollow a server
parameters:
- name: host
in: path
/server/followers:
get:
tags:
- - Server Following
- summary: Get followers of the server
+ - Instance Follows
+ summary: List instance followers
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
/server/following:
get:
tags:
- - Server Following
- summary: Get servers followed by the server
+ - Instance Follows
+ summary: List instance followings
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- OAuth2:
- admin
tags:
- - Server Following
+ - Instance Follows
summary: Follow a server
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
requestBody:
content:
application/json:
$ref: '#/components/schemas/Follow'
/users:
post:
- summary: Creates user
+ summary: Create a user
security:
- OAuth2:
- admin
tags:
- - User
+ - Users
responses:
'200':
description: successful operation
description: User to create
required: true
get:
- summary: Get a list of users
+ summary: List users
security:
- OAuth2: []
tags:
- - User
+ - Users
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
$ref: '#/components/schemas/User'
'/users/{id}':
delete:
- summary: Delete a user by its id
+ summary: Delete a user
security:
- OAuth2:
- admin
tags:
- - User
+ - Users
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
get:
- summary: Get user by its id
+ summary: Get a user
security:
- OAuth2: []
tags:
- - User
+ - Users
parameters:
- $ref: '#/components/parameters/id'
responses:
schema:
$ref: '#/components/schemas/User'
put:
- summary: Update user profile by its id
+ summary: Update a user
security:
- OAuth2: []
tags:
- - User
+ - Users
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
requestBody:
content:
application/json:
post:
summary: Register a user
tags:
- - User
+ - Users
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
requestBody:
content:
application/json:
required: true
/users/me:
get:
- summary: Get current user information
+ summary: Get my user information
security:
- OAuth2:
- user
items:
$ref: '#/components/schemas/User'
put:
- summary: Update current user information
+ summary: Update my user information
security:
- OAuth2:
- user
required: true
/users/me/videos/imports:
get:
- summary: Get video imports of current user
+ summary: Get video imports of my user
security:
- OAuth2:
- user
tags:
+ - Videos
- My User
parameters:
- $ref: '#/components/parameters/start'
$ref: '#/components/schemas/VideoImport'
/users/me/video-quota-used:
get:
- summary: Get current user used quota
+ summary: Get my user used quota
security:
- OAuth2:
- user
type: number
'/users/me/videos/{videoId}/rating':
get:
- summary: 'Get rating of video by its id, among those of the current user'
+ summary: Get rate of my user for a video
security:
- OAuth2: []
tags:
- My User
+ - Video Rates
parameters:
- name: videoId
in: path
$ref: '#/components/schemas/GetMeVideoRating'
/users/me/videos:
get:
- summary: Get videos of the current user
+ summary: Get videos of my user
security:
- OAuth2:
- user
tags:
- My User
+ - Videos
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
$ref: '#/components/schemas/VideoListResponse'
/users/me/subscriptions:
get:
- summary: Get subscriptions of the current user
+ summary: Get my user subscriptions
security:
- OAuth2:
- user
tags:
- - My User
+ - My Subscriptions
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
'200':
description: successful operation
post:
- summary: Add subscription to the current user
+ summary: Add subscription to my user
security:
- OAuth2:
- user
tags:
- - My User
+ - My Subscriptions
responses:
'200':
description: successful operation
/users/me/subscriptions/exist:
get:
- summary: Get if subscriptions exist for the current user
+ summary: Get if subscriptions exist for my user
security:
- OAuth2:
- user
tags:
- - My User
+ - My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionsUris'
responses:
type: object
/users/me/subscriptions/videos:
get:
- summary: Get videos of subscriptions of the current user
+ summary: List videos of subscriptions of my user
security:
- OAuth2:
- user
tags:
- - My User
+ - 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/sort'
+ - $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
$ref: '#/components/schemas/VideoListResponse'
'/users/me/subscriptions/{subscriptionHandle}':
get:
- summary: Get subscription of the current user for a given uri
+ summary: Get subscription of my user
security:
- OAuth2:
- user
tags:
- - My User
+ - My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionHandle'
responses:
schema:
$ref: '#/components/schemas/VideoChannel'
delete:
- summary: Delete subscription of the current user for a given uri
+ summary: Delete subscription of my user
security:
- OAuth2:
- user
tags:
- - My User
+ - My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionHandle'
responses:
description: successful operation
/users/me/avatar/pick:
post:
- summary: Update current user avatar
+ summary: Update my user avatar
security:
- OAuth2: []
tags:
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
+ '/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
+ '/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'
/videos:
get:
- summary: Get list of videos
+ summary: List videos
tags:
- Video
parameters:
- $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'
$ref: '#/components/schemas/VideoListResponse'
/videos/categories:
get:
- summary: Get list of video categories known by the server
+ summary: List available video categories
tags:
- Video
responses:
type: string
/videos/licences:
get:
- summary: Get list of video licences known by the server
+ summary: List available video licences
tags:
- Video
responses:
type: string
/videos/languages:
get:
- summary: Get list of languages known by the server
+ summary: List available video languages
tags:
- Video
responses:
type: string
/videos/privacies:
get:
- summary: Get list of privacy policies supported by the server
+ summary: List available video privacies
tags:
- Video
responses:
type: string
'/videos/{id}':
put:
- summary: Update metadata for a video by its id
+ summary: Update a video
security:
- OAuth2: []
tags:
language:
description: Video language
type: string
+ privacy:
+ $ref: '#/components/schemas/VideoPrivacySet'
description:
description: Video description
type: string
previewfile:
contentType: image/jpeg
get:
- summary: Get a video by its id
+ summary: Get a video
tags:
- Video
parameters:
schema:
$ref: '#/components/schemas/VideoDetails'
delete:
- summary: Delete a video by its id
+ summary: Delete a video
security:
- OAuth2: []
tags:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
'/videos/{id}/description':
get:
- summary: Get a video description by its id
+ summary: Get complete video description
tags:
- Video
parameters:
type: string
'/videos/{id}/views':
post:
- summary: Add a view to the video by its id
+ summary: Add a view to a video
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
'/videos/{id}/watching':
put:
- summary: Set watching progress of a video by its id for a user
+ summary: Set watching progress of a video
tags:
- Video
security:
required: true
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- /videos/ownership:
- get:
- summary: Get list of video ownership changes requests
- tags:
- - Video
- security:
- - OAuth2: []
- responses:
- '200':
description: successful operation
- '/videos/ownership/{id}/accept':
- post:
- summary: Refuse ownership change request for video by its id
- tags:
- - Video
- security:
- - OAuth2: []
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- responses:
- '204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- '/videos/ownership/{id}/refuse':
- post:
- summary: Accept ownership change request for video by its id
- tags:
- - Video
- security:
- - OAuth2: []
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- responses:
- '204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- '/videos/{id}/give-ownership':
- post:
- summary: Request change of ownership for a video you own, by its id
- tags:
- - Video
- security:
- - OAuth2: []
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- requestBody:
- required: true
- content:
- application/x-www-form-urlencoded:
- schema:
- type: object
- properties:
- username:
- type: string
- required:
- - username
- responses:
- '204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- '400':
- description: 'Changing video ownership to a remote account is not supported yet'
/videos/upload:
post:
- summary: Upload a video file with its metadata
+ summary: Upload a video
security:
- OAuth2: []
tags:
"Authorization:Bearer $token"
/videos/imports:
post:
- summary: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
+ summary: Import a video
+ description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
security:
- OAuth2: []
tags:
contentType: image/jpeg
/videos/abuse:
get:
- summary: Get list of reported video abuses
+ summary: List video abuses
security:
- - OAuth2: []
+ - OAuth2:
+ - admin
+ - moderator
tags:
- - Video Abuse
+ - Video Abuses
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
$ref: '#/components/schemas/VideoAbuse'
'/videos/{id}/abuse':
post:
- summary: 'Report an abuse, on a video by its id'
+ summary: Report an abuse
security:
- OAuth2: []
tags:
- - Video Abuse
+ - Video Abuses
+ - Videos
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ reason:
+ description: Reason why the user reports this video
+ type: string
+ responses:
+ '204':
+ description: successful operation
+ '/videos/{id}/abuse/{abuseId}':
+ put:
+ summary: Update an abuse
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Video Abuses
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
+ 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 comment of the video abuse for other admin/moderators'
+ delete:
+ summary: Delete an abuse
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Video Abuses
+ responses:
+ '204':
+ description: successful operation
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/abuseId'
+
'/videos/{id}/blacklist':
post:
- summary: Put on blacklist a video by its id
+ summary: Blacklist a video
security:
- OAuth2:
- admin
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
delete:
summary: Delete an entry of the blacklist of a video by its id
security:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
/videos/blacklist:
get:
- summary: Get list of videos on blacklist
+ summary: List blacklisted videos
security:
- OAuth2:
- admin
$ref: '#/components/schemas/VideoBlacklist'
/videos/{id}/captions:
get:
- summary: Get list of video's captions
+ summary: List captions of a video
tags:
- Video Caption
parameters:
contentType: text/vtt, application/x-subrip, text/plain
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
delete:
summary: Delete a video caption
tags:
- - Video Caption
+ - Video Caption
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/captionLanguage'
+ responses:
+ '204':
+ description: successful operation
+ /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: 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
+
+ /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: 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: number
+ 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: number
+ required:
+ - displayName
+
+ /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: number
+ delete:
+ summary: Delete a video playlist
+ security:
+ - OAuth2: []
+ tags:
+ - Video Playlists
parameters:
- $ref: '#/components/parameters/idOrUUID'
- - $ref: '#/components/parameters/captionLanguage'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- /video-channels:
+ description: successful operation
+
+ /video-playlists/{id}/videos:
get:
- summary: Get list of video channels
+ summary: 'List videos of a playlist'
tags:
- - Video Channel
+ - Videos
+ - Video Playlists
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoChannel'
+ $ref: '#/components/schemas/VideoListResponse'
post:
- summary: Creates a video channel for the current user
+ summary: 'Add a video in a playlist'
security:
- OAuth2: []
tags:
- - Video Channel
+ - Videos
+ - Video Playlists
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
responses:
- '204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ videoPlaylistElement:
+ type: object
+ properties:
+ id:
+ type: number
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannelCreate'
- '/video-channels/{channelHandle}':
- get:
- summary: Get a video channel by its id
+ type: object
+ properties:
+ videoId:
+ type: number
+ description: 'Video to add in the playlist'
+ startTimestamp:
+ type: number
+ description: 'Start the video at this specific timestamp (in seconds)'
+ stopTimestamp:
+ type: number
+ 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 Channel
+ - Video Playlists
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoChannel'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ startPosition:
+ type: number
+ description: 'Start position of the element to reorder (starts from 1)'
+ insertAfterPosition:
+ type: number
+ description: 'New position for the block to reorder (starts from 0, to add the block before the first element)'
+ reorderLength:
+ type: number
+ description: 'How many element from startPosition to reorder (minimum length is 1)'
+ required:
+ - startPosition
+ - insertAfterPosition
+
+ /video-playlists/{id}/videos/{playlistElementId}:
put:
- summary: Update a video channel by its id
+ summary: 'Update a playlist element'
security:
- OAuth2: []
tags:
- - Video Channel
+ - Video Playlists
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistElementId'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannelUpdate'
+ type: object
+ properties:
+ startTimestamp:
+ type: number
+ description: 'Start the video at this specific timestamp (in seconds)'
+ stopTimestamp:
+ type: number
+ description: 'Stop the video at this specific timestamp (in seconds)'
delete:
- summary: Delete a video channel by its id
+ summary: 'Delete an element from a playlist'
security:
- OAuth2: []
tags:
- - Video Channel
+ - Video Playlists
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistElementId'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
- '/video-channels/{channelHandle}/videos':
- get:
- summary: Get videos of a video channel by its id
- tags:
- - Video
- - Video Channel
- parameters:
- - $ref: '#/components/parameters/channelHandle'
- responses:
- '200':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoListResponse'
- /video-playlists:
+
+ '/users/me/video-playlists/videos-exist':
get:
- summary: Get list of video playlists
+ summary: 'Check video exists in my playlists'
+ security:
+ - OAuth2: []
tags:
- - Video Playlist
+ - Video Playlists
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - name: videoIds
+ in: query
+ required: true
+ description: The video ids to check
+ schema:
+ type: array
+ items:
+ type: number
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoPlaylist'
+ type: object
+ properties:
+ videoId:
+ type: array
+ items:
+ type: object
+ properties:
+ playlistElementId:
+ type: number
+ playlistId:
+ type: number
+ startTimestamp:
+ type: number
+ stopTimestamp:
+ type: number
+
'/accounts/{name}/video-channels':
get:
- summary: Get video channels of an account by its name
+ summary: List video channels of an account
tags:
- - Video Channel
+ - Video Channels
+ - Accounts
parameters:
- $ref: '#/components/parameters/name'
responses:
$ref: '#/components/schemas/VideoChannel'
'/accounts/{name}/ratings':
get:
- summary: Get ratings of an account by its name
+ summary: List ratings of an account
security:
- OAuth2: []
tags:
- - User
+ - Accounts
parameters:
- $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/start'
$ref: '#/components/schemas/VideoRating'
'/videos/{id}/comment-threads':
get:
- summary: Get the comment threads of a video by its id
+ summary: List threads of a video
tags:
- - Video Comment
+ - Video Comments
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/start'
schema:
$ref: '#/components/schemas/CommentThreadResponse'
post:
- summary: 'Creates a comment thread, on a video by its id'
+ summary: Create a thread
security:
- OAuth2: []
tags:
- - Video Comment
+ - Video Comments
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ text:
+ type: string
+ description: 'Text comment'
+ required:
+ - text
+
'/videos/{id}/comment-threads/{threadId}':
get:
- summary: 'Get the comment thread by its id, of a video by its id'
+ summary: Get a thread
tags:
- - Video Comment
+ - Video Comments
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/threadId'
$ref: '#/components/schemas/VideoCommentThreadTree'
'/videos/{id}/comments/{commentId}':
post:
- summary: 'Creates a comment in a comment thread by its id, of a video by its id'
+ summary: Reply to a thread of a video
security:
- OAuth2: []
tags:
- - Video Comment
+ - Video Comments
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/commentId'
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ text:
+ type: string
+ description: 'Text comment'
+ required:
+ - text
+
delete:
- summary: 'Delete a comment in a comment thread by its id, of a video by its id'
+ summary: Delete a comment or a reply
security:
- OAuth2: []
tags:
- - Video Comment
+ - Video Comments
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/commentId'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
'/videos/{id}/rate':
put:
- summary: Vote for a video by its id
+ summary: Like/dislike a video
security:
- OAuth2: []
tags:
- - Video Rate
+ - Video Rates
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
- $ref: '#/paths/~1users~1me/put/responses/204'
+ description: successful operation
/search/videos:
get:
tags:
- Search
- summary: Get the videos corresponding to a given query
+ summary: Search 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/videosSearchSort'
- url: 'https://peertube.cpy.re/api/v1'
description: Live Test Server (live data - stable version)
- url: 'https://peertube2.cpy.re/api/v1'
- description: Live Test Server (live data - bleeding edge version)
+ description: Live Test Server (live data - latest nighlty version)
- url: 'https://peertube3.cpy.re/api/v1'
- description: Live Test Server (live data - bleeding edge version)
+ description: Live Test Server (live data - latest RC version)
components:
parameters:
start:
name: count
in: query
required: false
- description: Number of items
+ description: "Number of items (max: 100)"
schema:
type: number
sort:
name: id
in: path
required: true
- description: The video id or uuid
+ description: The object id or uuid
schema:
type: string
+ playlistElementId:
+ name: playlistElementId
+ in: path
+ required: true
+ description: Playlist element id
+ schema:
+ type: number
+ abuseId:
+ name: abuseId
+ in: path
+ required: true
+ description: Video abuse id
+ schema:
+ type: number
captionLanguage:
name: captionLanguage
in: path
name: categoryOneOf
in: query
required: false
- description: category id of the video
+ description: category id of the video (see /videos/categories)
schema:
oneOf:
- type: number
name: languageOneOf
in: query
required: false
- description: language id of the video
+ description: language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language
schema:
oneOf:
- type: string
name: licenceOneOf
in: query
required: false
- description: licence id of the video
+ description: licence id of the video (see /videos/licences)
schema:
oneOf:
- type: number
type: number
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'
nsfw:
name: nsfw
in: query
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
- description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
+ - 4
+ description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3, Internal = 4)'
VideoPrivacyConstant:
properties:
id:
- type: integer
- enum:
- - 1
- - 2
- - 3
+ $ref: '#/components/schemas/VideoPrivacySet'
label:
type: string
+
+ NSFWPolicy:
+ type: string
+ enum:
+ - display
+ - blur
+ - do_not_list
+
+ UserRole:
+ type: number
+ enum:
+ - 0
+ - 1
+ - 2
+ description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+
VideoStateConstant:
properties:
id:
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
+
VideoResolutionConstant:
properties:
id:
properties:
privacy:
$ref: '#/components/schemas/VideoPrivacySet'
- description: Video privacy target
updateAt:
type: string
format: date
description: When to update the video
required:
- updateAt
- VideoAccountSummary:
+ AccountSummary:
properties:
id:
type: number
type: string
avatar:
nullable: true
- $ref: '#/components/schemas/Avatar'
+ allOf:
+ - $ref: '#/components/schemas/Avatar'
VideoChannelSummary:
properties:
id:
type: string
avatar:
nullable: true
- $ref: '#/components/schemas/Avatar'
+ allOf:
+ - $ref: '#/components/schemas/Avatar'
PlaylistElement:
properties:
position:
type: number
video:
nullable: true
- $ref: '#/components/schemas/Video'
+ allOf:
+ - $ref: '#/components/schemas/Video'
VideoFile:
properties:
magnetUri:
type: string
fps:
type: number
+ metadataUrl:
+ type: string
VideoStreamingPlaylists:
properties:
id:
type: string
segmentsSha256Url:
type: string
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoFile'
redundancies:
type: array
items:
$ref: '#/components/schemas/VideoStateConstant'
scheduledUpdate:
nullable: true
- $ref: '#/components/schemas/VideoScheduledUpdate'
+ allOf:
+ - $ref: '#/components/schemas/VideoScheduledUpdate'
blacklisted:
nullable: true
type: boolean
nullable: true
type: string
account:
- $ref: '#/components/schemas/VideoAccountSummary'
+ $ref: '#/components/schemas/AccountSummary'
channel:
$ref: '#/components/schemas/VideoChannelSummary'
userHistory:
type: string
reporterAccount:
$ref: '#/components/schemas/Account'
+ state:
+ $ref: '#/components/schemas/VideoAbuseStateConstant'
+ moderationComment:
+ type: string
video:
type: object
properties:
type: string
uuid:
type: string
- url:
- type: string
createdAt:
type: string
VideoBlacklist:
thumbnailPath:
type: string
privacy:
- type: object
- properties:
- id:
- type: number
- label:
- type: string
+ $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
type:
- type: object
- properties:
- id:
- type: number
- label:
- type: string
+ $ref: '#/components/schemas/VideoPlaylistTypeConstant'
ownerAccount:
- type: object
- properties:
- id:
- type: number
- name:
- type: string
- displayName:
- type: string
- url:
- type: string
- host:
- type: string
+ $ref: '#/components/schemas/AccountSummary'
+ videoChannel:
+ $ref: '#/components/schemas/VideoChannelSummary'
VideoComment:
properties:
id:
type: string
email:
type: string
- displayNSFW:
+ theme:
+ type: string
+ description: 'Theme enabled by this user'
+ emailVerified:
+ type: boolean
+ description: 'Is email verified?'
+ nsfwPolicy:
+ $ref: '#/components/schemas/NSFWPolicy'
+ webtorrentEnabled:
type: boolean
autoPlayVideo:
type: boolean
role:
- type: integer
- enum:
- - 0
- - 1
- - 2
- description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+ $ref: '#/components/schemas/UserRole'
roleLabel:
type: string
enum:
type: number
videoQuotaDaily:
type: number
+ videosCount:
+ type: number
+ videoAbusesCount:
+ type: number
+ videoAbusesAcceptedCount:
+ type: number
+ videoAbusesCreatedCount:
+ type: number
+ videoCommentsCount:
+ type: number
+ noInstanceConfigWarningModal:
+ type: boolean
+ noWelcomeModal:
+ type: boolean
+ blocked:
+ type: boolean
+ blockedReason:
+ type: string
createdAt:
type: string
account:
type: string
css:
type: string
+ search:
+ type: object
+ properties:
+ remoteUri:
+ type: object
+ properties:
+ users:
+ type: boolean
+ anonymous:
+ type: boolean
plugin:
type: object
properties:
properties:
enabled:
type: boolean
+ webtorrent:
+ type: object
+ properties:
+ enabled:
+ type: boolean
enabledResolutions:
type: array
items:
properties:
enabled:
type: boolean
+ followings:
+ type: object
+ properties:
+ instance:
+ type: object
+ properties:
+ autoFollowIndex:
+ type: object
+ properties:
+ indexUrl:
+ type: string
ServerConfigAbout:
properties:
instance:
description: 'The user username '
password:
type: string
- description: 'The user password '
+ description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent '
email:
type: string
description: 'The user email '
type: string
description: 'The user daily video quota '
role:
- type: integer
- enum:
- - 0
- - 1
- - 2
- description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+ $ref: '#/components/schemas/UserRole'
required:
- username
- password
type: string
description: 'The updated daily video quota of the user '
role:
- type: integer
- enum:
- - 0
- - 1
- - 2
- description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
+ $ref: '#/components/schemas/UserRole'
required:
- id
- email
projects / oweals / peertube.git / blobdiff