PeerTube

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.

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

Example:

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'. invalid-params.<field>.value reports the value that didn't pass validation whose invalid-params.<field>.msg is about.

max_file_size_reached

The uploaded file exceeds the instance-wide file size limit.

quota_reached

The uploaded file exceeds the user's storage quota.

does_not_respect_follow_constraints

The requested remote resource cannot be accessed because the instance does not follow its origin.

live_not_enabled

Live streaming is not enabled on the instance.

live_not_allowing_replay

Saving live replays is disabled on this instance, so a live cannot be created or updated with saveReplay enabled.

live_conflicting_permanent_and_save_replay

Not returned by PeerTube anymore: permanent lives can save replays.

max_instance_lives_limit_reached

The instance has reached its maximum number of simultaneous live streams.

max_user_lives_limit_reached

The user has reached the maximum number of simultaneous live streams.

incorrect_files_in_torrent

The torrent does not contain exactly one usable video file.

comment_not_associated_to_video

The comment is not associated with the requested video.

invalid_grant

The OAuth grant or refresh token is invalid.

invalid_client

Client authentication failed.

invalid_token

The access token is expired, revoked, malformed, or otherwise invalid.

unauthorized_request

The endpoint requires authentication but no access token was provided.

invalid_request

The authentication or token request is malformed: missing grant_type, malformed Authorization header, access token sent using more than one method, or sent in the query string.

unsupported_grant_type

The grant_type is not supported. PeerTube supports password and refresh_token.

unauthorized_client

The OAuth client is not allowed to use the requested grant_type.

server_error

An unexpected error occurred while checking the access token.

missing_two_factor

The required two-factor authentication header is missing.

too_long_password

The password exceeds the maximum allowed length.

invalid_two_factor

The two-factor authentication code is invalid.

account_blocked

The account is blocked.

email_not_verified

The account email address has not been verified.

account_waiting_for_approval

The account is waiting for administrator approval.

account_approval_rejected

The account approval request was rejected.

runner_job_not_in_processing_state

The runner job is not in the processing state.

runner_job_not_in_pending_state

The runner job is not in the pending state.

unknown_runner_token

The runner token is unknown.

video_requires_password

A password is required to access the video.

incorrect_video_password

The password provided for the video is incorrect.

video_already_being_transcoded

The video is already being transcoded.

video_already_being_transcribed

The video is already being transcribed.

video_already_has_captions

The video already has captions.

max_user_video_quota_exceeded_for_user_export

The user requested an export including video files, but the total size of their videos is above the maximum allowed by the instance for such exports. Request an export without video files instead.

current_password_is_invalid

The current password is invalid.

current_password_is_missing

The action requires a password confirmation but currentPassword is missing.

password_confirmation_unavailable

The action requires a password confirmation but the user authenticates with an external auth plugin (OpenID Connect, SAML...), so PeerTube cannot check their password.

Rate limits

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

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:

Password confirmation

If the security.password_confirmation.enabled setting is enabled (default), sensitive administrator actions require the user password in the currentPassword field of the request body:

• Install or update a plugin/theme
• Change the custom JavaScript or CSS of the instance (instance.customizations of the custom configuration)
• Create an administrator, or give the administrator role to a user
• Change the password, email or auth plugin (pluginAuth) of an administrator

After 10 failed password confirmations in 10 minutes (configurable), the user receives a 429 Too Many Requests status code until the end of the time frame, even with the correct password.

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.