openapi: 3.0.0
info:
title: PeerTube
- version: 3.1.0
+ version: 3.2.0-rc.1
contact:
name: PeerTube Community
url: 'https://joinpeertube.org'
The API uses standard HTTP status codes to indicate the success or failure
of the API call. The body of the response will be JSON in the following
- format.
+ formats.
```
{
- "code": "unauthorized_request", // example inner error code
- "error": "Token is invalid." // example exposed error message
+ "error": "Account not found" // error debug message
+ }
+ ```
+
+ Some errors benefit from a more detailed message:
+ ```
+ {
+ "errors": {
+ "id": { // where 'id' is the name of the parameter concerned by the error.
+ "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error.
+ "msg": "Should have an valid id", // error debug message
+ "param": "id",
+ "location": "params" // 'params', 'body', 'header', 'query' or 'cookies'
+ }
+ }
}
```
|-------------------------|------------------|---------------------------|
| `/*` | 50 | 10 seconds |
| `POST /users/token` | 15 | 5 minutes |
- | `POST /users/register` | 2¹ | 5 minutes |
+ | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
| `POST /users/ask-send-verify-email` | 3 | 5 minutes |
- Depending on the endpoint, ¹failed requests are not taken into account. A service
+ Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
limit is announced by a `429 Too Many Requests` status code.
You can get details about the current state of your rate limit by reading the
content:
multipart/form-data:
schema:
- type: object
- properties:
- torrentfile:
- description: Torrent File
- type: string
- format: binary
- targetUrl:
- description: HTTP target URL
- type: string
- magnetUri:
- description: Magnet URI
- type: string
- channelId:
- description: Channel id that will contain this video
- type: integer
- thumbnailfile:
- description: Video thumbnail file
- type: string
- format: binary
- previewfile:
- description: Video preview file
- type: string
- format: binary
- privacy:
- $ref: '#/components/schemas/VideoPrivacySet'
- category:
- $ref: '#/components/schemas/VideoCategorySet'
- licence:
- $ref: '#/components/schemas/VideoLicenceSet'
- language:
- $ref: '#/components/schemas/VideoLanguageSet'
- description:
- description: Video description
- type: string
- waitTranscoding:
- description: Whether or not we wait transcoding before publish the video
- 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: 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
- minItems: 1
- maxItems: 5
- items:
- type: string
- minLength: 2
- maxLength: 30
- commentsEnabled:
- description: Enable or disable comments for this video
- type: boolean
- downloadEnabled:
- description: Enable or disable downloading for this video
- type: boolean
- scheduleUpdate:
- $ref: '#/components/schemas/VideoScheduledUpdate'
- required:
- - channelId
- - name
+ $ref: '#/components/schemas/VideoCreateImport'
encoding:
torrentfile:
contentType: application/x-bittorrent
type: object
properties:
text:
- type: string
- description: 'Text comment'
+ allOf:
+ - $ref: '#/components/schemas/VideoComment/properties/text'
+ format: markdown
+ maxLength: 10000
required:
- text
type: object
properties:
text:
- $ref: '#/components/schemas/VideoComment/properties/text'
+ allOf:
+ - $ref: '#/components/schemas/VideoComment/properties/text'
+ format: markdown
+ maxLength: 10000
required:
- text
`0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
example: 240
VideoResolutionConstant:
+ description: resolutions and their labels for the video
properties:
id:
$ref: '#/components/schemas/VideoResolutionSet'
allOf:
- $ref: '#/components/schemas/Video'
VideoFile:
+ readOnly: true
properties:
magnetUri:
type: string
+ format: uri
+ description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
+ example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
+ pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
resolution:
$ref: '#/components/schemas/VideoResolutionConstant'
size:
type: integer
- description: 'Video file size in bytes'
+ description: Video file size in bytes
torrentUrl:
type: string
description: Direct URL of the torrent file
format: url
fps:
type: number
+ description: Frames per second of the video file
metadataUrl:
type: string
format: url
+ description: URL dereferencing the output of ffprobe on the file
VideoStreamingPlaylists:
allOf:
- type: object
items:
type: string
format: url
+ example:
+ - https://peertube2.cpy.re/tracker/announce
+ - wss://peertube2.cpy.re/tracker/socket
files:
type: array
items:
label:
type: string
example: Pending
+ VideoCreateImport:
+ allOf:
+ - type: object
+ additionalProperties: false
+ oneOf:
+ - properties:
+ targetUrl:
+ $ref: '#/components/schemas/VideoImport/properties/targetUrl'
+ required: [targetUrl]
+ - properties:
+ magnetUri:
+ $ref: '#/components/schemas/VideoImport/properties/magnetUri'
+ required: [magnetUri]
+ - properties:
+ torrentfile:
+ $ref: '#/components/schemas/VideoImport/properties/torrentfile'
+ required: [torrentfile]
+ - $ref: '#/components/schemas/VideoUploadRequestCommon'
+ required:
+ - channelId
+ - name
VideoImport:
properties:
id:
- $ref: '#/components/schemas/id'
+ readOnly: true
+ allOf:
+ - $ref: '#/components/schemas/id'
targetUrl:
type: string
format: url
+ description: remote URL where to find the import's source video
example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
magnetUri:
type: string
format: uri
+ description: magnet URI allowing to resolve the import's source video
example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
+ pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
+ torrentfile:
+ writeOnly: true
+ type: string
+ format: binary
+ description: Torrent file containing only the video file
torrentName:
+ readOnly: true
type: string
state:
- $ref: '#/components/schemas/VideoImportStateConstant'
+ readOnly: true
+ allOf:
+ - $ref: '#/components/schemas/VideoImportStateConstant'
error:
+ readOnly: true
type: string
createdAt:
+ readOnly: true
type: string
format: date-time
updatedAt:
+ readOnly: true
type: string
format: date-time
video:
- $ref: '#/components/schemas/Video'
+ readOnly: true
+ nullable: true
+ allOf:
+ - $ref: '#/components/schemas/Video'
VideoImportsList:
properties:
total:
format: url
text:
type: string
- description: Text of the comment in Markdown
+ format: html
+ description: Text of the comment
minLength: 1
- maxLength: 10000
+ example: This video is wonderful!
threadId:
- type: integer
- inReplyToCommentId:
$ref: '#/components/schemas/id'
+ inReplyToCommentId:
+ nullable: true
+ allOf:
+ - $ref: '#/components/schemas/id'
videoId:
$ref: '#/components/schemas/Video/properties/id'
createdAt:
updatedAt:
type: string
format: date-time
+ deletedAt:
+ nullable: true
+ type: string
+ format: date-time
+ default: null
+ isDeleted:
+ type: boolean
+ default: false
totalRepliesFromVideoAuthor:
type: integer
minimum: 0
type: string
format: url
name:
- type: string
+ description: immutable name of the actor
+ allOf:
+ - $ref: '#/components/schemas/username'
host:
type: string
format: hostname
+ description: server on which the actor is resident
hostRedundancyAllowed:
type: boolean
+ description: whether this actor's host allows redundancy of its videos
followingCount:
type: integer
+ minimum: 0
+ description: number of actors subscribed to by this actor, as seen by this instance
followersCount:
type: integer
+ minimum: 0
+ description: number of followers of this actor, as seen by this instance
createdAt:
type: string
format: date-time
- $ref: '#/components/schemas/Actor'
- properties:
userId:
- $ref: '#/components/schemas/id'
+ description: object id for the user tied to this account
+ allOf:
+ - $ref: '#/components/schemas/User/properties/id'
displayName:
type: string
+ description: name displayed on the account's profile
description:
type: string
+ description: text or bio displayed on the account's profile
UserWatchingVideo:
properties:
currentTime:
type: boolean
description: Has the user confirmed their email address?
id:
- type: integer
+ allOf:
+ - $ref: '#/components/schemas/id'
readOnly: true
pluginAuth:
type: string
type: string
nullable: true
magnetUri:
- type: string
- format: uri
- nullable: true
+ $ref: '#/components/schemas/VideoImport/properties/magnetUri'
targetUri:
type: string
format: uri