API PeerTube

Conheça a plataforma

O que integrar com PeerTube

Descrição técnica preservada da especificação de origem. A versão do contrato ajuda a identificar a API; confirme a disponibilidade atual no fornecedor.

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. 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. .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/* | | /.well-known/webfinger | In addition, all routes serving ActivityPub are CORS-enabled for all origins.

Do planejamento à produção

Checklist para integrar PeerTube

1. Defina o fluxo. Identifique quais dados precisam circular, o sistema de origem e o resultado esperado.
2. Leia os requisitos oficiais. Verifique acesso à API, plano necessário, versão e ambiente de testes.
3. Configure o acesso com segurança. Guarde credenciais secretas no servidor e conceda apenas as permissões necessárias. Restrinja chaves públicas conforme a documentação do fornecedor.
4. Teste a primeira requisição. Valide os campos, a paginação e o formato de resposta com dados de teste.
5. Prepare o tratamento de falhas. Considere limites de requisição, retentativas com espera e prevenção de operações duplicadas.
6. Acompanhe a integração. Registre erros sem expor dados sensíveis e monitore alterações na API.