openapi: 3.0.0
info:
title: PeerTube
- version: 2.2.0
+ version: 4.0.0
contact:
name: PeerTube Community
- url: 'https://joinpeertube.org'
+ url: https://joinpeertube.org
license:
name: AGPLv3.0
- url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
+ url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
x-logo:
- url: 'https://joinpeertube.org/img/brand.png'
+ url: https://joinpeertube.org/img/brand.png
altText: PeerTube Project Homepage
description: |
- # Introduction
-
The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
[openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
- [Go](https://framagit.org/framasoft/peertube/clients/go)
- [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
- See the [Quick Start guide](https://docs.joinpeertube.org/#/api-rest-getting-started) so you can play with the PeerTube API.
+ See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
+ examples of using the PeerTube API.
# Authentication
- When you sign up for an account, you are given the possibility to generate
- sessions, and authenticate using this session token. One session token can
- currently be used at a time.
+ When you sign up for an account on a PeerTube instance, you are given the possibility
+ to generate sessions on it, and authenticate there using an access token. Only __one
+ access token can currently be used at a time__.
+
+ ## Roles
+
+ Accounts are given permissions based on their role. There are three roles on
+ PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
# Errors
The API uses standard HTTP status codes to indicate the success or failure
- of the API call. The body of the response will be JSON in the following
- format.
+ of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
+
+ ```
+ HTTP 1.1 404 Not Found
+ Content-Type: application/problem+json; charset=utf-8
+
+ {
+ "detail": "Video not found",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 404,
+ "title": "Not Found",
+ "type": "about:blank"
+ }
+ ```
+
+ We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
+ but it is still optional. Types are used to disambiguate errors that bear the same status code
+ and are non-obvious:
+
+ ```
+ HTTP 1.1 403 Forbidden
+ Content-Type: application/problem+json; charset=utf-8
+
+ {
+ "detail": "Cannot get this video regarding follow constraints",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "status": 403,
+ "title": "Forbidden",
+ "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+ }
+ ```
+
+ Here a 403 error could otherwise mean that the video is private or blocklisted.
+
+ ### Validation errors
+
+ Each parameter is evaluated on its own against a set of rules before the route validator
+ proceeds with potential testing involving parameter combinations. Errors coming from validation
+ errors appear earlier and benefit from a more detailed error description:
```
+ HTTP 1.1 400 Bad Request
+ Content-Type: application/problem+json; charset=utf-8
+
{
- "code": "unauthorized_request", // example inner error code
- "error": "Token is invalid." // example exposed error message
+ "detail": "Incorrect request parameters: id",
+ "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
+ "invalid-params": {
+ "id": {
+ "location": "params",
+ "msg": "Invalid value",
+ "param": "id",
+ "value": "9c9de5e8-0a1e-484a-b099-e80766180"
+ }
+ },
+ "status": 400,
+ "title": "Bad Request",
+ "type": "about:blank"
}
```
+
+ Where `id` is the name of the field concerned by the error, within the route definition.
+ `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
+ `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
+ is about.
+
+ ### Deprecated error fields
+
+ Some fields could be included with previous versions. They are still included but their use is deprecated:
+ - `error`: superseded by `detail`
+ - `code`: superseded by `type` (which is now an URI)
+
+ # Rate limits
+
+ We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
+
+ | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
+ |------------------------------|---------------|--------------|
+ | `/*` | 50 | 10 seconds |
+ | `POST /users/token` | 15 | 5 minutes |
+ | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
+ | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
+
+ Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
+ limit is announced by a `429 Too Many Requests` status code.
+
+ You can get details about the current state of your rate limit by reading the
+ following headers:
+
+ | Header | Description |
+ |-------------------------|------------------------------------------------------------|
+ | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
+ | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
+ | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
+ | `Retry-After` | Seconds to delay after the first `429` is received |
+
+ # CORS
+
+ This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
+ allowing cross-domain communication from the browser for some routes:
+
+ | Endpoint |
+ |------------------------- ---|
+ | `/api/*` |
+ | `/download/*` |
+ | `/lazy-static/*` |
+ | `/live/segments-sha256/*` |
+ | `/.well-known/webfinger` |
+
+ In addition, all routes serving ActivityPub are CORS-enabled for all origins.
externalDocs:
url: https://docs.joinpeertube.org/api-rest-reference.html
tags:
+ - name: Register
+ description: |
+ As a visitor, you can use this API to open an account (if registrations are open on
+ that PeerTube instance). As an admin, you should use the dedicated [User creation
+ API](#operation/addUser) instead.
+ - name: Session
+ x-displayName: Login/Logout
+ description: |
+ Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
- name: Accounts
description: >
- Using some features of PeerTube require authentication, for which Accounts
+ Accounts encompass remote accounts discovered across the federation,
+ and correspond to the main Actor, along with video channels a user can create, which
+ are also Actors.
+
+ When a comment is posted, it is done with your Account's Actor.
+ - name: Users
+ description: >
+ Using some features of PeerTube require authentication, for which User
provide different levels of permission as well as associated user
- information. Accounts also encompass remote accounts discovered across the federation.
+ information. Each user has a corresponding local Account for federation.
+ - name: My User
+ description: >
+ Operations related to your own User, when logged-in.
+ - name: My Subscriptions
+ description: >
+ Operations related to your subscriptions to video channels, their
+ new videos, and how to keep up to date with their latest publications!
+ - name: My History
+ description: >
+ Operations related to your watch history.
+ - name: My Notifications
+ description: >
+ Notifications following new videos, follows or reports. They allow you
+ to keep track of the interactions and overall important information that
+ concerns you. You MAY set per-notification type delivery preference, to
+ receive the info either by mail, by in-browser notification or both.
- name: Config
description: >
Each server exposes public information regarding supported videos and
server then deals with inter-server ActivityPub operations and propagates
information across its social graph by posting activities to actors' inbox
endpoints.
- - name: Video Abuses
+ externalDocs:
+ url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
+ - name: Instance Redundancy
+ description: >
+ Redundancy is part of the inter-server solidarity that PeerTube fosters.
+ Manage the list of instances you wish to help by seeding their videos according
+ to the policy of video selection of your choice. Note that you have a similar functionality
+ to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
+ externalDocs:
+ url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
+ - name: Plugins
+ description: >
+ Managing plugins installed from a local path or from NPM, or search for new ones.
+ externalDocs:
+ url: https://docs.joinpeertube.org/api-plugins
+ - name: Abuses
description: |
- Video abuses deal with reports of local or remote videos alike.
+ Abuses deal with reports of local or remote videos/comments/accounts alike.
- name: Video
description: |
Operations dealing with listing, uploading, fetching or modifying videos.
+ - name: Video Upload
+ description: |
+ Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
+
+ ### Upload
+
+ - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
+ - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
+
+ You can upload videos more reliably by using the resumable variant. Its protocol lets
+ you resume an upload operation after a network interruption or other transmission failure,
+ saving time and bandwidth in the event of network failures.
+
+ Favor using resumable uploads in any of the following cases:
+ - You are transferring large files
+ - The likelihood of a network interruption is high
+ - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
+ such as a mobile device
+
+ ### Import
+
+ - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
+ - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
+ - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
+
+ The import function is practical when the desired video/audio is available online. It makes PeerTube
+ download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
+ - name: Video Imports
+ description: Operations dealing with listing, adding and removing video imports.
+ - name: Video Captions
+ description: Operations dealing with listing, adding and removing closed captions of a video.
+ - name: Video Channels
+ description: Operations dealing with the creation, modification and listing of videos within a channel.
+ - name: Video Comments
+ description: >
+ Operations dealing with comments to a video. Comments are organized in threads: adding a
+ comment in response to the video starts a thread, adding a reply to a comment adds it to
+ its root comment thread.
+ - name: Video Blocks
+ description: Operations dealing with blocking videos (removing them from view and preventing interactions).
+ - name: Video Rates
+ description: Like/dislike a video.
+ - name: Video Playlists
+ description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
+ - name: Video Files
+ description: Operations on video files
+ - name: Video Transcoding
+ description: Video transcoding related operations
+ - name: Video stats
+ description: Video statistics
+ - name: Feeds
+ description: Server syndication feeds
- name: Search
description: |
The search helps to find _videos_ or _channels_ from within the instance and beyond.
Administrators can also enable the use of a remote search system, indexing
videos and channels not could be not federated by the instance.
- - name: Video Comments
- description: >
- Operations dealing with comments to a video. Comments are organized in
- threads.
- - name: Video Playlists
- description: >
- Operations dealing with playlists of videos. Playlists are bound to users
- and/or channels.
- - name: Video Channels
- description: >
- Operations dealing with the creation, modification and listing of videos within a channel.
- - name: Video Blocks
- description: >
- Operations dealing with blocking videos (removing them from view and
- preventing interactions).
- - name: Video Rates
- description: >
- Like/dislike a video.
- - name: Feeds
- description: >
- Server syndication feeds
+ - name: Homepage
+ description: Get and update the custom homepage
+ - name: Video Mirroring
+ description: |
+ PeerTube instances can mirror videos from one another, and help distribute some videos.
+
+ For importing videos as your own, refer to [video imports](#operation/importVideo).
x-tagGroups:
+ - name: Auth
+ tags:
+ - Register
+ - Session
- name: Accounts
tags:
- Accounts
- My User
- My Subscriptions
- My Notifications
+ - My History
- name: Videos
tags:
- Video
- - Video Caption
+ - Video Upload
+ - Video Imports
+ - Video Captions
- Video Channels
- Video Comments
- Video Rates
- Video Playlists
+ - Video Stats
- Video Ownership Change
+ - Video Mirroring
+ - Video Files
+ - Video Transcoding
+ - Live Videos
- Feeds
- name: Search
tags:
- Search
+ - name: Custom pages
+ tags:
+ - Homepage
- name: Moderation
tags:
- - Video Abuses
+ - Abuses
- Video Blocks
- Account Blocks
- Server Blocks
tags:
- Config
- Instance Follows
+ - Instance Redundancy
+ - Plugins
- name: Jobs
tags:
- Job
tags:
- Accounts
summary: Get an account
+ operationId: getAccount
parameters:
- $ref: '#/components/parameters/name'
responses:
$ref: '#/components/schemas/Account'
'404':
description: account not found
+
'/accounts/{name}/videos':
get:
tags:
- Accounts
- Video
summary: 'List videos of an account'
+ operationId: getAccountVideos
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/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
- x-code-samples:
+ x-codeSamples:
- lang: JavaScript
source: |
fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
})
- lang: Shell
source: |
- # pip install httpie
- http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
+ ## DEPENDENCIES: jq
+ curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
- lang: Ruby
source: |
require 'net/http'
json = r.json()
print(json)
+
+ '/accounts/{name}/followers':
+ get:
+ tags:
+ - Accounts
+ summary: 'List followers of an account'
+ security:
+ - OAuth2: []
+ operationId: getAccountFollowers
+ parameters:
+ - $ref: '#/components/parameters/name'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/followersSort'
+ - $ref: '#/components/parameters/search'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
+
/accounts:
get:
tags:
- Accounts
summary: List accounts
+ operationId: getAccounts
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
type: array
items:
$ref: '#/components/schemas/Account'
+
/config:
get:
tags:
- Config
summary: Get instance public configuration
+ operationId: getConfig
responses:
'200':
description: successful operation
application/json:
schema:
$ref: '#/components/schemas/ServerConfig'
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/config
+
/config/about:
get:
summary: Get instance "About" information
+ operationId: getAbout
tags:
- Config
responses:
application/json:
schema:
$ref: '#/components/schemas/ServerConfigAbout'
+ 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
+ - admin
responses:
'200':
description: successful operation
$ref: '#/components/schemas/ServerConfigCustom'
put:
summary: Set instance runtime configuration
+ operationId: putCustomConfig
tags:
- Config
security:
- OAuth2:
- - admin
+ - admin
responses:
'200':
description: successful operation
+ '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
+ - admin
+ responses:
+ '200':
+ description: successful operation
+
+ /custom-pages/homepage/instance:
+ get:
+ summary: Get instance custom homepage
+ tags:
+ - Homepage
responses:
+ '404':
+ description: No homepage set
'200':
description: successful operation
+ content:
+ 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
+
/jobs/{state}:
get:
summary: List instance jobs
+ operationId: getJobs
security:
- OAuth2:
- - admin
+ - admin
tags:
- Job
parameters:
- name: state
in: path
required: true
- description: The state of the job
+ 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'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/Job'
- '/server/following/{host}':
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ maxItems: 100
+ items:
+ $ref: '#/components/schemas/Job'
+
+ /server/followers:
+ get:
+ tags:
+ - 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
+ 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
- summary: Unfollow a server
parameters:
- - name: host
+ - name: nameWithHost
in: path
required: true
- description: 'The host to unfollow '
+ description: The remote actor handle to remove from your followers
schema:
type: string
+ format: email
responses:
- '201':
+ '204':
description: successful operation
- /server/followers:
- get:
+ '404':
+ description: follower not found
+
+ '/server/followers/{nameWithHost}/reject':
+ post:
+ summary: Reject a pending follower to your server
+ security:
+ - OAuth2:
+ - admin
tags:
- Instance Follows
- summary: List instance followers
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:
- type: array
- items:
- $ref: '#/components/schemas/Follow'
+ '404':
+ description: follower not found
+
+ '/server/followers/{nameWithHost}/accept':
+ post:
+ summary: Accept a pending 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
+ '404':
+ description: follower not found
+
/server/following:
get:
tags:
- Instance Follows
summary: List instances followed by the server
parameters:
- - name: state
- in: query
- schema:
- type: string
- enum:
- - pending
- - accepted
- - name: actorType
- in: query
- schema:
- type: string
- enum:
- - Person
- - Application
- - Group
- - Service
- - Organization
+ - $ref: '#/components/parameters/followState'
+ - $ref: '#/components/parameters/actorType'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/Follow'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
post:
security:
- OAuth2:
- - admin
+ - admin
tags:
- Instance Follows
- summary: Follow a server
+ summary: Follow a list of actors (PeerTube instance, channel or account)
responses:
'204':
description: successful operation
type: array
items:
type: string
+ format: hostname
uniqueItems: true
- /users:
- post:
- summary: Create a user
- security:
- - OAuth2:
- - admin
- tags:
- - Users
- responses:
- '200':
+ handles:
+ type: array
+ items:
+ type: string
+ uniqueItems: true
+
+ '/server/following/{hostOrHandle}':
+ delete:
+ summary: Unfollow an actor (PeerTube instance, channel or account)
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Instance Follows
+ parameters:
+ - name: hostOrHandle
+ in: path
+ required: true
+ description: The hostOrHandle to unfollow
+ schema:
+ type: string
+ responses:
+ '204':
description: successful operation
+ '404':
+ description: host or handle not found
+
+ /users:
+ post:
+ summary: Create a user
+ operationId: addUser
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Users
+ responses:
+ '200':
+ description: user created
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: User to create
+ 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: []
+ - 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'
type: array
items:
$ref: '#/components/schemas/User'
+
'/users/{id}':
+ parameters:
+ - $ref: '#/components/parameters/id'
delete:
summary: Delete a user
security:
- OAuth2:
- - admin
+ - admin
tags:
- Users
- parameters:
- - $ref: '#/components/parameters/id'
+ operationId: delUser
responses:
'204':
description: successful operation
- OAuth2: []
tags:
- Users
+ operationId: getUser
parameters:
- - $ref: '#/components/parameters/id'
+ - name: withStats
+ in: query
+ description: include statistics about the user (only available as a moderator/admin)
+ schema:
+ type: boolean
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/User'
+ oneOf:
+ - $ref: '#/components/schemas/User'
+ - $ref: '#/components/schemas/UserWithStats'
put:
summary: Update a user
security:
- OAuth2: []
tags:
- Users
- parameters:
- - $ref: '#/components/parameters/id'
+ operationId: putUser
responses:
'204':
description: successful operation
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
+ tags:
+ - Session
+ 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.
+ 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'
+ responses:
+ '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
+ tags:
+ - Session
+ security:
+ - OAuth2: []
+ responses:
+ '200':
+ description: successful operation
+
/users/register:
post:
summary: Register a user
+ operationId: registerUser
tags:
- Users
+ - Register
responses:
'204':
description: successful operation
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'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ verificationString:
+ type: string
+ format: url
+ isPendingEmail:
+ type: boolean
+ required:
+ - verificationString
+ responses:
+ '204':
+ description: successful operation
+ '403':
+ description: invalid verification string
+ '404':
+ description: user not found
+
+ /users/ask-send-verify-email:
+ 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
security:
- OAuth2:
- user
$ref: '#/components/schemas/User'
put:
summary: Update my user information
+ operationId: putUserInfo
security:
- OAuth2:
- user
schema:
$ref: '#/components/schemas/UpdateMe'
required: true
+
/users/me/videos/imports:
get:
summary: Get video imports of my user
security:
- OAuth2:
- - user
+ - user
tags:
- Videos
- My User
content:
application/json:
schema:
- $ref: '#/components/schemas/VideoImport'
+ $ref: '#/components/schemas/VideoImportsList'
+
/users/me/video-quota-used:
get:
summary: Get my user used quota
content:
application/json:
schema:
- type: number
+ 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
+
'/users/me/videos/{videoId}/rating':
get:
summary: Get rate of my user for a video
- name: videoId
in: path
required: true
- description: 'The video id '
+ description: The video id
schema:
- type: string
+ $ref: '#/components/schemas/Video/properties/id'
responses:
'200':
description: successful operation
application/json:
schema:
$ref: '#/components/schemas/GetMeVideoRating'
+
/users/me/videos:
get:
summary: Get videos of my user
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
/users/me/subscriptions:
get:
summary: Get my user subscriptions
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
responses:
'200':
description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoChannelList'
post:
+ tags:
+ - My Subscriptions
summary: Add subscription to my user
security:
- OAuth2:
- - user
- tags:
- - My Subscriptions
+ - user
+ 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
+
/users/me/subscriptions/exist:
get:
summary: Get if subscriptions exist for my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
application/json:
schema:
type: object
+
/users/me/subscriptions/videos:
get:
summary: List videos of subscriptions of my user
- 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/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
'/users/me/subscriptions/{subscriptionHandle}':
get:
summary: Get subscription of my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
summary: Delete subscription of my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
responses:
'200':
description: successful operation
+
/users/me/notifications:
get:
summary: List my notifications
application/json:
schema:
$ref: '#/components/schemas/NotificationListResponse'
+
/users/me/notifications/read:
post:
summary: Mark notifications as read by their id
- My Notifications
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
type: object
properties:
responses:
'204':
description: successful operation
+
/users/me/notifications/read-all:
post:
summary: Mark all my notification as read
responses:
'204':
description: successful operation
+
/users/me/notification-settings:
put:
summary: Update my notification settings
- My Notifications
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
type: object
properties:
$ref: '#/components/schemas/NotificationSettingValue'
newCommentOnMyVideo:
$ref: '#/components/schemas/NotificationSettingValue'
- videoAbuseAsModerator:
+ abuseAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
videoAutoBlacklistAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
responses:
'204':
description: successful operation
+
+ /users/me/history/videos:
+ get:
+ summary: List watched videos history
+ security:
+ - OAuth2: []
+ tags:
+ - My History
+ parameters:
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/search'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoListResponse'
+
+ /users/me/history/videos/{videoId}:
+ delete:
+ summary: Delete history element
+ security:
+ - OAuth2: []
+ tags:
+ - My History
+ parameters:
+ - name: videoId
+ in: path
+ required: true
+ schema:
+ $ref: '#/components/schemas/Video/properties/id'
+ responses:
+ '204':
+ description: successful operation
+
+ /users/me/history/videos/remove:
+ post:
+ summary: Clear video history
+ security:
+ - OAuth2: []
+ tags:
+ - My History
+ requestBody:
+ content:
+ multipart/form-data:
+ 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
content:
application/json:
schema:
- $ref: '#/components/schemas/Avatar'
+ 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:
type: object
properties:
avatarfile:
- description: The file to upload.
+ 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
+
/videos/ownership:
get:
summary: List video ownership changes
responses:
'200':
description: successful operation
+
'/videos/ownership/{id}/accept':
post:
summary: Accept ownership change request
'403':
description: cannot terminate an ownership change of another user
'404':
- description: video owneship change not found
+ description: video ownership change not found
+
'/videos/ownership/{id}/refuse':
post:
summary: Refuse ownership change request
'403':
description: cannot terminate an ownership change of another user
'404':
- description: video owneship change not found
+ description: video ownership change not found
+
'/videos/{id}/give-ownership':
post:
summary: Request ownership change
description: changing video ownership to a remote account is not supported yet
'404':
description: video not found
+
/videos:
get:
summary: List videos
+ operationId: getVideos
tags:
- Video
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/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+
/videos/categories:
get:
summary: List available video categories
+ operationId: getCategories
tags:
- Video
responses:
type: array
items:
type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/categories
+
/videos/licences:
get:
summary: List available video licences
+ operationId: getLicences
tags:
- Video
responses:
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
tags:
- Video
responses:
type: array
items:
type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/languages
+
/videos/privacies:
get:
- summary: List available video privacies
+ summary: List available video privacy policies
+ operationId: getPrivacyPolicies
tags:
- Video
responses:
type: array
items:
type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
+
'/videos/{id}':
put:
summary: Update a video
+ operationId: putVideo
security:
- OAuth2: []
tags:
type: string
format: binary
category:
- description: Video category
- type: string
+ $ref: '#/components/schemas/VideoCategorySet'
licence:
- description: Video licence
- type: string
+ $ref: '#/components/schemas/VideoLicenceSet'
language:
- description: Video language
- type: string
+ $ref: '#/components/schemas/VideoLanguageSet'
privacy:
$ref: '#/components/schemas/VideoPrivacySet'
description:
description: Whether or not we wait transcoding before publish the video
type: string
support:
- description: Text describing how to support the video uploader
+ 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: string
+ 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
maxLength: 30
commentsEnabled:
description: Enable or disable comments for this video
- type: string
+ type: boolean
+ downloadEnabled:
+ description: Enable or disable downloading for this video
+ type: boolean
originallyPublishedAt:
description: Date when the content was originally published
type: string
contentType: image/jpeg
get:
summary: Get a video
+ operationId: getVideo
tags:
- Video
parameters:
$ref: '#/components/schemas/VideoDetails'
delete:
summary: Delete a video
+ operationId: delVideo
security:
- OAuth2: []
tags:
responses:
'204':
description: successful operation
+
'/videos/{id}/description':
get:
summary: Get complete video description
+ operationId: getVideoDesc
tags:
- Video
parameters:
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)**
+
'/videos/{id}/views':
post:
- summary: Add a view to a video
+ summary: Notify user is watching a video
+ description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
+ operationId: addView
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserViewingVideo'
+ required: true
responses:
'204':
description: successful operation
+
'/videos/{id}/watching':
put:
summary: Set watching progress of a video
+ deprecated: true
+ description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
tags:
- Video
security:
content:
application/json:
schema:
- $ref: '#/components/schemas/UserWatchingVideo'
+ $ref: '#/components/schemas/UserViewingVideo'
required: true
responses:
'204':
description: successful operation
- /videos/upload:
- post:
- summary: Upload a video
- security:
+
+ '/videos/{id}/stats/overall':
+ get:
+ summary: Get overall stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsOverall'
+
+ '/videos/{id}/stats/retention':
+ get:
+ summary: Get retention stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsRetention'
+
+ '/videos/{id}/stats/timeseries/{metric}':
+ get:
+ summary: Get timeserie stats of a video
+ tags:
+ - Video Stats
+ security:
+ - OAuth2: []
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ -
+ name: metric
+ in: path
+ required: true
+ description: The metric to get
+ schema:
+ type: string
+ enum:
+ - 'viewers'
+ - 'aggregateWatchTime'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoStatsTimeserie'
+
+ /videos/upload:
+ post:
+ summary: Upload a video
+ description: Uses a single request to upload a video.
+ operationId: uploadLegacy
+ security:
- OAuth2: []
tags:
- Video
+ - Video Upload
responses:
'200':
description: successful operation
schema:
$ref: '#/components/schemas/VideoUploadResponse'
'403':
- description: 'The user video quota is exceeded with this video.'
+ description: video didn't pass upload filter
'408':
- description: 'Upload has timed out'
+ 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 wether 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: 'Invalid input file.'
+ description: video unreadable
requestBody:
content:
multipart/form-data:
schema:
- type: object
- properties:
- videofile:
- description: Video file
- type: string
- format: binary
- channelId:
- description: Channel id that will contain this video
- type: integer
- thumbnailfile:
- description: Video thumbnail file
- type: string
- format: binary
- previewfile:
- description: Video preview file
- type: string
- format: binary
- privacy:
- $ref: '#/components/schemas/VideoPrivacySet'
- category:
- description: Video category
- type: string
- licence:
- description: Video licence
- type: string
- language:
- description: Video language
- type: string
- description:
- description: Video description
- type: string
- waitTranscoding:
- description: Whether or not we wait transcoding before publish the video
- type: string
- support:
- description: Text describing how to support the video uploader
- type: string
- nsfw:
- description: Whether or not this video contains sensitive content
- type: string
- name:
- description: Video name
- type: string
- tags:
- description: Video tags (maximum 5 tags each between 2 and 30 characters)
- type: array
- minItems: 1
- maxItems: 5
- uniqueItems: true
- items:
- type: string
- minLength: 2
- maxLength: 30
- commentsEnabled:
- description: Enable or disable comments for this video
- type: string
- originallyPublishedAt:
- description: Date when the content was originally published
- type: string
- format: date-time
- scheduleUpdate:
- $ref: '#/components/schemas/VideoScheduledUpdate'
- required:
- - videofile
- - channelId
- - name
+ $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
contentType: image/jpeg
previewfile:
contentType: image/jpeg
- x-code-samples:
+ x-codeSamples:
- lang: Shell
source: |
- ## DEPENDENCIES: httpie, jq
- # pip install httpie
+ ## 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"
- API_PATH="https://peertube2.cpy.re/api/v1"
## AUTH
- client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
- client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
- token=$(http -b --form POST "$API_PATH/users/token" \
- client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
- username=$USERNAME \
- password=$PASSWORD \
+ 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
- http -b --form POST "$API_PATH/videos/upload" \
- videofile@$FILE_PATH \
- channelId=$CHANNEL_ID \
- name=$NAME \
- "Authorization:Bearer $token"
+ curl -s "$API/videos/upload" \
+ -H "Authorization: Bearer $token" \
+ --max-time 600 \
+ --form videofile=@"$FILE_PATH" \
+ --form channelId=$CHANNEL_ID \
+ --form name="$NAME"
+
+ /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
+
/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
+
+ /videos/imports/{id}/cancel:
+ post:
+ summary: Cancel video import
+ description: Cancel a pending video import
security:
- OAuth2: []
tags:
+ - Video Imports
+ parameters:
+ - $ref: '#/components/parameters/id'
+ responses:
+ '204':
+ description: successful operation
+
+ /videos/imports/{id}:
+ delete:
+ summary: Delete video import
+ description: Delete ended video import
+ security:
+ - OAuth2: []
+ tags:
+ - Video Imports
+ parameters:
+ - $ref: '#/components/parameters/id'
+ responses:
+ '204':
+ description: successful operation
+
+ /videos/live:
+ post:
+ summary: Create a live
+ 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:
- torrentfile:
- description: Torrent File
- type: string
- format: binary
- targetUrl:
- description: HTTP target URL
- type: string
- magnetUri:
- description: Magnet URI
- type: string
channelId:
- description: Channel id that will contain this video
+ 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: Video thumbnail file
+ description: Live video/replay thumbnail file
type: string
format: binary
previewfile:
- description: Video preview file
+ description: Live video/replay preview file
type: string
format: binary
privacy:
$ref: '#/components/schemas/VideoPrivacySet'
category:
- description: Video category
- type: string
+ $ref: '#/components/schemas/VideoCategorySet'
licence:
- description: Video licence
- type: string
+ $ref: '#/components/schemas/VideoLicenceSet'
language:
- description: Video language
- type: string
+ $ref: '#/components/schemas/VideoLanguageSet'
description:
- description: Video description
- type: string
- waitTranscoding:
- description: Whether or not we wait transcoding before publish the video
+ description: Live video/replay description
type: string
support:
- description: Text describing how to support the video uploader
+ 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 video contains sensitive content
- type: string
+ description: Whether or not this live video/replay contains sensitive content
+ type: boolean
name:
- description: Video name
+ description: Live video/replay name
type: string
+ minLength: 3
+ maxLength: 120
tags:
- description: Video tags (maximum 5 tags each between 2 and 30 characters)
+ description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
type: array
minItems: 1
maxItems: 5
minLength: 2
maxLength: 30
commentsEnabled:
- description: Enable or disable comments for this video
- type: string
- scheduleUpdate:
- $ref: '#/components/schemas/VideoScheduledUpdate'
+ 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:
- torrentfile:
- contentType: application/x-bittorrent
thumbnailfile:
contentType: image/jpeg
previewfile:
contentType: image/jpeg
+
+ /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/VideoUploadResponse'
- '409':
- description: HTTP or Torrent/magnetURI import not enabled
+ $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: '`magnetUri` or `targetUrl` or a torrent file missing'
- /videos/abuse:
+ 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
+
+ /users/me/abuses:
get:
- summary: List video abuses
+ 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'
+
+ /abuses:
+ get:
+ summary: List abuses
+ operationId: getAbuses
security:
- OAuth2:
- admin
- moderator
tags:
- - Video Abuses
+ - 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'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoAbuse'
- '/videos/{id}/abuse':
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Abuse'
post:
summary: Report an abuse
security:
- - OAuth2: []
+ - 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
tags:
- - Video Abuses
- - Videos
+ - Abuses
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/abuseId'
requestBody:
- required: true
content:
application/json:
schema:
type: object
properties:
- reason:
- description: Reason why the user reports this video
+ state:
+ $ref: '#/components/schemas/AbuseStateSet'
+ moderationComment:
type: string
- predefinedReasons:
- description: Reason categories that help triage reports
- type: array
- items:
- type: string
- enum:
- - violentOrAbusive
- - hatefulOrAbusive
- - spamOrMisleading
- - privacy
- - rights
- - serverRules
- - thumbnails
- - captions
- startAt:
- type: integer
- description: Timestamp in the video that marks the beginning of the report
- endAt:
- type: integer
- description: Timestamp in the video that marks the ending of the report
- required:
- - reason
+ description: Update the report comment visible only to the moderation team
+ minLength: 2
+ maxLength: 3000
responses:
'204':
description: successful operation
- '/videos/{id}/abuse/{abuseId}':
- put:
- summary: Update an abuse
+ '404':
+ description: abuse not found
+ delete:
+ tags:
+ - Abuses
+ summary: Delete an abuse
security:
- OAuth2:
- admin
- moderator
- tags:
- - Video Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
responses:
'204':
description: successful operation
'404':
- description: video abuse not found
+ description: block 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'
+ post:
+ summary: Add message to an abuse
+ security:
+ - OAuth2: []
+ tags:
+ - Abuses
parameters:
- - $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/abuseId'
requestBody:
+ required: true
content:
application/json:
schema:
type: object
properties:
- state:
- $ref: '#/components/schemas/VideoAbuseStateSet'
- moderationComment:
+ message:
+ description: Message to send
type: string
- description: 'Update the comment of the video abuse for other admin/moderators'
+ minLength: 2
+ maxLength: 3000
+ required:
+ - message
+ responses:
+ '200':
+ description: successful operation
+ '400':
+ description: incorrect request parameters
+
+ '/abuses/{abuseId}/messages/{abuseMessageId}':
delete:
- summary: Delete an abuse
+ summary: Delete an abuse message
security:
- - OAuth2:
- - admin
- - moderator
+ - OAuth2: []
tags:
- - Video Abuses
+ - Abuses
+ parameters:
+ - $ref: '#/components/parameters/abuseId'
+ - $ref: '#/components/parameters/abuseMessageId'
responses:
'204':
description: successful operation
- '404':
- description: block not found
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
- - $ref: '#/components/parameters/abuseId'
'/videos/{id}/blacklist':
post:
summary: Block a video
+ operationId: addVideoBlock
security:
- OAuth2:
- - admin
- - moderator
+ - admin
+ - moderator
tags:
- Video Blocks
parameters:
description: successful operation
delete:
summary: Unblock a video by its id
+ operationId: delVideoBlock
security:
- OAuth2:
- - admin
- - moderator
+ - admin
+ - moderator
tags:
- Video Blocks
parameters:
description: successful operation
'404':
description: block not found
+
/videos/blacklist:
get:
tags:
- Video Blocks
summary: List video blocks
+ operationId: getVideoBlocks
security:
- OAuth2:
- - admin
- - moderator
+ - 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'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoBlacklist'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoBlacklist'
+
/videos/{id}/captions:
get:
summary: List captions of a video
+ operationId: getVideoCaptions
tags:
- - Video Caption
+ - Video Captions
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
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 Caption
+ - Video Captions
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/captionLanguage'
description: video or language not found
delete:
summary: Delete a video caption
+ operationId: delVideoCaption
+ security:
+ - OAuth2:
+ - user
tags:
- - Video Caption
+ - Video Captions
parameters:
- $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/captionLanguage'
description: successful operation
'404':
description: video or language or caption for that language not found
+
/video-channels:
get:
summary: List video channels
+ operationId: getVideoChannels
tags:
- Video Channels
parameters:
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoChannel'
+ $ref: '#/components/schemas/VideoChannelList'
post:
summary: Create a video channel
+ operationId: addVideoChannel
security:
- OAuth2: []
tags:
responses:
'204':
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'
+
'/video-channels/{channelHandle}':
get:
summary: Get a video channel
+ operationId: getVideoChannel
tags:
- Video Channels
parameters:
$ref: '#/components/schemas/VideoChannel'
put:
summary: Update a video channel
+ operationId: putVideoChannel
security:
- OAuth2: []
tags:
$ref: '#/components/schemas/VideoChannelUpdate'
delete:
summary: Delete a video channel
+ operationId: delVideoChannel
security:
- OAuth2: []
tags:
responses:
'204':
description: successful operation
+
'/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/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '/video-channels/{channelHandle}/followers':
+ get:
+ tags:
+ - Video Channels
+ summary: 'List followers of a video channel'
+ security:
+ - OAuth2: []
+ operationId: getVideoChannelFollowers
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/followersSort'
+ - $ref: '#/components/parameters/search'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Follow'
+
+ '/video-channels/{channelHandle}/avatar/pick':
+ post:
+ summary: Update channel avatar
+ 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
+
+ '/video-channels/{channelHandle}/avatar':
+ delete:
+ summary: Delete channel avatar
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
+ '/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
+
+ '/video-channels/{channelHandle}/banner':
+ delete:
+ summary: Delete channel banner
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
/video-playlists/privacies:
get:
- summary: List available playlist privacies
+ summary: List available playlist privacy policies
+ operationId: getPlaylistPrivacyPolicies
tags:
- Video Playlists
responses:
type: array
items:
type: string
+ examples:
+ nightly:
+ externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
/video-playlists:
get:
summary: List video playlists
+ operationId: getPlaylists
tags:
- Video Playlists
parameters:
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoPlaylist'
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
post:
summary: Create a video playlist
- description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
+ description: If the video playlist is set as public, `videoChannelId` is mandatory.
+ operationId: addPlaylist
security:
- OAuth2: []
tags:
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/VideoPlaylist/properties/id'
uuid:
- type: string
+ $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
+ shortUUID:
+ $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
requestBody:
content:
multipart/form-data:
displayName:
description: Video playlist display name
type: string
+ minLength: 1
+ maxLength: 120
thumbnailfile:
description: Video playlist thumbnail file
type: string
description:
description: Video playlist description
type: string
+ minLength: 3
+ maxLength: 1000
videoChannelId:
+ allOf:
+ - $ref: '#/components/schemas/id'
description: Video channel in which the playlist will be published
- type: integer
required:
- displayName
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
- /video-playlists/{id}:
+ /video-playlists/{playlistId}:
get:
summary: Get a video playlist
tags:
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
responses:
'200':
description: successful operation
'204':
description: successful operation
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
requestBody:
content:
multipart/form-data:
displayName:
description: Video playlist display name
type: string
+ minLength: 1
+ maxLength: 120
thumbnailfile:
description: Video playlist thumbnail file
type: string
description: Video playlist description
type: string
videoChannelId:
+ allOf:
+ - $ref: '#/components/schemas/id'
description: Video channel in which the playlist will be published
- type: integer
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
delete:
summary: Delete a video playlist
security:
tags:
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
responses:
'204':
description: successful operation
- /video-playlists/{id}/videos:
+ /video-playlists/{playlistId}/videos:
get:
summary: 'List videos of a playlist'
+ operationId: getVideoPlaylistVideos
tags:
- Videos
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
responses:
'200':
description: successful operation
schema:
$ref: '#/components/schemas/VideoListResponse'
post:
- summary: 'Add a video in a playlist'
+ summary: Add a video in a playlist
+ operationId: addVideoPlaylistVideo
security:
- OAuth2: []
tags:
- Videos
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
responses:
'200':
description: successful operation
properties:
id:
type: integer
+ example: 2
requestBody:
content:
application/json:
type: object
properties:
videoId:
- type: integer
- description: 'Video to add in the playlist'
+ oneOf:
+ - $ref: '#/components/schemas/Video/properties/uuid'
+ - $ref: '#/components/schemas/Video/properties/id'
+ description: Video to add in the playlist
startTimestamp:
type: integer
- description: 'Start the video at this specific timestamp (in seconds)'
+ format: seconds
+ description: Start the video at this specific timestamp
stopTimestamp:
type: integer
- description: 'Stop the video at this specific timestamp (in seconds)'
+ format: seconds
+ description: Stop the video at this specific timestamp
required:
- videoId
- /video-playlists/{id}/videos/reorder:
+ /video-playlists/{playlistId}/videos/reorder:
post:
summary: 'Reorder a playlist'
+ operationId: reorderVideoPlaylist
security:
- OAuth2: []
tags:
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
responses:
'204':
description: successful operation
- startPosition
- insertAfterPosition
- /video-playlists/{id}/videos/{playlistElementId}:
+ /video-playlists/{playlistId}/videos/{playlistElementId}:
put:
- summary: 'Update a playlist element'
+ summary: Update a playlist element
+ operationId: putVideoPlaylistVideo
security:
- OAuth2: []
tags:
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
- $ref: '#/components/parameters/playlistElementId'
responses:
'204':
properties:
startTimestamp:
type: integer
- description: 'Start the video at this specific timestamp (in seconds)'
+ format: seconds
+ description: Start the video at this specific timestamp
stopTimestamp:
type: integer
- description: 'Stop the video at this specific timestamp (in seconds)'
+ format: seconds
+ description: Stop the video at this specific timestamp
delete:
- summary: 'Delete an element from a playlist'
+ summary: Delete an element from a playlist
+ operationId: delVideoPlaylistVideo
security:
- OAuth2: []
tags:
- Video Playlists
parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - $ref: '#/components/parameters/playlistId'
- $ref: '#/components/parameters/playlistElementId'
responses:
'204':
'/users/me/video-playlists/videos-exist':
get:
- summary: 'Check video exists in my playlists'
+ summary: Check video exists in my playlists
security:
- OAuth2: []
tags:
schema:
type: array
items:
- type: integer
+ $ref: '#/components/schemas/Video/properties/id'
responses:
'200':
description: successful operation
type: integer
startTimestamp:
type: integer
+ format: seconds
stopTimestamp:
type: integer
+ format: seconds
'/accounts/{name}/video-channels':
get:
- Accounts
parameters:
- $ref: '#/components/parameters/name'
+ - name: withStats
+ in: query
+ description: include view statistics for the last 30 days (only if authentified as the account user)
+ schema:
+ type: boolean
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoChannel'
+ $ref: '#/components/schemas/VideoChannelList'
+
'/accounts/{name}/ratings':
get:
summary: List ratings of an account
type: array
items:
$ref: '#/components/schemas/VideoRating'
+
'/videos/{id}/comment-threads':
get:
summary: List threads of a video
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ '404':
+ description: video does not exist
requestBody:
content:
application/json:
type: object
properties:
text:
- type: string
- description: 'Text comment'
+ allOf:
+ - $ref: '#/components/schemas/VideoComment/properties/text'
+ format: markdown
+ maxLength: 10000
required:
- text
application/json:
schema:
$ref: '#/components/schemas/VideoCommentThreadTree'
+
'/videos/{id}/comments/{commentId}':
post:
summary: Reply to a thread of a video
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ '404':
+ description: thread or video does not exist
requestBody:
content:
application/json:
type: object
properties:
text:
- type: string
- description: 'Text comment'
+ allOf:
+ - $ref: '#/components/schemas/VideoComment/properties/text'
+ format: markdown
+ maxLength: 10000
required:
- text
-
delete:
summary: Delete a comment or a reply
security:
responses:
'204':
description: successful operation
+ '403':
+ description: cannot remove comment of another user
+ '404':
+ description: comment or video does not exist
+ '409':
+ description: comment is already deleted
+
'/videos/{id}/rate':
put:
summary: Like/dislike a video
- Video Rates
parameters:
- $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ rating:
+ type: string
+ enum:
+ - like
+ - dislike
+ required:
+ - rating
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+
+ '/videos/{id}/hls':
+ delete:
+ summary: Delete video HLS files
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Files
+ operationId: delVideoHLS
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+ '/videos/{id}/webtorrent':
+ delete:
+ summary: Delete video WebTorrent files
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Files
+ operationId: delVideoWebTorrent
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: video does not exist
+
+ '/videos/{id}/transcoding':
+ post:
+ summary: Create a transcoding job
+ security:
+ - OAuth2:
+ - admin
+ tags:
+ - Video Transcoding
+ operationId: createVideoTranscoding
+ parameters:
+ - $ref: '#/components/parameters/idOrUUID'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ transcodingType:
+ type: string
+ enum:
+ - hls
+ - webtorrent
+ required:
+ - transcodingType
responses:
'204':
description: successful operation
+ '404':
+ description: video does not exist
+
/search/videos:
get:
tags:
- Search
summary: Search videos
+ operationId: searchVideos
parameters:
+ - name: search
+ in: query
+ required: true
+ allowEmptyValue: false
+ description: >
+ String to search. If the user can make a remote URI search, and the string is an URI then the
+ PeerTube instance will fetch the remote object and add it to its database. Then,
+ you can use the REST API to fetch the complete video information and interact with it.
+ 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/filter'
+ - $ref: '#/components/parameters/isLocal'
+ - $ref: '#/components/parameters/include'
+ - $ref: '#/components/parameters/privacyOneOf'
+ - $ref: '#/components/parameters/hasHLSFiles'
+ - $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/searchTarget'
- $ref: '#/components/parameters/videosSearchSort'
- - name: search
- in: query
- required: true
- description: >
- String to search. If the user can make a remote URI search, and the string is an URI then the
- PeerTube instance will fetch the remote object and add it to its database. Then,
- you can use the REST API to fetch the complete video information and interact with it.
- schema:
- type: string
- name: startDate
in: query
- required: true
description: Get videos that are published after this date
schema:
type: string
format: date-time
- name: endDate
in: query
- required: true
description: Get videos that are published before this date
schema:
type: string
format: date-time
- name: originallyPublishedStartDate
in: query
- required: true
description: Get videos that are originally published after this date
schema:
type: string
format: date-time
- name: originallyPublishedEndDate
in: query
- required: true
description: Get videos that are originally published before this date
schema:
type: string
format: date-time
- name: durationMin
in: query
- required: true
description: Get videos that have this minimum duration
schema:
type: integer
- name: durationMax
in: query
- required: true
description: Get videos that have this maximum duration
schema:
type: integer
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
responses:
'200':
description: successful operation
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '500':
+ description: search index unavailable
+
/search/video-channels:
get:
tags:
- Search
summary: Search channels
+ operationId: searchChannels
parameters:
+ - name: search
+ in: query
+ required: true
+ description: >
+ String to search. If the user can make a remote URI search, and the string is an URI then the
+ PeerTube instance will fetch the remote object and add it to its database. Then,
+ you can use the REST API to fetch the complete channel information and interact with it.
+ schema:
+ type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/searchTarget'
- $ref: '#/components/parameters/sort'
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoChannelList'
+ '500':
+ description: search index unavailable
+
+ /search/video-playlists:
+ get:
+ tags:
+ - Search
+ summary: Search playlists
+ operationId: searchPlaylists
+ parameters:
- name: search
in: query
required: true
description: >
String to search. If the user can make a remote URI search, and the string is an URI then the
PeerTube instance will fetch the remote object and add it to its database. Then,
- you can use the REST API to fetch the complete channel information and interact with it.
+ you can use the REST API to fetch the complete playlist information and interact with it.
schema:
type: string
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/searchTarget'
+ - $ref: '#/components/parameters/sort'
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
responses:
'200':
description: successful operation
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoChannel'
- /blocklist/accounts:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
+ '500':
+ description: search index unavailable
+
+ /blocklist/status:
+ get:
+ tags:
+ - Account Blocks
+ - Server Blocks
+ summary: Get block status of accounts/hosts
+ parameters:
+ -
+ name: 'accounts'
+ in: query
+ description: 'Check if these accounts are blocked'
+ example: [ 'goofy@example.com', 'donald@example.com' ]
+ schema:
+ type: array
+ items:
+ type: string
+ -
+ name: 'hosts'
+ in: query
+ description: 'Check if these hosts are blocked'
+ example: [ 'example.com' ]
+ schema:
+ type: array
+ items:
+ type: string
+ responses:
+ '200':
+ description: successful operation
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/schemas/BlockStatus'
+
+ /server/blocklist/accounts:
get:
tags:
- Account Blocks
properties:
accountName:
type: string
+ example: chocobozzz@example.org
description: account to block, in the form `username@domain`
required:
- accountName
description: successful operation
'409':
description: self-blocking forbidden
- '/blocklist/accounts/{accountName}':
+
+ '/server/blocklist/accounts/{accountName}':
delete:
tags:
- Account Blocks
description: successful operation
'404':
description: account or account block does not exist
- /blocklist/servers:
+
+ /server/blocklist/servers:
get:
tags:
- Server Blocks
schema:
type: object
properties:
- accountName:
+ host:
type: string
+ format: hostname
description: server domain to block
required:
- - accountName
+ - host
+ responses:
+ '204':
+ description: successful operation
+ '409':
+ description: self-blocking forbidden
+
+ '/server/blocklist/servers/{host}':
+ delete:
+ tags:
+ - Server Blocks
+ summary: Unblock a server by its domain
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - name: host
+ in: path
+ required: true
+ description: server domain to unblock
+ schema:
+ type: string
+ format: hostname
+ responses:
+ '204':
+ description: successful operation
+ '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: self-blocking forbidden
- '/blocklist/servers/{host}':
+ description: video is already mirrored
+
+ /server/redundancy/videos/{redundancyId}:
delete:
tags:
- - Server Blocks
- summary: Unblock a server by its domain
+ - Video Mirroring
+ summary: Delete a mirror done on a video
+ operationId: delMirroredVideo
security:
- OAuth2:
- admin
parameters:
- - name: host
+ - name: redundancyId
in: path
required: true
- description: server domain to unblock
+ description: id of an existing redundancy on a video
schema:
type: string
responses:
- '201':
+ '204':
description: successful operation
'404':
- description: account block does not exist
+ description: video redundancy not found
+
'/feeds/video-comments.{format}':
get:
tags:
- Feeds
summary: List comments on videos
- servers:
- - url: 'https://peertube2.cpy.re'
- description: Live Test Server (live data - latest nightly version)
- - url: 'https://peertube3.cpy.re'
- description: Live Test Server (live data - latest RC version)
- - url: 'https://peertube.cpy.re'
- description: Live Test Server (live data - stable version)
+ operationId: getSyndicatedComments
parameters:
- name: format
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+ 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:
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:
'204':
description: successful operation
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
+
'/feeds/videos.{format}':
get:
tags:
- Feeds
summary: List videos
- servers:
- - url: 'https://peertube2.cpy.re'
- description: Live Test Server (live data - latest nightly version)
- - url: 'https://peertube3.cpy.re'
- description: Live Test Server (live data - latest RC version)
- - url: 'https://peertube.cpy.re'
- description: Live Test Server (live data - stable version)
+ operationId: getSyndicatedVideos
parameters:
- name: format
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+ 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:
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:
+ '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:
+ 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
+
+ '/feeds/subscriptions.{format}':
+ get:
+ tags:
+ - Feeds
+ - Account
+ summary: List videos of subscriptions tied to a token
+ operationId: getSyndicatedSubscriptionVideos
+ 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
+ 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:
'204':
description: successful operation
type: object
'406':
description: accept header unsupported
+
+ /plugins:
+ get:
+ tags:
+ - Plugins
+ summary: List plugins
+ operationId: getPlugins
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - name: pluginType
+ in: query
+ schema:
+ type: integer
+ - name: uninstalled
+ in: query
+ schema:
+ 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/PluginResponse'
+
+ /plugins/available:
+ get:
+ tags:
+ - Plugins
+ summary: List available plugins
+ operationId: getAvailablePlugins
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - name: search
+ in: query
+ schema:
+ type: string
+ - name: pluginType
+ in: query
+ schema:
+ type: integer
+ - name: currentPeerTubeEngine
+ in: query
+ schema:
+ type: string
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PluginResponse'
+ '503':
+ description: plugin index unavailable
+
+ /plugins/install:
+ post:
+ tags:
+ - Plugins
+ summary: Install a plugin
+ operationId: addPlugin
+ security:
+ - OAuth2:
+ - admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - type: object
+ properties:
+ npmName:
+ type: string
+ example: peertube-plugin-auth-ldap
+ required:
+ - npmName
+ additionalProperties: false
+ - type: object
+ properties:
+ path:
+ type: string
+ required:
+ - path
+ additionalProperties: false
+ responses:
+ '204':
+ description: successful operation
+ '400':
+ description: should have either `npmName` or `path` set
+
+ /plugins/update:
+ post:
+ tags:
+ - Plugins
+ summary: Update a plugin
+ operationId: updatePlugin
+ security:
+ - OAuth2:
+ - admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - type: object
+ properties:
+ npmName:
+ type: string
+ example: peertube-plugin-auth-ldap
+ required:
+ - npmName
+ additionalProperties: false
+ - type: object
+ properties:
+ path:
+ type: string
+ required:
+ - path
+ additionalProperties: false
+ responses:
+ '204':
+ description: successful operation
+ '400':
+ description: should have either `npmName` or `path` set
+ '404':
+ description: existing plugin not found
+
+ /plugins/uninstall:
+ post:
+ tags:
+ - Plugins
+ summary: Uninstall a plugin
+ operationId: uninstallPlugin
+ security:
+ - OAuth2:
+ - admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ npmName:
+ type: string
+ description: name of the plugin/theme in its package.json
+ example: peertube-plugin-auth-ldap
+ required:
+ - npmName
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: existing plugin not found
+
+ /plugins/{npmName}:
+ get:
+ tags:
+ - Plugins
+ summary: Get a plugin
+ operationId: getPlugin
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - $ref: '#/components/parameters/npmName'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Plugin'
+ '404':
+ description: plugin not found
+
+ /plugins/{npmName}/settings:
+ put:
+ tags:
+ - Plugins
+ summary: Set a plugin's settings
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - $ref: '#/components/parameters/npmName'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ settings:
+ type: object
+ additionalProperties: true
+ responses:
+ '204':
+ description: successful operation
+ '404':
+ description: plugin not found
+
+ /plugins/{npmName}/public-settings:
+ get:
+ tags:
+ - Plugins
+ summary: Get a plugin's public settings
+ parameters:
+ - $ref: '#/components/parameters/npmName'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ additionalProperties: true
+ '404':
+ description: plugin not found
+
+ /plugins/{npmName}/registered-settings:
+ get:
+ tags:
+ - Plugins
+ summary: Get a plugin's registered settings
+ security:
+ - OAuth2:
+ - admin
+ parameters:
+ - $ref: '#/components/parameters/npmName'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ additionalProperties: true
+ '404':
+ description: plugin not found
+
servers:
- url: 'https://peertube2.cpy.re/api/v1'
description: Live Test Server (live data - latest nightly version)
description: Offset used to paginate results
schema:
type: integer
+ minimum: 0
count:
name: count
in: query
description: "Number of items to return"
schema:
type: integer
+ default: 15
maximum: 100
minimum: 1
sort:
name: sort
in: query
required: false
- description: Sort column (`-createdAt` for example)
+ description: Sort column
+ schema:
+ type: string
+ example: -createdAt
+ search:
+ name: search
+ in: query
+ required: false
+ description: Plain text search, applied to various parts of the model depending on endpoint
schema:
type: string
searchTarget:
**Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
- It means the instance may not know the objects you fetched. If you want to load video/channel information:
+ It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
* If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
- * If the current user has not the ability to make a remote URI search, then redirect the user on the origin instance or fetch
+ * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch
the data from the origin instance API
schema:
type: string
schema:
type: string
enum:
- - -name
+ - name
- -duration
- -createdAt
- -publishedAt
- -views
- -likes
- -trending
+ - -hot
videosSearchSort:
name: sort
in: query
schema:
type: string
enum:
- - -name
+ - name
- -duration
- -createdAt
- -publishedAt
name: sort
in: query
required: false
- description: Sort blacklists by criteria
+ description: Sort blocklists by criteria
schema:
type: string
enum:
- -id
- - -name
+ - name
- -duration
- -views
- -likes
- -dislikes
- -uuid
- -createdAt
+ usersSearch:
+ name: search
+ in: query
+ required: false
+ description: Plain text search that will match with user usernames or emails
+ schema:
+ type: string
+ usersBlocked:
+ name: blocked
+ in: query
+ required: false
+ description: Filter results down to (un)banned users
+ schema:
+ type: boolean
usersSort:
name: sort
in: query
- -id
- -createdAt
- -state
+ videoRedundanciesSort:
+ name: sort
+ in: query
+ required: false
+ description: Sort abuses by criteria
+ schema:
+ type: string
+ enum:
+ - name
+ followersSort:
+ name: sort
+ in: query
+ required: false
+ description: Sort followers by criteria
+ schema:
+ type: string
+ enum:
+ - createdAt
name:
name: name
in: path
required: true
- description: >-
- The name of the account (`chocobozzz` or `chocobozzz@example.org` for
- example)
+ description: The username or handle of the account
schema:
type: string
+ example: chocobozzz | chocobozzz@example.org
id:
name: id
in: path
required: true
- description: The user id
+ description: Entity id
schema:
- type: integer
+ $ref: '#/components/schemas/id'
idOrUUID:
name: id
in: path
required: true
- description: The object id or uuid
+ description: The object id, uuid or short uuid
schema:
- type: string
+ oneOf:
+ - $ref: '#/components/schemas/id'
+ - $ref: '#/components/schemas/UUIDv4'
+ - $ref: '#/components/schemas/shortUUID'
+ playlistId:
+ name: playlistId
+ in: path
+ required: true
+ description: Playlist id
+ schema:
+ $ref: '#/components/schemas/VideoPlaylist/properties/id'
playlistElementId:
name: playlistElementId
in: path
required: true
description: Playlist element id
schema:
- type: integer
+ $ref: '#/components/schemas/id'
abuseId:
name: abuseId
in: path
required: true
- description: Video abuse id
+ description: Abuse id
schema:
- type: integer
+ $ref: '#/components/schemas/Abuse/properties/id'
+ abuseMessageId:
+ name: abuseMessageId
+ in: path
+ required: true
+ description: Abuse message id
+ schema:
+ $ref: '#/components/schemas/AbuseMessage/properties/id'
captionLanguage:
name: captionLanguage
in: path
required: true
description: The caption language
schema:
- type: string
+ $ref: '#/components/schemas/VideoLanguageSet'
channelHandle:
name: channelHandle
in: path
required: true
- description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
+ description: The video channel handle
schema:
type: string
+ example: my_username | my_username@example.com
subscriptionHandle:
name: subscriptionHandle
in: path
required: true
- description: "The subscription handle (example: 'my_username@example.com' or 'my_username')"
+ description: The subscription handle
schema:
type: string
+ example: my_username | my_username@example.com
threadId:
name: threadId
in: path
required: true
description: The comment id
schema:
- type: integer
+ $ref: '#/components/schemas/VideoComment/properties/id'
+ isLive:
+ name: isLive
+ in: query
+ required: false
+ description: whether or not the video is a live
+ schema:
+ type: boolean
categoryOneOf:
name: categoryOneOf
in: query
required: false
- description: category id of the video (see /videos/categories)
+ description: category id of the video (see [/videos/categories](#operation/getCategories))
schema:
oneOf:
- - type: integer
+ - $ref: '#/components/schemas/VideoCategorySet'
- type: array
items:
- type: integer
+ $ref: '#/components/schemas/VideoCategorySet'
style: form
explode: false
tagsOneOf:
oneOf:
- type: string
- type: array
+ maxItems: 5
items:
type: string
style: form
name: languageOneOf
in: query
required: false
- description: language id of the video (see /videos/languages). Use `_unknown` to filter on videos that don't have a video language
+ description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
schema:
oneOf:
- - type: string
+ - $ref: '#/components/schemas/VideoLanguageSet'
- type: array
items:
- type: string
+ $ref: '#/components/schemas/VideoLanguageSet'
style: form
explode: false
licenceOneOf:
name: licenceOneOf
in: query
required: false
- description: licence id of the video (see /videos/licences)
+ description: licence id of the video (see [/videos/licences](#operation/getLicences))
schema:
oneOf:
- - type: integer
+ - $ref: '#/components/schemas/VideoLicenceSet'
- type: array
items:
- type: integer
+ $ref: '#/components/schemas/VideoLicenceSet'
style: form
explode: false
skipCount:
enum:
- 'true'
- 'false'
- filter:
- name: filter
+ isLocal:
+ name: isLocal
in: query
required: false
- description: >
- Special filters (local for instance) which might require special rights:
- * `local` - only videos local to the instance
- * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
schema:
- type: string
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only local or remote videos'
+ hasHLSFiles:
+ name: hasHLSFiles
+ in: query
+ required: false
+ schema:
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only videos that have HLS files'
+ hasWebtorrentFiles:
+ name: hasWebtorrentFiles
+ in: query
+ required: false
+ schema:
+ type: boolean
+ description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
+ privacyOneOf:
+ name: privacyOneOf
+ in: query
+ required: false
+ schema:
+ $ref: '#/components/schemas/VideoPrivacySet'
+ description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
+ include:
+ name: include
+ in: query
+ required: false
+ schema:
+ type: integer
enum:
- - local
- - all-local
+ - 0
+ - 1
+ - 2
+ - 4
+ - 8
+ description: >
+ **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
+
+ - `0` NONE
+
+ - `1` NOT_PUBLISHED_STATE
+
+ - `2` BLACKLISTED
+
+ - `4` BLOCKED_OWNER
+
+ - `8` FILES
subscriptionsUris:
name: uris
in: query
type: array
items:
type: string
+ format: uri
+ npmName:
+ name: npmName
+ in: path
+ required: true
+ description: name of the plugin/theme on npmjs.com or in its package.json
+ schema:
+ type: string
+ example: peertube-plugin-auth-ldap
+ jobType:
+ name: jobType
+ in: query
+ required: false
+ description: job type
+ schema:
+ type: string
+ enum:
+ - activitypub-follow
+ - activitypub-http-broadcast
+ - activitypub-http-fetcher
+ - activitypub-http-unicast
+ - email
+ - video-transcoding
+ - video-file-import
+ - video-import
+ - videos-views-stats
+ - activitypub-refresher
+ - video-redundancy
+ - video-live-ending
+ followState:
+ name: state
+ in: query
+ schema:
+ type: string
+ enum:
+ - pending
+ - accepted
+ actorType:
+ name: actorType
+ in: query
+ schema:
+ type: string
+ enum:
+ - Person
+ - Application
+ - Group
+ - Service
+ - Organization
securitySchemes:
OAuth2:
- description: >
- In the header: *Authorization: Bearer <token\>*
-
-
+ description: |
Authenticating via OAuth requires the following steps:
+ - Have an activated account
+ - [Generate] an access token for that account at `/api/v1/users/token`.
+ - Make requests with the *Authorization: Bearer <token\>* header
+ - Profit, depending on the role assigned to the account
+ Note that the __access token is valid for 1 day__ and is given
+ along with a __refresh token valid for 2 weeks__.
- - Have an account with sufficient authorization levels
-
- - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
- Bearer Token
-
- - Make Authenticated Requests
+ [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
type: oauth2
flows:
password:
- tokenUrl: 'https://peertube.example.com/api/v1/users/token'
+ tokenUrl: /api/v1/users/token
scopes:
admin: Admin scope
moderator: Moderator scope
user: User scope
schemas:
- VideoConstantNumber:
+ # Resuable core properties
+ id:
+ type: integer
+ minimum: 1
+ example: 42
+ UUIDv4:
+ type: string
+ format: uuid
+ example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+ minLength: 36
+ maxLength: 36
+ shortUUID:
+ type: string
+ description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
+ example: 2y84q2MQUMWPbiEcxNXMgC
+ username:
+ type: string
+ description: immutable name of the user, used to find or mention its actor
+ example: chocobozzz
+ pattern: '/^[a-z0-9._]+$/'
+ minLength: 1
+ maxLength: 50
+ usernameChannel:
+ type: string
+ description: immutable name of the channel, used to interact with its actor
+ example: framasoft_videos
+ pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
+ minLength: 1
+ maxLength: 50
+ password:
+ type: string
+ format: password
+ minLength: 6
+ maxLength: 255
+
+ VideoCategorySet:
+ type: integer
+ description: category id of the video (see [/videos/categories](#operation/getCategories))
+ example: 15
+ VideoConstantNumber-Category:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/VideoCategorySet'
label:
type: string
- VideoConstantString:
+ example: Science & Technology
+
+ VideoLicenceSet:
+ type: integer
+ description: licence id of the video (see [/videos/licences](#operation/getLicences))
+ example: 2
+ VideoConstantNumber-Licence:
properties:
id:
+ $ref: '#/components/schemas/VideoLicenceSet'
+ label:
type: string
+ example: Attribution - Share Alike
+
+ VideoLanguageSet:
+ type: string
+ description: language id of the video (see [/videos/languages](#operation/getLanguages))
+ example: en
+ VideoConstantString-Language:
+ properties:
+ id:
+ $ref: '#/components/schemas/VideoLanguageSet'
label:
type: string
+ example: English
VideoPlaylistPrivacySet:
type: integer
- 1
- 2
- 3
- description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
+ description: Video playlist privacy policy (see [/video-playlists/privacies])
VideoPlaylistPrivacyConstant:
properties:
id:
enum:
- 1
- 2
- description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
+ description: The video playlist type (Regular = `1`, Watch Later = `2`)
VideoPlaylistTypeConstant:
properties:
id:
- 2
- 3
- 4
- description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
+ description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
VideoPrivacyConstant:
properties:
id:
label:
type: string
+ BlockStatus:
+ properties:
+ accounts:
+ type: object
+ additionalProperties:
+ x-additionalPropertiesName: account
+ type: object
+ properties:
+ blockedByServer:
+ type: boolean
+ blockedByUser:
+ type: boolean
+ hosts:
+ type: object
+ additionalProperties:
+ x-additionalPropertiesName: host
+ type: object
+ properties:
+ blockedByServer:
+ type: boolean
+ blockedByUser:
+ type: boolean
+
NSFWPolicy:
type: string
enum:
- 1
- 2
description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
+ example: 2
+ UserAdminFlags:
+ type: integer
+ enum:
+ - 0
+ - 1
+ description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
+ example: 1
+
+ LiveVideoLatencyMode:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
VideoStateConstant:
properties:
label:
type: string
- VideoAbuseStateSet:
+ AbuseStateSet:
type: integer
enum:
- 1
- 2
- 3
- description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
- VideoAbuseStateConstant:
+ description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+ AbuseStateConstant:
properties:
id:
- $ref: '#/components/schemas/VideoAbuseStateSet'
+ $ref: '#/components/schemas/AbuseStateSet'
label:
type: string
- VideoAbusePredefinedReasons:
+ AbusePredefinedReasons:
type: array
items:
type: string
- serverRules
- thumbnails
- captions
+ example: [spamOrMisleading]
+
+ VideoResolutionSet:
+ type: integer
+ description: |
+ Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
+ `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
+ example: 240
VideoResolutionConstant:
+ description: resolutions and their labels for the video
properties:
id:
- type: integer
- description: 'Video resolution (240, 360, 720 ...)'
+ $ref: '#/components/schemas/VideoResolutionSet'
label:
type: string
+ example: 240p
VideoScheduledUpdate:
properties:
privacy:
type: string
url:
type: string
+ format: url
host:
type: string
- avatar:
- nullable: true
- allOf:
- - $ref: '#/components/schemas/Avatar'
+ format: hostname
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
VideoChannelSummary:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
name:
type: string
displayName:
type: string
url:
type: string
+ format: url
host:
type: string
- avatar:
- nullable: true
- allOf:
- - $ref: '#/components/schemas/Avatar'
+ format: hostname
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
PlaylistElement:
properties:
position:
type: integer
startTimestamp:
type: integer
+ format: seconds
stopTimestamp:
type: integer
+ format: seconds
video:
nullable: true
allOf:
- $ref: '#/components/schemas/Video'
VideoFile:
+ readOnly: true
properties:
magnetUri:
type: string
+ format: uri
+ description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
+ pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
resolution:
$ref: '#/components/schemas/VideoResolutionConstant'
size:
type: integer
- description: 'Video file size in bytes'
+ description: Video file size in bytes
torrentUrl:
type: string
+ description: Direct URL of the torrent file
+ format: url
torrentDownloadUrl:
type: string
+ description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
+ format: url
fileUrl:
type: string
+ description: Direct URL of the video
+ format: url
fileDownloadUrl:
type: string
+ description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
+ format: url
fps:
type: number
+ description: Frames per second of the video file
metadataUrl:
type: string
+ format: url
+ description: URL dereferencing the output of ffprobe on the file
VideoStreamingPlaylists:
+ allOf:
+ - type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ type:
+ type: integer
+ enum:
+ - 1
+ description: |
+ Playlist type:
+ - `1`: HLS
+ - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
+ VideoStreamingPlaylists-HLS:
properties:
- id:
- type: integer
- type:
- type: integer
- enum:
- - 1
- description: 'Playlist type (HLS = `1`)'
playlistUrl:
type: string
+ format: url
segmentsSha256Url:
type: string
+ format: url
files:
type: array
+ description: |
+ Video files associated to this playlist.
+
+ The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
items:
$ref: '#/components/schemas/VideoFile'
redundancies:
properties:
baseUrl:
type: string
+ format: url
VideoInfo:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/Video/properties/id'
uuid:
- type: string
+ $ref: '#/components/schemas/Video/properties/uuid'
name:
- type: string
+ $ref: '#/components/schemas/Video/properties/name'
Video:
properties:
id:
- type: integer
+ description: object id for the video
+ allOf:
+ - $ref: '#/components/schemas/id'
uuid:
- type: string
+ description: universal identifier for the video, that can be used across instances
+ allOf:
+ - $ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ allOf:
+ - $ref: '#/components/schemas/shortUUID'
+ isLive:
+ type: boolean
createdAt:
type: string
+ format: date-time
+ example: 2017-10-01T10:52:46.396Z
+ description: time at which the video object was first drafted
publishedAt:
type: string
+ format: date-time
+ example: 2018-10-01T10:52:46.396Z
+ description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
updatedAt:
type: string
+ format: date-time
+ example: 2021-05-04T08:01:01.502Z
+ description: last time the video's metadata was modified
originallyPublishedAt:
type: string
+ format: date-time
+ example: 2010-10-01T10:52:46.396Z
+ description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
category:
- $ref: '#/components/schemas/VideoConstantNumber'
+ allOf:
+ - $ref: '#/components/schemas/VideoConstantNumber-Category'
+ description: category in which the video is classified
licence:
- $ref: '#/components/schemas/VideoConstantNumber'
+ allOf:
+ - $ref: '#/components/schemas/VideoConstantNumber-Licence'
+ description: licence under which the video is distributed
language:
- $ref: '#/components/schemas/VideoConstantString'
+ allOf:
+ - $ref: '#/components/schemas/VideoConstantString-Language'
+ description: main language used in the video
privacy:
- $ref: '#/components/schemas/VideoPrivacyConstant'
+ allOf:
+ - $ref: '#/components/schemas/VideoPrivacyConstant'
+ description: privacy policy used to distribute the video
description:
type: string
+ 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)**\r\n*A decentralized video hosting network, based on fr...
+ minLength: 3
+ maxLength: 250
+ description: |
+ truncated description of the video, written in Markdown.
+ Resolve `descriptionPath` to get the full description of maximum `10000` characters.
duration:
type: integer
+ example: 1419
+ format: seconds
+ description: duration of the video in seconds
isLocal:
type: boolean
name:
type: string
+ description: title of the video
+ example: What is PeerTube?
+ minLength: 3
+ maxLength: 120
thumbnailPath:
type: string
+ example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
previewPath:
type: string
+ example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
embedPath:
type: string
+ example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
views:
type: integer
+ example: 1337
likes:
type: integer
+ example: 42
dislikes:
type: integer
+ example: 7
nsfw:
type: boolean
waitTranscoding:
type: boolean
nullable: true
state:
- $ref: '#/components/schemas/VideoStateConstant'
+ allOf:
+ - $ref: '#/components/schemas/VideoStateConstant'
+ description: represents the internal state of the video processing within the PeerTube instance
scheduledUpdate:
nullable: true
allOf:
- $ref: '#/components/schemas/Video'
- type: object
properties:
+ viewers:
+ type: integer
+ description: If the video is a live, you have the amount of current viewers
descriptionPath:
type: string
+ example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
+ description: path at which to get the full description of maximum `10000` characters
support:
type: string
+ description: A text tell the audience how to support the video creator
+ example: Please support our work on https://soutenir.framasoft.org/en/ <3
+ minLength: 3
+ maxLength: 1000
channel:
$ref: '#/components/schemas/VideoChannel'
account:
$ref: '#/components/schemas/Account'
tags:
+ example: [flowers, gardening]
type: array
+ minItems: 1
+ maxItems: 5
items:
type: string
- files:
- type: array
- items:
- $ref: '#/components/schemas/VideoFile'
+ minLength: 2
+ maxLength: 30
commentsEnabled:
type: boolean
downloadEnabled:
type: array
items:
type: string
+ format: url
+ example:
+ - https://peertube2.cpy.re/tracker/announce
+ - wss://peertube2.cpy.re/tracker/socket
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoFile'
+ description: |
+ WebTorrent/raw video files. If WebTorrent is disabled on the server:
+
+ - field will be empty
+ - video files will be found in `streamingPlaylists[].files` field
streamingPlaylists:
type: array
items:
$ref: '#/components/schemas/VideoStreamingPlaylists'
+ description: |
+ HLS playlists/manifest files. If HLS is disabled on the server:
+
+ - field will be empty
+ - video files will be found in `files` field
+ FileRedundancyInformation:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ fileUrl:
+ type: string
+ format: url
+ strategy:
+ type: string
+ enum:
+ - manual
+ - most-views
+ - trending
+ - recently-added
+ size:
+ type: integer
+ createdAt:
+ type: string
+ format: date-time
+ updatedAt:
+ type: string
+ format: date-time
+ expiresOn:
+ type: string
+ format: date-time
+ VideoRedundancy:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ name:
+ type: string
+ url:
+ type: string
+ format: url
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
+ redundancies:
+ type: object
+ properties:
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/FileRedundancyInformation'
+ streamingPlaylists:
+ type: array
+ items:
+ $ref: '#/components/schemas/FileRedundancyInformation'
VideoImportStateConstant:
properties:
id:
description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
label:
type: string
+ example: Pending
+ VideoCreateImport:
+ allOf:
+ - type: object
+ additionalProperties: false
+ oneOf:
+ - properties:
+ targetUrl:
+ $ref: '#/components/schemas/VideoImport/properties/targetUrl'
+ required: [targetUrl]
+ - properties:
+ magnetUri:
+ $ref: '#/components/schemas/VideoImport/properties/magnetUri'
+ required: [magnetUri]
+ - properties:
+ torrentfile:
+ $ref: '#/components/schemas/VideoImport/properties/torrentfile'
+ required: [torrentfile]
+ - $ref: '#/components/schemas/VideoUploadRequestCommon'
+ required:
+ - channelId
+ - name
VideoImport:
properties:
id:
- type: integer
+ readOnly: true
+ allOf:
+ - $ref: '#/components/schemas/id'
targetUrl:
type: string
+ format: url
+ description: remote URL where to find the import's source video
+ example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
magnetUri:
type: string
+ format: uri
+ description: magnet URI allowing to resolve the import's source video
+ pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
+ torrentfile:
+ writeOnly: true
+ type: string
+ format: binary
+ description: Torrent file containing only the video file
torrentName:
+ readOnly: true
type: string
state:
- type: object
- properties:
- id:
- $ref: '#/components/schemas/VideoImportStateConstant'
- label:
- type: string
+ readOnly: true
+ allOf:
+ - $ref: '#/components/schemas/VideoImportStateConstant'
error:
+ readOnly: true
type: string
createdAt:
+ readOnly: true
type: string
+ format: date-time
updatedAt:
+ readOnly: true
type: string
+ format: date-time
video:
- $ref: '#/components/schemas/Video'
- VideoAbuse:
+ readOnly: true
+ nullable: true
+ allOf:
+ - $ref: '#/components/schemas/Video'
+ VideoImportsList:
properties:
- id:
+ total:
type: integer
+ example: 1
+ data:
+ type: array
+ maxItems: 100
+ items:
+ $ref: '#/components/schemas/VideoImport'
+ Abuse:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
reason:
type: string
+ example: The video is a spam
+ minLength: 2
+ maxLength: 3000
predefinedReasons:
- $ref: '#/components/schemas/VideoAbusePredefinedReasons'
+ $ref: '#/components/schemas/AbusePredefinedReasons'
reporterAccount:
$ref: '#/components/schemas/Account'
state:
- $ref: '#/components/schemas/VideoAbuseStateConstant'
+ $ref: '#/components/schemas/AbuseStateConstant'
moderationComment:
type: string
- video:
- type: object
- properties:
- id:
- type: integer
- name:
- type: string
- uuid:
- type: string
+ example: Decided to ban the server since it spams us regularly
+ minLength: 2
+ maxLength: 3000
+ video:
+ $ref: '#/components/schemas/VideoInfo'
+ createdAt:
+ type: string
+ format: date-time
+ AbuseMessage:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ message:
+ type: string
+ minLength: 2
+ maxLength: 3000
+ byModerator:
+ type: boolean
createdAt:
type: string
+ format: date-time
+ account:
+ $ref: '#/components/schemas/AccountSummary'
VideoBlacklist:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
videoId:
- type: integer
+ $ref: '#/components/schemas/Video/properties/id'
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
+ format: date-time
name:
type: string
+ minLength: 3
+ maxLength: 120
uuid:
- type: string
+ $ref: '#/components/schemas/UUIDv4'
description:
type: string
+ minLength: 3
+ maxLength: 10000
duration:
type: integer
views:
type: integer
nsfw:
type: boolean
- VideoChannel:
- properties:
- displayName:
- type: string
- description:
- type: string
- isLocal:
- type: boolean
- ownerAccount:
- type: object
- properties:
- id:
- type: integer
- uuid:
- type: string
VideoPlaylist:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
+ shortUUID:
+ allOf:
+ - $ref: '#/components/schemas/shortUUID'
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
+ format: date-time
description:
type: string
- uuid:
- type: string
+ minLength: 3
+ maxLength: 1000
displayName:
type: string
+ minLength: 1
+ maxLength: 120
isLocal:
type: boolean
videoLength:
type: integer
+ minimum: 0
thumbnailPath:
type: string
privacy:
VideoComment:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
url:
type: string
+ format: url
text:
type: string
+ format: html
+ description: Text of the comment
+ minLength: 1
+ example: This video is wonderful!
threadId:
- type: integer
+ $ref: '#/components/schemas/id'
inReplyToCommentId:
- type: integer
+ nullable: true
+ allOf:
+ - $ref: '#/components/schemas/id'
videoId:
- type: integer
+ $ref: '#/components/schemas/Video/properties/id'
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
+ format: date-time
+ deletedAt:
+ nullable: true
+ type: string
+ format: date-time
+ default: null
+ isDeleted:
+ type: boolean
+ default: false
totalRepliesFromVideoAuthor:
type: integer
+ minimum: 0
totalReplies:
type: integer
+ minimum: 0
account:
$ref: '#/components/schemas/Account'
VideoCommentThreadTree:
VideoCaption:
properties:
language:
- $ref: '#/components/schemas/VideoConstantString'
+ $ref: '#/components/schemas/VideoConstantString-Language'
captionPath:
type: string
- Avatar:
+ ActorImage:
properties:
path:
type: string
+ width:
+ type: integer
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
+ format: date-time
ActorInfo:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
name:
type: string
displayName:
type: string
host:
type: string
- avatar:
- nullable: true
- type: object
- properties:
- path:
- type: string
+ format: hostname
+ avatars:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
Actor:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
url:
type: string
+ format: url
name:
- type: string
+ description: immutable name of the actor, used to find or mention it
+ allOf:
+ - $ref: '#/components/schemas/username'
host:
type: string
+ format: hostname
+ description: server on which the actor is resident
+ hostRedundancyAllowed:
+ type: boolean
+ description: whether this actor's host allows redundancy of its videos
followingCount:
type: integer
+ minimum: 0
+ description: number of actors subscribed to by this actor, as seen by this instance
followersCount:
type: integer
+ minimum: 0
+ description: number of followers of this actor, as seen by this instance
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
- avatar:
- $ref: '#/components/schemas/Avatar'
+ format: date-time
Account:
allOf:
- $ref: '#/components/schemas/Actor'
- properties:
userId:
- type: string
+ description: object id for the user tied to this account
+ allOf:
+ - $ref: '#/components/schemas/User/properties/id'
displayName:
type: string
+ description: editable name of the account, displayed in its representations
+ minLength: 3
+ maxLength: 120
description:
type: string
- User:
+ description: text or bio displayed on the account's profile
+ UserViewingVideo:
+ required:
+ - currentTime
properties:
- id:
+ currentTime:
type: integer
- username:
- type: string
- email:
- type: string
- theme:
- type: string
- description: 'Theme enabled by this user'
- emailVerified:
- type: boolean
- description: 'Has the user confirmed their email address?'
- nsfwPolicy:
- $ref: '#/components/schemas/NSFWPolicy'
- webtorrentEnabled:
- type: boolean
- autoPlayVideo:
- type: boolean
- description: 'Automatically start playing the video on the watch page'
- role:
- $ref: '#/components/schemas/UserRole'
- roleLabel:
+ format: seconds
+ description: timestamp within the video, in seconds
+ example: 5
+ viewEvent:
type: string
enum:
- - User
- - Moderator
- - Administrator
- videoQuota:
- type: integer
- videoQuotaDaily:
- type: integer
- videosCount:
- type: integer
- videoAbusesCount:
- type: integer
- videoAbusesAcceptedCount:
- type: integer
- videoAbusesCreatedCount:
- type: integer
- videoCommentsCount:
- type: integer
- noInstanceConfigWarningModal:
- type: boolean
- noWelcomeModal:
- type: boolean
- blocked:
- type: boolean
- blockedReason:
- type: string
- createdAt:
+ - seek
+ description: >
+ Event since last viewing call:
+ * `seek` - If the user seeked the video
+
+ VideoStatsOverall:
+ properties:
+ averageWatchTime:
+ type: number
+ totalWatchTime:
+ type: number
+ viewersPeak:
+ type: number
+ viewersPeakDate:
type: string
- account:
- $ref: '#/components/schemas/Account'
- videoChannels:
+ format: date-time
+ views:
+ type: number
+ likes:
+ type: number
+ dislikes:
+ type: number
+ comments:
+ type: number
+ countries:
type: array
items:
- $ref: '#/components/schemas/VideoChannel'
- UserWatchingVideo:
+ type: object
+ properties:
+ isoCode:
+ type: string
+ viewers:
+ type: number
+
+ VideoStatsRetention:
properties:
- currentTime:
- type: integer
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ second:
+ type: number
+ retentionPercent:
+ type: number
+
+ VideoStatsTimeserie:
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ date:
+ type: string
+ value:
+ type: number
+
ServerConfig:
properties:
instance:
enabledResolutions:
type: array
items:
- type: integer
+ $ref: '#/components/schemas/VideoResolutionSet'
import:
type: object
properties:
properties:
videoQuota:
type: integer
+ example: 16810141515
videoQuotaDaily:
type: integer
+ example: 1681014151
trending:
type: object
properties:
properties:
indexUrl:
type: string
+ format: url
+ homepage:
+ type: object
+ properties:
+ enabled:
+ type: boolean
+
ServerConfigAbout:
properties:
instance:
properties:
email:
type: string
+ format: email
contactForm:
type: object
properties:
type: boolean
user:
type: object
+ description: Settings that apply to new users, if registration is enabled
properties:
videoQuota:
type: integer
+ example: 16810141515
videoQuotaDaily:
type: integer
+ example: 1681014151
transcoding:
type: object
+ description: Settings pertaining to transcoding jobs
properties:
enabled:
type: boolean
allowAdditionalExtensions:
type: boolean
+ description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
allowAudioFiles:
type: boolean
+ description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
threads:
type: integer
+ description: Amount of threads used by ffmpeg for 1 transcoding job
+ concurrency:
+ type: number
+ description: Amount of transcoding jobs to execute in parallel
+ profile:
+ type: string
+ enum:
+ - default
+ description: |
+ New profiles can be added by plugins ; available in core PeerTube: 'default'.
resolutions:
type: object
+ description: Resolutions to transcode _new videos_ to
properties:
+ 0p:
+ type: boolean
+ 144p:
+ type: boolean
240p:
type: boolean
360p:
type: boolean
1080p:
type: boolean
+ 1440p:
+ type: boolean
2160p:
type: boolean
+ webtorrent:
+ type: object
+ description: WebTorrent-specific settings
+ properties:
+ enabled:
+ type: boolean
hls:
type: object
+ description: HLS-specific settings
properties:
enabled:
type: boolean
type: boolean
manualApproval:
type: boolean
+
+ CustomHomepage:
+ properties:
+ content:
+ type: string
+
Follow:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
follower:
$ref: '#/components/schemas/Actor'
following:
$ref: '#/components/schemas/Actor'
score:
type: number
+ description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
state:
type: string
enum:
- accepted
createdAt:
type: string
+ format: date-time
updatedAt:
type: string
+ format: date-time
+
+ PredefinedAbuseReasons:
+ description: Reason categories that help triage reports
+ type: array
+ maxItems: 8
+ items:
+ type: string
+ enum:
+ - violentOrAbusive
+ - hatefulOrAbusive
+ - spamOrMisleading
+ - privacy
+ - rights
+ - serverRules
+ - thumbnails
+ - captions
+
Job:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
state:
type: string
enum:
- - pending
- - processing
- - error
- - success
- category:
+ - active
+ - completed
+ - failed
+ - waiting
+ - delayed
+ type:
type: string
enum:
- - transcoding
- - activitypub-http
- handlerName:
- type: string
- handlerInputData:
- type: string
+ - activitypub-http-unicast
+ - activitypub-http-broadcast
+ - activitypub-http-fetcher
+ - activitypub-follow
+ - video-file-import
+ - video-transcoding
+ - email
+ - video-import
+ - videos-views-stats
+ - activitypub-refresher
+ - video-redundancy
+ data:
+ type: object
+ additionalProperties: true
+ error:
+ type: object
+ additionalProperties: true
createdAt:
type: string
- updatedAt:
+ format: date-time
+ finishedOn:
+ type: string
+ format: date-time
+ processedOn:
type: string
+ format: date-time
AddUserResponse:
properties:
- id:
+ user:
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ account:
+ type: object
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ VideoUploadRequestCommon:
+ properties:
+ name:
+ description: Video name
+ type: string
+ example: What is PeerTube?
+ minLength: 3
+ maxLength: 120
+ channelId:
+ description: Channel id that will contain this video
type: integer
- uuid:
+ example: 3
+ minimum: 1
+ privacy:
+ $ref: '#/components/schemas/VideoPrivacySet'
+ category:
+ $ref: '#/components/schemas/VideoCategorySet'
+ licence:
+ $ref: '#/components/schemas/VideoLicenceSet'
+ language:
+ $ref: '#/components/schemas/VideoLanguageSet'
+ description:
+ description: Video description
+ type: string
+ 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)**
+ waitTranscoding:
+ description: Whether or not we wait transcoding before publish the video
+ type: boolean
+ 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
+ tags:
+ description: Video tags (maximum 5 tags each between 2 and 30 characters)
+ type: array
+ minItems: 1
+ maxItems: 5
+ uniqueItems: true
+ example:
+ - framasoft
+ - peertube
+ 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'
+ thumbnailfile:
+ description: Video thumbnail file
+ type: string
+ format: binary
+ previewfile:
+ description: Video preview file
type: string
+ format: binary
+ required:
+ - channelId
+ - name
+ VideoUploadRequestLegacy:
+ allOf:
+ - $ref: '#/components/schemas/VideoUploadRequestCommon'
+ - type: object
+ required:
+ - videofile
+ properties:
+ videofile:
+ description: Video file
+ type: string
+ format: binary
+ VideoUploadRequestResumable:
+ allOf:
+ - $ref: '#/components/schemas/VideoUploadRequestCommon'
+ - type: object
+ required:
+ - filename
+ properties:
+ filename:
+ description: Video filename including extension
+ type: string
+ format: filename
+ example: what_is_peertube.mp4
+ thumbnailfile:
+ description: Video thumbnail file
+ type: string
+ format: binary
+ previewfile:
+ description: Video preview file
+ type: string
+ format: binary
VideoUploadResponse:
properties:
video:
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/Video/properties/id'
uuid:
- type: string
+ $ref: '#/components/schemas/Video/properties/uuid'
+ shortUUID:
+ $ref: '#/components/schemas/Video/properties/shortUUID'
CommentThreadResponse:
properties:
total:
type: integer
+ example: 1
data:
type: array
+ maxItems: 100
items:
$ref: '#/components/schemas/VideoComment'
CommentThreadPostResponse:
properties:
total:
type: integer
+ example: 1
data:
type: array
+ maxItems: 100
items:
$ref: '#/components/schemas/Video'
- AddUser:
+ User:
properties:
- username:
+ account:
+ $ref: '#/components/schemas/Account'
+ autoPlayNextVideo:
+ type: boolean
+ description: Automatically start playing the upcoming video after the currently playing video
+ autoPlayNextVideoPlaylist:
+ type: boolean
+ description: Automatically start playing the video on the playlist after the currently playing video
+ autoPlayVideo:
+ type: boolean
+ description: Automatically start playing the video on the watch page
+ blocked:
+ type: boolean
+ blockedReason:
type: string
- description: 'The user username'
- minLength: 1
- maxLength: 50
- password:
+ createdAt:
type: string
- description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent'
- minLength: 6
- maxLength: 255
email:
type: string
- description: 'The user email. MUST be in the format of an email address.'
- videoQuota:
+ format: email
+ description: The user email
+ emailVerified:
+ type: boolean
+ description: Has the user confirmed their email address?
+ id:
+ allOf:
+ - $ref: '#/components/schemas/id'
+ readOnly: true
+ pluginAuth:
+ type: string
+ description: Auth plugin to use to authenticate the user
+ lastLoginDate:
+ type: string
+ format: date-time
+ noInstanceConfigWarningModal:
+ type: boolean
+ noAccountSetupWarningModal:
+ type: boolean
+ noWelcomeModal:
+ type: boolean
+ nsfwPolicy:
+ $ref: '#/components/schemas/NSFWPolicy'
+ role:
+ $ref: '#/components/schemas/UserRole'
+ roleLabel:
+ type: string
+ enum:
+ - User
+ - Moderator
+ - Administrator
+ theme:
type: string
- description: 'The user video quota'
+ description: Theme enabled by this user
+ username:
+ $ref: '#/components/schemas/username'
+ videoChannels:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoChannel'
+ videoQuota:
+ type: integer
+ description: The user video quota in bytes
+ example: -1
videoQuotaDaily:
+ type: integer
+ description: The user daily video quota in bytes
+ example: -1
+ p2pEnabled:
+ type: boolean
+ description: Enable P2P in the player
+ UserWithStats:
+ allOf:
+ - $ref: '#/components/schemas/User'
+ - properties:
+ # optionally present fields: they require WITH_STATS scope
+ videosCount:
+ type: integer
+ description: Count of videos published
+ abusesCount:
+ type: integer
+ description: Count of reports/abuses of which the user is a target
+ abusesAcceptedCount:
+ type: integer
+ description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
+ abusesCreatedCount:
+ type: integer
+ description: Count of reports/abuses created by the user
+ videoCommentsCount:
+ type: integer
+ description: Count of comments published
+ AddUser:
+ properties:
+ username:
+ $ref: '#/components/schemas/username'
+ password:
+ $ref: '#/components/schemas/password'
+ email:
type: string
- description: 'The user daily video quota'
+ format: email
+ description: The user email
+ videoQuota:
+ type: integer
+ description: The user video quota in bytes
+ example: -1
+ videoQuotaDaily:
+ type: integer
+ description: The user daily video quota in bytes
+ example: -1
+ channelName:
+ $ref: '#/components/schemas/usernameChannel'
role:
$ref: '#/components/schemas/UserRole'
+ adminFlags:
+ $ref: '#/components/schemas/UserAdminFlags'
required:
- username
- password
- role
UpdateUser:
properties:
- id:
- type: string
- description: 'The user id'
email:
- type: string
- description: 'The updated email of the user'
+ description: The updated email of the user
+ allOf:
+ - $ref: '#/components/schemas/User/properties/email'
+ emailVerified:
+ type: boolean
+ description: Set the email as verified
videoQuota:
- type: string
- description: 'The updated video quota of the user'
+ type: integer
+ description: The updated video quota of the user in bytes
videoQuotaDaily:
+ type: integer
+ description: The updated daily video quota of the user in bytes
+ pluginAuth:
type: string
- description: 'The updated daily video quota of the user'
+ nullable: true
+ description: The auth plugin to use to authenticate the user
+ example: 'peertube-plugin-auth-saml2'
role:
$ref: '#/components/schemas/UserRole'
- required:
- - id
- - email
- - videoQuota
- - videoQuotaDaily
- - role
+ adminFlags:
+ $ref: '#/components/schemas/UserAdminFlags'
+ password:
+ $ref: '#/components/schemas/password'
UpdateMe:
+ # see shared/models/users/user-update-me.model.ts:
properties:
password:
- type: string
- description: 'Your new password'
+ $ref: '#/components/schemas/password'
+ currentPassword:
+ $ref: '#/components/schemas/password'
email:
+ description: new email used for login and service communications
+ allOf:
+ - $ref: '#/components/schemas/User/properties/email'
+ displayName:
type: string
- description: 'Your new email'
+ description: new name of the user in its representations
+ minLength: 3
+ maxLength: 120
displayNSFW:
type: string
- description: 'Your new displayNSFW'
+ description: new NSFW display policy
+ enum:
+ - 'true'
+ - 'false'
+ - both
+ p2pEnabled:
+ type: boolean
+ description: whether to enable P2P in the player or not
autoPlayVideo:
+ type: boolean
+ description: new preference regarding playing videos automatically
+ autoPlayNextVideo:
+ type: boolean
+ description: new preference regarding playing following videos automatically
+ autoPlayNextVideoPlaylist:
+ type: boolean
+ description: new preference regarding playing following playlist videos automatically
+ videosHistoryEnabled:
+ type: boolean
+ description: whether to keep track of watched history or not
+ videoLanguages:
+ type: array
+ items:
+ type: string
+ description: list of languages to filter videos down to
+ theme:
type: string
- description: 'Your new autoPlayVideo'
- required:
- - password
- - email
- - displayNSFW
- - autoPlayVideo
+ noInstanceConfigWarningModal:
+ type: boolean
+ noAccountSetupWarningModal:
+ type: boolean
+ noWelcomeModal:
+ type: boolean
GetMeVideoRating:
properties:
id:
- type: string
- description: 'Id of the video'
+ $ref: '#/components/schemas/id'
rating:
- type: number
- description: 'Rating of the video'
+ type: string
+ enum:
+ - like
+ - dislike
+ - none
+ description: Rating of the video
required:
- id
- rating
video:
$ref: '#/components/schemas/Video'
rating:
- type: number
- description: 'Rating of the video'
+ type: string
+ enum:
+ - like
+ - dislike
+ - none
+ description: Rating of the video
required:
- video
- rating
RegisterUser:
properties:
username:
- type: string
- description: 'The username of the user'
+ description: immutable name of the user, used to find or mention its actor
+ allOf:
+ - $ref: '#/components/schemas/username'
password:
- type: string
- description: 'The password of the user'
+ $ref: '#/components/schemas/password'
email:
type: string
- description: 'The email of the user'
+ format: email
+ description: email of the user, used for login or service communications
displayName:
type: string
- description: 'The user display name'
+ description: editable name of the user, displayed in its representations
+ minLength: 1
+ maxLength: 120
channel:
type: object
+ description: channel base information used to create the first channel of the user
properties:
name:
- type: string
- description: 'The name for the default channel'
+ $ref: '#/components/schemas/usernameChannel'
displayName:
type: string
- description: 'The display name for the default channel'
-
required:
- username
- password
- email
- VideoChannelCreate:
+
+ OAuthClient:
properties:
- name:
- type: string
- displayName:
- type: string
- description:
- type: string
- support:
- type: string
- description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+ client_id:
+ type: string
+ pattern: /^[a-z0-9]$/
+ maxLength: 32
+ minLength: 32
+ example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
+ client_secret:
+ type: string
+ pattern: /^[a-zA-Z0-9]$/
+ maxLength: 32
+ minLength: 32
+ example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
+ OAuthToken-password:
+ allOf:
+ - $ref: '#/components/schemas/OAuthClient'
+ - type: object
+ properties:
+ grant_type:
+ type: string
+ enum:
+ - password
+ - refresh_token
+ default: password
+ username:
+ $ref: '#/components/schemas/User/properties/username'
+ password:
+ $ref: '#/components/schemas/password'
+ required:
+ - client_id
+ - client_secret
+ - grant_type
+ - username
+ - password
+ OAuthToken-refresh_token:
+ allOf:
+ - $ref: '#/components/schemas/OAuthClient'
+ - type: object
+ properties:
+ grant_type:
+ type: string
+ enum:
+ - password
+ - refresh_token
+ default: password
+ refresh_token:
+ type: string
+ example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
+ required:
+ - client_id
+ - client_secret
+ - grant_type
+ - refresh_token
+
+ VideoChannel:
+ allOf:
+ - $ref: '#/components/schemas/Actor'
+ - type: object
+ properties:
+ displayName:
+ type: string
+ description: editable name of the channel, displayed in its representations
+ example: Videos of Framasoft
+ minLength: 1
+ maxLength: 120
+ description:
+ type: string
+ example: Videos made with <3 by Framasoft
+ minLength: 3
+ maxLength: 1000
+ support:
+ type: string
+ description: text shown by default on all videos of this channel, to tell the audience how to support it
+ example: Please support our work on https://soutenir.framasoft.org/en/ <3
+ minLength: 3
+ maxLength: 1000
+ isLocal:
+ readOnly: true
+ type: boolean
+ updatedAt:
+ readOnly: true
+ type: string
+ format: date-time
+ banners:
+ type: array
+ items:
+ $ref: '#/components/schemas/ActorImage'
+ ownerAccount:
+ readOnly: true
+ nullable: true
+ type: object
+ properties:
+ id:
+ type: integer
+ uuid:
+ $ref: '#/components/schemas/UUIDv4'
+ VideoChannelCreate:
+ allOf:
+ - $ref: '#/components/schemas/VideoChannel'
+ - properties:
+ name:
+ description: username of the channel to create
+ allOf:
+ - $ref: '#/components/schemas/usernameChannel'
required:
- name
- displayName
VideoChannelUpdate:
+ allOf:
+ - $ref: '#/components/schemas/VideoChannel'
+ - properties:
+ bulkVideosSupportUpdate:
+ type: boolean
+ description: Update the support field for all videos of this channel
+ VideoChannelList:
properties:
- displayName:
- type: string
- description:
- type: string
- support:
- type: string
- description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
- bulkVideosSupportUpdate:
- type: boolean
- description: 'Update the support field for all videos of this channel'
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/VideoChannel'
+ - $ref: '#/components/schemas/Actor'
MRSSPeerLink:
type: object
properties:
url:
type: string
+ format: url
xml:
attribute: true
fileSize:
properties:
link:
type: string
+ format: url
guid:
type: string
pubDate:
properties:
link:
type: string
+ format: url
description: video watch page URL
guid:
type: string
properties:
url:
type: string
+ format: url
description: video embed path, relative to the canonical URL domain (MRSS)
xml:
attribute: true
properties:
url:
type: string
+ format: url
description: video watch path, relative to the canonical URL domain (MRSS)
xml:
attribute: true
properties:
url:
type: string
+ format: url
xml:
attribute: true
height:
properties:
url:
type: string
+ format: url
xml:
attribute: true
type:
type: integer
description: >
Notification type
+
- `0` NONE
+
- `1` WEB
+
- `2` EMAIL
enum:
- 0
- 1
- - 3
+ - 2
Notification:
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
type:
type: integer
description: >
Notification type, following the `UserNotificationType` enum:
+
- `1` NEW_VIDEO_FROM_SUBSCRIPTION
+
- `2` NEW_COMMENT_ON_MY_VIDEO
- - `3` NEW_VIDEO_ABUSE_FOR_MODERATORS
+
+ - `3` NEW_ABUSE_FOR_MODERATORS
+
- `4` BLACKLIST_ON_MY_VIDEO
+
- `5` UNBLACKLIST_ON_MY_VIDEO
+
- `6` MY_VIDEO_PUBLISHED
+
- `7` MY_VIDEO_IMPORT_SUCCESS
+
- `8` MY_VIDEO_IMPORT_ERROR
+
- `9` NEW_USER_REGISTRATION
+
- `10` NEW_FOLLOW
+
- `11` COMMENT_MENTION
+
- `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
+
- `13` NEW_INSTANCE_FOLLOWER
+
- `14` AUTO_INSTANCE_FOLLOWING
+
+ - `15` ABUSE_STATE_CHANGE
+
+ - `16` ABUSE_NEW_MESSAGE
+
+ - `17` NEW_PLUGIN_VERSION
+
+ - `18` NEW_PEERTUBE_VERSION
read:
type: boolean
video:
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
video:
nullable: true
$ref: '#/components/schemas/VideoInfo'
type: string
nullable: true
magnetUri:
- type: string
- nullable: true
+ $ref: '#/components/schemas/VideoImport/properties/magnetUri'
targetUri:
type: string
+ format: uri
nullable: true
comment:
nullable: true
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
threadId:
type: integer
video:
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
video:
allOf:
- $ref: '#/components/schemas/VideoInfo'
type: object
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
video:
allOf:
- $ref: '#/components/schemas/VideoInfo'
nullable: true
properties:
id:
- type: integer
+ $ref: '#/components/schemas/id'
follower:
$ref: '#/components/schemas/ActorInfo'
state:
type: string
host:
type: string
+ format: hostname
createdAt:
type: string
format: date-time
properties:
total:
type: integer
+ example: 1
+ data:
+ type: array
+ maxItems: 100
+ items:
+ $ref: '#/components/schemas/Notification'
+ Plugin:
+ properties:
+ name:
+ type: string
+ example: peertube-plugin-auth-ldap
+ type:
+ type: integer
+ description: >
+ - `1`: PLUGIN
+
+ - `2`: THEME
+ enum:
+ - 1
+ - 2
+ latestVersion:
+ type: string
+ example: 0.0.3
+ version:
+ type: string
+ example: 0.0.1
+ enabled:
+ type: boolean
+ uninstalled:
+ type: boolean
+ peertubeEngine:
+ type: string
+ example: 2.2.0
+ description:
+ type: string
+ homepage:
+ type: string
+ format: url
+ example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
+ settings:
+ type: object
+ additionalProperties: true
+ createdAt:
+ type: string
+ format: date-time
+ updatedAt:
+ type: string
+ format: date-time
+ PluginResponse:
+ properties:
+ total:
+ type: integer
+ example: 1
data:
type: array
+ maxItems: 100
items:
- $ref: '#/components/schemas/Notification'
\ No newline at end of file
+ $ref: '#/components/schemas/Plugin'
+
+ LiveVideoUpdate:
+ properties:
+ 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'
+
+ LiveVideoResponse:
+ properties:
+ rtmpUrl:
+ type: string
+ rtmpsUrl:
+ type: string
+ streamKey:
+ type: string
+ description: RTMP stream key to use to stream into this live video
+ 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'
+
+ callbacks:
+ searchIndex:
+ 'https://search.example.org/api/v1/search/videos':
+ post:
+ summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoListResponse'
projects / github / Chocobozzz / PeerTube.git / blobdiff