openapi: 3.0.0
info:
title: PeerTube
- version: 2.4.0
+ version: 3.1.0-rc.1
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
- 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'
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
application/json:
schema:
$ref: '#/components/schemas/Avatar'
+ '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:
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
$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
application/json:
schema:
$ref: '#/components/schemas/VideoUploadResponse'
- '409':
- description: HTTP or Torrent/magnetURI import not enabled
'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:
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
- -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
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
- 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:
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
type: boolean
1080p:
type: boolean
+ 1440p:
+ type: boolean
2160p:
type: boolean
hls:
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
properties:
saveReplay:
type: boolean
+ permanentLive:
+ description: User can stream multiple times in a permanent live
+ type: boolean
LiveVideoResponse:
properties:
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: