support/doc/api/quickstart.md

   1 # REST API quick start
   2
   3 ## Authentication
   4
   5 ### Get client
   6
   7 Some endpoints need authentication. We use OAuth 2.0 so first fetch the client tokens:
   8
   9 ```bash
  10 $ curl https://peertube.example.com/api/v1/oauth-clients/local
  11 ```
  12
  13 Response example:
  14
  15 ```json
  16 {
  17   "client_id": "v1ikx5hnfop4mdpnci8nsqh93c45rldf",
  18   "client_secret": "AjWiOapPltI6EnsWQwlFarRtLh4u8tDt"
  19 }
  20 ```
  21
  22 ### Get user token
  23
  24 Now you can fetch the user token:
  25
  26 ```bash
  27 $ curl -X POST \
  28  -d "client_id=v1ikx5hnfop4mdpnci8nsqh93c45rldf&client_secret=AjWiOapPltI6EnsWQwlFarRtLh4u8tDt&grant_type=password&response_type=code&username=your_user&password=your_password" \
  29   https://peertube.example.com/api/v1/users/token
  30 ```
  31
  32 Response example:
  33
  34 ```json
  35 {
  36   "access_token": "90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0",
  37   "token_type": "Bearer",
  38   "expires_in": 14399,
  39   "refresh_token": "2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7"
  40 }
  41 ```
  42
  43 Just use the `access_token` in the `Authorization` header:
  44
  45 ```bash
  46 $ curl -H 'Authorization: Bearer 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0' https://peertube.example.com/api/v1/jobs/completed
  47 ```
  48
  49
  50 ## List videos
  51
  52 ```bash
  53 $ curl https://peertube.example.com/api/v1/videos
  54 ```
  55
  56 ## Libraries
  57
  58 [Convenience libraries](https://framagit.org/framasoft/peertube/clients) are generated automatically from the [OpenAPI specification](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/api/openapi.yaml) for the following languages:
  59
  60 - [python](https://framagit.org/framasoft/peertube/clients/python)
  61 - [go](https://framagit.org/framasoft/peertube/clients/go)
  62 - [kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
  63
  64 Other [languages supported by the OpenAPI generator](https://openapi-generator.tech/docs/generators/#client-generators) can be added to the generation, provided they make a common enough use case.