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, 06 Dec 2024 04:10:38 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[The Boogaloo Mix #02 - isAAAc]]></title>
            <link>https://peertube2.cpy.re/w/gZxHbZpyQuf24hBT1mabnK;threadId=178285</link>
            <guid>https://peertube2.cpy.re/w/gZxHbZpyQuf24hBT1mabnK;threadId=178285</guid>
            <pubDate>Thu, 05 Dec 2024 11:59:58 GMT</pubDate>
            <content:encoded><![CDATA[<p>cool ❤️</p>
]]></content:encoded>
            <dc:creator>isAAAc</dc:creator>
        </item>
        <item>
            <title><![CDATA[Le rêve d'Elon Musk détruit par deux ingénieurs - Jancovici, Bihouix - tif_inégalitéS.capitalisme.TTdroites.écocide.5g.pub.nuc.gafam-CRIMES]]></title>
            <link>https://peertube2.cpy.re/w/uy1exfFUffDuR59SBtvBzq;threadId=178284</link>
            <guid>https://peertube2.cpy.re/w/uy1exfFUffDuR59SBtvBzq;threadId=178284</guid>
            <pubDate>Wed, 04 Dec 2024 20:22:08 GMT</pubDate>
            <content:encoded><![CDATA[<p>À PRÉCISER QUE C'EST SEULEMENT UN EXTRAIT !</p>
]]></content:encoded>
            <dc:creator>tif_inégalitéS.capitalisme.TTdroites.écocide.5g.pub.nuc.gafam-CRIMES</dc:creator>
        </item>
        <item>
            <title><![CDATA[Le rêve d'Elon Musk détruit par deux ingénieurs - Jancovici, Bihouix - tif_inégalitéS.capitalisme.TTdroites.écocide.5g.pub.nuc.gafam-CRIMES]]></title>
            <link>https://peertube2.cpy.re/w/uy1exfFUffDuR59SBtvBzq;threadId=178283</link>
            <guid>https://peertube2.cpy.re/w/uy1exfFUffDuR59SBtvBzq;threadId=178283</guid>
            <pubDate>Wed, 04 Dec 2024 20:21:20 GMT</pubDate>
            <content:encoded><![CDATA[<p>À PRÉCISER QUE C'EST UN EXTRAIT !</p>
]]></content:encoded>
            <dc:creator>tif_inégalitéS.capitalisme.TTdroites.écocide.5g.pub.nuc.gafam-CRIMES</dc:creator>
        </item>
        <item>
            <title><![CDATA[BREAKOUT - No Time To Rest (Official Music Video) - isAAAc]]></title>
            <link>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</link>
            <guid>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</guid>
            <pubDate>Wed, 04 Dec 2024 14:44:26 GMT</pubDate>
            <content:encoded><![CDATA[<p>@johnlivingston@www.yiny.org ouep j'irai bine les voir s'ils passent dans le coin de rennes, ou à paname quand j'y suis</p>
]]></content:encoded>
            <dc:creator>isAAAc</dc:creator>
        </item>
        <item>
            <title><![CDATA[Ergo‐L - la relève de Bépo ? - Nuclear Squid - JdLL2024 - Julien Blondeau]]></title>
            <link>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</link>
            <guid>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</guid>
            <pubDate>Wed, 04 Dec 2024 13:00:39 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://piaille.fr/@NuclearSquid" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>NuclearSquid</span></a></span> <span><a href="https://videos-libr.es/accounts/orga_jdll" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>orga_jdll</span></a></span> 
Top, merci beaucoup !</p>]]></content:encoded>
            <dc:creator>Julien Blondeau</dc:creator>
        </item>
        <item>
            <title><![CDATA[Ergo‐L - la relève de Bépo ? - Nuclear Squid - JdLL2024 - NuclearSquid]]></title>
            <link>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</link>
            <guid>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</guid>
            <pubDate>Wed, 04 Dec 2024 12:26:56 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://framapiaf.org/@captainju" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>captainju</span></a></span> <span><a href="https://videos-libr.es/accounts/orga_jdll" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>orga_jdll</span></a></span> 
Oops ! C’est ma faute ça, les slides étaient hostés à l’arrache sur le site d’Ergo‑L, mais c’était complètement con et mal foutu, donc j’ai migré ça sur un blog perso (bon le site est dégueulasse mais ça c’est pour plus tard lol). J’ai juste pas pensé à envoyer le nouveau lien là où il faut, désolé</p><p><a href="https://nuclear-squid.github.io/slides/jdll2024/#1" target="_blank" rel="noopener noreferrer"><span>https://</span><span>nuclear-squid.github.io/slides</span><span>/jdll2024/#1</span></a></p>]]></content:encoded>
            <dc:creator>NuclearSquid</dc:creator>
        </item>
        <item>
            <title><![CDATA[BREAKOUT - No Time To Rest (Official Music Video) - John Livingston]]></title>
            <link>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</link>
            <guid>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</guid>
            <pubDate>Wed, 04 Dec 2024 11:33:19 GMT</pubDate>
            <content:encoded><![CDATA[<p>@isaaac@media.krashboyz.org ouais, ça envoie du lourd comme groupe. Ils sont impressionnant sur scène !  Super carré !</p>
]]></content:encoded>
            <dc:creator>John Livingston</dc:creator>
        </item>
        <item>
            <title><![CDATA[BREAKOUT - No Time To Rest (Official Music Video) - isAAAc]]></title>
            <link>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</link>
            <guid>https://peertube2.cpy.re/w/aXVoDMSmBArcEoB3XGhc73;threadId=178276</guid>
            <pubDate>Wed, 04 Dec 2024 11:31:03 GMT</pubDate>
            <content:encoded><![CDATA[<p>ouch c'est très bon ça ! ❤️</p>
]]></content:encoded>
            <dc:creator>isAAAc</dc:creator>
        </item>
        <item>
            <title><![CDATA[BUNNY ENCOUNTER! - qrstuv]]></title>
            <link>https://peertube2.cpy.re/w/5jBegFpNbffA1nhmp32kqR;threadId=178272</link>
            <guid>https://peertube2.cpy.re/w/5jBegFpNbffA1nhmp32kqR;threadId=178272</guid>
            <pubDate>Tue, 03 Dec 2024 13:50:07 GMT</pubDate>
            <content:encoded><![CDATA[<p>@pizzapal Remember to like, favourite, and subscribe! And to open the modal to support the video uploader!</p>
]]></content:encoded>
            <dc:creator>qrstuv</dc:creator>
        </item>
        <item>
            <title><![CDATA[BUNNY ENCOUNTER! - pizzapal]]></title>
            <link>https://peertube2.cpy.re/w/5jBegFpNbffA1nhmp32kqR;threadId=178272</link>
            <guid>https://peertube2.cpy.re/w/5jBegFpNbffA1nhmp32kqR;threadId=178272</guid>
            <pubDate>Tue, 03 Dec 2024 04:58:49 GMT</pubDate>
            <content:encoded><![CDATA[<p>im lovin this bun!!!!!!</p>
]]></content:encoded>
            <dc:creator>pizzapal</dc:creator>
        </item>
        <item>
            <title><![CDATA[Metamorphosis Act 1 - gef]]></title>
            <link>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</link>
            <guid>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</guid>
            <pubDate>Mon, 02 Dec 2024 23:48:22 GMT</pubDate>
            <content:encoded><![CDATA[<p>@rat@social.sdf.org Thanks 😄</p>
]]></content:encoded>
            <dc:creator>gef</dc:creator>
        </item>
        <item>
            <title><![CDATA[Ergo‐L - la relève de Bépo ? - Nuclear Squid - JdLL2024 - Julien Blondeau]]></title>
            <link>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</link>
            <guid>https://peertube2.cpy.re/w/sosqtsJ7bBYW7PoKcqnPNW;threadId=178270</guid>
            <pubDate>Mon, 02 Dec 2024 06:55:41 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://videos-libr.es/accounts/orga_jdll" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>orga_jdll</span></a></span> merci pour la vidéo, merci pour la présentation.
Cependant le lien dans la description vers les slides ne fonctionne pas
ping <span><a href="https://piaille.fr/@NuclearSquid" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>NuclearSquid</span></a></span></p>]]></content:encoded>
            <dc:creator>Julien Blondeau</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - on aNONradio.net! - snowdusk]]></title>
            <link>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178266</link>
            <guid>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178266</guid>
            <pubDate>Mon, 02 Dec 2024 00:09:52 GMT</pubDate>
            <content:encoded><![CDATA[<p>@rat@social.sdf.org great to be back! thank you!</p>
]]></content:encoded>
            <dc:creator>snowdusk</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - on aNONradio.net! - snowdusk]]></title>
            <link>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178267</link>
            <guid>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178267</guid>
            <pubDate>Mon, 02 Dec 2024 00:09:38 GMT</pubDate>
            <content:encoded><![CDATA[<p>@peron thank you thank you!</p>
]]></content:encoded>
            <dc:creator>snowdusk</dc:creator>
        </item>
        <item>
            <title><![CDATA[Intergalactic Wasabi Mix - Live Mix by snowdusk - on aNONradio.net! - peron]]></title>
            <link>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178267</link>
            <guid>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178267</guid>
            <pubDate>Sun, 01 Dec 2024 23:50:12 GMT</pubDate>
            <content:encoded><![CDATA[<p>Great LIVE show!</p>
]]></content:encoded>
            <dc:creator>peron</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=178266</link>
            <guid>https://peertube2.cpy.re/w/37RMa2Mw9fj7BfAVhypVqa;threadId=178266</guid>
            <pubDate>Sun, 01 Dec 2024 23:08:40 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> welcome back!</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[Fedora 41 sur 6 mois, le bilan au bout du premier mois - Malck0]]></title>
            <link>https://peertube2.cpy.re/w/xyUKYZFcwWKfZcFy6BJAxT;threadId=178274</link>
            <guid>https://peertube2.cpy.re/w/xyUKYZFcwWKfZcFy6BJAxT;threadId=178274</guid>
            <pubDate>Sun, 01 Dec 2024 20:51:16 GMT</pubDate>
            <content:encoded><![CDATA[<p>Salut Tonton , en lieu et place de "htop" , essaie " btop" , tu m'en diras des nouvelles, si tu ne connais pas biensûr 😉 Tchuuusss</p>
]]></content:encoded>
            <dc:creator>Malck0</dc:creator>
        </item>
        <item>
            <title><![CDATA[Mastodon's most followed accounts - Pro Acetone Drinker]]></title>
            <link>https://peertube2.cpy.re/w/13ddHm9Prrw1UD1xmx9thw;threadId=176888</link>
            <guid>https://peertube2.cpy.re/w/13ddHm9Prrw1UD1xmx9thw;threadId=176888</guid>
            <pubDate>Fri, 29 Nov 2024 00:06:27 GMT</pubDate>
            <content:encoded><![CDATA[<p>@averagedude@video.ploud.fr  ok i know it's been like a year since you made this comment, but one thing i haven't been able to do on peertube (at least on this instance) is save playlists.</p>
]]></content:encoded>
            <dc:creator>Pro Acetone Drinker</dc:creator>
        </item>
        <item>
            <title><![CDATA[Metamorphosis Act 1 - 𝚛𝚊𝚝]]></title>
            <link>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</link>
            <guid>https://peertube2.cpy.re/w/w17WmDykgBPgG6ZYjcmHf5;threadId=178254</guid>
            <pubDate>Thu, 28 Nov 2024 22:06:33 GMT</pubDate>
            <content:encoded><![CDATA[<p><span><a href="https://toobnix.org/accounts/gef" class="u-url mention" target="_blank" rel="noopener noreferrer">@<span>gef</span></a></span> congratulations</p>]]></content:encoded>
            <dc:creator>𝚛𝚊𝚝</dc:creator>
        </item>
        <item>
            <title><![CDATA[La dénazification, mission impossible - isAAAc]]></title>
            <link>https://peertube2.cpy.re/w/fXAnnkiR4iWr29gcvaJAwS;threadId=178251</link>
            <guid>https://peertube2.cpy.re/w/fXAnnkiR4iWr29gcvaJAwS;threadId=178251</guid>
            <pubDate>Thu, 28 Nov 2024 10:19:53 GMT</pubDate>
            <content:encoded><![CDATA[<p>Merci pour le partage ❤️</p>
]]></content:encoded>
            <dc:creator>isAAAc</dc:creator>
        </item>
    </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 o

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