openapi: 3.0.0
info:
title: PeerTube
- version: 2.2.0
+ version: 2.3.0
contact:
name: PeerTube Community
url: 'https://joinpeertube.org'
tags:
- name: Accounts
description: >
- Accounts encompass remote accounts discovered across the federation,
+ 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.
Managing plugins installed from a local path or from NPM, or search for new ones.
externalDocs:
url: https://docs.joinpeertube.org/#/api-plugins
- - name: Video Abuses
+ - name: Abuses
description: |
- Video abuses deal with reports of local or remote videos alike.
+ Abuses deal with reports of local or remote videos/comments/accounts alike.
- name: Video
description: |
Operations dealing with listing, uploading, fetching or modifying videos.
- Search
- name: Moderation
tags:
- - Video Abuses
+ - Abuses
- Video Blocks
- Account Blocks
- Server Blocks
})
- lang: Shell
source: |
- # pip install httpie
- http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
+ ## DEPENDENCIES: jq
+ curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
- lang: Ruby
source: |
require 'net/http'
- Users
responses:
'200':
- description: successful operation
+ description: user created
content:
application/json:
schema:
$ref: '#/components/schemas/AddUserResponse'
+ links:
+ # GET /users/{id}
+ GetUserId:
+ operationId: getUserId
+ parameters:
+ id: '$response.body#/user/id'
+ # PUT /users/{id}
+ PutUserId:
+ operationId: putUserId
+ parameters:
+ id: '$response.body#/user/id'
+ # DELETE /users/{id}
+ DelUserId:
+ operationId: delUserId
+ parameters:
+ id: '$response.body#/user/id'
+ '403':
+ description: insufficient authority to create an admin or moderator
requestBody:
content:
application/json:
get:
summary: List users
security:
- - OAuth2: []
+ - 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'
items:
$ref: '#/components/schemas/User'
'/users/{id}':
+ parameters:
+ - $ref: '#/components/parameters/id'
delete:
summary: Delete a user
security:
- admin
tags:
- Users
- parameters:
- - $ref: '#/components/parameters/id'
+ operationId: delUserId
responses:
'204':
description: successful operation
- OAuth2: []
tags:
- Users
- parameters:
- - $ref: '#/components/parameters/id'
+ operationId: getUserId
responses:
'200':
description: successful operation
- OAuth2: []
tags:
- Users
- parameters:
- - $ref: '#/components/parameters/id'
+ operationId: putUserId
responses:
'204':
description: successful operation
'200':
description: successful operation
post:
+ tags:
+ - My Subscriptions
summary: Add subscription to my user
security:
- OAuth2:
- user
- tags:
- - My Subscriptions
+ 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
- My Notifications
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
type: object
properties:
- My Notifications
requestBody:
content:
- multipart/form-data:
+ application/json:
schema:
type: object
properties:
$ref: '#/components/schemas/NotificationSettingValue'
newCommentOnMyVideo:
$ref: '#/components/schemas/NotificationSettingValue'
- videoAbuseAsModerator:
+ abuseAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
videoAutoBlacklistAsModerator:
$ref: '#/components/schemas/NotificationSettingValue'
description: Whether or not we wait transcoding before publish the video
type: string
support:
- description: Text describing how to support the video uploader
+ description: A text tell the audience how to support the video creator
+ example: Please support my work on <insert crowdfunding plateform>! <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
description: Whether or not we wait transcoding before publish the video
type: string
support:
- description: Text describing how to support the video uploader
+ description: A text tell the audience how to support the video creator
+ example: Please support my work on <insert crowdfunding plateform>! <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
x-code-samples:
- lang: Shell
source: |
- ## DEPENDENCIES: httpie, jq
- # pip install httpie
+ ## DEPENDENCIES: jq
USERNAME="<your_username>"
PASSWORD="<your_password>"
FILE_PATH="<your_file_path>"
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 \
+ client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
+ client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
+ token=$(curl -s "$API_PATH/users/token" \
+ --data client_id="$client_id" \
+ --data client_secret="$client_secret" \
+ --data grant_type=password \
+ --data response_type=code \
+ --data username="$USERNAME" \
+ --data 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"
+ curl -s "$API_PATH/videos/upload" \
+ -H "Authorization: Bearer $token" \
+ --max-time 600 \
+ --form videofile=@"$FILE_PATH" \
+ --form channelId=$CHANNEL_ID \
+ --form name="$NAME"
/videos/imports:
post:
summary: Import a video
description: Whether or not we wait transcoding before publish the video
type: string
support:
- description: Text describing how to support the video uploader
+ description: A text tell the audience how to support the video creator
+ example: Please support my work on <insert crowdfunding plateform>! <3
type: string
nsfw:
description: Whether or not this video contains sensitive content
description: HTTP or Torrent/magnetURI import not enabled
'400':
description: '`magnetUri` or `targetUrl` or a torrent file missing'
- /videos/abuse:
+
+ /users/me/abuses:
get:
- summary: List video abuses
+ summary: List my abuses
+ 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/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/abusesSort'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/Abuse'
+
+ /abuses:
+ get:
+ summary: List abuses
security:
- OAuth2:
- admin
- moderator
tags:
- - Video Abuses
+ - Abuses
parameters:
- name: id
in: query
in: query
description: predefined reason the listed reports should contain
schema:
- type: string
- enum:
- - violentOrAbusive
- - hatefulOrAbusive
- - spamOrMisleading
- - privacy
- - rights
- - serverRules
- - thumbnails
- - captions
+ $ref: '#/components/schemas/PredefinedAbuseReasons'
- name: search
in: query
description: plain search that will match with video titles, reporter names and more
type: string
- name: state
in: query
- description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
schema:
- type: integer
- enum:
- - 1
- - 2
- - 3
+ $ref: '#/components/schemas/AbuseStateSet'
- name: searchReporter
in: query
description: only list reports of a specific reporter
description: only list reports of a specific video channel
schema:
type: string
+ - name: videoIs
+ in: query
+ description: only list blacklisted or deleted 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'
schema:
type: array
items:
- $ref: '#/components/schemas/VideoAbuse'
- '/videos/{id}/abuse':
+ $ref: '#/components/schemas/Abuse'
+
post:
summary: Report an abuse
security:
- OAuth2: []
tags:
- - Video Abuses
- - Videos
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
+ - Abuses
requestBody:
required: true
content:
type: string
minLength: 4
predefinedReasons:
- description: Reason categories that help triage reports
- type: array
- items:
- type: string
- enum:
- - violentOrAbusive
- - hatefulOrAbusive
- - spamOrMisleading
- - privacy
- - rights
- - serverRules
- - thumbnails
- - captions
- startAt:
- type: integer
- description: Timestamp in the video that marks the beginning of the report
- minimum: 0
- endAt:
- type: integer
- description: Timestamp in the video that marks the ending of the report
- minimum: 0
+ $ref: '#/components/schemas/PredefinedAbuseReasons'
+
+ video:
+ type: object
+ properties:
+ id:
+ description: Video id to report
+ type: number
+ startAt:
+ type: integer
+ description: Timestamp in the video that marks the beginning of the report
+ minimum: 0
+ endAt:
+ type: integer
+ description: Timestamp in the video that marks the ending of the report
+ minimum: 0
+ comment:
+ type: object
+ properties:
+ id:
+ description: Comment id to report
+ type: number
+ account:
+ type: object
+ properties:
+ id:
+ description: Account id to report
+ type: number
required:
- reason
responses:
description: successful operation
'400':
description: incorrect request parameters
- '/videos/{id}/abuse/{abuseId}':
+ '/abuses/{abuseId}':
put:
summary: Update an abuse
security:
- admin
- moderator
tags:
- - Video Abuses
+ - Abuses
parameters:
- - $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/abuseId'
requestBody:
content:
type: object
properties:
state:
- $ref: '#/components/schemas/VideoAbuseStateSet'
+ $ref: '#/components/schemas/AbuseStateSet'
moderationComment:
type: string
description: Update the report comment visible only to the moderation team
'204':
description: successful operation
'404':
- description: video abuse not found
+ description: abuse not found
delete:
tags:
- - Video Abuses
+ - Abuses
summary: Delete an abuse
security:
- OAuth2:
- admin
- moderator
parameters:
- - $ref: '#/components/parameters/idOrUUID'
- $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: 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
+ 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:
type: integer
required:
- displayName
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
/video-playlists/{id}:
get:
videoChannelId:
description: Video channel in which the playlist will be published
type: integer
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
delete:
summary: Delete a video playlist
security:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ '404':
+ description: video does not exist
requestBody:
content:
application/json:
application/json:
schema:
$ref: '#/components/schemas/CommentThreadPostResponse'
+ '404':
+ description: thread or video does not exist
requestBody:
content:
application/json:
responses:
'204':
description: successful operation
+ '404':
+ description: video does not exist
/search/videos:
get:
tags:
description: Get videos that have this maximum duration
schema:
type: integer
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
responses:
'200':
description: successful operation
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '500':
+ description: search index unavailable
/search/video-channels:
get:
tags:
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/searchTarget'
- $ref: '#/components/parameters/sort'
+ callbacks:
+ 'searchTarget === search-index':
+ $ref: '#/components/callbacks/searchIndex'
responses:
'200':
description: successful operation
type: array
items:
$ref: '#/components/schemas/VideoChannel'
+ '500':
+ description: search index unavailable
/blocklist/accounts:
get:
tags:
- name: format
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+ description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
schema:
type: string
enum:
description: 'limit listing to a specific video'
schema:
type: string
+ - name: accountId
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: accountName
+ in: query
+ description: 'limit listing to a specific account'
+ schema:
+ type: string
+ - name: videoChannelId
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
+ - name: videoChannelName
+ in: query
+ description: 'limit listing to a specific video channel'
+ schema:
+ type: string
responses:
'204':
description: successful operation
application/json:
schema:
type: object
+ '400':
+ x-summary: field inconsistencies
+ description: >
+ Arises when:
+ - videoId filter is mixed with a channel filter
+ '404':
+ description: video, video channel or account not found
'406':
description: accept header unsupported
'/feeds/videos.{format}':
- name: format
in: path
required: true
- description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
+ description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
schema:
type: string
enum:
application/json:
schema:
type: object
+ '404':
+ description: video channel or account not found
'406':
description: accept header unsupported
/plugins:
schema:
type: string
example: -createdAt
+ search:
+ name: search
+ in: query
+ required: false
+ description: Plain text search, applied to various parts of the model depending on endpoint
+ schema:
+ type: string
searchTarget:
name: searchTarget
in: query
- -dislikes
- -uuid
- -createdAt
+ usersSearch:
+ name: search
+ in: query
+ required: false
+ description: Plain text search that will match with user usernames or emails
+ schema:
+ type: string
+ usersBlocked:
+ name: blocked
+ in: query
+ required: false
+ description: Filter results down to (un)banned users
+ schema:
+ type: boolean
usersSort:
name: sort
in: query
name: abuseId
in: path
required: true
- description: Video abuse id
+ description: Abuse id
+ schema:
+ type: integer
+ abuseMessageId:
+ name: abuseMessageId
+ in: path
+ required: true
+ description: Abuse message id
schema:
type: integer
captionLanguage:
- 1
- 2
description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
+ example: 2
VideoStateConstant:
properties:
label:
type: string
- VideoAbuseStateSet:
+ AbuseStateSet:
type: integer
enum:
- 1
- 2
- 3
- description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
- VideoAbuseStateConstant:
+ description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+ AbuseStateConstant:
properties:
id:
- $ref: '#/components/schemas/VideoAbuseStateSet'
+ $ref: '#/components/schemas/AbuseStateSet'
label:
type: string
- VideoAbusePredefinedReasons:
+ AbusePredefinedReasons:
type: array
items:
type: string
type: string
support:
type: string
+ description: A text tell the audience how to support the video creator
example: Please support my work on <insert crowdfunding plateform>! <3
channel:
$ref: '#/components/schemas/VideoChannel'
files:
type: array
items:
- $ref: '#/components/schemas/FileRedundancyInformation'
+ $ref: '#/components/schemas/FileRedundancyInformation'
streamingPlaylists:
type: array
items:
- $ref: '#/components/schemas/FileRedundancyInformation'
+ $ref: '#/components/schemas/FileRedundancyInformation'
VideoImportStateConstant:
properties:
id:
format: date-time
video:
$ref: '#/components/schemas/Video'
- VideoAbuse:
+ Abuse:
properties:
id:
type: integer
type: string
example: The video is a spam
predefinedReasons:
- $ref: '#/components/schemas/VideoAbusePredefinedReasons'
+ $ref: '#/components/schemas/AbusePredefinedReasons'
reporterAccount:
$ref: '#/components/schemas/Account'
state:
- $ref: '#/components/schemas/VideoAbuseStateConstant'
+ $ref: '#/components/schemas/AbuseStateConstant'
moderationComment:
type: string
example: Decided to ban the server since it spams us regularly
createdAt:
type: string
format: date-time
+ AbuseMessage:
+ properties:
+ id:
+ type: integer
+ message:
+ type: string
+ byModerator:
+ type: boolean
+ createdAt:
+ type: string
+ format: date-time
+ account:
+ $ref: '#/components/schemas/AccountSummary'
VideoBlacklist:
properties:
id:
updatedAt:
type: string
format: date-time
+
+ PredefinedAbuseReasons:
+ description: Reason categories that help triage reports
+ type: array
+ items:
+ type: string
+ enum:
+ - violentOrAbusive
+ - hatefulOrAbusive
+ - spamOrMisleading
+ - privacy
+ - rights
+ - serverRules
+ - thumbnails
+ - captions
+
Job:
properties:
id:
format: date-time
AddUserResponse:
properties:
- id:
- type: integer
- uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ user:
+ type: object
+ properties:
+ id:
+ type: integer
+ example: 8
+ account:
+ type: object
+ properties:
+ id:
+ type: integer
+ example: 37
VideoUploadResponse:
properties:
video:
description: The user daily video quota
videosCount:
type: integer
- videoAbusesCount:
+ abusesCount:
type: integer
- videoAbusesAcceptedCount:
+ abusesAcceptedCount:
type: integer
- videoAbusesCreatedCount:
+ abusesCreatedCount:
type: integer
videoCommentsCount:
type: integer
support:
type: string
description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+ example: Please support my work on <insert crowdfunding plateform>! <3
required:
- name
- displayName
support:
type: string
description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
+ example: Please support my work on <insert crowdfunding plateform>! <3
bulkVideosSupportUpdate:
type: boolean
description: 'Update the support field for all videos of this channel'
- `2` NEW_COMMENT_ON_MY_VIDEO
- - `3` NEW_VIDEO_ABUSE_FOR_MODERATORS
+ - `3` NEW_ABUSE_FOR_MODERATORS
- `4` BLACKLIST_ON_MY_VIDEO
type: array
maxItems: 100
items:
- $ref: '#/components/schemas/Plugin'
\ No newline at end of file
+ $ref: '#/components/schemas/Plugin'
+ callbacks:
+ searchIndex:
+ 'https://search.example.org/api/v1/search/videos':
+ post:
+ summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoListResponse'
projects / github / Chocobozzz / PeerTube.git / blobdiff