PeerTube Project Homepage
API docs by Redocly

PeerTube (5.1.0)

Download OpenAPI specification:Download

URL: https://joinpeertube.org License: AGPLv3.0

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 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:

See the REST API quick start for a few examples of using the PeerTube API.

https://docs.joinpeertube.org/api/rest-reference.html

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 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 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, 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* 5 minutes
POST /users/ask-send-verify-email 3 5 minutes

Depending on the endpoint, *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), 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.

Static Video Files

Get public WebTorrent video file

path Parameters
filename
required
string

Filename

Responses

Get private WebTorrent video file

Authorizations:
OAuth2
path Parameters
filename
required
string

Filename

query Parameters
videoFileToken
string

Video file token generated by PeerTube so you don't need to provide an OAuth token in the request header.

Responses

Get public HLS video file

Authorizations:
OAuth2
path Parameters
filename
required
string

Filename

Responses

Get private HLS video file

Authorizations:
OAuth2
path Parameters
filename
required
string

Filename

query Parameters
reinjectVideoFileToken
boolean

Ask the server to reinject videoFileToken in URLs in m3u8 playlist

videoFileToken
string

Video file token generated by PeerTube so you don't need to provide an OAuth token in the request header.

Responses

Video Feeds

Server syndication feeds of videos

List comments on videos

path Parameters
format
required
string
Enum: "xml" "rss" "rss2" "atom" "atom1" "json" "json1"

format expected (we focus on making rss the most featureful ; it serves Media RSS)

query Parameters
accountId
string

limit listing to a specific account

accountName
string

limit listing to a specific account

videoChannelId
string

limit listing to a specific video channel

videoChannelName
string

limit listing to a specific video channel

videoId
string

limit listing to a specific video

Responses

Response samples

Content type
Loading...

List videos

path Parameters
format
required
string
Enum: "xml" "rss" "rss2" "atom" "atom1" "json" "json1"

format expected (we focus on making rss the most featureful ; it serves Media RSS)

query Parameters
accountId
string

limit listing to a specific account

accountName
string

limit listing to a specific account

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

sort
string
Example: sort=-createdAt

Sort column

videoChannelId
string

limit listing to a specific video channel

videoChannelName
string

limit listing to a specific video channel

Responses

Response samples

Content type
Loading...

List videos of subscriptions tied to a token

path Parameters
format
required
string
Enum: "xml" "rss" "rss2" "atom" "atom1" "json" "json1"

format expected (we focus on making rss the most featureful ; it serves Media RSS)

query Parameters
accountId
required
string

limit listing to a specific account

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

sort
string
Example: sort=-createdAt

Sort column

token
required
string

private token allowing access

Responses

Response samples

Content type
No sample

Register

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 instead.

Resend user verification link

Request Body schema: application/json
email
required
string

User email

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Resend verification link to registration email

Request Body schema: application/json
email
required
string

Registration email

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Verify a user

Following a user registration, the new user will receive an email asking to click a link containing a secret. This endpoint can also be used to verify a new email set in the user account.

path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
verificationString
required
string <url>
isPendingEmail
boolean

Responses

Request samples

Content type
application/json
{
  • "verificationString": "string",
  • "isPendingEmail": true
}

Verify a registration email

Following a user registration request, the user will receive an email asking to click a link containing a secret.

path Parameters
registrationId
required
integer (id) >= 1
Example: 42

Registration ID

Request Body schema: application/json
verificationString
required
string <url>

Responses

Request samples

Content type
application/json
{
  • "verificationString": "string"
}

Register a user

Signup has to be enabled and signup approval is not required

Request Body schema: application/json
email
required
string <email>

email of the user, used for login or service communications

password
required
string <password> (password) [ 6 .. 255 ] characters
username
required
string [ 1 .. 50 ] characters /^[a-z0-9._]+$/

immutable name of the user, used to find or mention its actor

object

channel base information used to create the first channel of the user

displayName
string [ 1 .. 120 ] characters

editable name of the user, displayed in its representations

Responses

Request samples

Content type
application/json
{
  • "username": "chocobozzz",
  • "password": "pa$$word",
  • "email": "user@example.com",
  • "displayName": "string",
  • "channel": {
    }
}

Request registration

Signup has to be enabled and require approval on the instance

Request Body schema: application/json
email
required
string <email>

email of the user, used for login or service communications

