openapi: 3.0.0
info:
title: PeerTube
- version: 3.2.1
+ version: 4.0.0
contact:
name: PeerTube Community
url: https://joinpeertube.org
description: Like/dislike a video.
- name: Video Playlists
description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
+ - name: Video Files
+ description: Operations on video files
+ - name: Video Transcoding
+ description: Video transcoding related operations
- name: Feeds
description: Server syndication feeds
- name: Search
- Video Playlists
- Video Ownership Change
- Video Mirroring
+ - Video Files
+ - Video Transcoding
- Live Videos
- Feeds
- name: Search
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
print(json)
+ '/accounts/{name}/followers':
+ get:
+ tags:
+ - Accounts
+ summary: 'List followers of an account'
+ security:
+ - OAuth2: []
+ operationId: getAccountFollowers
+ parameters:
+ - $ref: '#/components/parameters/name'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/followersSort'
+ - $ref: '#/components/parameters/search'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
+
/accounts:
get:
tags:
- admin
tags:
- Instance Follows
- summary: Follow a list of servers
+ summary: Follow a list of actors (PeerTube instance, channel or account)
responses:
'204':
description: successful operation
type: string
format: hostname
uniqueItems: true
+ handles:
+ type: array
+ items:
+ type: string
+ uniqueItems: true
- '/server/following/{host}':
+ '/server/following/{hostOrHandle}':
delete:
- summary: Unfollow a server
+ summary: Unfollow an actor (PeerTube instance, channel or account)
security:
- OAuth2:
- admin
tags:
- Instance Follows
parameters:
- - name: host
+ - name: hostOrHandle
in: path
required: true
- description: The host to unfollow
+ description: The hostOrHandle to unfollow
schema:
type: string
- format: hostname
responses:
'204':
description: successful operation
'404':
- description: host not found
+ description: host or handle not found
/users:
post:
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
commentsEnabled:
description: Enable or disable comments for this video
type: boolean
+ downloadEnabled:
+ description: Enable or disable downloading for this video
+ type: boolean
originallyPublishedAt:
description: Date when the content was originally published
type: string
description: video unreadable
'429':
description: too many concurrent requests
+ '503':
+ description: upload is already being processed
+ headers:
+ 'Retry-After':
+ schema:
+ type: number
+ example: 300
delete:
summary: Cancel the resumable upload of a video, deleting any data uploaded so far
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
description: Enable or disable comments for this live video/replay
type: boolean
downloadEnabled:
- description: Enable or disable downloading for the replay of this live
+ description: Enable or disable downloading for the replay of this live video
type: boolean
required:
- channelId
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '/video-channels/{channelHandle}/followers':
+ get:
+ tags:
+ - Video Channels
+ summary: 'List followers of a video channel'
+ security:
+ - OAuth2: []
+ operationId: getVideoChannelFollowers
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/followersSort'
+ - $ref: '#/components/parameters/search'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
+
'/video-channels/{channelHandle}/avatar/pick':
post:
summary: Update channel avatar
$ref: '#/components/schemas/VideoPlaylist/properties/id'
uuid:
$ref: '#/components/schemas/VideoPlaylist/properties/uuid'
+ shortUUID:
+ $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
requestBody:
content:
multipart/form-data:
- Video Playlists
parameters:
- $ref: '#/components/parameters/playlistId'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
responses:
'200':
description: successful operation
'404':
description: video does not exist
+ '/videos/{id}/hls':
+ delete:
+ summary: Delete video HLS files
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Files
+ operationId: delVideoHLS
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+ '/videos/{id}/webtorrent':
+ delete:
+ summary: Delete video WebTorrent files
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Files
+ operationId: delVideoWebTorrent
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+
+ '/videos/{id}/transcoding':
+ post:
+ summary: Create a transcoding job
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Transcoding
+ operationId: createVideoTranscoding
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ transcodingType:
+ type: string
+ enum:
+ - hls
+ - webtorrent
+ required:
+ - transcodingType
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+
/search/videos:
get:
tags:
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
'500':
description: search index unavailable
+ /search/video-playlists:
+ get:
+ tags:
+ - Search
+ summary: Search playlists
+ operationId: searchPlaylists
+ parameters:
+ - name: search
+ in: query
+ required: true
+ description: >
+ String to search. If the user can make a remote URI search, and the string is an URI then the
+ PeerTube instance will fetch the remote object and add it to its database. Then,
+ you can use the REST API to fetch the complete playlist information and interact with it.
+ schema:
+ type: string
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/searchTarget'
+ - $ref: '#/components/parameters/sort'
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
+ '500':
+ description: search index unavailable
+
+ /blocklist/status:
+ get:
+ tags:
+ - Account Blocks
+ - Server Blocks
+ summary: Get block status of accounts/hosts
+ parameters:
+ -
+ name: 'accounts'
+ in: query
+ description: 'Check if these accounts are blocked'
+ example: [ 'goofy@example.com', 'donald@example.com' ]
+ schema:
+ type: array
+ items:
+ type: string
+ -
+ name: 'hosts'
+ in: query
+ description: 'Check if these hosts are blocked'
+ example: [ 'example.com' ]
+ schema:
+ type: array
+ items:
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/schemas/BlockStatus'
+
/server/blocklist/accounts:
get:
tags:
type: string
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
responses:
'204':
description: successful operation
required: true
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
responses:
'204':
description: successful operation
type: string
enum:
- name
+ followersSort:
+ name: sort
+ in: query
+ required: false
+ description: Sort followers by criteria
+ schema:
+ type: string
+ enum:
+ - createdAt
name:
name: name
in: path
name: id
in: path
required: true
- description: The object id or uuid
+ description: The object id, uuid or short uuid
schema:
oneOf:
- $ref: '#/components/schemas/id'
- $ref: '#/components/schemas/UUIDv4'
+ - $ref: '#/components/schemas/shortUUID'
playlistId:
name: playlistId
in: path
enum:
- 'true'
- 'false'
- filter:
- name: filter
+ isLocal:
+ name: isLocal
in: query
required: false
- description: >
- Special filters which might require special rights:
- * `local` - only videos local to the instance
- * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
- * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
schema:
- type: string
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only local or remote videos'
+ hasHLSFiles:
+ name: hasHLSFiles
+ in: query
+ required: false
+ schema:
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only videos that have HLS files'
+ hasWebtorrentFiles:
+ name: hasWebtorrentFiles
+ in: query
+ required: false
+ schema:
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
+ privacyOneOf:
+ name: privacyOneOf
+ in: query
+ required: false
+ schema:
+ $ref: '#/components/schemas/VideoPrivacySet'
+ description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+ include:
+ name: include
+ in: query
+ required: false
+ schema:
+ type: integer
enum:
- - local
- - all-local
+ - 0
+ - 1
+ - 2
+ - 4
+ - 8
+ description: >
+ **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
+
+ - `0` NONE
+
+ - `1` NOT_PUBLISHED_STATE
+
+ - `2` BLACKLISTED
+
+ - `4` BLOCKED_OWNER
+
+ - `8` FILES
subscriptionsUris:
name: uris
in: query
- video-transcoding
- video-file-import
- video-import
- - videos-views
+ - videos-views-stats
- activitypub-refresher
- video-redundancy
- video-live-ending
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
minLength: 36
maxLength: 36
+ shortUUID:
+ type: string
+ description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
+ example: 2y84q2MQUMWPbiEcxNXMgC
username:
type: string
description: immutable name of the user, used to find or mention its actor
label:
type: string
+ BlockStatus:
+ properties:
+ accounts:
+ type: object
+ additionalProperties:
+ x-additionalPropertiesName: account
+ type: object
+ properties:
+ blockedByServer:
+ type: boolean
+ blockedByUser:
+ type: boolean
+ hosts:
+ type: object
+ additionalProperties:
+ x-additionalPropertiesName: host
+ type: object
+ properties:
+ blockedByServer:
+ type: boolean
+ blockedByUser:
+ type: boolean
+
NSFWPolicy:
type: string
enum:
type: string
format: uri
description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
- 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
pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
resolution:
$ref: '#/components/schemas/VideoResolutionConstant'
description: universal identifier for the video, that can be used across instances
allOf:
- $ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ allOf:
+ - $ref: '#/components/schemas/shortUUID'
isLive:
type: boolean
createdAt:
- $ref: '#/components/schemas/Video'
- type: object
properties:
+ viewers:
+ type: integer
+ description: If the video is a live, you have the amount of current viewers
descriptionPath:
type: string
example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
type: string
format: uri
description: magnet URI allowing to resolve the import's source video
- 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
pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
torrentfile:
writeOnly: true
$ref: '#/components/schemas/id'
uuid:
$ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ allOf:
+ - $ref: '#/components/schemas/shortUUID'
createdAt:
type: string
format: date-time
properties:
0p:
type: boolean
+ 144p:
+ type: boolean
240p:
type: boolean
360p:
- video-transcoding
- email
- video-import
- - videos-views
+ - videos-views-stats
- activitypub-refresher
- video-redundancy
data:
$ref: '#/components/schemas/Video/properties/id'
uuid:
$ref: '#/components/schemas/Video/properties/uuid'
+ shortUUID:
+ $ref: '#/components/schemas/Video/properties/shortUUID'
CommentThreadResponse:
properties:
total:
format: date-time
noInstanceConfigWarningModal:
type: boolean
+ noAccountSetupWarningModal:
+ type: boolean
noWelcomeModal:
type: boolean
nsfwPolicy:
type: integer
description: The user daily video quota in bytes
example: -1
- webtorrentEnabled:
+ p2pEnabled:
type: boolean
description: Enable P2P in the player
UserWithStats:
- 'true'
- 'false'
- both
- webTorrentEnabled:
+ p2pEnabled:
type: boolean
description: whether to enable P2P in the player or not
autoPlayVideo:
type: string
noInstanceConfigWarningModal:
type: boolean
+ noAccountSetupWarningModal:
+ type: boolean
noWelcomeModal:
type: boolean
GetMeVideoRating:
enum:
- 0
- 1
- - 3
+ - 2
Notification:
properties:
id:
- `13` NEW_INSTANCE_FOLLOWER
- `14` AUTO_INSTANCE_FOLLOWING
+
+ - `15` ABUSE_STATE_CHANGE
+
+ - `16` ABUSE_NEW_MESSAGE
+
+ - `17` NEW_PLUGIN_VERSION
+
+ - `18` NEW_PEERTUBE_VERSION
read:
type: boolean
video:
properties:
rtmpUrl:
type: string
+ rtmpsUrl:
+ type: string
streamKey:
type: string
description: RTMP stream key to use to stream into this live video