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
1562 $ref: '#/components/schemas/ActorImage'
1564 description: image file too large
1566 X-File-Maximum-Size:
1570 description: Maximum file size for the avatar
1573 multipart/form-data:
1578 description: The file to upload
1583 contentType: image/png, image/jpeg
1587 summary: Delete my avatar
1594 description: successful operation
1598 summary: List video ownership changes
1600 - Video Ownership Change
1605 description: successful operation
1607 '/videos/ownership/{id}/accept':
1609 summary: Accept ownership change request
1611 - Video Ownership Change
1615 - $ref: '#/components/parameters/idOrUUID'
1618 description: successful operation
1620 description: cannot terminate an ownership change of another user
1622 description: video ownership change not found
1624 '/videos/ownership/{id}/refuse':
1626 summary: Refuse ownership change request
1628 - Video Ownership Change
1632 - $ref: '#/components/parameters/idOrUUID'
1635 description: successful operation
1637 description: cannot terminate an ownership change of another user
1639 description: video ownership change not found
1641 '/videos/{id}/give-ownership':
1643 summary: Request ownership change
1645 - Video Ownership Change
1649 - $ref: '#/components/parameters/idOrUUID'
1653 application/x-www-form-urlencoded:
1663 description: successful operation
1665 description: changing video ownership to a remote account is not supported yet
1667 description: video not found
1671 summary: List videos
1672 operationId: getVideos
1676 - $ref: '#/components/parameters/categoryOneOf'
1677 - $ref: '#/components/parameters/isLive'
1678 - $ref: '#/components/parameters/tagsOneOf'
1679 - $ref: '#/components/parameters/tagsAllOf'
1680 - $ref: '#/components/parameters/licenceOneOf'
1681 - $ref: '#/components/parameters/languageOneOf'
1682 - $ref: '#/components/parameters/nsfw'
1683 - $ref: '#/components/parameters/isLocal'
1684 - $ref: '#/components/parameters/include'
1685 - $ref: '#/components/parameters/privacyOneOf'
1686 - $ref: '#/components/parameters/hasHLSFiles'
1687 - $ref: '#/components/parameters/hasWebtorrentFiles'
1688 - $ref: '#/components/parameters/skipCount'
1689 - $ref: '#/components/parameters/start'
1690 - $ref: '#/components/parameters/count'
1691 - $ref: '#/components/parameters/videosSort'
1694 description: successful operation
1698 $ref: '#/components/schemas/VideoListResponse'
1702 summary: List available video categories
1703 operationId: getCategories
1708 description: successful operation
1717 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1721 summary: List available video licences
1722 operationId: getLicences
1727 description: successful operation
1736 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1740 summary: List available video languages
1741 operationId: getLanguages
1746 description: successful operation
1755 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1759 summary: List available video privacy policies
1760 operationId: getPrivacyPolicies
1765 description: successful operation
1774 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1778 summary: Update a video
1779 operationId: putVideo
1785 - $ref: '#/components/parameters/idOrUUID'
1788 description: successful operation
1791 multipart/form-data:
1796 description: Video thumbnail file
1800 description: Video preview file
1804 $ref: '#/components/schemas/VideoCategorySet'
1806 $ref: '#/components/schemas/VideoLicenceSet'
1808 $ref: '#/components/schemas/VideoLanguageSet'
1810 $ref: '#/components/schemas/VideoPrivacySet'
1812 description: Video description
1815 description: Whether or not we wait transcoding before publish the video
1818 description: A text tell the audience how to support the video creator
1819 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1822 description: Whether or not this video contains sensitive content
1825 description: Video name
1830 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1839 description: Enable or disable comments for this video
1842 description: Enable or disable downloading for this video
1844 originallyPublishedAt:
1845 description: Date when the content was originally published
1849 $ref: '#/components/schemas/VideoScheduledUpdate'
1852 contentType: image/jpeg
1854 contentType: image/jpeg
1856 summary: Get a video
1857 operationId: getVideo
1861 - $ref: '#/components/parameters/idOrUUID'
1864 description: successful operation
1868 $ref: '#/components/schemas/VideoDetails'
1870 summary: Delete a video
1871 operationId: delVideo
1877 - $ref: '#/components/parameters/idOrUUID'
1880 description: successful operation
1882 '/videos/{id}/description':
1884 summary: Get complete video description
1885 operationId: getVideoDesc
1889 - $ref: '#/components/parameters/idOrUUID'
1892 description: successful operation
1901 **[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)**
1903 '/videos/{id}/views':
1905 summary: Add a view to a video
1906 operationId: addView
1910 - $ref: '#/components/parameters/idOrUUID'
1913 description: successful operation
1915 '/videos/{id}/watching':
1917 summary: Set watching progress of a video
1918 operationId: setProgress
1924 - $ref: '#/components/parameters/idOrUUID'
1929 $ref: '#/components/schemas/UserWatchingVideo'
1933 description: successful operation
1937 summary: Upload a video
1938 description: Uses a single request to upload a video.
1939 operationId: uploadLegacy
1947 description: successful operation
1951 $ref: '#/components/schemas/VideoUploadResponse'
1953 description: video didn't pass upload filter
1955 description: upload has timed out
1957 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1959 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1960 - `quota_reached` for quota limits wether daily or global
1962 X-File-Maximum-Size:
1966 description: Maximum file size for the video
1968 description: video type unsupported
1970 description: video unreadable
1973 multipart/form-data:
1975 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1978 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1980 contentType: image/jpeg
1982 contentType: image/jpeg
1987 USERNAME="<your_username>"
1988 PASSWORD="<your_password>"
1989 FILE_PATH="<your_file_path>"
1990 CHANNEL_ID="<your_channel_id>"
1992 API="https://peertube2.cpy.re/api/v1"
1995 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1996 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1997 token=$(curl -s "$API/users/token" \
1998 --data client_id="$client_id" \
1999 --data client_secret="$client_secret" \
2000 --data grant_type=password \
2001 --data username="$USERNAME" \
2002 --data password="$PASSWORD" \
2003 | jq -r ".access_token")
2006 curl -s "$API/videos/upload" \
2007 -H "Authorization: Bearer $token" \
2009 --form videofile=@"$FILE_PATH" \
2010 --form channelId=$CHANNEL_ID \
2013 /videos/upload-resumable:
2015 summary: Initialize the resumable upload of a video
2016 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2017 operationId: uploadResumableInit
2024 - name: X-Upload-Content-Length
2030 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2031 - name: X-Upload-Content-Type
2038 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2043 $ref: '#/components/schemas/VideoUploadRequestResumable'
2046 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2048 description: created
2054 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2060 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2062 Disambiguate via `type`:
2063 - `max_file_size_reached` for the absolute file size limit
2064 - `quota_reached` for quota limits whether daily or global
2066 description: video type unsupported
2068 summary: Send chunk for the resumable upload of a video
2069 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
2070 operationId: uploadResumable
2081 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2082 not valid anymore and you need to initialize a new upload.
2085 - name: Content-Range
2089 example: bytes 0-262143/2469036
2092 Specifies the bytes in the file that the request is uploading.
2094 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2095 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2096 - name: Content-Length
2103 Size of the chunk that the request is sending.
2105 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)
2106 doesn't mandate for chunks to have the same size throughout the upload sequence.
2108 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2109 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2112 application/octet-stream:
2118 description: last chunk received
2126 $ref: '#/components/schemas/VideoUploadResponse'
2128 description: resume incomplete
2133 example: bytes=0-262143
2139 description: video didn't pass upload filter
2141 description: upload not found
2143 description: chunk doesn't match range
2145 description: video unreadable
2147 description: too many concurrent requests
2149 description: upload is already being processed
2156 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2157 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2158 operationId: uploadResumableCancel
2169 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2170 not valid anymore and the upload session has already been deleted with its data ;-)
2173 - name: Content-Length
2181 description: upload cancelled
2188 description: upload not found
2192 summary: Import a video
2193 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2194 operationId: importVideo
2202 multipart/form-data:
2204 $ref: '#/components/schemas/VideoCreateImport'
2207 contentType: application/x-bittorrent
2209 contentType: image/jpeg
2211 contentType: image/jpeg
2214 description: successful operation
2218 $ref: '#/components/schemas/VideoUploadResponse'
2220 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2222 description: video didn't pass pre-import filter
2224 description: HTTP or Torrent/magnetURI import not enabled
2226 /videos/imports/{id}/cancel:
2228 summary: Cancel video import
2229 description: Cancel a pending video import
2235 - $ref: '#/components/parameters/id'
2238 description: successful operation
2240 /videos/imports/{id}:
2242 summary: Delete video import
2243 description: Delete ended video import
2249 - $ref: '#/components/parameters/id'
2252 description: successful operation
2256 summary: Create a live
2257 operationId: addLive
2265 description: successful operation
2269 $ref: '#/components/schemas/VideoUploadResponse'
2271 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2273 Disambiguate via `type`:
2274 - default type for a validation error
2275 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2277 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2279 Disambiguate via `type`:
2280 - `live_not_enabled` for a disabled live feature
2281 - `live_not_allowing_replay` for a disabled replay feature
2282 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2283 - `max_user_lives_limit_reached` for the user concurrent live limit
2286 multipart/form-data:
2291 description: Channel id that will contain this live video
2296 description: User can stream multiple times in a permanent live
2299 description: Live video/replay thumbnail file
2303 description: Live video/replay preview file
2307 $ref: '#/components/schemas/VideoPrivacySet'
2309 $ref: '#/components/schemas/VideoCategorySet'
2311 $ref: '#/components/schemas/VideoLicenceSet'
2313 $ref: '#/components/schemas/VideoLanguageSet'
2315 description: Live video/replay description
2318 description: A text tell the audience how to support the creator
2319 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2322 description: Whether or not this live video/replay contains sensitive content
2325 description: Live video/replay name
2330 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2339 description: Enable or disable comments for this live video/replay
2342 description: Enable or disable downloading for the replay of this live video
2349 contentType: image/jpeg
2351 contentType: image/jpeg
2355 summary: Get information about a live
2356 operationId: getLiveId
2363 - $ref: '#/components/parameters/idOrUUID'
2366 description: successful operation
2370 $ref: '#/components/schemas/LiveVideoResponse'
2372 summary: Update information about a live
2373 operationId: updateLiveId
2380 - $ref: '#/components/parameters/idOrUUID'
2385 $ref: '#/components/schemas/LiveVideoUpdate'
2388 description: successful operation
2390 description: bad parameters or trying to update a live that has already started
2392 description: trying to save replay of the live but saving replay is not enabled on the instance
2396 summary: List my abuses
2397 operationId: getMyAbuses
2406 description: only list the report with this id
2412 $ref: '#/components/schemas/AbuseStateSet'
2413 - $ref: '#/components/parameters/abusesSort'
2414 - $ref: '#/components/parameters/start'
2415 - $ref: '#/components/parameters/count'
2418 description: successful operation
2430 $ref: '#/components/schemas/Abuse'
2434 summary: List abuses
2435 operationId: getAbuses
2445 description: only list the report with this id
2448 - name: predefinedReason
2450 description: predefined reason the listed reports should contain
2452 $ref: '#/components/schemas/PredefinedAbuseReasons'
2455 description: plain search that will match with video titles, reporter names and more
2461 $ref: '#/components/schemas/AbuseStateSet'
2462 - name: searchReporter
2464 description: only list reports of a specific reporter
2467 - name: searchReportee
2468 description: only list reports of a specific reportee
2474 description: only list reports of a specific video
2477 - name: searchVideoChannel
2479 description: only list reports of a specific video channel
2484 description: only list deleted or blocklisted videos
2492 description: only list account, comment or video reports
2499 - $ref: '#/components/parameters/start'
2500 - $ref: '#/components/parameters/count'
2501 - $ref: '#/components/parameters/abusesSort'
2504 description: successful operation
2516 $ref: '#/components/schemas/Abuse'
2518 summary: Report an abuse
2531 description: Reason why the user reports this video
2536 $ref: '#/components/schemas/PredefinedAbuseReasons'
2541 description: Video id to report
2543 - $ref: '#/components/schemas/Video/properties/id'
2547 description: Timestamp in the video that marks the beginning of the report
2552 description: Timestamp in the video that marks the ending of the report
2558 description: Comment id to report
2560 - $ref: '#/components/schemas/VideoComment/properties/id'
2565 description: Account id to report
2571 description: successful operation
2581 $ref: '#/components/schemas/id'
2583 description: incorrect request parameters
2585 '/abuses/{abuseId}':
2587 summary: Update an abuse
2595 - $ref: '#/components/parameters/abuseId'
2603 $ref: '#/components/schemas/AbuseStateSet'
2606 description: Update the report comment visible only to the moderation team
2611 description: successful operation
2613 description: abuse not found
2617 summary: Delete an abuse
2623 - $ref: '#/components/parameters/abuseId'
2626 description: successful operation
2628 description: block not found
2630 '/abuses/{abuseId}/messages':
2632 summary: List messages of an abuse
2638 - $ref: '#/components/parameters/abuseId'
2641 description: successful operation
2653 $ref: '#/components/schemas/AbuseMessage'
2655 summary: Add message to an abuse
2661 - $ref: '#/components/parameters/abuseId'
2670 description: Message to send
2678 description: successful operation
2680 description: incorrect request parameters
2682 '/abuses/{abuseId}/messages/{abuseMessageId}':
2684 summary: Delete an abuse message
2690 - $ref: '#/components/parameters/abuseId'
2691 - $ref: '#/components/parameters/abuseMessageId'
2694 description: successful operation
2696 '/videos/{id}/blacklist':
2698 summary: Block a video
2699 operationId: addVideoBlock
2707 - $ref: '#/components/parameters/idOrUUID'
2710 description: successful operation
2712 summary: Unblock a video by its id
2713 operationId: delVideoBlock
2721 - $ref: '#/components/parameters/idOrUUID'
2724 description: successful operation
2726 description: block not found
2732 summary: List video blocks
2733 operationId: getVideoBlocks
2742 list only blocks that match this type:
2746 - `2`: automatic block that needs review
2754 description: plain search that will match with video titles, and more
2757 - $ref: '#/components/parameters/start'
2758 - $ref: '#/components/parameters/count'
2759 - $ref: '#/components/parameters/blacklistsSort'
2762 description: successful operation
2774 $ref: '#/components/schemas/VideoBlacklist'
2776 /videos/{id}/captions:
2778 summary: List captions of a video
2779 operationId: getVideoCaptions
2783 - $ref: '#/components/parameters/idOrUUID'
2786 description: successful operation
2798 $ref: '#/components/schemas/VideoCaption'
2800 /videos/{id}/captions/{captionLanguage}:
2802 summary: Add or replace a video caption
2803 operationId: addVideoCaption
2810 - $ref: '#/components/parameters/idOrUUID'
2811 - $ref: '#/components/parameters/captionLanguage'
2814 multipart/form-data:
2819 description: The file to upload.
2824 contentType: text/vtt, application/x-subrip, text/plain
2827 description: successful operation
2829 description: video or language not found
2831 summary: Delete a video caption
2832 operationId: delVideoCaption
2839 - $ref: '#/components/parameters/idOrUUID'
2840 - $ref: '#/components/parameters/captionLanguage'
2843 description: successful operation
2845 description: video or language or caption for that language not found
2849 summary: List video channels
2850 operationId: getVideoChannels
2854 - $ref: '#/components/parameters/start'
2855 - $ref: '#/components/parameters/count'
2856 - $ref: '#/components/parameters/sort'
2859 description: successful operation
2863 $ref: '#/components/schemas/VideoChannelList'
2865 summary: Create a video channel
2866 operationId: addVideoChannel
2873 description: successful operation
2883 $ref: '#/components/schemas/id'
2888 $ref: '#/components/schemas/VideoChannelCreate'
2890 '/video-channels/{channelHandle}':
2892 summary: Get a video channel
2893 operationId: getVideoChannel
2897 - $ref: '#/components/parameters/channelHandle'
2900 description: successful operation
2904 $ref: '#/components/schemas/VideoChannel'
2906 summary: Update a video channel
2907 operationId: putVideoChannel
2913 - $ref: '#/components/parameters/channelHandle'
2916 description: successful operation
2921 $ref: '#/components/schemas/VideoChannelUpdate'
2923 summary: Delete a video channel
2924 operationId: delVideoChannel
2930 - $ref: '#/components/parameters/channelHandle'
2933 description: successful operation
2935 '/video-channels/{channelHandle}/videos':
2937 summary: List videos of a video channel
2938 operationId: getVideoChannelVideos
2943 - $ref: '#/components/parameters/channelHandle'
2944 - $ref: '#/components/parameters/categoryOneOf'
2945 - $ref: '#/components/parameters/isLive'
2946 - $ref: '#/components/parameters/tagsOneOf'
2947 - $ref: '#/components/parameters/tagsAllOf'
2948 - $ref: '#/components/parameters/licenceOneOf'
2949 - $ref: '#/components/parameters/languageOneOf'
2950 - $ref: '#/components/parameters/nsfw'
2951 - $ref: '#/components/parameters/isLocal'
2952 - $ref: '#/components/parameters/include'
2953 - $ref: '#/components/parameters/privacyOneOf'
2954 - $ref: '#/components/parameters/hasHLSFiles'
2955 - $ref: '#/components/parameters/hasWebtorrentFiles'
2956 - $ref: '#/components/parameters/skipCount'
2957 - $ref: '#/components/parameters/start'
2958 - $ref: '#/components/parameters/count'
2959 - $ref: '#/components/parameters/videosSort'
2962 description: successful operation
2966 $ref: '#/components/schemas/VideoListResponse'
2968 '/video-channels/{channelHandle}/followers':
2972 summary: 'List followers of a video channel'
2975 operationId: getVideoChannelFollowers
2977 - $ref: '#/components/parameters/channelHandle'
2978 - $ref: '#/components/parameters/start'
2979 - $ref: '#/components/parameters/count'
2980 - $ref: '#/components/parameters/followersSort'
2981 - $ref: '#/components/parameters/search'
2984 description: successful operation
2996 $ref: '#/components/schemas/Follow'
2998 '/video-channels/{channelHandle}/avatar/pick':
3000 summary: Update channel avatar
3006 - $ref: '#/components/parameters/channelHandle'
3009 description: successful operation
3018 $ref: '#/components/schemas/ActorImage'
3020 description: image file too large
3022 X-File-Maximum-Size:
3026 description: Maximum file size for the avatar
3029 multipart/form-data:
3034 description: The file to upload.
3039 contentType: image/png, image/jpeg
3041 '/video-channels/{channelHandle}/avatar':
3043 summary: Delete channel avatar
3049 - $ref: '#/components/parameters/channelHandle'
3052 description: successful operation
3054 '/video-channels/{channelHandle}/banner/pick':
3056 summary: Update channel banner
3062 - $ref: '#/components/parameters/channelHandle'
3065 description: successful operation
3074 $ref: '#/components/schemas/ActorImage'
3076 description: image file too large
3078 X-File-Maximum-Size:
3082 description: Maximum file size for the banner
3085 multipart/form-data:
3090 description: The file to upload.
3095 contentType: image/png, image/jpeg
3097 '/video-channels/{channelHandle}/banner':
3099 summary: Delete channel banner
3105 - $ref: '#/components/parameters/channelHandle'
3108 description: successful operation
3110 /video-playlists/privacies:
3112 summary: List available playlist privacy policies
3113 operationId: getPlaylistPrivacyPolicies
3118 description: successful operation
3127 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3131 summary: List video playlists
3132 operationId: getPlaylists
3136 - $ref: '#/components/parameters/start'
3137 - $ref: '#/components/parameters/count'
3138 - $ref: '#/components/parameters/sort'
3141 description: successful operation
3153 $ref: '#/components/schemas/VideoPlaylist'
3155 summary: Create a video playlist
3156 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3157 operationId: addPlaylist
3164 description: successful operation
3174 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3176 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3178 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3181 multipart/form-data:
3186 description: Video playlist display name
3191 description: Video playlist thumbnail file
3195 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3197 description: Video playlist description
3203 - $ref: '#/components/schemas/id'
3204 description: Video channel in which the playlist will be published
3209 contentType: image/jpeg
3211 /video-playlists/{playlistId}:
3213 summary: Get a video playlist
3217 - $ref: '#/components/parameters/playlistId'
3220 description: successful operation
3224 $ref: '#/components/schemas/VideoPlaylist'
3226 summary: Update a video playlist
3227 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3234 description: successful operation
3236 - $ref: '#/components/parameters/playlistId'
3239 multipart/form-data:
3244 description: Video playlist display name
3249 description: Video playlist thumbnail file
3253 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3255 description: Video playlist description
3259 - $ref: '#/components/schemas/id'
3260 description: Video channel in which the playlist will be published
3263 contentType: image/jpeg
3265 summary: Delete a video playlist
3271 - $ref: '#/components/parameters/playlistId'
3274 description: successful operation
3276 /video-playlists/{playlistId}/videos:
3278 summary: 'List videos of a playlist'
3279 operationId: getVideoPlaylistVideos
3284 - $ref: '#/components/parameters/playlistId'
3285 - $ref: '#/components/parameters/start'
3286 - $ref: '#/components/parameters/count'
3289 description: successful operation
3293 $ref: '#/components/schemas/VideoListResponse'
3295 summary: Add a video in a playlist
3296 operationId: addVideoPlaylistVideo
3303 - $ref: '#/components/parameters/playlistId'
3306 description: successful operation
3312 videoPlaylistElement:
3326 - $ref: '#/components/schemas/Video/properties/uuid'
3327 - $ref: '#/components/schemas/Video/properties/id'
3328 description: Video to add in the playlist
3332 description: Start the video at this specific timestamp
3336 description: Stop the video at this specific timestamp
3340 /video-playlists/{playlistId}/videos/reorder:
3342 summary: 'Reorder a playlist'
3343 operationId: reorderVideoPlaylist
3349 - $ref: '#/components/parameters/playlistId'
3352 description: successful operation
3361 description: 'Start position of the element to reorder'
3363 insertAfterPosition:
3365 description: 'New position for the block to reorder, to add the block before the first element'
3369 description: 'How many element from `startPosition` to reorder'
3373 - insertAfterPosition
3375 /video-playlists/{playlistId}/videos/{playlistElementId}:
3377 summary: Update a playlist element
3378 operationId: putVideoPlaylistVideo
3384 - $ref: '#/components/parameters/playlistId'
3385 - $ref: '#/components/parameters/playlistElementId'
3388 description: successful operation
3398 description: Start the video at this specific timestamp
3402 description: Stop the video at this specific timestamp
3404 summary: Delete an element from a playlist
3405 operationId: delVideoPlaylistVideo
3411 - $ref: '#/components/parameters/playlistId'
3412 - $ref: '#/components/parameters/playlistElementId'
3415 description: successful operation
3417 '/users/me/video-playlists/videos-exist':
3419 summary: Check video exists in my playlists
3428 description: The video ids to check
3432 $ref: '#/components/schemas/Video/properties/id'
3435 description: successful operation
3457 '/accounts/{name}/video-channels':
3459 summary: List video channels of an account
3464 - $ref: '#/components/parameters/name'
3467 description: include view statistics for the last 30 days (only if authentified as the account user)
3470 - $ref: '#/components/parameters/start'
3471 - $ref: '#/components/parameters/count'
3472 - $ref: '#/components/parameters/sort'
3475 description: successful operation
3479 $ref: '#/components/schemas/VideoChannelList'
3481 '/accounts/{name}/ratings':
3483 summary: List ratings of an account
3489 - $ref: '#/components/parameters/name'
3490 - $ref: '#/components/parameters/start'
3491 - $ref: '#/components/parameters/count'
3492 - $ref: '#/components/parameters/sort'
3496 description: Optionally filter which ratings to retrieve
3504 description: successful operation
3510 $ref: '#/components/schemas/VideoRating'
3512 '/videos/{id}/comment-threads':
3514 summary: List threads of a video
3518 - $ref: '#/components/parameters/idOrUUID'
3519 - $ref: '#/components/parameters/start'
3520 - $ref: '#/components/parameters/count'
3521 - $ref: '#/components/parameters/commentsSort'
3524 description: successful operation
3528 $ref: '#/components/schemas/CommentThreadResponse'
3530 summary: Create a thread
3536 - $ref: '#/components/parameters/idOrUUID'
3539 description: successful operation
3543 $ref: '#/components/schemas/CommentThreadPostResponse'
3545 description: video does not exist
3554 - $ref: '#/components/schemas/VideoComment/properties/text'
3560 '/videos/{id}/comment-threads/{threadId}':
3562 summary: Get a thread
3566 - $ref: '#/components/parameters/idOrUUID'
3567 - $ref: '#/components/parameters/threadId'
3570 description: successful operation
3574 $ref: '#/components/schemas/VideoCommentThreadTree'
3576 '/videos/{id}/comments/{commentId}':
3578 summary: Reply to a thread of a video
3584 - $ref: '#/components/parameters/idOrUUID'
3585 - $ref: '#/components/parameters/commentId'
3588 description: successful operation
3592 $ref: '#/components/schemas/CommentThreadPostResponse'
3594 description: thread or video does not exist
3603 - $ref: '#/components/schemas/VideoComment/properties/text'
3609 summary: Delete a comment or a reply
3615 - $ref: '#/components/parameters/idOrUUID'
3616 - $ref: '#/components/parameters/commentId'
3619 description: successful operation
3621 description: cannot remove comment of another user
3623 description: comment or video does not exist
3625 description: comment is already deleted
3627 '/videos/{id}/rate':
3629 summary: Like/dislike a video
3635 - $ref: '#/components/parameters/idOrUUID'
3651 description: successful operation
3653 description: video does not exist
3657 summary: Delete video HLS files
3663 operationId: delVideoHLS
3665 - $ref: '#/components/parameters/idOrUUID'
3668 description: successful operation
3670 description: video does not exist
3671 '/videos/{id}/webtorrent':
3673 summary: Delete video WebTorrent files
3679 operationId: delVideoWebTorrent
3681 - $ref: '#/components/parameters/idOrUUID'
3684 description: successful operation
3686 description: video does not exist
3688 '/videos/{id}/transcoding':
3690 summary: Create a transcoding job
3696 operationId: createVideoTranscoding
3698 - $ref: '#/components/parameters/idOrUUID'
3714 description: successful operation
3716 description: video does not exist
3722 summary: Search videos
3723 operationId: searchVideos
3728 allowEmptyValue: false
3730 String to search. If the user can make a remote URI search, and the string is an URI then the
3731 PeerTube instance will fetch the remote object and add it to its database. Then,
3732 you can use the REST API to fetch the complete video information and interact with it.
3735 - $ref: '#/components/parameters/categoryOneOf'
3736 - $ref: '#/components/parameters/isLive'
3737 - $ref: '#/components/parameters/tagsOneOf'
3738 - $ref: '#/components/parameters/tagsAllOf'
3739 - $ref: '#/components/parameters/licenceOneOf'
3740 - $ref: '#/components/parameters/languageOneOf'
3741 - $ref: '#/components/parameters/nsfw'
3742 - $ref: '#/components/parameters/isLocal'
3743 - $ref: '#/components/parameters/include'
3744 - $ref: '#/components/parameters/privacyOneOf'
3745 - $ref: '#/components/parameters/hasHLSFiles'
3746 - $ref: '#/components/parameters/hasWebtorrentFiles'
3747 - $ref: '#/components/parameters/skipCount'
3748 - $ref: '#/components/parameters/start'
3749 - $ref: '#/components/parameters/count'
3750 - $ref: '#/components/parameters/searchTarget'
3751 - $ref: '#/components/parameters/videosSearchSort'
3754 description: Get videos that are published after this date
3760 description: Get videos that are published before this date
3764 - name: originallyPublishedStartDate
3766 description: Get videos that are originally published after this date
3770 - name: originallyPublishedEndDate
3772 description: Get videos that are originally published before this date
3778 description: Get videos that have this minimum duration
3783 description: Get videos that have this maximum duration
3787 'searchTarget === search-index':
3788 $ref: '#/components/callbacks/searchIndex'
3791 description: successful operation
3795 $ref: '#/components/schemas/VideoListResponse'
3797 description: search index unavailable
3799 /search/video-channels:
3803 summary: Search channels
3804 operationId: searchChannels
3810 String to search. If the user can make a remote URI search, and the string is an URI then the
3811 PeerTube instance will fetch the remote object and add it to its database. Then,
3812 you can use the REST API to fetch the complete channel information and interact with it.
3815 - $ref: '#/components/parameters/start'
3816 - $ref: '#/components/parameters/count'
3817 - $ref: '#/components/parameters/searchTarget'
3818 - $ref: '#/components/parameters/sort'
3820 'searchTarget === search-index':
3821 $ref: '#/components/callbacks/searchIndex'
3824 description: successful operation
3828 $ref: '#/components/schemas/VideoChannelList'
3830 description: search index unavailable
3832 /search/video-playlists:
3836 summary: Search playlists
3837 operationId: searchPlaylists
3843 String to search. If the user can make a remote URI search, and the string is an URI then the
3844 PeerTube instance will fetch the remote object and add it to its database. Then,
3845 you can use the REST API to fetch the complete playlist information and interact with it.
3848 - $ref: '#/components/parameters/start'
3849 - $ref: '#/components/parameters/count'
3850 - $ref: '#/components/parameters/searchTarget'
3851 - $ref: '#/components/parameters/sort'
3853 'searchTarget === search-index':
3854 $ref: '#/components/callbacks/searchIndex'
3857 description: successful operation
3869 $ref: '#/components/schemas/VideoPlaylist'
3871 description: search index unavailable
3878 summary: Get block status of accounts/hosts
3883 description: 'Check if these accounts are blocked'
3884 example: [ 'goofy@example.com', 'donald@example.com' ]
3892 description: 'Check if these hosts are blocked'
3893 example: [ 'example.com' ]
3900 description: successful operation
3904 $ref: '#/components/schemas/BlockStatus'
3906 /server/blocklist/accounts:
3910 summary: List account blocks
3915 - $ref: '#/components/parameters/start'
3916 - $ref: '#/components/parameters/count'
3917 - $ref: '#/components/parameters/sort'
3920 description: successful operation
3924 summary: Block an account
3936 example: chocobozzz@example.org
3937 description: account to block, in the form `username@domain`
3942 description: successful operation
3944 description: self-blocking forbidden
3946 '/server/blocklist/accounts/{accountName}':
3950 summary: Unblock an account by its handle
3958 description: account to unblock, in the form `username@domain`
3963 description: successful operation
3965 description: account or account block does not exist
3967 /server/blocklist/servers:
3971 summary: List server blocks
3976 - $ref: '#/components/parameters/start'
3977 - $ref: '#/components/parameters/count'
3978 - $ref: '#/components/parameters/sort'
3981 description: successful operation
3985 summary: Block a server
3998 description: server domain to block
4003 description: successful operation
4005 description: self-blocking forbidden
4007 '/server/blocklist/servers/{host}':
4011 summary: Unblock a server by its domain
4019 description: server domain to unblock
4025 description: successful operation
4027 description: account block does not exist
4029 /server/redundancy/{host}:
4032 - Instance Redundancy
4033 summary: Update a server redundancy policy
4041 description: server domain to mirror
4053 description: allow mirroring of the host's local videos
4058 description: successful operation
4060 description: server is not already known
4062 /server/redundancy/videos:
4066 summary: List videos being mirrored
4067 operationId: getMirroredVideos
4075 description: direction of the mirror
4081 - $ref: '#/components/parameters/start'
4082 - $ref: '#/components/parameters/count'
4083 - $ref: '#/components/parameters/videoRedundanciesSort'
4086 description: successful operation
4092 $ref: '#/components/schemas/VideoRedundancy'
4096 summary: Mirror a video
4097 operationId: putMirroredVideo
4108 $ref: '#/components/schemas/Video/properties/id'
4113 description: successful operation
4115 description: cannot mirror a local video
4117 description: video does not exist
4119 description: video is already mirrored
4121 /server/redundancy/videos/{redundancyId}:
4125 summary: Delete a mirror done on a video
4126 operationId: delMirroredVideo
4131 - name: redundancyId
4134 description: id of an existing redundancy on a video
4139 description: successful operation
4141 description: video redundancy not found
4143 '/feeds/video-comments.{format}':
4147 summary: List comments on videos
4148 operationId: getSyndicatedComments
4153 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4166 description: 'limit listing to a specific video'
4171 description: 'limit listing to a specific account'
4176 description: 'limit listing to a specific account'
4179 - name: videoChannelId
4181 description: 'limit listing to a specific video channel'
4184 - name: videoChannelName
4186 description: 'limit listing to a specific video channel'
4191 description: successful operation
4196 default: 'max-age=900' # 15 min cache
4200 $ref: '#/components/schemas/VideoCommentsForXML'
4203 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4204 application/rss+xml:
4206 $ref: '#/components/schemas/VideoCommentsForXML'
4209 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4212 $ref: '#/components/schemas/VideoCommentsForXML'
4215 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4216 application/atom+xml:
4218 $ref: '#/components/schemas/VideoCommentsForXML'
4221 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4227 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4229 x-summary: field inconsistencies
4232 - videoId filter is mixed with a channel filter
4234 description: video, video channel or account not found
4236 description: accept header unsupported
4238 '/feeds/videos.{format}':
4242 summary: List videos
4243 operationId: getSyndicatedVideos
4248 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4261 description: 'limit listing to a specific account'
4266 description: 'limit listing to a specific account'
4269 - name: videoChannelId
4271 description: 'limit listing to a specific video channel'
4274 - name: videoChannelName
4276 description: 'limit listing to a specific video channel'
4279 - $ref: '#/components/parameters/sort'
4280 - $ref: '#/components/parameters/nsfw'
4281 - $ref: '#/components/parameters/isLocal'
4282 - $ref: '#/components/parameters/include'
4283 - $ref: '#/components/parameters/privacyOneOf'
4284 - $ref: '#/components/parameters/hasHLSFiles'
4285 - $ref: '#/components/parameters/hasWebtorrentFiles'
4288 description: successful operation
4293 default: 'max-age=900' # 15 min cache
4297 $ref: '#/components/schemas/VideosForXML'
4300 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4301 application/rss+xml:
4303 $ref: '#/components/schemas/VideosForXML'
4306 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4309 $ref: '#/components/schemas/VideosForXML'
4312 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4313 application/atom+xml:
4315 $ref: '#/components/schemas/VideosForXML'
4318 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4324 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4326 description: video channel or account not found
4328 description: accept header unsupported
4330 '/feeds/subscriptions.{format}':
4335 summary: List videos of subscriptions tied to a token
4336 operationId: getSyndicatedSubscriptionVideos
4341 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4354 description: limit listing to a specific account
4360 description: private token allowing access
4364 - $ref: '#/components/parameters/sort'
4365 - $ref: '#/components/parameters/nsfw'
4366 - $ref: '#/components/parameters/isLocal'
4367 - $ref: '#/components/parameters/include'
4368 - $ref: '#/components/parameters/privacyOneOf'
4369 - $ref: '#/components/parameters/hasHLSFiles'
4370 - $ref: '#/components/parameters/hasWebtorrentFiles'
4373 description: successful operation
4378 default: 'max-age=900' # 15 min cache
4382 $ref: '#/components/schemas/VideosForXML'
4383 application/rss+xml:
4385 $ref: '#/components/schemas/VideosForXML'
4388 $ref: '#/components/schemas/VideosForXML'
4389 application/atom+xml:
4391 $ref: '#/components/schemas/VideosForXML'
4396 description: accept header unsupported
4402 summary: List plugins
4403 operationId: getPlugins
4416 - $ref: '#/components/parameters/start'
4417 - $ref: '#/components/parameters/count'
4418 - $ref: '#/components/parameters/sort'
4421 description: successful operation
4425 $ref: '#/components/schemas/PluginResponse'
4431 summary: List available plugins
4432 operationId: getAvailablePlugins
4445 - name: currentPeerTubeEngine
4449 - $ref: '#/components/parameters/start'
4450 - $ref: '#/components/parameters/count'
4451 - $ref: '#/components/parameters/sort'
4454 description: successful operation
4458 $ref: '#/components/schemas/PluginResponse'
4460 description: plugin index unavailable
4466 summary: Install a plugin
4467 operationId: addPlugin
4480 example: peertube-plugin-auth-ldap
4483 additionalProperties: false
4490 additionalProperties: false
4493 description: successful operation
4495 description: should have either `npmName` or `path` set
4501 summary: Update a plugin
4502 operationId: updatePlugin
4515 example: peertube-plugin-auth-ldap
4518 additionalProperties: false
4525 additionalProperties: false
4528 description: successful operation
4530 description: should have either `npmName` or `path` set
4532 description: existing plugin not found
4538 summary: Uninstall a plugin
4539 operationId: uninstallPlugin
4551 description: name of the plugin/theme in its package.json
4552 example: peertube-plugin-auth-ldap
4557 description: successful operation
4559 description: existing plugin not found
4565 summary: Get a plugin
4566 operationId: getPlugin
4571 - $ref: '#/components/parameters/npmName'
4574 description: successful operation
4578 $ref: '#/components/schemas/Plugin'
4580 description: plugin not found
4582 /plugins/{npmName}/settings:
4586 summary: Set a plugin's settings
4591 - $ref: '#/components/parameters/npmName'
4600 additionalProperties: true
4603 description: successful operation
4605 description: plugin not found
4607 /plugins/{npmName}/public-settings:
4611 summary: Get a plugin's public settings
4613 - $ref: '#/components/parameters/npmName'
4616 description: successful operation
4621 additionalProperties: true
4623 description: plugin not found
4625 /plugins/{npmName}/registered-settings:
4629 summary: Get a plugin's registered settings
4634 - $ref: '#/components/parameters/npmName'
4637 description: successful operation
4642 additionalProperties: true
4644 description: plugin not found
4647 - url: 'https://peertube2.cpy.re/api/v1'
4648 description: Live Test Server (live data - latest nightly version)
4649 - url: 'https://peertube3.cpy.re/api/v1'
4650 description: Live Test Server (live data - latest RC version)
4651 - url: 'https://peertube.cpy.re/api/v1'
4652 description: Live Test Server (live data - stable version)
4659 description: Offset used to paginate results
4667 description: "Number of items to return"
4677 description: Sort column
4685 description: Plain text search, applied to various parts of the model depending on endpoint
4693 If the administrator enabled search index support, you can override the default search target.
4696 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4697 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4698 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4699 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4700 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4701 * 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
4702 the data from the origin instance API
4712 description: Sort videos by criteria
4728 description: Sort videos by criteria
4743 description: Sort comments by criteria
4753 description: Sort blocklists by criteria
4769 description: Plain text search that will match with user usernames or emails
4776 description: Filter results down to (un)banned users
4783 description: Sort users by criteria
4794 description: Sort abuses by criteria
4801 videoRedundanciesSort:
4805 description: Sort abuses by criteria
4814 description: Sort followers by criteria
4823 description: The username or handle of the account
4826 example: chocobozzz | chocobozzz@example.org
4831 description: Entity id
4833 $ref: '#/components/schemas/id'
4838 description: The object id, uuid or short uuid
4841 - $ref: '#/components/schemas/id'
4842 - $ref: '#/components/schemas/UUIDv4'
4843 - $ref: '#/components/schemas/shortUUID'
4848 description: Playlist id
4850 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4852 name: playlistElementId
4855 description: Playlist element id
4857 $ref: '#/components/schemas/id'
4862 description: Abuse id
4864 $ref: '#/components/schemas/Abuse/properties/id'
4866 name: abuseMessageId
4869 description: Abuse message id
4871 $ref: '#/components/schemas/AbuseMessage/properties/id'
4873 name: captionLanguage
4876 description: The caption language
4878 $ref: '#/components/schemas/VideoLanguageSet'
4883 description: The video channel handle
4886 example: my_username | my_username@example.com
4888 name: subscriptionHandle
4891 description: The subscription handle
4894 example: my_username | my_username@example.com
4899 description: The thread id (root comment id)
4906 description: The comment id
4908 $ref: '#/components/schemas/VideoComment/properties/id'
4913 description: whether or not the video is a live
4920 description: category id of the video (see [/videos/categories](#operation/getCategories))
4923 - $ref: '#/components/schemas/VideoCategorySet'
4926 $ref: '#/components/schemas/VideoCategorySet'
4933 description: tag(s) of the video
4947 description: tag(s) of the video, where all should be present in the video
4960 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4963 - $ref: '#/components/schemas/VideoLanguageSet'
4966 $ref: '#/components/schemas/VideoLanguageSet'
4973 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4976 - $ref: '#/components/schemas/VideoLicenceSet'
4979 $ref: '#/components/schemas/VideoLicenceSet'
4986 description: if you don't need the `total` in the response
4997 description: whether to include nsfw videos, if any
5009 description: '**PeerTube >= 4.0** Display only local or remote videos'
5016 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5018 name: hasWebtorrentFiles
5023 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5029 $ref: '#/components/schemas/VideoPrivacySet'
5030 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5044 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5048 - `1` NOT_PUBLISHED_STATE
5059 description: list of uris to check if each is part of the user subscriptions
5069 description: name of the plugin/theme on npmjs.com or in its package.json
5072 example: peertube-plugin-auth-ldap
5077 description: job type
5081 - activitypub-follow
5082 - activitypub-http-broadcast
5083 - activitypub-http-fetcher
5084 - activitypub-http-unicast
5089 - videos-views-stats
5090 - activitypub-refresher
5115 Authenticating via OAuth requires the following steps:
5116 - Have an activated account
5117 - [Generate] an access token for that account at `/api/v1/users/token`.
5118 - Make requests with the *Authorization: Bearer <token\>* header
5119 - Profit, depending on the role assigned to the account
5121 Note that the __access token is valid for 1 day__ and is given
5122 along with a __refresh token valid for 2 weeks__.
5124 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5128 tokenUrl: /api/v1/users/token
5131 moderator: Moderator scope
5134 # Resuable core properties
5142 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5143 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5148 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5149 example: 2y84q2MQUMWPbiEcxNXMgC
5152 description: immutable name of the user, used to find or mention its actor
5154 pattern: '/^[a-z0-9._]+$/'
5159 description: immutable name of the channel, used to interact with its actor
5160 example: framasoft_videos
5161 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5172 description: category id of the video (see [/videos/categories](#operation/getCategories))
5174 VideoConstantNumber-Category:
5177 $ref: '#/components/schemas/VideoCategorySet'
5180 example: Science & Technology
5184 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5186 VideoConstantNumber-Licence:
5189 $ref: '#/components/schemas/VideoLicenceSet'
5192 example: Attribution - Share Alike
5196 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5198 VideoConstantString-Language:
5201 $ref: '#/components/schemas/VideoLanguageSet'
5206 VideoPlaylistPrivacySet:
5212 description: Video playlist privacy policy (see [/video-playlists/privacies])
5213 VideoPlaylistPrivacyConstant:
5216 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5220 VideoPlaylistTypeSet:
5225 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5226 VideoPlaylistTypeConstant:
5229 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5240 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5241 VideoPrivacyConstant:
5244 $ref: '#/components/schemas/VideoPrivacySet'
5252 additionalProperties:
5253 x-additionalPropertiesName: account
5262 additionalProperties:
5263 x-additionalPropertiesName: host
5284 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5291 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5302 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5312 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5316 $ref: '#/components/schemas/AbuseStateSet'
5319 AbusePredefinedReasons:
5332 example: [spamOrMisleading]
5337 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5339 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5341 VideoResolutionConstant:
5342 description: resolutions and their labels for the video
5345 $ref: '#/components/schemas/VideoResolutionSet'
5349 VideoScheduledUpdate:
5352 $ref: '#/components/schemas/VideoPrivacySet'
5356 description: When to update the video
5376 $ref: '#/components/schemas/ActorImage'
5377 VideoChannelSummary:
5380 $ref: '#/components/schemas/id'
5394 $ref: '#/components/schemas/ActorImage'
5408 - $ref: '#/components/schemas/Video'
5415 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5416 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5418 $ref: '#/components/schemas/VideoResolutionConstant'
5421 description: Video file size in bytes
5424 description: Direct URL of the torrent file
5428 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5432 description: Direct URL of the video
5436 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5440 description: Frames per second of the video file
5444 description: URL dereferencing the output of ffprobe on the file
5445 VideoStreamingPlaylists:
5450 $ref: '#/components/schemas/id'
5458 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5459 VideoStreamingPlaylists-HLS:
5470 Video files associated to this playlist.
5472 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5474 $ref: '#/components/schemas/VideoFile'
5486 $ref: '#/components/schemas/Video/properties/id'
5488 $ref: '#/components/schemas/Video/properties/uuid'
5490 $ref: '#/components/schemas/Video/properties/name'
5494 description: object id for the video
5496 - $ref: '#/components/schemas/id'
5498 description: universal identifier for the video, that can be used across instances
5500 - $ref: '#/components/schemas/UUIDv4'
5503 - $ref: '#/components/schemas/shortUUID'
5509 example: 2017-10-01T10:52:46.396Z
5510 description: time at which the video object was first drafted
5514 example: 2018-10-01T10:52:46.396Z
5515 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5519 example: 2021-05-04T08:01:01.502Z
5520 description: last time the video's metadata was modified
5521 originallyPublishedAt:
5524 example: 2010-10-01T10:52:46.396Z
5525 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5528 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5529 description: category in which the video is classified
5532 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5533 description: licence under which the video is distributed
5536 - $ref: '#/components/schemas/VideoConstantString-Language'
5537 description: main language used in the video
5540 - $ref: '#/components/schemas/VideoPrivacyConstant'
5541 description: privacy policy used to distribute the video
5545 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5546 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5550 truncated description of the video, written in Markdown.
5551 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5556 description: duration of the video in seconds
5561 description: title of the video
5562 example: What is PeerTube?
5567 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5570 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5573 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5590 - $ref: '#/components/schemas/VideoStateConstant'
5591 description: represents the internal state of the video processing within the PeerTube instance
5595 - $ref: '#/components/schemas/VideoScheduledUpdate'
5603 $ref: '#/components/schemas/AccountSummary'
5605 $ref: '#/components/schemas/VideoChannelSummary'
5614 - $ref: '#/components/schemas/Video'
5619 description: If the video is a live, you have the amount of current viewers
5622 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5623 description: path at which to get the full description of maximum `10000` characters
5626 description: A text tell the audience how to support the video creator
5627 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5631 $ref: '#/components/schemas/VideoChannel'
5633 $ref: '#/components/schemas/Account'
5635 example: [flowers, gardening]
5653 - https://peertube2.cpy.re/tracker/announce
5654 - wss://peertube2.cpy.re/tracker/socket
5658 $ref: '#/components/schemas/VideoFile'
5660 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5662 - field will be empty
5663 - video files will be found in `streamingPlaylists[].files` field
5667 $ref: '#/components/schemas/VideoStreamingPlaylists'
5669 HLS playlists/manifest files. If HLS is disabled on the server:
5671 - field will be empty
5672 - video files will be found in `files` field
5673 FileRedundancyInformation:
5676 $ref: '#/components/schemas/id'
5701 $ref: '#/components/schemas/id'
5708 $ref: '#/components/schemas/UUIDv4'
5715 $ref: '#/components/schemas/FileRedundancyInformation'
5719 $ref: '#/components/schemas/FileRedundancyInformation'
5720 VideoImportStateConstant:
5728 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5735 additionalProperties: false
5739 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5740 required: [targetUrl]
5743 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5744 required: [magnetUri]
5747 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5748 required: [torrentfile]
5749 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5758 - $ref: '#/components/schemas/id'
5762 description: remote URL where to find the import's source video
5763 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5767 description: magnet URI allowing to resolve the import's source video
5768 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5773 description: Torrent file containing only the video file
5780 - $ref: '#/components/schemas/VideoImportStateConstant'
5796 - $ref: '#/components/schemas/Video'
5806 $ref: '#/components/schemas/VideoImport'
5810 $ref: '#/components/schemas/id'
5813 example: The video is a spam
5817 $ref: '#/components/schemas/AbusePredefinedReasons'
5819 $ref: '#/components/schemas/Account'
5821 $ref: '#/components/schemas/AbuseStateConstant'
5824 example: Decided to ban the server since it spams us regularly
5828 $ref: '#/components/schemas/VideoInfo'
5835 $ref: '#/components/schemas/id'
5846 $ref: '#/components/schemas/AccountSummary'
5850 $ref: '#/components/schemas/id'
5852 $ref: '#/components/schemas/Video/properties/id'
5864 $ref: '#/components/schemas/UUIDv4'
5882 $ref: '#/components/schemas/id'
5884 $ref: '#/components/schemas/UUIDv4'
5887 - $ref: '#/components/schemas/shortUUID'
5910 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5912 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5914 $ref: '#/components/schemas/AccountSummary'
5916 $ref: '#/components/schemas/VideoChannelSummary'
5920 $ref: '#/components/schemas/id'
5927 description: Text of the comment
5929 example: This video is wonderful!
5931 $ref: '#/components/schemas/id'
5935 - $ref: '#/components/schemas/id'
5937 $ref: '#/components/schemas/Video/properties/id'
5952 totalRepliesFromVideoAuthor:
5959 $ref: '#/components/schemas/Account'
5960 VideoCommentThreadTree:
5963 $ref: '#/components/schemas/VideoComment'
5967 $ref: '#/components/schemas/VideoCommentThreadTree'
5971 $ref: '#/components/schemas/VideoConstantString-Language'
5989 $ref: '#/components/schemas/id'
6000 $ref: '#/components/schemas/ActorImage'
6004 $ref: '#/components/schemas/id'
6009 description: immutable name of the actor, used to find or mention it
6011 - $ref: '#/components/schemas/username'
6015 description: server on which the actor is resident
6016 hostRedundancyAllowed:
6018 description: whether this actor's host allows redundancy of its videos
6022 description: number of actors subscribed to by this actor, as seen by this instance
6026 description: number of followers of this actor, as seen by this instance
6035 - $ref: '#/components/schemas/Actor'
6038 description: object id for the user tied to this account
6040 - $ref: '#/components/schemas/User/properties/id'
6043 description: editable name of the account, displayed in its representations
6048 description: text or bio displayed on the account's profile
6054 description: timestamp within the video, in seconds
6121 allowedForCurrentIP:
6123 requiresEmailVerification:
6141 $ref: '#/components/schemas/VideoResolutionSet'
6226 example: 16810141515
6335 requiresEmailVerification:
6350 description: Settings that apply to new users, if registration is enabled
6354 example: 16810141515
6360 description: Settings pertaining to transcoding jobs
6364 allowAdditionalExtensions:
6366 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6369 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6372 description: Amount of threads used by ffmpeg for 1 transcoding job
6375 description: Amount of transcoding jobs to execute in parallel
6381 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6384 description: Resolutions to transcode _new videos_ to
6406 description: WebTorrent-specific settings
6412 description: HLS-specific settings
6462 $ref: '#/components/schemas/id'
6464 $ref: '#/components/schemas/Actor'
6466 $ref: '#/components/schemas/Actor'
6469 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6482 PredefinedAbuseReasons:
6483 description: Reason categories that help triage reports
6501 $ref: '#/components/schemas/id'
6513 - activitypub-http-unicast
6514 - activitypub-http-broadcast
6515 - activitypub-http-fetcher
6516 - activitypub-follow
6521 - videos-views-stats
6522 - activitypub-refresher
6526 additionalProperties: true
6529 additionalProperties: true
6545 $ref: '#/components/schemas/id'
6550 $ref: '#/components/schemas/id'
6551 VideoUploadRequestCommon:
6554 description: Video name
6556 example: What is PeerTube?
6560 description: Channel id that will contain this video
6565 $ref: '#/components/schemas/VideoPrivacySet'
6567 $ref: '#/components/schemas/VideoCategorySet'
6569 $ref: '#/components/schemas/VideoLicenceSet'
6571 $ref: '#/components/schemas/VideoLanguageSet'
6573 description: Video description
6576 **[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)**
6578 description: Whether or not we wait transcoding before publish the video
6581 description: A text tell the audience how to support the video creator
6582 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6585 description: Whether or not this video contains sensitive content
6588 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6601 description: Enable or disable comments for this video
6604 description: Enable or disable downloading for this video
6606 originallyPublishedAt:
6607 description: Date when the content was originally published
6611 $ref: '#/components/schemas/VideoScheduledUpdate'
6613 description: Video thumbnail file
6617 description: Video preview file
6623 VideoUploadRequestLegacy:
6625 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6631 description: Video file
6634 VideoUploadRequestResumable:
6636 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6642 description: Video filename including extension
6645 example: what_is_peertube.mp4
6647 description: Video thumbnail file
6651 description: Video preview file
6654 VideoUploadResponse:
6660 $ref: '#/components/schemas/Video/properties/id'
6662 $ref: '#/components/schemas/Video/properties/uuid'
6664 $ref: '#/components/schemas/Video/properties/shortUUID'
6665 CommentThreadResponse:
6674 $ref: '#/components/schemas/VideoComment'
6675 CommentThreadPostResponse:
6678 $ref: '#/components/schemas/VideoComment'
6688 $ref: '#/components/schemas/Video'
6692 $ref: '#/components/schemas/Account'
6695 description: Automatically start playing the upcoming video after the currently playing video
6696 autoPlayNextVideoPlaylist:
6698 description: Automatically start playing the video on the playlist after the currently playing video
6701 description: Automatically start playing the video on the watch page
6711 description: The user email
6714 description: Has the user confirmed their email address?
6717 - $ref: '#/components/schemas/id'
6721 description: Auth plugin to use to authenticate the user
6725 noInstanceConfigWarningModal:
6727 noAccountSetupWarningModal:
6732 $ref: '#/components/schemas/NSFWPolicy'
6734 $ref: '#/components/schemas/UserRole'
6743 description: Theme enabled by this user
6745 $ref: '#/components/schemas/username'
6749 $ref: '#/components/schemas/VideoChannel'
6752 description: The user video quota in bytes
6756 description: The user daily video quota in bytes
6760 description: Enable P2P in the player
6763 - $ref: '#/components/schemas/User'
6765 # optionally present fields: they require WITH_STATS scope
6768 description: Count of videos published
6771 description: Count of reports/abuses of which the user is a target
6772 abusesAcceptedCount:
6774 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6777 description: Count of reports/abuses created by the user
6780 description: Count of comments published
6784 $ref: '#/components/schemas/username'
6786 $ref: '#/components/schemas/password'
6790 description: The user email
6793 description: The user video quota in bytes
6797 description: The user daily video quota in bytes
6800 $ref: '#/components/schemas/usernameChannel'
6802 $ref: '#/components/schemas/UserRole'
6804 $ref: '#/components/schemas/UserAdminFlags'
6815 description: The updated email of the user
6817 - $ref: '#/components/schemas/User/properties/email'
6820 description: Set the email as verified
6823 description: The updated video quota of the user in bytes
6826 description: The updated daily video quota of the user in bytes
6830 description: The auth plugin to use to authenticate the user
6831 example: 'peertube-plugin-auth-saml2'
6833 $ref: '#/components/schemas/UserRole'
6835 $ref: '#/components/schemas/UserAdminFlags'
6837 $ref: '#/components/schemas/password'
6839 # see shared/models/users/user-update-me.model.ts:
6842 $ref: '#/components/schemas/password'
6844 $ref: '#/components/schemas/password'
6846 description: new email used for login and service communications
6848 - $ref: '#/components/schemas/User/properties/email'
6851 description: new name of the user in its representations
6856 description: new NSFW display policy
6863 description: whether to enable P2P in the player or not
6866 description: new preference regarding playing videos automatically
6869 description: new preference regarding playing following videos automatically
6870 autoPlayNextVideoPlaylist:
6872 description: new preference regarding playing following playlist videos automatically
6873 videosHistoryEnabled:
6875 description: whether to keep track of watched history or not
6880 description: list of languages to filter videos down to
6883 noInstanceConfigWarningModal:
6885 noAccountSetupWarningModal:
6892 $ref: '#/components/schemas/id'
6899 description: Rating of the video
6906 $ref: '#/components/schemas/Video'
6913 description: Rating of the video
6920 description: immutable name of the user, used to find or mention its actor
6922 - $ref: '#/components/schemas/username'
6924 $ref: '#/components/schemas/password'
6928 description: email of the user, used for login or service communications
6931 description: editable name of the user, displayed in its representations
6936 description: channel base information used to create the first channel of the user
6939 $ref: '#/components/schemas/usernameChannel'
6951 pattern: /^[a-z0-9]$/
6954 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6957 pattern: /^[a-zA-Z0-9]$/
6960 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6961 OAuthToken-password:
6963 - $ref: '#/components/schemas/OAuthClient'
6973 $ref: '#/components/schemas/User/properties/username'
6975 $ref: '#/components/schemas/password'
6982 OAuthToken-refresh_token:
6984 - $ref: '#/components/schemas/OAuthClient'
6995 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7004 - $ref: '#/components/schemas/Actor'
7009 description: editable name of the channel, displayed in its representations
7010 example: Videos of Framasoft
7015 example: Videos made with <3 by Framasoft
7020 description: text shown by default on all videos of this channel, to tell the audience how to support it
7021 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7034 $ref: '#/components/schemas/ActorImage'
7043 $ref: '#/components/schemas/UUIDv4'
7046 - $ref: '#/components/schemas/VideoChannel'
7049 description: username of the channel to create
7051 - $ref: '#/components/schemas/usernameChannel'
7057 - $ref: '#/components/schemas/VideoChannel'
7059 bulkVideosSupportUpdate:
7061 description: Update the support field for all videos of this channel
7071 - $ref: '#/components/schemas/VideoChannel'
7072 - $ref: '#/components/schemas/Actor'
7077 name: 'media:peerLink'
7086 - application/x-bittorrent
7092 name: 'media:content'
7123 VideoCommentsForXML:
7158 description: video watch page URL
7161 description: video canonical URL
7165 description: video publication date
7168 description: video description
7171 description: video description
7174 description: publisher user name
7177 description: video category (MRSS)
7180 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7195 description: video embed path, relative to the canonical URL domain (MRSS)
7204 description: video watch path, relative to the canonical URL domain (MRSS)
7225 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7226 'media:description':
7233 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7236 description: main streamable file for the video
7246 - application/x-bittorrent
7255 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)
7258 - $ref: '#/components/schemas/MRSSPeerLink'
7259 - $ref: '#/components/schemas/MRSSGroupContent'
7260 NotificationSettingValue:
7277 $ref: '#/components/schemas/id'
7281 Notification type, following the `UserNotificationType` enum:
7283 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7285 - `2` NEW_COMMENT_ON_MY_VIDEO
7287 - `3` NEW_ABUSE_FOR_MODERATORS
7289 - `4` BLACKLIST_ON_MY_VIDEO
7291 - `5` UNBLACKLIST_ON_MY_VIDEO
7293 - `6` MY_VIDEO_PUBLISHED
7295 - `7` MY_VIDEO_IMPORT_SUCCESS
7297 - `8` MY_VIDEO_IMPORT_ERROR
7299 - `9` NEW_USER_REGISTRATION
7303 - `11` COMMENT_MENTION
7305 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7307 - `13` NEW_INSTANCE_FOLLOWER
7309 - `14` AUTO_INSTANCE_FOLLOWING
7311 - `15` ABUSE_STATE_CHANGE
7313 - `16` ABUSE_NEW_MESSAGE
7315 - `17` NEW_PLUGIN_VERSION
7317 - `18` NEW_PEERTUBE_VERSION
7323 - $ref: '#/components/schemas/VideoInfo'
7327 $ref: '#/components/schemas/ActorInfo'
7333 $ref: '#/components/schemas/id'
7336 $ref: '#/components/schemas/VideoInfo'
7341 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7351 $ref: '#/components/schemas/id'
7355 $ref: '#/components/schemas/VideoInfo'
7357 $ref: '#/components/schemas/ActorInfo'
7363 $ref: '#/components/schemas/id'
7366 - $ref: '#/components/schemas/VideoInfo'
7372 $ref: '#/components/schemas/id'
7375 - $ref: '#/components/schemas/VideoInfo'
7379 - $ref: '#/components/schemas/ActorInfo'
7385 $ref: '#/components/schemas/id'
7387 $ref: '#/components/schemas/ActorInfo'
7415 NotificationListResponse:
7424 $ref: '#/components/schemas/Notification'
7429 example: peertube-plugin-auth-ldap
7457 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7460 additionalProperties: true
7476 $ref: '#/components/schemas/Plugin'
7483 description: User can stream multiple times in a permanent live
7494 description: RTMP stream key to use to stream into this live video
7498 description: User can stream multiple times in a permanent live
7505 'https://search.example.org/api/v1/search/videos':
7507 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7510 description: successful operation
7514 $ref: '#/components/schemas/VideoListResponse'