password
required
string <password> (password) [ 6 .. 255 ] characters
registrationReason
required
string

reason for the user to register on the instance

username
required
string [ 1 .. 50 ] characters /^[a-z0-9._]+$/

immutable name of the user, used to find or mention its actor

object

channel base information used to create the first channel of the user

displayName
string [ 1 .. 120 ] characters

editable name of the user, displayed in its representations

Responses

Request samples

Content type
application/json
{
  • "username": "chocobozzz",
  • "password": "pa$$word",
  • "email": "user@example.com",
  • "displayName": "string",
  • "channel": {
    },
  • "registrationReason": "string"
}

Response samples

Content type
application/json
{
  • "id": 42,
  • "state": {
    },
  • "registrationReason": "string",
  • "moderationResponse": "string",
  • "username": "string",
  • "email": "user@example.com",
  • "emailVerified": true,
  • "accountDisplayName": "string",
  • "channelHandle": "string",
  • "channelDisplayName": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "user": {
    }
}

Accept registration

Authorizations:
OAuth2
path Parameters
registrationId
required
integer (id) >= 1
Example: 42

Registration ID

Request Body schema: application/json
moderationResponse
required
string

Moderation response to send to the user

preventEmailDelivery
boolean

Set it to true if you don't want PeerTube to send an email to the user

Responses

Request samples

Content type
application/json
{
  • "moderationResponse": "string",
  • "preventEmailDelivery": true
}

Reject registration

Authorizations:
OAuth2
path Parameters
registrationId
required
integer (id) >= 1
Example: 42

Registration ID

Request Body schema: application/json
moderationResponse
required
string

Moderation response to send to the user

preventEmailDelivery
boolean

Set it to true if you don't want PeerTube to send an email to the user

Responses

Request samples

Content type
application/json
{
  • "moderationResponse": "string",
  • "preventEmailDelivery": true
}

Delete registration

Delete the registration entry. It will not remove the user associated with this registration (if any)

Authorizations:
OAuth2
path Parameters
registrationId
required
integer (id) >= 1
Example: 42

Registration ID

Responses

List registrations

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

search
string
sort
string
Enum: "-createdAt" "createdAt" "state" "-state"
start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Login/Logout

Sessions deal with access tokens over time. Only one session token can currently be used at a time.

Login prerequisite

You need to retrieve a client id and secret before logging in.

Responses

Request samples 

API="https://peertube2.cpy.re/api/v1"

## AUTH
curl -s "$API/oauth-clients/local"

Response samples

Content type
application/json
{
  • "client_id": "v1ikx5hnfop4mdpnci8nsqh93c45rldf",
  • "client_secret": "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt"
}

Login

With your client id and secret, you can retrieve an access and refresh tokens.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string = 32 characters /^[a-z0-9]$/
client_secret
required
string = 32 characters /^[a-zA-Z0-9]$/
grant_type
required
string
Default: "password"
password
required
string <password> (password) [ 6 .. 255 ] characters
username
required
string [ 1 .. 50 ] characters /^[a-z0-9._]+$/

immutable name of the user, used to find or mention its actor

Responses

Request samples 

## 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"

Response samples

Content type
application/json
{
  • "token_type": "Bearer",
  • "access_token": "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0",
  • "refresh_token": "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7",
  • "expires_in": 14399,
  • "refresh_token_expires_in": 1209600
}

Logout

Revokes your access token and its associated refresh token, destroying your current session.

Authorizations:
OAuth2

Responses

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.

Get an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "url": "string",
  • "name": "chocobozzz",
  • "host": "example.com",
  • "hostRedundancyAllowed": true,
  • "followingCount": 0,
  • "followersCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "userId": 42,
  • "displayName": "string",
  • "description": "string"
}

List videos of an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
VideoCategorySet (integer) or Array of VideoCategorySet (integers)

category id of the video (see /videos/categories)

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

VideoLanguageSet (string) or Array of VideoLanguageSet (strings)

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

VideoLicenceSet (integer) or Array of VideoLicenceSet (integers)

licence id of the video (see /videos/licences)

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

skipCount
string
Default: "false"
Enum: "true" "false"

if you don't need the total in the response

sort
string
Enum: "name" "-duration" "-createdAt" "-publishedAt" "-views" "-likes" "-trending" "-hot" "-best"

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)
start
integer >= 0

Offset used to paginate results

string or Array of strings

tag(s) of the video, where all should be present in the video

string or Array of strings

tag(s) of the video

Responses

Request samples 

fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
.then(function(response) {
  return response.json()
}).then(function(data) {
  console.log(data)
})

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List followers of an account

Authorizations:
OAuth2
path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

search
string

Plain text search, applied to various parts of the model depending on endpoint

sort
string
Value: "createdAt"

Sort followers by criteria

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List accounts

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List playlists of an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

playlistType
integer (VideoPlaylistTypeSet)
Enum: 1 2

The video playlist type (Regular = 1, Watch Later = 2)

search
string

Plain text search, applied to various parts of the model depending on endpoint

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List video channels of an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

withStats
boolean

include daily view statistics for the last 30 days and total views (only if authentified as the account user)

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List the synchronizations of video channels of an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List ratings of an account

Authorizations:
OAuth2
path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

rating
string
Enum: "like" "dislike"

Optionally filter which ratings to retrieve

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Users

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.

Create a user

Authorizations:
OAuth2
Request Body schema: application/json

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.

email
required
string <email>

The user email

password
required
string <password> (password) [ 6 .. 255 ] characters
role
required
integer (UserRole)
Enum: 0 1 2

The user role (Admin = 0, Moderator = 1, User = 2)

username
required
string (username) [ 1 .. 50 ] characters /^[a-z0-9._]+$/

immutable name of the user, used to find or mention its actor

videoQuota
required
integer

The user video quota in bytes

videoQuotaDaily
required
integer

The user daily video quota in bytes

adminFlags
integer (UserAdminFlags)
Enum: 0 1

Admin flags for the user (None = 0, Bypass video blocklist = 1)

channelName
string (usernameChannel) [ 1 .. 50 ] characters /^[a-zA-Z0-9\\-_.:]+$/

immutable name of the channel, used to interact with its actor

Responses

Request samples

Content type
application/json
{
  • "username": "chocobozzz",
  • "password": "pa$$word",
  • "email": "user@example.com",
  • "videoQuota": -1,
  • "videoQuotaDaily": -1,
  • "channelName": "framasoft_videos",
  • "role": 2,
  • "adminFlags": 1
}

Response samples

Content type
application/json
{
  • "user": {
    }
}

List users

Authorizations:
OAuth2
query Parameters
blocked
boolean

Filter results down to (un)banned users

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

search
string

Plain text search that will match with user usernames or emails

sort
string
Enum: "-id" "-username" "-createdAt"

Sort users by criteria

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete a user

Authorizations:
OAuth2
path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Responses

Get a user

Authorizations:
OAuth2
path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

query Parameters
withStats
boolean

include statistics about the user (only available as a moderator/admin)

Responses

Response samples

Content type
application/json
Example
{
  • "account": {
    },
  • "autoPlayNextVideo": true,
  • "autoPlayNextVideoPlaylist": true,
  • "autoPlayVideo": true,
  • "blocked": true,
  • "blockedReason": "string",
  • "createdAt": "string",
  • "email": "user@example.com",
  • "emailVerified": true,
  • "id": 42,
  • "pluginAuth": "string",
  • "lastLoginDate": "2019-08-24T14:15:22Z",
  • "noInstanceConfigWarningModal": true,
  • "noAccountSetupWarningModal": true,
  • "noWelcomeModal": true,
  • "nsfwPolicy": "display",
  • "role": {
    },
  • "theme": "string",
  • "username": "chocobozzz",
  • "videoChannels": [
    ],
  • "videoQuota": -1,
  • "videoQuotaDaily": -1,
  • "p2pEnabled": true
}

Update a user

Authorizations:
OAuth2
path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
adminFlags
integer (UserAdminFlags)
Enum: 0 1

Admin flags for the user (None = 0, Bypass video blocklist = 1)

email
string <email>

The updated email of the user

emailVerified
boolean

Set the email as verified

password
string <password> (password) [ 6 .. 255 ] characters
pluginAuth
string or null

The auth plugin to use to authenticate the user

role
integer (UserRole)
Enum: 0 1 2

The user role (Admin = 0, Moderator = 1, User = 2)

videoQuota
integer

The updated video quota of the user in bytes

videoQuotaDaily
integer

The updated daily video quota of the user in bytes

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "emailVerified": true,
  • "videoQuota": 0,
  • "videoQuotaDaily": 0,
  • "pluginAuth": "peertube-plugin-auth-saml2",
  • "role": 2,
  • "adminFlags": 1,
  • "password": "pa$$word"
}

