PeerTube/support/doc/api/openapi.yaml

1386 lines
32 KiB
YAML

swagger: '2.0'
info:
title: PeerTube
version: 1.0.0-beta
description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular.
host: peertube.example.com
securityDefinitions:
OAuth2:
description: 'In the header: *Authorization: Bearer mytoken*'
type: oauth2
flow: password
# Not implemented yet
# authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://peertube.example.com/api/v1/users/token
basePath: '/api/v1'
schemes:
- https
paths:
'/accounts/{name}':
get:
tags:
- Accounts
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "accounts.yaml#/parameters/name"
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Account'
'/accounts/{name}/videos':
get:
tags:
- Accounts
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "accounts.yaml#/parameters/name"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Video'
/accounts:
get:
tags:
- Accounts
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Account'
/config:
get:
tags:
- Config
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/ServerConfig'
/feeds/videos.{format}:
get:
tags:
- Feeds
produces:
- application/atom+xml
- application/rss+xml
- application/json
parameters:
- name: format
in: path
required: true
type: string
enum: [ 'xml', 'atom', 'json']
default: 'xml'
description: 'The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and json to JSON FEED 1.0'
- name: accountId
in: query
required: false
type: number
description: 'The id of the local account to filter to (beware, users IDs and not actors IDs which will return empty feeds'
- name: accountName
in: query
required: false
type: string
description: 'The name of the local account to filter to'
responses:
'200':
description: successful operation
/jobs:
get:
security:
- OAuth2: [ ]
tags:
- Job
consumes:
- application/json
produces:
- application/json
parameters:
- name: state
in: path
required: true
type: string
description: 'The state of the job'
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Job'
'/server/following/{host}':
delete:
security:
- OAuth2: [ ]
tags:
- ServerFollowing
consumes:
- application/json
produces:
- application/json
parameters:
- name: host
in: path
required: true
type: string
description: 'The host to unfollow '
responses:
'201':
description: successful operation
/server/followers:
get:
tags:
- ServerFollowing
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Follow'
/server/following:
get:
tags:
- ServerFollowing
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Follow'
post:
security:
- OAuth2: [ ]
tags:
- ServerFollowing
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
schema:
$ref: '#/definitions/Follow'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/users:
post:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: true
description: 'User to create'
schema:
$ref: '#/definitions/AddUser'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/AddUserResponse'
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/User'
'/users/{id}':
delete:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "users.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "users.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/User'
put:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "users.yaml#/parameters/id"
- in: body
name: body
required: true
schema:
$ref: '#/definitions/UpdateUser'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/users/me:
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/User'
put:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: true
schema:
$ref: '#/definitions/UpdateMe'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/users/me/video-quota-used:
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters: []
responses:
'200':
description: successful operation
schema:
type: number
'/users/me/videos/{videoId}/rating':
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- name: videoId
in: path
required: true
type: string
description: 'The video id '
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/GetMeVideoRating'
/users/me/videos:
get:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Video'
/users/register:
post:
tags:
- User
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: true
schema:
$ref: '#/definitions/RegisterUser'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/users/me/avatar/pick:
post:
security:
- OAuth2: [ ]
tags:
- User
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- in: formData
name: avatarfile
type: file
description: The file to upload.
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Avatar'
/videos:
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
parameters:
- name: category
in: query
required: false
type: number
description: category id of the video
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Video'
/videos/categories:
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
type: string
/videos/licences:
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
type: string
/videos/languages:
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
type: string
/videos/privacies:
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: successful operation
schema:
type: array
items:
type: string
"/videos/{id}":
put:
security:
- OAuth2: [ ]
tags:
- Video
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
- $ref: "videos.yaml#/parameters/thumbnailfile"
- $ref: "videos.yaml#/parameters/previewfile"
- $ref: "videos.yaml#/parameters/category"
- $ref: "videos.yaml#/parameters/licence"
- $ref: "videos.yaml#/parameters/language"
- $ref: "videos.yaml#/parameters/description"
- $ref: "videos.yaml#/parameters/waitTranscoding"
- $ref: "videos.yaml#/parameters/support"
- $ref: "videos.yaml#/parameters/nsfw"
- $ref: "videos.yaml#/parameters/name"
- $ref: "videos.yaml#/parameters/tags"
- $ref: "videos.yaml#/parameters/commentsEnabled"
- $ref: "videos.yaml#/parameters/privacy"
- $ref: "videos.yaml#/parameters/scheduleUpdate"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Video'
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Video'
delete:
security:
- OAuth2: [ ]
tags:
- Video
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
"/videos/{id}/description":
get:
tags:
- Video
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
type: string
"/videos/{id}/views":
post:
tags:
- Video
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/videos/upload:
post:
security:
- OAuth2: [ ]
tags:
- Video
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: videofile
in: formData
type: file
required: true
description: 'Video file'
- name: channelId
in: formData
required: true
type: number
description: 'Channel id that will contain this video'
- $ref: "videos.yaml#/parameters/thumbnailfile"
- $ref: "videos.yaml#/parameters/previewfile"
- $ref: "videos.yaml#/parameters/category"
- $ref: "videos.yaml#/parameters/licence"
- $ref: "videos.yaml#/parameters/language"
- $ref: "videos.yaml#/parameters/description"
- $ref: "videos.yaml#/parameters/waitTranscoding"
- $ref: "videos.yaml#/parameters/support"
- $ref: "videos.yaml#/parameters/nsfw"
- $ref: "videos.yaml#/parameters/name"
- $ref: "videos.yaml#/parameters/tags"
- $ref: "videos.yaml#/parameters/commentsEnabled"
- $ref: "videos.yaml#/parameters/privacy"
- $ref: "videos.yaml#/parameters/scheduleUpdate"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/VideoUploadResponse'
/videos/abuse:
get:
security:
- OAuth2: [ ]
tags:
- VideoAbuse
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/VideoAbuse'
"/videos/{id}/abuse":
post:
security:
- OAuth2: [ ]
tags:
- VideoAbuse
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
"/videos/{id}/blacklist":
post:
security:
- OAuth2: [ ]
tags:
- VideoBlacklist
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
delete:
security:
- OAuth2: [ ]
tags:
- VideoBlacklist
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/videos/blacklist:
get:
security:
- OAuth2: [ ]
tags:
- VideoBlacklist
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/VideoBlacklist'
/video-channels:
get:
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/VideoChannel'
post:
security:
- OAuth2: [ ]
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
schema:
$ref: '#/definitions/VideoChannelInput'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
"/video-channels/{id}":
get:
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "video-channels.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/VideoChannel'
put:
security:
- OAuth2: [ ]
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "video-channels.yaml#/parameters/id"
- in: body
name: body
schema:
$ref: '#/definitions/VideoChannelInput'
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
delete:
security:
- OAuth2: [ ]
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "video-channels.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
"/video-channels/{id}/videos":
get:
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "video-channels.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Video'
/accounts/{name}/video-channels:
get:
tags:
- VideoChannel
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "accounts.yaml#/parameters/name"
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/VideoChannel'
"/videos/{id}/comment-threads":
get:
tags:
- VideoComment
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/CommentThreadResponse'
post:
security:
- OAuth2: [ ]
tags:
- VideoComment
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/CommentThreadPostResponse'
"/videos/{id}/comment-threads/{threadId}":
get:
tags:
- VideoComment
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
- $ref: "video-comments.yaml#/parameters/threadId"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/VideoCommentThreadTree'
"/videos/{id}/comments/{commentId}":
post:
security:
- OAuth2: [ ]
tags:
- VideoComment
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
- $ref: "video-comments.yaml#/parameters/commentId"
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/CommentThreadPostResponse'
delete:
security:
- OAuth2: [ ]
tags:
- VideoComment
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
- $ref: "video-comments.yaml#/parameters/commentId"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
"/videos/{id}/rate":
put:
security:
- OAuth2: [ ]
tags:
- VideoRate
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "videos.yaml#/parameters/id"
responses:
'204':
$ref: "commons.yaml#/responses/emptySuccess"
/search/videos:
get:
tags:
- Search
consumes:
- application/json
produces:
- application/json
parameters:
- $ref: "commons.yaml#/parameters/start"
- $ref: "commons.yaml#/parameters/count"
- $ref: "commons.yaml#/parameters/sort"
- name: search
in: query
required: true
type: string
description: 'String to search'
responses:
'200':
description: successful operation
schema:
type: array
items:
$ref: '#/definitions/Video'
definitions:
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: "#/definitions/VideoConstantNumber"
licence:
$ref: "#/definitions/VideoConstantNumber"
language:
$ref: "#/definitions/VideoConstantString"
privacy:
$ref: "#/definitions/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: "#/definitions/Avatar"
VideoAbuse:
properties:
id:
type: number
reason:
type: string
reporterAccount:
$ref: "#/definitions/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: "#/definitions/Account"
VideoCommentThreadTree:
properties:
comment:
$ref: "#/definitions/VideoComment"
children:
type: array
items:
$ref: "#/definitions/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: "#/definitions/Avatar"
Account:
allOf:
- $ref: "#/definitions/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: "#/definitions/Account"
videoChannels:
type: array
items:
$ref: "#/definitions/VideoChannel"
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: "#/definitions/Actor"
following:
$ref: "#/definitions/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
# Api responses
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: "#/definitions/VideoComment"
CommentThreadPostResponse:
properties:
comment:
$ref: "#/definitions/VideoComment"
# Request bodies
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: string
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