6 name: PeerTube Community
7 url: https://joinpeertube.org
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
92 "msg": "Invalid value",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
98 "title": "Bad Request",
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
108 ### Deprecated error fields
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
128 You can get details about the current state of your rate limit by reading the
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
144 |------------------------- ---|
148 | `/live/segments-sha256/*` |
149 | `/.well-known/webfinger` |
151 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
153 url: https://docs.joinpeertube.org/api-rest-reference.html
157 As a visitor, you can use this API to open an account (if registrations are open on
158 that PeerTube instance). As an admin, you should use the dedicated [User creation
159 API](#operation/addUser) instead.
161 x-displayName: Login/Logout
163 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
166 Accounts encompass remote accounts discovered across the federation,
167 and correspond to the main Actor, along with video channels a user can create, which
170 When a comment is posted, it is done with your Account's Actor.
173 Using some features of PeerTube require authentication, for which User
174 provide different levels of permission as well as associated user
175 information. Each user has a corresponding local Account for federation.
178 Operations related to your own User, when logged-in.
179 - name: My Subscriptions
181 Operations related to your subscriptions to video channels, their
182 new videos, and how to keep up to date with their latest publications!
185 Operations related to your watch history.
186 - name: My Notifications
188 Notifications following new videos, follows or reports. They allow you
189 to keep track of the interactions and overall important information that
190 concerns you. You MAY set per-notification type delivery preference, to
191 receive the info either by mail, by in-browser notification or both.
194 Each server exposes public information regarding supported videos and
198 Jobs are long-running tasks enqueued and processed by the instance
199 itself. No additional worker registration is currently available.
200 - name: Instance Follows
202 Managing servers which the instance interacts with is crucial to the
203 concept of federation in PeerTube and external video indexation. The PeerTube
204 server then deals with inter-server ActivityPub operations and propagates
205 information across its social graph by posting activities to actors' inbox
208 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
209 - name: Instance Redundancy
211 Redundancy is part of the inter-server solidarity that PeerTube fosters.
212 Manage the list of instances you wish to help by seeding their videos according
213 to the policy of video selection of your choice. Note that you have a similar functionality
214 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
216 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
219 Managing plugins installed from a local path or from NPM, or search for new ones.
221 url: https://docs.joinpeertube.org/api-plugins
224 Abuses deal with reports of local or remote videos/comments/accounts alike.
227 Operations dealing with listing, uploading, fetching or modifying videos.
230 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
234 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
235 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
237 You can upload videos more reliably by using the resumable variant. Its protocol lets
238 you resume an upload operation after a network interruption or other transmission failure,
239 saving time and bandwidth in the event of network failures.
241 Favor using resumable uploads in any of the following cases:
242 - You are transferring large files
243 - The likelihood of a network interruption is high
244 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
245 such as a mobile device
249 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
250 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
253 The import function is practical when the desired video/audio is available online. It makes PeerTube
254 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
255 - name: Video Imports
256 description: Operations dealing with listing, adding and removing video imports.
257 - name: Video Captions
258 description: Operations dealing with listing, adding and removing closed captions of a video.
259 - name: Video Channels
260 description: Operations dealing with the creation, modification and listing of videos within a channel.
261 - name: Video Comments
263 Operations dealing with comments to a video. Comments are organized in threads: adding a
264 comment in response to the video starts a thread, adding a reply to a comment adds it to
265 its root comment thread.
267 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
269 description: Like/dislike a video.
270 - name: Video Playlists
271 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
273 description: Operations on video files
274 - name: Video Transcoding
275 description: Video transcoding related operations
277 description: Server syndication feeds
280 The search helps to find _videos_ or _channels_ from within the instance and beyond.
281 Videos from other instances federated by the instance (that is, instances
282 followed by the instance) can be found via keywords and other criteria of
285 Administrators can also enable the use of a remote search system, indexing
286 videos and channels not could be not federated by the instance.
288 description: Get and update the custom homepage
289 - name: Video Mirroring
291 PeerTube instances can mirror videos from one another, and help distribute some videos.
293 For importing videos as your own, refer to [video imports](#operation/importVideo).
317 - Video Ownership Change
335 - name: Instance Configuration
339 - Instance Redundancy
349 summary: Get an account
350 operationId: getAccount
352 - $ref: '#/components/parameters/name'
355 description: successful operation
359 $ref: '#/components/schemas/Account'
361 description: account not found
363 '/accounts/{name}/videos':
368 summary: 'List videos of an account'
369 operationId: getAccountVideos
371 - $ref: '#/components/parameters/name'
372 - $ref: '#/components/parameters/categoryOneOf'
373 - $ref: '#/components/parameters/isLive'
374 - $ref: '#/components/parameters/tagsOneOf'
375 - $ref: '#/components/parameters/tagsAllOf'
376 - $ref: '#/components/parameters/licenceOneOf'
377 - $ref: '#/components/parameters/languageOneOf'
378 - $ref: '#/components/parameters/nsfw'
379 - $ref: '#/components/parameters/isLocal'
380 - $ref: '#/components/parameters/include'
381 - $ref: '#/components/parameters/privacyOneOf'
382 - $ref: '#/components/parameters/hasHLSFiles'
383 - $ref: '#/components/parameters/hasWebtorrentFiles'
384 - $ref: '#/components/parameters/skipCount'
385 - $ref: '#/components/parameters/start'
386 - $ref: '#/components/parameters/count'
387 - $ref: '#/components/parameters/videosSort'
390 description: successful operation
394 $ref: '#/components/schemas/VideoListResponse'
398 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
399 .then(function(response) {
400 return response.json()
401 }).then(function(data) {
407 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
413 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
415 http = Net::HTTP.new(uri.host, uri.port)
418 response = http.get(uri.request_uri)
420 puts JSON.parse(response.read_body)
425 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
430 '/accounts/{name}/followers':
434 summary: 'List followers of an account'
437 operationId: getAccountFollowers
439 - $ref: '#/components/parameters/name'
440 - $ref: '#/components/parameters/start'
441 - $ref: '#/components/parameters/count'
442 - $ref: '#/components/parameters/followersSort'
443 - $ref: '#/components/parameters/search'
446 description: successful operation
458 $ref: '#/components/schemas/Follow'
464 summary: List accounts
465 operationId: getAccounts
467 - $ref: '#/components/parameters/start'
468 - $ref: '#/components/parameters/count'
469 - $ref: '#/components/parameters/sort'
472 description: successful operation
478 $ref: '#/components/schemas/Account'
484 summary: Get instance public configuration
485 operationId: getConfig
488 description: successful operation
492 $ref: '#/components/schemas/ServerConfig'
495 externalValue: https://peertube2.cpy.re/api/v1/config
499 summary: Get instance "About" information
500 operationId: getAbout
505 description: successful operation
509 $ref: '#/components/schemas/ServerConfigAbout'
512 externalValue: https://peertube2.cpy.re/api/v1/config/about
516 summary: Get instance runtime configuration
517 operationId: getCustomConfig
525 description: successful operation
529 $ref: '#/components/schemas/ServerConfigCustom'
531 summary: Set instance runtime configuration
532 operationId: putCustomConfig
540 description: successful operation
542 x-summary: field inconsistencies
545 - the emailer is disabled and the instance is open to registrations
546 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
548 summary: Delete instance runtime configuration
549 operationId: delCustomConfig
557 description: successful operation
559 /custom-pages/homepage/instance:
561 summary: Get instance custom homepage
566 description: No homepage set
568 description: successful operation
572 $ref: '#/components/schemas/CustomHomepage'
574 summary: Set instance custom homepage
588 description: content of the homepage, that will be injected in the client
591 description: successful operation
595 summary: Pause job queue
603 description: successful operation
607 summary: Resume job queue
615 description: successful operation
619 summary: List instance jobs
630 description: The state of the job ('' for for no filter)
640 - $ref: '#/components/parameters/jobType'
641 - $ref: '#/components/parameters/start'
642 - $ref: '#/components/parameters/count'
643 - $ref: '#/components/parameters/sort'
646 description: successful operation
659 $ref: '#/components/schemas/Job'
665 summary: List instances following the server
667 - $ref: '#/components/parameters/followState'
668 - $ref: '#/components/parameters/actorType'
669 - $ref: '#/components/parameters/start'
670 - $ref: '#/components/parameters/count'
671 - $ref: '#/components/parameters/sort'
674 description: successful operation
686 $ref: '#/components/schemas/Follow'
688 '/server/followers/{nameWithHost}':
690 summary: Remove or reject a follower to your server
700 description: The remote actor handle to remove from your followers
706 description: successful operation
708 description: follower not found
710 '/server/followers/{nameWithHost}/reject':
712 summary: Reject a pending follower to your server
722 description: The remote actor handle to remove from your followers
728 description: successful operation
730 description: follower not found
732 '/server/followers/{nameWithHost}/accept':
734 summary: Accept a pending follower to your server
744 description: The remote actor handle to remove from your followers
750 description: successful operation
752 description: follower not found
758 summary: List instances followed by the server
760 - $ref: '#/components/parameters/followState'
761 - $ref: '#/components/parameters/actorType'
762 - $ref: '#/components/parameters/start'
763 - $ref: '#/components/parameters/count'
764 - $ref: '#/components/parameters/sort'
767 description: successful operation
779 $ref: '#/components/schemas/Follow'
786 summary: Follow a list of actors (PeerTube instance, channel or account)
789 description: successful operation
791 description: cannot follow a non-HTTPS server
810 '/server/following/{hostOrHandle}':
812 summary: Unfollow an actor (PeerTube instance, channel or account)
822 description: The hostOrHandle to unfollow
827 description: successful operation
829 description: host or handle not found
833 summary: Create a user
842 description: user created
846 $ref: '#/components/schemas/AddUserResponse'
852 id: '$response.body#/user/id'
857 id: '$response.body#/user/id'
862 id: '$response.body#/user/id'
864 description: insufficient authority to create an admin or moderator
869 $ref: '#/components/schemas/AddUser'
871 If the smtp server is configured, you can leave the password empty and an email will be sent
872 asking the user to set it first.
876 operationId: getUsers
883 - $ref: '#/components/parameters/usersSearch'
884 - $ref: '#/components/parameters/usersBlocked'
885 - $ref: '#/components/parameters/start'
886 - $ref: '#/components/parameters/count'
887 - $ref: '#/components/parameters/usersSort'
890 description: successful operation
896 $ref: '#/components/schemas/User'
900 - $ref: '#/components/parameters/id'
902 summary: Delete a user
911 description: successful operation
922 description: include statistics about the user (only available as a moderator/admin)
927 x-summary: successful operation
929 As an admin/moderator, you can request a response augmented with statistics about the user's
930 moderation relations and videos usage, by using the `withStats` parameter.
935 - $ref: '#/components/schemas/User'
936 - $ref: '#/components/schemas/UserWithStats'
938 summary: Update a user
946 description: successful operation
951 $ref: '#/components/schemas/UpdateUser'
954 /oauth-clients/local:
956 summary: Login prerequisite
957 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
958 operationId: getOAuthClient
963 description: successful operation
967 $ref: '#/components/schemas/OAuthClient'
969 UseOAuthClientToLogin:
970 operationId: getOAuthToken
972 client_id: '$response.body#/client_id'
973 client_secret: '$response.body#/client_secret'
977 API="https://peertube2.cpy.re/api/v1"
980 curl -s "$API/oauth-clients/local"
985 operationId: getOAuthToken
986 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
991 application/x-www-form-urlencoded:
994 - $ref: '#/components/schemas/OAuthToken-password'
995 - $ref: '#/components/schemas/OAuthToken-refresh_token'
997 propertyName: grant_type
999 password: '#/components/schemas/OAuthToken-password'
1000 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1003 description: successful operation
1014 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1015 description: valid for 1 day
1018 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1019 description: valid for 2 weeks
1024 refresh_token_expires_in:
1029 x-summary: client or credentials are invalid
1031 Disambiguate via `type`:
1032 - `invalid_client` for an unmatched `client_id`
1033 - `invalid_grant` for unmatched credentials
1035 x-summary: token expired
1037 Disambiguate via `type`:
1038 - default value for a regular authentication failure
1039 - `invalid_token` for an expired token
1044 API="https://peertube2.cpy.re/api/v1"
1045 USERNAME="<your_username>"
1046 PASSWORD="<your_password>"
1049 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1050 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1051 curl -s "$API/users/token" \
1052 --data client_id="$client_id" \
1053 --data client_secret="$client_secret" \
1054 --data grant_type=password \
1055 --data username="$USERNAME" \
1056 --data password="$PASSWORD" \
1057 | jq -r ".access_token"
1059 /users/revoke-token:
1062 description: Revokes your access token and its associated refresh token, destroying your current session.
1063 operationId: revokeOAuthToken
1070 description: successful operation
1074 summary: Register a user
1075 operationId: registerUser
1081 description: successful operation
1086 $ref: '#/components/schemas/RegisterUser'
1089 /users/{id}/verify-email:
1091 summary: Verify a user
1092 operationId: verifyUser
1094 Following a user registration, the new user will receive an email asking to click a link
1095 containing a secret.
1100 - $ref: '#/components/parameters/id'
1113 - verificationString
1116 description: successful operation
1118 description: invalid verification string
1120 description: user not found
1122 /users/ask-send-verify-email:
1124 summary: Resend user verification link
1125 operationId: resendEmailToVerifyUser
1131 description: successful operation
1135 summary: Get my user information
1136 operationId: getUserInfo
1144 description: successful operation
1150 $ref: '#/components/schemas/User'
1152 summary: Update my user information
1153 operationId: putUserInfo
1161 description: successful operation
1166 $ref: '#/components/schemas/UpdateMe'
1169 /users/me/videos/imports:
1171 summary: Get video imports of my user
1179 - $ref: '#/components/parameters/start'
1180 - $ref: '#/components/parameters/count'
1181 - $ref: '#/components/parameters/sort'
1184 description: successful operation
1188 $ref: '#/components/schemas/VideoImportsList'
1190 /users/me/video-quota-used:
1192 summary: Get my user used quota
1200 description: successful operation
1208 description: The user video quota used so far in bytes
1209 example: 16810141515
1210 videoQuotaUsedDaily:
1212 description: The user video quota used today in bytes
1215 '/users/me/videos/{videoId}/rating':
1217 summary: Get rate of my user for a video
1227 description: The video id
1229 $ref: '#/components/schemas/Video/properties/id'
1232 description: successful operation
1236 $ref: '#/components/schemas/GetMeVideoRating'
1240 summary: Get videos of my user
1248 - $ref: '#/components/parameters/start'
1249 - $ref: '#/components/parameters/count'
1250 - $ref: '#/components/parameters/sort'
1253 description: successful operation
1257 $ref: '#/components/schemas/VideoListResponse'
1259 /users/me/subscriptions:
1261 summary: Get my user subscriptions
1268 - $ref: '#/components/parameters/start'
1269 - $ref: '#/components/parameters/count'
1270 - $ref: '#/components/parameters/sort'
1273 description: successful operation
1277 $ref: '#/components/schemas/VideoChannelList'
1281 summary: Add subscription to my user
1294 description: uri of the video channels to subscribe to
1300 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1303 description: successful operation
1305 /users/me/subscriptions/exist:
1307 summary: Get if subscriptions exist for my user
1314 - $ref: '#/components/parameters/subscriptionsUris'
1317 description: successful operation
1323 /users/me/subscriptions/videos:
1325 summary: List videos of subscriptions of my user
1333 - $ref: '#/components/parameters/categoryOneOf'
1334 - $ref: '#/components/parameters/isLive'
1335 - $ref: '#/components/parameters/tagsOneOf'
1336 - $ref: '#/components/parameters/tagsAllOf'
1337 - $ref: '#/components/parameters/licenceOneOf'
1338 - $ref: '#/components/parameters/languageOneOf'
1339 - $ref: '#/components/parameters/nsfw'
1340 - $ref: '#/components/parameters/isLocal'
1341 - $ref: '#/components/parameters/include'
1342 - $ref: '#/components/parameters/privacyOneOf'
1343 - $ref: '#/components/parameters/hasHLSFiles'
1344 - $ref: '#/components/parameters/hasWebtorrentFiles'
1345 - $ref: '#/components/parameters/skipCount'
1346 - $ref: '#/components/parameters/start'
1347 - $ref: '#/components/parameters/count'
1348 - $ref: '#/components/parameters/videosSort'
1351 description: successful operation
1355 $ref: '#/components/schemas/VideoListResponse'
1357 '/users/me/subscriptions/{subscriptionHandle}':
1359 summary: Get subscription of my user
1366 - $ref: '#/components/parameters/subscriptionHandle'
1369 description: successful operation
1373 $ref: '#/components/schemas/VideoChannel'
1375 summary: Delete subscription of my user
1382 - $ref: '#/components/parameters/subscriptionHandle'
1385 description: successful operation
1387 /users/me/notifications:
1389 summary: List my notifications
1397 description: only list unread notifications
1400 - $ref: '#/components/parameters/start'
1401 - $ref: '#/components/parameters/count'
1402 - $ref: '#/components/parameters/sort'
1405 description: successful operation
1409 $ref: '#/components/schemas/NotificationListResponse'
1411 /users/me/notifications/read:
1413 summary: Mark notifications as read by their id
1426 description: ids of the notifications to mark as read
1433 description: successful operation
1435 /users/me/notifications/read-all:
1437 summary: Mark all my notification as read
1444 description: successful operation
1446 /users/me/notification-settings:
1448 summary: Update my notification settings
1459 newVideoFromSubscription:
1460 $ref: '#/components/schemas/NotificationSettingValue'
1461 newCommentOnMyVideo:
1462 $ref: '#/components/schemas/NotificationSettingValue'
1464 $ref: '#/components/schemas/NotificationSettingValue'
1465 videoAutoBlacklistAsModerator:
1466 $ref: '#/components/schemas/NotificationSettingValue'
1468 $ref: '#/components/schemas/NotificationSettingValue'
1470 $ref: '#/components/schemas/NotificationSettingValue'
1471 myVideoImportFinished:
1472 $ref: '#/components/schemas/NotificationSettingValue'
1474 $ref: '#/components/schemas/NotificationSettingValue'
1475 newUserRegistration:
1476 $ref: '#/components/schemas/NotificationSettingValue'
1478 $ref: '#/components/schemas/NotificationSettingValue'
1479 newInstanceFollower:
1480 $ref: '#/components/schemas/NotificationSettingValue'
1481 autoInstanceFollowing:
1482 $ref: '#/components/schemas/NotificationSettingValue'
1485 description: successful operation
1487 /users/me/history/videos:
1489 summary: List watched videos history
1495 - $ref: '#/components/parameters/start'
1496 - $ref: '#/components/parameters/count'
1497 - $ref: '#/components/parameters/search'
1500 description: successful operation
1504 $ref: '#/components/schemas/VideoListResponse'
1506 /users/me/history/videos/{videoId}:
1508 summary: Delete history element
1518 $ref: '#/components/schemas/Video/properties/id'
1521 description: successful operation
1523 /users/me/history/videos/remove:
1525 summary: Clear video history
1532 multipart/form-data:
1537 description: history before this date will be deleted
1542 description: successful operation
1544 /users/me/avatar/pick:
1546 summary: Update my user avatar
1553 description: successful operation
1560 $ref: '#/components/schemas/ActorImage'
1562 description: image file too large
1564 X-File-Maximum-Size:
1568 description: Maximum file size for the avatar
1571 multipart/form-data:
1576 description: The file to upload
1581 contentType: image/png, image/jpeg
1585 summary: Delete my avatar
1592 description: successful operation
1596 summary: List video ownership changes
1598 - Video Ownership Change
1603 description: successful operation
1605 '/videos/ownership/{id}/accept':
1607 summary: Accept ownership change request
1609 - Video Ownership Change
1613 - $ref: '#/components/parameters/idOrUUID'
1616 description: successful operation
1618 description: cannot terminate an ownership change of another user
1620 description: video ownership change not found
1622 '/videos/ownership/{id}/refuse':
1624 summary: Refuse ownership change request
1626 - Video Ownership Change
1630 - $ref: '#/components/parameters/idOrUUID'
1633 description: successful operation
1635 description: cannot terminate an ownership change of another user
1637 description: video ownership change not found
1639 '/videos/{id}/give-ownership':
1641 summary: Request ownership change
1643 - Video Ownership Change
1647 - $ref: '#/components/parameters/idOrUUID'
1651 application/x-www-form-urlencoded:
1661 description: successful operation
1663 description: changing video ownership to a remote account is not supported yet
1665 description: video not found
1669 summary: List videos
1670 operationId: getVideos
1674 - $ref: '#/components/parameters/categoryOneOf'
1675 - $ref: '#/components/parameters/isLive'
1676 - $ref: '#/components/parameters/tagsOneOf'
1677 - $ref: '#/components/parameters/tagsAllOf'
1678 - $ref: '#/components/parameters/licenceOneOf'
1679 - $ref: '#/components/parameters/languageOneOf'
1680 - $ref: '#/components/parameters/nsfw'
1681 - $ref: '#/components/parameters/isLocal'
1682 - $ref: '#/components/parameters/include'
1683 - $ref: '#/components/parameters/privacyOneOf'
1684 - $ref: '#/components/parameters/hasHLSFiles'
1685 - $ref: '#/components/parameters/hasWebtorrentFiles'
1686 - $ref: '#/components/parameters/skipCount'
1687 - $ref: '#/components/parameters/start'
1688 - $ref: '#/components/parameters/count'
1689 - $ref: '#/components/parameters/videosSort'
1692 description: successful operation
1696 $ref: '#/components/schemas/VideoListResponse'
1700 summary: List available video categories
1701 operationId: getCategories
1706 description: successful operation
1715 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1719 summary: List available video licences
1720 operationId: getLicences
1725 description: successful operation
1734 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1738 summary: List available video languages
1739 operationId: getLanguages
1744 description: successful operation
1753 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1757 summary: List available video privacy policies
1758 operationId: getPrivacyPolicies
1763 description: successful operation
1772 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1776 summary: Update a video
1777 operationId: putVideo
1783 - $ref: '#/components/parameters/idOrUUID'
1786 description: successful operation
1789 multipart/form-data:
1794 description: Video thumbnail file
1798 description: Video preview file
1802 $ref: '#/components/schemas/VideoCategorySet'
1804 $ref: '#/components/schemas/VideoLicenceSet'
1806 $ref: '#/components/schemas/VideoLanguageSet'
1808 $ref: '#/components/schemas/VideoPrivacySet'
1810 description: Video description
1813 description: Whether or not we wait transcoding before publish the video
1816 description: A text tell the audience how to support the video creator
1817 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1820 description: Whether or not this video contains sensitive content
1823 description: Video name
1828 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1837 description: Enable or disable comments for this video
1840 description: Enable or disable downloading for this video
1842 originallyPublishedAt:
1843 description: Date when the content was originally published
1847 $ref: '#/components/schemas/VideoScheduledUpdate'
1850 contentType: image/jpeg
1852 contentType: image/jpeg
1854 summary: Get a video
1855 operationId: getVideo
1859 - $ref: '#/components/parameters/idOrUUID'
1862 description: successful operation
1866 $ref: '#/components/schemas/VideoDetails'
1868 summary: Delete a video
1869 operationId: delVideo
1875 - $ref: '#/components/parameters/idOrUUID'
1878 description: successful operation
1880 '/videos/{id}/description':
1882 summary: Get complete video description
1883 operationId: getVideoDesc
1887 - $ref: '#/components/parameters/idOrUUID'
1890 description: successful operation
1899 **[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)**
1901 '/videos/{id}/views':
1903 summary: Add a view to a video
1904 operationId: addView
1908 - $ref: '#/components/parameters/idOrUUID'
1911 description: successful operation
1913 '/videos/{id}/watching':
1915 summary: Set watching progress of a video
1916 operationId: setProgress
1922 - $ref: '#/components/parameters/idOrUUID'
1927 $ref: '#/components/schemas/UserWatchingVideo'
1931 description: successful operation
1935 summary: Upload a video
1936 description: Uses a single request to upload a video.
1937 operationId: uploadLegacy
1945 description: successful operation
1949 $ref: '#/components/schemas/VideoUploadResponse'
1951 description: video didn't pass upload filter
1953 description: upload has timed out
1955 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1957 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1958 - `quota_reached` for quota limits wether daily or global
1960 X-File-Maximum-Size:
1964 description: Maximum file size for the video
1966 description: video type unsupported
1968 description: video unreadable
1971 multipart/form-data:
1973 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1976 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1978 contentType: image/jpeg
1980 contentType: image/jpeg
1985 USERNAME="<your_username>"
1986 PASSWORD="<your_password>"
1987 FILE_PATH="<your_file_path>"
1988 CHANNEL_ID="<your_channel_id>"
1990 API="https://peertube2.cpy.re/api/v1"
1993 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1994 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1995 token=$(curl -s "$API/users/token" \
1996 --data client_id="$client_id" \
1997 --data client_secret="$client_secret" \
1998 --data grant_type=password \
1999 --data username="$USERNAME" \
2000 --data password="$PASSWORD" \
2001 | jq -r ".access_token")
2004 curl -s "$API/videos/upload" \
2005 -H "Authorization: Bearer $token" \
2007 --form videofile=@"$FILE_PATH" \
2008 --form channelId=$CHANNEL_ID \
2011 /videos/upload-resumable:
2013 summary: Initialize the resumable upload of a video
2014 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2015 operationId: uploadResumableInit
2022 - name: X-Upload-Content-Length
2028 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2029 - name: X-Upload-Content-Type
2036 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2041 $ref: '#/components/schemas/VideoUploadRequestResumable'
2044 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2046 description: created
2052 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2058 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2060 Disambiguate via `type`:
2061 - `max_file_size_reached` for the absolute file size limit
2062 - `quota_reached` for quota limits whether daily or global
2064 description: video type unsupported
2066 summary: Send chunk for the resumable upload of a video
2067 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
2068 operationId: uploadResumable
2079 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2080 not valid anymore and you need to initialize a new upload.
2083 - name: Content-Range
2087 example: bytes 0-262143/2469036
2090 Specifies the bytes in the file that the request is uploading.
2092 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2093 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2094 - name: Content-Length
2101 Size of the chunk that the request is sending.
2103 The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
2104 doesn't mandate for chunks to have the same size throughout the upload sequence.
2106 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2107 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2110 application/octet-stream:
2116 description: last chunk received
2124 $ref: '#/components/schemas/VideoUploadResponse'
2126 description: resume incomplete
2131 example: bytes=0-262143
2137 description: video didn't pass upload filter
2139 description: upload not found
2141 description: chunk doesn't match range
2143 description: video unreadable
2145 description: too many concurrent requests
2147 description: upload is already being processed
2154 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2155 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2156 operationId: uploadResumableCancel
2167 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2168 not valid anymore and the upload session has already been deleted with its data ;-)
2171 - name: Content-Length
2179 description: upload cancelled
2186 description: upload not found
2190 summary: Import a video
2191 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2192 operationId: importVideo
2200 multipart/form-data:
2202 $ref: '#/components/schemas/VideoCreateImport'
2205 contentType: application/x-bittorrent
2207 contentType: image/jpeg
2209 contentType: image/jpeg
2212 description: successful operation
2216 $ref: '#/components/schemas/VideoUploadResponse'
2218 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2220 description: video didn't pass pre-import filter
2222 description: HTTP or Torrent/magnetURI import not enabled
2224 /videos/imports/{id}/cancel:
2226 summary: Cancel video import
2227 description: Cancel a pending video import
2233 - $ref: '#/components/parameters/id'
2236 description: successful operation
2238 /videos/imports/{id}:
2240 summary: Delete video import
2241 description: Delete ended video import
2247 - $ref: '#/components/parameters/id'
2250 description: successful operation
2254 summary: Create a live
2255 operationId: addLive
2263 description: successful operation
2267 $ref: '#/components/schemas/VideoUploadResponse'
2269 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2271 Disambiguate via `type`:
2272 - default type for a validation error
2273 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2275 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2277 Disambiguate via `type`:
2278 - `live_not_enabled` for a disabled live feature
2279 - `live_not_allowing_replay` for a disabled replay feature
2280 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2281 - `max_user_lives_limit_reached` for the user concurrent live limit
2284 multipart/form-data:
2289 description: Channel id that will contain this live video
2294 description: User can stream multiple times in a permanent live
2297 description: Live video/replay thumbnail file
2301 description: Live video/replay preview file
2305 $ref: '#/components/schemas/VideoPrivacySet'
2307 $ref: '#/components/schemas/VideoCategorySet'
2309 $ref: '#/components/schemas/VideoLicenceSet'
2311 $ref: '#/components/schemas/VideoLanguageSet'
2313 description: Live video/replay description
2316 description: A text tell the audience how to support the creator
2317 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2320 description: Whether or not this live video/replay contains sensitive content
2323 description: Live video/replay name
2328 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2337 description: Enable or disable comments for this live video/replay
2340 description: Enable or disable downloading for the replay of this live video
2347 contentType: image/jpeg
2349 contentType: image/jpeg
2353 summary: Get information about a live
2354 operationId: getLiveId
2361 - $ref: '#/components/parameters/idOrUUID'
2364 description: successful operation
2368 $ref: '#/components/schemas/LiveVideoResponse'
2370 summary: Update information about a live
2371 operationId: updateLiveId
2378 - $ref: '#/components/parameters/idOrUUID'
2383 $ref: '#/components/schemas/LiveVideoUpdate'
2386 description: successful operation
2388 description: bad parameters or trying to update a live that has already started
2390 description: trying to save replay of the live but saving replay is not enabled on the instance
2394 summary: List my abuses
2395 operationId: getMyAbuses
2404 description: only list the report with this id
2410 $ref: '#/components/schemas/AbuseStateSet'
2411 - $ref: '#/components/parameters/abusesSort'
2412 - $ref: '#/components/parameters/start'
2413 - $ref: '#/components/parameters/count'
2416 description: successful operation
2428 $ref: '#/components/schemas/Abuse'
2432 summary: List abuses
2433 operationId: getAbuses
2443 description: only list the report with this id
2446 - name: predefinedReason
2448 description: predefined reason the listed reports should contain
2450 $ref: '#/components/schemas/PredefinedAbuseReasons'
2453 description: plain search that will match with video titles, reporter names and more
2459 $ref: '#/components/schemas/AbuseStateSet'
2460 - name: searchReporter
2462 description: only list reports of a specific reporter
2465 - name: searchReportee
2466 description: only list reports of a specific reportee
2472 description: only list reports of a specific video
2475 - name: searchVideoChannel
2477 description: only list reports of a specific video channel
2482 description: only list deleted or blocklisted videos
2490 description: only list account, comment or video reports
2497 - $ref: '#/components/parameters/start'
2498 - $ref: '#/components/parameters/count'
2499 - $ref: '#/components/parameters/abusesSort'
2502 description: successful operation
2514 $ref: '#/components/schemas/Abuse'
2516 summary: Report an abuse
2529 description: Reason why the user reports this video
2534 $ref: '#/components/schemas/PredefinedAbuseReasons'
2539 description: Video id to report
2541 - $ref: '#/components/schemas/Video/properties/id'
2545 description: Timestamp in the video that marks the beginning of the report
2550 description: Timestamp in the video that marks the ending of the report
2556 description: Comment id to report
2558 - $ref: '#/components/schemas/VideoComment/properties/id'
2563 description: Account id to report
2569 description: successful operation
2579 $ref: '#/components/schemas/id'
2581 description: incorrect request parameters
2583 '/abuses/{abuseId}':
2585 summary: Update an abuse
2593 - $ref: '#/components/parameters/abuseId'
2601 $ref: '#/components/schemas/AbuseStateSet'
2604 description: Update the report comment visible only to the moderation team
2609 description: successful operation
2611 description: abuse not found
2615 summary: Delete an abuse
2621 - $ref: '#/components/parameters/abuseId'
2624 description: successful operation
2626 description: block not found
2628 '/abuses/{abuseId}/messages':
2630 summary: List messages of an abuse
2636 - $ref: '#/components/parameters/abuseId'
2639 description: successful operation
2651 $ref: '#/components/schemas/AbuseMessage'
2653 summary: Add message to an abuse
2659 - $ref: '#/components/parameters/abuseId'
2668 description: Message to send
2676 description: successful operation
2678 description: incorrect request parameters
2680 '/abuses/{abuseId}/messages/{abuseMessageId}':
2682 summary: Delete an abuse message
2688 - $ref: '#/components/parameters/abuseId'
2689 - $ref: '#/components/parameters/abuseMessageId'
2692 description: successful operation
2694 '/videos/{id}/blacklist':
2696 summary: Block a video
2697 operationId: addVideoBlock
2705 - $ref: '#/components/parameters/idOrUUID'
2708 description: successful operation
2710 summary: Unblock a video by its id
2711 operationId: delVideoBlock
2719 - $ref: '#/components/parameters/idOrUUID'
2722 description: successful operation
2724 description: block not found
2730 summary: List video blocks
2731 operationId: getVideoBlocks
2740 list only blocks that match this type:
2744 - `2`: automatic block that needs review
2752 description: plain search that will match with video titles, and more
2755 - $ref: '#/components/parameters/start'
2756 - $ref: '#/components/parameters/count'
2757 - $ref: '#/components/parameters/blacklistsSort'
2760 description: successful operation
2772 $ref: '#/components/schemas/VideoBlacklist'
2774 /videos/{id}/captions:
2776 summary: List captions of a video
2777 operationId: getVideoCaptions
2781 - $ref: '#/components/parameters/idOrUUID'
2784 description: successful operation
2796 $ref: '#/components/schemas/VideoCaption'
2798 /videos/{id}/captions/{captionLanguage}:
2800 summary: Add or replace a video caption
2801 operationId: addVideoCaption
2808 - $ref: '#/components/parameters/idOrUUID'
2809 - $ref: '#/components/parameters/captionLanguage'
2812 multipart/form-data:
2817 description: The file to upload.
2822 contentType: text/vtt, application/x-subrip, text/plain
2825 description: successful operation
2827 description: video or language not found
2829 summary: Delete a video caption
2830 operationId: delVideoCaption
2837 - $ref: '#/components/parameters/idOrUUID'
2838 - $ref: '#/components/parameters/captionLanguage'
2841 description: successful operation
2843 description: video or language or caption for that language not found
2847 summary: List video channels
2848 operationId: getVideoChannels
2852 - $ref: '#/components/parameters/start'
2853 - $ref: '#/components/parameters/count'
2854 - $ref: '#/components/parameters/sort'
2857 description: successful operation
2861 $ref: '#/components/schemas/VideoChannelList'
2863 summary: Create a video channel
2864 operationId: addVideoChannel
2871 description: successful operation
2881 $ref: '#/components/schemas/VideoChannel/properties/id'
2886 $ref: '#/components/schemas/VideoChannelCreate'
2888 '/video-channels/{channelHandle}':
2890 summary: Get a video channel
2891 operationId: getVideoChannel
2895 - $ref: '#/components/parameters/channelHandle'
2898 description: successful operation
2902 $ref: '#/components/schemas/VideoChannel'
2904 summary: Update a video channel
2905 operationId: putVideoChannel
2911 - $ref: '#/components/parameters/channelHandle'
2914 description: successful operation
2919 $ref: '#/components/schemas/VideoChannelUpdate'
2921 summary: Delete a video channel
2922 operationId: delVideoChannel
2928 - $ref: '#/components/parameters/channelHandle'
2931 description: successful operation
2933 '/video-channels/{channelHandle}/videos':
2935 summary: List videos of a video channel
2936 operationId: getVideoChannelVideos
2941 - $ref: '#/components/parameters/channelHandle'
2942 - $ref: '#/components/parameters/categoryOneOf'
2943 - $ref: '#/components/parameters/isLive'
2944 - $ref: '#/components/parameters/tagsOneOf'
2945 - $ref: '#/components/parameters/tagsAllOf'
2946 - $ref: '#/components/parameters/licenceOneOf'
2947 - $ref: '#/components/parameters/languageOneOf'
2948 - $ref: '#/components/parameters/nsfw'
2949 - $ref: '#/components/parameters/isLocal'
2950 - $ref: '#/components/parameters/include'
2951 - $ref: '#/components/parameters/privacyOneOf'
2952 - $ref: '#/components/parameters/hasHLSFiles'
2953 - $ref: '#/components/parameters/hasWebtorrentFiles'
2954 - $ref: '#/components/parameters/skipCount'
2955 - $ref: '#/components/parameters/start'
2956 - $ref: '#/components/parameters/count'
2957 - $ref: '#/components/parameters/videosSort'
2960 description: successful operation
2964 $ref: '#/components/schemas/VideoListResponse'
2966 '/video-channels/{channelHandle}/followers':
2970 summary: 'List followers of a video channel'
2973 operationId: getVideoChannelFollowers
2975 - $ref: '#/components/parameters/channelHandle'
2976 - $ref: '#/components/parameters/start'
2977 - $ref: '#/components/parameters/count'
2978 - $ref: '#/components/parameters/followersSort'
2979 - $ref: '#/components/parameters/search'
2982 description: successful operation
2994 $ref: '#/components/schemas/Follow'
2996 '/video-channels/{channelHandle}/avatar/pick':
2998 summary: Update channel avatar
3004 - $ref: '#/components/parameters/channelHandle'
3007 description: successful operation
3014 $ref: '#/components/schemas/ActorImage'
3016 description: image file too large
3018 X-File-Maximum-Size:
3022 description: Maximum file size for the avatar
3025 multipart/form-data:
3030 description: The file to upload.
3035 contentType: image/png, image/jpeg
3037 '/video-channels/{channelHandle}/avatar':
3039 summary: Delete channel avatar
3045 - $ref: '#/components/parameters/channelHandle'
3048 description: successful operation
3050 '/video-channels/{channelHandle}/banner/pick':
3052 summary: Update channel banner
3058 - $ref: '#/components/parameters/channelHandle'
3061 description: successful operation
3068 $ref: '#/components/schemas/ActorImage'
3070 description: image file too large
3072 X-File-Maximum-Size:
3076 description: Maximum file size for the banner
3079 multipart/form-data:
3084 description: The file to upload.
3089 contentType: image/png, image/jpeg
3091 '/video-channels/{channelHandle}/banner':
3093 summary: Delete channel banner
3099 - $ref: '#/components/parameters/channelHandle'
3102 description: successful operation
3104 /video-playlists/privacies:
3106 summary: List available playlist privacy policies
3107 operationId: getPlaylistPrivacyPolicies
3112 description: successful operation
3121 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3125 summary: List video playlists
3126 operationId: getPlaylists
3130 - $ref: '#/components/parameters/start'
3131 - $ref: '#/components/parameters/count'
3132 - $ref: '#/components/parameters/sort'
3135 description: successful operation
3147 $ref: '#/components/schemas/VideoPlaylist'
3149 summary: Create a video playlist
3150 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3151 operationId: addPlaylist
3158 description: successful operation
3168 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3170 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3172 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3175 multipart/form-data:
3180 description: Video playlist display name
3185 description: Video playlist thumbnail file
3189 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3191 description: Video playlist description
3197 - $ref: '#/components/schemas/id'
3198 description: Video channel in which the playlist will be published
3203 contentType: image/jpeg
3205 /video-playlists/{playlistId}:
3207 summary: Get a video playlist
3211 - $ref: '#/components/parameters/playlistId'
3214 description: successful operation
3218 $ref: '#/components/schemas/VideoPlaylist'
3220 summary: Update a video playlist
3221 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3228 description: successful operation
3230 - $ref: '#/components/parameters/playlistId'
3233 multipart/form-data:
3238 description: Video playlist display name
3243 description: Video playlist thumbnail file
3247 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3249 description: Video playlist description
3253 - $ref: '#/components/schemas/id'
3254 description: Video channel in which the playlist will be published
3257 contentType: image/jpeg
3259 summary: Delete a video playlist
3265 - $ref: '#/components/parameters/playlistId'
3268 description: successful operation
3270 /video-playlists/{playlistId}/videos:
3272 summary: 'List videos of a playlist'
3273 operationId: getVideoPlaylistVideos
3278 - $ref: '#/components/parameters/playlistId'
3279 - $ref: '#/components/parameters/start'
3280 - $ref: '#/components/parameters/count'
3283 description: successful operation
3287 $ref: '#/components/schemas/VideoListResponse'
3289 summary: Add a video in a playlist
3290 operationId: addVideoPlaylistVideo
3297 - $ref: '#/components/parameters/playlistId'
3300 description: successful operation
3306 videoPlaylistElement:
3320 - $ref: '#/components/schemas/Video/properties/uuid'
3321 - $ref: '#/components/schemas/Video/properties/id'
3322 description: Video to add in the playlist
3326 description: Start the video at this specific timestamp
3330 description: Stop the video at this specific timestamp
3334 /video-playlists/{playlistId}/videos/reorder:
3336 summary: 'Reorder a playlist'
3337 operationId: reorderVideoPlaylist
3343 - $ref: '#/components/parameters/playlistId'
3346 description: successful operation
3355 description: 'Start position of the element to reorder'
3357 insertAfterPosition:
3359 description: 'New position for the block to reorder, to add the block before the first element'
3363 description: 'How many element from `startPosition` to reorder'
3367 - insertAfterPosition
3369 /video-playlists/{playlistId}/videos/{playlistElementId}:
3371 summary: Update a playlist element
3372 operationId: putVideoPlaylistVideo
3378 - $ref: '#/components/parameters/playlistId'
3379 - $ref: '#/components/parameters/playlistElementId'
3382 description: successful operation
3392 description: Start the video at this specific timestamp
3396 description: Stop the video at this specific timestamp
3398 summary: Delete an element from a playlist
3399 operationId: delVideoPlaylistVideo
3405 - $ref: '#/components/parameters/playlistId'
3406 - $ref: '#/components/parameters/playlistElementId'
3409 description: successful operation
3411 '/users/me/video-playlists/videos-exist':
3413 summary: Check video exists in my playlists
3422 description: The video ids to check
3426 $ref: '#/components/schemas/Video/properties/id'
3429 description: successful operation
3451 '/accounts/{name}/video-channels':
3453 summary: List video channels of an account
3458 - $ref: '#/components/parameters/name'
3461 description: include view statistics for the last 30 days (only if authentified as the account user)
3464 - $ref: '#/components/parameters/start'
3465 - $ref: '#/components/parameters/count'
3466 - $ref: '#/components/parameters/sort'
3469 description: successful operation
3473 $ref: '#/components/schemas/VideoChannelList'
3475 '/accounts/{name}/ratings':
3477 summary: List ratings of an account
3483 - $ref: '#/components/parameters/name'
3484 - $ref: '#/components/parameters/start'
3485 - $ref: '#/components/parameters/count'
3486 - $ref: '#/components/parameters/sort'
3490 description: Optionally filter which ratings to retrieve
3498 description: successful operation
3504 $ref: '#/components/schemas/VideoRating'
3506 '/videos/{id}/comment-threads':
3508 summary: List threads of a video
3512 - $ref: '#/components/parameters/idOrUUID'
3513 - $ref: '#/components/parameters/start'
3514 - $ref: '#/components/parameters/count'
3515 - $ref: '#/components/parameters/commentsSort'
3518 description: successful operation
3522 $ref: '#/components/schemas/CommentThreadResponse'
3524 summary: Create a thread
3530 - $ref: '#/components/parameters/idOrUUID'
3533 description: successful operation
3537 $ref: '#/components/schemas/CommentThreadPostResponse'
3539 description: video does not exist
3548 - $ref: '#/components/schemas/VideoComment/properties/text'
3554 '/videos/{id}/comment-threads/{threadId}':
3556 summary: Get a thread
3560 - $ref: '#/components/parameters/idOrUUID'
3561 - $ref: '#/components/parameters/threadId'
3564 description: successful operation
3568 $ref: '#/components/schemas/VideoCommentThreadTree'
3570 '/videos/{id}/comments/{commentId}':
3572 summary: Reply to a thread of a video
3578 - $ref: '#/components/parameters/idOrUUID'
3579 - $ref: '#/components/parameters/commentId'
3582 description: successful operation
3586 $ref: '#/components/schemas/CommentThreadPostResponse'
3588 description: thread or video does not exist
3597 - $ref: '#/components/schemas/VideoComment/properties/text'
3603 summary: Delete a comment or a reply
3609 - $ref: '#/components/parameters/idOrUUID'
3610 - $ref: '#/components/parameters/commentId'
3613 description: successful operation
3615 description: cannot remove comment of another user
3617 description: comment or video does not exist
3619 description: comment is already deleted
3621 '/videos/{id}/rate':
3623 summary: Like/dislike a video
3629 - $ref: '#/components/parameters/idOrUUID'
3645 description: successful operation
3647 description: video does not exist
3651 summary: Delete video HLS files
3657 operationId: delVideoHLS
3659 - $ref: '#/components/parameters/idOrUUID'
3662 description: successful operation
3664 description: video does not exist
3665 '/videos/{id}/webtorrent':
3667 summary: Delete video WebTorrent files
3673 operationId: delVideoWebTorrent
3675 - $ref: '#/components/parameters/idOrUUID'
3678 description: successful operation
3680 description: video does not exist
3682 '/videos/{id}/transcoding':
3684 summary: Create a transcoding job
3690 operationId: createVideoTranscoding
3692 - $ref: '#/components/parameters/idOrUUID'
3708 description: successful operation
3710 description: video does not exist
3716 summary: Search videos
3717 operationId: searchVideos
3722 allowEmptyValue: false
3724 String to search. If the user can make a remote URI search, and the string is an URI then the
3725 PeerTube instance will fetch the remote object and add it to its database. Then,
3726 you can use the REST API to fetch the complete video information and interact with it.
3729 - $ref: '#/components/parameters/categoryOneOf'
3730 - $ref: '#/components/parameters/isLive'
3731 - $ref: '#/components/parameters/tagsOneOf'
3732 - $ref: '#/components/parameters/tagsAllOf'
3733 - $ref: '#/components/parameters/licenceOneOf'
3734 - $ref: '#/components/parameters/languageOneOf'
3735 - $ref: '#/components/parameters/nsfw'
3736 - $ref: '#/components/parameters/isLocal'
3737 - $ref: '#/components/parameters/include'
3738 - $ref: '#/components/parameters/privacyOneOf'
3739 - $ref: '#/components/parameters/hasHLSFiles'
3740 - $ref: '#/components/parameters/hasWebtorrentFiles'
3741 - $ref: '#/components/parameters/skipCount'
3742 - $ref: '#/components/parameters/start'
3743 - $ref: '#/components/parameters/count'
3744 - $ref: '#/components/parameters/searchTarget'
3745 - $ref: '#/components/parameters/videosSearchSort'
3748 description: Get videos that are published after this date
3754 description: Get videos that are published before this date
3758 - name: originallyPublishedStartDate
3760 description: Get videos that are originally published after this date
3764 - name: originallyPublishedEndDate
3766 description: Get videos that are originally published before this date
3772 description: Get videos that have this minimum duration
3777 description: Get videos that have this maximum duration
3781 'searchTarget === search-index':
3782 $ref: '#/components/callbacks/searchIndex'
3785 description: successful operation
3789 $ref: '#/components/schemas/VideoListResponse'
3791 description: search index unavailable
3793 /search/video-channels:
3797 summary: Search channels
3798 operationId: searchChannels
3804 String to search. If the user can make a remote URI search, and the string is an URI then the
3805 PeerTube instance will fetch the remote object and add it to its database. Then,
3806 you can use the REST API to fetch the complete channel information and interact with it.
3809 - $ref: '#/components/parameters/start'
3810 - $ref: '#/components/parameters/count'
3811 - $ref: '#/components/parameters/searchTarget'
3812 - $ref: '#/components/parameters/sort'
3814 'searchTarget === search-index':
3815 $ref: '#/components/callbacks/searchIndex'
3818 description: successful operation
3822 $ref: '#/components/schemas/VideoChannelList'
3824 description: search index unavailable
3826 /search/video-playlists:
3830 summary: Search playlists
3831 operationId: searchPlaylists
3837 String to search. If the user can make a remote URI search, and the string is an URI then the
3838 PeerTube instance will fetch the remote object and add it to its database. Then,
3839 you can use the REST API to fetch the complete playlist information and interact with it.
3842 - $ref: '#/components/parameters/start'
3843 - $ref: '#/components/parameters/count'
3844 - $ref: '#/components/parameters/searchTarget'
3845 - $ref: '#/components/parameters/sort'
3847 'searchTarget === search-index':
3848 $ref: '#/components/callbacks/searchIndex'
3851 description: successful operation
3863 $ref: '#/components/schemas/VideoPlaylist'
3865 description: search index unavailable
3872 summary: Get block status of accounts/hosts
3877 description: 'Check if these accounts are blocked'
3878 example: [ 'goofy@example.com', 'donald@example.com' ]
3886 description: 'Check if these hosts are blocked'
3887 example: [ 'example.com' ]
3894 description: successful operation
3898 $ref: '#/components/schemas/BlockStatus'
3900 /server/blocklist/accounts:
3904 summary: List account blocks
3909 - $ref: '#/components/parameters/start'
3910 - $ref: '#/components/parameters/count'
3911 - $ref: '#/components/parameters/sort'
3914 description: successful operation
3918 summary: Block an account
3930 example: chocobozzz@example.org
3931 description: account to block, in the form `username@domain`
3936 description: successful operation
3938 description: self-blocking forbidden
3940 '/server/blocklist/accounts/{accountName}':
3944 summary: Unblock an account by its handle
3952 description: account to unblock, in the form `username@domain`
3957 description: successful operation
3959 description: account or account block does not exist
3961 /server/blocklist/servers:
3965 summary: List server blocks
3970 - $ref: '#/components/parameters/start'
3971 - $ref: '#/components/parameters/count'
3972 - $ref: '#/components/parameters/sort'
3975 description: successful operation
3979 summary: Block a server
3992 description: server domain to block
3997 description: successful operation
3999 description: self-blocking forbidden
4001 '/server/blocklist/servers/{host}':
4005 summary: Unblock a server by its domain
4013 description: server domain to unblock
4019 description: successful operation
4021 description: account block does not exist
4023 /server/redundancy/{host}:
4026 - Instance Redundancy
4027 summary: Update a server redundancy policy
4035 description: server domain to mirror
4047 description: allow mirroring of the host's local videos
4052 description: successful operation
4054 description: server is not already known
4056 /server/redundancy/videos:
4060 summary: List videos being mirrored
4061 operationId: getMirroredVideos
4069 description: direction of the mirror
4075 - $ref: '#/components/parameters/start'
4076 - $ref: '#/components/parameters/count'
4077 - $ref: '#/components/parameters/videoRedundanciesSort'
4080 description: successful operation
4086 $ref: '#/components/schemas/VideoRedundancy'
4090 summary: Mirror a video
4091 operationId: putMirroredVideo
4102 $ref: '#/components/schemas/Video/properties/id'
4107 description: successful operation
4109 description: cannot mirror a local video
4111 description: video does not exist
4113 description: video is already mirrored
4115 /server/redundancy/videos/{redundancyId}:
4119 summary: Delete a mirror done on a video
4120 operationId: delMirroredVideo
4125 - name: redundancyId
4128 description: id of an existing redundancy on a video
4133 description: successful operation
4135 description: video redundancy not found
4137 '/feeds/video-comments.{format}':
4141 summary: List comments on videos
4142 operationId: getSyndicatedComments
4147 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4160 description: 'limit listing to a specific video'
4165 description: 'limit listing to a specific account'
4170 description: 'limit listing to a specific account'
4173 - name: videoChannelId
4175 description: 'limit listing to a specific video channel'
4178 - name: videoChannelName
4180 description: 'limit listing to a specific video channel'
4185 description: successful operation
4190 default: 'max-age=900' # 15 min cache
4194 $ref: '#/components/schemas/VideoCommentsForXML'
4197 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4198 application/rss+xml:
4200 $ref: '#/components/schemas/VideoCommentsForXML'
4203 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4206 $ref: '#/components/schemas/VideoCommentsForXML'
4209 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4210 application/atom+xml:
4212 $ref: '#/components/schemas/VideoCommentsForXML'
4215 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4221 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4223 x-summary: field inconsistencies
4226 - videoId filter is mixed with a channel filter
4228 description: video, video channel or account not found
4230 description: accept header unsupported
4232 '/feeds/videos.{format}':
4236 summary: List videos
4237 operationId: getSyndicatedVideos
4242 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4255 description: 'limit listing to a specific account'
4260 description: 'limit listing to a specific account'
4263 - name: videoChannelId
4265 description: 'limit listing to a specific video channel'
4268 - name: videoChannelName
4270 description: 'limit listing to a specific video channel'
4273 - $ref: '#/components/parameters/sort'
4274 - $ref: '#/components/parameters/nsfw'
4275 - $ref: '#/components/parameters/isLocal'
4276 - $ref: '#/components/parameters/include'
4277 - $ref: '#/components/parameters/privacyOneOf'
4278 - $ref: '#/components/parameters/hasHLSFiles'
4279 - $ref: '#/components/parameters/hasWebtorrentFiles'
4282 description: successful operation
4287 default: 'max-age=900' # 15 min cache
4291 $ref: '#/components/schemas/VideosForXML'
4294 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4295 application/rss+xml:
4297 $ref: '#/components/schemas/VideosForXML'
4300 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4303 $ref: '#/components/schemas/VideosForXML'
4306 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4307 application/atom+xml:
4309 $ref: '#/components/schemas/VideosForXML'
4312 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4318 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4320 description: video channel or account not found
4322 description: accept header unsupported
4324 '/feeds/subscriptions.{format}':
4329 summary: List videos of subscriptions tied to a token
4330 operationId: getSyndicatedSubscriptionVideos
4335 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4348 description: limit listing to a specific account
4354 description: private token allowing access
4358 - $ref: '#/components/parameters/sort'
4359 - $ref: '#/components/parameters/nsfw'
4360 - $ref: '#/components/parameters/isLocal'
4361 - $ref: '#/components/parameters/include'
4362 - $ref: '#/components/parameters/privacyOneOf'
4363 - $ref: '#/components/parameters/hasHLSFiles'
4364 - $ref: '#/components/parameters/hasWebtorrentFiles'
4367 description: successful operation
4372 default: 'max-age=900' # 15 min cache
4376 $ref: '#/components/schemas/VideosForXML'
4377 application/rss+xml:
4379 $ref: '#/components/schemas/VideosForXML'
4382 $ref: '#/components/schemas/VideosForXML'
4383 application/atom+xml:
4385 $ref: '#/components/schemas/VideosForXML'
4390 description: accept header unsupported
4396 summary: List plugins
4397 operationId: getPlugins
4410 - $ref: '#/components/parameters/start'
4411 - $ref: '#/components/parameters/count'
4412 - $ref: '#/components/parameters/sort'
4415 description: successful operation
4419 $ref: '#/components/schemas/PluginResponse'
4425 summary: List available plugins
4426 operationId: getAvailablePlugins
4439 - name: currentPeerTubeEngine
4443 - $ref: '#/components/parameters/start'
4444 - $ref: '#/components/parameters/count'
4445 - $ref: '#/components/parameters/sort'
4448 description: successful operation
4452 $ref: '#/components/schemas/PluginResponse'
4454 description: plugin index unavailable
4460 summary: Install a plugin
4461 operationId: addPlugin
4474 example: peertube-plugin-auth-ldap
4477 additionalProperties: false
4484 additionalProperties: false
4487 description: successful operation
4489 description: should have either `npmName` or `path` set
4495 summary: Update a plugin
4496 operationId: updatePlugin
4509 example: peertube-plugin-auth-ldap
4512 additionalProperties: false
4519 additionalProperties: false
4522 description: successful operation
4524 description: should have either `npmName` or `path` set
4526 description: existing plugin not found
4532 summary: Uninstall a plugin
4533 operationId: uninstallPlugin
4545 description: name of the plugin/theme in its package.json
4546 example: peertube-plugin-auth-ldap
4551 description: successful operation
4553 description: existing plugin not found
4559 summary: Get a plugin
4560 operationId: getPlugin
4565 - $ref: '#/components/parameters/npmName'
4568 description: successful operation
4572 $ref: '#/components/schemas/Plugin'
4574 description: plugin not found
4576 /plugins/{npmName}/settings:
4580 summary: Set a plugin's settings
4585 - $ref: '#/components/parameters/npmName'
4594 additionalProperties: true
4597 description: successful operation
4599 description: plugin not found
4601 /plugins/{npmName}/public-settings:
4605 summary: Get a plugin's public settings
4607 - $ref: '#/components/parameters/npmName'
4610 description: successful operation
4615 additionalProperties: true
4617 description: plugin not found
4619 /plugins/{npmName}/registered-settings:
4623 summary: Get a plugin's registered settings
4628 - $ref: '#/components/parameters/npmName'
4631 description: successful operation
4636 additionalProperties: true
4638 description: plugin not found
4641 - url: 'https://peertube2.cpy.re/api/v1'
4642 description: Live Test Server (live data - latest nightly version)
4643 - url: 'https://peertube3.cpy.re/api/v1'
4644 description: Live Test Server (live data - latest RC version)
4645 - url: 'https://peertube.cpy.re/api/v1'
4646 description: Live Test Server (live data - stable version)
4653 description: Offset used to paginate results
4661 description: "Number of items to return"
4671 description: Sort column
4679 description: Plain text search, applied to various parts of the model depending on endpoint
4687 If the administrator enabled search index support, you can override the default search target.
4690 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4691 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4692 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4693 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4694 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4695 * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch
4696 the data from the origin instance API
4706 description: Sort videos by criteria
4722 description: Sort videos by criteria
4737 description: Sort comments by criteria
4747 description: Sort blocklists by criteria
4763 description: Plain text search that will match with user usernames or emails
4770 description: Filter results down to (un)banned users
4777 description: Sort users by criteria
4788 description: Sort abuses by criteria
4795 videoRedundanciesSort:
4799 description: Sort abuses by criteria
4808 description: Sort followers by criteria
4817 description: The username or handle of the account
4820 example: chocobozzz | chocobozzz@example.org
4825 description: Entity id
4827 $ref: '#/components/schemas/id'
4832 description: The object id, uuid or short uuid
4835 - $ref: '#/components/schemas/id'
4836 - $ref: '#/components/schemas/UUIDv4'
4837 - $ref: '#/components/schemas/shortUUID'
4842 description: Playlist id
4844 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4846 name: playlistElementId
4849 description: Playlist element id
4851 $ref: '#/components/schemas/id'
4856 description: Abuse id
4858 $ref: '#/components/schemas/Abuse/properties/id'
4860 name: abuseMessageId
4863 description: Abuse message id
4865 $ref: '#/components/schemas/AbuseMessage/properties/id'
4867 name: captionLanguage
4870 description: The caption language
4872 $ref: '#/components/schemas/VideoLanguageSet'
4877 description: The video channel handle
4880 example: my_username | my_username@example.com
4882 name: subscriptionHandle
4885 description: The subscription handle
4888 example: my_username | my_username@example.com
4893 description: The thread id (root comment id)
4900 description: The comment id
4902 $ref: '#/components/schemas/VideoComment/properties/id'
4907 description: whether or not the video is a live
4914 description: category id of the video (see [/videos/categories](#operation/getCategories))
4917 - $ref: '#/components/schemas/VideoCategorySet'
4920 $ref: '#/components/schemas/VideoCategorySet'
4927 description: tag(s) of the video
4941 description: tag(s) of the video, where all should be present in the video
4954 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4957 - $ref: '#/components/schemas/VideoLanguageSet'
4960 $ref: '#/components/schemas/VideoLanguageSet'
4967 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4970 - $ref: '#/components/schemas/VideoLicenceSet'
4973 $ref: '#/components/schemas/VideoLicenceSet'
4980 description: if you don't need the `total` in the response
4991 description: whether to include nsfw videos, if any
5003 description: '**PeerTube >= 4.0** Display only local or remote videos'
5010 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5012 name: hasWebtorrentFiles
5017 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5023 $ref: '#/components/schemas/VideoPrivacySet'
5024 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5038 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5042 - `1` NOT_PUBLISHED_STATE
5053 description: list of uris to check if each is part of the user subscriptions
5063 description: name of the plugin/theme on npmjs.com or in its package.json
5066 example: peertube-plugin-auth-ldap
5071 description: job type
5075 - activitypub-follow
5076 - activitypub-http-broadcast
5077 - activitypub-http-fetcher
5078 - activitypub-http-unicast
5083 - videos-views-stats
5084 - activitypub-refresher
5109 Authenticating via OAuth requires the following steps:
5110 - Have an activated account
5111 - [Generate] an access token for that account at `/api/v1/users/token`.
5112 - Make requests with the *Authorization: Bearer <token\>* header
5113 - Profit, depending on the role assigned to the account
5115 Note that the __access token is valid for 1 day__ and is given
5116 along with a __refresh token valid for 2 weeks__.
5118 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5122 tokenUrl: /api/v1/users/token
5125 moderator: Moderator scope
5128 # Resuable core properties
5136 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5137 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5142 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5143 example: 2y84q2MQUMWPbiEcxNXMgC
5146 description: immutable name of the user, used to find or mention its actor
5148 pattern: '/^[a-z0-9._]+$/'
5153 description: immutable name of the channel, used to interact with its actor
5154 example: framasoft_videos
5155 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5166 description: category id of the video (see [/videos/categories](#operation/getCategories))
5168 VideoConstantNumber-Category:
5171 $ref: '#/components/schemas/VideoCategorySet'
5174 example: Science & Technology
5178 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5180 VideoConstantNumber-Licence:
5183 $ref: '#/components/schemas/VideoLicenceSet'
5186 example: Attribution - Share Alike
5190 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5192 VideoConstantString-Language:
5195 $ref: '#/components/schemas/VideoLanguageSet'
5200 VideoPlaylistPrivacySet:
5206 description: Video playlist privacy policy (see [/video-playlists/privacies])
5207 VideoPlaylistPrivacyConstant:
5210 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5214 VideoPlaylistTypeSet:
5219 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5220 VideoPlaylistTypeConstant:
5223 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5234 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5235 VideoPrivacyConstant:
5238 $ref: '#/components/schemas/VideoPrivacySet'
5246 additionalProperties:
5247 x-additionalPropertiesName: account
5256 additionalProperties:
5257 x-additionalPropertiesName: host
5278 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5285 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5296 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5306 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5310 $ref: '#/components/schemas/AbuseStateSet'
5313 AbusePredefinedReasons:
5326 example: [spamOrMisleading]
5331 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5333 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5335 VideoResolutionConstant:
5336 description: resolutions and their labels for the video
5339 $ref: '#/components/schemas/VideoResolutionSet'
5343 VideoScheduledUpdate:
5346 $ref: '#/components/schemas/VideoPrivacySet'
5350 description: When to update the video
5370 - $ref: '#/components/schemas/ActorImage'
5371 VideoChannelSummary:
5374 $ref: '#/components/schemas/id'
5388 - $ref: '#/components/schemas/ActorImage'
5402 - $ref: '#/components/schemas/Video'
5409 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5410 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5412 $ref: '#/components/schemas/VideoResolutionConstant'
5415 description: Video file size in bytes
5418 description: Direct URL of the torrent file
5422 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5426 description: Direct URL of the video
5430 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5434 description: Frames per second of the video file
5438 description: URL dereferencing the output of ffprobe on the file
5439 VideoStreamingPlaylists:
5444 $ref: '#/components/schemas/id'
5452 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5453 VideoStreamingPlaylists-HLS:
5464 Video files associated to this playlist.
5466 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5468 $ref: '#/components/schemas/VideoFile'
5480 $ref: '#/components/schemas/Video/properties/id'
5482 $ref: '#/components/schemas/Video/properties/uuid'
5484 $ref: '#/components/schemas/Video/properties/name'
5488 description: object id for the video
5490 - $ref: '#/components/schemas/id'
5492 description: universal identifier for the video, that can be used across instances
5494 - $ref: '#/components/schemas/UUIDv4'
5497 - $ref: '#/components/schemas/shortUUID'
5503 example: 2017-10-01T10:52:46.396Z
5504 description: time at which the video object was first drafted
5508 example: 2018-10-01T10:52:46.396Z
5509 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5513 example: 2021-05-04T08:01:01.502Z
5514 description: last time the video's metadata was modified
5515 originallyPublishedAt:
5518 example: 2010-10-01T10:52:46.396Z
5519 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5522 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5523 description: category in which the video is classified
5526 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5527 description: licence under which the video is distributed
5530 - $ref: '#/components/schemas/VideoConstantString-Language'
5531 description: main language used in the video
5534 - $ref: '#/components/schemas/VideoPrivacyConstant'
5535 description: privacy policy used to distribute the video
5539 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5540 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5544 truncated description of the video, written in Markdown.
5545 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5550 description: duration of the video in seconds
5555 description: title of the video
5556 example: What is PeerTube?
5561 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5564 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5567 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5584 - $ref: '#/components/schemas/VideoStateConstant'
5585 description: represents the internal state of the video processing within the PeerTube instance
5589 - $ref: '#/components/schemas/VideoScheduledUpdate'
5597 $ref: '#/components/schemas/AccountSummary'
5599 $ref: '#/components/schemas/VideoChannelSummary'
5608 - $ref: '#/components/schemas/Video'
5613 description: If the video is a live, you have the amount of current viewers
5616 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5617 description: path at which to get the full description of maximum `10000` characters
5620 description: A text tell the audience how to support the video creator
5621 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5625 $ref: '#/components/schemas/VideoChannel'
5627 $ref: '#/components/schemas/Account'
5629 example: [flowers, gardening]
5647 - https://peertube2.cpy.re/tracker/announce
5648 - wss://peertube2.cpy.re/tracker/socket
5652 $ref: '#/components/schemas/VideoFile'
5654 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5656 - field will be empty
5657 - video files will be found in `streamingPlaylists[].files` field
5661 $ref: '#/components/schemas/VideoStreamingPlaylists'
5663 HLS playlists/manifest files. If HLS is disabled on the server:
5665 - field will be empty
5666 - video files will be found in `files` field
5667 FileRedundancyInformation:
5670 $ref: '#/components/schemas/id'
5695 $ref: '#/components/schemas/id'
5702 $ref: '#/components/schemas/UUIDv4'
5709 $ref: '#/components/schemas/FileRedundancyInformation'
5713 $ref: '#/components/schemas/FileRedundancyInformation'
5714 VideoImportStateConstant:
5722 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5729 additionalProperties: false
5733 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5734 required: [targetUrl]
5737 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5738 required: [magnetUri]
5741 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5742 required: [torrentfile]
5743 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5752 - $ref: '#/components/schemas/id'
5756 description: remote URL where to find the import's source video
5757 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5761 description: magnet URI allowing to resolve the import's source video
5762 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5767 description: Torrent file containing only the video file
5774 - $ref: '#/components/schemas/VideoImportStateConstant'
5790 - $ref: '#/components/schemas/Video'
5800 $ref: '#/components/schemas/VideoImport'
5804 $ref: '#/components/schemas/id'
5807 example: The video is a spam
5811 $ref: '#/components/schemas/AbusePredefinedReasons'
5813 $ref: '#/components/schemas/Account'
5815 $ref: '#/components/schemas/AbuseStateConstant'
5818 example: Decided to ban the server since it spams us regularly
5822 $ref: '#/components/schemas/VideoInfo'
5829 $ref: '#/components/schemas/id'
5840 $ref: '#/components/schemas/AccountSummary'
5844 $ref: '#/components/schemas/id'
5846 $ref: '#/components/schemas/Video/properties/id'
5858 $ref: '#/components/schemas/UUIDv4'
5876 $ref: '#/components/schemas/id'
5878 $ref: '#/components/schemas/UUIDv4'
5881 - $ref: '#/components/schemas/shortUUID'
5904 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5906 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5908 $ref: '#/components/schemas/AccountSummary'
5910 $ref: '#/components/schemas/VideoChannelSummary'
5914 $ref: '#/components/schemas/id'
5921 description: Text of the comment
5923 example: This video is wonderful!
5925 $ref: '#/components/schemas/id'
5929 - $ref: '#/components/schemas/id'
5931 $ref: '#/components/schemas/Video/properties/id'
5946 totalRepliesFromVideoAuthor:
5953 $ref: '#/components/schemas/Account'
5954 VideoCommentThreadTree:
5957 $ref: '#/components/schemas/VideoComment'
5961 $ref: '#/components/schemas/VideoCommentThreadTree'
5965 $ref: '#/components/schemas/VideoConstantString-Language'
5981 $ref: '#/components/schemas/id'
5998 $ref: '#/components/schemas/id'
6003 description: immutable name of the actor, used to find or mention it
6005 - $ref: '#/components/schemas/username'
6009 description: server on which the actor is resident
6010 hostRedundancyAllowed:
6012 description: whether this actor's host allows redundancy of its videos
6016 description: number of actors subscribed to by this actor, as seen by this instance
6020 description: number of followers of this actor, as seen by this instance
6028 $ref: '#/components/schemas/ActorImage'
6031 - $ref: '#/components/schemas/Actor'
6034 description: object id for the user tied to this account
6036 - $ref: '#/components/schemas/User/properties/id'
6039 description: editable name of the account, displayed in its representations
6044 description: text or bio displayed on the account's profile
6050 description: timestamp within the video, in seconds
6117 allowedForCurrentIP:
6119 requiresEmailVerification:
6137 $ref: '#/components/schemas/VideoResolutionSet'
6222 example: 16810141515
6331 requiresEmailVerification:
6346 description: Settings that apply to new users, if registration is enabled
6350 example: 16810141515
6356 description: Settings pertaining to transcoding jobs
6360 allowAdditionalExtensions:
6362 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6365 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6368 description: Amount of threads used by ffmpeg for 1 transcoding job
6371 description: Amount of transcoding jobs to execute in parallel
6377 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6380 description: Resolutions to transcode _new videos_ to
6402 description: WebTorrent-specific settings
6408 description: HLS-specific settings
6458 $ref: '#/components/schemas/id'
6460 $ref: '#/components/schemas/Actor'
6462 $ref: '#/components/schemas/Actor'
6465 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6478 PredefinedAbuseReasons:
6479 description: Reason categories that help triage reports
6497 $ref: '#/components/schemas/id'
6509 - activitypub-http-unicast
6510 - activitypub-http-broadcast
6511 - activitypub-http-fetcher
6512 - activitypub-follow
6517 - videos-views-stats
6518 - activitypub-refresher
6522 additionalProperties: true
6525 additionalProperties: true
6541 $ref: '#/components/schemas/id'
6546 $ref: '#/components/schemas/id'
6547 VideoUploadRequestCommon:
6550 description: Video name
6552 example: What is PeerTube?
6556 description: Channel id that will contain this video
6561 $ref: '#/components/schemas/VideoPrivacySet'
6563 $ref: '#/components/schemas/VideoCategorySet'
6565 $ref: '#/components/schemas/VideoLicenceSet'
6567 $ref: '#/components/schemas/VideoLanguageSet'
6569 description: Video description
6572 **[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)**
6574 description: Whether or not we wait transcoding before publish the video
6577 description: A text tell the audience how to support the video creator
6578 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6581 description: Whether or not this video contains sensitive content
6584 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6597 description: Enable or disable comments for this video
6600 description: Enable or disable downloading for this video
6602 originallyPublishedAt:
6603 description: Date when the content was originally published
6607 $ref: '#/components/schemas/VideoScheduledUpdate'
6609 description: Video thumbnail file
6613 description: Video preview file
6619 VideoUploadRequestLegacy:
6621 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6627 description: Video file
6630 VideoUploadRequestResumable:
6632 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6638 description: Video filename including extension
6641 example: what_is_peertube.mp4
6643 description: Video thumbnail file
6647 description: Video preview file
6650 VideoUploadResponse:
6656 $ref: '#/components/schemas/Video/properties/id'
6658 $ref: '#/components/schemas/Video/properties/uuid'
6660 $ref: '#/components/schemas/Video/properties/shortUUID'
6661 CommentThreadResponse:
6670 $ref: '#/components/schemas/VideoComment'
6671 CommentThreadPostResponse:
6674 $ref: '#/components/schemas/VideoComment'
6684 $ref: '#/components/schemas/Video'
6688 $ref: '#/components/schemas/Account'
6691 description: Automatically start playing the upcoming video after the currently playing video
6692 autoPlayNextVideoPlaylist:
6694 description: Automatically start playing the video on the playlist after the currently playing video
6697 description: Automatically start playing the video on the watch page
6707 description: The user email
6710 description: Has the user confirmed their email address?
6713 - $ref: '#/components/schemas/id'
6717 description: Auth plugin to use to authenticate the user
6721 noInstanceConfigWarningModal:
6723 noAccountSetupWarningModal:
6728 $ref: '#/components/schemas/NSFWPolicy'
6730 $ref: '#/components/schemas/UserRole'
6739 description: Theme enabled by this user
6741 $ref: '#/components/schemas/username'
6745 $ref: '#/components/schemas/VideoChannel'
6748 description: The user video quota in bytes
6752 description: The user daily video quota in bytes
6756 description: Enable P2P in the player
6759 - $ref: '#/components/schemas/User'
6761 # optionally present fields: they require WITH_STATS scope
6764 description: Count of videos published
6767 description: Count of reports/abuses of which the user is a target
6768 abusesAcceptedCount:
6770 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6773 description: Count of reports/abuses created by the user
6776 description: Count of comments published
6780 $ref: '#/components/schemas/username'
6782 $ref: '#/components/schemas/password'
6786 description: The user email
6789 description: The user video quota in bytes
6793 description: The user daily video quota in bytes
6796 $ref: '#/components/schemas/usernameChannel'
6798 $ref: '#/components/schemas/UserRole'
6800 $ref: '#/components/schemas/UserAdminFlags'
6811 description: The updated email of the user
6813 - $ref: '#/components/schemas/User/properties/email'
6816 description: Set the email as verified
6819 description: The updated video quota of the user in bytes
6822 description: The updated daily video quota of the user in bytes
6826 description: The auth plugin to use to authenticate the user
6827 example: 'peertube-plugin-auth-saml2'
6829 $ref: '#/components/schemas/UserRole'
6831 $ref: '#/components/schemas/UserAdminFlags'
6833 $ref: '#/components/schemas/password'
6835 # see shared/models/users/user-update-me.model.ts:
6838 $ref: '#/components/schemas/password'
6840 $ref: '#/components/schemas/password'
6842 description: new email used for login and service communications
6844 - $ref: '#/components/schemas/User/properties/email'
6847 description: new name of the user in its representations
6852 description: new NSFW display policy
6859 description: whether to enable P2P in the player or not
6862 description: new preference regarding playing videos automatically
6865 description: new preference regarding playing following videos automatically
6866 autoPlayNextVideoPlaylist:
6868 description: new preference regarding playing following playlist videos automatically
6869 videosHistoryEnabled:
6871 description: whether to keep track of watched history or not
6876 description: list of languages to filter videos down to
6879 noInstanceConfigWarningModal:
6881 noAccountSetupWarningModal:
6888 $ref: '#/components/schemas/id'
6895 description: Rating of the video
6902 $ref: '#/components/schemas/Video'
6909 description: Rating of the video
6916 description: immutable name of the user, used to find or mention its actor
6918 - $ref: '#/components/schemas/username'
6920 $ref: '#/components/schemas/password'
6924 description: email of the user, used for login or service communications
6927 description: editable name of the user, displayed in its representations
6932 description: channel base information used to create the first channel of the user
6935 $ref: '#/components/schemas/usernameChannel'
6937 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6947 pattern: /^[a-z0-9]$/
6950 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6953 pattern: /^[a-zA-Z0-9]$/
6956 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6957 OAuthToken-password:
6959 - $ref: '#/components/schemas/OAuthClient'
6969 $ref: '#/components/schemas/User/properties/username'
6971 $ref: '#/components/schemas/password'
6978 OAuthToken-refresh_token:
6980 - $ref: '#/components/schemas/OAuthClient'
6991 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7000 # GET/POST/PUT properties
7003 description: editable name of the channel, displayed in its representations
7004 example: Videos of Framasoft
7009 example: Videos made with <3 by Framasoft
7014 description: text shown by default on all videos of this channel, to tell the audience how to support it
7015 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7018 # GET-only properties
7022 - $ref: '#/components/schemas/id'
7038 $ref: '#/components/schemas/UUIDv4'
7041 - $ref: '#/components/schemas/VideoChannel'
7044 description: username of the channel to create
7046 - $ref: '#/components/schemas/usernameChannel'
7052 - $ref: '#/components/schemas/VideoChannel'
7054 bulkVideosSupportUpdate:
7056 description: Update the support field for all videos of this channel
7066 - $ref: '#/components/schemas/VideoChannel'
7067 - $ref: '#/components/schemas/Actor'
7072 name: 'media:peerLink'
7081 - application/x-bittorrent
7087 name: 'media:content'
7118 VideoCommentsForXML:
7153 description: video watch page URL
7156 description: video canonical URL
7160 description: video publication date
7163 description: video description
7166 description: video description
7169 description: publisher user name
7172 description: video category (MRSS)
7175 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7190 description: video embed path, relative to the canonical URL domain (MRSS)
7199 description: video watch path, relative to the canonical URL domain (MRSS)
7220 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7221 'media:description':
7228 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7231 description: main streamable file for the video
7241 - application/x-bittorrent
7250 description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS)
7253 - $ref: '#/components/schemas/MRSSPeerLink'
7254 - $ref: '#/components/schemas/MRSSGroupContent'
7255 NotificationSettingValue:
7272 $ref: '#/components/schemas/id'
7276 Notification type, following the `UserNotificationType` enum:
7278 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7280 - `2` NEW_COMMENT_ON_MY_VIDEO
7282 - `3` NEW_ABUSE_FOR_MODERATORS
7284 - `4` BLACKLIST_ON_MY_VIDEO
7286 - `5` UNBLACKLIST_ON_MY_VIDEO
7288 - `6` MY_VIDEO_PUBLISHED
7290 - `7` MY_VIDEO_IMPORT_SUCCESS
7292 - `8` MY_VIDEO_IMPORT_ERROR
7294 - `9` NEW_USER_REGISTRATION
7298 - `11` COMMENT_MENTION
7300 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7302 - `13` NEW_INSTANCE_FOLLOWER
7304 - `14` AUTO_INSTANCE_FOLLOWING
7306 - `15` ABUSE_STATE_CHANGE
7308 - `16` ABUSE_NEW_MESSAGE
7310 - `17` NEW_PLUGIN_VERSION
7312 - `18` NEW_PEERTUBE_VERSION
7318 - $ref: '#/components/schemas/VideoInfo'
7322 $ref: '#/components/schemas/ActorInfo'
7328 $ref: '#/components/schemas/id'
7331 $ref: '#/components/schemas/VideoInfo'
7336 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7346 $ref: '#/components/schemas/id'
7350 $ref: '#/components/schemas/VideoInfo'
7352 $ref: '#/components/schemas/ActorInfo'
7358 $ref: '#/components/schemas/id'
7361 - $ref: '#/components/schemas/VideoInfo'
7367 $ref: '#/components/schemas/id'
7370 - $ref: '#/components/schemas/VideoInfo'
7374 - $ref: '#/components/schemas/ActorInfo'
7380 $ref: '#/components/schemas/id'
7382 $ref: '#/components/schemas/ActorInfo'
7410 NotificationListResponse:
7419 $ref: '#/components/schemas/Notification'
7424 example: peertube-plugin-auth-ldap
7452 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7455 additionalProperties: true
7471 $ref: '#/components/schemas/Plugin'
7478 description: User can stream multiple times in a permanent live
7489 description: RTMP stream key to use to stream into this live video
7493 description: User can stream multiple times in a permanent live
7500 'https://search.example.org/api/v1/search/videos':
7502 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7505 description: successful operation
7509 $ref: '#/components/schemas/VideoListResponse'