PeerTube 5.1.0
Added: 04/07/2019
Updated at: 06/03/2023
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.