You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
7508 lines
217 KiB
7508 lines
217 KiB
openapi: 3.0.0 |
|
info: |
|
title: PeerTube |
|
version: 4.0.0 |
|
contact: |
|
name: PeerTube Community |
|
url: https://joinpeertube.org |
|
license: |
|
name: AGPLv3.0 |
|
url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE |
|
x-logo: |
|
url: https://joinpeertube.org/img/brand.png |
|
altText: PeerTube Project Homepage |
|
description: | |
|
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?id=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.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and |
|
`invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.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<sup>*</sup> | 5 minutes | |
|
| `POST /users/ask-send-verify-email` | 3 | 5 minutes | |
|
|
|
Depending on the endpoint, <sup>*</sup>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)](https://fetch.spec.whatwg.org/), |
|
allowing cross-domain communication from the browser for some routes: |
|
|
|
| Endpoint | |
|
|------------------------- ---| |
|
| `/api/*` | |
|
| `/download/*` | |
|
| `/lazy-static/*` | |
|
| `/live/segments-sha256/*` | |
|
| `/.well-known/webfinger` | |
|
|
|
In addition, all routes serving ActivityPub are CORS-enabled for all origins. |
|
externalDocs: |
|
url: https://docs.joinpeertube.org/api-rest-reference.html |
|
tags: |
|
- name: Register |
|
description: | |
|
As a visitor, you can use this API to open an account (if registrations are open on |
|
that PeerTube instance). As an admin, you should use the dedicated [User creation |
|
API](#operation/addUser) instead. |
|
- name: Session |
|
x-displayName: Login/Logout |
|
description: | |
|
Sessions deal with access tokens over time. Only __one session token can currently be used at a time__. |
|
- name: Accounts |
|
description: > |
|
Accounts encompass remote accounts discovered across the federation, |
|
and correspond to the main Actor, along with video channels a user can create, which |
|
are also Actors. |
|
|
|
When a comment is posted, it is done with your Account's Actor. |
|
- name: Users |
|
description: > |
|
Using some features of PeerTube require authentication, for which User |
|
provide different levels of permission as well as associated user |
|
information. Each user has a corresponding local Account for federation. |
|
- name: My User |
|
description: > |
|
Operations related to your own User, when logged-in. |
|
- name: My Subscriptions |
|
description: > |
|
Operations related to your subscriptions to video channels, their |
|
new videos, and how to keep up to date with their latest publications! |
|
- name: My History |
|
description: > |
|
Operations related to your watch history. |
|
- name: My Notifications |
|
description: > |
|
Notifications following new videos, follows or reports. They allow you |
|
to keep track of the interactions and overall important information that |
|
concerns you. You MAY set per-notification type delivery preference, to |
|
receive the info either by mail, by in-browser notification or both. |
|
- name: Config |
|
description: > |
|
Each server exposes public information regarding supported videos and |
|
options. |
|
- name: Job |
|
description: > |
|
Jobs are long-running tasks enqueued and processed by the instance |
|
itself. No additional worker registration is currently available. |
|
- name: Instance Follows |
|
description: > |
|
Managing servers which the instance interacts with is crucial to the |
|
concept of federation in PeerTube and external video indexation. The PeerTube |
|
server then deals with inter-server ActivityPub operations and propagates |
|
information across its social graph by posting activities to actors' inbox |
|
endpoints. |
|
externalDocs: |
|
url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows |
|
- name: Instance Redundancy |
|
description: > |
|
Redundancy is part of the inter-server solidarity that PeerTube fosters. |
|
Manage the list of instances you wish to help by seeding their videos according |
|
to the policy of video selection of your choice. Note that you have a similar functionality |
|
to mirror individual videos, see [video mirroring](#tag/Video-Mirroring). |
|
externalDocs: |
|
url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy |
|
- name: Plugins |
|
description: > |
|
Managing plugins installed from a local path or from NPM, or search for new ones. |
|
externalDocs: |
|
url: https://docs.joinpeertube.org/api-plugins |
|
- name: Abuses |
|
description: | |
|
Abuses deal with reports of local or remote videos/comments/accounts alike. |
|
- name: Video |
|
description: | |
|
Operations dealing with listing, uploading, fetching or modifying videos. |
|
- name: Video Upload |
|
description: | |
|
Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes. |
|
|
|
### Upload |
|
|
|
- [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request |
|
- [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks |
|
|
|
You can upload videos more reliably by using the resumable variant. Its protocol lets |
|
you resume an upload operation after a network interruption or other transmission failure, |
|
saving time and bandwidth in the event of network failures. |
|
|
|
Favor using resumable uploads in any of the following cases: |
|
- You are transferring large files |
|
- The likelihood of a network interruption is high |
|
- Uploads are originating from a device with a low-bandwidth or unstable Internet connection, |
|
such as a mobile device |
|
|
|
### Import |
|
|
|
- _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/) |
|
- _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file |
|
- _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file |
|
|
|
The import function is practical when the desired video/audio is available online. It makes PeerTube |
|
download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have. |
|
- name: Video Imports |
|
description: Operations dealing with listing, adding and removing video imports. |
|
- name: Video Captions |
|
description: Operations dealing with listing, adding and removing closed captions of a video. |
|
- name: Video Channels |
|
description: Operations dealing with the creation, modification and listing of videos within a channel. |
|
- name: Video Comments |
|
description: > |
|
Operations dealing with comments to a video. Comments are organized in threads: adding a |
|
comment in response to the video starts a thread, adding a reply to a comment adds it to |
|
its root comment thread. |
|
- name: Video Blocks |
|
description: Operations dealing with blocking videos (removing them from view and preventing interactions). |
|
- name: Video Rates |
|
description: Like/dislike a video. |
|
- name: Video Playlists |
|
description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels. |
|
- name: Video Files |
|
description: Operations on video files |
|
- name: Video Transcoding |
|
description: Video transcoding related operations |
|
- name: Feeds |
|
description: Server syndication feeds |
|
- name: Search |
|
description: | |
|
The search helps to find _videos_ or _channels_ from within the instance and beyond. |
|
Videos from other instances federated by the instance (that is, instances |
|
followed by the instance) can be found via keywords and other criteria of |
|
the advanced search. |
|
|
|
Administrators can also enable the use of a remote search system, indexing |
|
videos and channels not could be not federated by the instance. |
|
- name: Homepage |
|
description: Get and update the custom homepage |
|
- name: Video Mirroring |
|
description: | |
|
PeerTube instances can mirror videos from one another, and help distribute some videos. |
|
|
|
For importing videos as your own, refer to [video imports](#operation/importVideo). |
|
x-tagGroups: |
|
- name: Auth |
|
tags: |
|
- Register |
|
- Session |
|
- name: Accounts |
|
tags: |
|
- Accounts |
|
- Users |
|
- My User |
|
- My Subscriptions |
|
- My Notifications |
|
- My History |
|
- name: Videos |
|
tags: |
|
- Video |
|
- Video Upload |
|
- Video Imports |
|
- Video Captions |
|
- Video Channels |
|
- Video Comments |
|
- Video Rates |
|
- Video Playlists |
|
- Video Ownership Change |
|
- Video Mirroring |
|
- Video Files |
|
- Video Transcoding |
|
- Live Videos |
|
- Feeds |
|
- name: Search |
|
tags: |
|
- Search |
|
- name: Custom pages |
|
tags: |
|
- Homepage |
|
- name: Moderation |
|
tags: |
|
- Abuses |
|
- Video Blocks |
|
- Account Blocks |
|
- Server Blocks |
|
- name: Instance Configuration |
|
tags: |
|
- Config |
|
- Instance Follows |
|
- Instance Redundancy |
|
- Plugins |
|
- name: Jobs |
|
tags: |
|
- Job |
|
paths: |
|
'/accounts/{name}': |
|
get: |
|
tags: |
|
- Accounts |
|
summary: Get an account |
|
operationId: getAccount |
|
parameters: |
|
- $ref: '#/components/parameters/name' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/Account' |
|
'404': |
|
description: account not found |
|
|
|
'/accounts/{name}/videos': |
|
get: |
|
tags: |
|
- Accounts |
|
- Video |
|
summary: 'List videos of an account' |
|
operationId: getAccountVideos |
|
parameters: |
|
- $ref: '#/components/parameters/name' |
|
- $ref: '#/components/parameters/categoryOneOf' |
|
- $ref: '#/components/parameters/isLive' |
|
- $ref: '#/components/parameters/tagsOneOf' |
|
- $ref: '#/components/parameters/tagsAllOf' |
|
- $ref: '#/components/parameters/licenceOneOf' |
|
- $ref: '#/components/parameters/languageOneOf' |
|
- $ref: '#/components/parameters/nsfw' |
|
- $ref: '#/components/parameters/isLocal' |
|
- $ref: '#/components/parameters/include' |
|
- $ref: '#/components/parameters/privacyOneOf' |
|
- $ref: '#/components/parameters/hasHLSFiles' |
|
- $ref: '#/components/parameters/hasWebtorrentFiles' |
|
- $ref: '#/components/parameters/skipCount' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/videosSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoListResponse' |
|
x-codeSamples: |
|
- lang: JavaScript |
|
source: | |
|
fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos') |
|
.then(function(response) { |
|
return response.json() |
|
}).then(function(data) { |
|
console.log(data) |
|
}) |
|
- lang: Shell |
|
source: | |
|
## DEPENDENCIES: jq |
|
curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq |
|
- lang: Ruby |
|
source: | |
|
require 'net/http' |
|
require 'json' |
|
|
|
uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos") |
|
|
|
http = Net::HTTP.new(uri.host, uri.port) |
|
http.use_ssl = true |
|
|
|
response = http.get(uri.request_uri) |
|
|
|
puts JSON.parse(response.read_body) |
|
- lang: Python |
|
source: | |
|
import requests |
|
|
|
r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos") |
|
json = r.json() |
|
|
|
print(json) |
|
|
|
'/accounts/{name}/followers': |
|
get: |
|
tags: |
|
- Accounts |
|
summary: 'List followers of an account' |
|
security: |
|
- OAuth2: [] |
|
operationId: getAccountFollowers |
|
parameters: |
|
- $ref: '#/components/parameters/name' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/followersSort' |
|
- $ref: '#/components/parameters/search' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Follow' |
|
|
|
/accounts: |
|
get: |
|
tags: |
|
- Accounts |
|
summary: List accounts |
|
operationId: getAccounts |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
'application/json': |
|
schema: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Account' |
|
|
|
/config: |
|
get: |
|
tags: |
|
- Config |
|
summary: Get instance public configuration |
|
operationId: getConfig |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/ServerConfig' |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/config |
|
|
|
/config/about: |
|
get: |
|
summary: Get instance "About" information |
|
operationId: getAbout |
|
tags: |
|
- Config |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/ServerConfigAbout' |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/config/about |
|
|
|
/config/custom: |
|
get: |
|
summary: Get instance runtime configuration |
|
operationId: getCustomConfig |
|
tags: |
|
- Config |
|
security: |
|
- OAuth2: |
|
- admin |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/ServerConfigCustom' |
|
put: |
|
summary: Set instance runtime configuration |
|
operationId: putCustomConfig |
|
tags: |
|
- Config |
|
security: |
|
- OAuth2: |
|
- admin |
|
responses: |
|
'200': |
|
description: successful operation |
|
'400': |
|
x-summary: field inconsistencies |
|
description: > |
|
Arises when: |
|
- the emailer is disabled and the instance is open to registrations |
|
- webtorrent and hls are disabled with transcoding enabled - you need at least one enabled |
|
delete: |
|
summary: Delete instance runtime configuration |
|
operationId: delCustomConfig |
|
tags: |
|
- Config |
|
security: |
|
- OAuth2: |
|
- admin |
|
responses: |
|
'200': |
|
description: successful operation |
|
|
|
/custom-pages/homepage/instance: |
|
get: |
|
summary: Get instance custom homepage |
|
tags: |
|
- Homepage |
|
responses: |
|
'404': |
|
description: No homepage set |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/CustomHomepage' |
|
put: |
|
summary: Set instance custom homepage |
|
tags: |
|
- Homepage |
|
security: |
|
- OAuth2: |
|
- admin |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
content: |
|
type: string |
|
description: content of the homepage, that will be injected in the client |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/jobs/pause: |
|
post: |
|
summary: Pause job queue |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Job |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/jobs/resume: |
|
post: |
|
summary: Resume job queue |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Job |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/jobs/{state}: |
|
get: |
|
summary: List instance jobs |
|
operationId: getJobs |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Job |
|
parameters: |
|
- name: state |
|
in: path |
|
required: true |
|
description: The state of the job ('' for for no filter) |
|
schema: |
|
type: string |
|
enum: |
|
- '' |
|
- active |
|
- completed |
|
- failed |
|
- waiting |
|
- delayed |
|
- $ref: '#/components/parameters/jobType' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
maxItems: 100 |
|
items: |
|
$ref: '#/components/schemas/Job' |
|
|
|
/server/followers: |
|
get: |
|
tags: |
|
- Instance Follows |
|
summary: List instances following the server |
|
parameters: |
|
- $ref: '#/components/parameters/followState' |
|
- $ref: '#/components/parameters/actorType' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Follow' |
|
|
|
'/server/followers/{nameWithHost}': |
|
delete: |
|
summary: Remove or reject a follower to your server |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Instance Follows |
|
parameters: |
|
- name: nameWithHost |
|
in: path |
|
required: true |
|
description: The remote actor handle to remove from your followers |
|
schema: |
|
type: string |
|
format: email |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: follower not found |
|
|
|
'/server/followers/{nameWithHost}/reject': |
|
post: |
|
summary: Reject a pending follower to your server |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Instance Follows |
|
parameters: |
|
- name: nameWithHost |
|
in: path |
|
required: true |
|
description: The remote actor handle to remove from your followers |
|
schema: |
|
type: string |
|
format: email |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: follower not found |
|
|
|
'/server/followers/{nameWithHost}/accept': |
|
post: |
|
summary: Accept a pending follower to your server |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Instance Follows |
|
parameters: |
|
- name: nameWithHost |
|
in: path |
|
required: true |
|
description: The remote actor handle to remove from your followers |
|
schema: |
|
type: string |
|
format: email |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: follower not found |
|
|
|
/server/following: |
|
get: |
|
tags: |
|
- Instance Follows |
|
summary: List instances followed by the server |
|
parameters: |
|
- $ref: '#/components/parameters/followState' |
|
- $ref: '#/components/parameters/actorType' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Follow' |
|
post: |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Instance Follows |
|
summary: Follow a list of actors (PeerTube instance, channel or account) |
|
responses: |
|
'204': |
|
description: successful operation |
|
'500': |
|
description: cannot follow a non-HTTPS server |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
hosts: |
|
type: array |
|
items: |
|
type: string |
|
format: hostname |
|
uniqueItems: true |
|
handles: |
|
type: array |
|
items: |
|
type: string |
|
uniqueItems: true |
|
|
|
'/server/following/{hostOrHandle}': |
|
delete: |
|
summary: Unfollow an actor (PeerTube instance, channel or account) |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Instance Follows |
|
parameters: |
|
- name: hostOrHandle |
|
in: path |
|
required: true |
|
description: The hostOrHandle to unfollow |
|
schema: |
|
type: string |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: host or handle not found |
|
|
|
/users: |
|
post: |
|
summary: Create a user |
|
operationId: addUser |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Users |
|
responses: |
|
'200': |
|
description: user created |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/AddUserResponse' |
|
links: |
|
# GET /users/{id} |
|
GetUser: |
|
operationId: getUser |
|
parameters: |
|
id: '$response.body#/user/id' |
|
# PUT /users/{id} |
|
PutUser: |
|
operationId: putUser |
|
parameters: |
|
id: '$response.body#/user/id' |
|
# DELETE /users/{id} |
|
DelUser: |
|
operationId: delUser |
|
parameters: |
|
id: '$response.body#/user/id' |
|
'403': |
|
description: insufficient authority to create an admin or moderator |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/AddUser' |
|
description: | |
|
If the smtp server is configured, you can leave the password empty and an email will be sent |
|
asking the user to set it first. |
|
required: true |
|
get: |
|
summary: List users |
|
operationId: getUsers |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Users |
|
parameters: |
|
- $ref: '#/components/parameters/usersSearch' |
|
- $ref: '#/components/parameters/usersBlocked' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/usersSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/User' |
|
|
|
'/users/{id}': |
|
parameters: |
|
- $ref: '#/components/parameters/id' |
|
delete: |
|
summary: Delete a user |
|
security: |
|
- OAuth2: |
|
- admin |
|
tags: |
|
- Users |
|
operationId: delUser |
|
responses: |
|
'204': |
|
description: successful operation |
|
get: |
|
summary: Get a user |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Users |
|
operationId: getUser |
|
parameters: |
|
- name: withStats |
|
in: query |
|
description: include statistics about the user (only available as a moderator/admin) |
|
schema: |
|
type: boolean |
|
responses: |
|
'200': |
|
x-summary: successful operation |
|
description: | |
|
As an admin/moderator, you can request a response augmented with statistics about the user's |
|
moderation relations and videos usage, by using the `withStats` parameter. |
|
content: |
|
application/json: |
|
schema: |
|
oneOf: |
|
- $ref: '#/components/schemas/User' |
|
- $ref: '#/components/schemas/UserWithStats' |
|
put: |
|
summary: Update a user |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Users |
|
operationId: putUser |
|
responses: |
|
'204': |
|
description: successful operation |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/UpdateUser' |
|
required: true |
|
|
|
/oauth-clients/local: |
|
get: |
|
summary: Login prerequisite |
|
description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken). |
|
operationId: getOAuthClient |
|
tags: |
|
- Session |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/OAuthClient' |
|
links: |
|
UseOAuthClientToLogin: |
|
operationId: getOAuthToken |
|
parameters: |
|
client_id: '$response.body#/client_id' |
|
client_secret: '$response.body#/client_secret' |
|
x-codeSamples: |
|
- lang: Shell |
|
source: | |
|
API="https://peertube2.cpy.re/api/v1" |
|
|
|
## AUTH |
|
curl -s "$API/oauth-clients/local" |
|
|
|
/users/token: |
|
post: |
|
summary: Login |
|
operationId: getOAuthToken |
|
description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens. |
|
tags: |
|
- Session |
|
requestBody: |
|
content: |
|
application/x-www-form-urlencoded: |
|
schema: |
|
oneOf: |
|
- $ref: '#/components/schemas/OAuthToken-password' |
|
- $ref: '#/components/schemas/OAuthToken-refresh_token' |
|
discriminator: |
|
propertyName: grant_type |
|
mapping: |
|
password: '#/components/schemas/OAuthToken-password' |
|
refresh_token: '#/components/schemas/OAuthToken-refresh_token' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
token_type: |
|
type: string |
|
example: Bearer |
|
access_token: |
|
type: string |
|
example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0 |
|
description: valid for 1 day |
|
refresh_token: |
|
type: string |
|
example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7 |
|
description: valid for 2 weeks |
|
expires_in: |
|
type: integer |
|
minimum: 0 |
|
example: 14399 |
|
refresh_token_expires_in: |
|
type: integer |
|
minimum: 0 |
|
example: 1209600 |
|
'400': |
|
x-summary: client or credentials are invalid |
|
description: | |
|
Disambiguate via `type`: |
|
- `invalid_client` for an unmatched `client_id` |
|
- `invalid_grant` for unmatched credentials |
|
'401': |
|
x-summary: token expired |
|
description: | |
|
Disambiguate via `type`: |
|
- default value for a regular authentication failure |
|
- `invalid_token` for an expired token |
|
x-codeSamples: |
|
- lang: Shell |
|
source: | |
|
## DEPENDENCIES: jq |
|
API="https://peertube2.cpy.re/api/v1" |
|
USERNAME="<your_username>" |
|
PASSWORD="<your_password>" |
|
|
|
## AUTH |
|
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id") |
|
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret") |
|
curl -s "$API/users/token" \ |
|
--data client_id="$client_id" \ |
|
--data client_secret="$client_secret" \ |
|
--data grant_type=password \ |
|
--data username="$USERNAME" \ |
|
--data password="$PASSWORD" \ |
|
| jq -r ".access_token" |
|
|
|
/users/revoke-token: |
|
post: |
|
summary: Logout |
|
description: Revokes your access token and its associated refresh token, destroying your current session. |
|
operationId: revokeOAuthToken |
|
tags: |
|
- Session |
|
security: |
|
- OAuth2: [] |
|
responses: |
|
'200': |
|
description: successful operation |
|
|
|
/users/register: |
|
post: |
|
summary: Register a user |
|
operationId: registerUser |
|
tags: |
|
- Users |
|
- Register |
|
responses: |
|
'204': |
|
description: successful operation |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/RegisterUser' |
|
required: true |
|
|
|
/users/{id}/verify-email: |
|
post: |
|
summary: Verify a user |
|
operationId: verifyUser |
|
description: | |
|
Following a user registration, the new user will receive an email asking to click a link |
|
containing a secret. |
|
tags: |
|
- Users |
|
- Register |
|
parameters: |
|
- $ref: '#/components/parameters/id' |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
verificationString: |
|
type: string |
|
format: url |
|
isPendingEmail: |
|
type: boolean |
|
required: |
|
- verificationString |
|
responses: |
|
'204': |
|
description: successful operation |
|
'403': |
|
description: invalid verification string |
|
'404': |
|
description: user not found |
|
|
|
/users/ask-send-verify-email: |
|
post: |
|
summary: Resend user verification link |
|
operationId: resendEmailToVerifyUser |
|
tags: |
|
- Users |
|
- Register |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me: |
|
get: |
|
summary: Get my user information |
|
operationId: getUserInfo |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My User |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/User' |
|
put: |
|
summary: Update my user information |
|
operationId: putUserInfo |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My User |
|
responses: |
|
'204': |
|
description: successful operation |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/UpdateMe' |
|
required: true |
|
|
|
/users/me/videos/imports: |
|
get: |
|
summary: Get video imports of my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- Videos |
|
- My User |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoImportsList' |
|
|
|
/users/me/video-quota-used: |
|
get: |
|
summary: Get my user used quota |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My User |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
videoQuotaUsed: |
|
type: number |
|
description: The user video quota used so far in bytes |
|
example: 16810141515 |
|
videoQuotaUsedDaily: |
|
type: number |
|
description: The user video quota used today in bytes |
|
example: 1681014151 |
|
|
|
'/users/me/videos/{videoId}/rating': |
|
get: |
|
summary: Get rate of my user for a video |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My User |
|
- Video Rates |
|
parameters: |
|
- name: videoId |
|
in: path |
|
required: true |
|
description: The video id |
|
schema: |
|
$ref: '#/components/schemas/Video/properties/id' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/GetMeVideoRating' |
|
|
|
/users/me/videos: |
|
get: |
|
summary: Get videos of my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My User |
|
- Videos |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoListResponse' |
|
|
|
/users/me/subscriptions: |
|
get: |
|
summary: Get my user subscriptions |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My Subscriptions |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannelList' |
|
post: |
|
tags: |
|
- My Subscriptions |
|
summary: Add subscription to my user |
|
security: |
|
- OAuth2: |
|
- user |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
uri: |
|
type: string |
|
format: uri |
|
description: uri of the video channels to subscribe to |
|
required: |
|
- uri |
|
examples: |
|
default: |
|
value: |
|
uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr |
|
responses: |
|
'200': |
|
description: successful operation |
|
|
|
/users/me/subscriptions/exist: |
|
get: |
|
summary: Get if subscriptions exist for my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My Subscriptions |
|
parameters: |
|
- $ref: '#/components/parameters/subscriptionsUris' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
|
|
/users/me/subscriptions/videos: |
|
get: |
|
summary: List videos of subscriptions of my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My Subscriptions |
|
- Videos |
|
parameters: |
|
- $ref: '#/components/parameters/categoryOneOf' |
|
- $ref: '#/components/parameters/isLive' |
|
- $ref: '#/components/parameters/tagsOneOf' |
|
- $ref: '#/components/parameters/tagsAllOf' |
|
- $ref: '#/components/parameters/licenceOneOf' |
|
- $ref: '#/components/parameters/languageOneOf' |
|
- $ref: '#/components/parameters/nsfw' |
|
- $ref: '#/components/parameters/isLocal' |
|
- $ref: '#/components/parameters/include' |
|
- $ref: '#/components/parameters/privacyOneOf' |
|
- $ref: '#/components/parameters/hasHLSFiles' |
|
- $ref: '#/components/parameters/hasWebtorrentFiles' |
|
- $ref: '#/components/parameters/skipCount' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/videosSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoListResponse' |
|
|
|
'/users/me/subscriptions/{subscriptionHandle}': |
|
get: |
|
summary: Get subscription of my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My Subscriptions |
|
parameters: |
|
- $ref: '#/components/parameters/subscriptionHandle' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannel' |
|
delete: |
|
summary: Delete subscription of my user |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- My Subscriptions |
|
parameters: |
|
- $ref: '#/components/parameters/subscriptionHandle' |
|
responses: |
|
'200': |
|
description: successful operation |
|
|
|
/users/me/notifications: |
|
get: |
|
summary: List my notifications |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My Notifications |
|
parameters: |
|
- name: unread |
|
in: query |
|
description: only list unread notifications |
|
schema: |
|
type: boolean |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/NotificationListResponse' |
|
|
|
/users/me/notifications/read: |
|
post: |
|
summary: Mark notifications as read by their id |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My Notifications |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
ids: |
|
type: array |
|
description: ids of the notifications to mark as read |
|
items: |
|
type: integer |
|
required: |
|
- ids |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me/notifications/read-all: |
|
post: |
|
summary: Mark all my notification as read |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My Notifications |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me/notification-settings: |
|
put: |
|
summary: Update my notification settings |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My Notifications |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
newVideoFromSubscription: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
newCommentOnMyVideo: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
abuseAsModerator: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
videoAutoBlacklistAsModerator: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
blacklistOnMyVideo: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
myVideoPublished: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
myVideoImportFinished: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
newFollow: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
newUserRegistration: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
commentMention: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
newInstanceFollower: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
autoInstanceFollowing: |
|
$ref: '#/components/schemas/NotificationSettingValue' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me/history/videos: |
|
get: |
|
summary: List watched videos history |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My History |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/search' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoListResponse' |
|
|
|
/users/me/history/videos/{videoId}: |
|
delete: |
|
summary: Delete history element |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My History |
|
parameters: |
|
- name: videoId |
|
in: path |
|
required: true |
|
schema: |
|
$ref: '#/components/schemas/Video/properties/id' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me/history/videos/remove: |
|
post: |
|
summary: Clear video history |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My History |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
type: object |
|
properties: |
|
beforeDate: |
|
description: history before this date will be deleted |
|
type: string |
|
format: date-time |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/users/me/avatar/pick: |
|
post: |
|
summary: Update my user avatar |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My User |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
avatar: |
|
$ref: '#/components/schemas/ActorImage' |
|
'413': |
|
description: image file too large |
|
headers: |
|
X-File-Maximum-Size: |
|
schema: |
|
type: string |
|
format: Nginx size |
|
description: Maximum file size for the avatar |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
type: object |
|
properties: |
|
avatarfile: |
|
description: The file to upload |
|
type: string |
|
format: binary |
|
encoding: |
|
avatarfile: |
|
contentType: image/png, image/jpeg |
|
|
|
/users/me/avatar: |
|
delete: |
|
summary: Delete my avatar |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- My User |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/videos/ownership: |
|
get: |
|
summary: List video ownership changes |
|
tags: |
|
- Video Ownership Change |
|
security: |
|
- OAuth2: [] |
|
responses: |
|
'200': |
|
description: successful operation |
|
|
|
'/videos/ownership/{id}/accept': |
|
post: |
|
summary: Accept ownership change request |
|
tags: |
|
- Video Ownership Change |
|
security: |
|
- OAuth2: [] |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'403': |
|
description: cannot terminate an ownership change of another user |
|
'404': |
|
description: video owneship change not found |
|
|
|
'/videos/ownership/{id}/refuse': |
|
post: |
|
summary: Refuse ownership change request |
|
tags: |
|
- Video Ownership Change |
|
security: |
|
- OAuth2: [] |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'403': |
|
description: cannot terminate an ownership change of another user |
|
'404': |
|
description: video owneship change not found |
|
|
|
'/videos/{id}/give-ownership': |
|
post: |
|
summary: Request ownership change |
|
tags: |
|
- Video Ownership Change |
|
security: |
|
- OAuth2: [] |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
requestBody: |
|
required: true |
|
content: |
|
application/x-www-form-urlencoded: |
|
schema: |
|
type: object |
|
properties: |
|
username: |
|
type: string |
|
required: |
|
- username |
|
responses: |
|
'204': |
|
description: successful operation |
|
'400': |
|
description: changing video ownership to a remote account is not supported yet |
|
'404': |
|
description: video not found |
|
|
|
/videos: |
|
get: |
|
summary: List videos |
|
operationId: getVideos |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/categoryOneOf' |
|
- $ref: '#/components/parameters/isLive' |
|
- $ref: '#/components/parameters/tagsOneOf' |
|
- $ref: '#/components/parameters/tagsAllOf' |
|
- $ref: '#/components/parameters/licenceOneOf' |
|
- $ref: '#/components/parameters/languageOneOf' |
|
- $ref: '#/components/parameters/nsfw' |
|
- $ref: '#/components/parameters/isLocal' |
|
- $ref: '#/components/parameters/include' |
|
- $ref: '#/components/parameters/privacyOneOf' |
|
- $ref: '#/components/parameters/hasHLSFiles' |
|
- $ref: '#/components/parameters/hasWebtorrentFiles' |
|
- $ref: '#/components/parameters/skipCount' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/videosSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoListResponse' |
|
|
|
/videos/categories: |
|
get: |
|
summary: List available video categories |
|
operationId: getCategories |
|
tags: |
|
- Video |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
type: string |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/videos/categories |
|
|
|
/videos/licences: |
|
get: |
|
summary: List available video licences |
|
operationId: getLicences |
|
tags: |
|
- Video |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
type: string |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/videos/licences |
|
|
|
/videos/languages: |
|
get: |
|
summary: List available video languages |
|
operationId: getLanguages |
|
tags: |
|
- Video |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
type: string |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/videos/languages |
|
|
|
/videos/privacies: |
|
get: |
|
summary: List available video privacy policies |
|
operationId: getPrivacyPolicies |
|
tags: |
|
- Video |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: array |
|
items: |
|
type: string |
|
examples: |
|
nightly: |
|
externalValue: https://peertube2.cpy.re/api/v1/videos/privacies |
|
|
|
'/videos/{id}': |
|
put: |
|
summary: Update a video |
|
operationId: putVideo |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
type: object |
|
properties: |
|
thumbnailfile: |
|
description: Video thumbnail file |
|
type: string |
|
format: binary |
|
previewfile: |
|
description: Video preview file |
|
type: string |
|
format: binary |
|
category: |
|
$ref: '#/components/schemas/VideoCategorySet' |
|
licence: |
|
$ref: '#/components/schemas/VideoLicenceSet' |
|
language: |
|
$ref: '#/components/schemas/VideoLanguageSet' |
|
privacy: |
|
$ref: '#/components/schemas/VideoPrivacySet' |
|
description: |
|
description: Video description |
|
type: string |
|
waitTranscoding: |
|
description: Whether or not we wait transcoding before publish the video |
|
type: string |
|
support: |
|
description: A text tell the audience how to support the video creator |
|
example: Please support our work on https://soutenir.framasoft.org/en/ <3 |
|
type: string |
|
nsfw: |
|
description: Whether or not this video contains sensitive content |
|
type: boolean |
|
name: |
|
description: Video name |
|
type: string |
|
minLength: 3 |
|
maxLength: 120 |
|
tags: |
|
description: Video tags (maximum 5 tags each between 2 and 30 characters) |
|
type: array |
|
minItems: 1 |
|
maxItems: 5 |
|
items: |
|
type: string |
|
minLength: 2 |
|
maxLength: 30 |
|
commentsEnabled: |
|
description: Enable or disable comments for this video |
|
type: boolean |
|
downloadEnabled: |
|
description: Enable or disable downloading for this video |
|
type: boolean |
|
originallyPublishedAt: |
|
description: Date when the content was originally published |
|
type: string |
|
format: date-time |
|
scheduleUpdate: |
|
$ref: '#/components/schemas/VideoScheduledUpdate' |
|
encoding: |
|
thumbnailfile: |
|
contentType: image/jpeg |
|
previewfile: |
|
contentType: image/jpeg |
|
get: |
|
summary: Get a video |
|
operationId: getVideo |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoDetails' |
|
delete: |
|
summary: Delete a video |
|
operationId: delVideo |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
'/videos/{id}/description': |
|
get: |
|
summary: Get complete video description |
|
operationId: getVideoDesc |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
nullable: true |
|
type: string |
|
minLength: 3 |
|
maxLength: 10000 |
|
example: | |
|
**[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)** |
|
|
|
'/videos/{id}/views': |
|
post: |
|
summary: Add a view to a video |
|
operationId: addView |
|
tags: |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
'/videos/{id}/watching': |
|
put: |
|
summary: Set watching progress of a video |
|
operationId: setProgress |
|
tags: |
|
- Video |
|
security: |
|
- OAuth2: [] |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/UserWatchingVideo' |
|
required: true |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/videos/upload: |
|
post: |
|
summary: Upload a video |
|
description: Uses a single request to upload a video. |
|
operationId: uploadLegacy |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
- Video Upload |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadResponse' |
|
'403': |
|
description: video didn't pass upload filter |
|
'408': |
|
description: upload has timed out |
|
'413': |
|
x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy |
|
description: | |
|
If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`: |
|
- `quota_reached` for quota limits wether daily or global |
|
headers: |
|
X-File-Maximum-Size: |
|
schema: |
|
type: string |
|
format: Nginx size |
|
description: Maximum file size for the video |
|
'415': |
|
description: video type unsupported |
|
'422': |
|
description: video unreadable |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadRequestLegacy' |
|
encoding: |
|
videofile: |
|
contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream |
|
thumbnailfile: |
|
contentType: image/jpeg |
|
previewfile: |
|
contentType: image/jpeg |
|
x-codeSamples: |
|
- lang: Shell |
|
source: | |
|
## DEPENDENCIES: jq |
|
USERNAME="<your_username>" |
|
PASSWORD="<your_password>" |
|
FILE_PATH="<your_file_path>" |
|
CHANNEL_ID="<your_channel_id>" |
|
NAME="<video_name>" |
|
API="https://peertube2.cpy.re/api/v1" |
|
|
|
## AUTH |
|
client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id") |
|
client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret") |
|
token=$(curl -s "$API/users/token" \ |
|
--data client_id="$client_id" \ |
|
--data client_secret="$client_secret" \ |
|
--data grant_type=password \ |
|
--data username="$USERNAME" \ |
|
--data password="$PASSWORD" \ |
|
| jq -r ".access_token") |
|
|
|
## VIDEO UPLOAD |
|
curl -s "$API/videos/upload" \ |
|
-H "Authorization: Bearer $token" \ |
|
--max-time 600 \ |
|
--form videofile=@"$FILE_PATH" \ |
|
--form channelId=$CHANNEL_ID \ |
|
--form name="$NAME" |
|
|
|
/videos/upload-resumable: |
|
post: |
|
summary: Initialize the resumable upload of a video |
|
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video |
|
operationId: uploadResumableInit |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
- Video Upload |
|
parameters: |
|
- name: X-Upload-Content-Length |
|
in: header |
|
schema: |
|
type: number |
|
example: 2469036 |
|
required: true |
|
description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading. |
|
- name: X-Upload-Content-Type |
|
in: header |
|
schema: |
|
type: string |
|
format: mimetype |
|
example: video/mp4 |
|
required: true |
|
description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary. |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadRequestResumable' |
|
responses: |
|
'200': |
|
description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead |
|
'201': |
|
description: created |
|
headers: |
|
Location: |
|
schema: |
|
type: string |
|
format: url |
|
example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51 |
|
Content-Length: |
|
schema: |
|
type: number |
|
example: 0 |
|
'413': |
|
x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit |
|
description: | |
|
Disambiguate via `type`: |
|
- `max_file_size_reached` for the absolute file size limit |
|
- `quota_reached` for quota limits whether daily or global |
|
'415': |
|
description: video type unsupported |
|
put: |
|
summary: Send chunk for the resumable upload of a video |
|
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video |
|
operationId: uploadResumable |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
- Video Upload |
|
parameters: |
|
- name: upload_id |
|
in: query |
|
required: true |
|
description: | |
|
Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is |
|
not valid anymore and you need to initialize a new upload. |
|
schema: |
|
type: string |
|
- name: Content-Range |
|
in: header |
|
schema: |
|
type: string |
|
example: bytes 0-262143/2469036 |
|
required: true |
|
description: | |
|
Specifies the bytes in the file that the request is uploading. |
|
|
|
For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first |
|
262144 bytes (256 x 1024) in a 2,469,036 byte file. |
|
- name: Content-Length |
|
in: header |
|
schema: |
|
type: number |
|
example: 262144 |
|
required: true |
|
description: | |
|
Size of the chunk that the request is sending. |
|
|
|
The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol) |
|
doesn't mandate for chunks to have the same size throughout the upload sequence. |
|
|
|
Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from |
|
1048576 bytes (~1MB) and increases or reduces size depending on connection health. |
|
requestBody: |
|
content: |
|
application/octet-stream: |
|
schema: |
|
type: string |
|
format: binary |
|
responses: |
|
'200': |
|
description: last chunk received |
|
headers: |
|
Content-Length: |
|
schema: |
|
type: number |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadResponse' |
|
'308': |
|
description: resume incomplete |
|
headers: |
|
Range: |
|
schema: |
|
type: string |
|
example: bytes=0-262143 |
|
Content-Length: |
|
schema: |
|
type: number |
|
example: 0 |
|
'403': |
|
description: video didn't pass upload filter |
|
'404': |
|
description: upload not found |
|
'409': |
|
description: chunk doesn't match range |
|
'422': |
|
description: video unreadable |
|
'429': |
|
description: too many concurrent requests |
|
'503': |
|
description: upload is already being processed |
|
headers: |
|
'Retry-After': |
|
schema: |
|
type: number |
|
example: 300 |
|
delete: |
|
summary: Cancel the resumable upload of a video, deleting any data uploaded so far |
|
description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video |
|
operationId: uploadResumableCancel |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video |
|
- Video Upload |
|
parameters: |
|
- name: upload_id |
|
in: query |
|
required: true |
|
description: | |
|
Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is |
|
not valid anymore and the upload session has already been deleted with its data ;-) |
|
schema: |
|
type: string |
|
- name: Content-Length |
|
in: header |
|
required: true |
|
schema: |
|
type: number |
|
example: 0 |
|
responses: |
|
'204': |
|
description: upload cancelled |
|
headers: |
|
Content-Length: |
|
schema: |
|
type: number |
|
example: 0 |
|
'404': |
|
description: upload not found |
|
|
|
/videos/imports: |
|
post: |
|
summary: Import a video |
|
description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator) |
|
operationId: importVideo |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Imports |
|
- Video Upload |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
$ref: '#/components/schemas/VideoCreateImport' |
|
encoding: |
|
torrentfile: |
|
contentType: application/x-bittorrent |
|
thumbnailfile: |
|
contentType: image/jpeg |
|
previewfile: |
|
contentType: image/jpeg |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadResponse' |
|
'400': |
|
description: '`magnetUri` or `targetUrl` or a torrent file missing' |
|
'403': |
|
description: video didn't pass pre-import filter |
|
'409': |
|
description: HTTP or Torrent/magnetURI import not enabled |
|
|
|
/videos/imports/{id}/cancel: |
|
post: |
|
summary: Cancel video import |
|
description: Cancel a pending video import |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Imports |
|
parameters: |
|
- $ref: '#/components/parameters/id' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/videos/imports/{id}: |
|
delete: |
|
summary: Delete video import |
|
description: Delete ended video import |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Imports |
|
parameters: |
|
- $ref: '#/components/parameters/id' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
/videos/live: |
|
post: |
|
summary: Create a live |
|
operationId: addLive |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Live Videos |
|
- Video |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoUploadResponse' |
|
'400': |
|
x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set |
|
description: | |
|
Disambiguate via `type`: |
|
- default type for a validation error |
|
- `live_conflicting_permanent_and_save_replay` for conflicting parameters set |
|
'403': |
|
x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded |
|
description: | |
|
Disambiguate via `type`: |
|
- `live_not_enabled` for a disabled live feature |
|
- `live_not_allowing_replay` for a disabled replay feature |
|
- `max_instance_lives_limit_reached` for the absolute concurrent live limit |
|
- `max_user_lives_limit_reached` for the user concurrent live limit |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
type: object |
|
properties: |
|
channelId: |
|
description: Channel id that will contain this live video |
|
type: integer |
|
saveReplay: |
|
type: boolean |
|
permanentLive: |
|
description: User can stream multiple times in a permanent live |
|
type: boolean |
|
thumbnailfile: |
|
description: Live video/replay thumbnail file |
|
type: string |
|
format: binary |
|
previewfile: |
|
description: Live video/replay preview file |
|
type: string |
|
format: binary |
|
privacy: |
|
$ref: '#/components/schemas/VideoPrivacySet' |
|
category: |
|
$ref: '#/components/schemas/VideoCategorySet' |
|
licence: |
|
$ref: '#/components/schemas/VideoLicenceSet' |
|
language: |
|
$ref: '#/components/schemas/VideoLanguageSet' |
|
description: |
|
description: Live video/replay description |
|
type: string |
|
support: |
|
description: A text tell the audience how to support the creator |
|
example: Please support our work on https://soutenir.framasoft.org/en/ <3 |
|
type: string |
|
nsfw: |
|
description: Whether or not this live video/replay contains sensitive content |
|
type: boolean |
|
name: |
|
description: Live video/replay name |
|
type: string |
|
minLength: 3 |
|
maxLength: 120 |
|
tags: |
|
description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters) |
|
type: array |
|
minItems: 1 |
|
maxItems: 5 |
|
items: |
|
type: string |
|
minLength: 2 |
|
maxLength: 30 |
|
commentsEnabled: |
|
description: Enable or disable comments for this live video/replay |
|
type: boolean |
|
downloadEnabled: |
|
description: Enable or disable downloading for the replay of this live video |
|
type: boolean |
|
required: |
|
- channelId |
|
- name |
|
encoding: |
|
thumbnailfile: |
|
contentType: image/jpeg |
|
previewfile: |
|
contentType: image/jpeg |
|
|
|
/videos/live/{id}: |
|
get: |
|
summary: Get information about a live |
|
operationId: getLiveId |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Live Videos |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/LiveVideoResponse' |
|
put: |
|
summary: Update information about a live |
|
operationId: updateLiveId |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Live Videos |
|
- Video |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/LiveVideoUpdate' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'400': |
|
description: bad parameters or trying to update a live that has already started |
|
'403': |
|
description: trying to save replay of the live but saving replay is not enabled on the instance |
|
|
|
/users/me/abuses: |
|
get: |
|
summary: List my abuses |
|
operationId: getMyAbuses |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Abuses |
|
- My User |
|
parameters: |
|
- name: id |
|
in: query |
|
description: only list the report with this id |
|
schema: |
|
type: integer |
|
- name: state |
|
in: query |
|
schema: |
|
$ref: '#/components/schemas/AbuseStateSet' |
|
- $ref: '#/components/parameters/abusesSort' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Abuse' |
|
|
|
/abuses: |
|
get: |
|
summary: List abuses |
|
operationId: getAbuses |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
tags: |
|
- Abuses |
|
parameters: |
|
- name: id |
|
in: query |
|
description: only list the report with this id |
|
schema: |
|
type: integer |
|
- name: predefinedReason |
|
in: query |
|
description: predefined reason the listed reports should contain |
|
schema: |
|
$ref: '#/components/schemas/PredefinedAbuseReasons' |
|
- name: search |
|
in: query |
|
description: plain search that will match with video titles, reporter names and more |
|
schema: |
|
type: string |
|
- name: state |
|
in: query |
|
schema: |
|
$ref: '#/components/schemas/AbuseStateSet' |
|
- name: searchReporter |
|
in: query |
|
description: only list reports of a specific reporter |
|
schema: |
|
type: string |
|
- name: searchReportee |
|
description: only list reports of a specific reportee |
|
in: query |
|
schema: |
|
type: string |
|
- name: searchVideo |
|
in: query |
|
description: only list reports of a specific video |
|
schema: |
|
type: string |
|
- name: searchVideoChannel |
|
in: query |
|
description: only list reports of a specific video channel |
|
schema: |
|
type: string |
|
- name: videoIs |
|
in: query |
|
description: only list deleted or blocklisted videos |
|
schema: |
|
type: string |
|
enum: |
|
- 'deleted' |
|
- 'blacklisted' |
|
- name: filter |
|
in: query |
|
description: only list account, comment or video reports |
|
schema: |
|
type: string |
|
enum: |
|
- 'video' |
|
- 'comment' |
|
- 'account' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/abusesSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/Abuse' |
|
post: |
|
summary: Report an abuse |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Abuses |
|
requestBody: |
|
required: true |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
reason: |
|
description: Reason why the user reports this video |
|
type: string |
|
minLength: 2 |
|
maxLength: 3000 |
|
predefinedReasons: |
|
$ref: '#/components/schemas/PredefinedAbuseReasons' |
|
video: |
|
type: object |
|
properties: |
|
id: |
|
description: Video id to report |
|
allOf: |
|
- $ref: '#/components/schemas/Video/properties/id' |
|
startAt: |
|
type: integer |
|
format: seconds |
|
description: Timestamp in the video that marks the beginning of the report |
|
minimum: 0 |
|
endAt: |
|
type: integer |
|
format: seconds |
|
description: Timestamp in the video that marks the ending of the report |
|
minimum: 0 |
|
comment: |
|
type: object |
|
properties: |
|
id: |
|
description: Comment id to report |
|
allOf: |
|
- $ref: '#/components/schemas/VideoComment/properties/id' |
|
account: |
|
type: object |
|
properties: |
|
id: |
|
description: Account id to report |
|
type: integer |
|
required: |
|
- reason |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
abuse: |
|
type: object |
|
properties: |
|
id: |
|
$ref: '#/components/schemas/id' |
|
'400': |
|
description: incorrect request parameters |
|
|
|
'/abuses/{abuseId}': |
|
put: |
|
summary: Update an abuse |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
tags: |
|
- Abuses |
|
parameters: |
|
- $ref: '#/components/parameters/abuseId' |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
state: |
|
$ref: '#/components/schemas/AbuseStateSet' |
|
moderationComment: |
|
type: string |
|
description: Update the report comment visible only to the moderation team |
|
minLength: 2 |
|
maxLength: 3000 |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: abuse not found |
|
delete: |
|
tags: |
|
- Abuses |
|
summary: Delete an abuse |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
parameters: |
|
- $ref: '#/components/parameters/abuseId' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: block not found |
|
|
|
'/abuses/{abuseId}/messages': |
|
get: |
|
summary: List messages of an abuse |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Abuses |
|
parameters: |
|
- $ref: '#/components/parameters/abuseId' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/AbuseMessage' |
|
post: |
|
summary: Add message to an abuse |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Abuses |
|
parameters: |
|
- $ref: '#/components/parameters/abuseId' |
|
requestBody: |
|
required: true |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
message: |
|
description: Message to send |
|
type: string |
|
minLength: 2 |
|
maxLength: 3000 |
|
required: |
|
- message |
|
responses: |
|
'200': |
|
description: successful operation |
|
'400': |
|
description: incorrect request parameters |
|
|
|
'/abuses/{abuseId}/messages/{abuseMessageId}': |
|
delete: |
|
summary: Delete an abuse message |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Abuses |
|
parameters: |
|
- $ref: '#/components/parameters/abuseId' |
|
- $ref: '#/components/parameters/abuseMessageId' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
'/videos/{id}/blacklist': |
|
post: |
|
summary: Block a video |
|
operationId: addVideoBlock |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
tags: |
|
- Video Blocks |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
delete: |
|
summary: Unblock a video by its id |
|
operationId: delVideoBlock |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
tags: |
|
- Video Blocks |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: block not found |
|
|
|
/videos/blacklist: |
|
get: |
|
tags: |
|
- Video Blocks |
|
summary: List video blocks |
|
operationId: getVideoBlocks |
|
security: |
|
- OAuth2: |
|
- admin |
|
- moderator |
|
parameters: |
|
- name: type |
|
in: query |
|
description: > |
|
list only blocks that match this type: |
|
|
|
- `1`: manual block |
|
|
|
- `2`: automatic block that needs review |
|
schema: |
|
type: integer |
|
enum: |
|
- 1 |
|
- 2 |
|
- name: search |
|
in: query |
|
description: plain search that will match with video titles, and more |
|
schema: |
|
type: string |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/blacklistsSort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/VideoBlacklist' |
|
|
|
/videos/{id}/captions: |
|
get: |
|
summary: List captions of a video |
|
operationId: getVideoCaptions |
|
tags: |
|
- Video Captions |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
total: |
|
type: integer |
|
example: 1 |
|
data: |
|
type: array |
|
items: |
|
$ref: '#/components/schemas/VideoCaption' |
|
|
|
/videos/{id}/captions/{captionLanguage}: |
|
put: |
|
summary: Add or replace a video caption |
|
operationId: addVideoCaption |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- Video Captions |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
- $ref: '#/components/parameters/captionLanguage' |
|
requestBody: |
|
content: |
|
multipart/form-data: |
|
schema: |
|
type: object |
|
properties: |
|
captionfile: |
|
description: The file to upload. |
|
type: string |
|
format: binary |
|
encoding: |
|
captionfile: |
|
contentType: text/vtt, application/x-subrip, text/plain |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: video or language not found |
|
delete: |
|
summary: Delete a video caption |
|
operationId: delVideoCaption |
|
security: |
|
- OAuth2: |
|
- user |
|
tags: |
|
- Video Captions |
|
parameters: |
|
- $ref: '#/components/parameters/idOrUUID' |
|
- $ref: '#/components/parameters/captionLanguage' |
|
responses: |
|
'204': |
|
description: successful operation |
|
'404': |
|
description: video or language or caption for that language not found |
|
|
|
/video-channels: |
|
get: |
|
summary: List video channels |
|
operationId: getVideoChannels |
|
tags: |
|
- Video Channels |
|
parameters: |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/sort' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannelList' |
|
post: |
|
summary: Create a video channel |
|
operationId: addVideoChannel |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Channels |
|
responses: |
|
'204': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
type: object |
|
properties: |
|
videoChannel: |
|
type: object |
|
properties: |
|
id: |
|
$ref: '#/components/schemas/VideoChannel/properties/id' |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannelCreate' |
|
|
|
'/video-channels/{channelHandle}': |
|
get: |
|
summary: Get a video channel |
|
operationId: getVideoChannel |
|
tags: |
|
- Video Channels |
|
parameters: |
|
- $ref: '#/components/parameters/channelHandle' |
|
responses: |
|
'200': |
|
description: successful operation |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannel' |
|
put: |
|
summary: Update a video channel |
|
operationId: putVideoChannel |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Channels |
|
parameters: |
|
- $ref: '#/components/parameters/channelHandle' |
|
responses: |
|
'204': |
|
description: successful operation |
|
requestBody: |
|
content: |
|
application/json: |
|
schema: |
|
$ref: '#/components/schemas/VideoChannelUpdate' |
|
delete: |
|
summary: Delete a video channel |
|
operationId: delVideoChannel |
|
security: |
|
- OAuth2: [] |
|
tags: |
|
- Video Channels |
|
parameters: |
|
- $ref: '#/components/parameters/channelHandle' |
|
responses: |
|
'204': |
|
description: successful operation |
|
|
|
'/video-channels/{channelHandle}/videos': |
|
get: |
|
summary: List videos of a video channel |
|
operationId: getVideoChannelVideos |
|
tags: |
|
- Video |
|
- Video Channels |
|
parameters: |
|
- $ref: '#/components/parameters/channelHandle' |
|
- $ref: '#/components/parameters/categoryOneOf' |
|
- $ref: '#/components/parameters/isLive' |
|
- $ref: '#/components/parameters/tagsOneOf' |
|
- $ref: '#/components/parameters/tagsAllOf' |
|
- $ref: '#/components/parameters/licenceOneOf' |
|
- $ref: '#/components/parameters/languageOneOf' |
|
- $ref: '#/components/parameters/nsfw' |
|
- $ref: '#/components/parameters/isLocal' |
|
- $ref: '#/components/parameters/include' |
|
- $ref: '#/components/parameters/privacyOneOf' |
|
- $ref: '#/components/parameters/hasHLSFiles' |
|
- $ref: '#/components/parameters/hasWebtorrentFiles' |
|
- $ref: '#/components/parameters/skipCount' |
|
- $ref: '#/components/parameters/start' |
|
- $ref: '#/components/parameters/count' |
|
- $ref: '#/components/parameters/videosSort' |
|