openapi: 3.0.0
info:
title: PeerTube
- version: 3.3.0
+ version: 4.0.0
contact:
name: PeerTube Community
url: https://joinpeertube.org
### Import
- _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
- - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
- - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
+ - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
+ - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
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: 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
'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
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:
example: |
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
+ '/videos/{id}/source':
+ post:
+ summary: Get video source file metadata
+ operationId: getVideoSource
+ tags:
+ - Video
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoSource'
+
'/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
- operationId: setProgress
+ 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'
+ - name: startDate
+ in: query
+ description: Filter stats by start date
+ schema:
+ type: string
+ format: date-time
+ - name: endDate
+ in: query
+ description: Filter stats by end date
+ schema:
+ type: string
+ format: date-time
+ 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'
+ - name: startDate
+ in: query
+ description: Filter stats by start date
+ schema:
+ type: string
+ format: date-time
+ - name: endDate
+ in: query
+ description: Filter stats by end date
+ schema:
+ type: string
+ format: date-time
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsTimeserie'
+
/videos/upload:
post:
summary: Upload a video
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
+ - `quota_reached` for quota limits whether daily or global
headers:
X-File-Maximum-Size:
schema:
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:
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
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: bad parameters or trying to update a live that has already started
'403':
description: trying to save replay of the live but saving replay is not enabled on the instance
+ /videos/live/{id}/sessions:
+ get:
+ summary: List live sessions
+ description: List all sessions created in a particular live
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/LiveVideoSessionResponse'
+ /videos/{id}/live-session:
+ get:
+ summary: Get live session of a replay
+ description: If the video is a replay of a live, you can find the associated live session using this endpoint
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LiveVideoSessionResponse'
/users/me/abuses:
get:
type: object
properties:
id:
- $ref: '#/components/schemas/VideoChannel/properties/id'
+ $ref: '#/components/schemas/id'
requestBody:
content:
application/json:
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/parameters/name'
- name: withStats
in: query
- description: include view statistics for the last 30 days (only if authentified as the account user)
+ description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
schema:
type: boolean
- $ref: '#/components/parameters/start'
name: sort
in: query
required: false
- description: Sort videos by criteria
schema:
type: string
enum:
- - name
- - -duration
- - -createdAt
- - -publishedAt
- - -views
- - -likes
- - -trending
- - -hot
+ - name
+ - -duration
+ - -createdAt
+ - -publishedAt
+ - -views
+ - -likes
+ - -trending
+ - -hot
+ - -best
+ description: >
+ Sort videos by criteria (prefixing with `-` means `DESC` order):
+ * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
+ * `best` - Same than `hot`, but also takes into account user video history
+ * `trending` - Sort videos by recent views ("recent" is defined by the admin)
+ * `views` - Sort videos using their `views` counter
+ * `publishedAt` - Sort by video publication date (when it became publicly available)
videosSearchSort:
name: sort
in: query
required: false
- description: Sort videos by criteria
+ description: >
+ Sort videos by criteria (prefixing with `-` means `DESC` order):
schema:
type: string
enum:
name: id
in: path
required: true
- description: The user id
+ description: Entity id
schema:
$ref: '#/components/schemas/id'
idOrUUID:
moderator: Moderator scope
user: User scope
schemas:
- # Resuable core properties
+ # Reusable core properties
id:
type: integer
minimum: 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`, High latency = `2`, Small Latency = `3`)'
+
VideoStateConstant:
properties:
id:
- 1
- 2
- 3
- description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
+ - 4
+ - 5
+ - 6
+ - 7
+ - 8
+ - 9
+ description: |
+ The video state:
+ - `1`: Published
+ - `2`: To transcode
+ - `3`: To import
+ - `4`: Waiting for live stream
+ - `5`: Live ended
+ - `6`: To move to an external storage (object storage...)
+ - `7`: Transcoding failed
+ - `8`: Moving to an external storage failed
+ - `9`: To edit using studio edition feature
label:
type: string
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:
$ref: '#/components/schemas/VideoConstantString-Language'
captionPath:
type: string
+ VideoSource:
+ properties:
+ filename:
+ type: string
ActorImage:
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
+ 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:
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:
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'
- `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
+ description: Included in the response if an appropriate token is provided
rtmpsUrl:
type: string
+ description: Included in the response if an appropriate token is provided
streamKey:
type: string
- description: RTMP stream key to use to stream into this live video
+ description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
saveReplay:
type: boolean
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'
-
+ LiveVideoSessionResponse:
+ properties:
+ id:
+ type: integer
+ startDate:
+ type: string
+ format: date-time
+ description: Start date of the live session
+ endDate:
+ type: string
+ format: date-time
+ nullable: true
+ description: End date of the live session
+ error:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ - 4
+ - 5
+ nullable: true
+ description: >
+ Error type if an error occurred during the live session:
+ - `1`: Bad socket health (transcoding is too slow)
+ - `2`: Max duration exceeded
+ - `3`: Quota exceeded
+ - `4`: Quota FFmpeg error
+ - `5`: Video has been blacklisted during the live
+ replayVideo:
+ type: object
+ description: Video replay information
+ properties:
+ id:
+ type: number
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ $ref: '#/components/schemas/shortUUID'
callbacks:
searchIndex: