openapi: 3.0.0
info:
title: PeerTube
- version: 4.0.0
+ version: 5.1.0
contact:
name: PeerTube Community
url: https://joinpeertube.org
| `/api/*` |
| `/download/*` |
| `/lazy-static/*` |
- | `/live/segments-sha256/*` |
| `/.well-known/webfinger` |
In addition, all routes serving ActivityPub are CORS-enabled for all origins.
description: Video transcoding related operations
- name: Video stats
description: Video statistics
- - name: Feeds
- description: Server syndication feeds
+ - name: Video Feeds
+ description: Server syndication feeds of videos
- name: Search
description: |
The search helps to find _videos_ or _channels_ from within the instance and beyond.
Statistics
x-tagGroups:
+ - name: Static endpoints
+ tags:
+ - Static Video Files
+ - name: Feeds
+ tags:
+ - Video Feeds
- name: Auth
tags:
- Register
- Video Files
- Video Transcoding
- Live Videos
- - Feeds
- Channels Sync
- name: Search
tags:
- Logs
- Job
paths:
- '/accounts/{name}':
+ '/static/webseed/{filename}':
get:
tags:
- - Accounts
- summary: Get an account
- operationId: getAccount
+ - Static Video Files
+ summary: Get public WebTorrent video file
parameters:
- - $ref: '#/components/parameters/name'
+ - $ref: '#/components/parameters/staticFilename'
responses:
'200':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/Account'
'404':
- description: account not found
-
- '/accounts/{name}/videos':
+ description: not found
+ '/static/webseed/private/{filename}':
get:
tags:
- - Accounts
- - Video
- summary: 'List videos of an account'
- operationId: getAccountVideos
+ - Static Video Files
+ summary: Get private WebTorrent video file
parameters:
- - $ref: '#/components/parameters/name'
- - $ref: '#/components/parameters/categoryOneOf'
- - $ref: '#/components/parameters/isLive'
- - $ref: '#/components/parameters/tagsOneOf'
- - $ref: '#/components/parameters/tagsAllOf'
- - $ref: '#/components/parameters/licenceOneOf'
- - $ref: '#/components/parameters/languageOneOf'
- - $ref: '#/components/parameters/nsfw'
- - $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/videosSort'
+ - $ref: '#/components/parameters/staticFilename'
+ - $ref: '#/components/parameters/videoFileToken'
+ security:
+ - OAuth2: []
responses:
'200':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoListResponse'
- x-codeSamples:
- - lang: JavaScript
- source: |
- fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
- .then(function(response) {
- return response.json()
- }).then(function(data) {
- console.log(data)
- })
- - lang: Shell
- source: |
- ## DEPENDENCIES: jq
- curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
- - lang: Ruby
- source: |
- require 'net/http'
- require 'json'
-
- uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
-
- http = Net::HTTP.new(uri.host, uri.port)
- http.use_ssl = true
-
- response = http.get(uri.request_uri)
-
- puts JSON.parse(response.read_body)
- - lang: Python
- source: |
- import requests
-
- r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
- json = r.json()
-
- print(json)
+ '403':
+ description: invalid auth
+ '404':
+ description: not found
- '/accounts/{name}/followers':
+ '/static/streaming-playlists/hls/{filename}':
get:
tags:
- - Accounts
- summary: 'List followers of an account'
+ - Static Video Files
+ summary: Get public HLS video file
+ parameters:
+ - $ref: '#/components/parameters/staticFilename'
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:
+ '403':
+ description: invalid auth
+ '404':
+ description: not found
+ '/static/streaming-playlists/hls/private/{filename}':
get:
tags:
- - Accounts
- summary: List accounts
- operationId: getAccounts
+ - Static Video Files
+ summary: Get private HLS video file
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/staticFilename'
+ - $ref: '#/components/parameters/videoFileToken'
+ - $ref: '#/components/parameters/reinjectVideoFileToken'
+ security:
+ - OAuth2: []
responses:
'200':
description: successful operation
- content:
- 'application/json':
- schema:
- type: array
- items:
- $ref: '#/components/schemas/Account'
+ '403':
+ description: invalid auth
+ '404':
+ description: not found
- /config:
+
+ '/feeds/video-comments.{format}':
get:
tags:
- - Config
- summary: Get instance public configuration
- operationId: getConfig
+ - Video Feeds
+ summary: List comments on videos
+ operationId: getSyndicatedComments
+ parameters:
+ - name: format
+ in: path
+ required: true
+ description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
+ schema:
+ type: string
+ enum:
+ - xml
+ - rss
+ - rss2
+ - atom
+ - atom1
+ - json
+ - json1
+ - name: videoId
+ in: query
+ description: 'limit listing to a specific video'
+ schema:
+ type: string
+ - name: accountId
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: accountName
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: videoChannelId
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
+ - name: videoChannelName
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
responses:
- '200':
+ '204':
description: successful operation
+ headers:
+ Cache-Control:
+ schema:
+ type: string
+ default: 'max-age=900' # 15 min cache
content:
- application/json:
+ application/xml:
schema:
- $ref: '#/components/schemas/ServerConfig'
+ $ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
- externalValue: https://peertube2.cpy.re/api/v1/config
-
- /config/about:
- get:
- summary: Get instance "About" information
- operationId: getAbout
- tags:
- - Config
- responses:
- '200':
- description: successful operation
- content:
- application/json:
+ externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
+ application/rss+xml:
schema:
- $ref: '#/components/schemas/ServerConfigAbout'
+ $ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
- externalValue: https://peertube2.cpy.re/api/v1/config/about
-
- /config/custom:
- get:
- summary: Get instance runtime configuration
- operationId: getCustomConfig
- tags:
- - Config
- security:
- - OAuth2:
- - admin
- responses:
- '200':
- description: successful operation
- content:
+ externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
+ text/xml:
+ schema:
+ $ref: '#/components/schemas/VideoCommentsForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
+ application/atom+xml:
+ schema:
+ $ref: '#/components/schemas/VideoCommentsForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
application/json:
schema:
- $ref: '#/components/schemas/ServerConfigCustom'
- put:
- summary: Set instance runtime configuration
- operationId: putCustomConfig
- tags:
- - Config
- security:
- - OAuth2:
- - admin
- responses:
- '200':
- description: successful operation
+ type: object
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
'400':
x-summary: field inconsistencies
description: >
Arises when:
- - the emailer is disabled and the instance is open to registrations
- - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
- delete:
- summary: Delete instance runtime configuration
- operationId: delCustomConfig
- tags:
- - Config
- security:
- - OAuth2:
- - admin
- responses:
- '200':
- description: successful operation
+ - videoId filter is mixed with a channel filter
+ '404':
+ description: video, video channel or account not found
+ '406':
+ description: accept header unsupported
- /custom-pages/homepage/instance:
+ '/feeds/videos.{format}':
get:
- summary: Get instance custom homepage
tags:
- - Homepage
+ - Video Feeds
+ summary: List videos
+ operationId: getSyndicatedVideos
+ parameters:
+ - name: format
+ in: path
+ required: true
+ description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
+ schema:
+ type: string
+ enum:
+ - xml
+ - rss
+ - rss2
+ - atom
+ - atom1
+ - json
+ - json1
+ - name: accountId
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: accountName
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: videoChannelId
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
+ - name: videoChannelName
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
+ - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/nsfw'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
responses:
- '404':
- description: No homepage set
- '200':
+ '204':
description: successful operation
+ headers:
+ Cache-Control:
+ schema:
+ type: string
+ default: 'max-age=900' # 15 min cache
content:
+ application/xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
+ application/rss+xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
+ text/xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
+ application/atom+xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
application/json:
schema:
- $ref: '#/components/schemas/CustomHomepage'
- put:
- summary: Set instance custom homepage
- tags:
- - Homepage
- security:
- - OAuth2:
- - admin
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- content:
- type: string
- description: content of the homepage, that will be injected in the client
- responses:
- '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
+ type: object
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
+ '404':
+ description: video channel or account not found
+ '406':
+ description: accept header unsupported
- /jobs/{state}:
+ '/feeds/subscriptions.{format}':
get:
- summary: List instance jobs
- operationId: getJobs
- security:
- - OAuth2:
- - admin
tags:
- - Job
+ - Video Feeds
+ summary: List videos of subscriptions tied to a token
+ operationId: getSyndicatedSubscriptionVideos
parameters:
- - name: state
+ - name: format
in: path
required: true
- description: The state of the job ('' for for no filter)
+ description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
schema:
type: string
enum:
- - ''
- - active
- - completed
- - failed
- - waiting
- - delayed
- - $ref: '#/components/parameters/jobType'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
+ - xml
+ - rss
+ - rss2
+ - atom
+ - atom1
+ - json
+ - json1
+ - name: accountId
+ in: query
+ description: limit listing to a specific account
+ schema:
+ type: string
+ required: true
+ - name: token
+ in: query
+ description: private token allowing access
+ schema:
+ type: string
+ required: true
- $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/nsfw'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
responses:
- '200':
+ '204':
description: successful operation
+ headers:
+ Cache-Control:
+ schema:
+ type: string
+ default: 'max-age=900' # 15 min cache
content:
+ application/xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ application/rss+xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ text/xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
+ application/atom+xml:
+ schema:
+ $ref: '#/components/schemas/VideosForXML'
application/json:
schema:
type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- maxItems: 100
- items:
- $ref: '#/components/schemas/Job'
+ '406':
+ description: accept header unsupported
- /server/followers:
+ '/api/v1/accounts/{name}':
get:
tags:
- - Instance Follows
- summary: List instances following the server
+ - Accounts
+ summary: Get an account
+ operationId: getAccount
parameters:
- - $ref: '#/components/parameters/followState'
- - $ref: '#/components/parameters/actorType'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/name'
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'
-
- '/server/followers/{nameWithHost}':
- delete:
- summary: Remove or reject a follower to your server
- security:
- - OAuth2:
- - admin
- tags:
- - Instance Follows
- parameters:
- - name: nameWithHost
- in: path
- required: true
- description: The remote actor handle to remove from your followers
- schema:
- type: string
- format: email
- responses:
- '204':
- description: successful operation
+ $ref: '#/components/schemas/Account'
'404':
- description: follower not found
+ description: account not found
- '/server/followers/{nameWithHost}/reject':
- post:
- summary: Reject a pending follower to your server
- security:
- - OAuth2:
- - admin
+ '/api/v1/accounts/{name}/videos':
+ get:
tags:
- - Instance Follows
- parameters:
- - name: nameWithHost
- in: path
- required: true
- description: The remote actor handle to remove from your followers
- schema:
- type: string
- format: email
- responses:
- '204':
- description: successful operation
- '404':
- description: follower not found
-
- '/server/followers/{nameWithHost}/accept':
- post:
- summary: Accept a pending follower to your server
- security:
- - OAuth2:
- - admin
- tags:
- - Instance Follows
+ - Accounts
+ - Video
+ summary: 'List videos of an account'
+ operationId: getAccountVideos
parameters:
- - name: nameWithHost
- in: path
- required: true
- description: The remote actor handle to remove from your followers
- schema:
- type: string
- format: email
+ - $ref: '#/components/parameters/name'
+ - $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
+ - $ref: '#/components/parameters/tagsOneOf'
+ - $ref: '#/components/parameters/tagsAllOf'
+ - $ref: '#/components/parameters/licenceOneOf'
+ - $ref: '#/components/parameters/languageOneOf'
+ - $ref: '#/components/parameters/nsfw'
+ - $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/videosSort'
responses:
- '204':
+ '200':
description: successful operation
- '404':
- description: follower not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoListResponse'
+ x-codeSamples:
+ - lang: JavaScript
+ source: |
+ fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
+ .then(function(response) {
+ return response.json()
+ }).then(function(data) {
+ console.log(data)
+ })
+ - lang: Shell
+ source: |
+ ## DEPENDENCIES: jq
+ curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
+ - lang: Ruby
+ source: |
+ require 'net/http'
+ require 'json'
+
+ uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
+
+ http = Net::HTTP.new(uri.host, uri.port)
+ http.use_ssl = true
+
+ response = http.get(uri.request_uri)
+
+ puts JSON.parse(response.read_body)
+ - lang: Python
+ source: |
+ import requests
+
+ r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
+ json = r.json()
+
+ print(json)
- /server/following:
+ '/api/v1/accounts/{name}/followers':
get:
tags:
- - Instance Follows
- summary: List instances followed by the server
+ - Accounts
+ summary: 'List followers of an account'
+ security:
+ - OAuth2: []
+ operationId: getAccountFollowers
parameters:
- - $ref: '#/components/parameters/followState'
- - $ref: '#/components/parameters/actorType'
+ - $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/followersSort'
+ - $ref: '#/components/parameters/search'
responses:
'200':
description: successful operation
type: array
items:
$ref: '#/components/schemas/Follow'
- post:
- security:
- - OAuth2:
- - admin
+
+ /api/v1/accounts:
+ get:
tags:
- - Instance Follows
- summary: Follow a list of actors (PeerTube instance, channel or account)
+ - Accounts
+ summary: List accounts
+ operationId: getAccounts
+ parameters:
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
- '204':
+ '200':
description: successful operation
- '500':
- description: cannot follow a non-HTTPS server
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- hosts:
- type: array
- items:
- type: string
- format: hostname
- uniqueItems: true
- handles:
- type: array
- items:
- type: string
- uniqueItems: true
+ content:
+ 'application/json':
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Account'
- '/server/following/{hostOrHandle}':
- delete:
- summary: Unfollow an actor (PeerTube instance, channel or account)
- security:
- - OAuth2:
- - admin
+ /api/v1/config:
+ get:
tags:
- - Instance Follows
- parameters:
- - name: hostOrHandle
- in: path
- required: true
- description: The hostOrHandle to unfollow
- schema:
- type: string
+ - Config
+ summary: Get instance public configuration
+ operationId: getConfig
responses:
- '204':
+ '200':
description: successful operation
- '404':
- description: host or handle not found
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ServerConfig'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/config
- /users:
- post:
- summary: Create a user
- operationId: addUser
- security:
- - OAuth2:
- - admin
+ /api/v1/config/about:
+ get:
+ summary: Get instance "About" information
+ operationId: getAbout
tags:
- - Users
+ - Config
responses:
'200':
- description: user created
+ description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/AddUserResponse'
- links:
- # GET /users/{id}
- GetUser:
- operationId: getUser
- parameters:
- id: '$response.body#/user/id'
- # PUT /users/{id}
- PutUser:
- operationId: putUser
- parameters:
- id: '$response.body#/user/id'
- # DELETE /users/{id}
- DelUser:
- operationId: delUser
- parameters:
- id: '$response.body#/user/id'
- '403':
- description: insufficient authority to create an admin or moderator
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/AddUser'
- description: |
- If the smtp server is configured, you can leave the password empty and an email will be sent
- asking the user to set it first.
- required: true
+ $ref: '#/components/schemas/ServerConfigAbout'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/config/about
+
+ /api/v1/config/custom:
get:
- summary: List users
- operationId: getUsers
+ summary: Get instance runtime configuration
+ operationId: getCustomConfig
+ tags:
+ - Config
security:
- OAuth2:
- admin
- tags:
- - Users
- parameters:
- - $ref: '#/components/parameters/usersSearch'
- - $ref: '#/components/parameters/usersBlocked'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/usersSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/User'
-
- '/users/{id}':
- parameters:
- - $ref: '#/components/parameters/id'
- delete:
- summary: Delete a user
+ $ref: '#/components/schemas/ServerConfigCustom'
+ put:
+ summary: Set instance runtime configuration
+ operationId: putCustomConfig
+ tags:
+ - Config
security:
- OAuth2:
- admin
- tags:
- - Users
- operationId: delUser
responses:
- '204':
+ '200':
description: successful operation
- get:
- summary: Get a user
- security:
- - OAuth2: []
- tags:
- - Users
- operationId: getUser
- parameters:
- - name: withStats
- in: query
- description: include statistics about the user (only available as a moderator/admin)
- schema:
- type: boolean
- responses:
- '200':
- x-summary: successful operation
- description: |
- As an admin/moderator, you can request a response augmented with statistics about the user's
- moderation relations and videos usage, by using the `withStats` parameter.
- content:
- application/json:
- schema:
- oneOf:
- - $ref: '#/components/schemas/User'
- - $ref: '#/components/schemas/UserWithStats'
- put:
- summary: Update a user
- security:
- - OAuth2: []
- tags:
- - Users
- operationId: putUser
- responses:
- '204':
- description: successful operation
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/UpdateUser'
- required: true
-
- /oauth-clients/local:
- get:
- summary: Login prerequisite
- description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
- operationId: getOAuthClient
+ '400':
+ x-summary: field inconsistencies
+ description: >
+ Arises when:
+ - the emailer is disabled and the instance is open to registrations
+ - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
+ delete:
+ summary: Delete instance runtime configuration
+ operationId: delCustomConfig
tags:
- - Session
+ - Config
+ security:
+ - OAuth2:
+ - admin
responses:
'200':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/OAuthClient'
- links:
- UseOAuthClientToLogin:
- operationId: getOAuthToken
- parameters:
- client_id: '$response.body#/client_id'
- client_secret: '$response.body#/client_secret'
- x-codeSamples:
- - lang: Shell
- source: |
- API="https://peertube2.cpy.re/api/v1"
- ## AUTH
- curl -s "$API/oauth-clients/local"
-
- /users/token:
- post:
- summary: Login
- operationId: getOAuthToken
- description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
+ /api/v1/custom-pages/homepage/instance:
+ get:
+ summary: Get instance custom homepage
tags:
- - Session
- requestBody:
- content:
- application/x-www-form-urlencoded:
- schema:
- oneOf:
- - $ref: '#/components/schemas/OAuthToken-password'
- - $ref: '#/components/schemas/OAuthToken-refresh_token'
- discriminator:
- propertyName: grant_type
- mapping:
- password: '#/components/schemas/OAuthToken-password'
- refresh_token: '#/components/schemas/OAuthToken-refresh_token'
+ - Homepage
responses:
+ '404':
+ description: No homepage set
'200':
description: successful operation
content:
application/json:
schema:
- type: object
- properties:
- token_type:
- type: string
- example: Bearer
- access_token:
- type: string
- example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
- description: valid for 1 day
- refresh_token:
- type: string
- example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
- description: valid for 2 weeks
- expires_in:
- type: integer
- minimum: 0
- example: 14399
- refresh_token_expires_in:
- 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: |
- ## DEPENDENCIES: jq
- API="https://peertube2.cpy.re/api/v1"
- USERNAME="<your_username>"
- PASSWORD="<your_password>"
-
- ## AUTH
- client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
- client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
- curl -s "$API/users/token" \
- --data client_id="$client_id" \
- --data client_secret="$client_secret" \
- --data grant_type=password \
- --data username="$USERNAME" \
- --data password="$PASSWORD" \
- | jq -r ".access_token"
-
- /users/revoke-token:
- post:
- summary: Logout
- description: Revokes your access token and its associated refresh token, destroying your current session.
- operationId: revokeOAuthToken
+ $ref: '#/components/schemas/CustomHomepage'
+ put:
+ summary: Set instance custom homepage
tags:
- - Session
+ - Homepage
security:
- - OAuth2: []
- responses:
- '200':
- description: successful operation
-
- /users/register:
- post:
- summary: Register a user
- operationId: registerUser
- tags:
- - Users
- - Register
- responses:
- '204':
- description: successful operation
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/RegisterUser'
- required: true
-
- /users/{id}/verify-email:
- post:
- summary: Verify a user
- operationId: verifyUser
- description: |
- Following a user registration, the new user will receive an email asking to click a link
- containing a secret.
- tags:
- - Users
- - Register
- parameters:
- - $ref: '#/components/parameters/id'
+ - OAuth2:
+ - admin
requestBody:
content:
application/json:
schema:
type: object
properties:
- verificationString:
+ content:
type: string
- format: url
- isPendingEmail:
- type: boolean
- required:
- - verificationString
+ description: content of the homepage, that will be injected in the client
responses:
'204':
description: successful operation
- '403':
- description: invalid verification string
- '404':
- description: user not found
- /users/ask-send-verify-email:
+ /api/v1/jobs/pause:
post:
- summary: Resend user verification link
- operationId: resendEmailToVerifyUser
- tags:
- - Users
- - Register
- responses:
- '204':
- description: successful operation
-
- /users/me:
- get:
- summary: Get my user information
- operationId: getUserInfo
+ summary: Pause job queue
security:
- OAuth2:
- - user
+ - admin
tags:
- - My User
+ - Job
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/User'
- put:
- summary: Update my user information
- operationId: putUserInfo
+
+ /api/v1/jobs/resume:
+ post:
+ summary: Resume job queue
security:
- OAuth2:
- - user
+ - admin
tags:
- - My User
+ - Job
responses:
'204':
description: successful operation
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/UpdateMe'
- required: true
- /users/me/videos/imports:
+ /api/v1/jobs/{state}:
get:
- summary: Get video imports of my user
+ summary: List instance jobs
+ operationId: getJobs
security:
- OAuth2:
- - user
+ - admin
tags:
- - Videos
- - My User
+ - Job
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
- -
- name: targetUrl
- in: query
- required: false
- description: Filter on import target URL
- schema:
- type: string
- -
- name: videoChannelSyncId
- in: query
- required: false
- description: Filter on imports created by a specific channel synchronization
- schema:
- type: number
- -
- name: search
- in: query
- required: false
- description: Search in video names
+ - name: state
+ in: path
+ required: true
+ description: The state of the job ('' for for no filter)
schema:
type: string
+ enum:
+ - ''
+ - active
+ - completed
+ - failed
+ - waiting
+ - delayed
+ - $ref: '#/components/parameters/jobType'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoImportsList'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ maxItems: 100
+ items:
+ $ref: '#/components/schemas/Job'
- /users/me/video-quota-used:
+ /api/v1/server/followers:
get:
- summary: Get my user used quota
- security:
- - OAuth2:
- - user
tags:
- - My User
+ - Instance Follows
+ summary: List instances following the server
+ parameters:
+ - $ref: '#/components/parameters/followState'
+ - $ref: '#/components/parameters/actorType'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
schema:
type: object
properties:
- videoQuotaUsed:
- type: number
- description: The user video quota used so far in bytes
- example: 16810141515
- videoQuotaUsedDaily:
- type: number
- description: The user video quota used today in bytes
- example: 1681014151
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
- '/users/me/videos/{videoId}/rating':
- get:
- summary: Get rate of my user for a video
+ '/api/v1/server/followers/{nameWithHost}':
+ delete:
+ summary: Remove or reject a follower to your server
security:
- - OAuth2: []
+ - OAuth2:
+ - admin
tags:
- - My User
- - Video Rates
+ - Instance Follows
parameters:
- - name: videoId
+ - name: nameWithHost
in: path
required: true
- description: The video id
+ description: The remote actor handle to remove from your followers
schema:
- $ref: '#/components/schemas/Video/properties/id'
+ type: string
+ format: email
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/GetMeVideoRating'
+ '404':
+ description: follower not found
- /users/me/videos:
- get:
- summary: Get videos of my user
+ '/api/v1/server/followers/{nameWithHost}/reject':
+ post:
+ summary: Reject a pending follower to your server
security:
- OAuth2:
- - user
+ - admin
tags:
- - My User
- - Videos
+ - Instance Follows
parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - name: nameWithHost
+ in: path
+ required: true
+ description: The remote actor handle to remove from your followers
+ schema:
+ type: string
+ format: email
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoListResponse'
+ '404':
+ description: follower not found
- /users/me/subscriptions:
- get:
- summary: Get my user subscriptions
+ '/api/v1/server/followers/{nameWithHost}/accept':
+ post:
+ summary: Accept a pending follower to your server
security:
- OAuth2:
- - user
+ - admin
tags:
- - My Subscriptions
+ - Instance Follows
+ parameters:
+ - name: nameWithHost
+ in: path
+ required: true
+ description: The remote actor handle to remove from your followers
+ schema:
+ type: string
+ format: email
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: follower not found
+
+ /api/v1/server/following:
+ get:
+ tags:
+ - Instance Follows
+ summary: List instances followed by the server
parameters:
+ - $ref: '#/components/parameters/followState'
+ - $ref: '#/components/parameters/actorType'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannelList'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
post:
- tags:
- - My Subscriptions
- summary: Add subscription to my user
security:
- OAuth2:
- - user
+ - admin
+ tags:
+ - Instance Follows
+ summary: Follow a list of actors (PeerTube instance, channel or account)
+ responses:
+ '204':
+ description: successful operation
+ '500':
+ description: cannot follow a non-HTTPS server
requestBody:
content:
application/json:
schema:
type: object
properties:
- uri:
- type: string
- format: uri
- description: uri of the video channels to subscribe to
- required:
- - uri
- examples:
- default:
- value:
- uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
- responses:
- '200':
- description: successful operation
+ hosts:
+ type: array
+ items:
+ type: string
+ format: hostname
+ uniqueItems: true
+ handles:
+ type: array
+ items:
+ type: string
+ uniqueItems: true
- /users/me/subscriptions/exist:
- get:
- summary: Get if subscriptions exist for my user
+ '/api/v1/server/following/{hostOrHandle}':
+ delete:
+ summary: Unfollow an actor (PeerTube instance, channel or account)
security:
- OAuth2:
- - user
+ - admin
tags:
- - My Subscriptions
+ - Instance Follows
parameters:
- - $ref: '#/components/parameters/subscriptionsUris'
+ - name: hostOrHandle
+ in: path
+ required: true
+ description: The hostOrHandle to unfollow
+ schema:
+ type: string
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: object
+ '404':
+ description: host or handle not found
- /users/me/subscriptions/videos:
- get:
- summary: List videos of subscriptions of my user
+ /api/v1/users:
+ post:
+ summary: Create a user
+ operationId: addUser
security:
- OAuth2:
- - user
+ - admin
tags:
- - My Subscriptions
- - Videos
- parameters:
- - $ref: '#/components/parameters/categoryOneOf'
- - $ref: '#/components/parameters/isLive'
- - $ref: '#/components/parameters/tagsOneOf'
- - $ref: '#/components/parameters/tagsAllOf'
- - $ref: '#/components/parameters/licenceOneOf'
- - $ref: '#/components/parameters/languageOneOf'
- - $ref: '#/components/parameters/nsfw'
- - $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/videosSort'
+ - Users
responses:
'200':
- description: successful operation
+ description: user created
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoListResponse'
-
- '/users/me/subscriptions/{subscriptionHandle}':
- get:
- summary: Get subscription of my user
- security:
- - OAuth2:
- - user
- tags:
- - My Subscriptions
+ $ref: '#/components/schemas/AddUserResponse'
+ links:
+ # GET /users/{id}
+ GetUser:
+ operationId: getUser
+ parameters:
+ id: '$response.body#/user/id'
+ # PUT /users/{id}
+ PutUser:
+ operationId: putUser
+ parameters:
+ id: '$response.body#/user/id'
+ # DELETE /users/{id}
+ DelUser:
+ operationId: delUser
+ parameters:
+ id: '$response.body#/user/id'
+ '403':
+ description: insufficient authority to create an admin or moderator
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AddUser'
+ description: |
+ If the smtp server is configured, you can leave the password empty and an email will be sent
+ asking the user to set it first.
+ required: true
+ get:
+ summary: List users
+ operationId: getUsers
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Users
parameters:
- - $ref: '#/components/parameters/subscriptionHandle'
+ - $ref: '#/components/parameters/usersSearch'
+ - $ref: '#/components/parameters/usersBlocked'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/usersSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannel'
+ type: array
+ items:
+ $ref: '#/components/schemas/User'
+
+ '/api/v1/users/{id}':
+ parameters:
+ - $ref: '#/components/parameters/id'
delete:
- summary: Delete subscription of my user
+ summary: Delete a user
security:
- OAuth2:
- - user
+ - admin
tags:
- - My Subscriptions
- parameters:
- - $ref: '#/components/parameters/subscriptionHandle'
+ - Users
+ operationId: delUser
responses:
- '200':
+ '204':
description: successful operation
-
- /users/me/notifications:
get:
- summary: List my notifications
+ summary: Get a user
security:
- OAuth2: []
tags:
- - My Notifications
+ - Users
+ operationId: getUser
parameters:
- - name: unread
+ - name: withStats
in: query
- description: only list unread notifications
+ description: include statistics about the user (only available as a moderator/admin)
schema:
type: boolean
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
responses:
'200':
- description: successful operation
+ x-summary: successful operation
+ description: |
+ As an admin/moderator, you can request a response augmented with statistics about the user's
+ moderation relations and videos usage, by using the `withStats` parameter.
content:
application/json:
schema:
- $ref: '#/components/schemas/NotificationListResponse'
-
- /users/me/notifications/read:
- post:
- summary: Mark notifications as read by their id
- security:
- - OAuth2: []
- tags:
- - My Notifications
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- ids:
- type: array
- description: ids of the notifications to mark as read
- items:
- type: integer
- required:
- - ids
- responses:
- '204':
- description: successful operation
-
- /users/me/notifications/read-all:
- post:
- summary: Mark all my notification as read
+ oneOf:
+ - $ref: '#/components/schemas/User'
+ - $ref: '#/components/schemas/UserWithStats'
+ put:
+ summary: Update a user
security:
- OAuth2: []
tags:
- - My Notifications
+ - Users
+ operationId: putUser
responses:
'204':
description: successful operation
-
- /users/me/notification-settings:
- put:
- summary: Update my notification settings
- security:
- - OAuth2: []
- tags:
- - My Notifications
requestBody:
content:
application/json:
schema:
- type: object
- properties:
- newVideoFromSubscription:
- $ref: '#/components/schemas/NotificationSettingValue'
- newCommentOnMyVideo:
- $ref: '#/components/schemas/NotificationSettingValue'
- abuseAsModerator:
- $ref: '#/components/schemas/NotificationSettingValue'
- videoAutoBlacklistAsModerator:
- $ref: '#/components/schemas/NotificationSettingValue'
- blacklistOnMyVideo:
- $ref: '#/components/schemas/NotificationSettingValue'
- myVideoPublished:
- $ref: '#/components/schemas/NotificationSettingValue'
- myVideoImportFinished:
- $ref: '#/components/schemas/NotificationSettingValue'
- newFollow:
- $ref: '#/components/schemas/NotificationSettingValue'
- newUserRegistration:
- $ref: '#/components/schemas/NotificationSettingValue'
- commentMention:
- $ref: '#/components/schemas/NotificationSettingValue'
- newInstanceFollower:
- $ref: '#/components/schemas/NotificationSettingValue'
- autoInstanceFollowing:
- $ref: '#/components/schemas/NotificationSettingValue'
- responses:
- '204':
- description: successful operation
+ $ref: '#/components/schemas/UpdateUser'
+ required: true
- /users/me/history/videos:
+ /api/v1/oauth-clients/local:
get:
- summary: List watched videos history
- security:
- - OAuth2: []
+ summary: Login prerequisite
+ description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
+ operationId: getOAuthClient
tags:
- - My History
- parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/search'
+ - Session
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoListResponse'
+ $ref: '#/components/schemas/OAuthClient'
+ links:
+ UseOAuthClientToLogin:
+ operationId: getOAuthToken
+ parameters:
+ client_id: '$response.body#/client_id'
+ client_secret: '$response.body#/client_secret'
+ x-codeSamples:
+ - lang: Shell
+ source: |
+ API="https://peertube2.cpy.re/api/v1"
- /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
+ ## AUTH
+ curl -s "$API/oauth-clients/local"
- /users/me/history/videos/remove:
+ /api/v1/users/token:
post:
- summary: Clear video history
- security:
- - OAuth2: []
+ summary: Login
+ operationId: getOAuthToken
+ description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
tags:
- - My History
+ - Session
requestBody:
content:
- multipart/form-data:
+ application/x-www-form-urlencoded:
schema:
- type: object
- properties:
- beforeDate:
- description: history before this date will be deleted
- type: string
- format: date-time
- responses:
- '204':
- description: successful operation
-
- /users/me/avatar/pick:
- post:
- summary: Update my user avatar
- security:
- - OAuth2: []
- tags:
- - My User
+ oneOf:
+ - $ref: '#/components/schemas/OAuthToken-password'
+ - $ref: '#/components/schemas/OAuthToken-refresh_token'
+ discriminator:
+ propertyName: grant_type
+ mapping:
+ password: '#/components/schemas/OAuthToken-password'
+ refresh_token: '#/components/schemas/OAuthToken-refresh_token'
responses:
'200':
description: successful operation
schema:
type: object
properties:
- avatars:
- type: array
- items:
- $ref: '#/components/schemas/ActorImage'
- '413':
- description: image file too large
- headers:
- X-File-Maximum-Size:
- schema:
- type: string
- format: Nginx size
- description: Maximum file size for the avatar
- requestBody:
- content:
- multipart/form-data:
- schema:
- type: object
- properties:
- avatarfile:
- description: The file to upload
- type: string
- format: binary
- encoding:
- avatarfile:
- contentType: image/png, image/jpeg
-
- /users/me/avatar:
- delete:
- summary: Delete my avatar
- security:
- - OAuth2: []
- tags:
- - My User
- responses:
- '204':
- description: successful operation
+ token_type:
+ type: string
+ example: Bearer
+ access_token:
+ type: string
+ example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
+ description: valid for 1 day
+ refresh_token:
+ type: string
+ example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
+ description: valid for 2 weeks
+ expires_in:
+ type: integer
+ minimum: 0
+ example: 14399
+ refresh_token_expires_in:
+ 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: |
+ ## DEPENDENCIES: jq
+ API="https://peertube2.cpy.re/api/v1"
+ USERNAME="<your_username>"
+ PASSWORD="<your_password>"
- /videos/ownership:
- get:
- summary: List video ownership changes
+ ## AUTH
+ client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+ client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+ curl -s "$API/users/token" \
+ --data client_id="$client_id" \
+ --data client_secret="$client_secret" \
+ --data grant_type=password \
+ --data username="$USERNAME" \
+ --data password="$PASSWORD" \
+ | jq -r ".access_token"
+
+ /api/v1/users/revoke-token:
+ post:
+ summary: Logout
+ description: Revokes your access token and its associated refresh token, destroying your current session.
+ operationId: revokeOAuthToken
tags:
- - Video Ownership Change
+ - Session
security:
- OAuth2: []
responses:
'200':
description: successful operation
- '/videos/ownership/{id}/accept':
+ /api/v1/users/ask-send-verify-email:
post:
- summary: Accept ownership change request
+ summary: Resend user verification link
+ operationId: resendEmailToVerifyUser
tags:
- - Video Ownership Change
- security:
- - OAuth2: []
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - Users
+ - Register
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ description: User email
responses:
'204':
description: successful operation
- '403':
- description: cannot terminate an ownership change of another user
- '404':
- description: video ownership change not found
- '/videos/ownership/{id}/refuse':
+ /api/v1/users/registrations/ask-send-verify-email:
post:
- summary: Refuse ownership change request
+ summary: Resend verification link to registration email
+ operationId: resendEmailToVerifyRegistration
tags:
- - Video Ownership Change
- security:
- - OAuth2: []
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - Register
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ description: Registration email
responses:
'204':
description: successful operation
- '403':
- description: cannot terminate an ownership change of another user
- '404':
- description: video ownership change not found
- '/videos/{id}/give-ownership':
+ /api/v1/users/{id}/verify-email:
post:
- summary: Request ownership change
+ summary: Verify a user
+ operationId: verifyUser
+ description: |
+ Following a user registration, the new user will receive an email asking to click a link
+ containing a secret.
+ This endpoint can also be used to verify a new email set in the user account.
tags:
- - Video Ownership Change
- security:
- - OAuth2: []
+ - Users
+ - Register
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/id'
requestBody:
- required: true
content:
- application/x-www-form-urlencoded:
+ application/json:
schema:
type: object
properties:
- username:
+ verificationString:
type: string
+ format: url
+ isPendingEmail:
+ type: boolean
required:
- - username
+ - verificationString
responses:
'204':
description: successful operation
- '400':
- description: changing video ownership to a remote account is not supported yet
+ '403':
+ description: invalid verification string
'404':
- description: video not found
+ description: user not found
- /videos/{id}/studio/edit:
+ /api/v1/users/registrations/{registrationId}/verify-email:
post:
- summary: Create a studio task
+ summary: Verify a registration email
+ operationId: verifyRegistrationEmail
+ description: |
+ Following a user registration request, the user will receive an email asking to click a link
+ containing a secret.
tags:
- - Video Transcoding
- - Video
- description: Create a task to edit a video (cut, add intro/outro etc)
- security:
- - OAuth2: []
+ - Register
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/registrationId'
requestBody:
- required: true
content:
- application/x-www-form-urlencoded:
+ application/json:
schema:
- $ref: '#/components/schemas/VideoStudioCreateTask'
+ type: object
+ properties:
+ verificationString:
+ type: string
+ format: url
+ required:
+ - verificationString
responses:
'204':
description: successful operation
- '400':
- description: incorrect parameters
+ '403':
+ description: invalid verification string
'404':
- description: video not found
+ description: registration not found
- /videos:
- get:
- summary: List videos
- operationId: getVideos
+ /api/v1/users/{id}/two-factor/request:
+ post:
+ summary: Request two factor auth
+ operationId: requestTwoFactor
+ description: Request two factor authentication for a user
tags:
- - Video
+ - Users
parameters:
- - $ref: '#/components/parameters/categoryOneOf'
- - $ref: '#/components/parameters/isLive'
- - $ref: '#/components/parameters/tagsOneOf'
- - $ref: '#/components/parameters/tagsAllOf'
- - $ref: '#/components/parameters/licenceOneOf'
- - $ref: '#/components/parameters/languageOneOf'
- - $ref: '#/components/parameters/nsfw'
- - $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/videosSort'
+ - $ref: '#/components/parameters/id'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ currentPassword:
+ type: string
+ description: Password of the currently authenticated user
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoListResponse'
+ type: array
+ items:
+ $ref: '#/components/schemas/RequestTwoFactorResponse'
+ '403':
+ description: invalid password
+ '404':
+ description: user not found
- /videos/categories:
- get:
- summary: List available video categories
- operationId: getCategories
+ /api/v1/users/{id}/two-factor/confirm-request:
+ post:
+ summary: Confirm two factor auth
+ operationId: confirmTwoFactorRequest
+ description: Confirm a two factor authentication request
tags:
- - Video
+ - Users
+ parameters:
+ - $ref: '#/components/parameters/id'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ requestToken:
+ type: string
+ description: Token to identify the two factor request
+ otpToken:
+ type: string
+ description: OTP token generated by the app
+ required:
+ - requestToken
+ - otpToken
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
+ '403':
+ description: invalid request token or OTP token
+ '404':
+ description: user not found
+
+ /api/v1/users/{id}/two-factor/disable:
+ post:
+ summary: Disable two factor auth
+ operationId: disableTwoFactor
+ description: Disable two factor authentication of a user
+ tags:
+ - Users
+ parameters:
+ - $ref: '#/components/parameters/id'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ currentPassword:
type: string
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/api/v1/videos/categories
+ description: Password of the currently authenticated user
+ responses:
+ '204':
+ description: successful operation
+ '403':
+ description: invalid password
+ '404':
+ description: user not found
- /videos/licences:
+ /api/v1/users/me:
get:
- summary: List available video licences
- operationId: getLicences
+ summary: Get my user information
+ operationId: getUserInfo
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
+ - My User
responses:
'200':
description: successful operation
schema:
type: array
items:
- type: string
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/api/v1/videos/licences
-
- /videos/languages:
- get:
- summary: List available video languages
- operationId: getLanguages
+ $ref: '#/components/schemas/User'
+ put:
+ summary: Update my user information
+ operationId: putUserInfo
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
+ - My User
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- type: string
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/api/v1/videos/languages
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UpdateMe'
+ required: true
- /videos/privacies:
+ /api/v1/users/me/videos/imports:
get:
- summary: List available video privacy policies
- operationId: getPrivacyPolicies
+ summary: Get video imports of my user
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
+ - Videos
+ - My User
+ parameters:
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
+ -
+ name: targetUrl
+ in: query
+ required: false
+ description: Filter on import target URL
+ schema:
+ type: string
+ -
+ name: videoChannelSyncId
+ in: query
+ required: false
+ description: Filter on imports created by a specific channel synchronization
+ schema:
+ type: number
+ -
+ name: search
+ in: query
+ required: false
+ description: Search in video names
+ schema:
+ type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- type: string
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
+ $ref: '#/components/schemas/VideoImportsList'
- '/videos/{id}':
- put:
- summary: Update a video
- operationId: putVideo
- security:
- - OAuth2: []
- tags:
- - Video
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- responses:
- '204':
- description: successful operation
- requestBody:
- content:
- multipart/form-data:
- schema:
- type: object
- properties:
- thumbnailfile:
- description: Video thumbnail file
- type: string
- format: binary
- previewfile:
- description: Video preview file
- type: string
- format: binary
- category:
- $ref: '#/components/schemas/VideoCategorySet'
- licence:
- $ref: '#/components/schemas/VideoLicenceSet'
- language:
- $ref: '#/components/schemas/VideoLanguageSet'
- privacy:
- $ref: '#/components/schemas/VideoPrivacySet'
- description:
- description: Video description
- type: string
- waitTranscoding:
- description: Whether or not we wait transcoding before publish the video
- type: string
- support:
- description: A text tell the audience how to support the video creator
- example: Please support our work on https://soutenir.framasoft.org/en/ <3
- type: string
- nsfw:
- description: Whether or not this video contains sensitive content
- type: boolean
- name:
- description: Video name
- type: string
- minLength: 3
- maxLength: 120
- tags:
- description: Video tags (maximum 5 tags each between 2 and 30 characters)
- type: array
- minItems: 1
- maxItems: 5
- items:
- type: string
- minLength: 2
- maxLength: 30
- commentsEnabled:
- description: Enable or disable comments for this video
- type: boolean
- downloadEnabled:
- description: Enable or disable downloading for this video
- type: boolean
- originallyPublishedAt:
- description: Date when the content was originally published
- type: string
- format: date-time
- scheduleUpdate:
- $ref: '#/components/schemas/VideoScheduledUpdate'
- encoding:
- thumbnailfile:
- contentType: image/jpeg
- previewfile:
- contentType: image/jpeg
+ /api/v1/users/me/video-quota-used:
get:
- summary: Get a video
- operationId: getVideo
+ summary: Get my user used quota
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - My User
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoDetails'
- delete:
- summary: Delete a video
- operationId: delVideo
+ type: object
+ properties:
+ videoQuotaUsed:
+ type: number
+ description: The user video quota used so far in bytes
+ example: 16810141515
+ videoQuotaUsedDaily:
+ type: number
+ description: The user video quota used today in bytes
+ example: 1681014151
+
+ '/api/v1/users/me/videos/{videoId}/rating':
+ get:
+ summary: Get rate of my user for a video
security:
- OAuth2: []
tags:
- - Video
+ - My User
+ - Video Rates
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - name: videoId
+ in: path
+ required: true
+ description: The video id
+ schema:
+ $ref: '#/components/schemas/Video/properties/id'
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GetMeVideoRating'
- '/videos/{id}/description':
+ /api/v1/users/me/videos:
get:
- summary: Get complete video description
- operationId: getVideoDesc
+ summary: Get videos of my user
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
+ - My User
+ - Videos
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- nullable: true
- type: string
- minLength: 3
- maxLength: 10000
- 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)**
+ $ref: '#/components/schemas/VideoListResponse'
- '/videos/{id}/source':
- post:
- summary: Get video source file metadata
- operationId: getVideoSource
+ /api/v1/users/me/subscriptions:
+ get:
+ summary: Get my user subscriptions
+ security:
+ - OAuth2:
+ - user
tags:
- - Video
+ - My Subscriptions
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoSource'
-
- '/videos/{id}/views':
+ $ref: '#/components/schemas/VideoChannelList'
post:
- 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'
+ - My Subscriptions
+ summary: Add subscription to my user
+ security:
+ - OAuth2:
+ - user
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/UserViewingVideo'
- required: true
+ type: object
+ properties:
+ uri:
+ type: string
+ format: uri
+ description: uri of the video channels to subscribe to
+ required:
+ - uri
+ examples:
+ default:
+ value:
+ uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
responses:
- '204':
+ '200':
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
+ /api/v1/users/me/subscriptions/exist:
+ get:
+ summary: Get if subscriptions exist for my user
security:
- - OAuth2: []
+ - OAuth2:
+ - user
+ tags:
+ - My Subscriptions
parameters:
- - $ref: '#/components/parameters/idOrUUID'
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/UserViewingVideo'
- required: true
+ - $ref: '#/components/parameters/subscriptionsUris'
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
- '/videos/{id}/stats/overall':
+ /api/v1/users/me/subscriptions/videos:
get:
- summary: Get overall stats of a video
- tags:
- - Video Stats
+ summary: List videos of subscriptions of my user
security:
- - OAuth2: []
+ - OAuth2:
+ - user
+ tags:
+ - My Subscriptions
+ - Videos
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
+ - $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
+ - $ref: '#/components/parameters/tagsOneOf'
+ - $ref: '#/components/parameters/tagsAllOf'
+ - $ref: '#/components/parameters/licenceOneOf'
+ - $ref: '#/components/parameters/languageOneOf'
+ - $ref: '#/components/parameters/nsfw'
+ - $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/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoStatsOverall'
+ $ref: '#/components/schemas/VideoListResponse'
- '/videos/{id}/stats/retention':
+ '/api/v1/users/me/subscriptions/{subscriptionHandle}':
get:
- summary: Get retention stats of a video
- tags:
- - Video Stats
+ summary: Get subscription of my user
security:
- - OAuth2: []
+ - OAuth2:
+ - user
+ tags:
+ - My Subscriptions
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/subscriptionHandle'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoStatsRetention'
+ $ref: '#/components/schemas/VideoChannel'
+ delete:
+ summary: Delete subscription of my user
+ security:
+ - OAuth2:
+ - user
+ tags:
+ - My Subscriptions
+ parameters:
+ - $ref: '#/components/parameters/subscriptionHandle'
+ responses:
+ '200':
+ description: successful operation
- '/videos/{id}/stats/timeseries/{metric}':
+ /api/v1/users/me/notifications:
get:
- summary: Get timeserie stats of a video
- tags:
- - Video Stats
+ summary: List my notifications
security:
- OAuth2: []
+ tags:
+ - My Notifications
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
+ - name: unread
in: query
- description: Filter stats by end date
+ description: only list unread notifications
schema:
- type: string
- format: date-time
+ type: boolean
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoStatsTimeserie'
+ $ref: '#/components/schemas/NotificationListResponse'
- /videos/upload:
+ /api/v1/users/me/notifications/read:
post:
- summary: Upload a video
- description: Uses a single request to upload a video.
- operationId: uploadLegacy
+ summary: Mark notifications as read by their id
security:
- OAuth2: []
tags:
- - Video
- - Video Upload
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoUploadResponse'
- '403':
- description: video didn't pass upload filter
- '408':
- description: upload has timed out
- '413':
- 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 whether daily or global
- headers:
- X-File-Maximum-Size:
- schema:
- type: string
- format: Nginx size
- description: Maximum file size for the video
- '415':
- description: video type unsupported
- '422':
- description: video unreadable
+ - My Notifications
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
- $ref: '#/components/schemas/VideoUploadRequestLegacy'
- encoding:
- videofile:
- contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
- thumbnailfile:
- contentType: image/jpeg
- previewfile:
- contentType: image/jpeg
- x-codeSamples:
- - lang: Shell
- source: |
- ## DEPENDENCIES: jq
- USERNAME="<your_username>"
- PASSWORD="<your_password>"
- FILE_PATH="<your_file_path>"
- CHANNEL_ID="<your_channel_id>"
- NAME="<video_name>"
- API="https://peertube2.cpy.re/api/v1"
-
- ## AUTH
- client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
- client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
- token=$(curl -s "$API/users/token" \
- --data client_id="$client_id" \
- --data client_secret="$client_secret" \
- --data grant_type=password \
- --data username="$USERNAME" \
- --data password="$PASSWORD" \
- | jq -r ".access_token")
-
- ## VIDEO UPLOAD
- curl -s "$API/videos/upload" \
- -H "Authorization: Bearer $token" \
- --max-time 600 \
- --form videofile=@"$FILE_PATH" \
- --form channelId=$CHANNEL_ID \
- --form name="$NAME"
+ type: object
+ properties:
+ ids:
+ type: array
+ description: ids of the notifications to mark as read
+ items:
+ type: integer
+ required:
+ - ids
+ responses:
+ '204':
+ description: successful operation
- /videos/upload-resumable:
+ /api/v1/users/me/notifications/read-all:
post:
- summary: Initialize the resumable upload of a video
- description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
- operationId: uploadResumableInit
+ summary: Mark all my notification as read
security:
- OAuth2: []
tags:
- - Video
- - Video Upload
- parameters:
- - name: X-Upload-Content-Length
- in: header
- schema:
- type: number
- example: 2469036
- required: true
- description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
- - name: X-Upload-Content-Type
- in: header
- schema:
- type: string
- format: mimetype
- example: video/mp4
- required: true
- description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
+ - My Notifications
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/users/me/notification-settings:
+ put:
+ summary: Update my notification settings
+ security:
+ - OAuth2: []
+ tags:
+ - My Notifications
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoUploadRequestResumable'
- responses:
- '200':
- description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
- '201':
- description: created
- headers:
- Location:
- schema:
- type: string
- format: url
- example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
- Content-Length:
- schema:
- type: number
- example: 0
- '413':
- 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:
- summary: Send chunk for the resumable upload of a video
- description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
- operationId: uploadResumable
+ type: object
+ properties:
+ newVideoFromSubscription:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ newCommentOnMyVideo:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ abuseAsModerator:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ videoAutoBlacklistAsModerator:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ blacklistOnMyVideo:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ myVideoPublished:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ myVideoImportFinished:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ newFollow:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ newUserRegistration:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ commentMention:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ newInstanceFollower:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ autoInstanceFollowing:
+ $ref: '#/components/schemas/NotificationSettingValue'
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/users/me/history/videos:
+ get:
+ summary: List watched videos history
security:
- OAuth2: []
tags:
- - Video
- - Video Upload
+ - My History
parameters:
- - name: upload_id
- in: query
- required: true
- description: |
- 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
- - name: Content-Range
- in: header
- schema:
- type: string
- example: bytes 0-262143/2469036
- required: true
- description: |
- Specifies the bytes in the file that the request is uploading.
-
- For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
- 262144 bytes (256 x 1024) in a 2,469,036 byte file.
- - name: Content-Length
- in: header
- schema:
- type: number
- example: 262144
- required: true
- description: |
- Size of the chunk that the request is sending.
-
- 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:
- content:
- application/octet-stream:
- schema:
- type: string
- format: binary
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/search'
responses:
'200':
- description: last chunk received
- headers:
- Content-Length:
- schema:
- type: number
+ description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoUploadResponse'
- '308':
- description: resume incomplete
- headers:
- Range:
- schema:
- type: string
- example: bytes=0-262143
- Content-Length:
- schema:
- type: number
- example: 0
- '403':
- description: video didn't pass upload filter
- '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
+ $ref: '#/components/schemas/VideoListResponse'
+
+ /api/v1/users/me/history/videos/{videoId}:
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
- operationId: uploadResumableCancel
+ summary: Delete history element
security:
- OAuth2: []
tags:
- - Video
- - Video Upload
+ - My History
parameters:
- - name: upload_id
- in: query
- required: true
- description: |
- Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
- not valid anymore and the upload session has already been deleted with its data ;-)
- schema:
- type: string
- - name: Content-Length
- in: header
+ - name: videoId
+ in: path
required: true
schema:
- type: number
- example: 0
+ $ref: '#/components/schemas/Video/properties/id'
responses:
'204':
- description: upload cancelled
- headers:
- Content-Length:
- schema:
- type: number
- example: 0
- '404':
- description: upload not found
+ description: successful operation
- /videos/imports:
+ /api/v1/users/me/history/videos/remove:
post:
- summary: Import a video
- description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
- operationId: importVideo
+ summary: Clear video history
security:
- OAuth2: []
tags:
- - Video Imports
- - Video Upload
+ - My History
requestBody:
content:
multipart/form-data:
schema:
- $ref: '#/components/schemas/VideoCreateImport'
- encoding:
- torrentfile:
- contentType: application/x-bittorrent
- thumbnailfile:
- contentType: image/jpeg
- previewfile:
- contentType: image/jpeg
+ type: object
+ properties:
+ beforeDate:
+ description: history before this date will be deleted
+ type: string
+ format: date-time
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoUploadResponse'
- '400':
- description: '`magnetUri` or `targetUrl` or a torrent file missing'
- '403':
- description: video didn't pass pre-import filter
- '409':
- description: HTTP or Torrent/magnetURI import not enabled
- /videos/imports/{id}/cancel:
+ /api/v1/users/me/avatar/pick:
post:
- summary: Cancel video import
- description: Cancel a pending video import
+ summary: Update my user avatar
security:
- OAuth2: []
tags:
- - Video Imports
- parameters:
- - $ref: '#/components/parameters/id'
+ - My User
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
+ '413':
+ description: image file too large
+ headers:
+ X-File-Maximum-Size:
+ schema:
+ type: string
+ format: Nginx size
+ description: Maximum file size for the avatar
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ avatarfile:
+ description: The file to upload
+ type: string
+ format: binary
+ encoding:
+ avatarfile:
+ contentType: image/png, image/jpeg
- /videos/imports/{id}:
+ /api/v1/users/me/avatar:
delete:
- summary: Delete video import
- description: Delete ended video import
+ summary: Delete my avatar
security:
- OAuth2: []
tags:
- - Video Imports
- parameters:
- - $ref: '#/components/parameters/id'
+ - My User
responses:
'204':
description: successful operation
- /videos/live:
+ /api/v1/users/register:
post:
- summary: Create a live
- operationId: addLive
- security:
- - OAuth2: []
+ summary: Register a user
+ operationId: registerUser
+ description: Signup has to be enabled and signup approval is not required
tags:
- - Live Videos
- - Video
+ - Register
responses:
- '200':
+ '204':
description: successful operation
- content:
- 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
+ description: request error
'403':
- 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
+ description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
+ '409':
+ description: 'a user with this username, channel name or email already exists'
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
- type: object
- properties:
- channelId:
- description: Channel id that will contain this live video
- type: integer
- 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'
- thumbnailfile:
- description: Live video/replay thumbnail file
- type: string
- format: binary
- previewfile:
- description: Live video/replay preview file
- type: string
- format: binary
- privacy:
- $ref: '#/components/schemas/VideoPrivacySet'
- category:
- $ref: '#/components/schemas/VideoCategorySet'
- licence:
- $ref: '#/components/schemas/VideoLicenceSet'
- language:
- $ref: '#/components/schemas/VideoLanguageSet'
- description:
- description: Live video/replay description
- type: string
- support:
- description: A text tell the audience how to support the creator
- example: Please support our work on https://soutenir.framasoft.org/en/ <3
- type: string
- nsfw:
- description: Whether or not this live video/replay contains sensitive content
- type: boolean
- name:
- description: Live video/replay name
- type: string
- minLength: 3
- maxLength: 120
- tags:
- description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
- type: array
- minItems: 1
- maxItems: 5
- items:
- type: string
- minLength: 2
- maxLength: 30
- commentsEnabled:
- description: Enable or disable comments for this live video/replay
- type: boolean
- downloadEnabled:
- description: Enable or disable downloading for the replay of this live video
- type: boolean
- required:
- - channelId
- - name
- encoding:
- thumbnailfile:
- contentType: image/jpeg
- previewfile:
- contentType: image/jpeg
+ $ref: '#/components/schemas/RegisterUser'
+ required: true
- /videos/live/{id}:
- get:
- summary: Get information about a live
- operationId: getLiveId
- security:
- - OAuth2: []
+ /api/v1/users/registrations/request:
+ post:
+ summary: Request registration
+ description: Signup has to be enabled and require approval on the instance
+ operationId: requestRegistration
tags:
- - Live Videos
- - Video
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - Register
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/LiveVideoResponse'
- put:
- summary: Update information about a live
- operationId: updateLiveId
+ $ref: '#/components/schemas/UserRegistration'
+ '400':
+ description: request error or signup approval is not enabled on the instance
+ '403':
+ description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
+ '409':
+ description: 'a user or registration with this username, channel name or email already exists'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistrationRequest'
+
+ /api/v1/users/registrations/{registrationId}/accept:
+ post:
security:
- - OAuth2: []
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Accept registration
+ operationId: acceptRegistration
tags:
- - Live Videos
- - Video
+ - Register
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/registrationId'
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/LiveVideoUpdate'
+ $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
responses:
'204':
description: successful operation
- '400':
- 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
+
+ /api/v1/users/registrations/{registrationId}/reject:
+ post:
security:
- - OAuth2: []
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Reject registration
+ operationId: rejectRegistration
tags:
- - Live Videos
+ - Register
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/registrationId'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/LiveVideoSessionResponse'
- /users/me/abuses:
- get:
- summary: List my abuses
- operationId: getMyAbuses
+ /api/v1/users/registrations/{registrationId}:
+ delete:
security:
- - OAuth2: []
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Delete registration
+ description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
+ operationId: deleteRegistration
tags:
- - Abuses
- - My User
+ - Register
parameters:
- - name: id
- in: query
- description: only list the report with this id
- schema:
- type: integer
- - name: state
- in: query
- schema:
- $ref: '#/components/schemas/AbuseStateSet'
- - $ref: '#/components/parameters/abusesSort'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/registrationId'
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- items:
- $ref: '#/components/schemas/Abuse'
- /abuses:
+ /api/v1/users/registrations:
get:
- summary: List abuses
- operationId: getAbuses
security:
- OAuth2:
- admin
- moderator
+ summary: List registrations
+ operationId: listRegistrations
tags:
- - Abuses
+ - Register
parameters:
- - name: id
- in: query
- description: only list the report with this id
- schema:
- type: integer
- - name: predefinedReason
- in: query
- description: predefined reason the listed reports should contain
- schema:
- $ref: '#/components/schemas/PredefinedAbuseReasons'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
- name: search
in: query
- description: plain search that will match with video titles, reporter names and more
- schema:
- type: string
- - name: state
- in: query
- schema:
- $ref: '#/components/schemas/AbuseStateSet'
- - name: searchReporter
- in: query
- description: only list reports of a specific reporter
- schema:
- type: string
- - name: searchReportee
- description: only list reports of a specific reportee
- in: query
- schema:
- type: string
- - name: searchVideo
- in: query
- description: only list reports of a specific video
- schema:
- type: string
- - name: searchVideoChannel
- in: query
- description: only list reports of a specific video channel
- schema:
- type: string
- - name: videoIs
- in: query
- description: only list deleted or blocklisted videos
+ required: false
schema:
type: string
- enum:
- - 'deleted'
- - 'blacklisted'
- - name: filter
+ - name: sort
in: query
- description: only list account, comment or video reports
+ required: false
schema:
type: string
enum:
- - 'video'
- - 'comment'
- - 'account'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/abusesSort'
+ - -createdAt
+ - createdAt
+ - state
+ - -state
responses:
- '200':
+ '204':
description: successful operation
- content:
- application/json:
- schema:
- type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- items:
- $ref: '#/components/schemas/Abuse'
- post:
- summary: Report an abuse
+
+ /api/v1/videos/ownership:
+ get:
+ summary: List video ownership changes
+ tags:
+ - Video Ownership Change
security:
- OAuth2: []
- tags:
- - Abuses
- requestBody:
- required: true
- content:
- application/json:
- schema:
- type: object
- properties:
- reason:
- description: Reason why the user reports this video
- type: string
- minLength: 2
- maxLength: 3000
- predefinedReasons:
- $ref: '#/components/schemas/PredefinedAbuseReasons'
- video:
- type: object
- properties:
- id:
- description: Video id to report
- allOf:
- - $ref: '#/components/schemas/Video/properties/id'
- startAt:
- type: integer
- format: seconds
- description: Timestamp in the video that marks the beginning of the report
- minimum: 0
- endAt:
- type: integer
- format: seconds
- description: Timestamp in the video that marks the ending of the report
- minimum: 0
- comment:
- type: object
- properties:
- id:
- description: Comment id to report
- allOf:
- - $ref: '#/components/schemas/VideoComment/properties/id'
- account:
- type: object
- properties:
- id:
- description: Account id to report
- type: integer
- required:
- - reason
responses:
'200':
description: successful operation
- content:
- application/json:
- schema:
- type: object
- properties:
- abuse:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/id'
- '400':
- description: incorrect request parameters
- '/abuses/{abuseId}':
- put:
- summary: Update an abuse
- security:
- - OAuth2:
- - admin
- - moderator
+ '/api/v1/videos/ownership/{id}/accept':
+ post:
+ summary: Accept ownership change request
tags:
- - Abuses
+ - Video Ownership Change
+ security:
+ - OAuth2: []
parameters:
- - $ref: '#/components/parameters/abuseId'
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- state:
- $ref: '#/components/schemas/AbuseStateSet'
- moderationComment:
- type: string
- description: Update the report comment visible only to the moderation team
- minLength: 2
- maxLength: 3000
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
+ '403':
+ description: cannot terminate an ownership change of another user
'404':
- description: abuse not found
- delete:
+ description: video ownership change not found
+
+ '/api/v1/videos/ownership/{id}/refuse':
+ post:
+ summary: Refuse ownership change request
tags:
- - Abuses
- summary: Delete an abuse
+ - Video Ownership Change
security:
- - OAuth2:
- - admin
- - moderator
+ - OAuth2: []
parameters:
- - $ref: '#/components/parameters/abuseId'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
+ '403':
+ description: cannot terminate an ownership change of another user
'404':
- description: block not found
+ description: video ownership change not found
- '/abuses/{abuseId}/messages':
- get:
- summary: List messages of an abuse
- security:
- - OAuth2: []
- tags:
- - Abuses
- parameters:
- - $ref: '#/components/parameters/abuseId'
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- items:
- $ref: '#/components/schemas/AbuseMessage'
+ '/api/v1/videos/{id}/give-ownership':
post:
- summary: Add message to an abuse
+ summary: Request ownership change
+ tags:
+ - Video Ownership Change
security:
- OAuth2: []
- tags:
- - Abuses
parameters:
- - $ref: '#/components/parameters/abuseId'
+ - $ref: '#/components/parameters/idOrUUID'
requestBody:
required: true
content:
- application/json:
+ application/x-www-form-urlencoded:
schema:
type: object
properties:
- message:
- description: Message to send
+ username:
type: string
- minLength: 2
- maxLength: 3000
required:
- - message
+ - username
responses:
- '200':
+ '204':
description: successful operation
'400':
- description: incorrect request parameters
+ description: changing video ownership to a remote account is not supported yet
+ '404':
+ description: video not found
- '/abuses/{abuseId}/messages/{abuseMessageId}':
- delete:
- summary: Delete an abuse message
+ '/api/v1/videos/{id}/token':
+ post:
+ summary: Request video token
+ operationId: requestVideoToken
+ description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
+ tags:
+ - Video
security:
- OAuth2: []
- tags:
- - Abuses
parameters:
- - $ref: '#/components/parameters/abuseId'
- - $ref: '#/components/parameters/abuseMessageId'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoTokenResponse'
+ '400':
+ description: incorrect parameters
+ '404':
+ description: video not found
- '/videos/{id}/blacklist':
+ /api/v1/videos/{id}/studio/edit:
post:
- summary: Block a video
- operationId: addVideoBlock
- security:
- - OAuth2:
- - admin
- - moderator
+ summary: Create a studio task
tags:
- - Video Blocks
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- responses:
- '204':
- description: successful operation
- delete:
- summary: Unblock a video by its id
- operationId: delVideoBlock
+ - Video Transcoding
+ - Video
+ description: Create a task to edit a video (cut, add intro/outro etc)
security:
- - OAuth2:
- - admin
- - moderator
- tags:
- - Video Blocks
+ - OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ required: true
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ $ref: '#/components/schemas/VideoStudioCreateTask'
responses:
'204':
description: successful operation
+ '400':
+ description: incorrect parameters
'404':
- description: block not found
+ description: video not found
- /videos/blacklist:
+ /api/v1/videos:
get:
+ summary: List videos
+ operationId: getVideos
tags:
- - Video Blocks
- summary: List video blocks
- operationId: getVideoBlocks
- security:
- - OAuth2:
- - admin
- - moderator
+ - Video
parameters:
- - name: type
- in: query
- description: >
- list only blocks that match this type:
-
- - `1`: manual block
-
- - `2`: automatic block that needs review
- schema:
- type: integer
- enum:
- - 1
- - 2
- - name: search
- in: query
- description: plain search that will match with video titles, and more
- schema:
- type: string
+ - $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
+ - $ref: '#/components/parameters/tagsOneOf'
+ - $ref: '#/components/parameters/tagsAllOf'
+ - $ref: '#/components/parameters/licenceOneOf'
+ - $ref: '#/components/parameters/languageOneOf'
+ - $ref: '#/components/parameters/nsfw'
+ - $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/blacklistsSort'
+ - $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- items:
- $ref: '#/components/schemas/VideoBlacklist'
+ $ref: '#/components/schemas/VideoListResponse'
- /videos/{id}/captions:
+ /api/v1/videos/categories:
get:
- summary: List captions of a video
- operationId: getVideoCaptions
+ summary: List available video categories
+ operationId: getCategories
tags:
- - Video Captions
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: object
- properties:
- total:
- type: integer
- example: 1
- data:
- type: array
- items:
- $ref: '#/components/schemas/VideoCaption'
-
- /videos/{id}/captions/{captionLanguage}:
- put:
- summary: Add or replace a video caption
- operationId: addVideoCaption
- security:
- - OAuth2:
- - user
- tags:
- - Video Captions
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- - $ref: '#/components/parameters/captionLanguage'
- requestBody:
- content:
- multipart/form-data:
- schema:
- type: object
- properties:
- captionfile:
- description: The file to upload.
+ type: array
+ items:
type: string
- format: binary
- encoding:
- captionfile:
- contentType: text/vtt, application/x-subrip, text/plain
- responses:
- '204':
- description: successful operation
- '404':
- description: video or language not found
- delete:
- summary: Delete a video caption
- operationId: delVideoCaption
- security:
- - OAuth2:
- - user
- tags:
- - Video Captions
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- - $ref: '#/components/parameters/captionLanguage'
- responses:
- '204':
- description: successful operation
- '404':
- description: video or language or caption for that language not found
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/categories
- /video-channels:
+ /api/v1/videos/licences:
get:
- summary: List video channels
- operationId: getVideoChannels
+ summary: List available video licences
+ operationId: getLicences
tags:
- - Video Channels
- parameters:
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/sort'
+ - Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannelList'
- post:
- summary: Create a video channel
- operationId: addVideoChannel
- security:
- - OAuth2: []
+ type: array
+ items:
+ type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/licences
+
+ /api/v1/videos/languages:
+ get:
+ summary: List available video languages
+ operationId: getLanguages
tags:
- - Video Channels
+ - Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: object
- properties:
- videoChannel:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/id'
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoChannelCreate'
+ type: array
+ items:
+ type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/languages
- '/video-channels/{channelHandle}':
+ /api/v1/videos/privacies:
get:
- summary: Get a video channel
- operationId: getVideoChannel
+ summary: List available video privacy policies
+ operationId: getPrivacyPolicies
tags:
- - Video Channels
- parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoChannel'
+ type: array
+ items:
+ type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
+
+ '/api/v1/videos/{id}':
put:
- summary: Update a video channel
- operationId: putVideoChannel
+ summary: Update a video
+ operationId: putVideo
security:
- OAuth2: []
tags:
- - Video Channels
+ - Video
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
requestBody:
content:
- application/json:
+ multipart/form-data:
schema:
- $ref: '#/components/schemas/VideoChannelUpdate'
+ type: object
+ properties:
+ thumbnailfile:
+ description: Video thumbnail file
+ type: string
+ format: binary
+ previewfile:
+ description: Video preview file
+ type: string
+ format: binary
+ category:
+ $ref: '#/components/schemas/VideoCategorySet'
+ licence:
+ $ref: '#/components/schemas/VideoLicenceSet'
+ language:
+ $ref: '#/components/schemas/VideoLanguageSet'
+ privacy:
+ $ref: '#/components/schemas/VideoPrivacySet'
+ description:
+ description: Video description
+ type: string
+ waitTranscoding:
+ description: Whether or not we wait transcoding before publish the video
+ type: string
+ support:
+ description: A text tell the audience how to support the video creator
+ example: Please support our work on https://soutenir.framasoft.org/en/ <3
+ type: string
+ nsfw:
+ description: Whether or not this video contains sensitive content
+ type: boolean
+ name:
+ description: Video name
+ type: string
+ minLength: 3
+ maxLength: 120
+ tags:
+ description: Video tags (maximum 5 tags each between 2 and 30 characters)
+ type: array
+ minItems: 1
+ maxItems: 5
+ items:
+ type: string
+ minLength: 2
+ maxLength: 30
+ commentsEnabled:
+ description: Enable or disable comments for this video
+ type: boolean
+ downloadEnabled:
+ description: Enable or disable downloading for this video
+ type: boolean
+ originallyPublishedAt:
+ description: Date when the content was originally published
+ type: string
+ format: date-time
+ scheduleUpdate:
+ $ref: '#/components/schemas/VideoScheduledUpdate'
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
+ previewfile:
+ contentType: image/jpeg
+ get:
+ summary: Get a video
+ operationId: getVideo
+ tags:
+ - Video
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoDetails'
delete:
- summary: Delete a video channel
- operationId: delVideoChannel
+ summary: Delete a video
+ operationId: delVideo
security:
- OAuth2: []
tags:
- - Video Channels
+ - Video
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
- '/video-channels/{channelHandle}/videos':
+ '/api/v1/videos/{id}/description':
get:
- summary: List videos of a video channel
- operationId: getVideoChannelVideos
+ summary: Get complete video description
+ operationId: getVideoDesc
tags:
- Video
- - Video Channels
parameters:
- - $ref: '#/components/parameters/channelHandle'
- - $ref: '#/components/parameters/categoryOneOf'
- - $ref: '#/components/parameters/isLive'
- - $ref: '#/components/parameters/tagsOneOf'
- - $ref: '#/components/parameters/tagsAllOf'
- - $ref: '#/components/parameters/licenceOneOf'
- - $ref: '#/components/parameters/languageOneOf'
- - $ref: '#/components/parameters/nsfw'
- - $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/videosSort'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoListResponse'
+ nullable: true
+ type: string
+ minLength: 3
+ maxLength: 10000
+ 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)**
- '/video-channels/{channelHandle}/followers':
- get:
+ '/api/v1/videos/{id}/source':
+ post:
+ summary: Get video source file metadata
+ operationId: getVideoSource
tags:
- - Video Channels
- summary: 'List followers of a video channel'
- security:
- - OAuth2: []
- operationId: getVideoChannelFollowers
+ - Video
parameters:
- - $ref: '#/components/parameters/channelHandle'
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/followersSort'
- - $ref: '#/components/parameters/search'
+ - $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/Follow'
+ $ref: '#/components/schemas/VideoSource'
- '/video-channels/{channelHandle}/avatar/pick':
+ '/api/v1/videos/{id}/views':
post:
- summary: Update channel avatar
- security:
- - OAuth2: []
+ 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 Channels
+ - Video
parameters:
- - $ref: '#/components/parameters/channelHandle'
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- type: object
- properties:
- avatars:
- type: array
- items:
- $ref: '#/components/schemas/ActorImage'
- '413':
- description: image file too large
- headers:
- X-File-Maximum-Size:
- schema:
- type: string
- format: Nginx size
- description: Maximum file size for the avatar
+ - $ref: '#/components/parameters/idOrUUID'
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
- type: object
- properties:
- avatarfile:
- description: The file to upload.
- type: string
- format: binary
- encoding:
- avatarfile:
- contentType: image/png, image/jpeg
+ $ref: '#/components/schemas/UserViewingVideo'
+ required: true
+ responses:
+ '204':
+ description: successful operation
- '/video-channels/{channelHandle}/avatar':
- delete:
- summary: Delete channel avatar
+ '/api/v1/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:
- OAuth2: []
- tags:
- - Video Channels
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserViewingVideo'
+ required: true
responses:
'204':
description: successful operation
- '/video-channels/{channelHandle}/banner/pick':
- post:
- summary: Update channel banner
+ '/api/v1/videos/{id}/stats/overall':
+ get:
+ summary: Get overall stats of a video
+ tags:
+ - Video Stats
security:
- OAuth2: []
- tags:
- - Video Channels
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $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:
- type: object
- properties:
- banners:
- type: array
- items:
- $ref: '#/components/schemas/ActorImage'
- '413':
- description: image file too large
- headers:
- X-File-Maximum-Size:
- schema:
- type: string
- format: Nginx size
- description: Maximum file size for the banner
- requestBody:
- content:
- multipart/form-data:
- schema:
- type: object
- properties:
- bannerfile:
- description: The file to upload.
- type: string
- format: binary
- encoding:
- bannerfile:
- contentType: image/png, image/jpeg
+ $ref: '#/components/schemas/VideoStatsOverall'
- '/video-channels/{channelHandle}/banner':
- delete:
- summary: Delete channel banner
+ '/api/v1/videos/{id}/stats/retention':
+ get:
+ summary: Get retention stats of a video
+ tags:
+ - Video Stats
security:
- OAuth2: []
- tags:
- - Video Channels
parameters:
- - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/idOrUUID'
responses:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsRetention'
- '/video-channels/{channelHandle}/import-videos':
- post:
- summary: Import videos in channel
- description: Import a remote channel/playlist videos into a channel
+ '/api/v1/videos/{id}/stats/timeseries/{metric}':
+ get:
+ summary: Get timeserie stats of a video
+ tags:
+ - Video Stats
security:
- OAuth2: []
- tags:
- - Video Channels
- - Channels Sync
parameters:
- - $ref: '#/components/parameters/channelHandle'
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ImportVideosInChannelCreate'
+ - $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:
- '204':
+ '200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsTimeserie'
- '/video-channel-syncs':
+ /api/v1/videos/upload:
post:
- summary: Create a synchronization for a video channel
- operationId: addVideoChannelSync
+ summary: Upload a video
+ description: Uses a single request to upload a video.
+ operationId: uploadLegacy
security:
- OAuth2: []
tags:
- - Channels Sync
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/VideoChannelSyncCreate'
+ - Video
+ - Video Upload
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: object
- properties:
- videoChannelSync:
- $ref: "#/components/schemas/VideoChannelSync"
-
- '/video-channel-syncs/{channelSyncId}':
- delete:
- summary: Delete a video channel synchronization
- operationId: delVideoChannelSync
- security:
- - OAuth2: []
- tags:
- - Channels Sync
- parameters:
- - $ref: '#/components/parameters/channelSyncId'
- responses:
- '204':
+ $ref: '#/components/schemas/VideoUploadResponse'
+ '403':
+ description: video didn't pass upload filter
+ '408':
+ description: upload has timed out
+ '413':
+ 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 whether daily or global
+ headers:
+ X-File-Maximum-Size:
+ schema:
+ type: string
+ format: Nginx size
+ description: Maximum file size for the video
+ '415':
+ description: video type unsupported
+ '422':
+ description: video unreadable
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ $ref: '#/components/schemas/VideoUploadRequestLegacy'
+ encoding:
+ videofile:
+ contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
+ thumbnailfile:
+ contentType: image/jpeg
+ previewfile:
+ contentType: image/jpeg
+ x-codeSamples:
+ - lang: Shell
+ source: |
+ ## DEPENDENCIES: jq
+ USERNAME="<your_username>"
+ PASSWORD="<your_password>"
+ FILE_PATH="<your_file_path>"
+ CHANNEL_ID="<your_channel_id>"
+ NAME="<video_name>"
+ API="https://peertube2.cpy.re/api/v1"
+
+ ## AUTH
+ client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
+ client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
+ token=$(curl -s "$API/users/token" \
+ --data client_id="$client_id" \
+ --data client_secret="$client_secret" \
+ --data grant_type=password \
+ --data username="$USERNAME" \
+ --data password="$PASSWORD" \
+ | jq -r ".access_token")
+
+ ## VIDEO UPLOAD
+ curl -s "$API/videos/upload" \
+ -H "Authorization: Bearer $token" \
+ --max-time 600 \
+ --form videofile=@"$FILE_PATH" \
+ --form channelId=$CHANNEL_ID \
+ --form name="$NAME"
+
+ /api/v1/videos/upload-resumable:
+ post:
+ summary: Initialize the resumable upload of a video
+ description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
+ operationId: uploadResumableInit
+ security:
+ - OAuth2: []
+ tags:
+ - Video
+ - Video Upload
+ parameters:
+ - name: X-Upload-Content-Length
+ in: header
+ schema:
+ type: number
+ example: 2469036
+ required: true
+ description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
+ - name: X-Upload-Content-Type
+ in: header
+ schema:
+ type: string
+ format: mimetype
+ example: video/mp4
+ required: true
+ description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoUploadRequestResumable'
+ responses:
+ '200':
+ description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
+ '201':
+ description: created
+ headers:
+ Location:
+ schema:
+ type: string
+ format: url
+ example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
+ Content-Length:
+ schema:
+ type: number
+ example: 0
+ '413':
+ 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:
+ summary: Send chunk for the resumable upload of a video
+ description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
+ operationId: uploadResumable
+ security:
+ - OAuth2: []
+ tags:
+ - Video
+ - Video Upload
+ parameters:
+ - name: upload_id
+ in: query
+ required: true
+ description: |
+ 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
+ - name: Content-Range
+ in: header
+ schema:
+ type: string
+ example: bytes 0-262143/2469036
+ required: true
+ description: |
+ Specifies the bytes in the file that the request is uploading.
+
+ For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
+ 262144 bytes (256 x 1024) in a 2,469,036 byte file.
+ - name: Content-Length
+ in: header
+ schema:
+ type: number
+ example: 262144
+ required: true
+ description: |
+ Size of the chunk that the request is sending.
+
+ 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:
+ content:
+ application/octet-stream:
+ schema:
+ type: string
+ format: binary
+ responses:
+ '200':
+ description: last chunk received
+ headers:
+ Content-Length:
+ schema:
+ type: number
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoUploadResponse'
+ '308':
+ description: resume incomplete
+ headers:
+ Range:
+ schema:
+ type: string
+ example: bytes=0-262143
+ Content-Length:
+ schema:
+ type: number
+ example: 0
+ '403':
+ description: video didn't pass upload filter
+ '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
+ operationId: uploadResumableCancel
+ security:
+ - OAuth2: []
+ tags:
+ - Video
+ - Video Upload
+ parameters:
+ - name: upload_id
+ in: query
+ required: true
+ description: |
+ Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
+ not valid anymore and the upload session has already been deleted with its data ;-)
+ schema:
+ type: string
+ - name: Content-Length
+ in: header
+ required: true
+ schema:
+ type: number
+ example: 0
+ responses:
+ '204':
+ description: upload cancelled
+ headers:
+ Content-Length:
+ schema:
+ type: number
+ example: 0
+ '404':
+ description: upload not found
+
+ /api/v1/videos/imports:
+ post:
+ summary: Import a video
+ description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
+ operationId: importVideo
+ security:
+ - OAuth2: []
+ tags:
+ - Video Imports
+ - Video Upload
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ $ref: '#/components/schemas/VideoCreateImport'
+ encoding:
+ torrentfile:
+ contentType: application/x-bittorrent
+ thumbnailfile:
+ contentType: image/jpeg
+ previewfile:
+ contentType: image/jpeg
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoUploadResponse'
+ '400':
+ description: '`magnetUri` or `targetUrl` or a torrent file missing'
+ '403':
+ description: video didn't pass pre-import filter
+ '409':
+ description: HTTP or Torrent/magnetURI import not enabled
+
+ /api/v1/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
+
+ /api/v1/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
+
+ /api/v1/videos/live:
+ post:
+ summary: Create a live
+ operationId: addLive
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ - Video
+ responses:
+ '200':
+ description: successful operation
+ content:
+ 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':
+ 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:
+ schema:
+ type: object
+ properties:
+ channelId:
+ description: Channel id that will contain this live video
+ type: integer
+ 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'
+ thumbnailfile:
+ description: Live video/replay thumbnail file
+ type: string
+ format: binary
+ previewfile:
+ description: Live video/replay preview file
+ type: string
+ format: binary
+ privacy:
+ $ref: '#/components/schemas/VideoPrivacySet'
+ category:
+ $ref: '#/components/schemas/VideoCategorySet'
+ licence:
+ $ref: '#/components/schemas/VideoLicenceSet'
+ language:
+ $ref: '#/components/schemas/VideoLanguageSet'
+ description:
+ description: Live video/replay description
+ type: string
+ support:
+ description: A text tell the audience how to support the creator
+ example: Please support our work on https://soutenir.framasoft.org/en/ <3
+ type: string
+ nsfw:
+ description: Whether or not this live video/replay contains sensitive content
+ type: boolean
+ name:
+ description: Live video/replay name
+ type: string
+ minLength: 3
+ maxLength: 120
+ tags:
+ description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
+ type: array
+ minItems: 1
+ maxItems: 5
+ items:
+ type: string
+ minLength: 2
+ maxLength: 30
+ commentsEnabled:
+ description: Enable or disable comments for this live video/replay
+ type: boolean
+ downloadEnabled:
+ description: Enable or disable downloading for the replay of this live video
+ type: boolean
+ required:
+ - channelId
+ - name
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
+ previewfile:
+ contentType: image/jpeg
+
+ /api/v1/videos/live/{id}:
+ get:
+ summary: Get information about a live
+ operationId: getLiveId
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ - Video
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LiveVideoResponse'
+ put:
+ summary: Update information about a live
+ operationId: updateLiveId
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ - Video
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/LiveVideoUpdate'
+ responses:
+ '204':
+ description: successful operation
+ '400':
+ 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
+ /api/v1/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'
+ /api/v1/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'
+
+ /api/v1/users/me/abuses:
+ get:
+ summary: List my abuses
+ operationId: getMyAbuses
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
+ - My User
+ parameters:
+ - name: id
+ in: query
+ description: only list the report with this id
+ schema:
+ type: integer
+ - name: state
+ in: query
+ schema:
+ $ref: '#/components/schemas/AbuseStateSet'
+ - $ref: '#/components/parameters/abusesSort'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Abuse'
+
+ /api/v1/abuses:
+ get:
+ summary: List abuses
+ operationId: getAbuses
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Abuses
+ parameters:
+ - name: id
+ in: query
+ description: only list the report with this id
+ schema:
+ type: integer
+ - name: predefinedReason
+ in: query
+ description: predefined reason the listed reports should contain
+ schema:
+ $ref: '#/components/schemas/PredefinedAbuseReasons'
+ - name: search
+ in: query
+ description: plain search that will match with video titles, reporter names and more
+ schema:
+ type: string
+ - name: state
+ in: query
+ schema:
+ $ref: '#/components/schemas/AbuseStateSet'
+ - name: searchReporter
+ in: query
+ description: only list reports of a specific reporter
+ schema:
+ type: string
+ - name: searchReportee
+ description: only list reports of a specific reportee
+ in: query
+ schema:
+ type: string
+ - name: searchVideo
+ in: query
+ description: only list reports of a specific video
+ schema:
+ type: string
+ - name: searchVideoChannel
+ in: query
+ description: only list reports of a specific video channel
+ schema:
+ type: string
+ - name: videoIs
+ in: query
+ description: only list deleted or blocklisted videos
+ schema:
+ type: string
+ enum:
+ - 'deleted'
+ - 'blacklisted'
+ - name: filter
+ in: query
+ description: only list account, comment or video reports
+ schema:
+ type: string
+ enum:
+ - 'video'
+ - 'comment'
+ - 'account'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/abusesSort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Abuse'
+ post:
+ summary: Report an abuse
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ reason:
+ description: Reason why the user reports this video
+ type: string
+ minLength: 2
+ maxLength: 3000
+ predefinedReasons:
+ $ref: '#/components/schemas/PredefinedAbuseReasons'
+ video:
+ type: object
+ properties:
+ id:
+ description: Video id to report
+ allOf:
+ - $ref: '#/components/schemas/Video/properties/id'
+ startAt:
+ type: integer
+ format: seconds
+ description: Timestamp in the video that marks the beginning of the report
+ minimum: 0
+ endAt:
+ type: integer
+ format: seconds
+ description: Timestamp in the video that marks the ending of the report
+ minimum: 0
+ comment:
+ type: object
+ properties:
+ id:
+ description: Comment id to report
+ allOf:
+ - $ref: '#/components/schemas/VideoComment/properties/id'
+ account:
+ type: object
+ properties:
+ id:
+ description: Account id to report
+ type: integer
+ required:
+ - reason
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ abuse:
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ '400':
+ description: incorrect request parameters
+
+ '/api/v1/abuses/{abuseId}':
+ put:
+ summary: Update an abuse
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ state:
+ $ref: '#/components/schemas/AbuseStateSet'
+ moderationComment:
+ type: string
+ description: Update the report comment visible only to the moderation team
+ minLength: 2
+ maxLength: 3000
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: abuse not found
+ delete:
+ tags:
+ - Abuses
+ summary: Delete an abuse
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: block not found
+
+ '/api/v1/abuses/{abuseId}/messages':
+ get:
+ summary: List messages of an abuse
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/AbuseMessage'
+ post:
+ summary: Add message to an abuse
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ message:
+ description: Message to send
+ type: string
+ minLength: 2
+ maxLength: 3000
+ required:
+ - message
+ responses:
+ '200':
+ description: successful operation
+ '400':
+ description: incorrect request parameters
+
+ '/api/v1/abuses/{abuseId}/messages/{abuseMessageId}':
+ delete:
+ summary: Delete an abuse message
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ - $ref: '#/components/parameters/abuseMessageId'
+ responses:
+ '204':
+ description: successful operation
+
+ '/api/v1/videos/{id}/blacklist':
+ post:
+ summary: Block a video
+ operationId: addVideoBlock
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Video Blocks
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ delete:
+ summary: Unblock a video by its id
+ operationId: delVideoBlock
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ tags:
+ - Video Blocks
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: block not found
+
+ /api/v1/videos/blacklist:
+ get:
+ tags:
+ - Video Blocks
+ summary: List video blocks
+ operationId: getVideoBlocks
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ parameters:
+ - name: type
+ in: query
+ description: >
+ list only blocks that match this type:
+
+ - `1`: manual block
+
+ - `2`: automatic block that needs review
+ schema:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - name: search
+ in: query
+ description: plain search that will match with video titles, and more
+ schema:
+ type: string
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/blacklistsSort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoBlacklist'
+
+ /api/v1/videos/{id}/captions:
+ get:
+ summary: List captions of a video
+ operationId: getVideoCaptions
+ tags:
+ - Video Captions
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoCaption'
+
+ /api/v1/videos/{id}/captions/{captionLanguage}:
+ put:
+ summary: Add or replace a video caption
+ operationId: addVideoCaption
+ security:
+ - OAuth2:
+ - user
+ tags:
+ - Video Captions
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/captionLanguage'
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ captionfile:
+ description: The file to upload.
+ type: string
+ format: binary
+ encoding:
+ captionfile:
+ contentType: text/vtt, application/x-subrip, text/plain
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video or language not found
+ delete:
+ summary: Delete a video caption
+ operationId: delVideoCaption
+ security:
+ - OAuth2:
+ - user
+ tags:
+ - Video Captions
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/captionLanguage'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video or language or caption for that language not found
+
+ /api/v1/video-channels:
+ get:
+ summary: List video channels
+ operationId: getVideoChannels
+ 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:
+ $ref: '#/components/schemas/VideoChannelList'
+ post:
+ summary: Create a video channel
+ operationId: addVideoChannel
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ videoChannel:
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoChannelCreate'
+
+ '/api/v1/video-channels/{channelHandle}':
+ get:
+ summary: Get a video channel
+ operationId: getVideoChannel
+ 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
+ operationId: putVideoChannel
+ 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
+ operationId: delVideoChannel
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
+ '/api/v1/video-channels/{channelHandle}/videos':
+ get:
+ summary: List videos of a video channel
+ operationId: getVideoChannelVideos
+ tags:
+ - Video
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
+ - $ref: '#/components/parameters/tagsOneOf'
+ - $ref: '#/components/parameters/tagsAllOf'
+ - $ref: '#/components/parameters/licenceOneOf'
+ - $ref: '#/components/parameters/languageOneOf'
+ - $ref: '#/components/parameters/nsfw'
+ - $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/videosSort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoListResponse'
+
+ '/api/v1/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'
+
+ '/api/v1/video-channels/{channelHandle}/avatar/pick':
+ post:
+ summary: Update channel avatar
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
+ '413':
+ description: image file too large
+ headers:
+ X-File-Maximum-Size:
+ schema:
+ type: string
+ format: Nginx size
+ description: Maximum file size for the avatar
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ avatarfile:
+ description: The file to upload.
+ type: string
+ format: binary
+ encoding:
+ avatarfile:
+ contentType: image/png, image/jpeg
+
+ '/api/v1/video-channels/{channelHandle}/avatar':
+ delete:
+ summary: Delete channel avatar
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
+ '/api/v1/video-channels/{channelHandle}/banner/pick':
+ post:
+ summary: Update channel banner
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ banners:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
+ '413':
+ description: image file too large
+ headers:
+ X-File-Maximum-Size:
+ schema:
+ type: string
+ format: Nginx size
+ description: Maximum file size for the banner
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ bannerfile:
+ description: The file to upload.
+ type: string
+ format: binary
+ encoding:
+ bannerfile:
+ contentType: image/png, image/jpeg
+
+ '/api/v1/video-channels/{channelHandle}/banner':
+ delete:
+ summary: Delete channel banner
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
+ '/api/v1/video-channels/{channelHandle}/import-videos':
+ post:
+ summary: Import videos in channel
+ description: Import a remote channel/playlist videos into a channel
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ - Channels Sync
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/ImportVideosInChannelCreate'
+ responses:
+ '204':
+ description: successful operation
+
+ '/api/v1/video-channel-syncs':
+ post:
+ summary: Create a synchronization for a video channel
+ operationId: addVideoChannelSync
+ security:
+ - OAuth2: []
+ tags:
+ - Channels Sync
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoChannelSyncCreate'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ videoChannelSync:
+ $ref: "#/components/schemas/VideoChannelSync"
+
+ '/api/v1/video-channel-syncs/{channelSyncId}':
+ delete:
+ summary: Delete a video channel synchronization
+ operationId: delVideoChannelSync
+ security:
+ - OAuth2: []
+ tags:
+ - Channels Sync
+ parameters:
+ - $ref: '#/components/parameters/channelSyncId'
+ responses:
+ '204':
description: successful operation
- '/video-channel-syncs/{channelSyncId}/sync':
+ '/api/v1/video-channel-syncs/{channelSyncId}/sync':
post:
summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
operationId: triggerVideoChannelSync
description: successful operation
- /video-playlists/privacies:
+ /api/v1/video-playlists/privacies:
get:
summary: List available playlist privacy policies
operationId: getPlaylistPrivacyPolicies
nightly:
externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
- /video-playlists:
+ /api/v1/video-playlists:
get:
summary: List video playlists
operationId: getPlaylists
thumbnailfile:
contentType: image/jpeg
- /video-playlists/{playlistId}:
+ /api/v1/video-playlists/{playlistId}:
get:
summary: Get a video playlist
tags:
'204':
description: successful operation
- /video-playlists/{playlistId}/videos:
+ /api/v1/video-playlists/{playlistId}/videos:
get:
summary: 'List videos of a playlist'
operationId: getVideoPlaylistVideos
required:
- videoId
- /video-playlists/{playlistId}/videos/reorder:
+ /api/v1/video-playlists/{playlistId}/videos/reorder:
post:
summary: 'Reorder a playlist'
operationId: reorderVideoPlaylist
- startPosition
- insertAfterPosition
- /video-playlists/{playlistId}/videos/{playlistElementId}:
+ /api/v1/video-playlists/{playlistId}/videos/{playlistElementId}:
put:
summary: Update a playlist element
operationId: putVideoPlaylistVideo
'204':
description: successful operation
- '/users/me/video-playlists/videos-exist':
+ '/api/v1/users/me/video-playlists/videos-exist':
get:
summary: Check video exists in my playlists
security:
type: integer
format: seconds
- '/accounts/{name}/video-channels':
+ '/api/v1/accounts/{name}/video-channels':
get:
summary: List video channels of an account
tags:
schema:
$ref: '#/components/schemas/VideoChannelList'
- '/accounts/{name}/video-channel-syncs':
+ '/api/v1/accounts/{name}/video-channel-syncs':
get:
summary: List the synchronizations of video channels of an account
tags:
schema:
$ref: '#/components/schemas/VideoChannelSyncList'
- '/accounts/{name}/ratings':
+ '/api/v1/accounts/{name}/ratings':
get:
summary: List ratings of an account
security:
items:
$ref: '#/components/schemas/VideoRating'
- '/videos/{id}/comment-threads':
+ '/api/v1/videos/{id}/comment-threads':
get:
summary: List threads of a video
tags:
required:
- text
- '/videos/{id}/comment-threads/{threadId}':
+ '/api/v1/videos/{id}/comment-threads/{threadId}':
get:
summary: Get a thread
tags:
schema:
$ref: '#/components/schemas/VideoCommentThreadTree'
- '/videos/{id}/comments/{commentId}':
+ '/api/v1/videos/{id}/comments/{commentId}':
post:
summary: Reply to a thread of a video
security:
'409':
description: comment is already deleted
- '/videos/{id}/rate':
+ '/api/v1/videos/{id}/rate':
put:
summary: Like/dislike a video
security:
'404':
description: video does not exist
- '/videos/{id}/hls':
+ '/api/v1/videos/{id}/hls':
delete:
summary: Delete video HLS files
security:
description: successful operation
'404':
description: video does not exist
- '/videos/{id}/webtorrent':
+ '/api/v1/videos/{id}/webtorrent':
delete:
summary: Delete video WebTorrent files
security:
'404':
description: video does not exist
- '/videos/{id}/transcoding':
+ '/api/v1/videos/{id}/transcoding':
post:
summary: Create a transcoding job
security:
'404':
description: video does not exist
- /search/videos:
+ /api/v1/search/videos:
get:
tags:
- Search
- $ref: '#/components/parameters/isLocal'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/uuids'
- $ref: '#/components/parameters/hasHLSFiles'
- $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
'500':
description: search index unavailable
- /search/video-channels:
+ /api/v1/search/video-channels:
get:
tags:
- Search
'500':
description: search index unavailable
- /search/video-playlists:
+ /api/v1/search/video-playlists:
get:
tags:
- Search
'500':
description: search index unavailable
- /blocklist/status:
+ /api/v1/blocklist/status:
get:
tags:
- Account Blocks
schema:
$ref: '#/components/schemas/BlockStatus'
- /server/blocklist/accounts:
+ /api/v1/server/blocklist/accounts:
get:
tags:
- Account Blocks
'409':
description: self-blocking forbidden
- '/server/blocklist/accounts/{accountName}':
+ '/api/v1/server/blocklist/accounts/{accountName}':
delete:
tags:
- Account Blocks
'404':
description: account or account block does not exist
- /server/blocklist/servers:
+ /api/v1/server/blocklist/servers:
get:
tags:
- Server Blocks
'409':
description: self-blocking forbidden
- '/server/blocklist/servers/{host}':
+ '/api/v1/server/blocklist/servers/{host}':
delete:
tags:
- Server Blocks
'404':
description: account block does not exist
- /server/redundancy/{host}:
- put:
- tags:
- - Instance Redundancy
- summary: Update a server redundancy policy
- security:
- - OAuth2:
- - admin
- parameters:
- - name: host
- in: path
- required: true
- description: server domain to mirror
- schema:
- type: string
- format: hostname
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- redundancyAllowed:
- type: boolean
- description: allow mirroring of the host's local videos
- required:
- - redundancyAllowed
- responses:
- '204':
- description: successful operation
- '404':
- description: server is not already known
-
- /server/redundancy/videos:
- get:
- tags:
- - Video Mirroring
- summary: List videos being mirrored
- operationId: getMirroredVideos
- security:
- - OAuth2:
- - admin
- parameters:
- - name: target
- in: query
- required: true
- description: direction of the mirror
- schema:
- type: string
- enum:
- - my-videos
- - remote-videos
- - $ref: '#/components/parameters/start'
- - $ref: '#/components/parameters/count'
- - $ref: '#/components/parameters/videoRedundanciesSort'
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoRedundancy'
- post:
- tags:
- - Video Mirroring
- summary: Mirror a video
- operationId: putMirroredVideo
- security:
- - OAuth2:
- - admin
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- videoId:
- $ref: '#/components/schemas/Video/properties/id'
- required:
- - videoId
- responses:
- '204':
- description: successful operation
- '400':
- description: cannot mirror a local video
- '404':
- description: video does not exist
- '409':
- description: video is already mirrored
-
- /server/redundancy/videos/{redundancyId}:
- delete:
- tags:
- - Video Mirroring
- summary: Delete a mirror done on a video
- operationId: delMirroredVideo
- security:
- - OAuth2:
- - admin
- parameters:
- - name: redundancyId
- in: path
- required: true
- description: id of an existing redundancy on a video
- schema:
- type: string
- responses:
- '204':
- description: successful operation
- '404':
- description: video redundancy not found
-
- /server/stats:
- get:
- tags:
- - Stats
- summary: Get instance stats
- description: Get instance public statistics. This endpoint is cached.
- operationId: getInstanceStats
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/ServerStats'
-
- /server/logs/client:
- post:
- tags:
- - Logs
- summary: Send client log
- operationId: sendClientLog
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SendClientLog'
- responses:
- '204':
- description: successful operation
-
- /server/logs:
- get:
- tags:
- - Logs
- summary: Get instance logs
- operationId: getInstanceLogs
- security:
- - OAuth2:
- - admin
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- type: string
-
- /server/audit-logs:
- get:
- tags:
- - Logs
- summary: Get instance audit logs
- operationId: getInstanceAuditLogs
- security:
- - OAuth2:
- - admin
- responses:
- '200':
- description: successful operation
- content:
- application/json:
- schema:
- type: array
- items:
- type: string
-
- '/feeds/video-comments.{format}':
- get:
+ /api/v1/server/redundancy/{host}:
+ put:
tags:
- - Feeds
- summary: List comments on videos
- operationId: getSyndicatedComments
+ - Instance Redundancy
+ summary: Update a server redundancy policy
+ security:
+ - OAuth2:
+ - admin
parameters:
- - name: format
+ - name: host
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
- schema:
- type: string
- enum:
- - xml
- - rss
- - rss2
- - atom
- - atom1
- - json
- - json1
- - name: videoId
- in: query
- description: 'limit listing to a specific video'
- schema:
- type: string
- - name: accountId
- in: query
- description: 'limit listing to a specific account'
- schema:
- type: string
- - name: accountName
- in: query
- description: 'limit listing to a specific account'
- schema:
- type: string
- - name: videoChannelId
- in: query
- description: 'limit listing to a specific video channel'
- schema:
- type: string
- - name: videoChannelName
- in: query
- description: 'limit listing to a specific video channel'
+ description: server domain to mirror
schema:
type: string
+ format: hostname
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ redundancyAllowed:
+ type: boolean
+ description: allow mirroring of the host's local videos
+ required:
+ - redundancyAllowed
responses:
'204':
description: successful operation
- headers:
- Cache-Control:
- schema:
- type: string
- default: 'max-age=900' # 15 min cache
- content:
- application/xml:
- schema:
- $ref: '#/components/schemas/VideoCommentsForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
- application/rss+xml:
- schema:
- $ref: '#/components/schemas/VideoCommentsForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
- text/xml:
- schema:
- $ref: '#/components/schemas/VideoCommentsForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
- application/atom+xml:
- schema:
- $ref: '#/components/schemas/VideoCommentsForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
- application/json:
- schema:
- type: object
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
- '400':
- x-summary: field inconsistencies
- description: >
- Arises when:
- - videoId filter is mixed with a channel filter
'404':
- description: video, video channel or account not found
- '406':
- description: accept header unsupported
+ description: server is not already known
- '/feeds/videos.{format}':
+ /api/v1/server/redundancy/videos:
get:
tags:
- - Feeds
- summary: List videos
- operationId: getSyndicatedVideos
+ - Video Mirroring
+ summary: List videos being mirrored
+ operationId: getMirroredVideos
+ security:
+ - OAuth2:
+ - admin
parameters:
- - name: format
- in: path
+ - name: target
+ in: query
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
+ description: direction of the mirror
schema:
type: string
enum:
- - xml
- - rss
- - rss2
- - atom
- - atom1
- - json
- - json1
- - name: accountId
- in: query
- description: 'limit listing to a specific account'
- schema:
- type: string
- - name: accountName
- in: query
- description: 'limit listing to a specific account'
- schema:
- type: string
- - name: videoChannelId
- in: query
- description: 'limit listing to a specific video channel'
- schema:
- type: string
- - name: videoChannelName
- in: query
- description: 'limit listing to a specific video channel'
- schema:
- type: string
- - $ref: '#/components/parameters/sort'
- - $ref: '#/components/parameters/nsfw'
- - $ref: '#/components/parameters/isLocal'
- - $ref: '#/components/parameters/include'
- - $ref: '#/components/parameters/privacyOneOf'
- - $ref: '#/components/parameters/hasHLSFiles'
- - $ref: '#/components/parameters/hasWebtorrentFiles'
+ - my-videos
+ - remote-videos
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/videoRedundanciesSort'
responses:
- '204':
+ '200':
description: successful operation
- headers:
- Cache-Control:
- schema:
- type: string
- default: 'max-age=900' # 15 min cache
content:
- application/xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
- application/rss+xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
- text/xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
- application/atom+xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
application/json:
schema:
- type: object
- examples:
- nightly:
- externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoRedundancy'
+ post:
+ tags:
+ - Video Mirroring
+ summary: Mirror a video
+ operationId: putMirroredVideo
+ security:
+ - OAuth2:
+ - admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ videoId:
+ $ref: '#/components/schemas/Video/properties/id'
+ required:
+ - videoId
+ responses:
+ '204':
+ description: successful operation
+ '400':
+ description: cannot mirror a local video
'404':
- description: video channel or account not found
- '406':
- description: accept header unsupported
+ description: video does not exist
+ '409':
+ description: video is already mirrored
- '/feeds/subscriptions.{format}':
- get:
+ /api/v1/server/redundancy/videos/{redundancyId}:
+ delete:
tags:
- - Feeds
- - Account
- summary: List videos of subscriptions tied to a token
- operationId: getSyndicatedSubscriptionVideos
+ - Video Mirroring
+ summary: Delete a mirror done on a video
+ operationId: delMirroredVideo
+ security:
+ - OAuth2:
+ - admin
parameters:
- - name: format
+ - name: redundancyId
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
- schema:
- type: string
- enum:
- - xml
- - rss
- - rss2
- - atom
- - atom1
- - json
- - json1
- - name: accountId
- in: query
- description: limit listing to a specific account
- schema:
- type: string
- required: true
- - name: token
- in: query
- description: private token allowing access
+ description: id of an existing redundancy on a video
schema:
type: string
- required: true
- - $ref: '#/components/parameters/sort'
- - $ref: '#/components/parameters/nsfw'
- - $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
- headers:
- Cache-Control:
- schema:
- type: string
- default: 'max-age=900' # 15 min cache
+ '404':
+ description: video redundancy not found
+
+ /api/v1/server/stats:
+ get:
+ tags:
+ - Stats
+ summary: Get instance stats
+ description: Get instance public statistics. This endpoint is cached.
+ operationId: getInstanceStats
+ responses:
+ '200':
+ description: successful operation
content:
- application/xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- application/rss+xml:
- schema:
- $ref: '#/components/schemas/VideosForXML'
- text/xml:
+ application/json:
schema:
- $ref: '#/components/schemas/VideosForXML'
- application/atom+xml:
+ $ref: '#/components/schemas/ServerStats'
+
+ /api/v1/server/logs/client:
+ post:
+ tags:
+ - Logs
+ summary: Send client log
+ operationId: sendClientLog
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SendClientLog'
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/server/logs:
+ get:
+ tags:
+ - Logs
+ summary: Get instance logs
+ operationId: getInstanceLogs
+ security:
+ - OAuth2:
+ - admin
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
schema:
- $ref: '#/components/schemas/VideosForXML'
+ type: array
+ items:
+ type: string
+
+ /api/v1/server/audit-logs:
+ get:
+ tags:
+ - Logs
+ summary: Get instance audit logs
+ operationId: getInstanceAuditLogs
+ security:
+ - OAuth2:
+ - admin
+ responses:
+ '200':
+ description: successful operation
+ content:
application/json:
schema:
- type: object
- '406':
- description: accept header unsupported
+ type: array
+ items:
+ type: string
- /plugins:
+ /api/v1/plugins:
get:
tags:
- Plugins
schema:
$ref: '#/components/schemas/PluginResponse'
- /plugins/available:
+ /api/v1/plugins/available:
get:
tags:
- Plugins
'503':
description: plugin index unavailable
- /plugins/install:
+ /api/v1/plugins/install:
post:
tags:
- Plugins
'400':
description: should have either `npmName` or `path` set
- /plugins/update:
+ /api/v1/plugins/update:
post:
tags:
- Plugins
'404':
description: existing plugin not found
- /plugins/uninstall:
+ /api/v1/plugins/uninstall:
post:
tags:
- Plugins
'404':
description: existing plugin not found
- /plugins/{npmName}:
+ /api/v1/plugins/{npmName}:
get:
tags:
- Plugins
'404':
description: plugin not found
- /plugins/{npmName}/settings:
+ /api/v1/plugins/{npmName}/settings:
put:
tags:
- Plugins
'404':
description: plugin not found
- /plugins/{npmName}/public-settings:
+ /api/v1/plugins/{npmName}/public-settings:
get:
tags:
- Plugins
'404':
description: plugin not found
- /plugins/{npmName}/registered-settings:
+ /api/v1/plugins/{npmName}/registered-settings:
get:
tags:
- Plugins
'404':
description: plugin not found
+ /api/v1/metrics/playback:
+ post:
+ summary: Create playback metrics
+ description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
+ tags:
+ - Stats
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PlaybackMetricCreate'
+ responses:
+ '204':
+ description: successful operation
+
servers:
- - url: 'https://peertube2.cpy.re/api/v1'
+ - url: 'https://peertube2.cpy.re'
description: Live Test Server (live data - latest nightly version)
- - url: 'https://peertube3.cpy.re/api/v1'
+ - url: 'https://peertube3.cpy.re'
description: Live Test Server (live data - latest RC version)
- - url: 'https://peertube.cpy.re/api/v1'
+ - url: 'https://peertube.cpy.re'
description: Live Test Server (live data - stable version)
components:
parameters:
type: string
enum:
- createdAt
+
name:
name: name
in: path
description: Entity id
schema:
$ref: '#/components/schemas/id'
+ registrationId:
+ name: registrationId
+ in: path
+ required: true
+ description: Registration ID
+ schema:
+ $ref: '#/components/schemas/id'
idOrUUID:
name: id
in: path
schema:
$ref: '#/components/schemas/VideoPrivacySet'
description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+ uuids:
+ name: uuids
+ in: query
+ required: false
+ schema:
+ items:
+ type: string
+ description: 'Find videos with specific UUIDs'
include:
name: include
in: query
- Group
- Service
- Organization
+ staticFilename:
+ name: filename
+ in: path
+ required: true
+ description: Filename
+ schema:
+ type: string
+ videoFileToken:
+ name: videoFileToken
+ in: query
+ required: false
+ description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
+ schema:
+ type: string
+ reinjectVideoFileToken:
+ name: reinjectVideoFileToken
+ in: query
+ required: false
+ description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
+ schema:
+ type: boolean
+
securitySchemes:
OAuth2:
description: |
properties:
comment:
$ref: '#/components/schemas/VideoComment'
+ VideoTokenResponse:
+ properties:
+ files:
+ type: object
+ properties:
+ token:
+ type: string
+ expires:
+ type: string
+ format: date-time
VideoListResponse:
properties:
total:
nsfwPolicy:
$ref: '#/components/schemas/NSFWPolicy'
role:
- $ref: '#/components/schemas/UserRole'
- roleLabel:
- type: string
- enum:
- - User
- - Moderator
- - Administrator
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/UserRole'
+ label:
+ type: string
+ enum:
+ - User
+ - Moderator
+ - Administrator
theme:
type: string
description: Theme enabled by this user
required:
- video
- rating
+
RegisterUser:
properties:
username:
- password
- email
+ UserRegistrationRequest:
+ allOf:
+ - $ref: '#/components/schemas/RegisterUser'
+ - type: object
+ properties:
+ registrationReason:
+ type: string
+ description: reason for the user to register on the instance
+ required:
+ - registrationReason
+
+ UserRegistrationAcceptOrReject:
+ type: object
+ properties:
+ moderationResponse:
+ type: string
+ description: Moderation response to send to the user
+ preventEmailDelivery:
+ type: boolean
+ description: Set it to true if you don't want PeerTube to send an email to the user
+ required:
+ - moderationResponse
+
+ UserRegistration:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ state:
+ type: object
+ properties:
+ id:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+ label:
+ type: string
+ registrationReason:
+ type: string
+ moderationResponse:
+ type: string
+ nullable: true
+ username:
+ type: string
+ email:
+ type: string
+ format: email
+ emailVerified:
+ type: boolean
+ accountDisplayName:
+ type: string
+ channelHandle:
+ type: string
+ channelDisplayName:
+ type: string
+ createdAt:
+ type: string
+ format: date-time
+ updatedAt:
+ type: string
+ format: date-time
+ user:
+ type: object
+ nullable: true
+ description: If the registration has been accepted, this is a partial user object created by the registration
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+
OAuthClient:
properties:
client_id:
NotificationSettingValue:
type: integer
description: >
- Notification type
+ Notification type. One of the following values, or a sum of multiple values:
- `0` NONE
- `1` WEB
- `2` EMAIL
- enum:
- - 0
- - 1
- - 2
Notification:
properties:
id:
description: User can select live latency mode if enabled by the instance
$ref: '#/components/schemas/LiveVideoLatencyMode'
+ RequestTwoFactorResponse:
+ properties:
+ otpRequest:
+ type: object
+ properties:
+ requestToken:
+ type: string
+ description: The token to send to confirm this request
+ secret:
+ type: string
+ description: The OTP secret
+ uri:
+ type: string
+ description: The OTP URI
+
VideoStudioCreateTask:
type: array
items:
format: binary
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'
+ 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'
+
+ PlaybackMetricCreate:
+ properties:
+ playerMode:
+ type: string
+ enum:
+ - 'p2p-media-loader'
+ - 'webtorrent'
+ resolution:
+ type: number
+ description: Current player video resolution
+ fps:
+ type: number
+ description: Current player video fps
+ resolutionChanges:
+ type: number
+ description: How many resolution changes occured since the last metric creation
+ errors:
+ type: number
+ description: How many errors occured since the last metric creation
+ downloadedBytesP2P:
+ type: number
+ description: How many bytes were downloaded with P2P since the last metric creation
+ downloadedBytesHTTP:
+ type: number
+ description: How many bytes were downloaded with HTTP since the last metric creation
+ uploadedBytesP2P:
+ type: number
+ description: How many bytes were uploaded with P2P since the last metric creation
+ videoId:
+ oneOf:
+ - $ref: '#/components/schemas/id'
+ - $ref: '#/components/schemas/UUIDv4'
+ - $ref: '#/components/schemas/shortUUID'
+ required:
+ - playerMode
+ - resolutionChanges
+ - errors
+ - downloadedBytesP2P
+ - downloadedBytesHTTP
+ - uploadedBytesP2P
+ - videoId
callbacks:
searchIndex:
projects / github / Chocobozzz / PeerTube.git / blobdiff