PeerTube API

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.

Authentication

When you sign up for an account on a PeerTube instance, you are given the possibility to generate sessions on it, and authenticate there using an access token. Only one access token can currently be used at a time.

Roles

Accounts are given permissions based on their role. There are three roles on PeerTube: Administrator, Moderator, and User. See the roles guide for a detail of their permissions.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call, completed by a RFC7807-compliant response body.

HTTP 1.1 404 Not Found
Content-Type: application/problem+json; charset=utf-8

{
  "detail": "Video not found",
  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

We provide error type values for a growing number of cases, but it is still optional. Types are used to disambiguate errors that bear the same status code and are non-obvious:

HTTP 1.1 403 Forbidden
Content-Type: application/problem+json; charset=utf-8

{
  "detail": "Cannot get this video regarding follow constraints",
  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"
}

Here a 403 error could otherwise mean that the video is private or blocklisted.

Validation errors

Each parameter is evaluated on its own against a set of rules before the route validator proceeds with potential testing involving parameter combinations. Errors coming from validation errors appear earlier and benefit from a more detailed error description:

HTTP 1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "detail": "Incorrect request parameters: id",
  "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
  "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
  "invalid-params": {
    "id": {
      "location": "params",
      "msg": "Invalid value",
      "param": "id",
      "value": "9c9de5e8-0a1e-484a-b099-e80766180"
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Where id is the name of the field concerned by the error, within the route definition. invalid-params.<field>.location can be either 'params', 'body', 'header', 'query' or 'cookies', and invalid-params.<field>.value reports the value that didn't pass validation whose invalid-params.<field>.msg is about.

Deprecated error fields

Some fields could be included with previous versions. They are still included but their use is deprecated:

error: superseded by detail
code: superseded by type (which is now an URI)

Rate limits

We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:

Endpoint (prefix: `/api/v1`)	Calls	Time frame
`/*`	50	10 seconds
`POST /users/token`	15	5 minutes
`POST /users/register`	2^*	5 minutes
`POST /users/ask-send-verify-email`	3	5 minutes

Depending on the endpoint, ^*failed requests are not taken into account. A service limit is announced by a 429 Too Many Requests status code.

You can get details about the current state of your rate limit by reading the following headers:

Header	Description
`X-RateLimit-Limit`	Number of max requests allowed in the current time period
`X-RateLimit-Remaining`	Number of remaining requests in the current time period
`X-RateLimit-Reset`	Timestamp of end of current time period as UNIX timestamp
`Retry-After`	Seconds to delay after the first `429` is received

CORS

This API features Cross-Origin Resource Sharing (CORS), allowing cross-domain communication from the browser for some routes:

| Endpoint | |------------------------- ---| | /api/* | | /download/* | | /lazy-static/* | | /.well-known/webfinger |

In addition, all routes serving ActivityPub are CORS-enabled for all origins.

PeerTube

Description