Resend user verification link

Request Body schema: application/json
email
required
string

User email

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Verify a user

Following a user registration, the new user will receive an email asking to click a link containing a secret. This endpoint can also be used to verify a new email set in the user account.

path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
verificationString
required
string <url>
isPendingEmail
boolean

Responses

Request samples

Content type
application/json
{
  • "verificationString": "string",
  • "isPendingEmail": true
}

Request two factor auth

Request two factor authentication for a user

path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
currentPassword
string

Password of the currently authenticated user

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Confirm two factor auth

Confirm a two factor authentication request

path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
otpToken
required
string

OTP token generated by the app

requestToken
required
string

Token to identify the two factor request

Responses

Request samples

Content type
application/json
{
  • "requestToken": "string",
  • "otpToken": "string"
}

Disable two factor auth

Disable two factor authentication of a user

path Parameters
id
required
integer (id) >= 1
Example: 42

Entity id

Request Body schema: application/json
currentPassword
string

Password of the currently authenticated user

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "string"
}

My User

Operations related to your own User, when logged-in.

Get my user information

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update my user information

Authorizations:
OAuth2
Request Body schema: application/json
autoPlayNextVideo
boolean

new preference regarding playing following videos automatically

autoPlayNextVideoPlaylist
boolean

new preference regarding playing following playlist videos automatically

autoPlayVideo
boolean

new preference regarding playing videos automatically

currentPassword
string <password> (password) [ 6 .. 255 ] characters
displayName
string [ 3 .. 120 ] characters

new name of the user in its representations

displayNSFW
string
Enum: "true" "false" "both"

new NSFW display policy

email
string <email>

new email used for login and service communications

noAccountSetupWarningModal
boolean
noInstanceConfigWarningModal
boolean
noWelcomeModal
boolean
p2pEnabled
boolean

whether to enable P2P in the player or not

password
string <password> (password) [ 6 .. 255 ] characters
theme
string
videoLanguages
Array of strings

list of languages to filter videos down to

videosHistoryEnabled
boolean

whether to keep track of watched history or not

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word",
  • "currentPassword": "pa$$word",
  • "email": "user@example.com",
  • "displayName": "string",
  • "displayNSFW": "true",
  • "p2pEnabled": true,
  • "autoPlayVideo": true,
  • "autoPlayNextVideo": true,
  • "autoPlayNextVideoPlaylist": true,
  • "videosHistoryEnabled": true,
  • "videoLanguages": [
    ],
  • "theme": "string",
  • "noInstanceConfigWarningModal": true,
  • "noAccountSetupWarningModal": true,
  • "noWelcomeModal": true
}

Get video imports of my user

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

search
string

Search in video names

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

targetUrl
string

Filter on import target URL

videoChannelSyncId
number

Filter on imports created by a specific channel synchronization

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Get my user used quota

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "videoQuotaUsed": 16810141515,
  • "videoQuotaUsedDaily": 1681014151
}

Get rate of my user for a video

Authorizations:
OAuth2
path Parameters
videoId
required
integer >= 1
Example: 42

The video id

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "rating": "like"
}

Get videos of my user

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Update my user avatar

Authorizations:
OAuth2
Request Body schema: multipart/form-data
avatarfile
string <binary>

The file to upload

Responses

Response samples

Content type
application/json
{
  • "avatars": [
    ]
}

Delete my avatar

Authorizations:
OAuth2

Responses

List my abuses

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

id
integer

only list the report with this id

sort
string
Enum: "-id" "-createdAt" "-state"

Sort abuses by criteria

start
integer >= 0

Offset used to paginate results

state
integer (AbuseStateSet)
Enum: 1 2 3

The abuse state (Pending = 1, Rejected = 2, Accepted = 3)

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

My Subscriptions

Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications!

Get my user subscriptions

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Add subscription to my user

Authorizations:
OAuth2
Request Body schema: application/json
uri
required
string <uri>

uri of the video channels to subscribe to

Responses

Request samples

Content type
application/json
{
  • "uri": "008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr"
}

Get if subscriptions exist for my user

Authorizations:
OAuth2
query Parameters
uris
required
Array of strings <uri>

list of uris to check if each is part of the user subscriptions

Responses

Response samples

Content type
application/json
{ }

List videos of subscriptions of my user

Authorizations:
OAuth2
query Parameters
VideoCategorySet (integer) or Array of VideoCategorySet (integers)

category id of the video (see /videos/categories)

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

VideoLanguageSet (string) or Array of VideoLanguageSet (strings)

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

VideoLicenceSet (integer) or Array of VideoLicenceSet (integers)

licence id of the video (see /videos/licences)

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

skipCount
string
Default: "false"
Enum: "true" "false"

if you don't need the total in the response

sort
string
Enum: "name" "-duration" "-createdAt" "-publishedAt" "-views" "-likes" "-trending" "-hot" "-best"

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)
start
integer >= 0

Offset used to paginate results

string or Array of strings

tag(s) of the video, where all should be present in the video

string or Array of strings

tag(s) of the video

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Get subscription of my user

Authorizations:
OAuth2
path Parameters
subscriptionHandle
required
string
Example: my_username | my_username@example.com

The subscription handle

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "url": "string",
  • "name": "chocobozzz",
  • "host": "example.com",
  • "hostRedundancyAllowed": true,
  • "followingCount": 0,
  • "followersCount": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "displayName": "Videos of Framasoft",
  • "description": "Videos made with <3 by Framasoft",
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "isLocal": true,
  • "banners": [
    ],
  • "ownerAccount": {
    }
}

Delete subscription of my user

Authorizations:
OAuth2
path Parameters
subscriptionHandle
required
string
Example: my_username | my_username@example.com

The subscription handle

Responses

My Notifications

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.

List my notifications

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

unread
boolean

only list unread notifications

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Mark notifications as read by their id

Authorizations:
OAuth2
Request Body schema: application/json
ids
required
Array of integers

ids of the notifications to mark as read

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Mark all my notification as read

Authorizations:
OAuth2

Responses

Update my notification settings

Authorizations:
OAuth2
Request Body schema: application/json
abuseAsModerator
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
autoInstanceFollowing
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
blacklistOnMyVideo
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
commentMention
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoImportFinished
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
myVideoPublished
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newCommentOnMyVideo
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newFollow
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newInstanceFollower
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newUserRegistration
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
newVideoFromSubscription
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL
videoAutoBlacklistAsModerator
integer (NotificationSettingValue)

Notification type. One of the following values, or a sum of multiple values:

  • 0 NONE
  • 1 WEB
  • 2 EMAIL

Responses

Request samples

Content type
application/json
{
  • "newVideoFromSubscription": 0,
  • "newCommentOnMyVideo": 0,
  • "abuseAsModerator": 0,
  • "videoAutoBlacklistAsModerator": 0,
  • "blacklistOnMyVideo": 0,
  • "myVideoPublished": 0,
  • "myVideoImportFinished": 0,
  • "newFollow": 0,
  • "newUserRegistration": 0,
  • "commentMention": 0,
  • "newInstanceFollower": 0,
  • "autoInstanceFollowing": 0
}

My History

Operations related to your watch history.

List watched videos history

Authorizations:
OAuth2
query Parameters
count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

search
string

Plain text search, applied to various parts of the model depending on endpoint

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Delete history element

Authorizations:
OAuth2
path Parameters
videoId
required
integer >= 1
Example: 42

object id for the video

Responses

Clear video history

Authorizations:
OAuth2
Request Body schema: multipart/form-data
beforeDate
string <date-time>

history before this date will be deleted

Responses

Video

Operations dealing with listing, uploading, fetching or modifying videos.

List videos of an account

path Parameters
name
required
string
Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters
VideoCategorySet (integer) or Array of VideoCategorySet (integers)

category id of the video (see /videos/categories)

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

VideoLanguageSet (string) or Array of VideoLanguageSet (strings)

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

VideoLicenceSet (integer) or Array of VideoLicenceSet (integers)

licence id of the video (see /videos/licences)

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

skipCount
string
Default: "false"
Enum: "true" "false"

if you don't need the total in the response

sort
string
Enum: "name" "-duration" "-createdAt" "-publishedAt" "-views" "-likes" "-trending" "-hot" "-best"

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)
start
integer >= 0

Offset used to paginate results

string or Array of strings

tag(s) of the video, where all should be present in the video

string or Array of strings

tag(s) of the video

Responses

Request samples 

fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
.then(function(response) {
  return response.json()
}).then(function(data) {
  console.log(data)
})

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

