Skip to content
Permalink
develop
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time
openapi: 3.0.0
info:
title: PeerTube
version: 4.0.0
contact:
name: PeerTube Community
url: https://joinpeertube.org
license:
name: AGPLv3.0
url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
x-logo:
url: https://joinpeertube.org/img/brand.png
altText: PeerTube Project Homepage
description: |
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)
which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
- [Python](https://framagit.org/framasoft/peertube/clients/python)
- [Go](https://framagit.org/framasoft/peertube/clients/go)
- [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
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 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, 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
{
"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/*` |
| `/.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: >
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. 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
options.
- name: Job
description: >
Jobs are long-running tasks enqueued and processed by the instance
itself. No additional worker registration is currently available.
- name: Instance Follows
description: >
Managing servers which the instance interacts with is crucial to the
concept of federation in PeerTube and external video indexation. The PeerTube
server then deals with inter-server ActivityPub operations and propagates
information across its social graph by posting activities to actors' inbox
endpoints.
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: |
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 resource containing a single supported video file
- _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
The import function is practical when the desired video/audio is available online. It makes PeerTube
download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
- name: Video Imports
description: Operations dealing with listing, adding and removing video imports.
- name: Channels Sync
description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms
- 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: Video Feeds
description: Server syndication feeds of videos
- name: Search
description: |
The search helps to find _videos_ or _channels_ from within the instance and beyond.
Videos from other instances federated by the instance (that is, instances
followed by the instance) can be found via keywords and other criteria of
the advanced search.
Administrators can also enable the use of a remote search system, indexing
videos and channels not could be not federated by the instance.
- 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).
- name: Stats
description: |
Statistics
x-tagGroups:
- name: Static endpoints
tags:
- Static Video Files
- name: Feeds
tags:
- Video Feeds
- name: Auth
tags:
- Register
- Session
- name: Accounts
tags:
- Accounts
- Users
- My User
- My Subscriptions
- My Notifications
- My History
- name: Videos
tags:
- Video
- Video Upload
- Video Imports
- Video Captions
- Video Channels
- Video Comments
- Video Rates
- Video Playlists
- Video Stats
- Video Ownership Change
- Video Mirroring
- Video Files
- Video Transcoding
- Live Videos
- Channels Sync
- name: Search
tags:
- Search
- name: Moderation
tags:
- Abuses
- Video Blocks
- Account Blocks
- Server Blocks
- name: Instance
tags:
- Config
- Homepage
- Instance Follows
- Instance Redundancy
- Plugins
- Stats
- Logs
- Job
paths:
'/static/webseed/{filename}':
get:
tags:
- Static Video Files
summary: Get public WebTorrent video file
parameters:
- $ref: '#/components/parameters/staticFilename'
responses:
'200':
description: successful operation
'404':
description: not found
'/static/webseed/private/{filename}':
get:
tags:
- Static Video Files
summary: Get private WebTorrent video file
parameters:
- $ref: '#/components/parameters/staticFilename'
- $ref: '#/components/parameters/videoFileToken'
security:
- OAuth2: []
responses:
'200':
description: successful operation
'403':
description: invalid auth
'404':
description: not found
'/static/streaming-playlists/hls/{filename}':
get:
tags:
- Static Video Files
summary: Get public HLS video file
parameters:
- $ref: '#/components/parameters/staticFilename'
security:
- OAuth2: []
responses:
'200':
description: successful operation
'403':
description: invalid auth
'404':
description: not found
'/static/streaming-playlists/hls/private/{filename}':
get:
tags:
- Static Video Files
summary: Get private HLS video file
parameters:
- $ref: '#/components/parameters/staticFilename'
- $ref: '#/components/parameters/videoFileToken'
- $ref: '#/components/parameters/reinjectVideoFileToken'
security:
- OAuth2: []
responses:
'200':
description: successful operation
'403':
description: invalid auth
'404':
description: not found
'/feeds/video-comments.{format}':
get:
tags:
- Video Feeds
summary: List comments on videos
operationId: getSyndicatedComments
parameters:
- name: format
in: path
required: true
description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
schema:
type: string
enum:
- xml
- rss
- rss2
- atom
- atom1
- json
- json1
- name: videoId
in: query
description: 'limit listing to a specific video'
schema:
type: string
- name: accountId
in: query
description: 'limit listing to a specific account'
schema:
type: string
- name: accountName
in: query
description: 'limit listing to a specific account'
schema:
type: string
- name: videoChannelId
in: query
description: 'limit listing to a specific video channel'
schema:
type: string
- name: videoChannelName
in: query
description: 'limit listing to a specific video channel'
schema:
type: string
responses:
'204':
description: successful operation
headers:
Cache-Control:
schema:
type: string
default: 'max-age=900' # 15 min cache
content:
application/xml:
schema:
$ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
application/rss+xml:
schema:
$ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
text/xml:
schema:
$ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
application/atom+xml:
schema:
$ref: '#/components/schemas/VideoCommentsForXML'
examples:
nightly:
externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
application/json:
schema:
type: object
examples:
nightly:
externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
'400':
x-summary: field inconsistencies
description: >
Arises when:
- videoId filter is mixed with a channel filter
'404':
description: video, video channel or account not found
'406':
description: accept header unsupported
'/feeds/videos.{format}':
get:
tags:
- Video Feeds
summary: List videos
operationId: getSyndicatedVideos
parameters:
- name: format
in: path
required: true
description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
schema:
type: string
enum:
- xml
- rss
- rss2
- atom
- atom1
- json
- json1
- name: accountId
in: query
description: 'limit listing to a specific account'
schema:
type: string
- name: accountName
in: query
description: 'limit listing to a specific account'
schema:
type: string
- name: videoChannelId
in: query
description: 'limit listing to a specific video channel'
schema:
type: string
- name: videoChannelName
in: query
description: 'limit listing to a specific video channel'
schema:
type: string
- $ref: '#/components/parameters/sort'
- $ref: '#/components/parameters/nsfw'
- $ref: '#/components/parameters/isLocal'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/privacyOneOf'
- $ref: '#/components/parameters/hasHLSFiles'
- $ref: '#/components/parameters/hasWebtorrentFiles'
responses:
'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:
- Video Feeds
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
headers:
Cache-Control:
schema:
type: string
default: 'max-age=900' # 15 min cache
content:
application/xml:
schema:
$ref: '#/components/schemas/VideosForXML'
application/rss+xml:
schema:
$ref: '#/components/schemas/VideosForXML'
text/xml:
schema:
$ref: '#/components/schemas/VideosForXML'
application/atom+xml:
schema:
$ref: '#/components/schemas/VideosForXML'
application/json:
schema:
type: object
'406':
description: accept header unsupported
'/api/v1/accounts/{name}':
get:
tags:
- Accounts
summary: Get an account
operationId: getAccount
parameters:
- $ref: '#/components/parameters/name'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'404':
description: account not found
'/api/v1/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/isLocal'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/privacyOneOf'
- $ref: '#/components/parameters/hasHLSFiles'
- $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
x-codeSamples:
- lang: JavaScript
source: |
fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
.then(function(response) {
return response.json()
}).then(function(data) {
console.log(data)
})
- lang: Shell
source: |
## DEPENDENCIES: jq
curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
- lang: Ruby
source: |
require 'net/http'
require 'json'
uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.get(uri.request_uri)
puts JSON.parse(response.read_body)
- lang: Python
source: |
import requests
r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
json = r.json()
print(json)
'/api/v1/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'
/api/v1/accounts:
get:
tags:
- Accounts
summary: List accounts
operationId: getAccounts
parameters:
- $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/Account'
/api/v1/config:
get:
tags:
- Config
summary: Get instance public configuration
operationId: getConfig
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServerConfig'
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/config
/api/v1/config/about:
get:
summary: Get instance "About" information
operationId: getAbout
tags:
- Config
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServerConfigAbout'
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/config/about
/api/v1/config/custom:
get:
summary: Get instance runtime configuration
operationId: getCustomConfig
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServerConfigCustom'
put:
summary: Set instance runtime configuration
operationId: putCustomConfig
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
'400':
x-summary: field inconsistencies
description: >
Arises when:
- the emailer is disabled and the instance is open to registrations
- webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
delete:
summary: Delete instance runtime configuration
operationId: delCustomConfig
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
/api/v1/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
/api/v1/jobs/pause:
post:
summary: Pause job queue
security:
- OAuth2:
- admin
tags:
- Job
responses:
'204':
description: successful operation
/api/v1/jobs/resume:
post:
summary: Resume job queue
security:
- OAuth2:
- admin
tags:
- Job
responses:
'204':
description: successful operation
/api/v1/jobs/{state}:
get:
summary: List instance jobs
operationId: getJobs
security:
- OAuth2:
- admin
tags:
- Job
parameters:
- name: state
in: path
required: true
description: The state of the job ('' for for no filter)
schema:
type: string
enum:
- ''
- active
- completed
- failed
- waiting
- delayed
- $ref: '#/components/parameters/jobType'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
total:
type: integer
example: 1
data:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/Job'
/api/v1/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'
'/api/v1/server/followers/{nameWithHost}':
delete:
summary: Remove or reject a follower to your server
security:
- OAuth2:
- admin
tags:
- Instance Follows
parameters:
- name: nameWithHost
in: path
required: true
description: The remote actor handle to remove from your followers
schema:
type: string
format: email
responses:
'204':
description: successful operation
'404':
description: follower not found
'/api/v1/server/followers/{nameWithHost}/reject':
post:
summary: Reject 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
'/api/v1/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
/api/v1/server/following:
get:
tags:
- Instance Follows
summary: List instances followed by the server
parameters:
- $ref: '#/components/parameters/followState'
- $ref: '#/components/parameters/actorType'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
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'
post:
security:
- OAuth2:
- admin
tags:
- Instance Follows
summary: Follow a list of actors (PeerTube instance, channel or account)
responses:
'204':
description: successful operation
'500':
description: cannot follow a non-HTTPS server
requestBody:
content:
application/json:
schema:
type: object
properties:
hosts:
type: array
items:
type: string
format: hostname
uniqueItems: true
handles:
type: array
items:
type: string
uniqueItems: true
'/api/v1/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
/api/v1/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: |
If the smtp server is configured, you can leave the password empty and an email will be sent
asking the user to set it first.
required: true
get:
summary: List users
operationId: getUsers
security:
- OAuth2:
- admin
tags:
- Users
parameters:
- $ref: '#/components/parameters/usersSearch'
- $ref: '#/components/parameters/usersBlocked'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/usersSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'/api/v1/users/{id}':
parameters:
- $ref: '#/components/parameters/id'
delete:
summary: Delete a user
security:
- OAuth2:
- admin
tags:
- Users
operationId: delUser
responses:
'204':
description: successful operation
get:
summary: Get a user
security:
- OAuth2: []
tags:
- Users
operationId: getUser
parameters:
- name: withStats
in: query
description: include statistics about the user (only available as a moderator/admin)
schema:
type: boolean
responses:
'200':
x-summary: successful operation
description: |
As an admin/moderator, you can request a response augmented with statistics about the user's
moderation relations and videos usage, by using the `withStats` parameter.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/User'
- $ref: '#/components/schemas/UserWithStats'
put:
summary: Update a user
security:
- OAuth2: []
tags:
- Users
operationId: putUser
responses:
'204':
description: successful operation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
required: true
/api/v1/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"
/api/v1/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"
/api/v1/users/revoke-token:
post:
summary: Logout
description: Revokes your access token and its associated refresh token, destroying your current session.
operationId: revokeOAuthToken
tags:
- Session
security:
- OAuth2: []
responses:
'200':
description: successful operation
/api/v1/users/register:
post:
summary: Register a user
operationId: registerUser
tags:
- Users
- Register
responses:
'204':
description: successful operation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterUser'
required: true
/api/v1/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
/api/v1/users/{id}/two-factor/request:
post:
summary: Request two factor auth
operationId: requestTwoFactor
description: Request two factor authentication for a user
tags:
- Users
parameters:
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
type: object
properties:
currentPassword:
type: string
description: Password of the currently authenticated user
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RequestTwoFactorResponse'
'403':
description: invalid password
'404':
description: user not found
/api/v1/users/{id}/two-factor/confirm-request:
post:
summary: Confirm two factor auth
operationId: confirmTwoFactorRequest
description: Confirm a two factor authentication request
tags:
- Users
parameters:
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
type: object
properties:
requestToken:
type: string
description: Token to identify the two factor request
otpToken:
type: string
description: OTP token generated by the app
required:
- requestToken
- otpToken
responses:
'204':
description: successful operation
'403':
description: invalid request token or OTP token
'404':
description: user not found
/api/v1/users/{id}/two-factor/disable:
post:
summary: Disable two factor auth
operationId: disableTwoFactor
description: Disable two factor authentication of a user
tags:
- Users
parameters:
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
type: object
properties:
currentPassword:
type: string
description: Password of the currently authenticated user
responses:
'204':
description: successful operation
'403':
description: invalid password
'404':
description: user not found
/api/v1/users/ask-send-verify-email:
post:
summary: Resend user verification link
operationId: resendEmailToVerifyUser
tags:
- Users
- Register
responses:
'204':
description: successful operation
/api/v1/users/me:
get:
summary: Get my user information
operationId: getUserInfo
security:
- OAuth2:
- user
tags:
- My User
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
put:
summary: Update my user information
operationId: putUserInfo
security:
- OAuth2:
- user
tags:
- My User
responses:
'204':
description: successful operation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMe'
required: true
/api/v1/users/me/videos/imports:
get:
summary: Get video imports of my user
security:
- OAuth2:
- user
tags:
- Videos
- My User
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
-
name: targetUrl
in: query
required: false
description: Filter on import target URL
schema:
type: string
-
name: videoChannelSyncId
in: query
required: false
description: Filter on imports created by a specific channel synchronization
schema:
type: number
-
name: search
in: query
required: false
description: Search in video names
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoImportsList'
/api/v1/users/me/video-quota-used:
get:
summary: Get my user used quota
security:
- OAuth2:
- user
tags:
- My User
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
videoQuotaUsed:
type: number
description: The user video quota used so far in bytes
example: 16810141515
videoQuotaUsedDaily:
type: number
description: The user video quota used today in bytes
example: 1681014151
'/api/v1/users/me/videos/{videoId}/rating':
get:
summary: Get rate of my user for a video
security:
- OAuth2: []
tags:
- My User
- Video Rates
parameters:
- name: videoId
in: path
required: true
description: The video id
schema:
$ref: '#/components/schemas/Video/properties/id'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/GetMeVideoRating'
/api/v1/users/me/videos:
get:
summary: Get videos of my user
security:
- OAuth2:
- user
tags:
- My User
- Videos
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
/api/v1/users/me/subscriptions:
get:
summary: Get my user subscriptions
security:
- OAuth2:
- user
tags:
- My Subscriptions
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoChannelList'
post:
tags:
- My Subscriptions
summary: Add subscription to my user
security:
- OAuth2:
- 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
/api/v1/users/me/subscriptions/exist:
get:
summary: Get if subscriptions exist for my user
security:
- OAuth2:
- user
tags:
- My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionsUris'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
/api/v1/users/me/subscriptions/videos:
get:
summary: List videos of subscriptions of my user
security:
- OAuth2:
- user
tags:
- My Subscriptions
- Videos
parameters:
- $ref: '#/components/parameters/categoryOneOf'
- $ref: '#/components/parameters/isLive'
- $ref: '#/components/parameters/tagsOneOf'
- $ref: '#/components/parameters/tagsAllOf'
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- $ref: '#/components/parameters/isLocal'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/privacyOneOf'
- $ref: '#/components/parameters/hasHLSFiles'
- $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
'/api/v1/users/me/subscriptions/{subscriptionHandle}':
get:
summary: Get subscription of my user
security:
- OAuth2:
- user
tags:
- My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionHandle'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoChannel'
delete:
summary: Delete subscription of my user
security:
- OAuth2:
- user
tags:
- My Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionHandle'
responses:
'200':
description: successful operation
/api/v1/users/me/notifications:
get:
summary: List my notifications
security:
- OAuth2: []
tags:
- My Notifications
parameters:
- name: unread
in: query
description: only list unread notifications
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/NotificationListResponse'
/api/v1/users/me/notifications/read:
post:
summary: Mark notifications as read by their id
security:
- OAuth2: []
tags:
- My Notifications
requestBody:
content:
application/json:
schema:
type: object
properties:
ids:
type: array
description: ids of the notifications to mark as read
items:
type: integer
required:
- ids
responses:
'204':
description: successful operation
/api/v1/users/me/notifications/read-all:
post:
summary: Mark all my notification as read
security:
- OAuth2: []
tags:
- My Notifications
responses:
'204':
description: successful operation
/api/v1/users/me/notification-settings:
put:
summary: Update my notification settings
security:
- OAuth2: []
tags:
- My Notifications
requestBody:
content:
application/json:
schema:
type: object
properties:
newVideoFromSubscription:
$ref: '#/components/schemas/NotificationSettingValue'
newCommentOnMyVideo:
$ref: '#/components/schemas/NotificationSettingValue'
abuseAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
videoAutoBlacklistAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
blacklistOnMyVideo:
$ref: '#/components/schemas/NotificationSettingValue'
myVideoPublished:
$ref: '#/components/schemas/NotificationSettingValue'
myVideoImportFinished:
$ref: '#/components/schemas/NotificationSettingValue'
newFollow:
$ref: '#/components/schemas/NotificationSettingValue'
newUserRegistration:
$ref: '#/components/schemas/NotificationSettingValue'
commentMention:
$ref: '#/components/schemas/NotificationSettingValue'
newInstanceFollower:
$ref: '#/components/schemas/NotificationSettingValue'
autoInstanceFollowing:
$ref: '#/components/schemas/NotificationSettingValue'
responses:
'204':
description: successful operation
/api/v1/users/me/history/videos:
get:
summary: List watched videos history
security:
- OAuth2: []
tags:
- 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'
/api/v1/users/me/history/videos/{videoId}:
delete:
summary: Delete history element
security:
- OAuth2: []
tags:
- My History
parameters:
- name: videoId
in: path
required: true
schema:
$ref: '#/components/schemas/Video/properties/id'
responses:
'204':
description: successful operation
/api/v1/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
/api/v1/users/me/avatar/pick:
post:
summary: Update my user avatar
security:
- OAuth2: []
tags:
- My User
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
avatars:
type: array
items:
$ref: '#/components/schemas/ActorImage'
'413':
description: image file too large
headers:
X-File-Maximum-Size:
schema:
type: string
format: Nginx size
description: Maximum file size for the avatar
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
avatarfile:
description: The file to upload
type: string
format: binary
encoding:
avatarfile:
contentType: image/png, image/jpeg
/api/v1/users/me/avatar:
delete:
summary: Delete my avatar
security:
- OAuth2: []
tags:
- My User
responses:
'204':
description: successful operation
/api/v1/videos/ownership:
get:
summary: List video ownership changes
tags:
- Video Ownership Change
security:
- OAuth2: []
responses:
'200':
description: successful operation
'/api/v1/videos/ownership/{id}/accept':
post:
summary: Accept ownership change request
tags:
- Video Ownership Change
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
'403':
description: cannot terminate an ownership change of another user
'404':
description: video ownership change not found
'/api/v1/videos/ownership/{id}/refuse':
post:
summary: Refuse ownership change request
tags:
- Video Ownership Change
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
'403':
description: cannot terminate an ownership change of another user
'404':
description: video ownership change not found
'/api/v1/videos/{id}/give-ownership':
post:
summary: Request ownership change
tags:
- Video Ownership Change
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
type: string
required:
- username
responses:
'204':
description: successful operation
'400':
description: changing video ownership to a remote account is not supported yet
'404':
description: video not found
'/api/v1/videos/{id}/token':
post:
summary: Request video token
operationId: requestVideoToken
description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTokenResponse'
'400':
description: incorrect parameters
'404':
description: video not found
/api/v1/videos/{id}/studio/edit:
post:
summary: Create a studio task
tags:
- Video Transcoding
- Video
description: Create a task to edit a video (cut, add intro/outro etc)
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/VideoStudioCreateTask'
responses:
'204':
description: successful operation
'400':
description: incorrect parameters
'404':
description: video not found
/api/v1/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/isLocal'
- $ref: '#/components/parameters/include'
- $ref: '#/components/parameters/privacyOneOf'
- $ref: '#/components/parameters/hasHLSFiles'
- $ref: '#/components/parameters/hasWebtorrentFiles'
- $ref: '#/components/parameters/skipCount'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
/api/v1/videos/categories:
get:
summary: List available video categories
operationId: getCategories
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/categories
/api/v1/videos/licences:
get:
summary: List available video licences
operationId: getLicences
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/licences
/api/v1/videos/languages:
get:
summary: List available video languages
operationId: getLanguages
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/languages
/api/v1/videos/privacies:
get:
summary: List available video privacy policies
operationId: getPrivacyPolicies
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
examples:
nightly:
externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
'/api/v1/videos/{id}':
put:
summary: Update a video
operationId: putVideo
security:
- OAuth2: []
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
thumbnailfile:
description: Video thumbnail file
type: string
format: binary
previewfile:
description: Video preview file
type: string
format: binary
category:
$ref: '#/components/schemas/VideoCategorySet'
licence:
$ref: '#/components/schemas/VideoLicenceSet'
language:
$ref: '#/components/schemas/VideoLanguageSet'
privacy:
$ref: '#/components/schemas/VideoPrivacySet'
description:
description: Video description
type: string
waitTranscoding:
description: Whether or not we wait transcoding before publish the video
type: string
support:
description: A text tell the audience how to support the video creator
example: Please support our work on https://soutenir.framasoft.org/en/ <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: boolean
name:
description: Video name
type: string
minLength: 3
maxLength: 120
tags:
description: Video tags (maximum 5 tags each between 2 and 30 characters)
type: array
minItems: 1
maxItems: 5
items:
type: string
minLength: 2
maxLength: 30
commentsEnabled:
description: Enable or disable comments for this video
type: boolean
downloadEnabled:
description: Enable or disable downloading for this video
type: boolean
originallyPublishedAt:
description: Date when the content was originally published
type: string
format: date-time
scheduleUpdate:
$ref: '#/components/schemas/VideoScheduledUpdate'
encoding:
thumbnailfile:
contentType: image/jpeg
previewfile:
contentType: image/jpeg
get:
summary: Get a video
operationId: getVideo
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoDetails'
delete:
summary: Delete a video
operationId: delVideo
security:
- OAuth2: []
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'204':
description: successful operation
'/api/v1/videos/{id}/description':
get:
summary: Get complete video description
operationId: getVideoDesc
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
nullable: true
type: string
minLength: 3
maxLength: 10000
example: |
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
'/api/v1/videos/{id}/source':
post:
summary: Get video source file metadata
operationId: getVideoSource
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoSource'
'/api/v1/videos/{id}/views':
post:
summary: Notify user is watching a video
description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
operationId: addView
tags:
- Video
parameters:
- $ref: '#/components/parameters/idOrUUID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserViewingVideo'
required: true
responses:
'204':
description: successful operation
'/api/v1/videos/{id}/watching':
put:
summary: Set watching progress of a video
deprecated: true
description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserViewingVideo'
required: true
responses:
'204':
description: successful operation
'/api/v1/videos/{id}/stats/overall':
get:
summary: Get overall stats of a video
tags:
- Video Stats
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
- name: startDate
in: query
description: Filter stats by start date
schema:
type: string
format: date-time
- name: endDate
in: query
description: Filter stats by end date
schema:
type: string
format: date-time
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoStatsOverall'
'/api/v1/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'
'/api/v1/videos/{id}/stats/timeseries/{metric}':
get:
summary: Get timeserie stats of a video
tags:
- Video Stats
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/idOrUUID'
-
name: metric
in: path
required: true
description: The metric to get
schema:
type: string
enum:
- 'viewers'
- 'aggregateWatchTime'
- name: startDate
in: query
description: Filter stats by start date
schema:
type: string
format: date-time
- name: endDate
in: query
description: Filter stats by end date
schema:
type: string
format: date-time
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoStatsTimeserie'
/api/v1/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
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
'403':
description: video didn't pass upload filter
'408':
description: upload has timed out
'413':
x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
description: |
If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
- `quota_reached` for quota limits whether daily or global
headers:
X-File-Maximum-Size:
schema:
type: string
format: Nginx size
description: Maximum file size for the video
'415':
description: video type unsupported
'422':
description: video unreadable
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/VideoUploadRequestLegacy'
encoding:
videofile:
contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
thumbnailfile:
contentType: image/jpeg
previewfile:
contentType: image/jpeg
x-codeSamples:
- lang: Shell
source: |
## DEPENDENCIES: jq
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_name>"
API="https://peertube2.cpy.re/api/v1"
## AUTH
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
token=$(curl -s "$API/users/token" \
--data client_id="$client_id" \
--data client_secret="$client_secret" \
--data grant_type=password \
--data username="$USERNAME" \
--data password="$PASSWORD" \
| jq -r ".access_token")
## VIDEO UPLOAD
curl -s "$API/videos/upload" \
-H "Authorization: Bearer $token" \
--max-time 600 \
--form videofile=@"$FILE_PATH" \
--form channelId=$CHANNEL_ID \
--form name="$NAME"
/api/v1/videos/upload-resumable:
post:
summary: Initialize the resumable upload of a video
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
operationId: uploadResumableInit
security:
- OAuth2: []
tags:
- Video
- Video Upload
parameters:
- name: X-Upload-Content-Length
in: header
schema:
type: number
example: 2469036
required: true
description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
- name: X-Upload-Content-Type
in: header
schema:
type: string
format: mimetype
example: video/mp4
required: true
description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadRequestResumable'
responses:
'200':
description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
'201':
description: created
headers:
Location:
schema:
type: string
format: url
example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
Content-Length:
schema:
type: number
example: 0
'413':
x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
description: |
Disambiguate via `type`:
- `max_file_size_reached` for the absolute file size limit
- `quota_reached` for quota limits whether daily or global
'415':
description: video type unsupported
put:
summary: Send chunk for the resumable upload of a video
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
operationId: uploadResumable
security:
- OAuth2: []
tags:
- Video
- Video Upload
parameters:
- name: upload_id
in: query
required: true
description: |
Created session id to proceed with. If you didn't send chunks in the last hour, it is
not valid anymore and you need to initialize a new upload.
schema:
type: string
- name: Content-Range
in: header
schema:
type: string
example: bytes 0-262143/2469036
required: true
description: |
Specifies the bytes in the file that the request is uploading.
For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
262144 bytes (256 x 1024) in a 2,469,036 byte file.
- name: Content-Length
in: header
schema:
type: number
example: 262144
required: true
description: |
Size of the chunk that the request is sending.
Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1048576 bytes (~1MB) and increases or reduces size depending on connection health.
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
'200':
description: last chunk received
headers:
Content-Length:
schema:
type: number
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
'308':
description: resume incomplete
headers:
Range:
schema:
type: string
example: bytes=0-262143
Content-Length:
schema:
type: number
example: 0
'403':
description: video didn't pass upload filter
'404':
description: upload not found
'409':
description: chunk doesn't match range
'422':
description: video unreadable
'429':
description: too many concurrent requests
'503':
description: upload is already being processed
headers:
'Retry-After':
schema:
type: number
example: 300
delete:
summary: Cancel the resumable upload of a video, deleting any data uploaded so far
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
operationId: uploadResumableCancel
security:
- OAuth2: []
tags:
- Video
- Video Upload
parameters:
- name: upload_id
in: query
required: true
description: |
Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
not valid anymore and the upload session has already been deleted with its data ;-)
schema:
type: string
- name: Content-Length
in: header
required: true
schema:
type: number
example: 0
responses:
'204':
description: upload cancelled
headers:
Content-Length:
schema:
type: number
example: 0
'404':
description: upload not found
/api/v1/videos/imports:
post:
summary: Import a video
description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
operationId: importVideo
security:
- OAuth2: []
tags:
- Video Imports
- Video Upload
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/VideoCreateImport'
encoding:
torrentfile:
contentType: application/x-bittorrent
thumbnailfile:
contentType: image/jpeg
previewfile:
contentType: image/jpeg
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
'400':
description: '`magnetUri` or `targetUrl` or a torrent file missing'
'403':
description: video didn't pass pre-import filter
'409':
description: HTTP or Torrent/magnetURI import not enabled
/api/v1/videos/imports/{id}/cancel:
post:
summary: Cancel video import
description: Cancel a pending video import
security:
- OAuth2: []
tags:
- Video Imports
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
description: successful operation
/api/v1/videos/imports/{id}:
delete:
summary: Delete video import
description: Delete ended video import
security:
- OAuth2: []
tags:
- Video Imports
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
description: successful operation
/api/v1/videos/live:
post:
summary: Create a live
operationId: addLive
security:
- OAuth2: []
tags:
- Live Videos
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
'400':
x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
description: |
Disambiguate via `type`:
- default type for a validation error
- `live_conflicting_permanent_and_save_replay` for conflicting parameters set
'403':
x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
description: |
Disambiguate via `type`:
- `live_not_enabled` for a disabled live feature
- `live_not_allowing_replay` for a disabled replay feature
- `max_instance_lives_limit_reached` for the absolute concurrent live limit
- `max_user_lives_limit_reached` for the user concurrent live limit
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
channelId:
description: Channel id that will contain this live video
type: integer
saveReplay:
type: boolean
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
latencyMode:
description: User can select live latency mode if enabled by the instance
$ref: '#/components/schemas/LiveVideoLatencyMode'
thumbnailfile:
description: Live video/replay thumbnail file
type: string
format: binary
previewfile:
description: Live video/replay preview file
type: string
format: binary
privacy:
$ref: '#/components/schemas/VideoPrivacySet'
category:
$ref: '#/components/schemas/VideoCategorySet'
licence:
$ref: '#/components/schemas/VideoLicenceSet'
language:
$ref: '#/components/schemas/VideoLanguageSet'
description:
description: Live video/replay description
type: string
support:
description: A text tell the audience how to support the creator
example: Please support our work on https://soutenir.framasoft.org/en/ <3
type: string
nsfw:
description: Whether or not this live video/replay contains sensitive content
type: boolean
name:
description: Live video/replay name
type: string
minLength: 3
maxLength: 120
tags:
description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
type: array
minItems: 1
maxItems: 5
items:
type: string
minLength: 2
maxLength: 30
commentsEnabled:
description: Enable or disable comments for this live video/replay
type: boolean
downloadEnabled:
description: Enable or disable downloading for the replay of this live video
type: boolean
required:
- channelId
- name
encoding:
thumbnailfile:
contentType: image/jpeg
previewfile:
contentType: image/jpeg
/api/v1/videos/live/{id}:
get:
summary: Get information about a live
operationId: getLiveId
security:
- OAuth2: []
tags:
- Live Videos
- Video
parameters: