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

200

Content type

application/xml

<?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>Fri, 15 Nov 2024 04:10:33 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[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[Custom case for my 3D-printed eyeglasses - ExtremeDullard]]></title>
            <link>https://peertube2.cpy.re/w/9RNan4w7JuoXyDWYiVD8se;threadId=178204</link>
            <guid>https://peertube2.cpy.re/w/9RNan4w7JuoXyDWYiVD8se;threadId=178204</guid>
            <pubDate>Wed, 13 Nov 2024 02:37:33 GMT</pubDate>
            <content:encoded><![CDATA[<p>@colourlesspony@makertube.net Thanks! Yeah the magnets make a nice, secure lock without any complication.</p>
]]></content:encoded>
            <dc:creator>ExtremeDullard</dc:creator>
        </item>
        <item>
            <title><![CDATA[Pepper & Carrot - épisode 3 : L'ingrédient secret - Lazaruscb]]></title>
            <link>https://peertube2.cpy.re/w/6P15SNygm1xNCpXM322JUe;threadId=178205</link>
            <guid>https://peertube2.cpy.re/w/6P15SNygm1xNCpXM322JUe;threadId=178205</guid>
            <pubDate>Tue, 12 Nov 2024 18:04:18 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://peertube.touhoppai.moe/accounts/touhoppai" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>touhoppai</span></a></span> 
Mi sxatis gxin! Pipro estas beleta!</p>]]></content:encoded>
            <dc:creator>Lazaruscb</dc:creator>
        </item>
        <item>
            <title><![CDATA[Custom case for my 3D-printed eyeglasses - colourlesspony]]></title>
            <link>https://peertube2.cpy.re/w/9RNan4w7JuoXyDWYiVD8se;threadId=178204</link>
            <guid>https://peertube2.cpy.re/w/9RNan4w7JuoXyDWYiVD8se;threadId=178204</guid>
            <pubDate>Tue, 12 Nov 2024 13:52:31 GMT</pubDate>
            <content:encoded><![CDATA[<p>Nice! I like the magnets for keeping it closed.</p>
]]></content:encoded>
            <dc:creator>colourlesspony</dc:creator>
        </item>
        <item>
            <title><![CDATA[ADDING AN SDR INTERFACE TO YAESU FT 450D - M33]]></title>
            <link>https://peertube2.cpy.re/w/qkkH3wsSNC4cGT4Sccsaj4;threadId=178200</link>
            <guid>https://peertube2.cpy.re/w/qkkH3wsSNC4cGT4Sccsaj4;threadId=178200</guid>
            <pubDate>Mon, 11 Nov 2024 12:43:34 GMT</pubDate>
            <content:encoded><![CDATA[<p>This video was originally published on YT but I am now exiting the GAFAM's internet services... new home on SDF's peertube instance.</p>
]]></content:encoded>
            <dc:creator>M33</dc:creator>
        </item>
        <item>
            <title><![CDATA[Une petite expérience : un mois avec Tumbleweed et Siduction... - Trit’]]></title>
            <link>https://peertube2.cpy.re/w/wnoGSQ4dRTALiYxQh8cd2D;threadId=178193</link>
            <guid>https://peertube2.cpy.re/w/wnoGSQ4dRTALiYxQh8cd2D;threadId=178193</guid>
            <pubDate>Sun, 10 Nov 2024 19:43:56 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> <span><a href="https://mamot.fr/@fredericbezies" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>fredericbezies</span></a></span> T’es enrhummé ? Ta voix n’est pas la même que d’habitude… Limite, elle sonnerait plus jeune.</p>]]></content:encoded>
            <dc:creator>Trit’</dc:creator>
        </item>
        <item>
            <title><![CDATA[La vérité sur Vilebrequin - Lexi]]></title>
            <link>https://peertube2.cpy.re/w/eFn6fUWxCQHbw6RMHszkhX;threadId=178187</link>
            <guid>https://peertube2.cpy.re/w/eFn6fUWxCQHbw6RMHszkhX;threadId=178187</guid>
            <pubDate>Fri, 08 Nov 2024 21:42:20 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://indymotion.fr/accounts/vald" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>vald</span></a></span> Je que ce serait encore mieux, ce serait d'encourager le grand public a regardé si l'herbe est plus verte ailleurs, notamment sur Peertube. Mais malheureusement Youtube a une telle puissance de frappe, avec des moyens considérables, ....</p>]]></content:encoded>
            <dc:creator>Lexi</dc:creator>
        </item>
        <item>
            <title><![CDATA[2024-10-05-anonradio - tanakian]]></title>
            <link>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</link>
            <guid>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</guid>
            <pubDate>Fri, 08 Nov 2024 12:19:19 GMT</pubDate>
            <content:encoded><![CDATA[<p>@codepoet80@mastodon.sdf.org hey, i assemble gentoo.<br />
all the dockapps i have are from standard gentoo portage tree. except of the one with lots of fishes - that's sherman's aquarium, that dockapp didn't compile already 16 years ago, so i spent 3 days and nights bringing it to the modern times.<br />
<a href="https://github.com/norayr/shermans_aquarium" target="_blank" rel="noopener noreferrer">https://github.com/norayr/shermans_aquarium</a><br />
readme says how to build it. it uses general applet library which i also hod to bring to life:<br />
<a href="https://github.com/norayr/gai" target="_blank" rel="noopener noreferrer">https://github.com/norayr/gai</a></p>
<p>readme says how to build it.</p>
<p>i have no idea if x window manager may work on wayland.<br />
i always use xorg.</p>
]]></content:encoded>
            <dc:creator>tanakian</dc:creator>
        </item>
        <item>
            <title><![CDATA[L'horreur existentielle de l'usine à trombones. - Collectif Raccord]]></title>
            <link>https://peertube2.cpy.re/w/xqi3K534qQss3qLXmmYbEd;threadId=178183</link>
            <guid>https://peertube2.cpy.re/w/xqi3K534qQss3qLXmmYbEd;threadId=178183</guid>
            <pubDate>Thu, 07 Nov 2024 22:49:55 GMT</pubDate>
            <content:encoded><![CDATA[<p>Intéressant. Le site du Cesia est là <a href="https://www.securite-ia.fr/agir" target="_blank" rel="noopener noreferrer">https://www.securite-ia.fr/agir</a></p>
]]></content:encoded>
            <dc:creator>Collectif Raccord</dc:creator>
        </item>
        <item>
            <title><![CDATA[Eternal game engine update: reflections & prb + vertex normal debug view - jns]]></title>
            <link>https://peertube2.cpy.re/w/3QURmvku1vCV8BHLs2bGwL;threadId=178140</link>
            <guid>https://peertube2.cpy.re/w/3QURmvku1vCV8BHLs2bGwL;threadId=178140</guid>
            <pubDate>Tue, 05 Nov 2024 22:22:33 GMT</pubDate>
            <content:encoded><![CDATA[<p>@omniscient@fosstodon.org I am, although it's a bit on and off - i have a bunch of other large projects i'm also working on, but focus will eventually swing back around to this one.</p>
]]></content:encoded>
            <dc:creator>jns</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1103 - aNONradio.net - 2024/11/03 - tanakian]]></title>
            <link>https://peertube2.cpy.re/w/6k3HBhF8HVcLc52vXMxHps;threadId=178172</link>
            <guid>https://peertube2.cpy.re/w/6k3HBhF8HVcLc52vXMxHps;threadId=178172</guid>
            <pubDate>Mon, 04 Nov 2024 11:22:39 GMT</pubDate>
            <content:encoded><![CDATA[<p>was this saved automatically?</p>
]]></content:encoded>
            <dc:creator>tanakian</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - snowdusk]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Mon, 04 Nov 2024 00:18:15 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://social.sdf.org/@rat" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>rat</span></a></span> <span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk@toobnix.org</span></a></span> actually I have no control of snowdusk@toobnix  I think everyone on toobnix just gets that account... some sort of announcement or like RSS??</p>]]></content:encoded>
            <dc:creator>snowdusk</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Mon, 04 Nov 2024 00:16:03 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://mastodon.sdf.org/@snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk@mastodon.sdf.org</span></a></span> <span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk@toobnix.org</span></a></span> hey, one last thing; could you approve my follow of your toobnix? have got the notification bell set but the (un)follow button always says [cancel follow] and so no notifications of your toobnix activity on my mastodon feed. had a similar issue with @stug at one point and we got it fixed. &lt;3 etc</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - snowdusk]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Mon, 04 Nov 2024 00:02:17 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://social.sdf.org/@rat" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>rat</span></a></span> <span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk@toobnix.org</span></a></span> and i saw your response because I'm following you! haha Thank you ratxue!!!</p>]]></content:encoded>
            <dc:creator>snowdusk</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Sun, 03 Nov 2024 23:59:54 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk</span></a></span> it does! <a href="https://social.sdf.org/tags/success" class="mention hashtag" rel="noopener noreferrer" target="_blank">#<span>success</span></a></p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Sun, 03 Nov 2024 23:58:56 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk</span></a></span> wondering if reply to reply here on mastodon feeds back to the toobnix.. 
<a href="https://social.sdf.org/tags/science" class="mention hashtag" rel="noopener noreferrer" target="_blank">#<span>science</span></a></p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - Episode 1102 - aNONradio.net - 2024/11/02 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</link>
            <guid>https://peertube2.cpy.re/w/hjVJb8ZngibhptUsRVnNce;threadId=178166</guid>
            <pubDate>Sun, 03 Nov 2024 23:53:11 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk</span></a></span> last night's show was good too 🙌</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - on aNONradio.net! - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178165</link>
            <guid>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178165</guid>
            <pubDate>Sun, 03 Nov 2024 23:50:00 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/snowdusk" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>snowdusk</span></a></span> another great show 😃</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[2024-10-05-anonradio - codepoet]]></title>
            <link>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</link>
            <guid>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</guid>
            <pubDate>Sun, 03 Nov 2024 21:49:48 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> so cool. I tried it once but it seemed to struggle rendering consistently on a high res screen. Guess I need to try it again. What distro you on? Using X or Wayland? And where’d you find all the cool little dock tiles that are animated while they sit there?</p>]]></content:encoded>
            <dc:creator>codepoet</dc:creator>
        </item>
        <item>
            <title><![CDATA[2024-10-05-anonradio - tanakian]]></title>
            <link>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</link>
            <guid>https://peertube2.cpy.re/w/oyRjXBgrVTURqovu8Y55JK;threadId=178162</guid>
            <pubDate>Sun, 03 Nov 2024 20:38:19 GMT</pubDate>
            <content:encoded><![CDATA[<p>@codepoet80@mastodon.sdf.org hey! that's windowmaker. it is implemented via gnustep which is open source implementation of openstep api.</p>
]]></content:encoded>
            <dc:creator>tanakian</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

200

Content type

application/xml

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

200

Content type

application/xml

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

Payload

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

Payload

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

Payload

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

Payload

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

Payload

Content type

application/json

{"username": "chocobozzz",
"password": "pa$$word",
"email": "user@example.com",
"displayName": "string",
"channel": {"name": "framasoft_videos",
"displayName": "string"
}
}

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

Payload

Content type

application/json

{"username": "chocobozzz",
"password": "pa$$word",
"email": "user@example.com",
"displayName": "string",
"channel": {"name": "framasoft_videos",
"displayName": "string"
},
"registrationReason": "string"
}

Response samples

200

Content type

application/json

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

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

Payload

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"state": {"id": 1,
"label": "string"
},
"registrationReason": "string",
"moderationResponse": "string",
"username": "string",
"email": "user@example.com",
"emailVerified": true,
"accountDisplayName": "string",
"channelHandle": "string",
"channelDisplayName": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"user": {"id": 42
}
}
]
}

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

Shell

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

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

Response samples

200

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

Shell

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

200

Content type

application/json

{"token_type": "Bearer",
"access_token": "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0",
"refresh_token": "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7",
"expires_in": 14399,
"refresh_token_expires_in": 1209600
}

Logout

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

Authorizations:

OAuth2

Responses

Accounts

Accounts encompass remote accounts discovered across the federation, and correspond to the main Actor, along with video channels a user can create, which are also Actors. When a comment is posted, it is done with your Account's Actor.

Get an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

Responses

Response samples

200

Content type

application/json

{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"userId": 42,
"displayName": "string",
"description": "string"
}

List videos of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

	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

JavaScript
Shell
Ruby
Python

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

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

List followers of an account

Authorizations:

OAuth2

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
search	string Plain text search, applied to various parts of the model depending on endpoint
sort	string Value: "createdAt" Sort followers by criteria
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"follower": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"following": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"score": 0,
"state": "pending",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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 playlists of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
playlistType	integer (VideoPlaylistTypeSet) Enum: 1 2 The video playlist type (Regular = `1`, Watch Later = `2`)
search	string Plain text search, applied to various parts of the model depending on endpoint
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

List video channels of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results
withStats	boolean include daily view statistics for the last 30 days and total views (only if authentified as the account user)

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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 the synchronizations of video channels of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"state": {"id": 2,
"label": "PROCESSING"
},
"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"createdAt": "2019-08-24T14:15:22Z",
"lastSyncAt": "2019-08-24T14:15:22Z",
"channel": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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 ratings of an account

Authorizations:

OAuth2

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
rating	string Enum: "like" "dislike" Optionally filter which ratings to retrieve
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

[{"video": {"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
},
"rating": "like"
}
]

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

Payload

Content type

application/json

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

Response samples

200

Content type

application/json

{"user": {"id": 42,
"account": {"id": 42
}
}
}

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

200

Content type

application/json

[{"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"autoPlayNextVideo": true,
"autoPlayNextVideoPlaylist": true,
"autoPlayVideo": true,
"blocked": true,
"blockedReason": "string",
"createdAt": "string",
"email": "user@example.com",
"emailVerified": true,
"id": 42,
"pluginAuth": "string",
"lastLoginDate": "2019-08-24T14:15:22Z",
"noInstanceConfigWarningModal": true,
"noAccountSetupWarningModal": true,
"noWelcomeModal": true,
"nsfwPolicy": "display",
"role": {"id": 2,
"label": "User"
},
"theme": "string",
"username": "chocobozzz",
"videoChannels": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
],
"videoQuota": -1,
"videoQuotaDaily": -1,
"p2pEnabled": true
}
]

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

200

Content type

application/json

Example

User

