PeerTube/support/doc/api/openapi.yaml

2167 lines
57 KiB
YAML
Raw Normal View History

openapi: 3.0.0
info:
2018-01-24 11:54:32 +01:00
title: PeerTube
2019-02-14 12:41:55 +01:00
version: 1.2.1
2018-11-13 23:27:58 +01:00
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
2018-11-13 23:27:58 +01:00
description: |
# Introduction
The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
resource URLs. It returns HTTP response codes to indicate errors. It also
accepts and returns JSON in the HTTP body. You can use your favorite
HTTP/REST library for your programming language to use PeerTube. No official
SDK is currently provided, but 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.
2018-11-13 23:27:58 +01:00
# Authentication
When you sign up for an account, you are given the possibility to generate
sessions, and authenticate using this session token. One session token can
2018-11-13 23:27:58 +01:00
currently be used at a time.
# Errors
The API uses standard HTTP status codes to indicate the success or failure
of the API call. The body of the response will be JSON in the following
format.
```
{
"code": "unauthorized_request", // example inner error code
"error": "Token is invalid." // example exposed error message
}
```
externalDocs:
url: https://docs.joinpeertube.org/api.html
2018-11-13 23:27:58 +01:00
tags:
- name: Accounts
description: >
2018-11-13 23:27:58 +01:00
Using some features of PeerTube require authentication, for which Accounts
provide different levels of permission as well as associated user
information. Accounts also encompass remote accounts discovered across the federation.
2018-11-13 23:27:58 +01:00
- name: Config
description: >
Each server exposes public information regarding supported videos and
options.
2018-11-13 23:27:58 +01:00
- name: Feeds
description: |
Feeds of videos and feeds of comments allow to see updates and get them in
an aggregator or script of your choice.
- name: Job
description: >
Jobs are long-running tasks enqueued and processed by the instance
itself. No additional worker registration is currently available.
- name: Server Following
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
2018-11-13 23:27:58 +01:00
information across its social graph by posting activities to actors' inbox
endpoints.
- name: Video Abuse
2018-11-13 23:27:58 +01:00
description: |
Video abuses deal with reports of local or remote videos alike.
- name: Video
description: |
Operations dealing with listing, uploading, fetching or modifying videos.
- name: Search
description: |
The search helps to find _videos_ 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.
- name: Video Comment
description: >
Operations dealing with comments to a video. Comments are organized in
threads.
- name: Video Channel
description: >
Operations dealing with creation, modification and video listing of a
user's channels.
- name: Video Blacklist
description: >
Operations dealing with blacklisting videos (removing them from view and
preventing interactions).
- name: Video Rate
description: >
Voting for a video.
x-tagGroups:
- name: Accounts
tags:
- Accounts
- User
- name: Videos
tags:
- Video
- Video Channel
- Video Comment
- Video Following
- Video Rate
- name: Moderation
tags:
2018-11-17 15:17:33 +01:00
- Video Abuse
- Video Blacklist
- name: Instance Configuration
tags:
- Config
- Server Following
- name: Notifications
tags:
- Feeds
- name: Jobs
tags:
- Job
- name: Search
tags:
- Search
paths:
2018-05-25 09:57:16 +02:00
'/accounts/{name}':
get:
tags:
- Accounts
2018-11-13 23:27:58 +01:00
summary: Get the account by name
parameters:
- $ref: '#/components/parameters/name'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
2018-05-25 09:57:16 +02:00
'/accounts/{name}/videos':
2018-04-25 10:21:38 +02:00
get:
tags:
- Accounts
2018-11-13 23:27:58 +01:00
- Video
summary: 'Get videos for an account, provided the name of that account'
2018-04-25 10:21:38 +02:00
parameters:
- $ref: '#/components/parameters/name'
2018-04-25 10:21:38 +02:00
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
2018-11-13 23:27:58 +01:00
x-code-samples:
- lang: JavaScript
source: |
fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
2018-11-13 23:27:58 +01:00
.then(function(response) {
return response.json()
}).then(function(data) {
console.log(data)
})
- lang: Shell
source: |
# pip install httpie
http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
- lang: Ruby
source: |
require 'uri'
require 'net/http'
url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
response = http.request(request)
puts response.read_body
- lang: Python
source: |
import http.client
conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
headers = {
'content-type': "application/json"
}
conn.request("POST", "/accounts/{name}/videos", None, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
/accounts:
get:
tags:
- Accounts
2018-11-13 23:27:58 +01:00
summary: Get all accounts
responses:
'200':
description: successful operation
content:
'application/json':
schema:
type: array
items:
$ref: '#/components/schemas/Account'
/config:
get:
tags:
- Config
summary: Get the public configuration of the server
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ServerConfig'
/config/about:
get:
summary: Get the instance about page content
tags:
- Config
responses:
'200':
description: successful operation
/config/custom:
get:
summary: Get the runtime configuration of the server
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
put:
summary: Set the runtime configuration of the server
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
delete:
summary: Delete the runtime configuration of the server
tags:
- Config
security:
- OAuth2:
- admin
responses:
'200':
description: successful operation
'/feeds/videos.{format}':
get:
summary: >-
Get the feed of videos for the server, with optional filter by account
name or id
tags:
- Feeds
parameters:
- name: format
in: path
required: true
description: >-
The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
json to JSON FEED 1.0
schema:
type: string
enum:
- xml
- atom
- json
default: xml
- name: accountId
in: query
required: false
description: >-
The id of the local account to filter to (beware, users IDs and not
actors IDs which will return empty feeds
schema:
type: number
- name: accountName
in: query
required: false
description: The name of the local account to filter to
schema:
type: string
responses:
'200':
description: successful operation
2018-11-19 22:10:35 +01:00
/jobs/{state}:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of jobs
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
tags:
- Job
parameters:
- name: state
in: path
required: true
description: The state of the job
schema:
type: string
enum:
- active
- completed
- failed
- waiting
- delayed
- $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/Job'
'/server/following/{host}':
delete:
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
tags:
- Server Following
2018-11-13 23:27:58 +01:00
summary: Unfollow a server by hostname
parameters:
- name: host
in: path
required: true
description: 'The host to unfollow '
schema:
type: string
responses:
'201':
description: successful operation
/server/followers:
get:
tags:
- Server Following
2018-11-13 23:27:58 +01:00
summary: Get followers of the server
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/Follow'
/server/following:
get:
tags:
- Server Following
2018-11-13 23:27:58 +01:00
summary: Get servers followed by the server
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/Follow'
post:
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
tags:
- Server Following
2018-11-13 23:27:58 +01:00
summary: Follow a server
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Follow'
/users:
post:
2018-11-13 23:27:58 +01:00
summary: Creates user
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
tags:
- User
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AddUserResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddUser'
description: User to create
required: true
get:
2018-11-13 23:27:58 +01:00
summary: Get a list of users
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- User
parameters:
- $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}':
delete:
2018-11-13 23:27:58 +01:00
summary: Delete a user by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
tags:
- User
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
get:
2018-11-13 23:27:58 +01:00
summary: Get user by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- User
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
2018-11-13 23:27:58 +01:00
summary: Update user profile by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- User
parameters:
- $ref: '#/components/parameters/id'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
required: true
/users/me:
get:
2018-11-13 23:27:58 +01:00
summary: Get current user information
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- user
tags:
- User
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
put:
2018-11-13 23:27:58 +01:00
summary: Update current user information
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- user
tags:
- User
responses:
'204':
description: Successful operation
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMe'
required: true
/users/me/video-quota-used:
get:
2018-11-13 23:27:58 +01:00
summary: Get current user used quota
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- user
tags:
- User
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: number
'/users/me/videos/{videoId}/rating':
get:
summary: 'Get rating of video by its id, among those of the current user'
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- User
parameters:
- name: videoId
in: path
required: true
description: 'The video id '
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/GetMeVideoRating'
/users/me/videos:
get:
2018-11-13 23:27:58 +01:00
summary: Get videos of the current user
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- user
tags:
- User
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/Video'
/users/me/subscriptions:
get:
summary: Get subscriptions of the current user
security:
- OAuth2:
- user
tags:
- User
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
post:
summary: Add subscription to the current user
security:
- OAuth2:
- user
tags:
- User
responses:
'200':
description: successful operation
/users/me/subscriptions/exist:
get:
summary: Get if subscriptions exist for the current user
security:
- OAuth2:
- user
tags:
- User
parameters:
- $ref: '#/components/parameters/subscriptionsUris'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
/users/me/subscriptions/videos:
get:
summary: Get videos of subscriptions of the current user
security:
- OAuth2:
- user
tags:
- User
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/Video'
'/users/me/subscriptions/{uri}':
get:
summary: Get subscription of the current user for a given uri
security:
- OAuth2:
- user
tags:
- User
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoChannel'
delete:
summary: Delete subscription of the current user for a given uri
security:
- OAuth2:
- user
tags:
- User
responses:
'200':
description: successful operation
/users/register:
post:
2018-11-13 23:27:58 +01:00
summary: Register a user
tags:
- User
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegisterUser'
required: true
/users/me/avatar/pick:
post:
2018-11-13 23:27:58 +01:00
summary: Update current user avatar
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- User
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
avatarfile:
description: The file to upload.
type: string
format: binary
encoding:
profileImage:
# only accept png/jpeg
contentType: image/png, image/jpeg
/videos:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of videos
tags:
- Video
parameters:
- $ref: '#/components/parameters/categoryOneOf'
- $ref: '#/components/parameters/tagsOneOf'
- $ref: '#/components/parameters/tagsAllOf'
- $ref: '#/components/parameters/licenceOneOf'
- $ref: '#/components/parameters/languageOneOf'
- $ref: '#/components/parameters/nsfw'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/videosSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Video'
/videos/categories:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of video licences known by the server
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
/videos/licences:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of video licences known by the server
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
/videos/languages:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of languages known by the server
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
/videos/privacies:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of privacy policies supported by the server
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
type: string
'/videos/{id}':
put:
2018-11-13 23:27:58 +01:00
summary: Update metadata for a video by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video
parameters:
- $ref: '#/components/parameters/id2'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
thumbnailfile:
description: Video thumbnail file
type: string
previewfile:
description: Video preview file
type: string
category:
description: Video category
type: string
licence:
description: Video licence
type: string
language:
description: Video language
type: string
description:
description: Video description
type: string
waitTranscoding:
description: Whether or not we wait transcoding before publish the video
type: string
support:
description: Text describing how to support the video uploader
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: string
name:
description: Video name
type: string
tags:
description: Video tags (maximum 5 tags each between 2 and 30 characters)
type: array
items:
type: string
commentsEnabled:
description: Enable or disable comments for this video
type: string
scheduleUpdate: &ref_0
type: object
properties:
privacy:
type: string
enum:
- Public
- Unlisted
description: Video privacy target
updateAt:
type: string
format: date
description: When to update the video
required:
- updateAt
get:
2018-11-13 23:27:58 +01:00
summary: Get a video by its id
tags:
- Video
parameters:
- $ref: '#/components/parameters/id2'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
delete:
2018-11-13 23:27:58 +01:00
summary: Delete a video by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/{id}/description':
get:
2018-11-13 23:27:58 +01:00
summary: Get a video description by its id
tags:
- Video
parameters:
- $ref: '#/components/parameters/id2'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: string
'/videos/{id}/views':
post:
2018-11-13 23:27:58 +01:00
summary: Add a view to the video by its id
tags:
- Video
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/{id}/watching':
put:
summary: Set watching progress of a video by its id for a user
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/id2'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserWatchingVideo'
required: true
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
/videos/ownership:
get:
summary: Get list of video ownership changes requests
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/id2'
responses:
'200':
description: successful operation
'/videos/ownership/{id}/accept':
post:
summary: Refuse ownership change request for video by its id
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/ownership/{id}/refuse':
post:
summary: Accept ownership change request for video by its id
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/{id}/give-ownership':
post:
summary: Request change of ownership for a video you own, by its id
tags:
- Video
security:
- OAuth2: []
parameters:
- $ref: '#/components/parameters/id2'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
username:
type: string
required:
- username
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'400':
description: 'Changing video ownership to a remote account is not supported yet'
/videos/upload:
post:
2018-11-13 23:27:58 +01:00
summary: Upload a video file with its metadata
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
videofile:
description: Video file
type: string
format: binary
channelId:
description: Channel id that will contain this video
type: number
thumbnailfile:
description: Video thumbnail file
type: string
previewfile:
description: Video preview file
type: string
privacy:
$ref: '#/components/schemas/VideoPrivacy'
category:
description: Video category
type: string
licence:
description: Video licence
type: string
language:
description: Video language
type: string
description:
description: Video description
type: string
waitTranscoding:
description: Whether or not we wait transcoding before publish the video
type: string
support:
description: Text describing how to support the video uploader
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: string
name:
description: Video name
type: string
tags:
description: Video tags
type: array
items:
type: string
commentsEnabled:
description: Enable or disable comments for this video
type: string
scheduleUpdate: *ref_0
required:
- videofile
- channelId
- name
x-code-samples:
- lang: Shell
source: |
## DEPENDENCIES: httpie, jq
# pip install httpie
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
CHANNEL_ID="<your_channel_id>"
NAME="<video_name>"
API_PATH="https://peertube2.cpy.re/api/v1"
## AUTH
client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
token=$(http -b --form POST "$API_PATH/users/token" \
client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
username=$USERNAME \
password=$PASSWORD \
| jq -r ".access_token")
## VIDEO UPLOAD
http -b --form POST "$API_PATH/videos/upload" \
videofile@$FILE_PATH \
channelId=$CHANNEL_ID \
name=$NAME \
"Authorization:Bearer $token"
2019-02-19 17:56:09 +01:00
/videos/imports:
post:
summary: Import a torrent or magnetURI or HTTP ressource (if enabled by the instance administrator)
security:
- OAuth2: []
tags:
- Video
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
torrentfile:
description: Torrent File
type: string
format: binary
targetUrl:
description: HTTP target URL
type: string
magnetUri:
description: Magnet URI
type: string
channelId:
description: Channel id that will contain this video
type: number
thumbnailfile:
description: Video thumbnail file
type: string
previewfile:
description: Video preview file
type: string
privacy:
$ref: '#/components/schemas/VideoPrivacy'
category:
description: Video category
type: string
licence:
description: Video licence
type: string
language:
description: Video language
type: string
description:
description: Video description
type: string
waitTranscoding:
description: Whether or not we wait transcoding before publish the video
type: string
support:
description: Text describing how to support the video uploader
type: string
nsfw:
description: Whether or not this video contains sensitive content
type: string
name:
description: Video name
type: string
tags:
description: Video tags
type: array
items:
type: string
commentsEnabled:
description: Enable or disable comments for this video
type: string
scheduleUpdate: *ref_0
required:
- channelId
- name
/videos/abuse:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of reported video abuses
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Abuse
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/abusesSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VideoAbuse'
'/videos/{id}/abuse':
post:
summary: 'Report an abuse, on a video by its id'
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Abuse
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/{id}/blacklist':
post:
2018-11-13 23:27:58 +01:00
summary: Put on blacklist a video by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
- moderator
tags:
- Video Blacklist
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
delete:
2018-11-13 23:27:58 +01:00
summary: Delete an entry of the blacklist of a video by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
- moderator
tags:
- Video Blacklist
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
/videos/blacklist:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of videos on blacklist
2018-04-16 10:48:17 +02:00
security:
- OAuth2:
- admin
- moderator
tags:
- Video Blacklist
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/blacklistsSort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VideoBlacklist'
2018-04-24 17:05:32 +02:00
/video-channels:
get:
2018-11-13 23:27:58 +01:00
summary: Get list of video channels
tags:
- Video Channel
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/VideoChannel'
post:
2018-11-13 23:27:58 +01:00
summary: Creates a video channel for the current user
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Channel
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
requestBody:
$ref: '#/components/requestBodies/VideoChannelInput'
'/video-channels/{id}':
get:
2018-11-13 23:27:58 +01:00
summary: Get a video channel by its id
tags:
- Video Channel
parameters:
- $ref: '#/components/parameters/id3'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoChannel'
put:
2018-11-13 23:27:58 +01:00
summary: Update a video channel by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Channel
parameters:
- $ref: '#/components/parameters/id3'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
requestBody:
$ref: '#/components/requestBodies/VideoChannelInput'
delete:
2018-11-13 23:27:58 +01:00
summary: Delete a video channel by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Channel
parameters:
- $ref: '#/components/parameters/id3'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/video-channels/{id}/videos':
get:
2018-11-13 23:27:58 +01:00
summary: Get videos of a video channel by its id
tags:
- Video Channel
parameters:
- $ref: '#/components/parameters/id3'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Video'
'/accounts/{name}/video-channels':
2018-04-25 10:21:38 +02:00
get:
2018-11-13 23:27:58 +01:00
summary: Get video channels of an account by its name
2018-04-25 10:21:38 +02:00
tags:
- Video Channel
2018-04-25 10:21:38 +02:00
parameters:
- $ref: '#/components/parameters/name'
2018-04-25 10:21:38 +02:00
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VideoChannel'
'/videos/{id}/comment-threads':
get:
2018-11-13 23:27:58 +01:00
summary: Get the comment threads of a video by its id
tags:
- Video Comment
parameters:
- $ref: '#/components/parameters/id2'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadResponse'
post:
summary: 'Creates a comment thread, on a video by its id'
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Comment
parameters:
- $ref: '#/components/parameters/id2'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
'/videos/{id}/comment-threads/{threadId}':
get:
summary: 'Get the comment thread by its id, of a video by its id'
tags:
- Video Comment
parameters:
- $ref: '#/components/parameters/id2'
- name: threadId
in: path
required: true
description: The thread id (root comment id)
schema:
type: number
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/VideoCommentThreadTree'
'/videos/{id}/comments/{commentId}':
post:
summary: 'Creates a comment in a comment thread by its id, of a video by its id'
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Comment
parameters:
- $ref: '#/components/parameters/id2'
- $ref: '#/components/parameters/commentId'
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
delete:
summary: 'Delete a comment in a comment therad by its id, of a video by its id'
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Comment
parameters:
- $ref: '#/components/parameters/id2'
- $ref: '#/components/parameters/commentId'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
'/videos/{id}/rate':
put:
2018-11-13 23:27:58 +01:00
summary: Vote for a video by its id
2018-04-16 10:48:17 +02:00
security:
- OAuth2: []
tags:
- Video Rate
parameters:
- $ref: '#/components/parameters/id2'
responses:
'204':
$ref: '#/paths/~1users~1me/put/responses/204'
/search/videos:
get:
tags:
- Search
2018-11-13 23:27:58 +01:00
summary: Get the videos corresponding to a given query
parameters:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/videosSearchSort'
- name: search
in: query
required: true
description: String to search
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Video'
servers:
- url: 'https://peertube.cpy.re/api/v1'
description: Live Test Server (live data - stable version)
- url: 'https://peertube2.cpy.re/api/v1'
description: Live Test Server (live data - bleeding edge version)
- url: 'https://peertube3.cpy.re/api/v1'
description: Live Test Server (live data - bleeding edge version)
components:
parameters:
start:
name: start
in: query
required: false
description: Offset
schema:
type: number
count:
name: count
in: query
required: false
description: Number of items
schema:
type: number
sort:
name: sort
in: query
required: false
description: Sort column (-createdAt for example)
schema:
type: string
videosSort:
name: sort
in: query
required: false
description: Sort videos by criteria
schema:
type: string
enum:
- -name
- -duration
- -createdAt
- -publishedAt
- -views
- -likes
- -trending
videosSearchSort:
name: sort
in: query
required: false
description: Sort videos by criteria
schema:
type: string
enum:
- -name
- -duration
- -createdAt
- -publishedAt
- -views
- -likes
- -match
blacklistsSort:
name: sort
in: query
required: false
description: Sort blacklists by criteria
schema:
type: string
enum:
- -id
- -name
- -duration
- -views
- -likes
- -dislikes
- -uuid
- -createdAt
usersSort:
name: sort
in: query
required: false
description: Sort users by criteria
schema:
type: string
enum:
- -id
- -username
- -createdAt
abusesSort:
name: sort
in: query
required: false
description: Sort abuses by criteria
schema:
type: string
enum:
- -id
- -createdAt
- -state
name:
name: name
in: path
required: true
description: >-
The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
example)
schema:
type: string
id:
name: id
in: path
required: true
description: The user id
schema:
type: number
id2:
name: id
in: path
required: true
description: The video id or uuid
schema:
type: string
id3:
name: id
in: path
required: true
description: The video channel id or uuid
schema:
type: string
commentId:
name: threadId
in: path
required: true
description: The comment id
schema:
type: number
categoryOneOf:
name: categoryOneOf
in: query
required: false
description: category id of the video
schema:
oneOf:
- type: number
- type: array
items:
type: number
style: form
explode: false
tagsOneOf:
name: tagsOneOf
in: query
required: false
description: tag(s) of the video
schema:
oneOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
tagsAllOf:
name: tagsAllOf
in: query
required: false
description: tag(s) of the video, where all should be present in the video
schema:
oneOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
languageOneOf:
name: languageOneOf
in: query
required: false
description: language id of the video
schema:
oneOf:
- type: string
- type: array
items:
type: string
style: form
explode: false
licenceOneOf:
name: licenceOneOf
in: query
required: false
description: licence id of the video
schema:
oneOf:
- type: number
- type: array
items:
type: number
style: form
explode: false
nsfw:
name: nsfw
in: query
required: false
description: whether to include nsfw videos, if any
schema:
type: string
enum:
- 'true'
- 'false'
filter:
name: filter
in: query
required: false
description: >
Special filters (local for instance) which might require special rights:
* `local` - only videos local to the instance
* `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
schema:
type: string
enum:
- local
- all-local
subscriptionsUris:
name: uris
in: query
required: true
description: list of uris to check if each is part of the user subscriptions
schema:
type: array
items:
type: string
requestBodies:
VideoChannelInput:
content:
application/json:
schema:
$ref: '#/components/schemas/VideoChannelInput'
securitySchemes:
OAuth2:
description: >
In the header: *Authorization: Bearer <token\>*
Authenticating via OAuth requires the following steps:
- Have an account with sufficient authorization levels
- [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
Bearer Token
- Make Authenticated Requests
type: oauth2
flows:
password:
tokenUrl: 'https://peertube.example.com/api/v1/users/token'
scopes:
admin: Admin scope
moderator: Moderator scope
user: User scope
schemas:
VideoConstantNumber:
properties:
id:
type: number
label:
type: string
VideoConstantString:
properties:
id:
type: string
label:
type: string
VideoPrivacy:
type: string
enum:
- Public
- Unlisted
- Private
Video:
properties:
id:
type: number
uuid:
type: string
createdAt:
type: string
publishedAt:
type: string
updatedAt:
type: string
category:
$ref: '#/components/schemas/VideoConstantNumber'
licence:
$ref: '#/components/schemas/VideoConstantNumber'
language:
$ref: '#/components/schemas/VideoConstantString'
privacy:
$ref: '#/components/schemas/VideoPrivacy'
description:
type: string
duration:
type: number
isLocal:
type: boolean
name:
type: string
thumbnailPath:
type: string
previewPath:
type: string
embedPath:
type: string
views:
type: number
likes:
type: number
dislikes:
type: number
nsfw:
type: boolean
account:
type: object
properties:
name:
type: string
displayName:
type: string
url:
type: string
host:
type: string
avatar:
$ref: '#/components/schemas/Avatar'
VideoAbuse:
properties:
id:
type: number
reason:
type: string
reporterAccount:
$ref: '#/components/schemas/Account'
video:
type: object
properties:
id:
type: number
name:
type: string
uuid:
type: string
url:
type: string
createdAt:
type: string
VideoBlacklist:
properties:
id:
type: number
videoId:
type: number
createdAt:
type: string
updatedAt:
type: string
name:
type: string
uuid:
type: string
description:
type: string
duration:
type: number
views:
type: number
likes:
type: number
dislikes:
type: number
nsfw:
type: boolean
VideoChannel:
properties:
displayName:
type: string
description:
type: string
isLocal:
type: boolean
ownerAccount:
type: object
properties:
id:
type: number
uuid:
type: string
VideoComment:
properties:
id:
type: number
url:
type: string
text:
type: string
threadId:
type: number
inReplyToCommentId:
type: number
videoId:
type: number
createdAt:
type: string
updatedAt:
type: string
totalReplies:
type: number
account:
$ref: '#/components/schemas/Account'
VideoCommentThreadTree:
properties:
comment:
$ref: '#/components/schemas/VideoComment'
children:
type: array
items:
$ref: '#/components/schemas/VideoCommentThreadTree'
Avatar:
properties:
path:
type: string
createdAt:
type: string
updatedAt:
type: string
Actor:
properties:
id:
type: number
uuid:
type: string
url:
type: string
name:
type: string
host:
type: string
followingCount:
type: number
followersCount:
type: number
createdAt:
type: string
updatedAt:
type: string
avatar:
$ref: '#/components/schemas/Avatar'
Account:
allOf:
- $ref: '#/components/schemas/Actor'
- properties:
displayName:
type: string
User:
properties:
id:
type: number
username:
type: string
email:
type: string
displayNSFW:
type: boolean
autoPlayVideo:
type: boolean
role:
type: string
enum:
- User
- Moderator
- Administrator
videoQuota:
type: number
createdAt:
type: string
account:
$ref: '#/components/schemas/Account'
videoChannels:
type: array
items:
$ref: '#/components/schemas/VideoChannel'
UserWatchingVideo:
properties:
currentTime:
type: number
ServerConfig:
properties:
signup:
type: object
properties:
allowed:
type: boolean
transcoding:
type: object
properties:
enabledResolutions:
type: array
items:
type: number
avatar:
type: object
properties:
file:
type: object
properties:
size:
type: object
properties:
max:
type: number
extensions:
type: array
items:
type: string
video:
type: object
properties:
file:
type: object
properties:
extensions:
type: array
items:
type: string
Follow:
properties:
id:
type: number
follower:
$ref: '#/components/schemas/Actor'
following:
$ref: '#/components/schemas/Actor'
score:
type: number
state:
type: string
enum:
- pending
- accepted
createdAt:
type: string
updatedAt:
type: string
Job:
properties:
id:
type: number
state:
type: string
enum:
- pending
- processing
- error
- success
category:
type: string
enum:
- transcoding
- activitypub-http
handlerName:
type: string
handlerInputData:
type: string
createdAt:
type: string
updatedAt:
type: string
AddUserResponse:
properties:
id:
type: number
uuid:
type: string
VideoUploadResponse:
properties:
video:
type: object
properties:
id:
type: number
uuid:
type: string
CommentThreadResponse:
properties:
total:
type: number
data:
type: array
items:
$ref: '#/components/schemas/VideoComment'
CommentThreadPostResponse:
properties:
comment:
$ref: '#/components/schemas/VideoComment'
AddUser:
properties:
username:
type: string
description: 'The user username '
password:
type: string
description: 'The user password '
email:
type: string
description: 'The user email '
videoQuota:
type: string
description: 'The user videoQuota '
role:
type: integer
format: int32
enum:
- 0
- 1
- 2
description: 'The user role '
required:
- username
- password
- email
- videoQuota
- role
UpdateUser:
properties:
id:
type: string
description: 'The user id '
email:
type: string
description: 'The updated email of the user '
videoQuota:
type: string
description: 'The updated videoQuota of the user '
role:
type: string
description: 'The updated role of the user '
required:
- id
- email
- videoQuota
- role
UpdateMe:
properties:
password:
type: string
description: 'Your new password '
email:
type: string
description: 'Your new email '
displayNSFW:
type: string
description: 'Your new displayNSFW '
autoPlayVideo:
type: string
description: 'Your new autoPlayVideo '
required:
- password
- email
- displayNSFW
- autoPlayVideo
GetMeVideoRating:
properties:
id:
type: string
description: 'Id of the video '
rating:
type: number
description: 'Rating of the video '
required:
- id
- rating
RegisterUser:
properties:
username:
type: string
description: 'The username of the user '
password:
type: string
description: 'The password of the user '
email:
type: string
description: 'The email of the user '
required:
- username
- password
- email
VideoChannelInput:
properties:
name:
type: string
description:
type: string