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:
Python
Go
Kotlin
See the REST API quick start for a few
examples of using the PeerTube API.
Authentication
When you sign up for an account on a PeerTube instance, you are given the possibility
to generate sessions on it, and authenticate there using an access token. Only __one
access token can currently be used at a time__.
Roles
Accounts are given permissions based on their role. There are three roles on
PeerTube: Administrator, Moderator, and User. See the roles guide 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.
Where id is the name of the field concerned by the error, within the route definition.
invalid-params..location can be either 'params', 'body', 'header', 'query' or 'cookies', and
invalid-params..value reports the value that didn't pass validation whose invalid-params..msg
is about.
Deprecated error fields
Some fields could be included with previous versions. They are still included but their use is deprecated:
error: superseded by detail
code: superseded by type (which is now an URI)
Rate limits
We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
| Endpoint (prefix: /api/v1) | Calls | Time frame |
|------------------------------|---------------|--------------|
| /* | 50 | 10 seconds |
| POST /users/token | 15 | 5 minutes |
| POST /users/register | 2 * | 5 minutes |
| POST /users/ask-send-verify-email | 3 | 5 minutes |
Depending on the endpoint, * failed requests are not taken into account. A service
limit is announced by a 429 Too Many Requests status code.
You can get details about the current state of your rate limit by reading the
following headers:
| Header | Description |
|-------------------------|------------------------------------------------------------|
| X-RateLimit-Limit | Number of max requests allowed in the current time period |
| X-RateLimit-Remaining | Number of remaining requests in the current time period |
| X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp |
| Retry-After | Seconds to delay after the first 429 is received |
CORS
This API features Cross-Origin Resource Sharing (CORS),
allowing cross-domain communication from the browser for some routes:
| Endpoint |
|------------------------- ---|
| /api/* |
| /download/* |
| /lazy-static/* |
| /live/segments-sha256/* |
| /.well-known/webfinger |
In addition, all routes serving ActivityPub are CORS-enabled for all origins.