{"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"autoPlayNextVideo": true,
"autoPlayNextVideoPlaylist": true,
"autoPlayVideo": true,
"blocked": true,
"blockedReason": "string",
"createdAt": "string",
"email": "user@example.com",
"emailVerified": true,
"id": 42,
"pluginAuth": "string",
"lastLoginDate": "2019-08-24T14:15:22Z",
"noInstanceConfigWarningModal": true,
"noAccountSetupWarningModal": true,
"noWelcomeModal": true,
"nsfwPolicy": "display",
"role": {"id": 2,
"label": "User"
},
"theme": "string",
"username": "chocobozzz",
"videoChannels": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
],
"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

Payload

Content type

application/json

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

Resend user verification link

Request Body schema: application/json

email

required

string

User email

Responses

Request samples

Payload

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

Payload

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

Payload

Content type

application/json

{"currentPassword": "string"
}

Response samples

200

Content type

application/json

[{"otpRequest": {"requestToken": "string",
"secret": "string",
"uri": "string"
}
}
]

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

Payload

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

Payload

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

Payload

Content type

application/json

{"withVideoFiles": true
}

Response samples

200

Content type

application/json

{"export": {"id": 0
}
}

List user exports

PeerTube >= 6.1

Authorizations:

OAuth2

path Parameters

userId

required

integer (id) >= 1

Example: 42

User id

Responses

Response samples

200

Content type

application/json

{"id": 0,
"state": {"id": 1,
"label": "string"
},
"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

Payload

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

200

Content type

application/json

{"id": 0,
"state": {"id": 1,
"label": "string"
},
"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

200

Content type

application/json

[{"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"autoPlayNextVideo": true,
"autoPlayNextVideoPlaylist": true,
"autoPlayVideo": true,
"blocked": true,
"blockedReason": "string",
"createdAt": "string",
"email": "user@example.com",
"emailVerified": true,
"id": 42,
"pluginAuth": "string",
"lastLoginDate": "2019-08-24T14:15:22Z",
"noInstanceConfigWarningModal": true,
"noAccountSetupWarningModal": true,
"noWelcomeModal": true,
"nsfwPolicy": "display",
"role": {"id": 2,
"label": "User"
},
"theme": "string",
"username": "chocobozzz",
"videoChannels": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
],
"videoQuota": -1,
"videoQuotaDaily": -1,
"p2pEnabled": true
}
]

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

Payload

Content type

application/json

{"password": "pa$$word",
"currentPassword": "pa$$word",
"email": "user@example.com",
"displayName": "string",
"displayNSFW": "true",
"p2pEnabled": true,
"autoPlayVideo": true,
"autoPlayNextVideo": true,
"autoPlayNextVideoPlaylist": true,
"videosHistoryEnabled": true,
"videoLanguages": ["string"
],
"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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"targetUrl": "https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d",
"magnetUri": "http://example.com",
"torrentName": "string",
"state": {"id": 1,
"label": "Pending"
},
"error": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"video": {"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
}
]
}

Get my user used quota

Authorizations:

OAuth2

Responses

Response samples

200

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

200

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

Update my user avatar

Authorizations:

OAuth2

Request Body schema: multipart/form-data

avatarfile

string <binary>

The file to upload

Responses

Response samples

200

Content type

application/json

{"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"reason": "The video is a spam",
"predefinedReasons": ["spamOrMisleading"
],
"reporterAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"state": {"id": 1,
"label": "string"
},
"moderationComment": "Decided to ban the server since it spams us regularly",
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
]
}

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

Payload

Content type

application/json

{"uri": "008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr"
}

Get if subscriptions exist for my user

Authorizations:

OAuth2

query Parameters

uris

required

Array of strings <uri> [ items <uri > ]

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

Responses

Response samples

200

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

Get subscription of my user

Authorizations:

OAuth2

path Parameters

subscriptionHandle

required

string

Example: my_username | my_username@example.com

The subscription handle

Responses

Response samples

200

Content type

application/json

{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}

Delete subscription of my user

Authorizations:

OAuth2

path Parameters

subscriptionHandle

required

string

Example: my_username | my_username@example.com

The subscription handle

Responses

My Notifications

Notifications following new videos, follows or reports. They allow you to keep track of the interactions and overall important information that concerns you. You MAY set per-notification type delivery preference, to receive the info either by mail, by in-browser notification or both.

List my notifications

Authorizations:

OAuth2

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results
unread	boolean only list unread notifications

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"type": 0,
"read": true,
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?",
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
},
"videoImport": {"id": 42,
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"torrentName": "string",
"magnetUri": "http://example.com",
"targetUri": "http://example.com"
},
"comment": {"id": 42,
"threadId": 0,
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"account": {"id": 42,
"name": "string",
"displayName": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"heldForReview": true
},
"videoAbuse": {"id": 42,
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
}
},
"videoBlacklist": {"id": 42,
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
}
},
"account": {"id": 42,
"name": "string",
"displayName": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"actorFollow": {"id": 42,
"follower": {"id": 42,
"name": "string",
"displayName": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"state": "pending",
"following": {"type": "account",
"name": "string",
"displayName": "string",
"host": "example.com"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

Payload

Content type

application/json

{"ids": [0
]
}

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

Delete history element

Authorizations:

OAuth2

path Parameters

videoId

required

integer >= 1

Example: 42

object id for the video

Responses

Clear video history

Authorizations:

OAuth2

Request Body schema: multipart/form-data

beforeDate

string <date-time>

history before this date will be deleted

Responses

Video

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

List videos of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

	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

JavaScript
Shell
Ruby
Python

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

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

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

200

Content type

application/json

{"files": {"token": "string",
"expires": "2019-08-24T14:15:22Z"
}
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

List available video categories

Responses

Response samples

200

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

200

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

200

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

200

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

200

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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 42,
"name": "chocobozzz",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"userId": 42,
"description": "string"
},
"channel": {"id": 42,
"name": "chocobozzz",
"displayName": "Videos of Framasoft",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"description": "Videos made with <3 by Framasoft",
"support": "Please support our work on https://soutenir.framasoft.org/en/ <3",
"isLocal": true,
"banners": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
},
"userHistory": {"currentTime": 0
},
"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": ["flowers",
"gardening"
],
"commentsEnabled": true,
"commentsPolicy": {"id": 1,
"label": "string"
},
"downloadEnabled": true,
"inputFileUpdatedAt": "2019-08-24T14:15:22Z",
"trackerUrls": ["https://peertube2.cpy.re/tracker/announce",
"wss://peertube2.cpy.re/tracker/socket"
],
"files": [{"id": 42,
"magnetUri": "http://example.com",
"resolution": {"id": 240,
"label": "240p"
},
"size": 0,
"torrentUrl": "string",
"torrentDownloadUrl": "string",
"fileUrl": "string",
"fileDownloadUrl": "string",
"fps": 0,
"width": 0,
"height": 0,
"metadataUrl": "string",
"hasAudio": true,
"hasVideo": true,
"storage": 0
}
],
"streamingPlaylists": [{"id": 42,
"type": 1,
"playlistUrl": "string",
"segmentsSha256Url": "string",
"files": [{"id": 42,
"magnetUri": "http://example.com",
"resolution": {"id": 240,
"label": "240p"
},
"size": 0,
"torrentUrl": "string",
"torrentDownloadUrl": "string",
"fileUrl": "string",
"fileDownloadUrl": "string",
"fps": 0,
"width": 0,
"height": 0,
"metadataUrl": "string",
"hasAudio": true,
"hasVideo": true,
"storage": 0
}
],
"redundancies": [{"baseUrl": "string"
}
]
}
]
}

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

200

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

Payload

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

Payload

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

Shell

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

Payload

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": ["framasoft",
"peertube"
],
"commentsEnabled": true,
"commentsPolicy": 1,
"downloadEnabled": true,
"originallyPublishedAt": "2019-08-24T14:15:22Z",
"scheduleUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"thumbnailfile": "string",
"previewfile": "string",
"videoPasswords": ["string"
],
"filename": "what_is_peertube.mp4"
}

Send chunk for the resumable upload of a video

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

Authorizations:

OAuth2

query Parameters

upload_id

required

string

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

header Parameters

Content-Length required	number Example: 262144 Size of the chunk that the request is sending. Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
Content-Range required	string Example: bytes 0-262143/2469036 Specifies the bytes in the file that the request is uploading. For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first 262144 bytes (256 x 1024) in a 2,469,036 byte file.

Request Body schema: application/octet-stream

string <binary>

Responses

Response samples

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

200

Content type

application/json

{"rtmpUrl": "string",
"rtmpsUrl": "string",
"streamKey": "string",
"saveReplay": true,
"replaySettings": {"privacy": 1
},
"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

Payload

Content type

application/json

{"saveReplay": true,
"replaySettings": {"privacy": 1
},
"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

200

Content type

application/json

{"filename": "string",
"inputFilename": "string",
"fileDownloadUrl": "string",
"resolution": {"id": 240,
"label": "240p"
},
"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

Payload

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

200

Content type

application/json

{"storyboards": [{"storyboardPath": "string",
"totalHeight": 0,
"totalWidth": 0,
"spriteHeight": 0,
"spriteWidth": 0,
"spriteDuration": 0
}
]
}

List videos of a video channel

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

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

Shell

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

Payload

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": ["framasoft",
"peertube"
],
"commentsEnabled": true,
"commentsPolicy": 1,
"downloadEnabled": true,
"originallyPublishedAt": "2019-08-24T14:15:22Z",
"scheduleUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"thumbnailfile": "string",
"previewfile": "string",
"videoPasswords": ["string"
],
"filename": "what_is_peertube.mp4"
}

Send chunk for the resumable upload of a video

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

Authorizations:

OAuth2

query Parameters

upload_id

required

string

Created session id to proceed with. If you didn't send chunks in the last hour, it is not valid anymore and you need to initialize a new upload.

header Parameters

Content-Length required	number Example: 262144 Size of the chunk that the request is sending. Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
Content-Range required	string Example: bytes 0-262143/2469036 Specifies the bytes in the file that the request is uploading. For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first 262144 bytes (256 x 1024) in a 2,469,036 byte file.

Request Body schema: application/octet-stream

string <binary>

Responses

Response samples

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

Payload

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

200

Content type

application/json

{"total": 1,
"data": [{"language": {"id": "en",
"label": "English"
},
"captionPath": "string"
}
]
}

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

Payload

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

200

Content type

application/json

{"chapters": {"title": "string",
"timecode": 0
}
}

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

Payload

Content type

application/json

{"chapters": [{"title": "string",
"timecode": 0
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
]
}

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

Payload

Content type

application/json

{"displayName": null,
"description": null,
"support": null,
"name": "framasoft_videos"
}

Response samples

200

Content type

application/json

{"videoChannel": {"id": 42
}
}

Get a video channel

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

The video channel handle

Responses

Response samples

200

Content type

application/json

{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}

Update a video channel

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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

Payload

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 | my_username@example.com

The video channel handle

Responses

List videos of a video channel

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

List playlists of a channel

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

List followers of a video channel

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"follower": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"following": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"score": 0,
"state": "pending",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Update channel avatar

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

The video channel handle

Request Body schema: multipart/form-data

avatarfile

string <binary>

The file to upload.

Responses

Response samples

200

Content type

application/json

{"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Delete channel avatar

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

The video channel handle

Responses

Update channel banner

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

The video channel handle

Request Body schema: multipart/form-data

bannerfile

string <binary>

The file to upload.

Responses

Response samples

200

Content type

application/json

{"banners": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Delete channel banner

Authorizations:

OAuth2

path Parameters

channelHandle

required

string

Example: my_username | my_username@example.com

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 | my_username@example.com

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

Payload

Content type

application/json

{"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"videoChannelSyncId": 0
}

List video channels of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results
withStats	boolean include daily view statistics for the last 30 days and total views (only if authentified as the account user)

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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 the synchronizations of video channels of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"state": {"id": 2,
"label": "PROCESSING"
},
"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"createdAt": "2019-08-24T14:15:22Z",
"lastSyncAt": "2019-08-24T14:15:22Z",
"channel": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"text": "This video is wonderful!",
"heldForReview": true,
"threadId": 42,
"inReplyToCommentId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"automaticTags": ["string"
]
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"text": "This video is wonderful!",
"threadId": 42,
"inReplyToCommentId": 42,
"videoId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": null,
"isDeleted": false,
"heldForReview": true,
"totalRepliesFromVideoAuthor": 0,
"totalReplies": 0,
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
]
}

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

Payload

Content type

application/json

{"text": "This video is wonderful!"
}

Response samples

200

Content type

application/json

{"comment": {"id": 42,
"url": "string",
"text": "This video is wonderful!",
"threadId": 42,
"inReplyToCommentId": 42,
"videoId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": null,
"isDeleted": false,
"heldForReview": true,
"totalRepliesFromVideoAuthor": 0,
"totalReplies": 0,
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
}

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

200

Content type

application/json

{"comment": {"id": 42,
"url": "string",
"text": "This video is wonderful!",
"threadId": 42,
"inReplyToCommentId": 42,
"videoId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": null,
"isDeleted": false,
"heldForReview": true,
"totalRepliesFromVideoAuthor": 0,
"totalReplies": 0,
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
},
"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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"text": "This video is wonderful!",
"heldForReview": true,
"threadId": 42,
"inReplyToCommentId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"automaticTags": ["string"
]
}
]
}

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

Payload

Content type

application/json

{"text": "This video is wonderful!"
}

Response samples

200

Content type

application/json

