openapi: 3.0.0
info:
title: PeerTube
- version: 4.0.0
+ version: 5.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 [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
+ See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few
examples of using 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#roles) for a detail of their permissions.
# Errors
{
"detail": "Video not found",
- "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
"status": 404,
"title": "Not Found",
"type": "about:blank"
{
"detail": "Cannot get this video regarding follow constraints",
- "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
"status": 403,
"title": "Forbidden",
- "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+ "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"
}
```
{
"detail": "Incorrect request parameters: id",
- "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+ "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
"instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
"invalid-params": {
"id": {
In addition, all routes serving ActivityPub are CORS-enabled for all origins.
externalDocs:
- url: https://docs.joinpeertube.org/api-rest-reference.html
+ url: https://docs.joinpeertube.org/api/rest-reference.html
tags:
- name: Register
description: |
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#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](#tag/Video-Mirroring).
externalDocs:
- url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
+ url: https://docs.joinpeertube.org/admin/following-instances#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.
'200':
description: successful operation
- /api/v1/users/register:
+ /api/v1/users/ask-send-verify-email:
post:
- summary: Register a user
- operationId: registerUser
+ summary: Resend user verification link
+ operationId: resendEmailToVerifyUser
tags:
- Users
- Register
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ description: User email
+ required:
+ - email
responses:
'204':
description: successful operation
+
+ /api/v1/users/registrations/ask-send-verify-email:
+ post:
+ summary: Resend verification link to registration email
+ operationId: resendEmailToVerifyRegistration
+ tags:
+ - Register
requestBody:
content:
application/json:
schema:
- $ref: '#/components/schemas/RegisterUser'
- required: true
+ type: object
+ properties:
+ email:
+ type: string
+ description: Registration email
+ required:
+ - email
+ responses:
+ '204':
+ description: successful operation
/api/v1/users/{id}/verify-email:
post:
description: |
Following a user registration, the new user will receive an email asking to click a link
containing a secret.
+ This endpoint can also be used to verify a new email set in the user account.
tags:
- Users
- Register
'404':
description: user not found
+ /api/v1/users/registrations/{registrationId}/verify-email:
+ post:
+ summary: Verify a registration email
+ operationId: verifyRegistrationEmail
+ description: |
+ Following a user registration request, the user will receive an email asking to click a link
+ containing a secret.
+ tags:
+ - Register
+ parameters:
+ - $ref: '#/components/parameters/registrationId'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ verificationString:
+ type: string
+ format: url
+ required:
+ - verificationString
+ responses:
+ '204':
+ description: successful operation
+ '403':
+ description: invalid verification string
+ '404':
+ description: registration not found
+
/api/v1/users/{id}/two-factor/request:
post:
summary: Request two factor auth
'404':
description: user not found
-
- /api/v1/users/ask-send-verify-email:
- post:
- summary: Resend user verification link
- operationId: resendEmailToVerifyUser
- tags:
- - Users
- - Register
- responses:
- '204':
- description: successful operation
-
/api/v1/users/me:
get:
summary: Get my user information
'204':
description: successful operation
+ /api/v1/users/register:
+ post:
+ summary: Register a user
+ operationId: registerUser
+ description: Signup has to be enabled and signup approval is not required
+ tags:
+ - Register
+ responses:
+ '204':
+ description: successful operation
+ '400':
+ description: request error
+ '403':
+ description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
+ '409':
+ description: 'a user with this username, channel name or email already exists'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/RegisterUser'
+ required: true
+
+ /api/v1/users/registrations/request:
+ post:
+ summary: Request registration
+ description: Signup has to be enabled and require approval on the instance
+ operationId: requestRegistration
+ tags:
+ - Register
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistration'
+ '400':
+ description: request error or signup approval is not enabled on the instance
+ '403':
+ description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
+ '409':
+ description: 'a user or registration with this username, channel name or email already exists'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistrationRequest'
+
+ /api/v1/users/registrations/{registrationId}/accept:
+ post:
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Accept registration
+ operationId: acceptRegistration
+ tags:
+ - Register
+ parameters:
+ - $ref: '#/components/parameters/registrationId'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/users/registrations/{registrationId}/reject:
+ post:
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Reject registration
+ operationId: rejectRegistration
+ tags:
+ - Register
+ parameters:
+ - $ref: '#/components/parameters/registrationId'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/UserRegistrationAcceptOrReject'
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/users/registrations/{registrationId}:
+ delete:
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ summary: Delete registration
+ description: 'Delete the registration entry. It will not remove the user associated with this registration (if any)'
+ operationId: deleteRegistration
+ tags:
+ - Register
+ parameters:
+ - $ref: '#/components/parameters/registrationId'
+ responses:
+ '204':
+ description: successful operation
+
+ /api/v1/users/registrations:
+ get:
+ security:
+ - OAuth2:
+ - admin
+ - moderator
+ summary: List registrations
+ operationId: listRegistrations
+ tags:
+ - Register
+ parameters:
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - name: search
+ in: query
+ required: false
+ schema:
+ type: string
+ - name: sort
+ in: query
+ required: false
+ schema:
+ type: string
+ enum:
+ - -createdAt
+ - createdAt
+ - state
+ - -state
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/UserRegistration'
+
/api/v1/videos/ownership:
get:
summary: List video ownership changes
/api/v1/videos/privacies:
get:
summary: List available video privacy policies
- operationId: getPrivacyPolicies
+ operationId: getVideoPrivacyPolicies
tags:
- Video
responses:
type: integer
saveReplay:
type: boolean
+ replaySettings:
+ $ref: '#/components/schemas/LiveVideoReplaySettings'
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
schema:
$ref: '#/components/schemas/VideoListResponse'
+ '/api/v1/video-channels/{channelHandle}/video-playlists':
+ get:
+ summary: List playlists of a channel
+ tags:
+ - Video Playlists
+ - Video Channels
+ parameters:
+ - $ref: '#/components/parameters/channelHandle'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/videoPlaylistType'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
+
'/api/v1/video-channels/{channelHandle}/followers':
get:
tags:
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/videoPlaylistType'
responses:
'200':
description: successful operation
format: seconds
stopTimestamp:
type: integer
- format: seconds
+
+ '/api/v1/accounts/{name}/video-playlists':
+ get:
+ summary: List playlists of an account
+ tags:
+ - Video Playlists
+ - Accounts
+ parameters:
+ - $ref: '#/components/parameters/name'
+ - $ref: '#/components/parameters/start'
+ - $ref: '#/components/parameters/count'
+ - $ref: '#/components/parameters/sort'
+ - $ref: '#/components/parameters/search'
+ - $ref: '#/components/parameters/videoPlaylistType'
+ responses:
+ '200':
+ description: successful operation
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ total:
+ type: integer
+ example: 1
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/VideoPlaylist'
'/api/v1/accounts/{name}/video-channels':
get:
type: string
enum:
- createdAt
+
name:
name: name
in: path
description: Entity id
schema:
$ref: '#/components/schemas/id'
+ registrationId:
+ name: registrationId
+ in: path
+ required: true
+ description: Registration ID
+ schema:
+ $ref: '#/components/schemas/id'
idOrUUID:
name: id
in: path
description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
schema:
type: boolean
-
+ videoPlaylistType:
+ name: playlistType
+ in: query
+ required: false
+ schema:
+ $ref: '#/components/schemas/VideoPlaylistTypeSet'
+
securitySchemes:
OAuth2:
description: |
Note that the __access token is valid for 1 day__ and is given
along with a __refresh token valid for 2 weeks__.
- [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
+ [Generate]: https://docs.joinpeertube.org/api/rest-getting-started
type: oauth2
flows:
password:
- 1
- 2
- 3
- description: Video playlist privacy policy (see [/video-playlists/privacies])
+ description: Video playlist privacy policy (see [/video-playlists/privacies](#operation/getPlaylistPrivacyPolicies))
VideoPlaylistPrivacyConstant:
properties:
id:
- 2
- 3
- 4
- description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
+ description: privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies))
VideoPrivacyConstant:
properties:
id:
- 2
- 3
description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
+
+ LiveVideoReplaySettings:
+ type: object
+ properties:
+ privacy:
+ # description: Video playlist privacy policy (see [../video-playlists/privacies])
+ $ref: '#/components/schemas/VideoPrivacySet'
+
VideoStateConstant:
properties:
required:
- video
- rating
+
RegisterUser:
properties:
username:
- password
- email
+ UserRegistrationRequest:
+ allOf:
+ - $ref: '#/components/schemas/RegisterUser'
+ - type: object
+ properties:
+ registrationReason:
+ type: string
+ description: reason for the user to register on the instance
+ required:
+ - registrationReason
+
+ UserRegistrationAcceptOrReject:
+ type: object
+ properties:
+ moderationResponse:
+ type: string
+ description: Moderation response to send to the user
+ preventEmailDelivery:
+ type: boolean
+ description: Set it to true if you don't want PeerTube to send an email to the user
+ required:
+ - moderationResponse
+
+ UserRegistration:
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+ state:
+ type: object
+ properties:
+ id:
+ type: integer
+ enum:
+ - 1
+ - 2
+ - 3
+ description: 'The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
+ label:
+ type: string
+ registrationReason:
+ type: string
+ moderationResponse:
+ type: string
+ nullable: true
+ username:
+ type: string
+ email:
+ type: string
+ format: email
+ emailVerified:
+ type: boolean
+ accountDisplayName:
+ type: string
+ channelHandle:
+ type: string
+ channelDisplayName:
+ type: string
+ createdAt:
+ type: string
+ format: date-time
+ updatedAt:
+ type: string
+ format: date-time
+ user:
+ type: object
+ nullable: true
+ description: If the registration has been accepted, this is a partial user object created by the registration
+ properties:
+ id:
+ $ref: '#/components/schemas/id'
+
OAuthClient:
properties:
client_id:
uuid:
$ref: '#/components/schemas/UUIDv4'
+ VideoChannelEdit:
+ properties:
+ displayName:
+ description: Channel display name
+ description:
+ description: Channel description
+ support:
+ description: How to support/fund the channel
+
VideoChannelCreate:
allOf:
- - $ref: '#/components/schemas/VideoChannel'
+ - $ref: '#/components/schemas/VideoChannelEdit'
- properties:
name:
description: username of the channel to create
- displayName
VideoChannelUpdate:
allOf:
- - $ref: '#/components/schemas/VideoChannel'
+ - $ref: '#/components/schemas/VideoChannelEdit'
- properties:
bulkVideosSupportUpdate:
type: boolean
description: Update the support field for all videos of this channel
+
VideoChannelList:
properties:
total:
NotificationSettingValue:
type: integer
description: >
- Notification type
+ Notification type. One of the following values, or a sum of multiple values:
- `0` NONE
- `1` WEB
- `2` EMAIL
- enum:
- - 0
- - 1
- - 2
Notification:
properties:
id:
properties:
saveReplay:
type: boolean
+ replaySettings:
+ $ref: '#/components/schemas/LiveVideoReplaySettings'
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean
description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
saveReplay:
type: boolean
+ replaySettings:
+ $ref: '#/components/schemas/LiveVideoReplaySettings'
permanentLive:
description: User can stream multiple times in a permanent live
type: boolean