PeerTube Project Homepage
API docs by Redocly

PeerTube (6.3.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 (following RFC7807) and code (internal PeerTube code) 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

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 Web Video file

PeerTube >= 6.0

path Parameters
filename
required
string

Filename

Responses

Get private Web Video file

PeerTube >= 6.0

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 Download

Download video files

Download video file

Generate a mp4 container that contains at most 1 video stream and at most 1 audio stream. Mainly used to merge the HLS audio only video file and the HLS video only resolution file.

path Parameters
videoId
required
integer >= 1
Example: 42

The video id

query Parameters
videoFileIds
required
Array of integers

streams of video files to mux in the output

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

Comments on videos feeds

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 comments to videos of a specific account

accountName
string

limit listing comments to videos of a specific account

videoChannelId
string

limit listing comments to videos of a specific video channel

videoChannelName
string

limit listing comments to videos of a specific video channel

videoId
string

limit listing comments to a specific video

Responses

Response samples

Content type
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
        <title>PeerTube Nightly</title>
        <link>https://peertube2.cpy.re</link>
        <description>This instance is a test instance of the PeerTube project. It is updated to the latest commit in the develop branch every business day, 8pm CET.</description>
        <lastBuildDate>Sat, 30 Nov 2024 04:10:58 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>PeerTube - https://peertube2.cpy.re</generator>
        <image>
            <title>PeerTube Nightly</title>
            <url>https://peertube2.cpy.re/client/assets/images/icons/icon-96x96.png</url>
            <link>https://peertube2.cpy.re</link>
        </image>
        <copyright>All rights reserved, unless otherwise specified in the terms specified at https://peertube2.cpy.re/about and potential licenses granted by each content's rightholder.</copyright>
        <atom:link href="https://peertube2.cpy.re/feeds/video-comments.xml?filter=local" rel="self" type="application/rss+xml"/>
        <item>
            <title><![CDATA[SVP utiliser le lien YouTube dans les commentaires - ENS Palestine]]></title>
            <link>https://peertube2.cpy.re/w/rtiad8PuC2sj7QPJUfGt4Q;threadId=178265</link>
            <guid>https://peertube2.cpy.re/w/rtiad8PuC2sj7QPJUfGt4Q;threadId=178265</guid>
            <pubDate>Fri, 29 Nov 2024 13:37:07 GMT</pubDate>
            <content:encoded><![CDATA[<p>Utilisez le lien suivant pour suivre l'evenement svp: <a href="https://youtube.com/live/UtUrM5D3OmY?feature=share" target="_blank" rel="noopener noreferrer">https://youtube.com/live/UtUrM5D3OmY?feature=share</a></p>
]]></content:encoded>
            <dc:creator>ENS Palestine</dc:creator>
        </item>
        <item>
            <title><![CDATA[Metamorphosis Act 1 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</link>
            <guid>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</guid>
            <pubDate>Thu, 28 Nov 2024 22:06:33 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/gef" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>gef</span></a></span> congratulations</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[La dénazification, mission impossible - isAAAc]]></title>
            <link>https://peertube2.cpy.re/w/fXAnnkiR4iWr29gcvaJAwS;threadId=178251</link>
            <guid>https://peertube2.cpy.re/w/fXAnnkiR4iWr29gcvaJAwS;threadId=178251</guid>
            <pubDate>Thu, 28 Nov 2024 10:19:53 GMT</pubDate>
            <content:encoded><![CDATA[<p>Merci pour le partage ❤️</p>
]]></content:encoded>
            <dc:creator>isAAAc</dc:creator>
        </item>
        <item>
            <title><![CDATA[It's Squirrels!  Episode 1 - pizzapal]]></title>
            <link>https://peertube2.cpy.re/w/jgbLjkSFJBKW77SKK2U41h;threadId=178250</link>
            <guid>https://peertube2.cpy.re/w/jgbLjkSFJBKW77SKK2U41h;threadId=178250</guid>
            <pubDate>Thu, 28 Nov 2024 04:12:35 GMT</pubDate>
            <content:encoded><![CDATA[<p>im lovin these sqwrls!!!!!!!</p>
]]></content:encoded>
            <dc:creator>pizzapal</dc:creator>
        </item>
        <item>
            <title><![CDATA[Falco - Rock Me Amadeus (Official Video) - zm music]]></title>
            <link>https://peertube2.cpy.re/w/xbLGQ3cVbVVaZ9wRrhauD3;threadId=178249</link>
            <guid>https://peertube2.cpy.re/w/xbLGQ3cVbVVaZ9wRrhauD3;threadId=178249</guid>
            <pubDate>Wed, 27 Nov 2024 04:39:24 GMT</pubDate>
            <content:encoded><![CDATA[<p>oh yeah</p>
]]></content:encoded>
            <dc:creator>zm music</dc:creator>
        </item>
        <item>
            <title><![CDATA[Bombyx Mori "Motörass"- La Gare XP Paris le 23/11/2024 - raindog]]></title>
            <link>https://peertube2.cpy.re/w/wmGpz9BTqE3QjfmYo3Yj7E;threadId=178248</link>
            <guid>https://peertube2.cpy.re/w/wmGpz9BTqE3QjfmYo3Yj7E;threadId=178248</guid>
            <pubDate>Tue, 26 Nov 2024 06:27:43 GMT</pubDate>
            <content:encoded><![CDATA[<p>Very punky. Nice 😃</p>
]]></content:encoded>
            <dc:creator>raindog</dc:creator>
        </item>
        <item>
            <title><![CDATA[LibreWolf: like Firefox, but better! - Linux app pick - TKb0iZ]]></title>
            <link>https://peertube2.cpy.re/w/mMh8WTeEsyvxKKM9sSC3qA;threadId=178243</link>
            <guid>https://peertube2.cpy.re/w/mMh8WTeEsyvxKKM9sSC3qA;threadId=178243</guid>
            <pubDate>Fri, 22 Nov 2024 20:01:35 GMT</pubDate>
            <content:encoded><![CDATA[<p>i use librewolf every day</p>
]]></content:encoded>
            <dc:creator>TKb0iZ</dc:creator>
        </item>
        <item>
            <title><![CDATA[One Must Fall 2097 - Dave Heinemann 🇦🇺]]></title>
            <link>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178241</link>
            <guid>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178241</guid>
            <pubDate>Thu, 21 Nov 2024 21:14:44 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/notptr" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>notptr</span></a></span> One of my all-time favourite game soundtracks!</p>]]></content:encoded>
            <dc:creator>Dave Heinemann 🇦🇺</dc:creator>
        </item>
        <item>
            <title><![CDATA[Quelques jeux pour les Hector et Victor de Micronique - Sylvain Glaize]]></title>
            <link>https://peertube2.cpy.re/w/98x2qUN8uggSjpkR5u3Wmg;threadId=178240</link>
            <guid>https://peertube2.cpy.re/w/98x2qUN8uggSjpkR5u3Wmg;threadId=178240</guid>
            <pubDate>Thu, 21 Nov 2024 20:36:00 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://peertube.pcservice46.fr/accounts/clashoffredo" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>clashoffredo</span></a></span> merci pour la vidéo de review</p>]]></content:encoded>
            <dc:creator>Sylvain Glaize</dc:creator>
        </item>
        <item>
            <title><![CDATA[One Must Fall 2097 - notptr]]></title>
            <link>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178238</link>
            <guid>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178238</guid>
            <pubDate>Thu, 21 Nov 2024 13:20:15 GMT</pubDate>
            <content:encoded><![CDATA[<p>@[email protected] I remeber enjoying the demo. I didn't have it on my pc but I remember playing it at my grandmother's. I do enjoy that Epic Megagames went with tracker music for their games.</p>
]]></content:encoded>
            <dc:creator>notptr</dc:creator>
        </item>
        <item>
            <title><![CDATA[One Must Fall 2097 - Nazo]]></title>
            <link>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178238</link>
            <guid>https://peertube2.cpy.re/w/jnXBQxHy5Sg8bcAjyWzhhD;threadId=178238</guid>
            <pubDate>Thu, 21 Nov 2024 05:08:44 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/notptr" class="u-url mention" rel="noopener noreferrer" target="_blank">@<span>notptr</span></a></span> When I first played this game shortly after it came out (then only the demo) its music and all around quality just blew me away.  Their choice to use a tracker format for the music was really neat for someone who only knew FM synthesis up ta that point.</p>]]></content:encoded>
            <dc:creator>Nazo</dc:creator>
        </item>
        <item>
            <title><![CDATA[anonradio - 11_16_2024, 9_00_24 PM - M33]]></title>
            <link>https://peertube2.cpy.re/w/pUv6TyKUJ9HJf7Md9M4ixM;threadId=178237</link>
            <guid>https://peertube2.cpy.re/w/pUv6TyKUJ9HJf7Md9M4ixM;threadId=178237</guid>
            <pubDate>Wed, 20 Nov 2024 15:27:17 GMT</pubDate>
            <content:encoded><![CDATA[<p>⭐⭐⭐⭐⭐ 😎</p>
]]></content:encoded>
            <dc:creator>M33</dc:creator>
        </item>
        <item>
            <title><![CDATA[La France est-elle un enfer fiscal ? Spoiler : NON ! - JohnArgutie]]></title>
            <link>https://peertube2.cpy.re/w/jsLW89b53z4u7emiB6bR2j;threadId=178236</link>
            <guid>https://peertube2.cpy.re/w/jsLW89b53z4u7emiB6bR2j;threadId=178236</guid>
            <pubDate>Wed, 20 Nov 2024 06:24:54 GMT</pubDate>
            <content:encoded><![CDATA[<p>Félicitations Gilles et merci pour cette vidéo qui permet de continuer à se cultiver. Je suis convaincu par ce format qui passera plus facilement en classe de SES par exemple ou pour envoyer aux membres de la famille un peu libéraux. Je ne manquerai pas d'aller voir l'article de l'INSEE que tu as mentionné. ✌️</p>
]]></content:encoded>
            <dc:creator>JohnArgutie</dc:creator>
        </item>
        <item>
            <title><![CDATA[screwtape_202411200000 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/cPtNtBAUwrjsjHVrk8unXW;threadId=178235</link>
            <guid>https://peertube2.cpy.re/w/cPtNtBAUwrjsjHVrk8unXW;threadId=178235</guid>
            <pubDate>Wed, 20 Nov 2024 00:43:31 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/screwtape" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>screwtape</span></a></span> thanks for the fallback; we got Zhen House set inside LambdaMOO w/ DJ Screwtape from 15-Dec-2023 on aNONradio..</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Challenge Master The Handpan de Novembre 2024 - Couleurart]]></title>
            <link>https://peertube2.cpy.re/w/ipPutedC4Uv3PrQz3hjM3S;threadId=178223</link>
            <guid>https://peertube2.cpy.re/w/ipPutedC4Uv3PrQz3hjM3S;threadId=178223</guid>
            <pubDate>Mon, 18 Nov 2024 08:10:06 GMT</pubDate>
            <content:encoded><![CDATA[<p>@olivier.l    Merci à toi 😃</p>
]]></content:encoded>
            <dc:creator>Couleurart</dc:creator>
        </item>
        <item>
            <title><![CDATA[Challenge Master The Handpan de Novembre 2024 - Olivier.L]]></title>
            <link>https://peertube2.cpy.re/w/ipPutedC4Uv3PrQz3hjM3S;threadId=178223</link>
            <guid>https://peertube2.cpy.re/w/ipPutedC4Uv3PrQz3hjM3S;threadId=178223</guid>
            <pubDate>Sun, 17 Nov 2024 20:52:14 GMT</pubDate>
            <content:encoded><![CDATA[<p>Bravo à toi pour tout ce travail :clap :clap</p>
]]></content:encoded>
            <dc:creator>Olivier.L</dc:creator>
        </item>
        <item>
            <title><![CDATA[anonradio - 11_16_2024, 9_00_24 PM - senpie]]></title>
            <link>https://peertube2.cpy.re/w/pUv6TyKUJ9HJf7Md9M4ixM;threadId=178219</link>
            <guid>https://peertube2.cpy.re/w/pUv6TyKUJ9HJf7Md9M4ixM;threadId=178219</guid>
            <pubDate>Sun, 17 Nov 2024 15:46:10 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/tanakian" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>tanakian</span></a></span> 53:00 🔥🔥🔥</p>]]></content:encoded>
            <dc:creator>senpie</dc:creator>
        </item>
        <item>
            <title><![CDATA[Very short jam (Atari 800XL, DR-55, ZynAddSubFX) - Fedi.Video on PeerTube]]></title>
            <link>https://peertube2.cpy.re/w/sAmnbFVRjXusH4hHd7GQk1;threadId=178218</link>
            <guid>https://peertube2.cpy.re/w/sAmnbFVRjXusH4hHd7GQk1;threadId=178218</guid>
            <pubDate>Sat, 16 Nov 2024 10:38:27 GMT</pubDate>
            <content:encoded><![CDATA[<p>Very nice! Moody and electronic 😎</p>
]]></content:encoded>
            <dc:creator>Fedi.Video on PeerTube</dc:creator>
        </item>
        <item>
            <title><![CDATA[Manjaro Linux on Samsung Galaxy S7 natif (no android) - Malsasa]]></title>
            <link>https://peertube2.cpy.re/w/t6TcVtfVRaqWKjjeyhygAN;threadId=178212</link>
            <guid>https://peertube2.cpy.re/w/t6TcVtfVRaqWKjjeyhygAN;threadId=178212</guid>
            <pubDate>Wed, 13 Nov 2024 11:26:44 GMT</pubDate>
            <content:encoded><![CDATA[<p>Thank you for sharing.</p>
]]></content:encoded>
            <dc:creator>Malsasa</dc:creator>
        </item>
        <item>
            <title><![CDATA[my suckless caravan - vulonkaaz v4.0]]></title>
            <link>https://peertube2.cpy.re/w/p14Jvk74eejEm7ZWae68ia;threadId=178221</link>
            <guid>https://peertube2.cpy.re/w/p14Jvk74eejEm7ZWae68ia;threadId=178221</guid>
            <pubDate>Wed, 13 Nov 2024 06:04:53 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a class="u-url mention" data-user="AnDxT3gg6HNzqrilP6" href="https://libre.video/accounts/drummyfish" rel="noopener noreferrer" target="_blank">@<span>drummyfish</span></a></span> how's the caravan life now ? managed to install electricity and grow food or something ?</p>
]]></content:encoded>
            <dc:creator>vulonkaaz v4.0</dc:creator>
        </item>
    </channel>
</rss>

Common videos feeds

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

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4 5

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

Videos of subscriptions feeds

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

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

nsfw
string
Enum: "true" "false"

whether to include nsfw videos, if any

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4 5

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

Videos podcast feed

query Parameters
videoChannelId
required
string

Limit listing to a specific video channel

Responses

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
required
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": "[email protected]",
  • "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": "[email protected]",
  • "displayName": "string",
  • "channel": {
    },
  • "registrationReason": "string"
}

Response samples

Content type
application/json
{
  • "id": 42,
  • "state": {
    },
  • "registrationReason": "string",
  • "moderationResponse": "string",
  • "username": "string",
  • "email": "[email protected]",
  • "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-urlencode 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 | [email protected]

The username or handle of the account

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "url": "string",
  • "name": "chocobozzz",
  • "avatars": [
    ],
  • "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 | [email protected]

The username or handle of the account

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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 | [email protected]

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
{
  • "total": 1,
  • "data": [
    ]
}

List playlists of an account

path Parameters
name
required
string
Example: chocobozzz | [email protected]

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 | [email protected]

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 | [email protected]

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 | [email protected]

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
required

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

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

videoQuota
integer

The user video quota in bytes

videoQuotaDaily
integer

The user daily video quota in bytes

Responses

Request samples

Content type
application/json
{
  • "username": "chocobozzz",
  • "password": "pa$$word",
  • "email": "[email protected]",
  • "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": "[email protected]",
  • "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
required
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": "[email protected]",
  • "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

Authorizations:
OAuth2
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

Authorizations:
OAuth2
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

Authorizations:
OAuth2
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"
}

User Exports

To create an archive of user data.

Request user export

Request an archive of user data. An email is sent when the archive is ready.

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

User id

Request Body schema: application/json
withVideoFiles
boolean

Whether to include video files in the archive

Responses

Request samples

Content type
application/json
{
  • "withVideoFiles": true
}

Response samples

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

List user exports

PeerTube >= 6.1

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

User id

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "state": {
    },
  • "size": 0,
  • "privateDownloadUrl": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresOn": "2019-08-24T14:15:22Z"
}

Delete a user export

PeerTube >= 6.1

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

Entity id

userId
required
integer (id) >= 1
Example: 42

User id

Responses

User Imports

To import an archive of user data.

Initialize the resumable user import

PeerTube >= 6.1 Uses a resumable protocol to initialize the import of the archive

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
filename
string <filename>

Archive filename including extension

Responses

Request samples

Content type
application/json
{
  • "filename": "user-export-6-2024-02-09T10_12_11.682Z"
}

Send chunk for the resumable user import

PeerTube >= 6.1 Uses a resumable protocol to continue, pause or resume the import of the archive

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

Cancel the resumable user import

PeerTube >= 6.1 Uses a resumable protocol to cancel the resumable user import

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: 0

Responses

Get latest user import

PeerTube >= 6.1

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

User id

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "state": {
    },
  • "createdAt": "2019-08-24T14:15:22Z"
}

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
required
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": "[email protected]",
  • "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"
}

List 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
{}

Get if subscriptions exist for my user

Authorizations:
OAuth2
query Parameters
uris
required
Array of strings <uri> [ items <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
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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 | [email protected]

The subscription handle

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "url": "string",
  • "name": "chocobozzz",
  • "avatars": [
    ],
  • "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 | [email protected]

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 | [email protected]

The username or handle of the account

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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

header Parameters
x-peertube-video-password
string

Required on password protected video

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
required
Array
Any of
name
string
Value: "cut"
object

Responses

List videos

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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
{
  • "1": "Music",
  • "2": "Films",
  • "3": "Vehicles",
  • "4": "Art",
  • "5": "Sports",
  • "6": "Travels",
  • "7": "Gaming",
  • "8": "People",
  • "9": "Comedy",
  • "10": "Entertainment",
  • "11": "News & Politics",
  • "12": "How To",
  • "13": "Education",
  • "14": "Activism",
  • "15": "Science & Technology",
  • "16": "Animals",
  • "17": "Kids",
  • "18": "Food"
}

List available video licences

Responses

Response samples

Content type
application/json
{
  • "1": "Attribution",
  • "2": "Attribution - Share Alike",
  • "3": "Attribution - No Derivatives",
  • "4": "Attribution - Non Commercial",
  • "5": "Attribution - Non Commercial - Share Alike",
  • "6": "Attribution - Non Commercial - No Derivatives",
  • "7": "Public Domain Dedication"
}

List available video languages

Responses

Response samples

Content type
application/json
{
  • "aa": "Afar",
  • "ab": "Abkhazian",
  • "af": "Afrikaans",
  • "ak": "Akan",
  • "am": "Amharic",
  • "ar": "Arabic",
  • "an": "Aragonese",
  • "ase": "American Sign Language",
  • "as": "Assamese",
  • "asq": "Austrian Sign Language",
  • "av": "Avaric",
  • "avk": "Kotava",
  • "ay": "Aymara",
  • "az": "Azerbaijani",
  • "ba": "Bashkir",
  • "bm": "Bambara",
  • "be": "Belarusian",
  • "bn": "Bengali",
  • "bfi": "British Sign Language",
  • "bi": "Bislama",
  • "bo": "Tibetan",
  • "bs": "Bosnian",
  • "br": "Breton",
  • "bg": "Bulgarian",
  • "bzs": "Brazilian Sign Language",
  • "ca": "Catalan",
  • "cs": "Czech",
  • "ch": "Chamorro",
  • "ce": "Chechen",
  • "cv": "Chuvash",
  • "kw": "Cornish",
  • "co": "Corsican",
  • "cr": "Cree",
  • "cse": "Czech Sign Language",
  • "csl": "Chinese Sign Language",
  • "cy": "Welsh",
  • "da": "Danish",
  • "de": "German",
  • "dv": "Dhivehi",
  • "dsl": "Danish Sign Language",
  • "dz": "Dzongkha",
  • "el": "Greek",
  • "en": "English",
  • "eo": "Esperanto",
  • "et": "Estonian",
  • "eu": "Basque",
  • "ee": "Ewe",
  • "fo": "Faroese",
  • "fa": "Persian",
  • "fj": "Fijian",
  • "fi": "Finnish",
  • "fr": "French",
  • "fy": "Western Frisian",
  • "fse": "Finnish Sign Language",
  • "fsl": "French Sign Language",
  • "ff": "Fulah",
  • "gcf": "Guadeloupean Creole French",
  • "gd": "Scottish Gaelic",
  • "ga": "Irish",
  • "gl": "Galician",
  • "gv": "Manx",
  • "gn": "Guarani",
  • "gsg": "German Sign Language",
  • "gu": "Gujarati",
  • "ht": "Haitian",
  • "ha": "Hausa",
  • "sh": "Serbo-Croatian",
  • "he": "Hebrew",
  • "hz": "Herero",
  • "hi": "Hindi",
  • "ho": "Hiri Motu",
  • "hr": "Croatian",
  • "hu": "Hungarian",
  • "hy": "Armenian",
  • "ig": "Igbo",
  • "ii": "Sichuan Yi",
  • "iu": "Inuktitut",
  • "id": "Indonesian",
  • "ik": "Inupiaq",
  • "is": "Icelandic",
  • "it": "Italian",
  • "jv": "Javanese",
  • "jbo": "Lojban",
  • "ja": "Japanese",
  • "jsl": "Japanese Sign Language",
  • "kab": "Kabyle",
  • "kl": "Kalaallisut",
  • "kn": "Kannada",
  • "ks": "Kashmiri",
  • "ka": "Georgian",
  • "kr": "Kanuri",
  • "kk": "Kazakh",
  • "km": "Khmer",
  • "ki": "Kikuyu",
  • "rw": "Kinyarwanda",
  • "ky": "Kirghiz",
  • "kv": "Komi",
  • "kg": "Kongo",
  • "ko": "Korean",
  • "kj": "Kuanyama",
  • "ku": "Kurdish",
  • "lo": "Lao",
  • "la": "Latin",
  • "lv": "Latvian",
  • "li": "Limburgan",
  • "ln": "Lingala",
  • "lt": "Lithuanian",
  • "lb": "Luxembourgish",
  • "lu": "Luba-Katanga",
  • "lg": "Ganda",
  • "mh": "Marshallese",
  • "ml": "Malayalam",
  • "mr": "Marathi",
  • "mk": "Macedonian",
  • "mg": "Malagasy",
  • "mt": "Maltese",
  • "mn": "Mongolian",
  • "mi": "Maori",
  • "ms": "Malay (macrolanguage)",
  • "my": "Burmese",
  • "na": "Nauru",
  • "nv": "Navajo",
  • "nr": "South Ndebele",
  • "nd": "North Ndebele",
  • "ng": "Ndonga",
  • "ne": "Nepali (macrolanguage)",
  • "nl": "Dutch",
  • "nn": "Norwegian Nynorsk",
  • "nb": "Norwegian Bokmål",
  • "no": "Norwegian",
  • "ny": "Nyanja",
  • "oc": "Occitan",
  • "oj": "Ojibwa",
  • "or": "Oriya (macrolanguage)",
  • "om": "Oromo",
  • "os": "Ossetian",
  • "pa": "Panjabi",
  • "pks": "Pakistan Sign Language",
  • "pl": "Polish",
  • "pt": "Portuguese (Brazilian)",
  • "ps": "Pushto",
  • "qu": "Quechua",
  • "rm": "Romansh",
  • "ro": "Romanian",
  • "rsl": "Russian Sign Language",
  • "rn": "Rundi",
  • "ru": "Russian",
  • "sg": "Sango",
  • "sdl": "Saudi Arabian Sign Language",
  • "sfs": "South African Sign Language",
  • "si": "Sinhala",
  • "sk": "Slovak",
  • "sl": "Slovenian",
  • "se": "Northern Sami",
  • "sm": "Samoan",
  • "sn": "Shona",
  • "sd": "Sindhi",
  • "so": "Somali",
  • "st": "Southern Sotho",
  • "es": "Spanish (Spain)",
  • "sq": "Albanian",
  • "sc": "Sardinian",
  • "sr": "Serbian",
  • "ss": "Swati",
  • "su": "Sundanese",
  • "sw": "Swahili (macrolanguage)",
  • "sv": "Swedish",
  • "swl": "Swedish Sign Language",
  • "ty": "Tahitian",
  • "ta": "Tamil",
  • "tt": "Tatar",
  • "te": "Telugu",
  • "tg": "Tajik",
  • "tl": "Tagalog",
  • "th": "Thai",
  • "ti": "Tigrinya",
  • "tlh": "Klingon",
  • "to": "Tonga (Tonga Islands)",
  • "tn": "Tswana",
  • "ts": "Tsonga",
  • "tk": "Turkmen",
  • "tr": "Turkish",
  • "tw": "Twi",
  • "ug": "Uighur",
  • "uk": "Ukrainian",
  • "ur": "Urdu",
  • "uz": "Uzbek",
  • "ve": "Venda",
  • "vi": "Vietnamese",
  • "wa": "Walloon",
  • "wo": "Wolof",
  • "xh": "Xhosa",
  • "yi": "Yiddish",
  • "yo": "Yoruba",
  • "za": "Zhuang",
  • "zh": "Chinese",
  • "zu": "Zulu",
  • "zxx": "No linguistic content",
  • "tok": "Toki Pona",
  • "pt-PT": "Portuguese (Portugal)",
  • "es-419": "Spanish (Latin America)",
  • "zh-Hans": "Simplified Chinese",
  • "zh-Hant": "Traditional Chinese",
  • "ca-valencia": "Valencian"
}

List available video privacy policies

Responses

Response samples

Content type
application/json
{
  • "1": "Public",
  • "2": "Unlisted",
  • "3": "Private",
  • "4": "Internal",
  • "5": "Password protected"
}

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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

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 or null <date-time>

Date when the content was originally published

previewfile
string <binary>

Video preview file

privacy
integer (VideoPrivacySet)
Enum: 1 2 3 4 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
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

header Parameters
x-peertube-video-password
string

Required on password protected video

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": {
    },
  • "truncatedDescription": "**[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,
  • "aspectRatio": 1.778,
  • "isLocal": true,
  • "name": "What is PeerTube?",
  • "thumbnailPath": "/lazy-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,
  • "description": "\t\"**[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,\n based on free/libre software!*\\r\\n\\r\\n**Animation Produced by:** [LILA](https://libreart.info) - [ZeMarmot Team](https://film.zemarmot.net)\\r\\n\n *Directed by* Aryeom\\r\\n*Assistant* Jehan\\r\\n**Licence**: [CC-By-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\\r\\n\\r\\n\n **Sponsored by** [Framasoft](https://framasoft.org)\\r\\n\\r\\n**Music**: [Red Step Forward](http://play.dogmazic.net/song.php?song_id=52491) - CC-By Ken Bushima\\r\\n\\r\\n\n **Movie Clip**: [Caminades 3: Llamigos](http://www.caminandes.com/) CC-By Blender Institute\\r\\n\\r\\n**Video sources**: https://gitlab.gnome.org/Jehan/what-is-peertube/\"\n",
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "tags": [
    ],
  • "commentsEnabled": true,
  • "commentsPolicy": {
    },
  • "downloadEnabled": true,
  • "inputFileUpdatedAt": "2019-08-24T14:15:22Z",
  • "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

header Parameters
x-peertube-video-password
string

Required on password protected video

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"

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
required
currentTime
required
integer <seconds>

timestamp within the video, in seconds

sessionId
string

Optional param to represent the current viewer session. Used by the backend to properly count one view per session per video. PeerTube admin can configure the server to not trust this sessionId parameter but use the request IP address instead to identify a viewer.

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",
  • "sessionId": "string"
}

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
required
currentTime
required
integer <seconds>

timestamp within the video, in seconds

sessionId
string

Optional param to represent the current viewer session. Used by the backend to properly count one view per session per video. PeerTube admin can configure the server to not trust this sessionId parameter but use the request IP address instead to identify a viewer.

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",
  • "sessionId": "string"
}

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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
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,
  • "generateTranscription": true,
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "nsfw": true,
  • "tags": [
    ],
  • "commentsEnabled": true,
  • "commentsPolicy": 1,
  • "downloadEnabled": true,
  • "originallyPublishedAt": "2019-08-24T14:15:22Z",
  • "scheduleUpdate": {
    },
  • "thumbnailfile": "string",
  • "previewfile": "string",
  • "videoPasswords": [
    ],
  • "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 hour, it is not valid anymore and you need to initialize a new upload.

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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

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 5

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

object (LiveVideoReplaySettings)
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,
  • "replaySettings": {
    },
  • "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

object (LiveVideoReplaySettings)
saveReplay
boolean

Responses

Request samples

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

Get video source file metadata

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
{
  • "filename": "string",
  • "inputFilename": "string",
  • "fileDownloadUrl": "string",
  • "resolution": {
    },
  • "size": 0,
  • "fps": 0,
  • "width": 0,
  • "height": 0,
  • "createdAt": "2019-08-24T14:15:22Z"
}

Delete video source file

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

The object id, uuid or short uuid

Responses

Initialize the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to initialize the replacement 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
filename
string <filename>

Video filename including extension

Responses

Request samples

Content type
application/json
{
  • "filename": "what_is_peertube.mp4"
}

Send chunk for the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to continue, pause or resume the replacement 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

Cancel the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to cancel the replacement 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: 0

Responses

List storyboards of a video

PeerTube >= 6.0

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
{
  • "storyboards": [
    ]
}

List videos of a video channel

path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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": [
    ]
}

Search videos

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

durationMax
integer

Get videos that have this maximum duration

durationMin
integer

Get videos that have this minimum duration

endDate
string <date-time>

Get videos that are published before this date

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

host
string

Find elements owned by this host

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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

originallyPublishedEndDate
string <date-time>

Get videos that are originally published before this date

originallyPublishedStartDate
string <date-time>

Get videos that are originally published after this date

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4 5

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

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
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" "-match"

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

start
integer >= 0

Offset used to paginate results

startDate
string <date-time>

Get videos that are published after this date

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

uuids
Array of strings

Find elements with specific UUIDs

Responses

Callbacks

Response samples

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

Video Upload

Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.

Upload

  • legacy, where the video file is sent in a single request
  • resumable, 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
  • 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.

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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
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,
  • "generateTranscription": true,
  • "support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
  • "nsfw": true,
  • "tags": [
    ],
  • "commentsEnabled": true,
  • "commentsPolicy": 1,
  • "downloadEnabled": true,
  • "originallyPublishedAt": "2019-08-24T14:15:22Z",
  • "scheduleUpdate": {
    },
  • "thumbnailfile": "string",
  • "previewfile": "string",
  • "videoPasswords": [
    ],
  • "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 hour, it is not valid anymore and you need to initialize a new upload.

header Parameters
Content-Length
required
number
Example: 0

Responses

Import a video

Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)

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

Channel id that will contain this video

name
required
string [ 3 .. 120 ] characters

Video name

targetUrl
required
string <url>

remote URL where to find the import's source video

category
integer (VideoCategorySet)

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

commentsEnabled
boolean
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
waitTranscoding
boolean

Whether or not we wait transcoding before publish the video

Responses

Response samples

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

Initialize the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to initialize the replacement 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
filename
string <filename>

Video filename including extension

Responses

Request samples

Content type
application/json
{
  • "filename": "what_is_peertube.mp4"
}

Send chunk for the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to continue, pause or resume the replacement 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

Cancel the resumable replacement of a video

PeerTube >= 6.0 Uses a resumable protocol to cancel the replacement 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: 0

Responses

Video Imports

Operations dealing with listing, adding and removing video imports.

Import a video

Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)

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

Channel id that will contain this video

name
required
string [ 3 .. 120 ] characters

Video name

targetUrl
required
string <url>

remote URL where to find the import's source video

category
integer (VideoCategorySet)

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

commentsEnabled
boolean
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

description
string

Video description

downloadEnabled
boolean

Enable or disable downloading for this video

generateTranscription
boolean

PeerTube >= 6.2 If enabled by the admin, automatically generate a subtitle of the 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 5

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

videoPasswords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]
waitTranscoding
boolean

Whether or not we wait transcoding before publish the video

Responses

Response samples

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

Cancel video import

Cancel a pending video import

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

Entity id

Responses

Delete video import

Delete ended video import

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

Entity id

Responses

Video Captions

Operations dealing with listing, adding and removing closed captions of a video.

List captions of a video

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

The object id, uuid or short uuid

header Parameters
x-peertube-video-password
string

Required on password protected video

Responses

Response samples

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

Generate a video caption

PeerTube >= 6.2 This feature has to be enabled by the administrator

Authorizations:
OAuth2
Request Body schema: application/json
forceTranscription
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "forceTranscription": false
}

Add or replace a video caption

Authorizations:
OAuth2
path Parameters
captionLanguage
required
string (VideoLanguageSet)
Example: en

The caption language

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

The object id, uuid or short uuid

Request Body schema: multipart/form-data
captionfile
string <binary>

The file to upload.

Responses

Delete a video caption

Authorizations:
OAuth2
path Parameters
captionLanguage
required
string (VideoLanguageSet)
Example: en

The caption language

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

The object id, uuid or short uuid

Responses

Video Chapters

Operations dealing with managing chapters of a video.

Get chapters of a video

PeerTube >= 6.0

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

The object id, uuid or short uuid

header Parameters
x-peertube-video-password
string

Required on password protected video

Responses

Response samples

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

Replace video chapters

PeerTube >= 6.0

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
Array of objects

Responses

Request samples

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

Video Channels

Operations dealing with the creation, modification and listing of videos within a channel.

List video channels

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": [
    ]
}

Create a video channel

Authorizations:
OAuth2
Request Body schema: application/json
displayName
required
any

Channel display name

name
required
string [ 1 .. 50 ] characters /^[a-zA-Z0-9\\-_.:]+$/

username of the channel to create

description
any

Channel description

support
any

How to support/fund the channel

Responses

Request samples

Content type
application/json
{
  • "displayName": null,
  • "description": null,
  • "support": null,
  • "name": "framasoft_videos"
}

Response samples

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

Get a video channel

path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "url": "string",
  • "name": "chocobozzz",
  • "avatars": [
    ],
  • "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": {
    }
}

Update a video channel

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Request Body schema: application/json
bulkVideosSupportUpdate
boolean

Update the support field for all videos of this channel

description
any

Channel description

displayName
any

Channel display name

support
any

How to support/fund the channel

Responses

Request samples

Content type
application/json
{
  • "displayName": null,
  • "description": null,
  • "support": null,
  • "bulkVideosSupportUpdate": true
}

Delete a video channel

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Responses

List videos of a video channel

path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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 5

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

search
string

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

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 playlists of a channel

path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

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)

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 followers of a video channel

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

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": [
    ]
}

Update channel avatar

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

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

The file to upload.

Responses

Response samples

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

Delete channel avatar

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Responses

Update channel banner

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Request Body schema: multipart/form-data
bannerfile
string <binary>

The file to upload.

Responses

Response samples

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

Delete channel banner

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Responses

Import videos in channel

Import a remote channel/playlist videos into a channel

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Request Body schema: application/json
externalChannelUrl
required
string
videoChannelSyncId
integer

If part of a channel sync process, specify its id to assign video imports to this channel synchronization

Responses

Request samples

Content type
application/json
{}

List video channels of an account

path Parameters
name
required
string
Example: chocobozzz | [email protected]

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 | [email protected]

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": [
    ]
}

Search channels

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

Number of items to return

handles
Array of strings

Find elements with these handles

host
string

Find elements owned by this host

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete channel information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Callbacks

Response samples

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

Video Comments

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.

List comments on user's videos

PeerTube >= 6.2

Authorizations:
OAuth2
query Parameters
string or Array of strings

PeerTube >= 6.2 filter on comments that contain one of these automatic tags

isHeldForReview
boolean

only display comments that are held for review

search
string

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

searchAccount
string

Filter comments by searching on the account

searchVideo
string

Filter comments by searching on the video

videoChannelId
integer

Limit results on this specific video channel

videoId
integer

Limit results on this specific video

Responses

Response samples

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

List threads of a video

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

The object id, uuid or short uuid

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

Number of items to return

sort
string
Enum: "-createdAt" "-totalReplies"

Sort comments by criteria

start
integer >= 0

Offset used to paginate results

header Parameters
x-peertube-video-password
string

Required on password protected video

Responses

Response samples

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

Create a thread

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
text
required
string <html> [ 1 .. 10000 ] characters

Text of the comment

Responses

Request samples

Content type
application/json
{
  • "text": "This video is wonderful!"
}

Response samples

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

Get a thread

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

The object id, uuid or short uuid

threadId
required
integer

The thread id (root comment id)

header Parameters
x-peertube-video-password
string

Required on password protected video

Responses

Response samples

Content type
application/json
{
  • "comment": {
    },
  • "children": [
    ]
}

List instance comments

Authorizations:
OAuth2
query Parameters
string or Array of strings

PeerTube >= 6.2 filter on comments that contain one of these automatic tags

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

onLocalVideo
boolean

Display only objects of local or remote videos

search
string

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

searchAccount
string

Filter comments by searching on the account

searchVideo
string

Filter comments by searching on the video

videoChannelId
integer

Limit results on this specific video channel

videoId
integer

Limit results on this specific video

Responses

Response samples

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

Reply to a thread of a video

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

The comment id

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

The object id, uuid or short uuid

header Parameters
x-peertube-video-password
string

Required on password protected video

Request Body schema: application/json
text
required
string <html> [ 1 .. 10000 ] characters

Text of the comment

Responses

Request samples

Content type
application/json
{
  • "text": "This video is wonderful!"
}

Response samples

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

Delete a comment or a reply

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

The comment id

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

The object id, uuid or short uuid

Responses

Approve a comment

PeerTube >= 6.2 Approve a comment that requires a review

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

The comment id

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

The object id, uuid or short uuid

Responses

Video Rates

Like/dislike a video.

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

Like/dislike a video

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

The object id, uuid or short uuid

header Parameters
x-peertube-video-password
string

Required on password protected video

Request Body schema: application/json
rating
required
string
Enum: "like" "dislike"

Responses

Request samples

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

Video Playlists

Operations dealing with playlists of videos. Playlists are bound to users and/or channels.

List playlists of a channel

path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

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)

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 available playlist privacy policies

Responses

Response samples

Content type
application/json
{
  • "1": "Public",
  • "2": "Unlisted",
  • "3": "Private"
}

List video playlists

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)

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": [
    ]
}

Create a video playlist

If the video playlist is set as public, videoChannelId is mandatory.

Authorizations:
OAuth2
Request Body schema: multipart/form-data
displayName
required
string [ 1 .. 120 ] characters

Video playlist display name

description
string [ 3 .. 1000 ] characters

Video playlist description

privacy
integer (VideoPlaylistPrivacySet)
Enum: 1 2 3

Video playlist privacy policy (see /video-playlists/privacies)

thumbnailfile
string <binary>

Video playlist thumbnail file

videoChannelId
integer >= 1

Video channel in which the playlist will be published

Responses

Response samples

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

Get a video playlist

path Parameters
playlistId
required
integer >= 1
Example: 42

Playlist id

Responses

Response samples

Content type
application/json
{
  • "id": 42,
  • "uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
  • "shortUUID": "2y84q2MQUMWPbiEcxNXMgC",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "displayName": "string",
  • "isLocal": true,
  • "videoLength": 0,
  • "thumbnailPath": "string",
  • "privacy": {
    },
  • "type": {
    },
  • "ownerAccount": {
    },
  • "videoChannel": {
    }
}

Update a video playlist

If the video playlist is set as public, the playlist must have a assigned channel.

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

Playlist id

Request Body schema: multipart/form-data
description
string

Video playlist description

displayName
string [ 1 .. 120 ] characters

Video playlist display name

privacy
integer (VideoPlaylistPrivacySet)
Enum: 1 2 3

Video playlist privacy policy (see /video-playlists/privacies)

thumbnailfile
string <binary>

Video playlist thumbnail file

videoChannelId
integer >= 1

Video channel in which the playlist will be published

Responses

Delete a video playlist

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

Playlist id

Responses

List videos of a playlist

path Parameters
playlistId
required
integer >= 1
Example: 42

Playlist id

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

Number of items to return

start
integer >= 0

Offset used to paginate results

Responses

Response samples

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

Add a video in a playlist

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

Playlist id

Request Body schema: application/json
required
string or integer

Video to add in the playlist

startTimestamp
integer <seconds>

Start the video at this specific timestamp

stopTimestamp
integer <seconds>

Stop the video at this specific timestamp

Responses

Request samples

Content type
application/json
{
  • "videoId": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
  • "startTimestamp": 0,
  • "stopTimestamp": 0
}

Response samples

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

Reorder a playlist

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

Playlist id

Request Body schema: application/json
insertAfterPosition
required
integer >= 0

New position for the block to reorder, to add the block before the first element

startPosition
required
integer >= 1

Start position of the element to reorder

reorderLength
integer >= 1

How many element from startPosition to reorder

Responses

Request samples

Content type
application/json
{
  • "startPosition": 1,
  • "insertAfterPosition": 0,
  • "reorderLength": 1
}

Update a playlist element

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

Playlist element id

playlistId
required
integer >= 1
Example: 42

Playlist id

Request Body schema: application/json
startTimestamp
integer <seconds>

Start the video at this specific timestamp

stopTimestamp
integer <seconds>

Stop the video at this specific timestamp

Responses

Request samples

Content type
application/json
{
  • "startTimestamp": 0,
  • "stopTimestamp": 0
}

Delete an element from a playlist

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

Playlist element id

playlistId
required
integer >= 1
Example: 42

Playlist id

Responses

Check video exists in my playlists

Authorizations:
OAuth2
query Parameters
videoIds
required
Array of integers[ items >= 1 ]
Example: videoIds=42

The video ids to check

Responses

Response samples

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

List playlists of an account

path Parameters
name
required
string
Example: chocobozzz | [email protected]

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": [
    ]
}

Search playlists

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

Number of items to return

host
string

Find elements owned by this host

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete playlist information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

uuids
Array of strings

Find elements with specific UUIDs

Responses

Callbacks

Response samples

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

Video Stats

Video statistics

Get overall stats of a video

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

The object id, uuid or short uuid

query Parameters
endDate
string <date-time>

Filter stats by end date

startDate
string <date-time>

Filter stats by start date

Responses

Response samples

Content type
application/json
{
  • "averageWatchTime": 0,
  • "totalWatchTime": 0,
  • "viewersPeak": 0,
  • "viewersPeakDate": "2019-08-24T14:15:22Z",
  • "countries": [
    ]
}

Get retention stats of a video

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
{
  • "data": [
    ]
}

Get timeserie stats of a video

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

The object id, uuid or short uuid

metric
required
string
Enum: "viewers" "aggregateWatchTime"

The metric to get

query Parameters
endDate
string <date-time>

Filter stats by end date

startDate
string <date-time>

Filter stats by start date

Responses

Response samples

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

Video Ownership Change

List video ownership changes

Authorizations:
OAuth2

Responses

Accept ownership change request

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

The object id, uuid or short uuid

Responses

Refuse ownership change request

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

The object id, uuid or short uuid

Responses

Request ownership change

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
required
username
required
string

Responses

Video Mirroring

PeerTube instances can mirror videos from one another, and help distribute some videos.

For importing videos as your own, refer to video imports.

List videos being mirrored

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

Number of items to return

sort
string
Value: "name"

Sort abuses by criteria

start
integer >= 0

Offset used to paginate results

target
required
string
Enum: "my-videos" "remote-videos"

direction of the mirror

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Mirror a video

Authorizations:
OAuth2
Request Body schema: application/json
videoId
required
integer >= 1

object id for the video

Responses

Request samples

Content type
application/json
{
  • "videoId": 42
}

Delete a mirror done on a video

Authorizations:
OAuth2
path Parameters
redundancyId
required
string

id of an existing redundancy on a video

Responses

Video Files

Operations on video files

Delete video HLS files

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

The object id, uuid or short uuid

Responses

Delete video Web Video files

PeerTube >= 6.0

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

The object id, uuid or short uuid

Responses

Video Transcoding

Video transcoding related operations

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
required
Array
Any of
name
string
Value: "cut"
object

Responses

Create a transcoding job

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
transcodingType
required
string
Enum: "hls" "web-video"
forceTranscoding
boolean
Default: false

If the video is stuck in transcoding state, do it anyway

Responses

Request samples

Content type
application/json
{
  • "transcodingType": "hls",
  • "forceTranscoding": false
}

Live Videos

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
Deprecated

Deprecated in 6.2, use commentsPolicy instead

commentsPolicy
integer (VideoCommentsPolicySet)
Enum: 1 2 3

Comments policy of the video (Enabled = 1, Disabled = 2, Requires Approval = 3)

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 5

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

object (LiveVideoReplaySettings)
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,
  • "replaySettings": {
    },
  • "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

object (LiveVideoReplaySettings)
saveReplay
boolean

Responses

Request samples

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

List live sessions

List all sessions created in a particular 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
{
  • "total": 1,
  • "data": [
    ]
}

Get live session of a replay

If the video is a replay of a live, you can find the associated live session using this endpoint

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

The object id, uuid or short uuid

header Parameters
x-peertube-video-password
string

Required on password protected video

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "error": 1,
  • "replayVideo": {
    }
}

Channels Sync

Operations dealing with synchronizing PeerTube user's channel with channels of other platforms

Import videos in channel

Import a remote channel/playlist videos into a channel

Authorizations:
OAuth2
path Parameters
channelHandle
required
string
Example: my_username | [email protected]

The video channel handle

Request Body schema: application/json
externalChannelUrl
required
string
videoChannelSyncId
integer

If part of a channel sync process, specify its id to assign video imports to this channel synchronization

Responses

Request samples

Content type
application/json
{}

Create a synchronization for a video channel

Authorizations:
OAuth2
Request Body schema: application/json
externalChannelUrl
string
videoChannelId
integer (id) >= 1

Responses

Request samples

Content type
application/json
{}

Response samples

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

Delete a video channel synchronization

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

Channel Sync id

Responses

Triggers the channel synchronization job, fetching all the videos from the remote channel

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

Channel Sync id

Responses

List the synchronizations of video channels of an account

path Parameters
name
required
string
Example: chocobozzz | [email protected]

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": [
    ]
}

Video Passwords

Operation on video passwords

List video passwords

PeerTube >= 6.0

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

The object id, uuid or short uuid

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 video passwords

PeerTube >= 6.0

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
passwords
Array of strings (AddVideoPasswords) unique [ items >= 2 characters ]

Responses

Request samples

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

Delete a video password

PeerTube >= 6.0

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

The object id, uuid or short uuid

videoPasswordId
required
integer (id) >= 1
Example: 42

The video password id

Responses

Search

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.

Search videos

query Parameters
string or Array of strings

PeerTube >= 6.2 Admins and moderators only filter on videos that contain one of these automatic tags

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

durationMax
integer

Get videos that have this maximum duration

durationMin
integer

Get videos that have this minimum duration

endDate
string <date-time>

Get videos that are published before this date

excludeAlreadyWatched
boolean

Whether or not to exclude videos that are in the user's video history

hasHLSFiles
boolean

PeerTube >= 4.0 Display only videos that have HLS files

hasWebVideoFiles
boolean

PeerTube >= 6.0 Display only videos that have Web Video files

host
string

Find elements owned by this host

include
integer
Enum: 0 1 2 4 8 16 32

Only administrators and moderators can use this parameter

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
  • 16 CAPTIONS
  • 32 VIDEO SOURCE
isLive
boolean

whether or not the video is a live

isLocal
boolean

PeerTube >= 4.0 Display only local or remote objects

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

originallyPublishedEndDate
string <date-time>

Get videos that are originally published before this date

originallyPublishedStartDate
string <date-time>

Get videos that are originally published after this date

privacyOneOf
integer (VideoPrivacySet)
Enum: 1 2 3 4 5

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

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
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" "-match"

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

start
integer >= 0

Offset used to paginate results

startDate
string <date-time>

Get videos that are published after this date

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

uuids
Array of strings

Find elements with specific UUIDs

Responses

Callbacks

Response samples

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

Search channels

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

Number of items to return

handles
Array of strings

Find elements with these handles

host
string

Find elements owned by this host

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete channel information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Callbacks

Response samples

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

Search playlists

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

Number of items to return

host
string

Find elements owned by this host

search
required
string

String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete playlist information and interact with it.

searchTarget
string
Enum: "local" "search-index"

If the administrator enabled search index support, you can override the default search target.

Warning: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:

  • If the current user has the ability to make a remote URI search (this information is available in the config endpoint), then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database. After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
  • If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch the data from the origin instance API
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

uuids
Array of strings

Find elements with specific UUIDs

Responses

Callbacks

Response samples

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

Abuses

Abuses deal with reports of local or remote videos/comments/accounts alike.

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": [
    ]
}

List abuses

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

Number of items to return

filter
string
Enum: "video" "comment" "account"

only list account, comment or video reports

id
integer

only list the report with this id

predefinedReason
Array of strings (PredefinedAbuseReasons) <= 8 items
Items Enum: "violentOrAbusive" "hatefulOrAbusive" "spamOrMisleading" "privacy" "rights" "serverRules" "thumbnails" "captions"

predefined reason the listed reports should contain

search
string

plain search that will match with video titles, reporter names and more

searchReportee
string

only list reports of a specific reportee

searchReporter
string

only list reports of a specific reporter

searchVideo
string

only list reports of a specific video

searchVideoChannel
string

only list reports of a specific video channel

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)

videoIs
string
Enum: "deleted" "blacklisted"

only list deleted or blocklisted videos

Responses

Response samples

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

Report an abuse

Authorizations:
OAuth2
Request Body schema: application/json
required
reason
required
string [ 2 .. 3000 ] characters

Reason why the user reports this video

object
object
predefinedReasons
Array of strings (PredefinedAbuseReasons) <= 8 items
Items Enum: "violentOrAbusive" "hatefulOrAbusive" "spamOrMisleading" "privacy" "rights" "serverRules" "thumbnails" "captions"

Reason categories that help triage reports

object

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "predefinedReasons": [
    ],
  • "video": {
    },
  • "comment": {
    },
  • "account": {
    }
}

Response samples

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

Update an abuse

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

Abuse id

Request Body schema: application/json
moderationComment
string [ 2 .. 3000 ] characters

Update the report comment visible only to the moderation team

state
integer (AbuseStateSet)
Enum: 1 2 3

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

Responses

Request samples

Content type
application/json
{
  • "state": 1,
  • "moderationComment": "string"
}

Delete an abuse

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

Abuse id

Responses

List messages of an abuse

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

Abuse id

Responses

Response samples

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

Add message to an abuse

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

Abuse id

Request Body schema: application/json
required
message
required
string [ 2 .. 3000 ] characters

Message to send

Responses

Request samples

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

Delete an abuse message

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

Abuse id

abuseMessageId
required
integer >= 1
Example: 42

Abuse message id

Responses

Video Blocks

Operations dealing with blocking videos (removing them from view and preventing interactions).

Block a video

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

The object id, uuid or short uuid

Responses

Unblock a video by its id

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

The object id, uuid or short uuid

Responses

List video blocks

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

Number of items to return

search
string

plain search that will match with video titles, and more

sort
string
Enum: "-id" "name" "-duration" "-views" "-likes" "-dislikes" "-uuid" "-createdAt"

Sort blocklists by criteria

start
integer >= 0

Offset used to paginate results

type
integer
Enum: 1 2

list only blocks that match this type:

  • 1: manual block
  • 2: automatic block that needs review

Responses

Response samples

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

Account Blocks

Get block status of accounts/hosts

query Parameters
accounts
Array of strings

Check if these accounts are blocked

hosts
Array of strings
Example: hosts=example.com

Check if these hosts are blocked

Responses

Response samples

Content type
application/json
{
  • "accounts": {
    },
  • "hosts": {
    }
}

List account blocks

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

Block an account

Authorizations:
OAuth2
Request Body schema: application/json
accountName
required
string

account to block, in the form username@domain

Responses

Request samples

Content type
application/json
{}

Unblock an account by its handle

Authorizations:
OAuth2
path Parameters
accountName
required
string

account to unblock, in the form username@domain

Responses

Server Blocks

Get block status of accounts/hosts

query Parameters
accounts
Array of strings

Check if these accounts are blocked

hosts
Array of strings
Example: hosts=example.com

Check if these hosts are blocked

Responses

Response samples

Content type
application/json
{
  • "accounts": {
    },
  • "hosts": {
    }
}

List server blocks

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

Block a server

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

server domain to block

Responses

Request samples

Content type
application/json
{
  • "host": "example.com"
}

Unblock a server by its domain

Authorizations:
OAuth2
path Parameters
host
required
string <hostname>

server domain to unblock

Responses

Automatic Tags

Automatic tags set on objects (like comments or videos) by specific rules (external link, watched words, etc.)

Get account auto tag policies on comments

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string

account name to get auto tag policies

Responses

Response samples

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

Update account auto tag policies on comments

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string

account name to update auto tag policies

Request Body schema: application/json
review
Array of strings

Auto tags that automatically set the comment in review state

Responses

Request samples

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

Get account available auto tags

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string

account name to get auto tag policies

Responses

Response samples

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

Get server available auto tags

PeerTube >= 6.2

Authorizations:
OAuth2

Responses

Response samples

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

Watched Words

Manage list of watched words to detect patterns on objects (like comments of videos)

List account watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string

account name to list watched words

Responses

Response samples

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

Add account watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string
Request Body schema: application/json
listName
string
words
Array of strings

Responses

Request samples

Content type
application/json
{
  • "listName": "string",
  • "words": [
    ]
}

Response samples

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

Update account watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string
listId
required
string

list of watched words to update

Request Body schema: application/json
listName
string
words
Array of strings

Responses

Request samples

Content type
application/json
{
  • "listName": "string",
  • "words": [
    ]
}

Delete account watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
accountName
required
string
listId
required
string

list of watched words to delete

Responses

List server watched words

PeerTube >= 6.2

Authorizations:
OAuth2

Responses

Response samples

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

Add server watched words

PeerTube >= 6.2

Authorizations:
OAuth2
Request Body schema: application/json
listName
string
words
Array of strings

Responses

Request samples

Content type
application/json
{
  • "listName": "string",
  • "words": [
    ]
}

Response samples

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

Update server watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
listId
required
string

list of watched words to update

Request Body schema: application/json
listName
string
words
Array of strings

Responses

Request samples

Content type
application/json
{
  • "listName": "string",
  • "words": [
    ]
}

Delete server watched words

PeerTube >= 6.2

Authorizations:
OAuth2
path Parameters
listId
required
string

list of watched words to delete

Responses

Config

Each server exposes public information regarding supported videos and options.

Get instance public configuration

Responses

Response samples

Content type
application/json
{
  • "client": {
    },
  • "defaults": {
    },
  • "webadmin": {
    },
  • "instance": {
    },
  • "search": {
    },
  • "plugin": {
    },
  • "theme": {
    },
  • "email": {
    },
  • "contactForm": {
    },
  • "serverVersion": "7.0.0-rc.1-nightly-2024-11-29",
  • "serverCommit": "",
  • "transcoding": {
    },
  • "live": {
    },
  • "videoStudio": {
    },
  • "videoFile": {
    },
  • "videoTranscription": {
    },
  • "import": {
    },
  • "export": {
    },
  • "autoBlacklist": {
    },
  • "avatar": {
    },
  • "banner": {
    },
  • "video": {
    },
  • "videoCaption": {
    },
  • "user": {
    },
  • "videoChannels": {
    },
  • "trending": {
    },
  • "tracker": {
    },
  • "followings": {},
  • "broadcastMessage": {
    },
  • "homepage": {
    },
  • "openTelemetry": {
    },
  • "views": {
    },
  • "storyboards": {
    },
  • "webrtc": {
    },
  • "signup": {
    }
}

Get instance "About" information

Responses

Response samples

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

Get instance runtime configuration

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "instance": {
    },
  • "theme": {
    },
  • "services": {
    },
  • "cache": {
    },
  • "signup": {
    },
  • "admin": {},
  • "contactForm": {
    },
  • "user": {
    },
  • "transcoding": {
    },
  • "import": {
    },
  • "autoBlacklist": {
    },
  • "followers": {
    }
}

Set instance runtime configuration

Authorizations:
OAuth2

Responses

Delete instance runtime configuration

Authorizations:
OAuth2

Responses

Update instance banner

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

The file to upload.

Responses

Delete instance banner

Authorizations:
OAuth2

Responses

Update instance avatar

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

The file to upload.

Responses

Delete instance avatar

Authorizations:
OAuth2

Responses

Homepage

Get and update the custom homepage

Get instance custom homepage

Responses

Response samples

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

Set instance custom homepage

Authorizations:
OAuth2
Request Body schema: application/json
content
string

content of the homepage, that will be injected in the client

Responses

Request samples

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

Instance Follows

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.

https://docs.joinpeertube.org/admin/following-instances#instances-follows

List instances following the server

query Parameters
actorType
string
Enum: "Person" "Application" "Group" "Service" "Organization"
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

state
string
Enum: "pending" "accepted"

Responses

Response samples

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

Remove or reject a follower to your server

Authorizations:
OAuth2
path Parameters
nameWithHost
required
string <email>

The remote actor handle to remove from your followers

Responses

Reject a pending follower to your server

Authorizations:
OAuth2
path Parameters
nameWithHost
required
string <email>

The remote actor handle to remove from your followers

Responses

Accept a pending follower to your server

Authorizations:
OAuth2
path Parameters
nameWithHost
required
string <email>

The remote actor handle to remove from your followers

Responses

List instances followed by the server

query Parameters
actorType
string
Enum: "Person" "Application" "Group" "Service" "Organization"
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

state
string
Enum: "pending" "accepted"

Responses

Response samples

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

Follow a list of actors (PeerTube instance, channel or account)

Authorizations:
OAuth2
Request Body schema: application/json
handles
Array of strings unique
hosts
Array of strings <hostname> unique [ items <hostname > ]

Responses

Request samples

Content type
application/json
{
  • "hosts": [
    ],
  • "handles": [
    ]
}

Unfollow an actor (PeerTube instance, channel or account)

Authorizations:
OAuth2
path Parameters
hostOrHandle
required
string

The hostOrHandle to unfollow

Responses

Instance Redundancy

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.

https://docs.joinpeertube.org/admin/following-instances#instances-redundancy

Update a server redundancy policy

Authorizations:
OAuth2
path Parameters
host
required
string <hostname>

server domain to mirror

Request Body schema: application/json
redundancyAllowed
required
boolean

allow mirroring of the host's local videos

Responses

Request samples

Content type
application/json
{
  • "redundancyAllowed": true
}

Plugins

Managing plugins installed from a local path or from NPM, or search for new ones.

https://docs.joinpeertube.org/api/plugins

List plugins

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

Number of items to return

pluginType
integer
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

uninstalled
boolean

Responses

Response samples

Content type
application/json
{}

List available plugins

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

Number of items to return

currentPeerTubeEngine
string
pluginType
integer
search
string
sort
string
Example: sort=-createdAt

Sort column

start
integer >= 0

Offset used to paginate results

Responses

Response samples

Content type
application/json
{}

Install a plugin

Authorizations:
OAuth2
Request Body schema: application/json
One of
npmName
required
string

Responses

Request samples

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

Update a plugin

Authorizations:
OAuth2
Request Body schema: application/json
One of
npmName
required
string

Responses

Request samples

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

Uninstall a plugin

Authorizations:
OAuth2
Request Body schema: application/json
npmName
required
string

name of the plugin/theme in its package.json

Responses

Request samples

Content type
application/json
{
  • "npmName": "peertube-plugin-auth-ldap"
}

Get a plugin

Authorizations:
OAuth2
path Parameters
npmName
required
string
Example: peertube-plugin-auth-ldap

name of the plugin/theme on npmjs.com or in its package.json

Responses

Response samples

Content type
application/json
{}

Set a plugin's settings

Authorizations:
OAuth2
path Parameters
npmName
required
string
Example: peertube-plugin-auth-ldap

name of the plugin/theme on npmjs.com or in its package.json

Request Body schema: application/json
object

Responses

Request samples

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

Get a plugin's public settings

path Parameters
npmName
required
string
Example: peertube-plugin-auth-ldap

name of the plugin/theme on npmjs.com or in its package.json

Responses

Response samples

Content type
application/json
{ }

Get a plugin's registered settings

Authorizations:
OAuth2
path Parameters
npmName
required
string
Example: peertube-plugin-auth-ldap

name of the plugin/theme on npmjs.com or in its package.json

Responses

Response samples

Content type
application/json
{ }

Stats

Statistics

Get instance stats

Get instance public statistics. This endpoint is cached.

Responses

Response samples

Content type
application/json
{
  • "totalUsers": 0,
  • "totalDailyActiveUsers": 0,
  • "totalWeeklyActiveUsers": 0,
  • "totalMonthlyActiveUsers": 0,
  • "totalModerators": 0,
  • "totalAdmins": 0,
  • "totalLocalVideos": 0,
  • "totalLocalVideoViews": 0,
  • "totalLocalVideoComments": 0,
  • "totalLocalVideoFilesSize": 0,
  • "totalVideos": 0,
  • "totalVideoComments": 0,
  • "totalLocalVideoChannels": 0,
  • "totalLocalDailyActiveVideoChannels": 0,
  • "totalLocalWeeklyActiveVideoChannels": 0,
  • "totalLocalMonthlyActiveVideoChannels": 0,
  • "totalLocalPlaylists": 0,
  • "totalInstanceFollowers": 0,
  • "totalInstanceFollowing": 0,
  • "videosRedundancy": [
    ],
  • "totalActivityPubMessagesProcessed": 0,
  • "totalActivityPubMessagesSuccesses": 0,
  • "totalActivityPubMessagesErrors": 0,
  • "activityPubMessagesProcessedPerSecond": 0,
  • "totalActivityPubMessagesWaiting": 0,
  • "averageRegistrationRequestResponseTimeMs": 0,
  • "totalRegistrationRequestsProcessed": 0,
  • "totalRegistrationRequests": 0,
  • "averageAbuseResponseTimeMs": 0,
  • "totalAbusesProcessed": 0,
  • "totalAbuses": 0
}

Create playback metrics

These metrics are exposed by OpenTelemetry metrics exporter if enabled.

Request Body schema: application/json
downloadedBytesHTTP
required
number

How many bytes were downloaded with HTTP since the last metric creation

downloadedBytesP2P
required
number

How many bytes were downloaded with P2P since the last metric creation

errors
required
number

How many errors occurred since the last metric creation

p2pEnabled
required
boolean
playerMode
required
string
Enum: "p2p-media-loader" "web-video"
resolutionChanges
required
number

How many resolution changes occurred since the last metric creation

uploadedBytesP2P
required
number

How many bytes were uploaded with P2P since the last metric creation

required
id (integer) or UUIDv4 (string) or shortUUID (string)
bufferStalled
number

How many times buffer has been stalled since the last metric creation

fps
number

Current player video fps

p2pPeers
number

P2P peers connected (doesn't include WebSeed peers)

resolution
number

Current player video resolution

Responses

Request samples

Content type
application/json
{
  • "playerMode": "p2p-media-loader",
  • "resolution": 0,
  • "fps": 0,
  • "p2pEnabled": true,
  • "p2pPeers": 0,
  • "resolutionChanges": 0,
  • "bufferStalled": 0,
  • "errors": 0,
  • "downloadedBytesP2P": 0,
  • "downloadedBytesHTTP": 0,
  • "uploadedBytesP2P": 0,
  • "videoId": 42
}

Logs

Send client log

Request Body schema: application/json
level
required
any
Enum: "error" "warn"
message
required
string
url
required
string

URL of the current user page

meta
string

Additional information regarding this log

stackTrace
string

Stack trace of the error if there is one

userAgent
string

User agent of the web browser that sends the message

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "url": "string",
  • "level": "error",
  • "stackTrace": "string",
  • "userAgent": "string",
  • "meta": "string"
}

Get instance logs

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get instance audit logs

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • "string"
]

Job

Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available.

Pause job queue

Authorizations:
OAuth2

Responses

Resume job queue

Authorizations:
OAuth2

Responses

List instance jobs

Authorizations:
OAuth2
path Parameters
state
required
string
Enum: "" "active" "completed" "failed" "waiting" "delayed"

The state of the job ('' for for no filter)

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

Number of items to return

jobType
string
Enum: "activitypub-follow" "activitypub-http-broadcast" "activitypub-http-fetcher" "activitypub-http-unicast" "email" "video-transcoding" "video-file-import" "video-import" "videos-views-stats" "activitypub-refresher" "video-redundancy" "video-live-ending" "video-channel-import"

job type

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": [
    ]
}

Runner Registration Token

Manage runner registration token

Generate registration token

Generate a new runner registration token

Authorizations:
OAuth2

Responses

Remove registration token

Remove a registration token. Runners that used this token for their registration are automatically removed.

Authorizations:
OAuth2
path Parameters
registrationTokenId
required
integer

Responses

List registration tokens

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

Number of items to return

sort
string
Value: "createdAt"

Sort registration tokens by criteria

start
integer >= 0

Offset used to paginate results

Responses

Response samples

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

Runner Jobs

Request a new job

API used by PeerTube runners

Request Body schema: application/json
runnerToken
required
string
jobTypes
Array of strings

Filter jobs depending on their types

Responses

Request samples

Content type
application/json
{
  • "runnerToken": "string",
  • "jobTypes": [
    ]
}

Response samples

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

Accept job

API used by PeerTube runners

path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
Request Body schema: application/json
runnerToken
required
string

Responses

Request samples

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

Response samples

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

Abort job

API used by PeerTube runners

path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
Request Body schema: application/json
jobToken
required
string
reason
required
string

Why the runner aborts this job

runnerToken
required
string

Responses

Request samples

Content type
application/json
{
  • "runnerToken": "string",
  • "jobToken": "string",
  • "reason": "string"
}

Update job

API used by PeerTube runners

path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
Request Body schema: application/json
jobToken
required
string
runnerToken
required
string
object
progress
integer

Update job progression percentage (optional)

Responses

Request samples

Content type
application/json
{
  • "runnerToken": "string",
  • "jobToken": "string",
  • "progress": 0,
  • "payload": {
    }
}

Post job error

API used by PeerTube runners

path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
Request Body schema: application/json
jobToken
required
string
message
required
string

Why the runner failed to process this job

runnerToken
required
string

Responses

Request samples

Content type
application/json
{
  • "runnerToken": "string",
  • "jobToken": "string",
  • "message": "string"
}

Post job success

API used by PeerTube runners

path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
Request Body schema: application/json
jobToken
required
string
required
VOD web video transcoding (object) or VOD HLS transcoding (object) or VOD audio merge transcoding (object) or Live RTMP to HLS transcoding (object)
runnerToken
required
string

Responses

Request samples

Content type
application/json
{
  • "runnerToken": "string",
  • "jobToken": "string",
  • "payload": {
    }
}

Cancel a job

Authorizations:
OAuth2
path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d

Responses

Delete a job

The endpoint will first cancel the job if needed, and then remove it from the database. Children jobs will also be removed

Authorizations:
OAuth2
path Parameters
jobUUID
required
string <uuid> (UUIDv4) = 36 characters ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...
Example: 9c9de5e8-0a1e-484a-b099-e80766180a6d

Responses

List jobs

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

sort
string
Enum: "updatedAt" "createdAt" "priority" "state" "progress"

Sort runner jobs by criteria

start
integer >= 0

Offset used to paginate results

stateOneOf
Array of integers (RunnerJobState)
Items Enum: 1 2 3 4 5 6 7 8

Responses

Response samples

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

Runners

Register a new runner

API used by PeerTube runners

Request Body schema: application/json
name
required
string
registrationToken
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "registrationToken": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "runnerToken": "string"
}

Unregister a runner

API used by PeerTube runners

Request Body schema: application/json
runnerToken
required
string

Responses

Request samples

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

Delete a runner

Authorizations:
OAuth2
path Parameters
runnerId
required
integer
Request Body schema: application/json
runnerToken
required
string

Responses

Request samples

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

List runners

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

Number of items to return

sort
string
Value: "createdAt"

Sort runners by criteria

start
integer >= 0

Offset used to paginate results

Responses

Response samples

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