{"comment": {"id": 42,
"url": "string",
"text": "This video is wonderful!",
"threadId": 42,
"inReplyToCommentId": 42,
"videoId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"deletedAt": null,
"isDeleted": false,
"heldForReview": true,
"totalRepliesFromVideoAuthor": 0,
"totalReplies": 0,
"account": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
}

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

200

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

Payload

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 | my_username@example.com

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

List available playlist privacy policies

Responses

Response samples

200

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

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

200

Content type

application/json

{"videoPlaylist": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

Get a video playlist

path Parameters

playlistId

required

integer >= 1

Example: 42

Playlist id

Responses

Response samples

200

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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

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

Payload

Content type

application/json

{"videoId": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"startTimestamp": 0,
"stopTimestamp": 0
}

Response samples

200

Content type

application/json

{"videoPlaylistElement": {"id": 2
}
}

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

Payload

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

Live Test Server (live data - latest nightly version)

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Live Test Server (live data - latest RC version)

https://peertube3.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Live Test Server (live data - stable version)

https://peertube.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Request samples

Payload

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

Live Test Server (live data - latest nightly version)

https://peertube2.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Live Test Server (live data - latest RC version)

https://peertube3.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

Live Test Server (live data - stable version)

https://peertube.cpy.re/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}

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

200

Content type

application/json

{"videoId": [{"playlistElementId": 0,
"playlistId": 0,
"startTimestamp": 0,
"stopTimestamp": 0
}
]
}

List playlists of an account

path Parameters

name

required

string

Example: chocobozzz | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
playlistType	integer (VideoPlaylistTypeSet) Enum: 1 2 The video playlist type (Regular = `1`, Watch Later = `2`)
search	string Plain text search, applied to various parts of the model depending on endpoint
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

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

200

Content type

application/json

{"averageWatchTime": 0,
"totalWatchTime": 0,
"viewersPeak": 0,
"viewersPeakDate": "2019-08-24T14:15:22Z",
"countries": [{"isoCode": "string",
"viewers": 0
}
]
}

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

200

Content type

application/json

{"data": [{"second": 0,
"retentionPercent": 0
}
]
}

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

200

Content type

application/json

{"data": [{"date": "string",
"value": 0
}
]
}

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

200

Content type

application/json

[{"id": 42,
"name": "string",
"url": "string",
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"redundancies": {"files": [{"id": 42,
"fileUrl": "string",
"strategy": "manual",
"size": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresOn": "2019-08-24T14:15:22Z"
}
],
"streamingPlaylists": [{"id": 42,
"fileUrl": "string",
"strategy": "manual",
"size": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"expiresOn": "2019-08-24T14:15:22Z"
}
]
}
}
]

Mirror a video

Authorizations:

OAuth2

Request Body schema: application/json

videoId

required

integer >= 1

object id for the video

Responses

Request samples

Payload

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

Payload

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

200

Content type

application/json

{"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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

200

Content type

application/json

{"rtmpUrl": "string",
"rtmpsUrl": "string",
"streamKey": "string",
"saveReplay": true,
"replaySettings": {"privacy": 1
},
"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

Payload

Content type

application/json

{"saveReplay": true,
"replaySettings": {"privacy": 1
},
"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

200

Content type

application/json

{"total": 1,
"data": [{"id": 0,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"error": 1,
"replayVideo": {"id": 0,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}
]
}

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

200

Content type

application/json

{"id": 0,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"error": 1,
"replayVideo": {"id": 0,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"shortUUID": "2y84q2MQUMWPbiEcxNXMgC"
}
}

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 | my_username@example.com

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

Payload

Content type

application/json

{"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"videoChannelSyncId": 0
}

Create a synchronization for a video channel

Authorizations:

OAuth2

Request Body schema: application/json

externalChannelUrl	string
videoChannelId	integer (id) >= 1

Responses

Request samples

Payload

Content type

application/json

{"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"videoChannelId": 42
}

Response samples

200

Content type

application/json

{"videoChannelSync": {"id": 42,
"state": {"id": 2,
"label": "PROCESSING"
},
"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"createdAt": "2019-08-24T14:15:22Z",
"lastSyncAt": "2019-08-24T14:15:22Z",
"channel": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
}
}

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 | chocobozzz@example.org

The username or handle of the account

query Parameters

count	integer [ 1 .. 100 ] Default: 15 Number of items to return
sort	string Example: sort=-createdAt Sort column
start	integer >= 0 Offset used to paginate results

Responses

Response samples

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"state": {"id": 2,
"label": "PROCESSING"
},
"externalChannelUrl": "https://youtube.com/c/UC_myfancychannel",
"createdAt": "2019-08-24T14:15:22Z",
"lastSyncAt": "2019-08-24T14:15:22Z",
"channel": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
}
]
}

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

204

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"password": "string",
"videoId": 42
}
]
}

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

Payload

Content type

application/json

{"passwords": ["string"
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 15,
"label": "Science & Technology"
},
"licence": {"id": 2,
"label": "Attribution - Share Alike"
},
"language": {"id": "en",
"label": "English"
},
"privacy": {"id": 1,
"label": "string"
},
"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": {"id": 1,
"label": "string"
},
"scheduledUpdate": {"privacy": 1,
"updateAt": "2019-08-24T14:15:22Z"
},
"blacklisted": true,
"blacklistedReason": "string",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"channel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"userHistory": {"currentTime": 0
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"ownerAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"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": {"id": 1,
"label": "string"
},
"type": {"id": 1,
"label": "string"
},
"ownerAccount": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
},
"videoChannel": {"id": 42,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"reason": "The video is a spam",
"predefinedReasons": ["spamOrMisleading"
],
"reporterAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"state": {"id": 1,
"label": "string"
},
"moderationComment": "Decided to ban the server since it spams us regularly",
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"reason": "The video is a spam",
"predefinedReasons": ["spamOrMisleading"
],
"reporterAccount": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"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"
},
"state": {"id": 1,
"label": "string"
},
"moderationComment": "Decided to ban the server since it spams us regularly",
"video": {"id": 42,
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"name": "What is PeerTube?"
},
"createdAt": "2019-08-24T14:15:22Z"
}
]
}

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

Payload

Content type

application/json

{"reason": "string",
"predefinedReasons": ["violentOrAbusive"
],
"video": {"id": 42,
"startAt": 0,
"endAt": 0
},
"comment": {"id": 42
},
"account": {"id": 0
}
}

Response samples

200

Content type

application/json

{"abuse": {"id": 42
}
}

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"message": "string",
"byModerator": true,
"createdAt": "2019-08-24T14:15:22Z",
"account": {"id": 0,
"name": "string",
"displayName": "string",
"url": "string",
"host": "example.com",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}
}
]
}

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"videoId": 42,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"name": "string",
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"description": "string",
"duration": 0,
"views": 0,
"likes": 0,
"dislikes": 0,
"nsfw": true
}
]
}

Account Blocks

Get block status of accounts/hosts

query Parameters

accounts	Array of strings Example: accounts=goofy@example.com&accounts=donald@example.com Check if these accounts are blocked
hosts	Array of strings Example: hosts=example.com Check if these hosts are blocked

Responses

Response samples

200

Content type

application/json

{"accounts": {"account1": {"blockedByServer": true,
"blockedByUser": true
},
"account2": {"blockedByServer": true,
"blockedByUser": true
}
},
"hosts": {"host1": {"blockedByServer": true,
"blockedByUser": true
},
"host2": {"blockedByServer": true,
"blockedByUser": true
}
}
}

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

Payload

Content type

application/json

{"accountName": "chocobozzz@example.org"
}

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 Example: accounts=goofy@example.com&accounts=donald@example.com Check if these accounts are blocked
hosts	Array of strings Example: hosts=example.com Check if these hosts are blocked

Responses

Response samples

200

Content type

application/json

{"accounts": {"account1": {"blockedByServer": true,
"blockedByUser": true
},
"account2": {"blockedByServer": true,
"blockedByUser": true
}
},
"hosts": {"host1": {"blockedByServer": true,
"blockedByUser": true
},
"host2": {"blockedByServer": true,
"blockedByUser": true
}
}
}

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

Payload

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

Live Test Server (live data - latest nightly version)

https://peertube2.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Live Test Server (live data - latest RC version)

https://peertube3.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Live Test Server (live data - stable version)

https://peertube.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Response samples

200

Content type

application/json

{"review": ["string"
]
}

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

Live Test Server (live data - latest nightly version)

https://peertube2.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Live Test Server (live data - latest RC version)

https://peertube3.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Live Test Server (live data - stable version)

