openapi: 3.0.0
info:
title: PeerTube
- version: 3.2.0
+ version: 4.0.0
contact:
name: PeerTube Community
url: https://joinpeertube.org
# Errors
The API uses standard HTTP status codes to indicate the success or failure
- of the API call.
+ of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
```
HTTP 1.1 404 Not Found
- Content-Type: application/json
+ Content-Type: application/problem+json; charset=utf-8
{
- "errorCode": 1
- "error": "Account not found"
+ "detail": "Video not found",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 404,
+ "title": "Not Found",
+ "type": "about:blank"
}
```
- We provide error codes for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
- but it is still optional.
+ We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
+ but it is still optional. Types are used to disambiguate errors that bear the same status code
+ and are non-obvious:
+
+ ```
+ HTTP 1.1 403 Forbidden
+ Content-Type: application/problem+json; charset=utf-8
+
+ {
+ "detail": "Cannot get this video regarding follow constraints",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 403,
+ "title": "Forbidden",
+ "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+ }
+ ```
+
+ Here a 403 error could otherwise mean that the video is private or blocklisted.
### Validation errors
Each parameter is evaluated on its own against a set of rules before the route validator
- proceeds with potential testing involving parameter combinations. Errors coming from Validation
- errors appear earlier and benefit from a more detailed error type:
+ proceeds with potential testing involving parameter combinations. Errors coming from validation
+ errors appear earlier and benefit from a more detailed error description:
```
HTTP 1.1 400 Bad Request
- Content-Type: application/json
+ Content-Type: application/problem+json; charset=utf-8
{
- "errors": {
+ "detail": "Incorrect request parameters: id",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
+ "invalid-params": {
"id": {
- "value": "a117eb-c6a9-4756-bb09-2a956239f",
- "msg": "Should have a valid id",
+ "location": "params",
+ "msg": "Invalid value",
"param": "id",
- "location": "params"
+ "value": "9c9de5e8-0a1e-484a-b099-e80766180"
}
- }
+ },
+ "status": 400,
+ "title": "Bad Request",
+ "type": "about:blank"
}
```
Where `id` is the name of the field concerned by the error, within the route definition.
- `errors.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
- `errors.<field>.value` reports the value that didn't pass validation whose `errors.<field>.msg`
+ `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
+ `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
is about.
+ ### Deprecated error fields
+
+ Some fields could be included with previous versions. They are still included but their use is deprecated:
+ - `error`: superseded by `detail`
+ - `code`: superseded by `type` (which is now an URI)
+
# Rate limits
We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
The import function is practical when the desired video/audio is available online. It makes PeerTube
download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
+ - name: Video Imports
+ description: Operations dealing with listing, adding and removing video imports.
- name: Video Captions
description: Operations dealing with listing, adding and removing closed captions of a video.
- name: Video Channels
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: Video stats
+ description: Video statistics
- name: Feeds
description: Server syndication feeds
- name: Search
tags:
- Video
- Video Upload
+ - Video Imports
- Video Captions
- Video Channels
- Video Comments
- Video Rates
- Video Playlists
+ - Video Stats
- 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:
'204':
description: successful operation
+ /jobs/pause:
+ post:
+ summary: Pause job queue
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Job
+ responses:
+ '204':
+ description: successful operation
+
+ /jobs/resume:
+ post:
+ summary: Resume job queue
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Job
+ responses:
+ '204':
+ description: successful operation
+
/jobs/{state}:
get:
summary: List instance jobs
- 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:
type: integer
minimum: 0
example: 1209600
+ '400':
+ x-summary: client or credentials are invalid
+ description: |
+ Disambiguate via `type`:
+ - `invalid_client` for an unmatched `client_id`
+ - `invalid_grant` for unmatched credentials
+ '401':
+ x-summary: token expired
+ description: |
+ Disambiguate via `type`:
+ - default value for a regular authentication failure
+ - `invalid_token` for an expired token
x-codeSamples:
- lang: Shell
source: |
- $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'
+ /users/me/history/videos/{videoId}:
+ delete:
+ summary: Delete history element
+ security:
+ - OAuth2: []
+ tags:
+ - My History
+ parameters:
+ - name: videoId
+ in: path
+ required: true
+ schema:
+ $ref: '#/components/schemas/Video/properties/id'
+ responses:
+ '204':
+ description: successful operation
+
/users/me/history/videos/remove:
post:
summary: Clear video history
schema:
type: object
properties:
- avatar:
- $ref: '#/components/schemas/ActorImage'
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
'413':
description: image file too large
headers:
'403':
description: cannot terminate an ownership change of another user
'404':
- description: video owneship change not found
+ description: video ownership change not found
'/videos/ownership/{id}/refuse':
post:
'403':
description: cannot terminate an ownership change of another user
'404':
- description: video owneship change not found
+ description: video ownership change not found
'/videos/{id}/give-ownership':
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'
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
'/videos/{id}/views':
post:
- summary: Add a view to a video
+ summary: Notify user is watching a video
+ description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
+ operationId: addView
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserViewingVideo'
+ required: true
responses:
'204':
description: successful operation
'/videos/{id}/watching':
put:
summary: Set watching progress of a video
+ deprecated: true
+ description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
tags:
- Video
security:
content:
application/json:
schema:
- $ref: '#/components/schemas/UserWatchingVideo'
+ $ref: '#/components/schemas/UserViewingVideo'
required: true
responses:
'204':
description: successful operation
+ '/videos/{id}/stats/overall':
+ get:
+ summary: Get overall stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsOverall'
+
+ '/videos/{id}/stats/retention':
+ get:
+ summary: Get retention stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsRetention'
+
+ '/videos/{id}/stats/timeseries/{metric}':
+ get:
+ summary: Get timeserie stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ -
+ name: metric
+ in: path
+ required: true
+ description: The metric to get
+ schema:
+ type: string
+ enum:
+ - 'viewers'
+ - 'aggregateWatchTime'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsTimeserie'
+
/videos/upload:
post:
summary: Upload a video
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
- '400':
- description: invalid file field, schedule date or parameter
'403':
description: video didn't pass upload filter
'408':
description: upload has timed out
'413':
- description: video file too large, due to quota or max body size limit set by the reverse-proxy
+ x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
+ description: |
+ If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
+ - `quota_reached` for quota limits wether daily or global
headers:
X-File-Maximum-Size:
schema:
schema:
type: number
example: 0
- '400':
- description: invalid file field, schedule date or parameter
'413':
- description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+ x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
+ description: |
+ Disambiguate via `type`:
+ - `max_file_size_reached` for the absolute file size limit
+ - `quota_reached` for quota limits whether daily or global
'415':
description: video type unsupported
put:
in: query
required: true
description: |
- Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+ Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.
schema:
type: string
description: |
Size of the chunk that the request is sending.
- The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
- doesn't mandate for chunks to have the same size throughout the upload sequence.
-
Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1048576 bytes (~1MB) and increases or reduces size depending on connection health.
requestBody:
example: 0
'403':
description: video didn't pass upload filter
- '413':
- description: video file too large, due to quota or max body size limit set by the reverse-proxy
+ '404':
+ description: upload not found
+ '409':
+ description: chunk doesn't match range
'422':
description: video unreadable
+ '429':
+ description: too many concurrent requests
+ '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
schema:
type: number
example: 0
+ '404':
+ description: upload not found
/videos/imports:
post:
security:
- OAuth2: []
tags:
- - Video
+ - Video Imports
- Video Upload
requestBody:
content:
'409':
description: HTTP or Torrent/magnetURI import not enabled
+ /videos/imports/{id}/cancel:
+ post:
+ summary: Cancel video import
+ description: Cancel a pending video import
+ security:
+ - OAuth2: []
+ tags:
+ - Video Imports
+ parameters:
+ - $ref: '#/components/parameters/id'
+ responses:
+ '204':
+ description: successful operation
+
+ /videos/imports/{id}:
+ delete:
+ summary: Delete video import
+ description: Delete ended video import
+ security:
+ - OAuth2: []
+ tags:
+ - Video Imports
+ parameters:
+ - $ref: '#/components/parameters/id'
+ responses:
+ '204':
+ description: successful operation
+
/videos/live:
post:
summary: Create a live
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
+ '400':
+ x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
+ description: |
+ Disambiguate via `type`:
+ - default type for a validation error
+ - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
'403':
- description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+ x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+ description: |
+ Disambiguate via `type`:
+ - `live_not_enabled` for a disabled live feature
+ - `live_not_allowing_replay` for a disabled replay feature
+ - `max_instance_lives_limit_reached` for the absolute concurrent live limit
+ - `max_user_lives_limit_reached` for the user concurrent live limit
requestBody:
content:
multipart/form-data:
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
thumbnailfile:
description: Live video/replay thumbnail file
type: string
description: Enable or disable comments for this live video/replay
type: boolean
downloadEnabled:
- description: Enable or disable downloading for the replay of this live
+ description: Enable or disable downloading for the replay of this live video
type: boolean
required:
- channelId
type: string
- name: videoIs
in: query
- description: only list blacklisted or deleted videos
+ description: only list deleted or blocklisted videos
schema:
type: string
enum:
type: object
properties:
id:
- $ref: '#/components/schemas/VideoChannel/properties/id'
+ $ref: '#/components/schemas/id'
requestBody:
content:
application/json:
- $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
schema:
type: object
properties:
- avatar:
- $ref: '#/components/schemas/ActorImage'
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
'413':
description: image file too large
headers:
schema:
type: object
properties:
- banner:
- $ref: '#/components/schemas/ActorImage'
+ banners:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
'413':
description: image file too large
headers:
$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
name: sort
in: query
required: false
- description: Sort blacklists by criteria
+ description: Sort blocklists by criteria
schema:
type: string
enum:
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 user id
+ description: Entity id
schema:
$ref: '#/components/schemas/id'
idOrUUID:
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:
enum:
- 0
- 1
- description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
+ description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
example: 1
+ LiveVideoLatencyMode:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
+
VideoStateConstant:
properties:
id:
host:
type: string
format: hostname
- avatar:
- nullable: true
- allOf:
- - $ref: '#/components/schemas/ActorImage'
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
VideoChannelSummary:
properties:
id:
host:
type: string
format: hostname
- avatar:
- nullable: true
- allOf:
- - $ref: '#/components/schemas/ActorImage'
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
PlaylistElement:
properties:
position:
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:
path:
type: string
+ width:
+ type: integer
createdAt:
type: string
format: date-time
host:
type: string
format: hostname
- avatar:
- nullable: true
- type: object
- properties:
- path:
- type: string
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
Actor:
properties:
id:
updatedAt:
type: string
format: date-time
- avatar:
- $ref: '#/components/schemas/ActorImage'
Account:
allOf:
- $ref: '#/components/schemas/Actor'
description:
type: string
description: text or bio displayed on the account's profile
- UserWatchingVideo:
+ UserViewingVideo:
+ required:
+ - currentTime
properties:
currentTime:
type: integer
format: seconds
description: timestamp within the video, in seconds
example: 5
+ viewEvent:
+ type: string
+ enum:
+ - seek
+ description: >
+ Event since last viewing call:
+ * `seek` - If the user seeked the video
+
+ VideoStatsOverall:
+ properties:
+ averageWatchTime:
+ type: number
+ totalWatchTime:
+ type: number
+ viewersPeak:
+ type: number
+ viewersPeakDate:
+ type: string
+ format: date-time
+ views:
+ type: number
+ likes:
+ type: number
+ dislikes:
+ type: number
+ comments:
+ type: number
+ countries:
+ type: array
+ items:
+ type: object
+ properties:
+ isoCode:
+ type: string
+ viewers:
+ type: number
+
+ VideoStatsRetention:
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ second:
+ type: number
+ retentionPercent:
+ type: number
+
+ VideoStatsTimeserie:
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ date:
+ type: string
+ value:
+ type: number
+
ServerConfig:
properties:
instance:
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:
$ref: '#/components/schemas/UserRole'
adminFlags:
$ref: '#/components/schemas/UserAdminFlags'
+ password:
+ $ref: '#/components/schemas/password'
UpdateMe:
# see shared/models/users/user-update-me.model.ts:
properties:
- '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:
name:
$ref: '#/components/schemas/usernameChannel'
displayName:
- $ref: '#/components/schemas/VideoChannel/properties/displayName'
+ type: string
required:
- username
- password
- refresh_token
VideoChannel:
- properties:
- # GET/POST/PUT properties
- displayName:
- type: string
- description: editable name of the channel, displayed in its representations
- example: Videos of Framasoft
- minLength: 1
- maxLength: 120
- description:
- type: string
- example: Videos made with <3 by Framasoft
- minLength: 3
- maxLength: 1000
- support:
- type: string
- description: text shown by default on all videos of this channel, to tell the audience how to support it
- example: Please support our work on https://soutenir.framasoft.org/en/ <3
- minLength: 3
- maxLength: 1000
- # GET-only properties
- id:
- readOnly: true
- allOf:
- - $ref: '#/components/schemas/id'
- isLocal:
- readOnly: true
- type: boolean
- updatedAt:
- readOnly: true
- type: string
- format: date-time
- ownerAccount:
- readOnly: true
- nullable: true
- type: object
+ allOf:
+ - $ref: '#/components/schemas/Actor'
+ - type: object
properties:
- id:
- type: integer
- uuid:
- $ref: '#/components/schemas/UUIDv4'
+ displayName:
+ type: string
+ description: editable name of the channel, displayed in its representations
+ example: Videos of Framasoft
+ minLength: 1
+ maxLength: 120
+ description:
+ type: string
+ example: Videos made with <3 by Framasoft
+ minLength: 3
+ maxLength: 1000
+ support:
+ type: string
+ description: text shown by default on all videos of this channel, to tell the audience how to support it
+ example: Please support our work on https://soutenir.framasoft.org/en/ <3
+ minLength: 3
+ maxLength: 1000
+ isLocal:
+ readOnly: true
+ type: boolean
+ updatedAt:
+ readOnly: true
+ type: string
+ format: date-time
+ banners:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
+ ownerAccount:
+ readOnly: true
+ nullable: true
+ type: object
+ properties:
+ id:
+ type: integer
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
VideoChannelCreate:
allOf:
- $ref: '#/components/schemas/VideoChannel'
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:
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
LiveVideoResponse:
properties:
rtmpUrl:
type: string
+ rtmpsUrl:
+ type: string
streamKey:
type: string
description: RTMP stream key to use to stream into this live video
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
-
-
+ latencyMode:
+ description: User can select live latency mode if enabled by the instance
+ $ref: '#/components/schemas/LiveVideoLatencyMode'
callbacks:
searchIndex:
projects / github / Chocobozzz / PeerTube.git / blobdiff