openapi: 3.0.0
info:
title: PeerTube
- version: 2.3.0-rc.1
+ version: 3.1.0
contact:
name: PeerTube Community
url: 'https://joinpeertube.org'
- [Go](https://framagit.org/framasoft/peertube/clients/go)
- [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
- See the [Quick Start guide](https://docs.joinpeertube.org/#/api-rest-getting-started) so you can play with the PeerTube API.
+ See the [Quick Start guide](https://docs.joinpeertube.org/api-rest-getting-started) so you can play with the PeerTube API.
# Authentication
## 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.
+ 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
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
information across its social graph by posting activities to actors' inbox
endpoints.
externalDocs:
- url: https://docs.joinpeertube.org/#/admin-following-instances?id=instances-follows
+ 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.
to the policy of video selection of your choice. Note that you have a similar functionality
to mirror individual videos, see `Video Mirroring`.
externalDocs:
- url: https://docs.joinpeertube.org/#/admin-following-instances?id=instances-redundancy
+ 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
+ url: https://docs.joinpeertube.org/api-plugins
- name: Abuses
description: |
Abuses deal with reports of local or remote videos/comments/accounts alike.
- My User
- My Subscriptions
- My Notifications
+ - My History
- name: Videos
tags:
- Video
- Video Playlists
- Video Ownership Change
- Video Mirroring
+ - Live Videos
- Feeds
- name: Search
tags:
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'
})
- 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'
- Config
security:
- OAuth2:
- - admin
+ - admin
responses:
'200':
description: successful operation
- Config
security:
- OAuth2:
- - admin
+ - admin
responses:
'200':
description: successful operation
- Config
security:
- OAuth2:
- - admin
+ - admin
responses:
'200':
description: successful operation
summary: List instance jobs
security:
- OAuth2:
- - admin
+ - admin
tags:
- Job
parameters:
- name: state
in: path
required: true
- description: The state of the job
+ 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'
post:
security:
- OAuth2:
- - admin
+ - admin
tags:
- Instance Follows
summary: Follow a server
summary: Create a user
security:
- OAuth2:
- - admin
+ - admin
tags:
- Users
responses:
summary: Delete a user
security:
- OAuth2:
- - admin
+ - admin
tags:
- Users
operationId: delUserId
summary: Get video imports of my user
security:
- OAuth2:
- - user
+ - user
tags:
- Videos
- My User
summary: Get my user subscriptions
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
summary: Add subscription to my user
security:
- OAuth2:
- - user
+ - user
requestBody:
content:
application/json:
summary: Get if subscriptions exist for my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
- Videos
parameters:
- $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
- $ref: '#/components/parameters/tagsOneOf'
- $ref: '#/components/parameters/tagsAllOf'
- $ref: '#/components/parameters/licenceOneOf'
summary: Get subscription of my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
summary: Delete subscription of my user
security:
- OAuth2:
- - user
+ - user
tags:
- My Subscriptions
parameters:
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/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
content:
application/json:
schema:
- $ref: '#/components/schemas/Avatar'
+ 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:
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
- Video
parameters:
- $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
- $ref: '#/components/parameters/tagsOneOf'
- $ref: '#/components/parameters/tagsAllOf'
- $ref: '#/components/parameters/licenceOneOf'
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
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
+ '400':
+ description: invalid file field, schedule date or parameter
'403':
- description: user video quota is exceeded with this video
+ description: video didn't pass upload filter
'408':
description: upload has timed out
+ '413':
+ description: video file too large, due to quota or max body size limit set by the reverse-proxy
+ 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: invalid input file
+ description: video unreadable
requestBody:
content:
multipart/form-data:
example: 4
licence:
description: Video licence
- type: string
- language:
- description: Video language
type: integer
example: 2
+ 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
+ type: boolean
support:
description: A text tell the audience how to support the video creator
example: Please support my work on <insert crowdfunding plateform>! <3
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
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
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
$ref: '#/components/schemas/VideoPrivacySet'
category:
description: Video category
- type: string
+ type: integer
+ example: 4
licence:
description: Video licence
- type: string
+ type: integer
+ example: 2
language:
description: Video language
type: string
type: string
waitTranscoding:
description: Whether or not we wait transcoding before publish the video
- type: string
+ type: boolean
support:
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
- type: string
+ 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
maxLength: 30
commentsEnabled:
description: Enable or disable comments for this video
- type: string
+ type: boolean
+ downloadEnabled:
+ description: Enable or disable downloading for this video
+ type: boolean
scheduleUpdate:
$ref: '#/components/schemas/VideoScheduledUpdate'
required:
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/live:
+ post:
+ summary: Create a live
+ security:
+ - OAuth2: []
+ tags:
+ - Live Videos
+ - Video
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VideoUploadResponse'
+ '403':
+ description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
+ 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:
+ description: Live video/replay category
+ type: string
+ licence:
+ description: Live video/replay licence
+ type: string
+ language:
+ description: Live video/replay language
+ type: string
+ description:
+ description: Live video/replay description
+ type: string
+ support:
+ description: A text tell the audience how to support the creator
+ example: Please support my work on <insert crowdfunding plateform>! <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
+ type: boolean
+ required:
+ - channelId
+ - name
+ encoding:
+ thumbnailfile:
+ contentType: image/jpeg
+ previewfile:
+ contentType: image/jpeg
+
+ /videos/live/{id}:
+ get:
+ summary: Get a live information
+ 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 a live information
+ 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: '`magnetUri` or `targetUrl` or a torrent file missing'
- /videos/abuse:
+ 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
+ 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:
- deprecated: true
summary: List abuses
security:
- OAuth2:
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 abuse state (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
schema:
type: array
items:
- $ref: '#/components/schemas/VideoAbuse'
- '/videos/{id}/abuse':
+ $ref: '#/components/schemas/Abuse'
+
post:
- deprecated: true
summary: Report an abuse
security:
- OAuth2: []
tags:
- Abuses
- - Videos
- parameters:
- - $ref: '#/components/parameters/idOrUUID'
requestBody:
required: true
content:
reason:
description: Reason why the user reports this video
type: string
- minLength: 4
+ minLength: 2
+ maxLength: 3000
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:
- deprecated: true
summary: Update an abuse
security:
- OAuth2:
tags:
- Abuses
parameters:
- - $ref: '#/components/parameters/idOrUUID'
- $ref: '#/components/parameters/abuseId'
requestBody:
content:
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:
- deprecated: true
tags:
- Abuses
summary: Delete an abuse
security:
- OAuth2:
- - admin
- - moderator
+ - 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: 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/idOrUUID'
- $ref: '#/components/parameters/abuseId'
+ - $ref: '#/components/parameters/abuseMessageId'
responses:
'204':
description: successful operation
- '404':
- description: block not found
'/videos/{id}/blacklist':
post:
summary: Block a video
security:
- OAuth2:
- - admin
- - moderator
+ - admin
+ - moderator
tags:
- Video Blocks
parameters:
summary: Unblock a video by its id
security:
- OAuth2:
- - admin
- - moderator
+ - admin
+ - moderator
tags:
- Video Blocks
parameters:
summary: List video blocks
security:
- OAuth2:
- - admin
- - moderator
+ - admin
+ - moderator
parameters:
- name: type
in: query
/videos/{id}/captions/{captionLanguage}:
put:
summary: Add or replace a video caption
+ security:
+ - OAuth2:
+ - user
tags:
- Video Captions
parameters:
description: video or language not found
delete:
summary: Delete a video caption
+ security:
+ - OAuth2:
+ - user
tags:
- Video Captions
parameters:
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'
application/json:
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '/video-channels/{channelHandle}/avatar/pick':
+ post:
+ summary: Update channel avatar
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ 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
+ '/video-channels/{channelHandle}/avatar':
+ delete:
+ summary: Delete channel avatar
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
+
+
+ '/video-channels/{channelHandle}/banner/pick':
+ post:
+ summary: Update channel banner
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ banner:
+ $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 banner
+ requestBody:
+ content:
+ multipart/form-data:
+ schema:
+ type: object
+ properties:
+ bannerfile:
+ description: The file to upload.
+ type: string
+ format: binary
+ encoding:
+ bannerfile:
+ contentType: image/png, image/jpeg
+ '/video-channels/{channelHandle}/banner':
+ delete:
+ summary: Delete channel banner
+ security:
+ - OAuth2: []
+ tags:
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ responses:
+ '204':
+ description: successful operation
/video-playlists/privacies:
get:
id:
type: integer
uuid:
- type: string
+ $ref: '#/components/schemas/UUIDv4'
requestBody:
content:
multipart/form-data:
displayName:
description: Video playlist display name
type: string
+ minLength: 1
+ maxLength: 120
thumbnailfile:
description: Video playlist thumbnail file
type: string
displayName:
description: Video playlist display name
type: string
+ minLength: 1
+ maxLength: 120
thumbnailfile:
description: Video playlist thumbnail file
type: string
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/VideoChannel'
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoChannel'
'/accounts/{name}/ratings':
get:
summary: List ratings of an account
schema:
type: string
- $ref: '#/components/parameters/categoryOneOf'
+ - $ref: '#/components/parameters/isLive'
- $ref: '#/components/parameters/tagsOneOf'
- $ref: '#/components/parameters/tagsAllOf'
- $ref: '#/components/parameters/licenceOneOf'
- -views
- -likes
- -trending
+ - -hot
videosSearchSort:
name: sort
in: query
name: name
in: path
required: true
- description: The name of the account
+ description: The username or handle of the account
schema:
type: string
example: chocobozzz | chocobozzz@example.org
- type: integer
minimum: 0
example: 42
- - type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ - $ref: '#/components/schemas/UUIDv4'
playlistElementId:
name: playlistElementId
in: path
description: Abuse id
schema:
type: integer
+ abuseMessageId:
+ name: abuseMessageId
+ in: path
+ required: true
+ description: Abuse message id
+ schema:
+ type: integer
captionLanguage:
name: captionLanguage
in: path
description: The comment id
schema:
type: integer
+ isLive:
+ name: isLive
+ in: query
+ required: false
+ description: whether or not the video is a live
+ schema:
+ type: boolean
categoryOneOf:
name: categoryOneOf
in: query
in: query
required: false
description: >
- Special filters (local for instance) which might require special rights:
+ Special filters 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)
+ * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
schema:
type: string
enum:
schema:
type: string
example: peertube-plugin-auth-ldap
+ jobType:
+ name: jobType
+ in: query
+ required: false
+ description: job type
+ schema:
+ type: string
+ enum:
+ - activitypub-follow
+ - activitypub-http-broadcast
+ - activitypub-http-fetcher
+ - activitypub-http-unicast
+ - email
+ - video-transcoding
+ - video-file-import
+ - video-import
+ - videos-views
+ - activitypub-refresher
+ - video-redundancy
+ - video-live-ending
securitySchemes:
OAuth2:
description: >
- Have an account with sufficient authorization levels
- - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
+ - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
Bearer Token
- Make Authenticated Requests
moderator: Moderator scope
user: User scope
schemas:
- VideoConstantNumber:
+ UUIDv4:
+ type: string
+ format: uuid
+ example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+ # the regex above limits the length;
+ # however, some tools might require explicit settings:
+ minLength: 36
+ maxLength: 36
+
+ VideoConstantNumber-Category:
+ properties:
+ id:
+ type: integer
+ description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
+ label:
+ type: string
+ VideoConstantNumber-Licence:
properties:
id:
type: integer
+ description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
label:
type: string
- VideoConstantString:
+ VideoConstantString-Language:
properties:
id:
type: string
+ description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
label:
type: string
- 2
description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
example: 2
+ UserAdminFlags:
+ type: integer
+ enum:
+ - 0
+ - 1
+ description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
+ example: 1
VideoStateConstant:
properties:
- 1
- 2
- 3
- description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+ description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
AbuseStateConstant:
properties:
id:
properties:
id:
type: integer
- description: 'Video resolution (240, 360, 720 ...)'
+ description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
example: 240
label:
type: string
avatar:
nullable: true
allOf:
- - $ref: '#/components/schemas/Avatar'
+ - $ref: '#/components/schemas/ActorImage'
VideoChannelSummary:
properties:
id:
avatar:
nullable: true
allOf:
- - $ref: '#/components/schemas/Avatar'
+ - $ref: '#/components/schemas/ActorImage'
PlaylistElement:
properties:
position:
description: 'Video file size in bytes'
torrentUrl:
type: string
+ description: Direct URL of the torrent file
format: url
torrentDownloadUrl:
type: string
+ description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
format: url
fileUrl:
type: string
+ description: Direct URL of the video
format: url
fileDownloadUrl:
type: string
+ description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
format: url
fps:
type: number
type: string
format: url
VideoStreamingPlaylists:
+ allOf:
+ - type: object
+ properties:
+ id:
+ type: integer
+ type:
+ type: integer
+ enum:
+ - 1
+ description: |
+ Playlist type:
+ - `1`: HLS
+ - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
+ VideoStreamingPlaylists-HLS:
properties:
- id:
- type: integer
- type:
- type: integer
- enum:
- - 1
- description: 'Playlist type (HLS = `1`)'
playlistUrl:
type: string
format: url
format: url
files:
type: array
+ description: |
+ Video files associated to this playlist.
+
+ The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
items:
$ref: '#/components/schemas/VideoFile'
redundancies:
id:
type: integer
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
name:
type: string
+ minLength: 3
+ maxLength: 120
Video:
properties:
id:
type: integer
example: 8
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
+ isLive:
+ type: boolean
createdAt:
type: string
format: date-time
+ example: 2017-10-01T10:52:46.396Z
+ description: time at which the video object was first drafted
publishedAt:
type: string
format: date-time
+ example: 2018-10-01T10:52:46.396Z
+ description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
updatedAt:
type: string
format: date-time
+ example: 2021-05-04T08:01:01.502Z
+ description: last time the video's metadata was modified
originallyPublishedAt:
type: string
format: date-time
+ example: 2010-10-01T10:52:46.396Z
+ description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
category:
- $ref: '#/components/schemas/VideoConstantNumber'
+ $ref: '#/components/schemas/VideoConstantNumber-Category'
licence:
- $ref: '#/components/schemas/VideoConstantNumber'
+ $ref: '#/components/schemas/VideoConstantNumber-Licence'
language:
- $ref: '#/components/schemas/VideoConstantString'
+ $ref: '#/components/schemas/VideoConstantString-Language'
privacy:
$ref: '#/components/schemas/VideoPrivacyConstant'
description:
type: string
+ 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)**\r\n*A decentralized video hosting network, based on fr...
+ minLength: 3
+ maxLength: 250
+ description: |
+ truncated description of the video, written in Markdown.
+ Resolve `descriptionPath` to get the full description of maximum `10000` characters.
duration:
type: integer
example: 1419
+ description: duration of the video in seconds
isLocal:
type: boolean
name:
type: string
example: What is PeerTube?
+ minLength: 3
+ maxLength: 120
thumbnailPath:
type: string
example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
previewPath:
type: string
- example: /static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
+ example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
embedPath:
type: string
example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
properties:
descriptionPath:
type: string
+ example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
+ description: path at which to get the full description of maximum `10000` characters
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
+ minLength: 3
+ maxLength: 1000
channel:
$ref: '#/components/schemas/VideoChannel'
account:
$ref: '#/components/schemas/Account'
tags:
- type: array
- items:
- type: string
example: [flowers, gardening]
- files:
type: array
+ minItems: 1
+ maxItems: 5
items:
- $ref: '#/components/schemas/VideoFile'
+ type: string
+ minLength: 2
+ maxLength: 30
commentsEnabled:
type: boolean
downloadEnabled:
items:
type: string
format: url
+ files:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoFile'
+ description: |
+ WebTorrent/raw video files. If WebTorrent is disabled on the server:
+
+ - field will be empty
+ - video files will be found in `streamingPlaylists[].files` field
streamingPlaylists:
type: array
items:
$ref: '#/components/schemas/VideoStreamingPlaylists'
+ description: |
+ HLS playlists/manifest files. If HLS is disabled on the server:
+
+ - field will be empty
+ - video files will be found in `files` field
FileRedundancyInformation:
properties:
id:
type: string
format: url
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
redundancies:
type: object
properties:
format: date-time
video:
$ref: '#/components/schemas/Video'
- VideoAbuse:
+ Abuse:
properties:
id:
type: integer
reason:
type: string
example: The video is a spam
+ minLength: 2
+ maxLength: 3000
predefinedReasons:
$ref: '#/components/schemas/AbusePredefinedReasons'
reporterAccount:
moderationComment:
type: string
example: Decided to ban the server since it spams us regularly
+ minLength: 2
+ maxLength: 3000
video:
- type: object
- properties:
- id:
- type: integer
- name:
- type: string
- uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/VideoInfo'
+ createdAt:
+ type: string
+ format: date-time
+ AbuseMessage:
+ properties:
+ id:
+ type: integer
+ message:
+ type: string
+ minLength: 2
+ maxLength: 3000
+ byModerator:
+ type: boolean
createdAt:
type: string
format: date-time
+ account:
+ $ref: '#/components/schemas/AccountSummary'
VideoBlacklist:
properties:
id:
format: date-time
name:
type: string
+ minLength: 3
+ maxLength: 120
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
description:
type: string
+ minLength: 3
+ maxLength: 10000
duration:
type: integer
views:
properties:
displayName:
type: string
+ minLength: 1
+ maxLength: 120
description:
type: string
+ minLength: 3
+ maxLength: 1000
isLocal:
type: boolean
ownerAccount:
id:
type: integer
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
VideoPlaylist:
properties:
id:
format: date-time
description:
type: string
+ minLength: 3
+ maxLength: 1000
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
displayName:
type: string
+ minLength: 1
+ maxLength: 120
isLocal:
type: boolean
videoLength:
format: url
text:
type: string
+ minLength: 1
+ maxLength: 10000
threadId:
type: integer
inReplyToCommentId:
VideoCaption:
properties:
language:
- $ref: '#/components/schemas/VideoConstantString'
+ $ref: '#/components/schemas/VideoConstantString-Language'
captionPath:
type: string
- Avatar:
+ ActorImage:
properties:
path:
type: string
type: string
format: date-time
avatar:
- $ref: '#/components/schemas/Avatar'
+ $ref: '#/components/schemas/ActorImage'
Account:
allOf:
- $ref: '#/components/schemas/Actor'
type: boolean
1080p:
type: boolean
+ 1440p:
+ type: boolean
2160p:
type: boolean
hls:
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:
type: integer
example: 8
uuid:
- type: string
- format: uuid
- example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
+ $ref: '#/components/schemas/UUIDv4'
CommentThreadResponse:
properties:
total:
type: string
format: email
description: The user email
+ pluginAuth:
+ type: string
+ description: Auth plugin to use to authenticate the user
theme:
type: string
description: Theme enabled by this user
videoQuotaDaily:
type: integer
description: The user daily video quota
+ channelName:
+ type: string
+ description: The user default channel username
role:
$ref: '#/components/schemas/UserRole'
+ adminFlags:
+ $ref: '#/components/schemas/UserAdminFlags'
required:
- username
- password
type: string
format: email
description: The updated email of the user
+ emailVerified:
+ type: boolean
+ description: Set the email as verified
videoQuota:
type: integer
description: The updated video quota of the user
videoQuotaDaily:
type: integer
description: The updated daily video quota of the user
+ pluginAuth:
+ type: string
+ nullable: true
+ description: The auth plugin to use to authenticate the user
+ example: 'peertube-plugin-auth-saml2'
role:
$ref: '#/components/schemas/UserRole'
+ adminFlags:
+ $ref: '#/components/schemas/UserAdminFlags'
required:
- id
- - email
- - videoQuota
- - videoQuotaDaily
- - role
UpdateMe:
properties:
password:
properties:
name:
type: string
- description: The name for the default channel
+ description: The username for the default channel
pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
displayName:
type: string
- username
- password
- email
- VideoChannelCreate:
+
+ VideoChannelCommon:
properties:
- name:
- type: string
displayName:
type: string
+ minLength: 1
+ maxLength: 120
description:
type: string
+ minLength: 3
+ maxLength: 1000
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
+ minLength: 3
+ maxLength: 1000
+ VideoChannelCreate:
+ allOf:
+ - $ref: '#/components/schemas/VideoChannelCommon'
+ - properties:
+ name:
+ type: string
+ minLength: 1
+ maxLength: 120
required:
- name
- displayName
VideoChannelUpdate:
- properties:
- displayName:
- type: string
- description:
- type: string
- 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'
+ allOf:
+ - $ref: '#/components/schemas/VideoChannelCommon'
+ - properties:
+ bulkVideosSupportUpdate:
+ type: boolean
+ description: 'Update the support field for all videos of this channel'
MRSSPeerLink:
type: object
maxItems: 100
items:
$ref: '#/components/schemas/Plugin'
+
+ LiveVideoUpdate:
+ properties:
+ saveReplay:
+ type: boolean
+ permanentLive:
+ description: User can stream multiple times in a permanent live
+ type: boolean
+
+ LiveVideoResponse:
+ properties:
+ rtmpUrl:
+ type: string
+ streamKey:
+ type: string
+ description: RTMP stream key to use to stream into this live video
+ saveReplay:
+ type: boolean
+ permanentLive:
+ description: User can stream multiple times in a permanent live
+ type: boolean
+
+
+
callbacks:
searchIndex:
- '{%CONFIG.SEARCH.SEARCH_INDEX.URL%}/api/v1/search/videos/':
+ '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:
projects / github / Chocobozzz / PeerTube.git / blobdiff