https://peertube.cpy.re/api/v1/automatic-tags/policies/accounts/{accountName}/comments

Request samples

Payload

Content type

application/json

{"review": ["string"
]
}

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

200

Content type

application/json

{"available": [{"name": "string",
"type": "core"
}
]
}

Get server available auto tags

PeerTube >= 6.2

Authorizations:

OAuth2

Responses

Response samples

200

Content type

application/json

{"available": [{"name": "string",
"type": "core"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"listName": "string",
"words": ["string"
],
"updatedAt": "2021-05-04T08:01:01.502Z",
"createdAt": "2021-05-04T08:01:01.502Z"
}
]
}

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

Payload

Content type

application/json

{"listName": "string",
"words": ["string"
]
}

Response samples

200

Content type

application/json

{"watchedWordsList": {"id": 0
}
}

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

Payload

Content type

application/json

{"listName": "string",
"words": ["string"
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"listName": "string",
"words": ["string"
],
"updatedAt": "2021-05-04T08:01:01.502Z",
"createdAt": "2021-05-04T08:01:01.502Z"
}
]
}

Add server watched words

PeerTube >= 6.2

Authorizations:

OAuth2

Request Body schema: application/json

listName	string
words	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"listName": "string",
"words": ["string"
]
}

Response samples

200

Content type

application/json

{"watchedWordsList": {"id": 0
}
}

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

Payload

Content type

application/json

{"listName": "string",
"words": ["string"
]
}

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

200

Content type

application/json

{"client": {"videos": {"miniature": {"displayAuthorAvatar": false,
"preferAuthorDisplayName": false
},
"resumableUpload": {"maxChunkSize": 0
}
},
"menu": {"login": {"redirectOnSingleExternalAuth": false
}
}
},
"defaults": {"publish": {"downloadEnabled": true,
"commentsPolicy": 1,
"commentsEnabled": true,
"privacy": 1,
"licence": null
},
"p2p": {"webapp": {"enabled": true
},
"embed": {"enabled": true
}
}
},
"webadmin": {"configuration": {"edition": {"allowed": true
}
}
},
"instance": {"name": "PeerTube Nightly",
"shortDescription": "PeerTube instance updated nightly",
"isNSFW": false,
"defaultNSFWPolicy": "do_not_list",
"defaultClientRoute": "/home",
"customizations": {"javascript": "",
"css": ""
},
"avatars": [{"width": 48,
"path": "/lazy-static/avatars/abace30f-69ad-4ff2-a954-dea06c5db6eb.png",
"createdAt": "2024-05-15T09:12:38.749Z",
"updatedAt": "2024-05-15T09:12:38.749Z"
},
{"width": 120,
"path": "/lazy-static/avatars/1163da44-0367-4df9-bf10-a1b0dc0e3fb9.png",
"createdAt": "2024-05-15T09:12:38.719Z",
"updatedAt": "2024-05-15T09:12:38.719Z"
},
{"width": 600,
"path": "/lazy-static/avatars/177f70c4-ddef-4bb6-bc96-b00d5e2a0e05.png",
"createdAt": "2024-05-15T09:12:38.709Z",
"updatedAt": "2024-05-15T09:12:38.709Z"
},
{"width": 1500,
"path": "/lazy-static/avatars/82936e50-9560-42e7-9e4b-d96309f5c9c9.png",
"createdAt": "2024-05-15T09:12:38.684Z",
"updatedAt": "2024-05-15T09:12:38.684Z"
}
],
"banners": [{"width": 600,
"path": "/lazy-static/banners/d853452c-f020-4c6f-a4ea-9fc582d68ff2.jpg",
"createdAt": "2024-04-16T14:09:02.665Z",
"updatedAt": "2024-04-16T14:09:02.665Z"
},
{"width": 1920,
"path": "/lazy-static/banners/772ff0ae-6cb5-4d1c-b89b-ace85eece196.jpg",
"createdAt": "2024-04-16T14:09:02.615Z",
"updatedAt": "2024-04-16T14:09:02.615Z"
}
]
},
"search": {"remoteUri": {"users": true,
"anonymous": false
},
"searchIndex": {"enabled": true,
"url": "https://search.joinpeertube.org/",
"disableLocalSearch": false,
"isDefaultSearch": true
}
},
"plugin": {"registered": [{"npmName": "peertube-plugin-logo-framasoft",
"name": "logo-framasoft",
"version": "0.0.1",
"description": "Framasoft logo on PeerTube.",
"clientScripts": {"client/common-client-plugin.js": {"script": "client/common-client-plugin.js",
"scopes": ["common"
]
}
}
},
{"npmName": "peertube-plugin-auto-mute",
"name": "auto-mute",
"version": "0.0.6",
"description": "Auto mute plugin for PeerTube",
"clientScripts": { }
},
{"npmName": "peertube-plugin-matomo",
"name": "matomo",
"version": "1.0.2",
"description": "Matomo plugin that tracks page views on a PeerTube instance.",
"clientScripts": {"dist/common-client-plugin.js": {"script": "dist/common-client-plugin.js",
"scopes": ["common"
]
},
"dist/embed-client-plugin.js": {"script": "dist/embed-client-plugin.js",
"scopes": ["embed"
]
}
}
},
{"npmName": "peertube-plugin-auth-ldap",
"name": "auth-ldap",
"version": "0.0.14",
"description": "Add LDAP support to login form in PeerTube.",
"clientScripts": { }
},
{"npmName": "peertube-plugin-akismet",
"name": "akismet",
"version": "0.1.2",
"description": "Reject local comments, remote comments and registrations based on Akismet service",
"clientScripts": {"dist/common-client-plugin.js": {"script": "dist/common-client-plugin.js",
"scopes": ["common"
]
}
}
},
{"npmName": "peertube-plugin-transcoding-custom-quality",
"name": "transcoding-custom-quality",
"version": "0.2.0",
"description": "Set a custom quality for transcoding",
"clientScripts": { }
},
{"npmName": "peertube-plugin-beeldengeluid-event-metadata-importer",
"name": "beeldengeluid-event-metadata-importer",
"version": "0.0.3",
"description": "PeerTube plugin Beeld en Geluid event importer",
"clientScripts": {"dist/video-edit-client-plugin.js": {"script": "dist/video-edit-client-plugin.js",
"scopes": ["video-edit"
]
},
"dist/video-watch-client-plugin.js": {"script": "dist/video-watch-client-plugin.js",
"scopes": ["video-watch"
]
}
}
},
{"npmName": "peertube-plugin-livechat",
"name": "livechat",
"version": "11.0.1",
"description": "PeerTube plugin livechat: create chat rooms for your Peertube lives! Comes with many features: federation, moderation tools, chat bot, chat persistence, OBS integration, ...",
"clientScripts": {"dist/client/common-client-plugin.js": {"script": "dist/client/common-client-plugin.js",
"scopes": ["common"
]
},
"dist/client/admin-plugin-client-plugin.js": {"script": "dist/client/admin-plugin-client-plugin.js",
"scopes": ["admin-plugin"
]
}
}
}
],
"registeredExternalAuths": [ ],
"registeredIdAndPassAuths": [{"npmName": "peertube-plugin-auth-ldap",
"name": "auth-ldap",
"version": "0.0.14",
"authName": "ldap",
"weight": 100
}
]
},
"theme": {"registered": [{"npmName": "peertube-theme-dark",
"name": "dark",
"version": "2.6.1",
"description": "PeerTube dark theme",
"css": ["assets/style.css"
],
"clientScripts": { }
}
],
"default": "default"
},
"email": {"enabled": true
},
"contactForm": {"enabled": true
},
"serverVersion": "6.3.3-nightly-2024-11-14",
"serverCommit": "",
"transcoding": {"remoteRunners": {"enabled": false
},
"hls": {"enabled": true
},
"web_videos": {"enabled": false
},
"enabledResolutions": [0,
240,
480
],
"profile": "custom-quality",
"availableProfiles": ["default",
"custom-quality"
]
},
"live": {"enabled": true,
"allowReplay": true,
"latencySetting": {"enabled": true
},
"maxDuration": -1,
"maxInstanceLives": 20,
"maxUserLives": 3,
"transcoding": {"enabled": true,
"remoteRunners": {"enabled": true
},
"enabledResolutions": [ ],
"profile": "default",
"availableProfiles": ["default",
"custom-quality"
]
},
"rtmp": {"port": 1935
}
},
"videoStudio": {"enabled": true,
"remoteRunners": {"enabled": false
}
},
"videoFile": {"update": {"enabled": true
}
},
"videoTranscription": {"enabled": true,
"remoteRunners": {"enabled": true
}
},
"import": {"videos": {"http": {"enabled": true
},
"torrent": {"enabled": true
}
},
"videoChannelSynchronization": {"enabled": true
},
"users": {"enabled": true
}
},
"export": {"users": {"enabled": true,
"exportExpiration": 172800000,
"maxUserVideoQuota": 10737418240
}
},
"autoBlacklist": {"videos": {"ofUsers": {"enabled": true
}
}
},
"avatar": {"file": {"size": {"max": 4194304
},
"extensions": [".png",
".jpeg",
".jpg",
".gif",
".webp"
]
}
},
"banner": {"file": {"size": {"max": 4194304
},
"extensions": [".png",
".jpeg",
".jpg",
".gif",
".webp"
]
}
},
"video": {"image": {"extensions": [".png",
".jpg",
".jpeg",
".webp"
],
"size": {"max": 4194304
}
},
"file": {"extensions": [".webm",
".ogv",
".ogg",
".mp4",
".mkv",
".mov",
".qt",
".mqv",
".m4v",
".flv",
".f4v",
".wmv",
".avi",
".3gp",
".3gpp",
".3g2",
".3gpp2",
".nut",
".mts",
".m2ts",
".mpv",
".m2v",
".m1v",
".mpg",
".mpe",
".mpeg",
".vob",
".mxf",
".mp3",
".wma",
".wav",
".flac",
".aac",
".m4a",
".ac3"
]
}
},
"videoCaption": {"file": {"size": {"max": 20971520
},
"extensions": [".vtt",
".srt"
]
}
},
"user": {"videoQuota": 104857600,
"videoQuotaDaily": 104857600
},
"videoChannels": {"maxPerUser": 20
},
"trending": {"videos": {"intervalDays": 7,
"algorithms": {"enabled": ["best",
"hot",
"most-viewed",
"most-liked"
],
"default": "most-viewed"
}
}
},
"tracker": {"enabled": true
},
"followings": {"instance": {"autoFollowIndex": {"indexUrl": "https://instances.joinpeertube.org"
}
}
},
"broadcastMessage": {"enabled": false,
"message": "We are currently experiencing technical problems on this instance. We are trying to fix it as soon as possible. Thank you for your understanding.",
"level": "error",
"dismissable": false
},
"homepage": {"enabled": true
},
"openTelemetry": {"metrics": {"enabled": true,
"playbackStatsInterval": 15000
}
},
"views": {"videos": {"watchingInterval": {"anonymous": 5000,
"users": 5000
}
}
},
"storyboards": {"enabled": true
},
"webrtc": {"stunServers": ["stun:stunserver2024.stunprotocol.org",
"stun:stun.framasoft.org"
]
},
"signup": {"allowed": false,
"allowedForCurrentIP": true,
"minimumAge": 16,
"requiresApproval": true,
"requiresEmailVerification": true
}
}

