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. The spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice - we generate some client SDKs automatically: - [Python](https://framagit.org/framasoft/peertube/clients/python) - [Go](https://framagit.org/framasoft/peertube/clients/go) - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) 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": "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](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/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": "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…