# 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](https://docs.joinpeertube.org/api/rest-getting-started) 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](https://docs.joinpeertube.org/admin/managing-users#roles) 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](https://tools.ietf.org/html/rfc7807) response body. ``` HTTP 1.1 404 Not Found Content-Type: application/problem+json; charset=utf-8 { "detail": "Video not found", "docs": "/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](https://github.com/Chocobozzz/PeerTube/blob/develop/packages/models/src/server/server-error-code.enum.ts), 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": "/api-rest-reference.html#operation/getVideo", "status": 403, "title": "Forbidden", "type": "/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": "/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..location` can be either 'params', 'body', 'header', 'query' or 'cookies'. `invalid-params..value` reports the value that didn't pass validation whose `invalid-params..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](#section/Password-confirmation) but `currentPassword` is missing. ### password_confirmation_unavailable The action requires a [password confirmation](#section/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: | 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 | ## Password confirmation If the `webadmin.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)](https://fetch.spec.whatwg.org/), 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. Version: 8.3.0 Authentication: - OAuth2: oauth2. Authenticating via OAuth requires the following steps: - Have an activated account - [Generate] an access token for that account at `/api/v1/users/token`. - Make requests with the *Authorization: Bearer * header - Profit, depending on the role assigned to the account Note that the __access token is valid for 1 day__ and is given along with a __refresh token valid for 2 weeks__. [Generate]: https://docs.joinpeertube.org/api/rest-getting-started