Get instance "About" information

Responses

Response samples

200

Content type

application/json

{"instance": {"name": "PeerTube Nightly",
"shortDescription": "PeerTube instance updated nightly",
"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.",
"terms": "No terms for now. Being a closed test instance, no real terms of use beyond fair use are to be expected.",
"codeOfConduct": "",
"hardwareInformation": "",
"creationReason": "",
"moderationInformation": "",
"administrator": "",
"maintenanceLifetime": "",
"businessModel": "",
"languages": ["en"
],
"categories": [16
],
"banners": [{"width": 600,
"path": "/lazy-static/banners/d853452c-f020-4c6f-a4ea-9fc582d68ff2.jpg",
"createdAt": "2024-04-16T14:09:02.665Z",
"updatedAt": "2024-04-16T14:09:02.665Z"
},
{"width": 1920,
"path": "/lazy-static/banners/772ff0ae-6cb5-4d1c-b89b-ace85eece196.jpg",
"createdAt": "2024-04-16T14:09:02.615Z",
"updatedAt": "2024-04-16T14:09:02.615Z"
}
],
"avatars": [{"width": 48,
"path": "/lazy-static/avatars/abace30f-69ad-4ff2-a954-dea06c5db6eb.png",
"createdAt": "2024-05-15T09:12:38.749Z",
"updatedAt": "2024-05-15T09:12:38.749Z"
},
{"width": 120,
"path": "/lazy-static/avatars/1163da44-0367-4df9-bf10-a1b0dc0e3fb9.png",
"createdAt": "2024-05-15T09:12:38.719Z",
"updatedAt": "2024-05-15T09:12:38.719Z"
},
{"width": 600,
"path": "/lazy-static/avatars/177f70c4-ddef-4bb6-bc96-b00d5e2a0e05.png",
"createdAt": "2024-05-15T09:12:38.709Z",
"updatedAt": "2024-05-15T09:12:38.709Z"
},
{"width": 1500,
"path": "/lazy-static/avatars/82936e50-9560-42e7-9e4b-d96309f5c9c9.png",
"createdAt": "2024-05-15T09:12:38.684Z",
"updatedAt": "2024-05-15T09:12:38.684Z"
}
]
}
}

Get instance runtime configuration

Authorizations:

OAuth2

Responses

Response samples

200

Content type

application/json

{"instance": {"name": "string",
"shortDescription": "string",
"description": "string",
"terms": "string",
"defaultClientRoute": "string",
"isNSFW": true,
"defaultNSFWPolicy": "string",
"customizations": {"javascript": "string",
"css": "string"
}
},
"theme": {"default": "string"
},
"services": {"twitter": {"username": "string"
}
},
"cache": {"previews": {"size": 0
},
"captions": {"size": 0
}
},
"signup": {"enabled": true,
"limit": 0,
"requiresEmailVerification": true
},
"admin": {"email": "user@example.com"
},
"contactForm": {"enabled": true
},
"user": {"videoQuota": 16810141515,
"videoQuotaDaily": 1681014151
},
"transcoding": {"enabled": true,
"originalFile": {"keep": true
},
"allowAdditionalExtensions": true,
"allowAudioFiles": true,
"threads": 0,
"concurrency": 0,
"profile": "default",
"resolutions": {"0p": true,
"144p": true,
"240p": true,
"360p": true,
"480p": true,
"720p": true,
"1080p": true,
"1440p": true,
"2160p": true
},
"web_videos": {"enabled": true
},
"hls": {"enabled": true,
"splitAudioAndVideo": true
}
},
"import": {"videos": {"http": {"enabled": true
},
"torrent": {"enabled": true
}
},
"video_channel_synchronization": {"enabled": true
}
},
"autoBlacklist": {"videos": {"ofUsers": {"enabled": true
}
}
},
"followers": {"instance": {"enabled": true,
"manualApproval": true
}
}
}

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

200

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"follower": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"following": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"score": 0,
"state": "pending",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"follower": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"following": {"id": 42,
"url": "string",
"name": "chocobozzz",
"avatars": [{"path": "string",
"width": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"host": "example.com",
"hostRedundancyAllowed": true,
"followingCount": 0,
"followersCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"score": 0,
"state": "pending",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

Payload

Content type

application/json

{"hosts": ["example.com"
],
"handles": ["string"
]
}

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"name": "peertube-plugin-auth-ldap",
"type": 1,
"latestVersion": "0.0.3",
"version": "0.0.1",
"enabled": true,
"uninstalled": true,
"peertubeEngine": "2.2.0",
"description": "string",
"homepage": "https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap",
"settings": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"name": "peertube-plugin-auth-ldap",
"type": 1,
"latestVersion": "0.0.3",
"version": "0.0.1",
"enabled": true,
"uninstalled": true,
"peertubeEngine": "2.2.0",
"description": "string",
"homepage": "https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap",
"settings": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]
}

Install a plugin

Authorizations:

OAuth2

Request Body schema: application/json

One of

npmName

required

string

Responses

Request samples

Payload

Content type

application/json

{"path": "string"
}

Update a plugin

Authorizations:

OAuth2

Request Body schema: application/json

One of

npmName

required

string

Responses

Request samples

Payload

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

Payload

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

200

Content type

application/json

{"name": "peertube-plugin-auth-ldap",
"type": 1,
"latestVersion": "0.0.3",
"version": "0.0.1",
"enabled": true,
"uninstalled": true,
"peertubeEngine": "2.2.0",
"description": "string",
"homepage": "https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap",
"settings": { },
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

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

Payload

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

200

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

200

Content type

application/json

{ }

Stats

Statistics

Get instance stats

Get instance public statistics. This endpoint is cached.

Responses

Response samples

200

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": [{"strategy": "string",
"totalSize": 0,
"totalUsed": 0,
"totalVideoFiles": 0,
"totalVideos": 0
}
],
"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

Payload

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

Payload

Content type

application/json

{"message": "string",
"url": "string",
"level": "error",
"stackTrace": "string",
"userAgent": "string",
"meta": "string"
}

Get instance logs

Authorizations:

OAuth2

Responses

Response samples

200

Content type

application/json

["string"
]

Get instance audit logs

Authorizations:

OAuth2

Responses

Response samples

200

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 42,
"state": "active",
"type": "activitypub-http-unicast",
"data": { },
"error": { },
"createdAt": "2019-08-24T14:15:22Z",
"finishedOn": "2019-08-24T14:15:22Z",
"processedOn": "2019-08-24T14:15:22Z"
}
]
}

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 0,
"registrationToken": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"registeredRunnersCount": 0
}
]
}

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

Payload

Content type

application/json

{"runnerToken": "string",
"jobTypes": ["string"
]
}

Response samples

200

Content type

application/json

{"availableJobs": [{"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"type": "vod-web-video-transcoding",
"payload": {"input": {"videoFileUrl": "string"
},
"output": {"resolution": 0,
"fps": 0
}
}
}
]
}

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

Payload

Content type

application/json

{"runnerToken": "string"
}

Response samples

200

Content type

application/json

{"job": {"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"type": "vod-web-video-transcoding",
"state": {"id": 1,
"label": "Processing"
},
"payload": {"input": {"videoFileUrl": "string"
},
"output": {"resolution": 0,
"fps": 0
}
},
"failures": 0,
"error": "string",
"progress": 0,
"priority": 0,
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"startedAt": "2019-08-24T14:15:22Z",
"finishedAt": "2019-08-24T14:15:22Z",
"parent": {"type": "vod-web-video-transcoding",
"state": {"id": 1,
"label": "Processing"
},
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d"
},
"runner": {"id": 0,
"name": "string",
"description": "string"
},
"jobToken": "string"
}
}

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

Payload

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

Payload

Content type

application/json

{"runnerToken": "string",
"jobToken": "string",
"progress": 0,
"payload": {"type": "add-chunk",
"masterPlaylistFile": "string",
"resolutionPlaylistFile": "string",
"resolutionPlaylistFilename": "string",
"videoChunkFile": "string",
"videoChunkFilename": "string"
}
}

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

Payload

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

Payload

Content type

application/json

{"runnerToken": "string",
"jobToken": "string",
"payload": {"videoFile": "string"
}
}

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

200

Content type

application/json

{"total": 1,
"data": [{"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d",
"type": "vod-web-video-transcoding",
"state": {"id": 1,
"label": "Processing"
},
"payload": {"input": {"videoFileUrl": "string"
},
"output": {"resolution": 0,
"fps": 0
}
},
"failures": 0,
"error": "string",
"progress": 0,
"priority": 0,
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"startedAt": "2019-08-24T14:15:22Z",
"finishedAt": "2019-08-24T14:15:22Z",
"parent": {"type": "vod-web-video-transcoding",
"state": {"id": 1,
"label": "Processing"
},
"uuid": "9c9de5e8-0a1e-484a-b099-e80766180a6d"
},
"runner": {"id": 0,
"name": "string",
"description": "string"
},
"privatePayload": { }
}
]
}

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

Payload

Content type

application/json

{"registrationToken": "string",
"name": "string",
"description": "string"
}

Response samples

200

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

Payload

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

Payload

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

200

Content type

application/json

{"total": 1,
"data": [{"id": 0,
"name": "string",
"description": "string",
"ip": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"lastContact": "2019-08-24T14:15:22Z"
}
]
}

PeerTube (6.3.0)

Authentication

Roles

Errors

Validation errors

Deprecated error fields

Rate limits

CORS

Static Video Files

Get public Web Video file

path Parameters

Responses

Get private Web Video file

Authorizations:

path Parameters

query Parameters

Responses

Get public HLS video file

Authorizations:

path Parameters

Responses

Get private HLS video file

Authorizations:

path Parameters

query Parameters

Responses

Video Download

Download video file

path Parameters

query Parameters

Responses

Video Feeds

Comments on videos feeds

path Parameters

query Parameters

Responses

Response samples

Common videos feeds

path Parameters

query Parameters

Responses

Response samples

Videos of subscriptions feeds

path Parameters

query Parameters

Responses

Response samples

Videos podcast feed

query Parameters

Responses

Register

Resend user verification link

Request Body schema: application/json

Responses

Request samples

Resend verification link to registration email

Request Body schema: application/json

Responses

Request samples

Verify a user

path Parameters

Request Body schema: application/json

Responses

Request samples

Verify a registration email

path Parameters

Request Body schema: application/json

Responses

Request samples

Register a user

Request Body schema: application/jsonrequired

Responses

Request samples

Request registration

Request Body schema: application/json

Responses

Request samples

Response samples

Accept registration

Authorizations:

Request Body schema: application/json
required