Request video token

Request special tokens that expire quickly to use them in some context (like accessing private static files)

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Response samples

Content type
application/json
{
  • "files": {
    }
}

Create a studio task

Create a task to edit a video (cut, add intro/outro etc)

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Request Body schema: application/x-www-form-urlencoded
Array
Any of
name
string
Value: "cut"
object

Responses

List videos

query Parameters
VideoCategorySet (integer) or Array of VideoCategorySet (integers)

category id of the video (see /videos/categories)

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

VideoLanguageSet (string) or Array of VideoLanguageSet (strings)

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

VideoLicenceSet (integer) or Array of VideoLicenceSet (integers)

licence id of the video (see /videos/licences)

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

skipCount
string
Default: "false"
Enum: "true" "false"

if you don't need the total in the response

sort
string
Enum: "name" "-duration" "-createdAt" "-publishedAt" "-views" "-likes" "-trending" "-hot" "-best"

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)
start
integer >= 0

Offset used to paginate results

string or Array of strings

tag(s) of the video, where all should be present in the video

string or Array of strings

tag(s) of the video

Responses

Response samples

Content type
application/json
{
  • "total": 1,
  • "data": [
    ]
}

List available video categories

Responses

Response samples

Content type
application/json
Loading...

List available video licences

Responses

Response samples

Content type
application/json
Loading...

List available video languages

Responses

Response samples

Content type
application/json
Loading...

List available video privacy policies

Responses

Response samples

Content type
application/json
Loading...

Update a video

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Request Body schema: multipart/form-data
category
integer (VideoCategorySet)

category id of the video (see /videos/categories)

commentsEnabled
boolean

Enable or disable comments for this video

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

language
string (VideoLanguageSet)

language id of the video (see /videos/languages)

licence
integer (VideoLicenceSet)

licence id of the video (see /videos/licences)

name
string [ 3 .. 120 ] characters

Video name

nsfw
boolean

Whether or not this video contains sensitive content

originallyPublishedAt
string <date-time>

Date when the content was originally published

previewfile
string <binary>

Video preview file

privacy
integer (VideoPrivacySet)
Enum: 1 2 3 4

privacy id of the video (see /videos/privacies)

object (VideoScheduledUpdate)
support
string

A text tell the audience how to support the video creator

tags
Array of strings [ 1 .. 5 ] items [ items [ 2 .. 30 ] characters ]

Video tags (maximum 5 tags each between 2 and 30 characters)

thumbnailfile
string <binary>

Video thumbnail file

waitTranscoding
string

Whether or not we wait transcoding before publish the video

Responses

Get a video

path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
  • "shortUUID": "2y84q2MQUMWPbiEcxNXMgC",
  • "isLive": true,
  • "createdAt": "2017-10-01T10:52:46.396Z",
  • "publishedAt": "2018-10-01T10:52:46.396Z",
  • "updatedAt": "2021-05-04T08:01:01.502Z",
  • "originallyPublishedAt": "2010-10-01T10:52:46.396Z",
  • "category": {
    },
  • "licence": {
    },
  • "language": {
    },
  • "privacy": {
    },
  • "description": "**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\\r\\n\\r\\n\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\\r\\n*A decentralized video hosting network, based on fr...\n",
  • "duration": 1419,
  • "isLocal": true,
  • "name": "What is PeerTube?",
  • "thumbnailPath": "/static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
  • "previewPath": "/lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg",
  • "embedPath": "/videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee",
  • "views": 1337,
  • "likes": 42,
  • "dislikes": 7,
  • "nsfw": true,
  • "waitTranscoding": true,
  • "state": {
    },
  • "scheduledUpdate": {
    },
  • "blacklisted": true,
  • "blacklistedReason": "string",
  • "account": {
    },
  • "channel": {
    },
  • "userHistory": {
    },
  • "viewers": 0,
  • "descriptionPath": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description",
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "tags": [
    ],
  • "commentsEnabled": true,
  • "downloadEnabled": true,
  • "trackerUrls": [],
  • "files": [
    ],
  • "streamingPlaylists": [
    ]
}

Delete a video

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Get complete video description

path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Response samples

Content type
application/json
"**[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)**\n"

Get video source file metadata

path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Response samples

Content type
application/json
{
  • "filename": "string"
}

Notify user is watching a video

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.

path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Request Body schema: application/json
currentTime
required
integer <seconds>

timestamp within the video, in seconds

viewEvent
string
Value: "seek"

Event since last viewing call:

  • seek - If the user seeked the video

Responses

Request samples

Content type
application/json
{
  • "currentTime": 5,
  • "viewEvent": "seek"
}

Set watching progress of a video Deprecated

This endpoint has been deprecated. Use /videos/{id}/views instead

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Request Body schema: application/json
currentTime
required
integer <seconds>

timestamp within the video, in seconds

viewEvent
string
Value: "seek"

Event since last viewing call:

  • seek - If the user seeked the video

Responses

Request samples

Content type
application/json
{
  • "currentTime": 5,
  • "viewEvent": "seek"
}

Upload a video

Uses a single request to upload a video.

Authorizations:
OAuth2
Request Body schema: multipart/form-data
channelId
required
integer >= 1

Channel id that will contain this video

name
required
string [ 3 .. 120 ] characters

Video name

videofile
required
string <binary>

Video file

category
integer (VideoCategorySet)

category id of the video (see /videos/categories)

commentsEnabled
boolean

Enable or disable comments for this video

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

language
string (VideoLanguageSet)

language id of the video (see /videos/languages)

licence
integer (VideoLicenceSet)

licence id of the video (see /videos/licences)

nsfw
boolean

Whether or not this video contains sensitive content

originallyPublishedAt
string <date-time>

Date when the content was originally published

previewfile
string <binary>

Video preview file

privacy
integer (VideoPrivacySet)
Enum: 1 2 3 4

privacy id of the video (see /videos/privacies)

object (VideoScheduledUpdate)
support
string

A text tell the audience how to support the video creator

tags
Array of strings [ 1 .. 5 ] items unique [ items [ 2 .. 30 ] characters ]

Video tags (maximum 5 tags each between 2 and 30 characters)

thumbnailfile
string <binary>

Video thumbnail file

waitTranscoding
boolean

Whether or not we wait transcoding before publish the video

Responses

Request samples 

## 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"

Response samples

Content type
application/json
{
  • "video": {
    }
}

Initialize the resumable upload of a video

Uses a resumable protocol to initialize the upload of a video

Authorizations:
OAuth2
header Parameters
X-Upload-Content-Length
required
number
Example: 2469036

Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.

X-Upload-Content-Type
required
string <mimetype>
Example: video/mp4

MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.

Request Body schema: application/json
channelId
required
integer >= 1

Channel id that will contain this video

filename
required
string <filename>

Video filename including extension

name
required
string [ 3 .. 120 ] characters

Video name

category
integer (VideoCategorySet)

category id of the video (see /videos/categories)

commentsEnabled
boolean

Enable or disable comments for this video

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

language
string (VideoLanguageSet)

language id of the video (see /videos/languages)

licence
integer (VideoLicenceSet)

licence id of the video (see /videos/licences)

nsfw
boolean

Whether or not this video contains sensitive content

originallyPublishedAt
string <date-time>

Date when the content was originally published

previewfile
string <binary>

Video preview file

privacy
integer (VideoPrivacySet)
Enum: 1 2 3 4

privacy id of the video (see /videos/privacies)

object (VideoScheduledUpdate)
support
string

A text tell the audience how to support the video creator

tags
Array of strings [ 1 .. 5 ] items unique [ items [ 2 .. 30 ] characters ]

Video tags (maximum 5 tags each between 2 and 30 characters)

thumbnailfile
string <binary>

Video thumbnail file

waitTranscoding
boolean

Whether or not we wait transcoding before publish the video

Responses

Request samples

Content type
application/json
{
  • "name": "What is PeerTube?",
  • "channelId": 3,
  • "privacy": 1,
  • "category": 15,
  • "licence": 2,
  • "language": "en",
  • "description": "**[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)**\n",
  • "waitTranscoding": true,
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "nsfw": true,
  • "tags": [
    ],
  • "commentsEnabled": true,
  • "downloadEnabled": true,
  • "originallyPublishedAt": "2019-08-24T14:15:22Z",
  • "scheduleUpdate": {
    },
  • "thumbnailfile": "string",
  • "previewfile": "string",
  • "filename": "what_is_peertube.mp4"
}

Send chunk for the resumable upload of a video

Uses a resumable protocol to continue, pause or resume the upload of a video

Authorizations:
OAuth2
query Parameters
upload_id
required
string

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.

header Parameters
Content-Length
required
number
Example: 262144

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.

Content-Range
required
string
Example: bytes 0-262143/2469036

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.

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "video": {
    }
}

Cancel the resumable upload of a video, deleting any data uploaded so far

Uses a resumable protocol to cancel the upload of a video

Authorizations:
OAuth2
query Parameters
upload_id
required
string

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 ;-)

header Parameters
Content-Length
required
number
Example: 0

Responses

Create a live

Authorizations:
OAuth2
Request Body schema: multipart/form-data
channelId
required
integer

Channel id that will contain this live video

name
required
string [ 3 .. 120 ] characters

Live video/replay name

category
integer (VideoCategorySet)

category id of the video (see /videos/categories)

commentsEnabled
boolean

Enable or disable comments for this live video/replay

description
string

Live video/replay description

downloadEnabled
boolean

Enable or disable downloading for the replay of this live video

language
string (VideoLanguageSet)

language id of the video (see /videos/languages)

latencyMode
integer (LiveVideoLatencyMode)
Enum: 1 2 3

The live latency mode (Default = 1, High latency = 2, Small Latency = 3)

licence
integer (VideoLicenceSet)

licence id of the video (see /videos/licences)

nsfw
boolean

Whether or not this live video/replay contains sensitive content

permanentLive
boolean

User can stream multiple times in a permanent live

previewfile
string <binary>

Live video/replay preview file

privacy
integer (VideoPrivacySet)
Enum: 1 2 3 4

privacy id of the video (see /videos/privacies)

saveReplay
boolean
support
string

A text tell the audience how to support the creator

tags
Array of strings [ 1 .. 5 ] items [ items [ 2 .. 30 ] characters ]

Live video/replay tags (maximum 5 tags each between 2 and 30 characters)

thumbnailfile
string <binary>

Live video/replay thumbnail file

Responses

Response samples

Content type
application/json
{
  • "video": {
    }
}

Get information about a live

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Responses

Response samples

Content type
application/json
{
  • "rtmpUrl": "string",
  • "rtmpsUrl": "string",
  • "streamKey": "string",
  • "saveReplay": true,
  • "permanentLive": true,
  • "latencyMode": 1
}

Update information about a live

Authorizations:
OAuth2
path Parameters
required
id (integer) or UUIDv4 (string) or shortUUID (string)

The object id, uuid or short uuid

Request Body schema: application/json
latencyMode
integer (LiveVideoLatencyMode)
Enum: 1 2 3

The live latency mode (Default = 1, High latency = 2, Small Latency = 3)

permanentLive
boolean

User can stream multiple times in a permanent live

saveReplay
boolean

Responses

Request samples

Content type
application/json
{
  • "saveReplay": true,
  • "permanentLive": true,
  • "latencyMode": 1
}

List videos of a video channel

path Parameters
channelHandle
required
string
Example: my_username | my_username@example.com

The video channel handle

query Parameters
VideoCategorySet (integer) or Array of VideoCategorySet (integers)

category id of the video (see /videos/categories)

count
integer [ 1 .. 100 ]
Default: 15

Number of items to return

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebtorrentFiles
boolean

PeerTube >= 4.0 Display only videos that have WebTorrent files

include
integer
Enum: 0 1 2 4 8

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
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote videos

VideoLanguageSet (string) or Array of VideoLanguageSet (strings)

language id of the video (see /videos/languages). Use _unknown to filter on videos that don't have a video language

VideoLicenceSet (integer) or Array of VideoLicenceSet (integers)

licence id of the video (see /videos/licences)

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4

PeerTube >= 4.0 Display only videos in this specific privacy/privacies

skipCount
string
Default: "false"
Enum: "true" "false"

if you don't need the total in the response

sort
string
Enum: "name" "-duration" "-createdAt" "-publishedAt" "-views" "-likes" "-trending" "-hot" "-best"

Sort videos by criteria (prefixing with - means DESC order):

  • hot - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
  • best - Same than hot, but also takes into account user video history
  • trending - Sort videos by recent views ("recent" is defined by the admin)
  • views - Sort videos using their views counter
  • publishedAt - Sort by video publication date (when it became publicly available)
start
integer >= 0

Offset used to paginate results

string or Array of strings

tag(s) of the video, where all should be present in the video

string or Array of strings

tag(s) of the video

Responses