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",
55 We provide error types for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
56 but it is still optional.
60 Each parameter is evaluated on its own against a set of rules before the route validator
61 proceeds with potential testing involving parameter combinations. Errors coming from validation
62 errors appear earlier and benefit from a more detailed error type:
65 HTTP 1.1 400 Bad Request
66 Content-Type: application/problem+json; charset=utf-8
69 "detail": "Incorrect request parameters: id",
70 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
74 "msg": "Invalid value",
76 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
80 "title": "Bad Request",
85 Where `id` is the name of the field concerned by the error, within the route definition.
86 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
87 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
92 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
94 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
95 |------------------------------|---------------|--------------|
96 | `/*` | 50 | 10 seconds |
97 | `POST /users/token` | 15 | 5 minutes |
98 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
99 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
101 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
102 limit is announced by a `429 Too Many Requests` status code.
104 You can get details about the current state of your rate limit by reading the
107 | Header | Description |
108 |-------------------------|------------------------------------------------------------|
109 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
110 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
111 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
112 | `Retry-After` | Seconds to delay after the first `429` is received |
116 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
117 allowing cross-domain communication from the browser for some routes:
120 |------------------------- ---|
124 | `/live/segments-sha256/*` |
125 | `/.well-known/webfinger` |
127 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
129 url: https://docs.joinpeertube.org/api-rest-reference.html
133 As a visitor, you can use this API to open an account (if registrations are open on
134 that PeerTube instance). As an admin, you should use the dedicated [User creation
135 API](#operation/addUser) instead.
137 x-displayName: Login/Logout
139 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
142 Accounts encompass remote accounts discovered across the federation,
143 and correspond to the main Actor, along with video channels a user can create, which
146 When a comment is posted, it is done with your Account's Actor.
149 Using some features of PeerTube require authentication, for which User
150 provide different levels of permission as well as associated user
151 information. Each user has a corresponding local Account for federation.
154 Operations related to your own User, when logged-in.
155 - name: My Subscriptions
157 Operations related to your subscriptions to video channels, their
158 new videos, and how to keep up to date with their latest publications!
161 Operations related to your watch history.
162 - name: My Notifications
164 Notifications following new videos, follows or reports. They allow you
165 to keep track of the interactions and overall important information that
166 concerns you. You MAY set per-notification type delivery preference, to
167 receive the info either by mail, by in-browser notification or both.
170 Each server exposes public information regarding supported videos and
174 Jobs are long-running tasks enqueued and processed by the instance
175 itself. No additional worker registration is currently available.
176 - name: Instance Follows
178 Managing servers which the instance interacts with is crucial to the
179 concept of federation in PeerTube and external video indexation. The PeerTube
180 server then deals with inter-server ActivityPub operations and propagates
181 information across its social graph by posting activities to actors' inbox
184 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
185 - name: Instance Redundancy
187 Redundancy is part of the inter-server solidarity that PeerTube fosters.
188 Manage the list of instances you wish to help by seeding their videos according
189 to the policy of video selection of your choice. Note that you have a similar functionality
190 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
192 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
195 Managing plugins installed from a local path or from NPM, or search for new ones.
197 url: https://docs.joinpeertube.org/api-plugins
200 Abuses deal with reports of local or remote videos/comments/accounts alike.
203 Operations dealing with listing, uploading, fetching or modifying videos.
206 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
210 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
211 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
213 You can upload videos more reliably by using the resumable variant. Its protocol lets
214 you resume an upload operation after a network interruption or other transmission failure,
215 saving time and bandwidth in the event of network failures.
217 Favor using resumable uploads in any of the following cases:
218 - You are transferring large files
219 - The likelihood of a network interruption is high
220 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
221 such as a mobile device
225 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
226 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
227 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
229 The import function is practical when the desired video/audio is available online. It makes PeerTube
230 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
231 - name: Video Captions
232 description: Operations dealing with listing, adding and removing closed captions of a video.
233 - name: Video Channels
234 description: Operations dealing with the creation, modification and listing of videos within a channel.
235 - name: Video Comments
237 Operations dealing with comments to a video. Comments are organized in threads: adding a
238 comment in response to the video starts a thread, adding a reply to a comment adds it to
239 its root comment thread.
241 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
243 description: Like/dislike a video.
244 - name: Video Playlists
245 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
247 description: Server syndication feeds
250 The search helps to find _videos_ or _channels_ from within the instance and beyond.
251 Videos from other instances federated by the instance (that is, instances
252 followed by the instance) can be found via keywords and other criteria of
255 Administrators can also enable the use of a remote search system, indexing
256 videos and channels not could be not federated by the instance.
258 description: Get and update the custom homepage
259 - name: Video Mirroring
261 PeerTube instances can mirror videos from one another, and help distribute some videos.
263 For importing videos as your own, refer to [video imports](#operation/importVideo).
286 - Video Ownership Change
302 - name: Instance Configuration
306 - Instance Redundancy
316 summary: Get an account
317 operationId: getAccount
319 - $ref: '#/components/parameters/name'
322 description: successful operation
326 $ref: '#/components/schemas/Account'
328 description: account not found
330 '/accounts/{name}/videos':
335 summary: 'List videos of an account'
336 operationId: getAccountVideos
338 - $ref: '#/components/parameters/name'
339 - $ref: '#/components/parameters/categoryOneOf'
340 - $ref: '#/components/parameters/isLive'
341 - $ref: '#/components/parameters/tagsOneOf'
342 - $ref: '#/components/parameters/tagsAllOf'
343 - $ref: '#/components/parameters/licenceOneOf'
344 - $ref: '#/components/parameters/languageOneOf'
345 - $ref: '#/components/parameters/nsfw'
346 - $ref: '#/components/parameters/filter'
347 - $ref: '#/components/parameters/skipCount'
348 - $ref: '#/components/parameters/start'
349 - $ref: '#/components/parameters/count'
350 - $ref: '#/components/parameters/videosSort'
353 description: successful operation
357 $ref: '#/components/schemas/VideoListResponse'
361 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
362 .then(function(response) {
363 return response.json()
364 }).then(function(data) {
370 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
376 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
378 http = Net::HTTP.new(uri.host, uri.port)
381 response = http.get(uri.request_uri)
383 puts JSON.parse(response.read_body)
388 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
397 summary: List accounts
398 operationId: getAccounts
400 - $ref: '#/components/parameters/start'
401 - $ref: '#/components/parameters/count'
402 - $ref: '#/components/parameters/sort'
405 description: successful operation
411 $ref: '#/components/schemas/Account'
417 summary: Get instance public configuration
418 operationId: getConfig
421 description: successful operation
425 $ref: '#/components/schemas/ServerConfig'
428 externalValue: https://peertube2.cpy.re/api/v1/config
432 summary: Get instance "About" information
433 operationId: getAbout
438 description: successful operation
442 $ref: '#/components/schemas/ServerConfigAbout'
445 externalValue: https://peertube2.cpy.re/api/v1/config/about
449 summary: Get instance runtime configuration
450 operationId: getCustomConfig
458 description: successful operation
462 $ref: '#/components/schemas/ServerConfigCustom'
464 summary: Set instance runtime configuration
465 operationId: putCustomConfig
473 description: successful operation
475 x-summary: field inconsistencies
478 - the emailer is disabled and the instance is open to registrations
479 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
481 summary: Delete instance runtime configuration
482 operationId: delCustomConfig
490 description: successful operation
492 /custom-pages/homepage/instance:
494 summary: Get instance custom homepage
499 description: No homepage set
501 description: successful operation
505 $ref: '#/components/schemas/CustomHomepage'
507 summary: Set instance custom homepage
521 description: content of the homepage, that will be injected in the client
524 description: successful operation
528 summary: List instance jobs
539 description: The state of the job ('' for for no filter)
549 - $ref: '#/components/parameters/jobType'
550 - $ref: '#/components/parameters/start'
551 - $ref: '#/components/parameters/count'
552 - $ref: '#/components/parameters/sort'
555 description: successful operation
568 $ref: '#/components/schemas/Job'
574 summary: List instances following the server
576 - $ref: '#/components/parameters/followState'
577 - $ref: '#/components/parameters/actorType'
578 - $ref: '#/components/parameters/start'
579 - $ref: '#/components/parameters/count'
580 - $ref: '#/components/parameters/sort'
583 description: successful operation
595 $ref: '#/components/schemas/Follow'
597 '/server/followers/{nameWithHost}':
599 summary: Remove or reject a follower to your server
609 description: The remote actor handle to remove from your followers
615 description: successful operation
617 description: follower not found
619 '/server/followers/{nameWithHost}/reject':
621 summary: Reject a pending follower to your server
631 description: The remote actor handle to remove from your followers
637 description: successful operation
639 description: follower not found
641 '/server/followers/{nameWithHost}/accept':
643 summary: Accept a pending follower to your server
653 description: The remote actor handle to remove from your followers
659 description: successful operation
661 description: follower not found
667 summary: List instances followed by the server
669 - $ref: '#/components/parameters/followState'
670 - $ref: '#/components/parameters/actorType'
671 - $ref: '#/components/parameters/start'
672 - $ref: '#/components/parameters/count'
673 - $ref: '#/components/parameters/sort'
676 description: successful operation
688 $ref: '#/components/schemas/Follow'
695 summary: Follow a list of servers
698 description: successful operation
700 description: cannot follow a non-HTTPS server
714 '/server/following/{host}':
716 summary: Unfollow a server
726 description: The host to unfollow
732 description: successful operation
734 description: host not found
738 summary: Create a user
747 description: user created
751 $ref: '#/components/schemas/AddUserResponse'
757 id: '$response.body#/user/id'
762 id: '$response.body#/user/id'
767 id: '$response.body#/user/id'
769 description: insufficient authority to create an admin or moderator
774 $ref: '#/components/schemas/AddUser'
776 If the smtp server is configured, you can leave the password empty and an email will be sent
777 asking the user to set it first.
781 operationId: getUsers
788 - $ref: '#/components/parameters/usersSearch'
789 - $ref: '#/components/parameters/usersBlocked'
790 - $ref: '#/components/parameters/start'
791 - $ref: '#/components/parameters/count'
792 - $ref: '#/components/parameters/usersSort'
795 description: successful operation
801 $ref: '#/components/schemas/User'
805 - $ref: '#/components/parameters/id'
807 summary: Delete a user
816 description: successful operation
827 description: include statistics about the user (only available as a moderator/admin)
832 x-summary: successful operation
834 As an admin/moderator, you can request a response augmented with statistics about the user's
835 moderation relations and videos usage, by using the `withStats` parameter.
840 - $ref: '#/components/schemas/User'
841 - $ref: '#/components/schemas/UserWithStats'
843 summary: Update a user
851 description: successful operation
856 $ref: '#/components/schemas/UpdateUser'
859 /oauth-clients/local:
861 summary: Login prerequisite
862 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
863 operationId: getOAuthClient
868 description: successful operation
872 $ref: '#/components/schemas/OAuthClient'
874 UseOAuthClientToLogin:
875 operationId: getOAuthToken
877 client_id: '$response.body#/client_id'
878 client_secret: '$response.body#/client_secret'
882 API="https://peertube2.cpy.re/api/v1"
885 curl -s "$API/oauth-clients/local"
890 operationId: getOAuthToken
891 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
896 application/x-www-form-urlencoded:
899 - $ref: '#/components/schemas/OAuthToken-password'
900 - $ref: '#/components/schemas/OAuthToken-refresh_token'
902 propertyName: grant_type
904 password: '#/components/schemas/OAuthToken-password'
905 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
908 description: successful operation
919 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
920 description: valid for 1 day
923 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
924 description: valid for 2 weeks
929 refresh_token_expires_in:
937 API="https://peertube2.cpy.re/api/v1"
938 USERNAME="<your_username>"
939 PASSWORD="<your_password>"
942 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
943 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
944 curl -s "$API/users/token" \
945 --data client_id="$client_id" \
946 --data client_secret="$client_secret" \
947 --data grant_type=password \
948 --data username="$USERNAME" \
949 --data password="$PASSWORD" \
950 | jq -r ".access_token"
955 description: Revokes your access token and its associated refresh token, destroying your current session.
956 operationId: revokeOAuthToken
963 description: successful operation
967 summary: Register a user
968 operationId: registerUser
974 description: successful operation
979 $ref: '#/components/schemas/RegisterUser'
982 /users/{id}/verify-email:
984 summary: Verify a user
985 operationId: verifyUser
987 Following a user registration, the new user will receive an email asking to click a link
993 - $ref: '#/components/parameters/id'
1006 - verificationString
1009 description: successful operation
1011 description: invalid verification string
1013 description: user not found
1015 /users/ask-send-verify-email:
1017 summary: Resend user verification link
1018 operationId: resendEmailToVerifyUser
1024 description: successful operation
1028 summary: Get my user information
1029 operationId: getUserInfo
1037 description: successful operation
1043 $ref: '#/components/schemas/User'
1045 summary: Update my user information
1046 operationId: putUserInfo
1054 description: successful operation
1059 $ref: '#/components/schemas/UpdateMe'
1062 /users/me/videos/imports:
1064 summary: Get video imports of my user
1072 - $ref: '#/components/parameters/start'
1073 - $ref: '#/components/parameters/count'
1074 - $ref: '#/components/parameters/sort'
1077 description: successful operation
1081 $ref: '#/components/schemas/VideoImportsList'
1083 /users/me/video-quota-used:
1085 summary: Get my user used quota
1093 description: successful operation
1101 description: The user video quota used so far in bytes
1102 example: 16810141515
1103 videoQuotaUsedDaily:
1105 description: The user video quota used today in bytes
1108 '/users/me/videos/{videoId}/rating':
1110 summary: Get rate of my user for a video
1120 description: The video id
1122 $ref: '#/components/schemas/Video/properties/id'
1125 description: successful operation
1129 $ref: '#/components/schemas/GetMeVideoRating'
1133 summary: Get videos of my user
1141 - $ref: '#/components/parameters/start'
1142 - $ref: '#/components/parameters/count'
1143 - $ref: '#/components/parameters/sort'
1146 description: successful operation
1150 $ref: '#/components/schemas/VideoListResponse'
1152 /users/me/subscriptions:
1154 summary: Get my user subscriptions
1161 - $ref: '#/components/parameters/start'
1162 - $ref: '#/components/parameters/count'
1163 - $ref: '#/components/parameters/sort'
1166 description: successful operation
1170 $ref: '#/components/schemas/VideoChannelList'
1174 summary: Add subscription to my user
1187 description: uri of the video channels to subscribe to
1193 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1196 description: successful operation
1198 /users/me/subscriptions/exist:
1200 summary: Get if subscriptions exist for my user
1207 - $ref: '#/components/parameters/subscriptionsUris'
1210 description: successful operation
1216 /users/me/subscriptions/videos:
1218 summary: List videos of subscriptions of my user
1226 - $ref: '#/components/parameters/categoryOneOf'
1227 - $ref: '#/components/parameters/isLive'
1228 - $ref: '#/components/parameters/tagsOneOf'
1229 - $ref: '#/components/parameters/tagsAllOf'
1230 - $ref: '#/components/parameters/licenceOneOf'
1231 - $ref: '#/components/parameters/languageOneOf'
1232 - $ref: '#/components/parameters/nsfw'
1233 - $ref: '#/components/parameters/filter'
1234 - $ref: '#/components/parameters/skipCount'
1235 - $ref: '#/components/parameters/start'
1236 - $ref: '#/components/parameters/count'
1237 - $ref: '#/components/parameters/videosSort'
1240 description: successful operation
1244 $ref: '#/components/schemas/VideoListResponse'
1246 '/users/me/subscriptions/{subscriptionHandle}':
1248 summary: Get subscription of my user
1255 - $ref: '#/components/parameters/subscriptionHandle'
1258 description: successful operation
1262 $ref: '#/components/schemas/VideoChannel'
1264 summary: Delete subscription of my user
1271 - $ref: '#/components/parameters/subscriptionHandle'
1274 description: successful operation
1276 /users/me/notifications:
1278 summary: List my notifications
1286 description: only list unread notifications
1289 - $ref: '#/components/parameters/start'
1290 - $ref: '#/components/parameters/count'
1291 - $ref: '#/components/parameters/sort'
1294 description: successful operation
1298 $ref: '#/components/schemas/NotificationListResponse'
1300 /users/me/notifications/read:
1302 summary: Mark notifications as read by their id
1315 description: ids of the notifications to mark as read
1322 description: successful operation
1324 /users/me/notifications/read-all:
1326 summary: Mark all my notification as read
1333 description: successful operation
1335 /users/me/notification-settings:
1337 summary: Update my notification settings
1348 newVideoFromSubscription:
1349 $ref: '#/components/schemas/NotificationSettingValue'
1350 newCommentOnMyVideo:
1351 $ref: '#/components/schemas/NotificationSettingValue'
1353 $ref: '#/components/schemas/NotificationSettingValue'
1354 videoAutoBlacklistAsModerator:
1355 $ref: '#/components/schemas/NotificationSettingValue'
1357 $ref: '#/components/schemas/NotificationSettingValue'
1359 $ref: '#/components/schemas/NotificationSettingValue'
1360 myVideoImportFinished:
1361 $ref: '#/components/schemas/NotificationSettingValue'
1363 $ref: '#/components/schemas/NotificationSettingValue'
1364 newUserRegistration:
1365 $ref: '#/components/schemas/NotificationSettingValue'
1367 $ref: '#/components/schemas/NotificationSettingValue'
1368 newInstanceFollower:
1369 $ref: '#/components/schemas/NotificationSettingValue'
1370 autoInstanceFollowing:
1371 $ref: '#/components/schemas/NotificationSettingValue'
1374 description: successful operation
1376 /users/me/history/videos:
1378 summary: List watched videos history
1384 - $ref: '#/components/parameters/start'
1385 - $ref: '#/components/parameters/count'
1386 - $ref: '#/components/parameters/search'
1389 description: successful operation
1393 $ref: '#/components/schemas/VideoListResponse'
1395 /users/me/history/videos/remove:
1397 summary: Clear video history
1404 multipart/form-data:
1409 description: history before this date will be deleted
1414 description: successful operation
1416 /users/me/avatar/pick:
1418 summary: Update my user avatar
1425 description: successful operation
1432 $ref: '#/components/schemas/ActorImage'
1434 description: image file too large
1436 X-File-Maximum-Size:
1440 description: Maximum file size for the avatar
1443 multipart/form-data:
1448 description: The file to upload
1453 contentType: image/png, image/jpeg
1457 summary: Delete my avatar
1464 description: successful operation
1468 summary: List video ownership changes
1470 - Video Ownership Change
1475 description: successful operation
1477 '/videos/ownership/{id}/accept':
1479 summary: Accept ownership change request
1481 - Video Ownership Change
1485 - $ref: '#/components/parameters/idOrUUID'
1488 description: successful operation
1490 description: cannot terminate an ownership change of another user
1492 description: video owneship change not found
1494 '/videos/ownership/{id}/refuse':
1496 summary: Refuse ownership change request
1498 - Video Ownership Change
1502 - $ref: '#/components/parameters/idOrUUID'
1505 description: successful operation
1507 description: cannot terminate an ownership change of another user
1509 description: video owneship change not found
1511 '/videos/{id}/give-ownership':
1513 summary: Request ownership change
1515 - Video Ownership Change
1519 - $ref: '#/components/parameters/idOrUUID'
1523 application/x-www-form-urlencoded:
1533 description: successful operation
1535 description: changing video ownership to a remote account is not supported yet
1537 description: video not found
1541 summary: List videos
1542 operationId: getVideos
1546 - $ref: '#/components/parameters/categoryOneOf'
1547 - $ref: '#/components/parameters/isLive'
1548 - $ref: '#/components/parameters/tagsOneOf'
1549 - $ref: '#/components/parameters/tagsAllOf'
1550 - $ref: '#/components/parameters/licenceOneOf'
1551 - $ref: '#/components/parameters/languageOneOf'
1552 - $ref: '#/components/parameters/nsfw'
1553 - $ref: '#/components/parameters/filter'
1554 - $ref: '#/components/parameters/skipCount'
1555 - $ref: '#/components/parameters/start'
1556 - $ref: '#/components/parameters/count'
1557 - $ref: '#/components/parameters/videosSort'
1560 description: successful operation
1564 $ref: '#/components/schemas/VideoListResponse'
1568 summary: List available video categories
1569 operationId: getCategories
1574 description: successful operation
1583 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1587 summary: List available video licences
1588 operationId: getLicences
1593 description: successful operation
1602 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1606 summary: List available video languages
1607 operationId: getLanguages
1612 description: successful operation
1621 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1625 summary: List available video privacy policies
1626 operationId: getPrivacyPolicies
1631 description: successful operation
1640 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1644 summary: Update a video
1645 operationId: putVideo
1651 - $ref: '#/components/parameters/idOrUUID'
1654 description: successful operation
1657 multipart/form-data:
1662 description: Video thumbnail file
1666 description: Video preview file
1670 $ref: '#/components/schemas/VideoCategorySet'
1672 $ref: '#/components/schemas/VideoLicenceSet'
1674 $ref: '#/components/schemas/VideoLanguageSet'
1676 $ref: '#/components/schemas/VideoPrivacySet'
1678 description: Video description
1681 description: Whether or not we wait transcoding before publish the video
1684 description: A text tell the audience how to support the video creator
1685 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1688 description: Whether or not this video contains sensitive content
1691 description: Video name
1696 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1705 description: Enable or disable comments for this video
1707 originallyPublishedAt:
1708 description: Date when the content was originally published
1712 $ref: '#/components/schemas/VideoScheduledUpdate'
1715 contentType: image/jpeg
1717 contentType: image/jpeg
1719 summary: Get a video
1720 operationId: getVideo
1724 - $ref: '#/components/parameters/idOrUUID'
1727 description: successful operation
1731 $ref: '#/components/schemas/VideoDetails'
1733 summary: Delete a video
1734 operationId: delVideo
1740 - $ref: '#/components/parameters/idOrUUID'
1743 description: successful operation
1745 '/videos/{id}/description':
1747 summary: Get complete video description
1748 operationId: getVideoDesc
1752 - $ref: '#/components/parameters/idOrUUID'
1755 description: successful operation
1764 **[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)**
1766 '/videos/{id}/views':
1768 summary: Add a view to a video
1772 - $ref: '#/components/parameters/idOrUUID'
1775 description: successful operation
1777 '/videos/{id}/watching':
1779 summary: Set watching progress of a video
1785 - $ref: '#/components/parameters/idOrUUID'
1790 $ref: '#/components/schemas/UserWatchingVideo'
1794 description: successful operation
1798 summary: Upload a video
1799 description: Uses a single request to upload a video.
1800 operationId: uploadLegacy
1808 description: successful operation
1812 $ref: '#/components/schemas/VideoUploadResponse'
1814 description: invalid file field, schedule date or parameter
1816 description: video didn't pass upload filter
1818 description: upload has timed out
1820 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1822 X-File-Maximum-Size:
1826 description: Maximum file size for the video
1828 description: video type unsupported
1830 description: video unreadable
1833 multipart/form-data:
1835 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1838 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1840 contentType: image/jpeg
1842 contentType: image/jpeg
1847 USERNAME="<your_username>"
1848 PASSWORD="<your_password>"
1849 FILE_PATH="<your_file_path>"
1850 CHANNEL_ID="<your_channel_id>"
1852 API="https://peertube2.cpy.re/api/v1"
1855 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1856 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1857 token=$(curl -s "$API/users/token" \
1858 --data client_id="$client_id" \
1859 --data client_secret="$client_secret" \
1860 --data grant_type=password \
1861 --data username="$USERNAME" \
1862 --data password="$PASSWORD" \
1863 | jq -r ".access_token")
1866 curl -s "$API/videos/upload" \
1867 -H "Authorization: Bearer $token" \
1869 --form videofile=@"$FILE_PATH" \
1870 --form channelId=$CHANNEL_ID \
1873 /videos/upload-resumable:
1875 summary: Initialize the resumable upload of a video
1876 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1877 operationId: uploadResumableInit
1884 - name: X-Upload-Content-Length
1890 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1891 - name: X-Upload-Content-Type
1898 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1903 $ref: '#/components/schemas/VideoUploadRequestResumable'
1906 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1908 description: created
1914 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1920 description: invalid file field, schedule date or parameter
1922 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1924 description: video type unsupported
1926 summary: Send chunk for the resumable upload of a video
1927 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
1928 operationId: uploadResumable
1939 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1940 not valid anymore and you need to initialize a new upload.
1943 - name: Content-Range
1947 example: bytes 0-262143/2469036
1950 Specifies the bytes in the file that the request is uploading.
1952 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1953 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1954 - name: Content-Length
1961 Size of the chunk that the request is sending.
1963 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)
1964 doesn't mandate for chunks to have the same size throughout the upload sequence.
1966 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1967 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1970 application/octet-stream:
1976 description: last chunk received
1984 $ref: '#/components/schemas/VideoUploadResponse'
1986 description: resume incomplete
1991 example: bytes=0-262143
1997 description: video didn't pass upload filter
1999 description: video file too large, due to quota or max body size limit set by the reverse-proxy
2001 description: video unreadable
2003 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2004 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2005 operationId: uploadResumableCancel
2016 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2017 not valid anymore and the upload session has already been deleted with its data ;-)
2020 - name: Content-Length
2028 description: upload cancelled
2037 summary: Import a video
2038 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2039 operationId: importVideo
2047 multipart/form-data:
2049 $ref: '#/components/schemas/VideoCreateImport'
2052 contentType: application/x-bittorrent
2054 contentType: image/jpeg
2056 contentType: image/jpeg
2059 description: successful operation
2063 $ref: '#/components/schemas/VideoUploadResponse'
2065 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2067 description: video didn't pass pre-import filter
2069 description: HTTP or Torrent/magnetURI import not enabled
2073 summary: Create a live
2074 operationId: addLive
2082 description: successful operation
2086 $ref: '#/components/schemas/VideoUploadResponse'
2088 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2091 multipart/form-data:
2096 description: Channel id that will contain this live video
2101 description: User can stream multiple times in a permanent live
2104 description: Live video/replay thumbnail file
2108 description: Live video/replay preview file
2112 $ref: '#/components/schemas/VideoPrivacySet'
2114 $ref: '#/components/schemas/VideoCategorySet'
2116 $ref: '#/components/schemas/VideoLicenceSet'
2118 $ref: '#/components/schemas/VideoLanguageSet'
2120 description: Live video/replay description
2123 description: A text tell the audience how to support the creator
2124 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2127 description: Whether or not this live video/replay contains sensitive content
2130 description: Live video/replay name
2135 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2144 description: Enable or disable comments for this live video/replay
2147 description: Enable or disable downloading for the replay of this live
2154 contentType: image/jpeg
2156 contentType: image/jpeg
2160 summary: Get information about a live
2161 operationId: getLiveId
2168 - $ref: '#/components/parameters/idOrUUID'
2171 description: successful operation
2175 $ref: '#/components/schemas/LiveVideoResponse'
2177 summary: Update information about a live
2178 operationId: updateLiveId
2185 - $ref: '#/components/parameters/idOrUUID'
2190 $ref: '#/components/schemas/LiveVideoUpdate'
2193 description: successful operation
2195 description: bad parameters or trying to update a live that has already started
2197 description: trying to save replay of the live but saving replay is not enabled on the instance
2201 summary: List my abuses
2202 operationId: getMyAbuses
2211 description: only list the report with this id
2217 $ref: '#/components/schemas/AbuseStateSet'
2218 - $ref: '#/components/parameters/abusesSort'
2219 - $ref: '#/components/parameters/start'
2220 - $ref: '#/components/parameters/count'
2223 description: successful operation
2235 $ref: '#/components/schemas/Abuse'
2239 summary: List abuses
2240 operationId: getAbuses
2250 description: only list the report with this id
2253 - name: predefinedReason
2255 description: predefined reason the listed reports should contain
2257 $ref: '#/components/schemas/PredefinedAbuseReasons'
2260 description: plain search that will match with video titles, reporter names and more
2266 $ref: '#/components/schemas/AbuseStateSet'
2267 - name: searchReporter
2269 description: only list reports of a specific reporter
2272 - name: searchReportee
2273 description: only list reports of a specific reportee
2279 description: only list reports of a specific video
2282 - name: searchVideoChannel
2284 description: only list reports of a specific video channel
2289 description: only list blacklisted or deleted videos
2297 description: only list account, comment or video reports
2304 - $ref: '#/components/parameters/start'
2305 - $ref: '#/components/parameters/count'
2306 - $ref: '#/components/parameters/abusesSort'
2309 description: successful operation
2321 $ref: '#/components/schemas/Abuse'
2323 summary: Report an abuse
2336 description: Reason why the user reports this video
2341 $ref: '#/components/schemas/PredefinedAbuseReasons'
2346 description: Video id to report
2348 - $ref: '#/components/schemas/Video/properties/id'
2352 description: Timestamp in the video that marks the beginning of the report
2357 description: Timestamp in the video that marks the ending of the report
2363 description: Comment id to report
2365 - $ref: '#/components/schemas/VideoComment/properties/id'
2370 description: Account id to report
2376 description: successful operation
2386 $ref: '#/components/schemas/id'
2388 description: incorrect request parameters
2390 '/abuses/{abuseId}':
2392 summary: Update an abuse
2400 - $ref: '#/components/parameters/abuseId'
2408 $ref: '#/components/schemas/AbuseStateSet'
2411 description: Update the report comment visible only to the moderation team
2416 description: successful operation
2418 description: abuse not found
2422 summary: Delete an abuse
2428 - $ref: '#/components/parameters/abuseId'
2431 description: successful operation
2433 description: block not found
2435 '/abuses/{abuseId}/messages':
2437 summary: List messages of an abuse
2443 - $ref: '#/components/parameters/abuseId'
2446 description: successful operation
2458 $ref: '#/components/schemas/AbuseMessage'
2460 summary: Add message to an abuse
2466 - $ref: '#/components/parameters/abuseId'
2475 description: Message to send
2483 description: successful operation
2485 description: incorrect request parameters
2487 '/abuses/{abuseId}/messages/{abuseMessageId}':
2489 summary: Delete an abuse message
2495 - $ref: '#/components/parameters/abuseId'
2496 - $ref: '#/components/parameters/abuseMessageId'
2499 description: successful operation
2501 '/videos/{id}/blacklist':
2503 summary: Block a video
2504 operationId: addVideoBlock
2512 - $ref: '#/components/parameters/idOrUUID'
2515 description: successful operation
2517 summary: Unblock a video by its id
2518 operationId: delVideoBlock
2526 - $ref: '#/components/parameters/idOrUUID'
2529 description: successful operation
2531 description: block not found
2537 summary: List video blocks
2538 operationId: getVideoBlocks
2547 list only blocks that match this type:
2551 - `2`: automatic block that needs review
2559 description: plain search that will match with video titles, and more
2562 - $ref: '#/components/parameters/start'
2563 - $ref: '#/components/parameters/count'
2564 - $ref: '#/components/parameters/blacklistsSort'
2567 description: successful operation
2579 $ref: '#/components/schemas/VideoBlacklist'
2581 /videos/{id}/captions:
2583 summary: List captions of a video
2584 operationId: getVideoCaptions
2588 - $ref: '#/components/parameters/idOrUUID'
2591 description: successful operation
2603 $ref: '#/components/schemas/VideoCaption'
2605 /videos/{id}/captions/{captionLanguage}:
2607 summary: Add or replace a video caption
2608 operationId: addVideoCaption
2615 - $ref: '#/components/parameters/idOrUUID'
2616 - $ref: '#/components/parameters/captionLanguage'
2619 multipart/form-data:
2624 description: The file to upload.
2629 contentType: text/vtt, application/x-subrip, text/plain
2632 description: successful operation
2634 description: video or language not found
2636 summary: Delete a video caption
2637 operationId: delVideoCaption
2644 - $ref: '#/components/parameters/idOrUUID'
2645 - $ref: '#/components/parameters/captionLanguage'
2648 description: successful operation
2650 description: video or language or caption for that language not found
2654 summary: List video channels
2655 operationId: getVideoChannels
2659 - $ref: '#/components/parameters/start'
2660 - $ref: '#/components/parameters/count'
2661 - $ref: '#/components/parameters/sort'
2664 description: successful operation
2668 $ref: '#/components/schemas/VideoChannelList'
2670 summary: Create a video channel
2671 operationId: addVideoChannel
2678 description: successful operation
2688 $ref: '#/components/schemas/VideoChannel/properties/id'
2693 $ref: '#/components/schemas/VideoChannelCreate'
2695 '/video-channels/{channelHandle}':
2697 summary: Get a video channel
2698 operationId: getVideoChannel
2702 - $ref: '#/components/parameters/channelHandle'
2705 description: successful operation
2709 $ref: '#/components/schemas/VideoChannel'
2711 summary: Update a video channel
2712 operationId: putVideoChannel
2718 - $ref: '#/components/parameters/channelHandle'
2721 description: successful operation
2726 $ref: '#/components/schemas/VideoChannelUpdate'
2728 summary: Delete a video channel
2729 operationId: delVideoChannel
2735 - $ref: '#/components/parameters/channelHandle'
2738 description: successful operation
2740 '/video-channels/{channelHandle}/videos':
2742 summary: List videos of a video channel
2743 operationId: getVideoChannelVideos
2748 - $ref: '#/components/parameters/channelHandle'
2749 - $ref: '#/components/parameters/categoryOneOf'
2750 - $ref: '#/components/parameters/isLive'
2751 - $ref: '#/components/parameters/tagsOneOf'
2752 - $ref: '#/components/parameters/tagsAllOf'
2753 - $ref: '#/components/parameters/licenceOneOf'
2754 - $ref: '#/components/parameters/languageOneOf'
2755 - $ref: '#/components/parameters/nsfw'
2756 - $ref: '#/components/parameters/filter'
2757 - $ref: '#/components/parameters/skipCount'
2758 - $ref: '#/components/parameters/start'
2759 - $ref: '#/components/parameters/count'
2760 - $ref: '#/components/parameters/videosSort'
2763 description: successful operation
2767 $ref: '#/components/schemas/VideoListResponse'
2769 '/video-channels/{channelHandle}/avatar/pick':
2771 summary: Update channel avatar
2777 - $ref: '#/components/parameters/channelHandle'
2780 description: successful operation
2787 $ref: '#/components/schemas/ActorImage'
2789 description: image file too large
2791 X-File-Maximum-Size:
2795 description: Maximum file size for the avatar
2798 multipart/form-data:
2803 description: The file to upload.
2808 contentType: image/png, image/jpeg
2810 '/video-channels/{channelHandle}/avatar':
2812 summary: Delete channel avatar
2818 - $ref: '#/components/parameters/channelHandle'
2821 description: successful operation
2823 '/video-channels/{channelHandle}/banner/pick':
2825 summary: Update channel banner
2831 - $ref: '#/components/parameters/channelHandle'
2834 description: successful operation
2841 $ref: '#/components/schemas/ActorImage'
2843 description: image file too large
2845 X-File-Maximum-Size:
2849 description: Maximum file size for the banner
2852 multipart/form-data:
2857 description: The file to upload.
2862 contentType: image/png, image/jpeg
2864 '/video-channels/{channelHandle}/banner':
2866 summary: Delete channel banner
2872 - $ref: '#/components/parameters/channelHandle'
2875 description: successful operation
2877 /video-playlists/privacies:
2879 summary: List available playlist privacy policies
2880 operationId: getPlaylistPrivacyPolicies
2885 description: successful operation
2894 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2898 summary: List video playlists
2899 operationId: getPlaylists
2903 - $ref: '#/components/parameters/start'
2904 - $ref: '#/components/parameters/count'
2905 - $ref: '#/components/parameters/sort'
2908 description: successful operation
2920 $ref: '#/components/schemas/VideoPlaylist'
2922 summary: Create a video playlist
2923 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2924 operationId: addPlaylist
2931 description: successful operation
2941 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2943 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2946 multipart/form-data:
2951 description: Video playlist display name
2956 description: Video playlist thumbnail file
2960 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2962 description: Video playlist description
2968 - $ref: '#/components/schemas/id'
2969 description: Video channel in which the playlist will be published
2974 contentType: image/jpeg
2976 /video-playlists/{playlistId}:
2978 summary: Get a video playlist
2982 - $ref: '#/components/parameters/playlistId'
2985 description: successful operation
2989 $ref: '#/components/schemas/VideoPlaylist'
2991 summary: Update a video playlist
2992 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2999 description: successful operation
3001 - $ref: '#/components/parameters/playlistId'
3004 multipart/form-data:
3009 description: Video playlist display name
3014 description: Video playlist thumbnail file
3018 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3020 description: Video playlist description
3024 - $ref: '#/components/schemas/id'
3025 description: Video channel in which the playlist will be published
3028 contentType: image/jpeg
3030 summary: Delete a video playlist
3036 - $ref: '#/components/parameters/playlistId'
3039 description: successful operation
3041 /video-playlists/{playlistId}/videos:
3043 summary: 'List videos of a playlist'
3044 operationId: getVideoPlaylistVideos
3049 - $ref: '#/components/parameters/playlistId'
3052 description: successful operation
3056 $ref: '#/components/schemas/VideoListResponse'
3058 summary: Add a video in a playlist
3059 operationId: addVideoPlaylistVideo
3066 - $ref: '#/components/parameters/playlistId'
3069 description: successful operation
3075 videoPlaylistElement:
3089 - $ref: '#/components/schemas/Video/properties/uuid'
3090 - $ref: '#/components/schemas/Video/properties/id'
3091 description: Video to add in the playlist
3095 description: Start the video at this specific timestamp
3099 description: Stop the video at this specific timestamp
3103 /video-playlists/{playlistId}/videos/reorder:
3105 summary: 'Reorder a playlist'
3106 operationId: reorderVideoPlaylist
3112 - $ref: '#/components/parameters/playlistId'
3115 description: successful operation
3124 description: 'Start position of the element to reorder'
3126 insertAfterPosition:
3128 description: 'New position for the block to reorder, to add the block before the first element'
3132 description: 'How many element from `startPosition` to reorder'
3136 - insertAfterPosition
3138 /video-playlists/{playlistId}/videos/{playlistElementId}:
3140 summary: Update a playlist element
3141 operationId: putVideoPlaylistVideo
3147 - $ref: '#/components/parameters/playlistId'
3148 - $ref: '#/components/parameters/playlistElementId'
3151 description: successful operation
3161 description: Start the video at this specific timestamp
3165 description: Stop the video at this specific timestamp
3167 summary: Delete an element from a playlist
3168 operationId: delVideoPlaylistVideo
3174 - $ref: '#/components/parameters/playlistId'
3175 - $ref: '#/components/parameters/playlistElementId'
3178 description: successful operation
3180 '/users/me/video-playlists/videos-exist':
3182 summary: Check video exists in my playlists
3191 description: The video ids to check
3195 $ref: '#/components/schemas/Video/properties/id'
3198 description: successful operation
3220 '/accounts/{name}/video-channels':
3222 summary: List video channels of an account
3227 - $ref: '#/components/parameters/name'
3230 description: include view statistics for the last 30 days (only if authentified as the account user)
3233 - $ref: '#/components/parameters/start'
3234 - $ref: '#/components/parameters/count'
3235 - $ref: '#/components/parameters/sort'
3238 description: successful operation
3242 $ref: '#/components/schemas/VideoChannelList'
3244 '/accounts/{name}/ratings':
3246 summary: List ratings of an account
3252 - $ref: '#/components/parameters/name'
3253 - $ref: '#/components/parameters/start'
3254 - $ref: '#/components/parameters/count'
3255 - $ref: '#/components/parameters/sort'
3259 description: Optionally filter which ratings to retrieve
3267 description: successful operation
3273 $ref: '#/components/schemas/VideoRating'
3275 '/videos/{id}/comment-threads':
3277 summary: List threads of a video
3281 - $ref: '#/components/parameters/idOrUUID'
3282 - $ref: '#/components/parameters/start'
3283 - $ref: '#/components/parameters/count'
3284 - $ref: '#/components/parameters/commentsSort'
3287 description: successful operation
3291 $ref: '#/components/schemas/CommentThreadResponse'
3293 summary: Create a thread
3299 - $ref: '#/components/parameters/idOrUUID'
3302 description: successful operation
3306 $ref: '#/components/schemas/CommentThreadPostResponse'
3308 description: video does not exist
3317 - $ref: '#/components/schemas/VideoComment/properties/text'
3323 '/videos/{id}/comment-threads/{threadId}':
3325 summary: Get a thread
3329 - $ref: '#/components/parameters/idOrUUID'
3330 - $ref: '#/components/parameters/threadId'
3333 description: successful operation
3337 $ref: '#/components/schemas/VideoCommentThreadTree'
3339 '/videos/{id}/comments/{commentId}':
3341 summary: Reply to a thread of a video
3347 - $ref: '#/components/parameters/idOrUUID'
3348 - $ref: '#/components/parameters/commentId'
3351 description: successful operation
3355 $ref: '#/components/schemas/CommentThreadPostResponse'
3357 description: thread or video does not exist
3366 - $ref: '#/components/schemas/VideoComment/properties/text'
3372 summary: Delete a comment or a reply
3378 - $ref: '#/components/parameters/idOrUUID'
3379 - $ref: '#/components/parameters/commentId'
3382 description: successful operation
3384 description: cannot remove comment of another user
3386 description: comment or video does not exist
3388 description: comment is already deleted
3390 '/videos/{id}/rate':
3392 summary: Like/dislike a video
3398 - $ref: '#/components/parameters/idOrUUID'
3414 description: successful operation
3416 description: video does not exist
3422 summary: Search videos
3423 operationId: searchVideos
3428 allowEmptyValue: false
3430 String to search. If the user can make a remote URI search, and the string is an URI then the
3431 PeerTube instance will fetch the remote object and add it to its database. Then,
3432 you can use the REST API to fetch the complete video information and interact with it.
3435 - $ref: '#/components/parameters/categoryOneOf'
3436 - $ref: '#/components/parameters/isLive'
3437 - $ref: '#/components/parameters/tagsOneOf'
3438 - $ref: '#/components/parameters/tagsAllOf'
3439 - $ref: '#/components/parameters/licenceOneOf'
3440 - $ref: '#/components/parameters/languageOneOf'
3441 - $ref: '#/components/parameters/nsfw'
3442 - $ref: '#/components/parameters/filter'
3443 - $ref: '#/components/parameters/skipCount'
3444 - $ref: '#/components/parameters/start'
3445 - $ref: '#/components/parameters/count'
3446 - $ref: '#/components/parameters/searchTarget'
3447 - $ref: '#/components/parameters/videosSearchSort'
3450 description: Get videos that are published after this date
3456 description: Get videos that are published before this date
3460 - name: originallyPublishedStartDate
3462 description: Get videos that are originally published after this date
3466 - name: originallyPublishedEndDate
3468 description: Get videos that are originally published before this date
3474 description: Get videos that have this minimum duration
3479 description: Get videos that have this maximum duration
3483 'searchTarget === search-index':
3484 $ref: '#/components/callbacks/searchIndex'
3487 description: successful operation
3491 $ref: '#/components/schemas/VideoListResponse'
3493 description: search index unavailable
3495 /search/video-channels:
3499 summary: Search channels
3500 operationId: searchChannels
3506 String to search. If the user can make a remote URI search, and the string is an URI then the
3507 PeerTube instance will fetch the remote object and add it to its database. Then,
3508 you can use the REST API to fetch the complete channel information and interact with it.
3511 - $ref: '#/components/parameters/start'
3512 - $ref: '#/components/parameters/count'
3513 - $ref: '#/components/parameters/searchTarget'
3514 - $ref: '#/components/parameters/sort'
3516 'searchTarget === search-index':
3517 $ref: '#/components/callbacks/searchIndex'
3520 description: successful operation
3524 $ref: '#/components/schemas/VideoChannelList'
3526 description: search index unavailable
3528 /server/blocklist/accounts:
3532 summary: List account blocks
3537 - $ref: '#/components/parameters/start'
3538 - $ref: '#/components/parameters/count'
3539 - $ref: '#/components/parameters/sort'
3542 description: successful operation
3546 summary: Block an account
3558 example: chocobozzz@example.org
3559 description: account to block, in the form `username@domain`
3564 description: successful operation
3566 description: self-blocking forbidden
3568 '/server/blocklist/accounts/{accountName}':
3572 summary: Unblock an account by its handle
3580 description: account to unblock, in the form `username@domain`
3585 description: successful operation
3587 description: account or account block does not exist
3589 /server/blocklist/servers:
3593 summary: List server blocks
3598 - $ref: '#/components/parameters/start'
3599 - $ref: '#/components/parameters/count'
3600 - $ref: '#/components/parameters/sort'
3603 description: successful operation
3607 summary: Block a server
3620 description: server domain to block
3625 description: successful operation
3627 description: self-blocking forbidden
3629 '/server/blocklist/servers/{host}':
3633 summary: Unblock a server by its domain
3641 description: server domain to unblock
3647 description: successful operation
3649 description: account block does not exist
3651 /server/redundancy/{host}:
3654 - Instance Redundancy
3655 summary: Update a server redundancy policy
3663 description: server domain to mirror
3675 description: allow mirroring of the host's local videos
3680 description: successful operation
3682 description: server is not already known
3684 /server/redundancy/videos:
3688 summary: List videos being mirrored
3689 operationId: getMirroredVideos
3697 description: direction of the mirror
3703 - $ref: '#/components/parameters/start'
3704 - $ref: '#/components/parameters/count'
3705 - $ref: '#/components/parameters/videoRedundanciesSort'
3708 description: successful operation
3714 $ref: '#/components/schemas/VideoRedundancy'
3718 summary: Mirror a video
3719 operationId: putMirroredVideo
3730 $ref: '#/components/schemas/Video/properties/id'
3735 description: successful operation
3737 description: cannot mirror a local video
3739 description: video does not exist
3741 description: video is already mirrored
3743 /server/redundancy/videos/{redundancyId}:
3747 summary: Delete a mirror done on a video
3748 operationId: delMirroredVideo
3753 - name: redundancyId
3756 description: id of an existing redundancy on a video
3761 description: successful operation
3763 description: video redundancy not found
3765 '/feeds/video-comments.{format}':
3769 summary: List comments on videos
3770 operationId: getSyndicatedComments
3775 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3788 description: 'limit listing to a specific video'
3793 description: 'limit listing to a specific account'
3798 description: 'limit listing to a specific account'
3801 - name: videoChannelId
3803 description: 'limit listing to a specific video channel'
3806 - name: videoChannelName
3808 description: 'limit listing to a specific video channel'
3813 description: successful operation
3818 default: 'max-age=900' # 15 min cache
3822 $ref: '#/components/schemas/VideoCommentsForXML'
3825 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3826 application/rss+xml:
3828 $ref: '#/components/schemas/VideoCommentsForXML'
3831 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3834 $ref: '#/components/schemas/VideoCommentsForXML'
3837 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3838 application/atom+xml:
3840 $ref: '#/components/schemas/VideoCommentsForXML'
3843 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3849 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3851 x-summary: field inconsistencies
3854 - videoId filter is mixed with a channel filter
3856 description: video, video channel or account not found
3858 description: accept header unsupported
3860 '/feeds/videos.{format}':
3864 summary: List videos
3865 operationId: getSyndicatedVideos
3870 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3883 description: 'limit listing to a specific account'
3888 description: 'limit listing to a specific account'
3891 - name: videoChannelId
3893 description: 'limit listing to a specific video channel'
3896 - name: videoChannelName
3898 description: 'limit listing to a specific video channel'
3901 - $ref: '#/components/parameters/sort'
3902 - $ref: '#/components/parameters/nsfw'
3903 - $ref: '#/components/parameters/filter'
3906 description: successful operation
3911 default: 'max-age=900' # 15 min cache
3915 $ref: '#/components/schemas/VideosForXML'
3918 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3919 application/rss+xml:
3921 $ref: '#/components/schemas/VideosForXML'
3924 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3927 $ref: '#/components/schemas/VideosForXML'
3930 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3931 application/atom+xml:
3933 $ref: '#/components/schemas/VideosForXML'
3936 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3942 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3944 description: video channel or account not found
3946 description: accept header unsupported
3948 '/feeds/subscriptions.{format}':
3953 summary: List videos of subscriptions tied to a token
3954 operationId: getSyndicatedSubscriptionVideos
3959 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3972 description: limit listing to a specific account
3978 description: private token allowing access
3982 - $ref: '#/components/parameters/sort'
3983 - $ref: '#/components/parameters/nsfw'
3984 - $ref: '#/components/parameters/filter'
3987 description: successful operation
3992 default: 'max-age=900' # 15 min cache
3996 $ref: '#/components/schemas/VideosForXML'
3997 application/rss+xml:
3999 $ref: '#/components/schemas/VideosForXML'
4002 $ref: '#/components/schemas/VideosForXML'
4003 application/atom+xml:
4005 $ref: '#/components/schemas/VideosForXML'
4010 description: accept header unsupported
4016 summary: List plugins
4017 operationId: getPlugins
4030 - $ref: '#/components/parameters/start'
4031 - $ref: '#/components/parameters/count'
4032 - $ref: '#/components/parameters/sort'
4035 description: successful operation
4039 $ref: '#/components/schemas/PluginResponse'
4045 summary: List available plugins
4046 operationId: getAvailablePlugins
4059 - name: currentPeerTubeEngine
4063 - $ref: '#/components/parameters/start'
4064 - $ref: '#/components/parameters/count'
4065 - $ref: '#/components/parameters/sort'
4068 description: successful operation
4072 $ref: '#/components/schemas/PluginResponse'
4074 description: plugin index unavailable
4080 summary: Install a plugin
4081 operationId: addPlugin
4094 example: peertube-plugin-auth-ldap
4097 additionalProperties: false
4104 additionalProperties: false
4107 description: successful operation
4109 description: should have either `npmName` or `path` set
4115 summary: Update a plugin
4116 operationId: updatePlugin
4129 example: peertube-plugin-auth-ldap
4132 additionalProperties: false
4139 additionalProperties: false
4142 description: successful operation
4144 description: should have either `npmName` or `path` set
4146 description: existing plugin not found
4152 summary: Uninstall a plugin
4153 operationId: uninstallPlugin
4165 description: name of the plugin/theme in its package.json
4166 example: peertube-plugin-auth-ldap
4171 description: successful operation
4173 description: existing plugin not found
4179 summary: Get a plugin
4180 operationId: getPlugin
4185 - $ref: '#/components/parameters/npmName'
4188 description: successful operation
4192 $ref: '#/components/schemas/Plugin'
4194 description: plugin not found
4196 /plugins/{npmName}/settings:
4200 summary: Set a plugin's settings
4205 - $ref: '#/components/parameters/npmName'
4214 additionalProperties: true
4217 description: successful operation
4219 description: plugin not found
4221 /plugins/{npmName}/public-settings:
4225 summary: Get a plugin's public settings
4227 - $ref: '#/components/parameters/npmName'
4230 description: successful operation
4235 additionalProperties: true
4237 description: plugin not found
4239 /plugins/{npmName}/registered-settings:
4243 summary: Get a plugin's registered settings
4248 - $ref: '#/components/parameters/npmName'
4251 description: successful operation
4256 additionalProperties: true
4258 description: plugin not found
4261 - url: 'https://peertube2.cpy.re/api/v1'
4262 description: Live Test Server (live data - latest nightly version)
4263 - url: 'https://peertube3.cpy.re/api/v1'
4264 description: Live Test Server (live data - latest RC version)
4265 - url: 'https://peertube.cpy.re/api/v1'
4266 description: Live Test Server (live data - stable version)
4273 description: Offset used to paginate results
4281 description: "Number of items to return"
4291 description: Sort column
4299 description: Plain text search, applied to various parts of the model depending on endpoint
4307 If the administrator enabled search index support, you can override the default search target.
4310 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4311 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4312 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4313 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4314 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4315 * 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
4316 the data from the origin instance API
4326 description: Sort videos by criteria
4342 description: Sort videos by criteria
4357 description: Sort comments by criteria
4367 description: Sort blacklists by criteria
4383 description: Plain text search that will match with user usernames or emails
4390 description: Filter results down to (un)banned users
4397 description: Sort users by criteria
4408 description: Sort abuses by criteria
4415 videoRedundanciesSort:
4419 description: Sort abuses by criteria
4428 description: The username or handle of the account
4431 example: chocobozzz | chocobozzz@example.org
4436 description: The user id
4438 $ref: '#/components/schemas/id'
4443 description: The object id or uuid
4446 - $ref: '#/components/schemas/id'
4447 - $ref: '#/components/schemas/UUIDv4'
4452 description: Playlist id
4454 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4456 name: playlistElementId
4459 description: Playlist element id
4461 $ref: '#/components/schemas/id'
4466 description: Abuse id
4468 $ref: '#/components/schemas/Abuse/properties/id'
4470 name: abuseMessageId
4473 description: Abuse message id
4475 $ref: '#/components/schemas/AbuseMessage/properties/id'
4477 name: captionLanguage
4480 description: The caption language
4482 $ref: '#/components/schemas/VideoLanguageSet'
4487 description: The video channel handle
4490 example: my_username | my_username@example.com
4492 name: subscriptionHandle
4495 description: The subscription handle
4498 example: my_username | my_username@example.com
4503 description: The thread id (root comment id)
4510 description: The comment id
4512 $ref: '#/components/schemas/VideoComment/properties/id'
4517 description: whether or not the video is a live
4524 description: category id of the video (see [/videos/categories](#operation/getCategories))
4527 - $ref: '#/components/schemas/VideoCategorySet'
4530 $ref: '#/components/schemas/VideoCategorySet'
4537 description: tag(s) of the video
4551 description: tag(s) of the video, where all should be present in the video
4564 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4567 - $ref: '#/components/schemas/VideoLanguageSet'
4570 $ref: '#/components/schemas/VideoLanguageSet'
4577 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4580 - $ref: '#/components/schemas/VideoLicenceSet'
4583 $ref: '#/components/schemas/VideoLicenceSet'
4590 description: if you don't need the `total` in the response
4601 description: whether to include nsfw videos, if any
4612 Special filters which might require special rights:
4613 * `local` - only videos local to the instance
4614 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4615 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4625 description: list of uris to check if each is part of the user subscriptions
4635 description: name of the plugin/theme on npmjs.com or in its package.json
4638 example: peertube-plugin-auth-ldap
4643 description: job type
4647 - activitypub-follow
4648 - activitypub-http-broadcast
4649 - activitypub-http-fetcher
4650 - activitypub-http-unicast
4656 - activitypub-refresher
4681 Authenticating via OAuth requires the following steps:
4682 - Have an activated account
4683 - [Generate] an access token for that account at `/api/v1/users/token`.
4684 - Make requests with the *Authorization: Bearer <token\>* header
4685 - Profit, depending on the role assigned to the account
4687 Note that the __access token is valid for 1 day__ and is given
4688 along with a __refresh token valid for 2 weeks__.
4690 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4694 tokenUrl: /api/v1/users/token
4697 moderator: Moderator scope
4700 # Resuable core properties
4708 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4709 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4714 description: immutable name of the user, used to find or mention its actor
4716 pattern: '/^[a-z0-9._]+$/'
4721 description: immutable name of the channel, used to interact with its actor
4722 example: framasoft_videos
4723 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4734 description: category id of the video (see [/videos/categories](#operation/getCategories))
4736 VideoConstantNumber-Category:
4739 $ref: '#/components/schemas/VideoCategorySet'
4742 example: Science & Technology
4746 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4748 VideoConstantNumber-Licence:
4751 $ref: '#/components/schemas/VideoLicenceSet'
4754 example: Attribution - Share Alike
4758 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4760 VideoConstantString-Language:
4763 $ref: '#/components/schemas/VideoLanguageSet'
4768 VideoPlaylistPrivacySet:
4774 description: Video playlist privacy policy (see [/video-playlists/privacies])
4775 VideoPlaylistPrivacyConstant:
4778 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4782 VideoPlaylistTypeSet:
4787 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4788 VideoPlaylistTypeConstant:
4791 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4802 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4803 VideoPrivacyConstant:
4806 $ref: '#/components/schemas/VideoPrivacySet'
4823 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4830 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4841 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4851 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4855 $ref: '#/components/schemas/AbuseStateSet'
4858 AbusePredefinedReasons:
4871 example: [spamOrMisleading]
4876 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4878 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4880 VideoResolutionConstant:
4881 description: resolutions and their labels for the video
4884 $ref: '#/components/schemas/VideoResolutionSet'
4888 VideoScheduledUpdate:
4891 $ref: '#/components/schemas/VideoPrivacySet'
4895 description: When to update the video
4915 - $ref: '#/components/schemas/ActorImage'
4916 VideoChannelSummary:
4919 $ref: '#/components/schemas/id'
4933 - $ref: '#/components/schemas/ActorImage'
4947 - $ref: '#/components/schemas/Video'
4954 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4955 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
4956 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4958 $ref: '#/components/schemas/VideoResolutionConstant'
4961 description: Video file size in bytes
4964 description: Direct URL of the torrent file
4968 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4972 description: Direct URL of the video
4976 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4980 description: Frames per second of the video file
4984 description: URL dereferencing the output of ffprobe on the file
4985 VideoStreamingPlaylists:
4990 $ref: '#/components/schemas/id'
4998 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4999 VideoStreamingPlaylists-HLS:
5010 Video files associated to this playlist.
5012 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5014 $ref: '#/components/schemas/VideoFile'
5026 $ref: '#/components/schemas/Video/properties/id'
5028 $ref: '#/components/schemas/Video/properties/uuid'
5030 $ref: '#/components/schemas/Video/properties/name'
5034 description: object id for the video
5036 - $ref: '#/components/schemas/id'
5038 description: universal identifier for the video, that can be used across instances
5040 - $ref: '#/components/schemas/UUIDv4'
5046 example: 2017-10-01T10:52:46.396Z
5047 description: time at which the video object was first drafted
5051 example: 2018-10-01T10:52:46.396Z
5052 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5056 example: 2021-05-04T08:01:01.502Z
5057 description: last time the video's metadata was modified
5058 originallyPublishedAt:
5061 example: 2010-10-01T10:52:46.396Z
5062 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5065 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5066 description: category in which the video is classified
5069 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5070 description: licence under which the video is distributed
5073 - $ref: '#/components/schemas/VideoConstantString-Language'
5074 description: main language used in the video
5077 - $ref: '#/components/schemas/VideoPrivacyConstant'
5078 description: privacy policy used to distribute the video
5082 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5083 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5087 truncated description of the video, written in Markdown.
5088 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5093 description: duration of the video in seconds
5098 description: title of the video
5099 example: What is PeerTube?
5104 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5107 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5110 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5127 - $ref: '#/components/schemas/VideoStateConstant'
5128 description: represents the internal state of the video processing within the PeerTube instance
5132 - $ref: '#/components/schemas/VideoScheduledUpdate'
5140 $ref: '#/components/schemas/AccountSummary'
5142 $ref: '#/components/schemas/VideoChannelSummary'
5151 - $ref: '#/components/schemas/Video'
5156 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5157 description: path at which to get the full description of maximum `10000` characters
5160 description: A text tell the audience how to support the video creator
5161 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5165 $ref: '#/components/schemas/VideoChannel'
5167 $ref: '#/components/schemas/Account'
5169 example: [flowers, gardening]
5187 - https://peertube2.cpy.re/tracker/announce
5188 - wss://peertube2.cpy.re/tracker/socket
5192 $ref: '#/components/schemas/VideoFile'
5194 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5196 - field will be empty
5197 - video files will be found in `streamingPlaylists[].files` field
5201 $ref: '#/components/schemas/VideoStreamingPlaylists'
5203 HLS playlists/manifest files. If HLS is disabled on the server:
5205 - field will be empty
5206 - video files will be found in `files` field
5207 FileRedundancyInformation:
5210 $ref: '#/components/schemas/id'
5235 $ref: '#/components/schemas/id'
5242 $ref: '#/components/schemas/UUIDv4'
5249 $ref: '#/components/schemas/FileRedundancyInformation'
5253 $ref: '#/components/schemas/FileRedundancyInformation'
5254 VideoImportStateConstant:
5262 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5269 additionalProperties: false
5273 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5274 required: [targetUrl]
5277 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5278 required: [magnetUri]
5281 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5282 required: [torrentfile]
5283 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5292 - $ref: '#/components/schemas/id'
5296 description: remote URL where to find the import's source video
5297 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5301 description: magnet URI allowing to resolve the import's source video
5302 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
5303 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5308 description: Torrent file containing only the video file
5315 - $ref: '#/components/schemas/VideoImportStateConstant'
5331 - $ref: '#/components/schemas/Video'
5341 $ref: '#/components/schemas/VideoImport'
5345 $ref: '#/components/schemas/id'
5348 example: The video is a spam
5352 $ref: '#/components/schemas/AbusePredefinedReasons'
5354 $ref: '#/components/schemas/Account'
5356 $ref: '#/components/schemas/AbuseStateConstant'
5359 example: Decided to ban the server since it spams us regularly
5363 $ref: '#/components/schemas/VideoInfo'
5370 $ref: '#/components/schemas/id'
5381 $ref: '#/components/schemas/AccountSummary'
5385 $ref: '#/components/schemas/id'
5387 $ref: '#/components/schemas/Video/properties/id'
5399 $ref: '#/components/schemas/UUIDv4'
5417 $ref: '#/components/schemas/id'
5419 $ref: '#/components/schemas/UUIDv4'
5442 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5444 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5446 $ref: '#/components/schemas/AccountSummary'
5448 $ref: '#/components/schemas/VideoChannelSummary'
5452 $ref: '#/components/schemas/id'
5459 description: Text of the comment
5461 example: This video is wonderful!
5463 $ref: '#/components/schemas/id'
5467 - $ref: '#/components/schemas/id'
5469 $ref: '#/components/schemas/Video/properties/id'
5484 totalRepliesFromVideoAuthor:
5491 $ref: '#/components/schemas/Account'
5492 VideoCommentThreadTree:
5495 $ref: '#/components/schemas/VideoComment'
5499 $ref: '#/components/schemas/VideoCommentThreadTree'
5503 $ref: '#/components/schemas/VideoConstantString-Language'
5519 $ref: '#/components/schemas/id'
5536 $ref: '#/components/schemas/id'
5541 description: immutable name of the actor, used to find or mention it
5543 - $ref: '#/components/schemas/username'
5547 description: server on which the actor is resident
5548 hostRedundancyAllowed:
5550 description: whether this actor's host allows redundancy of its videos
5554 description: number of actors subscribed to by this actor, as seen by this instance
5558 description: number of followers of this actor, as seen by this instance
5566 $ref: '#/components/schemas/ActorImage'
5569 - $ref: '#/components/schemas/Actor'
5572 description: object id for the user tied to this account
5574 - $ref: '#/components/schemas/User/properties/id'
5577 description: editable name of the account, displayed in its representations
5582 description: text or bio displayed on the account's profile
5588 description: timestamp within the video, in seconds
5655 allowedForCurrentIP:
5657 requiresEmailVerification:
5675 $ref: '#/components/schemas/VideoResolutionSet'
5760 example: 16810141515
5869 requiresEmailVerification:
5884 description: Settings that apply to new users, if registration is enabled
5888 example: 16810141515
5894 description: Settings pertaining to transcoding jobs
5898 allowAdditionalExtensions:
5900 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5903 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5906 description: Amount of threads used by ffmpeg for 1 transcoding job
5909 description: Amount of transcoding jobs to execute in parallel
5915 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5918 description: Resolutions to transcode _new videos_ to
5938 description: WebTorrent-specific settings
5944 description: HLS-specific settings
5994 $ref: '#/components/schemas/id'
5996 $ref: '#/components/schemas/Actor'
5998 $ref: '#/components/schemas/Actor'
6001 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6014 PredefinedAbuseReasons:
6015 description: Reason categories that help triage reports
6033 $ref: '#/components/schemas/id'
6045 - activitypub-http-unicast
6046 - activitypub-http-broadcast
6047 - activitypub-http-fetcher
6048 - activitypub-follow
6054 - activitypub-refresher
6058 additionalProperties: true
6061 additionalProperties: true
6077 $ref: '#/components/schemas/id'
6082 $ref: '#/components/schemas/id'
6083 VideoUploadRequestCommon:
6086 description: Video name
6088 example: What is PeerTube?
6092 description: Channel id that will contain this video
6097 $ref: '#/components/schemas/VideoPrivacySet'
6099 $ref: '#/components/schemas/VideoCategorySet'
6101 $ref: '#/components/schemas/VideoLicenceSet'
6103 $ref: '#/components/schemas/VideoLanguageSet'
6105 description: Video description
6108 **[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)**
6110 description: Whether or not we wait transcoding before publish the video
6113 description: A text tell the audience how to support the video creator
6114 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6117 description: Whether or not this video contains sensitive content
6120 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6133 description: Enable or disable comments for this video
6136 description: Enable or disable downloading for this video
6138 originallyPublishedAt:
6139 description: Date when the content was originally published
6143 $ref: '#/components/schemas/VideoScheduledUpdate'
6145 description: Video thumbnail file
6149 description: Video preview file
6155 VideoUploadRequestLegacy:
6157 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6163 description: Video file
6166 VideoUploadRequestResumable:
6168 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6174 description: Video filename including extension
6177 example: what_is_peertube.mp4
6179 description: Video thumbnail file
6183 description: Video preview file
6186 VideoUploadResponse:
6192 $ref: '#/components/schemas/Video/properties/id'
6194 $ref: '#/components/schemas/Video/properties/uuid'
6195 CommentThreadResponse:
6204 $ref: '#/components/schemas/VideoComment'
6205 CommentThreadPostResponse:
6208 $ref: '#/components/schemas/VideoComment'
6218 $ref: '#/components/schemas/Video'
6222 $ref: '#/components/schemas/Account'
6225 description: Automatically start playing the upcoming video after the currently playing video
6226 autoPlayNextVideoPlaylist:
6228 description: Automatically start playing the video on the playlist after the currently playing video
6231 description: Automatically start playing the video on the watch page
6241 description: The user email
6244 description: Has the user confirmed their email address?
6247 - $ref: '#/components/schemas/id'
6251 description: Auth plugin to use to authenticate the user
6255 noInstanceConfigWarningModal:
6260 $ref: '#/components/schemas/NSFWPolicy'
6262 $ref: '#/components/schemas/UserRole'
6271 description: Theme enabled by this user
6273 $ref: '#/components/schemas/username'
6277 $ref: '#/components/schemas/VideoChannel'
6280 description: The user video quota in bytes
6284 description: The user daily video quota in bytes
6288 description: Enable P2P in the player
6291 - $ref: '#/components/schemas/User'
6293 # optionally present fields: they require WITH_STATS scope
6296 description: Count of videos published
6299 description: Count of reports/abuses of which the user is a target
6300 abusesAcceptedCount:
6302 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6305 description: Count of reports/abuses created by the user
6308 description: Count of comments published
6312 $ref: '#/components/schemas/username'
6314 $ref: '#/components/schemas/password'
6318 description: The user email
6321 description: The user video quota in bytes
6325 description: The user daily video quota in bytes
6328 $ref: '#/components/schemas/usernameChannel'
6330 $ref: '#/components/schemas/UserRole'
6332 $ref: '#/components/schemas/UserAdminFlags'
6343 description: The updated email of the user
6345 - $ref: '#/components/schemas/User/properties/email'
6348 description: Set the email as verified
6351 description: The updated video quota of the user in bytes
6354 description: The updated daily video quota of the user in bytes
6358 description: The auth plugin to use to authenticate the user
6359 example: 'peertube-plugin-auth-saml2'
6361 $ref: '#/components/schemas/UserRole'
6363 $ref: '#/components/schemas/UserAdminFlags'
6365 # see shared/models/users/user-update-me.model.ts:
6368 $ref: '#/components/schemas/password'
6370 $ref: '#/components/schemas/password'
6372 description: new email used for login and service communications
6374 - $ref: '#/components/schemas/User/properties/email'
6377 description: new name of the user in its representations
6382 description: new NSFW display policy
6389 description: whether to enable P2P in the player or not
6392 description: new preference regarding playing videos automatically
6395 description: new preference regarding playing following videos automatically
6396 autoPlayNextVideoPlaylist:
6398 description: new preference regarding playing following playlist videos automatically
6399 videosHistoryEnabled:
6401 description: whether to keep track of watched history or not
6406 description: list of languages to filter videos down to
6409 noInstanceConfigWarningModal:
6416 $ref: '#/components/schemas/id'
6423 description: Rating of the video
6430 $ref: '#/components/schemas/Video'
6437 description: Rating of the video
6444 description: immutable name of the user, used to find or mention its actor
6446 - $ref: '#/components/schemas/username'
6448 $ref: '#/components/schemas/password'
6452 description: email of the user, used for login or service communications
6455 description: editable name of the user, displayed in its representations
6460 description: channel base information used to create the first channel of the user
6463 $ref: '#/components/schemas/usernameChannel'
6465 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6475 pattern: /^[a-z0-9]$/
6478 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6481 pattern: /^[a-zA-Z0-9]$/
6484 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6485 OAuthToken-password:
6487 - $ref: '#/components/schemas/OAuthClient'
6497 $ref: '#/components/schemas/User/properties/username'
6499 $ref: '#/components/schemas/password'
6506 OAuthToken-refresh_token:
6508 - $ref: '#/components/schemas/OAuthClient'
6519 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6528 # GET/POST/PUT properties
6531 description: editable name of the channel, displayed in its representations
6532 example: Videos of Framasoft
6537 example: Videos made with <3 by Framasoft
6542 description: text shown by default on all videos of this channel, to tell the audience how to support it
6543 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6546 # GET-only properties
6550 - $ref: '#/components/schemas/id'
6566 $ref: '#/components/schemas/UUIDv4'
6569 - $ref: '#/components/schemas/VideoChannel'
6572 description: username of the channel to create
6574 - $ref: '#/components/schemas/usernameChannel'
6580 - $ref: '#/components/schemas/VideoChannel'
6582 bulkVideosSupportUpdate:
6584 description: Update the support field for all videos of this channel
6594 - $ref: '#/components/schemas/VideoChannel'
6595 - $ref: '#/components/schemas/Actor'
6600 name: 'media:peerLink'
6609 - application/x-bittorrent
6615 name: 'media:content'
6646 VideoCommentsForXML:
6681 description: video watch page URL
6684 description: video canonical URL
6688 description: video publication date
6691 description: video description
6694 description: video description
6697 description: publisher user name
6700 description: video category (MRSS)
6703 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6718 description: video embed path, relative to the canonical URL domain (MRSS)
6727 description: video watch path, relative to the canonical URL domain (MRSS)
6748 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6749 'media:description':
6756 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6759 description: main streamable file for the video
6769 - application/x-bittorrent
6778 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)
6781 - $ref: '#/components/schemas/MRSSPeerLink'
6782 - $ref: '#/components/schemas/MRSSGroupContent'
6783 NotificationSettingValue:
6800 $ref: '#/components/schemas/id'
6804 Notification type, following the `UserNotificationType` enum:
6806 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6808 - `2` NEW_COMMENT_ON_MY_VIDEO
6810 - `3` NEW_ABUSE_FOR_MODERATORS
6812 - `4` BLACKLIST_ON_MY_VIDEO
6814 - `5` UNBLACKLIST_ON_MY_VIDEO
6816 - `6` MY_VIDEO_PUBLISHED
6818 - `7` MY_VIDEO_IMPORT_SUCCESS
6820 - `8` MY_VIDEO_IMPORT_ERROR
6822 - `9` NEW_USER_REGISTRATION
6826 - `11` COMMENT_MENTION
6828 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6830 - `13` NEW_INSTANCE_FOLLOWER
6832 - `14` AUTO_INSTANCE_FOLLOWING
6838 - $ref: '#/components/schemas/VideoInfo'
6842 $ref: '#/components/schemas/ActorInfo'
6848 $ref: '#/components/schemas/id'
6851 $ref: '#/components/schemas/VideoInfo'
6856 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6866 $ref: '#/components/schemas/id'
6870 $ref: '#/components/schemas/VideoInfo'
6872 $ref: '#/components/schemas/ActorInfo'
6878 $ref: '#/components/schemas/id'
6881 - $ref: '#/components/schemas/VideoInfo'
6887 $ref: '#/components/schemas/id'
6890 - $ref: '#/components/schemas/VideoInfo'
6894 - $ref: '#/components/schemas/ActorInfo'
6900 $ref: '#/components/schemas/id'
6902 $ref: '#/components/schemas/ActorInfo'
6930 NotificationListResponse:
6939 $ref: '#/components/schemas/Notification'
6944 example: peertube-plugin-auth-ldap
6972 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6975 additionalProperties: true
6991 $ref: '#/components/schemas/Plugin'
6998 description: User can stream multiple times in a permanent live
7007 description: RTMP stream key to use to stream into this live video
7011 description: User can stream multiple times in a permanent live
7018 'https://search.example.org/api/v1/search/videos':
7020 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7023 description: successful operation
7027 $ref: '#/components/schemas/VideoListResponse'