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
44 HTTP 1.1 404 Not Found
45 Content-Type: application/json
49 "error": "Account not found"
53 We provide error codes for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
54 but it is still optional.
58 Each parameter is evaluated on its own against a set of rules before the route validator
59 proceeds with potential testing involving parameter combinations. Errors coming from Validation
60 errors appear earlier and benefit from a more detailed error type:
63 HTTP 1.1 400 Bad Request
64 Content-Type: application/json
69 "value": "a117eb-c6a9-4756-bb09-2a956239f",
70 "msg": "Should have a valid id",
78 Where `id` is the name of the field concerned by the error, within the route definition.
79 `errors.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
80 `errors.<field>.value` reports the value that didn't pass validation whose `errors.<field>.msg`
85 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
87 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
88 |------------------------------|---------------|--------------|
89 | `/*` | 50 | 10 seconds |
90 | `POST /users/token` | 15 | 5 minutes |
91 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
92 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
94 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
95 limit is announced by a `429 Too Many Requests` status code.
97 You can get details about the current state of your rate limit by reading the
100 | Header | Description |
101 |-------------------------|------------------------------------------------------------|
102 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
103 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
104 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
105 | `Retry-After` | Seconds to delay after the first `429` is received |
109 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
110 allowing cross-domain communication from the browser for some routes:
113 |------------------------- ---|
117 | `/live/segments-sha256/*` |
118 | `/.well-known/webfinger` |
120 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
122 url: https://docs.joinpeertube.org/api-rest-reference.html
126 As a visitor, you can use this API to open an account (if registrations are open on
127 that PeerTube instance). As an admin, you should use the dedicated [User creation
128 API](#operation/addUser) instead.
130 x-displayName: Login/Logout
132 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
135 Accounts encompass remote accounts discovered across the federation,
136 and correspond to the main Actor, along with video channels a user can create, which
139 When a comment is posted, it is done with your Account's Actor.
142 Using some features of PeerTube require authentication, for which User
143 provide different levels of permission as well as associated user
144 information. Each user has a corresponding local Account for federation.
147 Operations related to your own User, when logged-in.
148 - name: My Subscriptions
150 Operations related to your subscriptions to video channels, their
151 new videos, and how to keep up to date with their latest publications!
154 Operations related to your watch history.
155 - name: My Notifications
157 Notifications following new videos, follows or reports. They allow you
158 to keep track of the interactions and overall important information that
159 concerns you. You MAY set per-notification type delivery preference, to
160 receive the info either by mail, by in-browser notification or both.
163 Each server exposes public information regarding supported videos and
167 Jobs are long-running tasks enqueued and processed by the instance
168 itself. No additional worker registration is currently available.
169 - name: Instance Follows
171 Managing servers which the instance interacts with is crucial to the
172 concept of federation in PeerTube and external video indexation. The PeerTube
173 server then deals with inter-server ActivityPub operations and propagates
174 information across its social graph by posting activities to actors' inbox
177 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
178 - name: Instance Redundancy
180 Redundancy is part of the inter-server solidarity that PeerTube fosters.
181 Manage the list of instances you wish to help by seeding their videos according
182 to the policy of video selection of your choice. Note that you have a similar functionality
183 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
185 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
188 Managing plugins installed from a local path or from NPM, or search for new ones.
190 url: https://docs.joinpeertube.org/api-plugins
193 Abuses deal with reports of local or remote videos/comments/accounts alike.
196 Operations dealing with listing, uploading, fetching or modifying videos.
199 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
203 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
204 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
206 You can upload videos more reliably by using the resumable variant. Its protocol lets
207 you resume an upload operation after a network interruption or other transmission failure,
208 saving time and bandwidth in the event of network failures.
210 Favor using resumable uploads in any of the following cases:
211 - You are transferring large files
212 - The likelihood of a network interruption is high
213 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
214 such as a mobile device
218 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
219 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
220 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
222 The import function is practical when the desired video/audio is available online. It makes PeerTube
223 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
224 - name: Video Captions
225 description: Operations dealing with listing, adding and removing closed captions of a video.
226 - name: Video Channels
227 description: Operations dealing with the creation, modification and listing of videos within a channel.
228 - name: Video Comments
230 Operations dealing with comments to a video. Comments are organized in threads: adding a
231 comment in response to the video starts a thread, adding a reply to a comment adds it to
232 its root comment thread.
234 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
236 description: Like/dislike a video.
237 - name: Video Playlists
238 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
240 description: Server syndication feeds
243 The search helps to find _videos_ or _channels_ from within the instance and beyond.
244 Videos from other instances federated by the instance (that is, instances
245 followed by the instance) can be found via keywords and other criteria of
248 Administrators can also enable the use of a remote search system, indexing
249 videos and channels not could be not federated by the instance.
250 - name: Video Mirroring
252 PeerTube instances can mirror videos from one another, and help distribute some videos.
254 For importing videos as your own, refer to [video imports](#operation/importVideo).
277 - Video Ownership Change
290 - name: Instance Configuration
294 - Instance Redundancy
304 summary: Get an account
305 operationId: getAccount
307 - $ref: '#/components/parameters/name'
310 description: successful operation
314 $ref: '#/components/schemas/Account'
316 description: account not found
318 '/accounts/{name}/videos':
323 summary: 'List videos of an account'
324 operationId: getAccountVideos
326 - $ref: '#/components/parameters/name'
327 - $ref: '#/components/parameters/categoryOneOf'
328 - $ref: '#/components/parameters/isLive'
329 - $ref: '#/components/parameters/tagsOneOf'
330 - $ref: '#/components/parameters/tagsAllOf'
331 - $ref: '#/components/parameters/licenceOneOf'
332 - $ref: '#/components/parameters/languageOneOf'
333 - $ref: '#/components/parameters/nsfw'
334 - $ref: '#/components/parameters/filter'
335 - $ref: '#/components/parameters/skipCount'
336 - $ref: '#/components/parameters/start'
337 - $ref: '#/components/parameters/count'
338 - $ref: '#/components/parameters/videosSort'
341 description: successful operation
345 $ref: '#/components/schemas/VideoListResponse'
349 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
350 .then(function(response) {
351 return response.json()
352 }).then(function(data) {
358 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
364 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
366 http = Net::HTTP.new(uri.host, uri.port)
369 response = http.get(uri.request_uri)
371 puts JSON.parse(response.read_body)
376 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
385 summary: List accounts
386 operationId: getAccounts
388 - $ref: '#/components/parameters/start'
389 - $ref: '#/components/parameters/count'
390 - $ref: '#/components/parameters/sort'
393 description: successful operation
399 $ref: '#/components/schemas/Account'
405 summary: Get instance public configuration
406 operationId: getConfig
409 description: successful operation
413 $ref: '#/components/schemas/ServerConfig'
416 externalValue: https://peertube2.cpy.re/api/v1/config
420 summary: Get instance "About" information
421 operationId: getAbout
426 description: successful operation
430 $ref: '#/components/schemas/ServerConfigAbout'
433 externalValue: https://peertube2.cpy.re/api/v1/config/about
437 summary: Get instance runtime configuration
438 operationId: getCustomConfig
446 description: successful operation
450 $ref: '#/components/schemas/ServerConfigCustom'
452 summary: Set instance runtime configuration
453 operationId: putCustomConfig
461 description: successful operation
463 x-summary: field inconsistencies
466 - the emailer is disabled and the instance is open to registrations
467 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
469 summary: Delete instance runtime configuration
470 operationId: delCustomConfig
478 description: successful operation
482 summary: List instance jobs
493 description: The state of the job ('' for for no filter)
503 - $ref: '#/components/parameters/jobType'
504 - $ref: '#/components/parameters/start'
505 - $ref: '#/components/parameters/count'
506 - $ref: '#/components/parameters/sort'
509 description: successful operation
522 $ref: '#/components/schemas/Job'
528 summary: List instances following the server
530 - $ref: '#/components/parameters/followState'
531 - $ref: '#/components/parameters/actorType'
532 - $ref: '#/components/parameters/start'
533 - $ref: '#/components/parameters/count'
534 - $ref: '#/components/parameters/sort'
537 description: successful operation
549 $ref: '#/components/schemas/Follow'
551 '/server/followers/{nameWithHost}':
553 summary: Remove or reject a follower to your server
563 description: The remote actor handle to remove from your followers
569 description: successful operation
571 description: follower not found
573 '/server/followers/{nameWithHost}/reject':
575 summary: Reject a pending follower to your server
585 description: The remote actor handle to remove from your followers
591 description: successful operation
593 description: follower not found
595 '/server/followers/{nameWithHost}/accept':
597 summary: Accept a pending follower to your server
607 description: The remote actor handle to remove from your followers
613 description: successful operation
615 description: follower not found
621 summary: List instances followed by the server
623 - $ref: '#/components/parameters/followState'
624 - $ref: '#/components/parameters/actorType'
625 - $ref: '#/components/parameters/start'
626 - $ref: '#/components/parameters/count'
627 - $ref: '#/components/parameters/sort'
630 description: successful operation
642 $ref: '#/components/schemas/Follow'
649 summary: Follow a list of servers
652 description: successful operation
654 description: cannot follow a non-HTTPS server
668 '/server/following/{host}':
670 summary: Unfollow a server
680 description: The host to unfollow
686 description: successful operation
688 description: host not found
692 summary: Create a user
701 description: user created
705 $ref: '#/components/schemas/AddUserResponse'
711 id: '$response.body#/user/id'
716 id: '$response.body#/user/id'
721 id: '$response.body#/user/id'
723 description: insufficient authority to create an admin or moderator
728 $ref: '#/components/schemas/AddUser'
730 If the smtp server is configured, you can leave the password empty and an email will be sent
731 asking the user to set it first.
735 operationId: getUsers
742 - $ref: '#/components/parameters/usersSearch'
743 - $ref: '#/components/parameters/usersBlocked'
744 - $ref: '#/components/parameters/start'
745 - $ref: '#/components/parameters/count'
746 - $ref: '#/components/parameters/usersSort'
749 description: successful operation
755 $ref: '#/components/schemas/User'
759 - $ref: '#/components/parameters/id'
761 summary: Delete a user
770 description: successful operation
781 description: include statistics about the user (only available as a moderator/admin)
786 x-summary: successful operation
788 As an admin/moderator, you can request a response augmented with statistics about the user's
789 moderation relations and videos usage, by using the `withStats` parameter.
794 - $ref: '#/components/schemas/User'
795 - $ref: '#/components/schemas/UserWithStats'
797 summary: Update a user
805 description: successful operation
810 $ref: '#/components/schemas/UpdateUser'
813 /oauth-clients/local:
815 summary: Login prerequisite
816 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
817 operationId: getOAuthClient
822 description: successful operation
826 $ref: '#/components/schemas/OAuthClient'
828 UseOAuthClientToLogin:
829 operationId: getOAuthToken
831 client_id: '$response.body#/client_id'
832 client_secret: '$response.body#/client_secret'
836 API="https://peertube2.cpy.re/api/v1"
839 curl -s "$API/oauth-clients/local"
844 operationId: getOAuthToken
845 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
850 application/x-www-form-urlencoded:
853 - $ref: '#/components/schemas/OAuthToken-password'
854 - $ref: '#/components/schemas/OAuthToken-refresh_token'
856 propertyName: grant_type
858 password: '#/components/schemas/OAuthToken-password'
859 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
862 description: successful operation
873 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
874 description: valid for 1 day
877 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
878 description: valid for 2 weeks
883 refresh_token_expires_in:
891 API="https://peertube2.cpy.re/api/v1"
892 USERNAME="<your_username>"
893 PASSWORD="<your_password>"
896 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
897 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
898 curl -s "$API/users/token" \
899 --data client_id="$client_id" \
900 --data client_secret="$client_secret" \
901 --data grant_type=password \
902 --data username="$USERNAME" \
903 --data password="$PASSWORD" \
904 | jq -r ".access_token"
909 description: Revokes your access token and its associated refresh token, destroying your current session.
910 operationId: revokeOAuthToken
917 description: successful operation
921 summary: Register a user
922 operationId: registerUser
928 description: successful operation
933 $ref: '#/components/schemas/RegisterUser'
936 /users/{id}/verify-email:
938 summary: Verify a user
939 operationId: verifyUser
941 Following a user registration, the new user will receive an email asking to click a link
947 - $ref: '#/components/parameters/id'
963 description: successful operation
965 description: invalid verification string
967 description: user not found
969 /users/ask-send-verify-email:
971 summary: Resend user verification link
972 operationId: resendEmailToVerifyUser
978 description: successful operation
982 summary: Get my user information
983 operationId: getUserInfo
991 description: successful operation
997 $ref: '#/components/schemas/User'
999 summary: Update my user information
1000 operationId: putUserInfo
1008 description: successful operation
1013 $ref: '#/components/schemas/UpdateMe'
1016 /users/me/videos/imports:
1018 summary: Get video imports of my user
1026 - $ref: '#/components/parameters/start'
1027 - $ref: '#/components/parameters/count'
1028 - $ref: '#/components/parameters/sort'
1031 description: successful operation
1035 $ref: '#/components/schemas/VideoImportsList'
1037 /users/me/video-quota-used:
1039 summary: Get my user used quota
1047 description: successful operation
1055 description: The user video quota used so far in bytes
1056 example: 16810141515
1057 videoQuotaUsedDaily:
1059 description: The user video quota used today in bytes
1062 '/users/me/videos/{videoId}/rating':
1064 summary: Get rate of my user for a video
1074 description: The video id
1076 $ref: '#/components/schemas/Video/properties/id'
1079 description: successful operation
1083 $ref: '#/components/schemas/GetMeVideoRating'
1087 summary: Get videos of my user
1095 - $ref: '#/components/parameters/start'
1096 - $ref: '#/components/parameters/count'
1097 - $ref: '#/components/parameters/sort'
1100 description: successful operation
1104 $ref: '#/components/schemas/VideoListResponse'
1106 /users/me/subscriptions:
1108 summary: Get my user subscriptions
1115 - $ref: '#/components/parameters/start'
1116 - $ref: '#/components/parameters/count'
1117 - $ref: '#/components/parameters/sort'
1120 description: successful operation
1124 $ref: '#/components/schemas/VideoChannelList'
1128 summary: Add subscription to my user
1141 description: uri of the video channels to subscribe to
1147 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1150 description: successful operation
1152 /users/me/subscriptions/exist:
1154 summary: Get if subscriptions exist for my user
1161 - $ref: '#/components/parameters/subscriptionsUris'
1164 description: successful operation
1170 /users/me/subscriptions/videos:
1172 summary: List videos of subscriptions of my user
1180 - $ref: '#/components/parameters/categoryOneOf'
1181 - $ref: '#/components/parameters/isLive'
1182 - $ref: '#/components/parameters/tagsOneOf'
1183 - $ref: '#/components/parameters/tagsAllOf'
1184 - $ref: '#/components/parameters/licenceOneOf'
1185 - $ref: '#/components/parameters/languageOneOf'
1186 - $ref: '#/components/parameters/nsfw'
1187 - $ref: '#/components/parameters/filter'
1188 - $ref: '#/components/parameters/skipCount'
1189 - $ref: '#/components/parameters/start'
1190 - $ref: '#/components/parameters/count'
1191 - $ref: '#/components/parameters/videosSort'
1194 description: successful operation
1198 $ref: '#/components/schemas/VideoListResponse'
1200 '/users/me/subscriptions/{subscriptionHandle}':
1202 summary: Get subscription of my user
1209 - $ref: '#/components/parameters/subscriptionHandle'
1212 description: successful operation
1216 $ref: '#/components/schemas/VideoChannel'
1218 summary: Delete subscription of my user
1225 - $ref: '#/components/parameters/subscriptionHandle'
1228 description: successful operation
1230 /users/me/notifications:
1232 summary: List my notifications
1240 description: only list unread notifications
1243 - $ref: '#/components/parameters/start'
1244 - $ref: '#/components/parameters/count'
1245 - $ref: '#/components/parameters/sort'
1248 description: successful operation
1252 $ref: '#/components/schemas/NotificationListResponse'
1254 /users/me/notifications/read:
1256 summary: Mark notifications as read by their id
1269 description: ids of the notifications to mark as read
1276 description: successful operation
1278 /users/me/notifications/read-all:
1280 summary: Mark all my notification as read
1287 description: successful operation
1289 /users/me/notification-settings:
1291 summary: Update my notification settings
1302 newVideoFromSubscription:
1303 $ref: '#/components/schemas/NotificationSettingValue'
1304 newCommentOnMyVideo:
1305 $ref: '#/components/schemas/NotificationSettingValue'
1307 $ref: '#/components/schemas/NotificationSettingValue'
1308 videoAutoBlacklistAsModerator:
1309 $ref: '#/components/schemas/NotificationSettingValue'
1311 $ref: '#/components/schemas/NotificationSettingValue'
1313 $ref: '#/components/schemas/NotificationSettingValue'
1314 myVideoImportFinished:
1315 $ref: '#/components/schemas/NotificationSettingValue'
1317 $ref: '#/components/schemas/NotificationSettingValue'
1318 newUserRegistration:
1319 $ref: '#/components/schemas/NotificationSettingValue'
1321 $ref: '#/components/schemas/NotificationSettingValue'
1322 newInstanceFollower:
1323 $ref: '#/components/schemas/NotificationSettingValue'
1324 autoInstanceFollowing:
1325 $ref: '#/components/schemas/NotificationSettingValue'
1328 description: successful operation
1330 /users/me/history/videos:
1332 summary: List watched videos history
1338 - $ref: '#/components/parameters/start'
1339 - $ref: '#/components/parameters/count'
1340 - $ref: '#/components/parameters/search'
1343 description: successful operation
1347 $ref: '#/components/schemas/VideoListResponse'
1349 /users/me/history/videos/remove:
1351 summary: Clear video history
1358 multipart/form-data:
1363 description: history before this date will be deleted
1368 description: successful operation
1370 /users/me/avatar/pick:
1372 summary: Update my user avatar
1379 description: successful operation
1386 $ref: '#/components/schemas/ActorImage'
1388 description: image file too large
1390 X-File-Maximum-Size:
1394 description: Maximum file size for the avatar
1397 multipart/form-data:
1402 description: The file to upload
1407 contentType: image/png, image/jpeg
1411 summary: Delete my avatar
1418 description: successful operation
1422 summary: List video ownership changes
1424 - Video Ownership Change
1429 description: successful operation
1431 '/videos/ownership/{id}/accept':
1433 summary: Accept ownership change request
1435 - Video Ownership Change
1439 - $ref: '#/components/parameters/idOrUUID'
1442 description: successful operation
1444 description: cannot terminate an ownership change of another user
1446 description: video owneship change not found
1448 '/videos/ownership/{id}/refuse':
1450 summary: Refuse ownership change request
1452 - Video Ownership Change
1456 - $ref: '#/components/parameters/idOrUUID'
1459 description: successful operation
1461 description: cannot terminate an ownership change of another user
1463 description: video owneship change not found
1465 '/videos/{id}/give-ownership':
1467 summary: Request ownership change
1469 - Video Ownership Change
1473 - $ref: '#/components/parameters/idOrUUID'
1477 application/x-www-form-urlencoded:
1487 description: successful operation
1489 description: changing video ownership to a remote account is not supported yet
1491 description: video not found
1495 summary: List videos
1496 operationId: getVideos
1500 - $ref: '#/components/parameters/categoryOneOf'
1501 - $ref: '#/components/parameters/isLive'
1502 - $ref: '#/components/parameters/tagsOneOf'
1503 - $ref: '#/components/parameters/tagsAllOf'
1504 - $ref: '#/components/parameters/licenceOneOf'
1505 - $ref: '#/components/parameters/languageOneOf'
1506 - $ref: '#/components/parameters/nsfw'
1507 - $ref: '#/components/parameters/filter'
1508 - $ref: '#/components/parameters/skipCount'
1509 - $ref: '#/components/parameters/start'
1510 - $ref: '#/components/parameters/count'
1511 - $ref: '#/components/parameters/videosSort'
1514 description: successful operation
1518 $ref: '#/components/schemas/VideoListResponse'
1522 summary: List available video categories
1523 operationId: getCategories
1528 description: successful operation
1537 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1541 summary: List available video licences
1542 operationId: getLicences
1547 description: successful operation
1556 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1560 summary: List available video languages
1561 operationId: getLanguages
1566 description: successful operation
1575 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1579 summary: List available video privacy policies
1580 operationId: getPrivacyPolicies
1585 description: successful operation
1594 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1598 summary: Update a video
1599 operationId: putVideo
1605 - $ref: '#/components/parameters/idOrUUID'
1608 description: successful operation
1611 multipart/form-data:
1616 description: Video thumbnail file
1620 description: Video preview file
1624 $ref: '#/components/schemas/VideoCategorySet'
1626 $ref: '#/components/schemas/VideoLicenceSet'
1628 $ref: '#/components/schemas/VideoLanguageSet'
1630 $ref: '#/components/schemas/VideoPrivacySet'
1632 description: Video description
1635 description: Whether or not we wait transcoding before publish the video
1638 description: A text tell the audience how to support the video creator
1639 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1642 description: Whether or not this video contains sensitive content
1645 description: Video name
1650 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1659 description: Enable or disable comments for this video
1661 originallyPublishedAt:
1662 description: Date when the content was originally published
1666 $ref: '#/components/schemas/VideoScheduledUpdate'
1669 contentType: image/jpeg
1671 contentType: image/jpeg
1673 summary: Get a video
1674 operationId: getVideo
1678 - $ref: '#/components/parameters/idOrUUID'
1681 description: successful operation
1685 $ref: '#/components/schemas/VideoDetails'
1687 summary: Delete a video
1688 operationId: delVideo
1694 - $ref: '#/components/parameters/idOrUUID'
1697 description: successful operation
1699 '/videos/{id}/description':
1701 summary: Get complete video description
1702 operationId: getVideoDesc
1706 - $ref: '#/components/parameters/idOrUUID'
1709 description: successful operation
1718 **[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)**
1720 '/videos/{id}/views':
1722 summary: Add a view to a video
1726 - $ref: '#/components/parameters/idOrUUID'
1729 description: successful operation
1731 '/videos/{id}/watching':
1733 summary: Set watching progress of a video
1739 - $ref: '#/components/parameters/idOrUUID'
1744 $ref: '#/components/schemas/UserWatchingVideo'
1748 description: successful operation
1752 summary: Upload a video
1753 description: Uses a single request to upload a video.
1754 operationId: uploadLegacy
1762 description: successful operation
1766 $ref: '#/components/schemas/VideoUploadResponse'
1768 description: invalid file field, schedule date or parameter
1770 description: video didn't pass upload filter
1772 description: upload has timed out
1774 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1776 X-File-Maximum-Size:
1780 description: Maximum file size for the video
1782 description: video type unsupported
1784 description: video unreadable
1787 multipart/form-data:
1789 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1792 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1794 contentType: image/jpeg
1796 contentType: image/jpeg
1801 USERNAME="<your_username>"
1802 PASSWORD="<your_password>"
1803 FILE_PATH="<your_file_path>"
1804 CHANNEL_ID="<your_channel_id>"
1806 API="https://peertube2.cpy.re/api/v1"
1809 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1810 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1811 token=$(curl -s "$API/users/token" \
1812 --data client_id="$client_id" \
1813 --data client_secret="$client_secret" \
1814 --data grant_type=password \
1815 --data username="$USERNAME" \
1816 --data password="$PASSWORD" \
1817 | jq -r ".access_token")
1820 curl -s "$API/videos/upload" \
1821 -H "Authorization: Bearer $token" \
1823 --form videofile=@"$FILE_PATH" \
1824 --form channelId=$CHANNEL_ID \
1827 /videos/upload-resumable:
1829 summary: Initialize the resumable upload of a video
1830 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1831 operationId: uploadResumableInit
1838 - name: X-Upload-Content-Length
1844 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1845 - name: X-Upload-Content-Type
1852 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1857 $ref: '#/components/schemas/VideoUploadRequestResumable'
1860 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1862 description: created
1868 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1874 description: invalid file field, schedule date or parameter
1876 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1878 description: video type unsupported
1880 summary: Send chunk for the resumable upload of a video
1881 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
1882 operationId: uploadResumable
1893 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1894 not valid anymore and you need to initialize a new upload.
1897 - name: Content-Range
1901 example: bytes 0-262143/2469036
1904 Specifies the bytes in the file that the request is uploading.
1906 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1907 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1908 - name: Content-Length
1915 Size of the chunk that the request is sending.
1917 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)
1918 doesn't mandate for chunks to have the same size throughout the upload sequence.
1920 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1921 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1924 application/octet-stream:
1930 description: last chunk received
1938 $ref: '#/components/schemas/VideoUploadResponse'
1940 description: resume incomplete
1945 example: bytes=0-262143
1951 description: video didn't pass upload filter
1953 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1955 description: video unreadable
1957 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1958 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1959 operationId: uploadResumableCancel
1970 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1971 not valid anymore and the upload session has already been deleted with its data ;-)
1974 - name: Content-Length
1982 description: upload cancelled
1991 summary: Import a video
1992 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1993 operationId: importVideo
2001 multipart/form-data:
2003 $ref: '#/components/schemas/VideoCreateImport'
2006 contentType: application/x-bittorrent
2008 contentType: image/jpeg
2010 contentType: image/jpeg
2013 description: successful operation
2017 $ref: '#/components/schemas/VideoUploadResponse'
2019 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2021 description: video didn't pass pre-import filter
2023 description: HTTP or Torrent/magnetURI import not enabled
2027 summary: Create a live
2028 operationId: addLive
2036 description: successful operation
2040 $ref: '#/components/schemas/VideoUploadResponse'
2042 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2045 multipart/form-data:
2050 description: Channel id that will contain this live video
2055 description: User can stream multiple times in a permanent live
2058 description: Live video/replay thumbnail file
2062 description: Live video/replay preview file
2066 $ref: '#/components/schemas/VideoPrivacySet'
2068 $ref: '#/components/schemas/VideoCategorySet'
2070 $ref: '#/components/schemas/VideoLicenceSet'
2072 $ref: '#/components/schemas/VideoLanguageSet'
2074 description: Live video/replay description
2077 description: A text tell the audience how to support the creator
2078 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2081 description: Whether or not this live video/replay contains sensitive content
2084 description: Live video/replay name
2089 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2098 description: Enable or disable comments for this live video/replay
2101 description: Enable or disable downloading for the replay of this live
2108 contentType: image/jpeg
2110 contentType: image/jpeg
2114 summary: Get information about a live
2115 operationId: getLiveId
2122 - $ref: '#/components/parameters/idOrUUID'
2125 description: successful operation
2129 $ref: '#/components/schemas/LiveVideoResponse'
2131 summary: Update information about a live
2132 operationId: updateLiveId
2139 - $ref: '#/components/parameters/idOrUUID'
2144 $ref: '#/components/schemas/LiveVideoUpdate'
2147 description: successful operation
2149 description: bad parameters or trying to update a live that has already started
2151 description: trying to save replay of the live but saving replay is not enabled on the instance
2155 summary: List my abuses
2156 operationId: getMyAbuses
2165 description: only list the report with this id
2171 $ref: '#/components/schemas/AbuseStateSet'
2172 - $ref: '#/components/parameters/abusesSort'
2173 - $ref: '#/components/parameters/start'
2174 - $ref: '#/components/parameters/count'
2177 description: successful operation
2189 $ref: '#/components/schemas/Abuse'
2193 summary: List abuses
2194 operationId: getAbuses
2204 description: only list the report with this id
2207 - name: predefinedReason
2209 description: predefined reason the listed reports should contain
2211 $ref: '#/components/schemas/PredefinedAbuseReasons'
2214 description: plain search that will match with video titles, reporter names and more
2220 $ref: '#/components/schemas/AbuseStateSet'
2221 - name: searchReporter
2223 description: only list reports of a specific reporter
2226 - name: searchReportee
2227 description: only list reports of a specific reportee
2233 description: only list reports of a specific video
2236 - name: searchVideoChannel
2238 description: only list reports of a specific video channel
2243 description: only list blacklisted or deleted videos
2251 description: only list account, comment or video reports
2258 - $ref: '#/components/parameters/start'
2259 - $ref: '#/components/parameters/count'
2260 - $ref: '#/components/parameters/abusesSort'
2263 description: successful operation
2275 $ref: '#/components/schemas/Abuse'
2277 summary: Report an abuse
2290 description: Reason why the user reports this video
2295 $ref: '#/components/schemas/PredefinedAbuseReasons'
2300 description: Video id to report
2302 - $ref: '#/components/schemas/Video/properties/id'
2306 description: Timestamp in the video that marks the beginning of the report
2311 description: Timestamp in the video that marks the ending of the report
2317 description: Comment id to report
2319 - $ref: '#/components/schemas/VideoComment/properties/id'
2324 description: Account id to report
2330 description: successful operation
2340 $ref: '#/components/schemas/id'
2342 description: incorrect request parameters
2344 '/abuses/{abuseId}':
2346 summary: Update an abuse
2354 - $ref: '#/components/parameters/abuseId'
2362 $ref: '#/components/schemas/AbuseStateSet'
2365 description: Update the report comment visible only to the moderation team
2370 description: successful operation
2372 description: abuse not found
2376 summary: Delete an abuse
2382 - $ref: '#/components/parameters/abuseId'
2385 description: successful operation
2387 description: block not found
2389 '/abuses/{abuseId}/messages':
2391 summary: List messages of an abuse
2397 - $ref: '#/components/parameters/abuseId'
2400 description: successful operation
2412 $ref: '#/components/schemas/AbuseMessage'
2414 summary: Add message to an abuse
2420 - $ref: '#/components/parameters/abuseId'
2429 description: Message to send
2437 description: successful operation
2439 description: incorrect request parameters
2441 '/abuses/{abuseId}/messages/{abuseMessageId}':
2443 summary: Delete an abuse message
2449 - $ref: '#/components/parameters/abuseId'
2450 - $ref: '#/components/parameters/abuseMessageId'
2453 description: successful operation
2455 '/videos/{id}/blacklist':
2457 summary: Block a video
2458 operationId: addVideoBlock
2466 - $ref: '#/components/parameters/idOrUUID'
2469 description: successful operation
2471 summary: Unblock a video by its id
2472 operationId: delVideoBlock
2480 - $ref: '#/components/parameters/idOrUUID'
2483 description: successful operation
2485 description: block not found
2491 summary: List video blocks
2492 operationId: getVideoBlocks
2501 list only blocks that match this type:
2505 - `2`: automatic block that needs review
2513 description: plain search that will match with video titles, and more
2516 - $ref: '#/components/parameters/start'
2517 - $ref: '#/components/parameters/count'
2518 - $ref: '#/components/parameters/blacklistsSort'
2521 description: successful operation
2533 $ref: '#/components/schemas/VideoBlacklist'
2535 /videos/{id}/captions:
2537 summary: List captions of a video
2538 operationId: getVideoCaptions
2542 - $ref: '#/components/parameters/idOrUUID'
2545 description: successful operation
2557 $ref: '#/components/schemas/VideoCaption'
2559 /videos/{id}/captions/{captionLanguage}:
2561 summary: Add or replace a video caption
2562 operationId: addVideoCaption
2569 - $ref: '#/components/parameters/idOrUUID'
2570 - $ref: '#/components/parameters/captionLanguage'
2573 multipart/form-data:
2578 description: The file to upload.
2583 contentType: text/vtt, application/x-subrip, text/plain
2586 description: successful operation
2588 description: video or language not found
2590 summary: Delete a video caption
2591 operationId: delVideoCaption
2598 - $ref: '#/components/parameters/idOrUUID'
2599 - $ref: '#/components/parameters/captionLanguage'
2602 description: successful operation
2604 description: video or language or caption for that language not found
2608 summary: List video channels
2609 operationId: getVideoChannels
2613 - $ref: '#/components/parameters/start'
2614 - $ref: '#/components/parameters/count'
2615 - $ref: '#/components/parameters/sort'
2618 description: successful operation
2622 $ref: '#/components/schemas/VideoChannelList'
2624 summary: Create a video channel
2625 operationId: addVideoChannel
2632 description: successful operation
2642 $ref: '#/components/schemas/VideoChannel/properties/id'
2647 $ref: '#/components/schemas/VideoChannelCreate'
2649 '/video-channels/{channelHandle}':
2651 summary: Get a video channel
2652 operationId: getVideoChannel
2656 - $ref: '#/components/parameters/channelHandle'
2659 description: successful operation
2663 $ref: '#/components/schemas/VideoChannel'
2665 summary: Update a video channel
2666 operationId: putVideoChannel
2672 - $ref: '#/components/parameters/channelHandle'
2675 description: successful operation
2680 $ref: '#/components/schemas/VideoChannelUpdate'
2682 summary: Delete a video channel
2683 operationId: delVideoChannel
2689 - $ref: '#/components/parameters/channelHandle'
2692 description: successful operation
2694 '/video-channels/{channelHandle}/videos':
2696 summary: List videos of a video channel
2697 operationId: getVideoChannelVideos
2702 - $ref: '#/components/parameters/channelHandle'
2703 - $ref: '#/components/parameters/categoryOneOf'
2704 - $ref: '#/components/parameters/isLive'
2705 - $ref: '#/components/parameters/tagsOneOf'
2706 - $ref: '#/components/parameters/tagsAllOf'
2707 - $ref: '#/components/parameters/licenceOneOf'
2708 - $ref: '#/components/parameters/languageOneOf'
2709 - $ref: '#/components/parameters/nsfw'
2710 - $ref: '#/components/parameters/filter'
2711 - $ref: '#/components/parameters/skipCount'
2712 - $ref: '#/components/parameters/start'
2713 - $ref: '#/components/parameters/count'
2714 - $ref: '#/components/parameters/videosSort'
2717 description: successful operation
2721 $ref: '#/components/schemas/VideoListResponse'
2723 '/video-channels/{channelHandle}/avatar/pick':
2725 summary: Update channel avatar
2731 - $ref: '#/components/parameters/channelHandle'
2734 description: successful operation
2741 $ref: '#/components/schemas/ActorImage'
2743 description: image file too large
2745 X-File-Maximum-Size:
2749 description: Maximum file size for the avatar
2752 multipart/form-data:
2757 description: The file to upload.
2762 contentType: image/png, image/jpeg
2764 '/video-channels/{channelHandle}/avatar':
2766 summary: Delete channel avatar
2772 - $ref: '#/components/parameters/channelHandle'
2775 description: successful operation
2777 '/video-channels/{channelHandle}/banner/pick':
2779 summary: Update channel banner
2785 - $ref: '#/components/parameters/channelHandle'
2788 description: successful operation
2795 $ref: '#/components/schemas/ActorImage'
2797 description: image file too large
2799 X-File-Maximum-Size:
2803 description: Maximum file size for the banner
2806 multipart/form-data:
2811 description: The file to upload.
2816 contentType: image/png, image/jpeg
2818 '/video-channels/{channelHandle}/banner':
2820 summary: Delete channel banner
2826 - $ref: '#/components/parameters/channelHandle'
2829 description: successful operation
2831 /video-playlists/privacies:
2833 summary: List available playlist privacy policies
2834 operationId: getPlaylistPrivacyPolicies
2839 description: successful operation
2848 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2852 summary: List video playlists
2853 operationId: getPlaylists
2857 - $ref: '#/components/parameters/start'
2858 - $ref: '#/components/parameters/count'
2859 - $ref: '#/components/parameters/sort'
2862 description: successful operation
2874 $ref: '#/components/schemas/VideoPlaylist'
2876 summary: Create a video playlist
2877 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2878 operationId: addPlaylist
2885 description: successful operation
2895 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2897 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2900 multipart/form-data:
2905 description: Video playlist display name
2910 description: Video playlist thumbnail file
2914 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2916 description: Video playlist description
2922 - $ref: '#/components/schemas/id'
2923 description: Video channel in which the playlist will be published
2928 contentType: image/jpeg
2930 /video-playlists/{playlistId}:
2932 summary: Get a video playlist
2936 - $ref: '#/components/parameters/playlistId'
2939 description: successful operation
2943 $ref: '#/components/schemas/VideoPlaylist'
2945 summary: Update a video playlist
2946 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2953 description: successful operation
2955 - $ref: '#/components/parameters/playlistId'
2958 multipart/form-data:
2963 description: Video playlist display name
2968 description: Video playlist thumbnail file
2972 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2974 description: Video playlist description
2978 - $ref: '#/components/schemas/id'
2979 description: Video channel in which the playlist will be published
2982 contentType: image/jpeg
2984 summary: Delete a video playlist
2990 - $ref: '#/components/parameters/playlistId'
2993 description: successful operation
2995 /video-playlists/{playlistId}/videos:
2997 summary: 'List videos of a playlist'
2998 operationId: getVideoPlaylistVideos
3003 - $ref: '#/components/parameters/playlistId'
3006 description: successful operation
3010 $ref: '#/components/schemas/VideoListResponse'
3012 summary: Add a video in a playlist
3013 operationId: addVideoPlaylistVideo
3020 - $ref: '#/components/parameters/playlistId'
3023 description: successful operation
3029 videoPlaylistElement:
3043 - $ref: '#/components/schemas/Video/properties/uuid'
3044 - $ref: '#/components/schemas/Video/properties/id'
3045 description: Video to add in the playlist
3049 description: Start the video at this specific timestamp
3053 description: Stop the video at this specific timestamp
3057 /video-playlists/{playlistId}/videos/reorder:
3059 summary: 'Reorder a playlist'
3060 operationId: reorderVideoPlaylist
3066 - $ref: '#/components/parameters/playlistId'
3069 description: successful operation
3078 description: 'Start position of the element to reorder'
3080 insertAfterPosition:
3082 description: 'New position for the block to reorder, to add the block before the first element'
3086 description: 'How many element from `startPosition` to reorder'
3090 - insertAfterPosition
3092 /video-playlists/{playlistId}/videos/{playlistElementId}:
3094 summary: Update a playlist element
3095 operationId: putVideoPlaylistVideo
3101 - $ref: '#/components/parameters/playlistId'
3102 - $ref: '#/components/parameters/playlistElementId'
3105 description: successful operation
3115 description: Start the video at this specific timestamp
3119 description: Stop the video at this specific timestamp
3121 summary: Delete an element from a playlist
3122 operationId: delVideoPlaylistVideo
3128 - $ref: '#/components/parameters/playlistId'
3129 - $ref: '#/components/parameters/playlistElementId'
3132 description: successful operation
3134 '/users/me/video-playlists/videos-exist':
3136 summary: Check video exists in my playlists
3145 description: The video ids to check
3149 $ref: '#/components/schemas/Video/properties/id'
3152 description: successful operation
3174 '/accounts/{name}/video-channels':
3176 summary: List video channels of an account
3181 - $ref: '#/components/parameters/name'
3184 description: include view statistics for the last 30 days (only if authentified as the account user)
3187 - $ref: '#/components/parameters/start'
3188 - $ref: '#/components/parameters/count'
3189 - $ref: '#/components/parameters/sort'
3192 description: successful operation
3196 $ref: '#/components/schemas/VideoChannelList'
3198 '/accounts/{name}/ratings':
3200 summary: List ratings of an account
3206 - $ref: '#/components/parameters/name'
3207 - $ref: '#/components/parameters/start'
3208 - $ref: '#/components/parameters/count'
3209 - $ref: '#/components/parameters/sort'
3213 description: Optionally filter which ratings to retrieve
3221 description: successful operation
3227 $ref: '#/components/schemas/VideoRating'
3229 '/videos/{id}/comment-threads':
3231 summary: List threads of a video
3235 - $ref: '#/components/parameters/idOrUUID'
3236 - $ref: '#/components/parameters/start'
3237 - $ref: '#/components/parameters/count'
3238 - $ref: '#/components/parameters/commentsSort'
3241 description: successful operation
3245 $ref: '#/components/schemas/CommentThreadResponse'
3247 summary: Create a thread
3253 - $ref: '#/components/parameters/idOrUUID'
3256 description: successful operation
3260 $ref: '#/components/schemas/CommentThreadPostResponse'
3262 description: video does not exist
3271 - $ref: '#/components/schemas/VideoComment/properties/text'
3277 '/videos/{id}/comment-threads/{threadId}':
3279 summary: Get a thread
3283 - $ref: '#/components/parameters/idOrUUID'
3284 - $ref: '#/components/parameters/threadId'
3287 description: successful operation
3291 $ref: '#/components/schemas/VideoCommentThreadTree'
3293 '/videos/{id}/comments/{commentId}':
3295 summary: Reply to a thread of a video
3301 - $ref: '#/components/parameters/idOrUUID'
3302 - $ref: '#/components/parameters/commentId'
3305 description: successful operation
3309 $ref: '#/components/schemas/CommentThreadPostResponse'
3311 description: thread or video does not exist
3320 - $ref: '#/components/schemas/VideoComment/properties/text'
3326 summary: Delete a comment or a reply
3332 - $ref: '#/components/parameters/idOrUUID'
3333 - $ref: '#/components/parameters/commentId'
3336 description: successful operation
3338 description: cannot remove comment of another user
3340 description: comment or video does not exist
3342 description: comment is already deleted
3344 '/videos/{id}/rate':
3346 summary: Like/dislike a video
3352 - $ref: '#/components/parameters/idOrUUID'
3368 description: successful operation
3370 description: video does not exist
3376 summary: Search videos
3377 operationId: searchVideos
3382 allowEmptyValue: false
3384 String to search. If the user can make a remote URI search, and the string is an URI then the
3385 PeerTube instance will fetch the remote object and add it to its database. Then,
3386 you can use the REST API to fetch the complete video information and interact with it.
3389 - $ref: '#/components/parameters/categoryOneOf'
3390 - $ref: '#/components/parameters/isLive'
3391 - $ref: '#/components/parameters/tagsOneOf'
3392 - $ref: '#/components/parameters/tagsAllOf'
3393 - $ref: '#/components/parameters/licenceOneOf'
3394 - $ref: '#/components/parameters/languageOneOf'
3395 - $ref: '#/components/parameters/nsfw'
3396 - $ref: '#/components/parameters/filter'
3397 - $ref: '#/components/parameters/skipCount'
3398 - $ref: '#/components/parameters/start'
3399 - $ref: '#/components/parameters/count'
3400 - $ref: '#/components/parameters/searchTarget'
3401 - $ref: '#/components/parameters/videosSearchSort'
3404 description: Get videos that are published after this date
3410 description: Get videos that are published before this date
3414 - name: originallyPublishedStartDate
3416 description: Get videos that are originally published after this date
3420 - name: originallyPublishedEndDate
3422 description: Get videos that are originally published before this date
3428 description: Get videos that have this minimum duration
3433 description: Get videos that have this maximum duration
3437 'searchTarget === search-index':
3438 $ref: '#/components/callbacks/searchIndex'
3441 description: successful operation
3445 $ref: '#/components/schemas/VideoListResponse'
3447 description: search index unavailable
3449 /search/video-channels:
3453 summary: Search channels
3454 operationId: searchChannels
3460 String to search. If the user can make a remote URI search, and the string is an URI then the
3461 PeerTube instance will fetch the remote object and add it to its database. Then,
3462 you can use the REST API to fetch the complete channel information and interact with it.
3465 - $ref: '#/components/parameters/start'
3466 - $ref: '#/components/parameters/count'
3467 - $ref: '#/components/parameters/searchTarget'
3468 - $ref: '#/components/parameters/sort'
3470 'searchTarget === search-index':
3471 $ref: '#/components/callbacks/searchIndex'
3474 description: successful operation
3478 $ref: '#/components/schemas/VideoChannelList'
3480 description: search index unavailable
3482 /server/blocklist/accounts:
3486 summary: List account blocks
3491 - $ref: '#/components/parameters/start'
3492 - $ref: '#/components/parameters/count'
3493 - $ref: '#/components/parameters/sort'
3496 description: successful operation
3500 summary: Block an account
3512 example: chocobozzz@example.org
3513 description: account to block, in the form `username@domain`
3518 description: successful operation
3520 description: self-blocking forbidden
3522 '/server/blocklist/accounts/{accountName}':
3526 summary: Unblock an account by its handle
3534 description: account to unblock, in the form `username@domain`
3539 description: successful operation
3541 description: account or account block does not exist
3543 /server/blocklist/servers:
3547 summary: List server blocks
3552 - $ref: '#/components/parameters/start'
3553 - $ref: '#/components/parameters/count'
3554 - $ref: '#/components/parameters/sort'
3557 description: successful operation
3561 summary: Block a server
3574 description: server domain to block
3579 description: successful operation
3581 description: self-blocking forbidden
3583 '/server/blocklist/servers/{host}':
3587 summary: Unblock a server by its domain
3595 description: server domain to unblock
3601 description: successful operation
3603 description: account block does not exist
3605 /server/redundancy/{host}:
3608 - Instance Redundancy
3609 summary: Update a server redundancy policy
3617 description: server domain to mirror
3629 description: allow mirroring of the host's local videos
3634 description: successful operation
3636 description: server is not already known
3638 /server/redundancy/videos:
3642 summary: List videos being mirrored
3643 operationId: getMirroredVideos
3651 description: direction of the mirror
3657 - $ref: '#/components/parameters/start'
3658 - $ref: '#/components/parameters/count'
3659 - $ref: '#/components/parameters/videoRedundanciesSort'
3662 description: successful operation
3668 $ref: '#/components/schemas/VideoRedundancy'
3672 summary: Mirror a video
3673 operationId: putMirroredVideo
3684 $ref: '#/components/schemas/Video/properties/id'
3689 description: successful operation
3691 description: cannot mirror a local video
3693 description: video does not exist
3695 description: video is already mirrored
3697 /server/redundancy/videos/{redundancyId}:
3701 summary: Delete a mirror done on a video
3702 operationId: delMirroredVideo
3707 - name: redundancyId
3710 description: id of an existing redundancy on a video
3715 description: successful operation
3717 description: video redundancy not found
3719 '/feeds/video-comments.{format}':
3723 summary: List comments on videos
3724 operationId: getSyndicatedComments
3729 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3742 description: 'limit listing to a specific video'
3747 description: 'limit listing to a specific account'
3752 description: 'limit listing to a specific account'
3755 - name: videoChannelId
3757 description: 'limit listing to a specific video channel'
3760 - name: videoChannelName
3762 description: 'limit listing to a specific video channel'
3767 description: successful operation
3772 default: 'max-age=900' # 15 min cache
3776 $ref: '#/components/schemas/VideoCommentsForXML'
3779 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3780 application/rss+xml:
3782 $ref: '#/components/schemas/VideoCommentsForXML'
3785 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3788 $ref: '#/components/schemas/VideoCommentsForXML'
3791 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3792 application/atom+xml:
3794 $ref: '#/components/schemas/VideoCommentsForXML'
3797 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3803 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3805 x-summary: field inconsistencies
3808 - videoId filter is mixed with a channel filter
3810 description: video, video channel or account not found
3812 description: accept header unsupported
3814 '/feeds/videos.{format}':
3818 summary: List videos
3819 operationId: getSyndicatedVideos
3824 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3837 description: 'limit listing to a specific account'
3842 description: 'limit listing to a specific account'
3845 - name: videoChannelId
3847 description: 'limit listing to a specific video channel'
3850 - name: videoChannelName
3852 description: 'limit listing to a specific video channel'
3855 - $ref: '#/components/parameters/sort'
3856 - $ref: '#/components/parameters/nsfw'
3857 - $ref: '#/components/parameters/filter'
3860 description: successful operation
3865 default: 'max-age=900' # 15 min cache
3869 $ref: '#/components/schemas/VideosForXML'
3872 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3873 application/rss+xml:
3875 $ref: '#/components/schemas/VideosForXML'
3878 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3881 $ref: '#/components/schemas/VideosForXML'
3884 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3885 application/atom+xml:
3887 $ref: '#/components/schemas/VideosForXML'
3890 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3896 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3898 description: video channel or account not found
3900 description: accept header unsupported
3902 '/feeds/subscriptions.{format}':
3907 summary: List videos of subscriptions tied to a token
3908 operationId: getSyndicatedSubscriptionVideos
3913 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3926 description: limit listing to a specific account
3932 description: private token allowing access
3936 - $ref: '#/components/parameters/sort'
3937 - $ref: '#/components/parameters/nsfw'
3938 - $ref: '#/components/parameters/filter'
3941 description: successful operation
3946 default: 'max-age=900' # 15 min cache
3950 $ref: '#/components/schemas/VideosForXML'
3951 application/rss+xml:
3953 $ref: '#/components/schemas/VideosForXML'
3956 $ref: '#/components/schemas/VideosForXML'
3957 application/atom+xml:
3959 $ref: '#/components/schemas/VideosForXML'
3964 description: accept header unsupported
3970 summary: List plugins
3971 operationId: getPlugins
3984 - $ref: '#/components/parameters/start'
3985 - $ref: '#/components/parameters/count'
3986 - $ref: '#/components/parameters/sort'
3989 description: successful operation
3993 $ref: '#/components/schemas/PluginResponse'
3999 summary: List available plugins
4000 operationId: getAvailablePlugins
4013 - name: currentPeerTubeEngine
4017 - $ref: '#/components/parameters/start'
4018 - $ref: '#/components/parameters/count'
4019 - $ref: '#/components/parameters/sort'
4022 description: successful operation
4026 $ref: '#/components/schemas/PluginResponse'
4028 description: plugin index unavailable
4034 summary: Install a plugin
4035 operationId: addPlugin
4048 example: peertube-plugin-auth-ldap
4051 additionalProperties: false
4058 additionalProperties: false
4061 description: successful operation
4063 description: should have either `npmName` or `path` set
4069 summary: Update a plugin
4070 operationId: updatePlugin
4083 example: peertube-plugin-auth-ldap
4086 additionalProperties: false
4093 additionalProperties: false
4096 description: successful operation
4098 description: should have either `npmName` or `path` set
4100 description: existing plugin not found
4106 summary: Uninstall a plugin
4107 operationId: uninstallPlugin
4119 description: name of the plugin/theme in its package.json
4120 example: peertube-plugin-auth-ldap
4125 description: successful operation
4127 description: existing plugin not found
4133 summary: Get a plugin
4134 operationId: getPlugin
4139 - $ref: '#/components/parameters/npmName'
4142 description: successful operation
4146 $ref: '#/components/schemas/Plugin'
4148 description: plugin not found
4150 /plugins/{npmName}/settings:
4154 summary: Set a plugin's settings
4159 - $ref: '#/components/parameters/npmName'
4168 additionalProperties: true
4171 description: successful operation
4173 description: plugin not found
4175 /plugins/{npmName}/public-settings:
4179 summary: Get a plugin's public settings
4181 - $ref: '#/components/parameters/npmName'
4184 description: successful operation
4189 additionalProperties: true
4191 description: plugin not found
4193 /plugins/{npmName}/registered-settings:
4197 summary: Get a plugin's registered settings
4202 - $ref: '#/components/parameters/npmName'
4205 description: successful operation
4210 additionalProperties: true
4212 description: plugin not found
4215 - url: 'https://peertube2.cpy.re/api/v1'
4216 description: Live Test Server (live data - latest nightly version)
4217 - url: 'https://peertube3.cpy.re/api/v1'
4218 description: Live Test Server (live data - latest RC version)
4219 - url: 'https://peertube.cpy.re/api/v1'
4220 description: Live Test Server (live data - stable version)
4227 description: Offset used to paginate results
4235 description: "Number of items to return"
4245 description: Sort column
4253 description: Plain text search, applied to various parts of the model depending on endpoint
4261 If the administrator enabled search index support, you can override the default search target.
4264 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4265 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4266 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4267 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4268 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4269 * 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
4270 the data from the origin instance API
4280 description: Sort videos by criteria
4296 description: Sort videos by criteria
4311 description: Sort comments by criteria
4321 description: Sort blacklists by criteria
4337 description: Plain text search that will match with user usernames or emails
4344 description: Filter results down to (un)banned users
4351 description: Sort users by criteria
4362 description: Sort abuses by criteria
4369 videoRedundanciesSort:
4373 description: Sort abuses by criteria
4382 description: The username or handle of the account
4385 example: chocobozzz | chocobozzz@example.org
4390 description: The user id
4392 $ref: '#/components/schemas/id'
4397 description: The object id or uuid
4400 - $ref: '#/components/schemas/id'
4401 - $ref: '#/components/schemas/UUIDv4'
4406 description: Playlist id
4408 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4410 name: playlistElementId
4413 description: Playlist element id
4415 $ref: '#/components/schemas/id'
4420 description: Abuse id
4422 $ref: '#/components/schemas/Abuse/properties/id'
4424 name: abuseMessageId
4427 description: Abuse message id
4429 $ref: '#/components/schemas/AbuseMessage/properties/id'
4431 name: captionLanguage
4434 description: The caption language
4436 $ref: '#/components/schemas/VideoLanguageSet'
4441 description: The video channel handle
4444 example: my_username | my_username@example.com
4446 name: subscriptionHandle
4449 description: The subscription handle
4452 example: my_username | my_username@example.com
4457 description: The thread id (root comment id)
4459 $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
4464 description: The comment id
4466 $ref: '#/components/schemas/VideoComment/properties/id'
4471 description: whether or not the video is a live
4478 description: category id of the video (see [/videos/categories](#operation/getCategories))
4481 - $ref: '#/components/schemas/VideoCategorySet'
4484 $ref: '#/components/schemas/VideoCategorySet'
4491 description: tag(s) of the video
4505 description: tag(s) of the video, where all should be present in the video
4518 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4521 - $ref: '#/components/schemas/VideoLanguageSet'
4524 $ref: '#/components/schemas/VideoLanguageSet'
4531 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4534 - $ref: '#/components/schemas/VideoLicenceSet'
4537 $ref: '#/components/schemas/VideoLicenceSet'
4544 description: if you don't need the `total` in the response
4555 description: whether to include nsfw videos, if any
4566 Special filters which might require special rights:
4567 * `local` - only videos local to the instance
4568 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4569 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4579 description: list of uris to check if each is part of the user subscriptions
4589 description: name of the plugin/theme on npmjs.com or in its package.json
4592 example: peertube-plugin-auth-ldap
4597 description: job type
4601 - activitypub-follow
4602 - activitypub-http-broadcast
4603 - activitypub-http-fetcher
4604 - activitypub-http-unicast
4610 - activitypub-refresher
4635 Authenticating via OAuth requires the following steps:
4636 - Have an activated account
4637 - [Generate] an access token for that account at `/api/v1/users/token`.
4638 - Make requests with the *Authorization: Bearer <token\>* header
4639 - Profit, depending on the role assigned to the account
4641 Note that the __access token is valid for 1 day__ and is given
4642 along with a __refresh token valid for 2 weeks__.
4644 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4648 tokenUrl: /api/v1/users/token
4651 moderator: Moderator scope
4654 # Resuable core properties
4662 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4663 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4668 description: immutable name of the user, used to find or mention its actor
4670 pattern: '/^[a-z0-9._]+$/'
4675 description: immutable name of the channel, used to interact with its actor
4676 example: framasoft_videos
4677 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4688 description: category id of the video (see [/videos/categories](#operation/getCategories))
4690 VideoConstantNumber-Category:
4693 $ref: '#/components/schemas/VideoCategorySet'
4696 example: Science & Technology
4700 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4702 VideoConstantNumber-Licence:
4705 $ref: '#/components/schemas/VideoLicenceSet'
4708 example: Attribution - Share Alike
4712 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4714 VideoConstantString-Language:
4717 $ref: '#/components/schemas/VideoLanguageSet'
4722 VideoPlaylistPrivacySet:
4728 description: Video playlist privacy policy (see [/video-playlists/privacies])
4729 VideoPlaylistPrivacyConstant:
4732 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4736 VideoPlaylistTypeSet:
4741 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4742 VideoPlaylistTypeConstant:
4745 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4756 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4757 VideoPrivacyConstant:
4760 $ref: '#/components/schemas/VideoPrivacySet'
4777 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4784 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4795 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4805 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4809 $ref: '#/components/schemas/AbuseStateSet'
4812 AbusePredefinedReasons:
4825 example: [spamOrMisleading]
4830 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4832 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4834 VideoResolutionConstant:
4835 description: resolutions and their labels for the video
4838 $ref: '#/components/schemas/VideoResolutionSet'
4842 VideoScheduledUpdate:
4845 $ref: '#/components/schemas/VideoPrivacySet'
4849 description: When to update the video
4869 - $ref: '#/components/schemas/ActorImage'
4870 VideoChannelSummary:
4873 $ref: '#/components/schemas/id'
4887 - $ref: '#/components/schemas/ActorImage'
4901 - $ref: '#/components/schemas/Video'
4908 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4909 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
4910 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4912 $ref: '#/components/schemas/VideoResolutionConstant'
4915 description: Video file size in bytes
4918 description: Direct URL of the torrent file
4922 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4926 description: Direct URL of the video
4930 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4934 description: Frames per second of the video file
4938 description: URL dereferencing the output of ffprobe on the file
4939 VideoStreamingPlaylists:
4944 $ref: '#/components/schemas/id'
4952 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4953 VideoStreamingPlaylists-HLS:
4964 Video files associated to this playlist.
4966 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4968 $ref: '#/components/schemas/VideoFile'
4980 $ref: '#/components/schemas/Video/properties/id'
4982 $ref: '#/components/schemas/Video/properties/uuid'
4984 $ref: '#/components/schemas/Video/properties/name'
4988 description: object id for the video
4990 - $ref: '#/components/schemas/id'
4992 description: universal identifier for the video, that can be used across instances
4994 - $ref: '#/components/schemas/UUIDv4'
5000 example: 2017-10-01T10:52:46.396Z
5001 description: time at which the video object was first drafted
5005 example: 2018-10-01T10:52:46.396Z
5006 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5010 example: 2021-05-04T08:01:01.502Z
5011 description: last time the video's metadata was modified
5012 originallyPublishedAt:
5015 example: 2010-10-01T10:52:46.396Z
5016 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5019 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5020 description: category in which the video is classified
5023 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5024 description: licence under which the video is distributed
5027 - $ref: '#/components/schemas/VideoConstantString-Language'
5028 description: main language used in the video
5031 - $ref: '#/components/schemas/VideoPrivacyConstant'
5032 description: privacy policy used to distribute the video
5036 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5037 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5041 truncated description of the video, written in Markdown.
5042 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5047 description: duration of the video in seconds
5052 description: title of the video
5053 example: What is PeerTube?
5058 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5061 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5064 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5081 - $ref: '#/components/schemas/VideoStateConstant'
5082 description: represents the internal state of the video processing within the PeerTube instance
5086 - $ref: '#/components/schemas/VideoScheduledUpdate'
5094 $ref: '#/components/schemas/AccountSummary'
5096 $ref: '#/components/schemas/VideoChannelSummary'
5105 - $ref: '#/components/schemas/Video'
5110 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5111 description: path at which to get the full description of maximum `10000` characters
5114 description: A text tell the audience how to support the video creator
5115 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5119 $ref: '#/components/schemas/VideoChannel'
5121 $ref: '#/components/schemas/Account'
5123 example: [flowers, gardening]
5141 - https://peertube2.cpy.re/tracker/announce
5142 - wss://peertube2.cpy.re/tracker/socket
5146 $ref: '#/components/schemas/VideoFile'
5148 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5150 - field will be empty
5151 - video files will be found in `streamingPlaylists[].files` field
5155 $ref: '#/components/schemas/VideoStreamingPlaylists'
5157 HLS playlists/manifest files. If HLS is disabled on the server:
5159 - field will be empty
5160 - video files will be found in `files` field
5161 FileRedundancyInformation:
5164 $ref: '#/components/schemas/id'
5189 $ref: '#/components/schemas/id'
5196 $ref: '#/components/schemas/UUIDv4'
5203 $ref: '#/components/schemas/FileRedundancyInformation'
5207 $ref: '#/components/schemas/FileRedundancyInformation'
5208 VideoImportStateConstant:
5216 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5223 additionalProperties: false
5227 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5228 required: [targetUrl]
5231 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5232 required: [magnetUri]
5235 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5236 required: [torrentfile]
5237 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5246 - $ref: '#/components/schemas/id'
5250 description: remote URL where to find the import's source video
5251 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5255 description: magnet URI allowing to resolve the import's source video
5256 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
5257 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5262 description: Torrent file containing only the video file
5269 - $ref: '#/components/schemas/VideoImportStateConstant'
5285 - $ref: '#/components/schemas/Video'
5295 $ref: '#/components/schemas/VideoImport'
5299 $ref: '#/components/schemas/id'
5302 example: The video is a spam
5306 $ref: '#/components/schemas/AbusePredefinedReasons'
5308 $ref: '#/components/schemas/Account'
5310 $ref: '#/components/schemas/AbuseStateConstant'
5313 example: Decided to ban the server since it spams us regularly
5317 $ref: '#/components/schemas/VideoInfo'
5324 $ref: '#/components/schemas/id'
5335 $ref: '#/components/schemas/AccountSummary'
5339 $ref: '#/components/schemas/id'
5341 $ref: '#/components/schemas/Video/properties/id'
5353 $ref: '#/components/schemas/UUIDv4'
5371 $ref: '#/components/schemas/id'
5373 $ref: '#/components/schemas/UUIDv4'
5396 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5398 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5400 $ref: '#/components/schemas/AccountSummary'
5402 $ref: '#/components/schemas/VideoChannelSummary'
5406 $ref: '#/components/schemas/id'
5413 description: Text of the comment
5415 example: This video is wonderful!
5417 $ref: '#/components/schemas/id'
5421 - $ref: '#/components/schemas/id'
5423 $ref: '#/components/schemas/Video/properties/id'
5438 totalRepliesFromVideoAuthor:
5445 $ref: '#/components/schemas/Account'
5446 VideoCommentThreadTree:
5449 $ref: '#/components/schemas/VideoComment'
5453 $ref: '#/components/schemas/VideoCommentThreadTree'
5457 $ref: '#/components/schemas/VideoConstantString-Language'
5473 $ref: '#/components/schemas/id'
5490 $ref: '#/components/schemas/id'
5495 description: immutable name of the actor, used to find or mention it
5497 - $ref: '#/components/schemas/username'
5501 description: server on which the actor is resident
5502 hostRedundancyAllowed:
5504 description: whether this actor's host allows redundancy of its videos
5508 description: number of actors subscribed to by this actor, as seen by this instance
5512 description: number of followers of this actor, as seen by this instance
5520 $ref: '#/components/schemas/ActorImage'
5523 - $ref: '#/components/schemas/Actor'
5526 description: object id for the user tied to this account
5528 - $ref: '#/components/schemas/User/properties/id'
5531 description: editable name of the account, displayed in its representations
5536 description: text or bio displayed on the account's profile
5542 description: timestamp within the video, in seconds
5609 allowedForCurrentIP:
5611 requiresEmailVerification:
5629 $ref: '#/components/schemas/VideoResolutionSet'
5714 example: 16810141515
5817 requiresEmailVerification:
5832 description: Settings that apply to new users, if registration is enabled
5836 example: 16810141515
5842 description: Settings pertaining to transcoding jobs
5846 allowAdditionalExtensions:
5848 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5851 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5854 description: Amount of threads used by ffmpeg for 1 transcoding job
5857 description: Amount of transcoding jobs to execute in parallel
5863 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5866 description: Resolutions to transcode _new videos_ to
5886 description: WebTorrent-specific settings
5892 description: HLS-specific settings
5936 $ref: '#/components/schemas/id'
5938 $ref: '#/components/schemas/Actor'
5940 $ref: '#/components/schemas/Actor'
5943 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5956 PredefinedAbuseReasons:
5957 description: Reason categories that help triage reports
5975 $ref: '#/components/schemas/id'
5987 - activitypub-http-unicast
5988 - activitypub-http-broadcast
5989 - activitypub-http-fetcher
5990 - activitypub-follow
5996 - activitypub-refresher
6000 additionalProperties: true
6003 additionalProperties: true
6019 $ref: '#/components/schemas/id'
6024 $ref: '#/components/schemas/id'
6025 VideoUploadRequestCommon:
6028 description: Video name
6030 example: What is PeerTube?
6034 description: Channel id that will contain this video
6039 $ref: '#/components/schemas/VideoPrivacySet'
6041 $ref: '#/components/schemas/VideoCategorySet'
6043 $ref: '#/components/schemas/VideoLicenceSet'
6045 $ref: '#/components/schemas/VideoLanguageSet'
6047 description: Video description
6050 **[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)**
6052 description: Whether or not we wait transcoding before publish the video
6055 description: A text tell the audience how to support the video creator
6056 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6059 description: Whether or not this video contains sensitive content
6062 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6075 description: Enable or disable comments for this video
6078 description: Enable or disable downloading for this video
6080 originallyPublishedAt:
6081 description: Date when the content was originally published
6085 $ref: '#/components/schemas/VideoScheduledUpdate'
6087 description: Video thumbnail file
6091 description: Video preview file
6097 VideoUploadRequestLegacy:
6099 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6105 description: Video file
6108 VideoUploadRequestResumable:
6110 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6116 description: Video filename including extension
6119 example: what_is_peertube.mp4
6121 description: Video thumbnail file
6125 description: Video preview file
6128 VideoUploadResponse:
6134 $ref: '#/components/schemas/Video/properties/id'
6136 $ref: '#/components/schemas/Video/properties/uuid'
6137 CommentThreadResponse:
6146 $ref: '#/components/schemas/VideoComment'
6147 CommentThreadPostResponse:
6150 $ref: '#/components/schemas/VideoComment'
6160 $ref: '#/components/schemas/Video'
6164 $ref: '#/components/schemas/Account'
6167 description: Automatically start playing the upcoming video after the currently playing video
6168 autoPlayNextVideoPlaylist:
6170 description: Automatically start playing the video on the playlist after the currently playing video
6173 description: Automatically start playing the video on the watch page
6183 description: The user email
6186 description: Has the user confirmed their email address?
6189 - $ref: '#/components/schemas/id'
6193 description: Auth plugin to use to authenticate the user
6197 noInstanceConfigWarningModal:
6202 $ref: '#/components/schemas/NSFWPolicy'
6204 $ref: '#/components/schemas/UserRole'
6213 description: Theme enabled by this user
6215 $ref: '#/components/schemas/username'
6219 $ref: '#/components/schemas/VideoChannel'
6222 description: The user video quota in bytes
6226 description: The user daily video quota in bytes
6230 description: Enable P2P in the player
6233 - $ref: '#/components/schemas/User'
6235 # optionally present fields: they require WITH_STATS scope
6238 description: Count of videos published
6241 description: Count of reports/abuses of which the user is a target
6242 abusesAcceptedCount:
6244 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6247 description: Count of reports/abuses created by the user
6250 description: Count of comments published
6254 $ref: '#/components/schemas/username'
6256 $ref: '#/components/schemas/password'
6260 description: The user email
6263 description: The user video quota in bytes
6267 description: The user daily video quota in bytes
6270 $ref: '#/components/schemas/usernameChannel'
6272 $ref: '#/components/schemas/UserRole'
6274 $ref: '#/components/schemas/UserAdminFlags'
6285 description: The updated email of the user
6287 - $ref: '#/components/schemas/User/properties/email'
6290 description: Set the email as verified
6293 description: The updated video quota of the user in bytes
6296 description: The updated daily video quota of the user in bytes
6300 description: The auth plugin to use to authenticate the user
6301 example: 'peertube-plugin-auth-saml2'
6303 $ref: '#/components/schemas/UserRole'
6305 $ref: '#/components/schemas/UserAdminFlags'
6307 # see shared/models/users/user-update-me.model.ts:
6310 $ref: '#/components/schemas/password'
6312 $ref: '#/components/schemas/password'
6314 description: new email used for login and service communications
6316 - $ref: '#/components/schemas/User/properties/email'
6319 description: new name of the user in its representations
6324 description: new NSFW display policy
6331 description: whether to enable P2P in the player or not
6334 description: new preference regarding playing videos automatically
6337 description: new preference regarding playing following videos automatically
6338 autoPlayNextVideoPlaylist:
6340 description: new preference regarding playing following playlist videos automatically
6341 videosHistoryEnabled:
6343 description: whether to keep track of watched history or not
6348 description: list of languages to filter videos down to
6351 noInstanceConfigWarningModal:
6358 $ref: '#/components/schemas/id'
6365 description: Rating of the video
6372 $ref: '#/components/schemas/Video'
6379 description: Rating of the video
6386 description: immutable name of the user, used to find or mention its actor
6388 - $ref: '#/components/schemas/username'
6390 $ref: '#/components/schemas/password'
6394 description: email of the user, used for login or service communications
6397 description: editable name of the user, displayed in its representations
6402 description: channel base information used to create the first channel of the user
6405 $ref: '#/components/schemas/usernameChannel'
6407 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6417 pattern: /^[a-z0-9]$/
6420 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6423 pattern: /^[a-zA-Z0-9]$/
6426 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6427 OAuthToken-password:
6429 - $ref: '#/components/schemas/OAuthClient'
6439 $ref: '#/components/schemas/User/properties/username'
6441 $ref: '#/components/schemas/password'
6448 OAuthToken-refresh_token:
6450 - $ref: '#/components/schemas/OAuthClient'
6461 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6470 # GET/POST/PUT properties
6473 description: editable name of the channel, displayed in its representations
6474 example: Videos of Framasoft
6479 example: Videos made with <3 by Framasoft
6484 description: text shown by default on all videos of this channel, to tell the audience how to support it
6485 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6488 # GET-only properties
6492 - $ref: '#/components/schemas/id'
6508 $ref: '#/components/schemas/UUIDv4'
6511 - $ref: '#/components/schemas/VideoChannel'
6514 description: username of the channel to create
6516 - $ref: '#/components/schemas/usernameChannel'
6522 - $ref: '#/components/schemas/VideoChannel'
6524 bulkVideosSupportUpdate:
6526 description: Update the support field for all videos of this channel
6536 - $ref: '#/components/schemas/VideoChannel'
6537 - $ref: '#/components/schemas/Actor'
6542 name: 'media:peerLink'
6551 - application/x-bittorrent
6557 name: 'media:content'
6588 VideoCommentsForXML:
6623 description: video watch page URL
6626 description: video canonical URL
6630 description: video publication date
6633 description: video description
6636 description: video description
6639 description: publisher user name
6642 description: video category (MRSS)
6645 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6660 description: video embed path, relative to the canonical URL domain (MRSS)
6669 description: video watch path, relative to the canonical URL domain (MRSS)
6690 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6691 'media:description':
6698 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6701 description: main streamable file for the video
6711 - application/x-bittorrent
6720 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)
6723 - $ref: '#/components/schemas/MRSSPeerLink'
6724 - $ref: '#/components/schemas/MRSSGroupContent'
6725 NotificationSettingValue:
6742 $ref: '#/components/schemas/id'
6746 Notification type, following the `UserNotificationType` enum:
6748 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6750 - `2` NEW_COMMENT_ON_MY_VIDEO
6752 - `3` NEW_ABUSE_FOR_MODERATORS
6754 - `4` BLACKLIST_ON_MY_VIDEO
6756 - `5` UNBLACKLIST_ON_MY_VIDEO
6758 - `6` MY_VIDEO_PUBLISHED
6760 - `7` MY_VIDEO_IMPORT_SUCCESS
6762 - `8` MY_VIDEO_IMPORT_ERROR
6764 - `9` NEW_USER_REGISTRATION
6768 - `11` COMMENT_MENTION
6770 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6772 - `13` NEW_INSTANCE_FOLLOWER
6774 - `14` AUTO_INSTANCE_FOLLOWING
6780 - $ref: '#/components/schemas/VideoInfo'
6784 $ref: '#/components/schemas/ActorInfo'
6790 $ref: '#/components/schemas/id'
6793 $ref: '#/components/schemas/VideoInfo'
6798 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6808 $ref: '#/components/schemas/id'
6812 $ref: '#/components/schemas/VideoInfo'
6814 $ref: '#/components/schemas/ActorInfo'
6820 $ref: '#/components/schemas/id'
6823 - $ref: '#/components/schemas/VideoInfo'
6829 $ref: '#/components/schemas/id'
6832 - $ref: '#/components/schemas/VideoInfo'
6836 - $ref: '#/components/schemas/ActorInfo'
6842 $ref: '#/components/schemas/id'
6844 $ref: '#/components/schemas/ActorInfo'
6872 NotificationListResponse:
6881 $ref: '#/components/schemas/Notification'
6886 example: peertube-plugin-auth-ldap
6914 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6917 additionalProperties: true
6933 $ref: '#/components/schemas/Plugin'
6940 description: User can stream multiple times in a permanent live
6949 description: RTMP stream key to use to stream into this live video
6953 description: User can stream multiple times in a permanent live
6960 'https://search.example.org/api/v1/search/videos':
6962 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6965 description: successful operation
6969 $ref: '#/components/schemas/VideoListResponse'