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 with 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/createUser) 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
306 - $ref: '#/components/parameters/name'
309 description: successful operation
313 $ref: '#/components/schemas/Account'
315 description: account not found
316 '/accounts/{name}/videos':
321 summary: 'List videos of an account'
323 - $ref: '#/components/parameters/name'
324 - $ref: '#/components/parameters/categoryOneOf'
325 - $ref: '#/components/parameters/isLive'
326 - $ref: '#/components/parameters/tagsOneOf'
327 - $ref: '#/components/parameters/tagsAllOf'
328 - $ref: '#/components/parameters/licenceOneOf'
329 - $ref: '#/components/parameters/languageOneOf'
330 - $ref: '#/components/parameters/nsfw'
331 - $ref: '#/components/parameters/filter'
332 - $ref: '#/components/parameters/skipCount'
333 - $ref: '#/components/parameters/start'
334 - $ref: '#/components/parameters/count'
335 - $ref: '#/components/parameters/videosSort'
338 description: successful operation
342 $ref: '#/components/schemas/VideoListResponse'
346 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
347 .then(function(response) {
348 return response.json()
349 }).then(function(data) {
355 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
361 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
363 http = Net::HTTP.new(uri.host, uri.port)
366 response = http.get(uri.request_uri)
368 puts JSON.parse(response.read_body)
373 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
381 summary: List accounts
383 - $ref: '#/components/parameters/start'
384 - $ref: '#/components/parameters/count'
385 - $ref: '#/components/parameters/sort'
388 description: successful operation
394 $ref: '#/components/schemas/Account'
399 summary: Get instance public configuration
402 description: successful operation
406 $ref: '#/components/schemas/ServerConfig'
409 externalValue: https://peertube2.cpy.re/api/v1/config
412 summary: Get instance "About" information
417 description: successful operation
421 $ref: '#/components/schemas/ServerConfigAbout'
424 externalValue: https://peertube2.cpy.re/api/v1/config/about
427 summary: Get instance runtime configuration
435 description: successful operation
439 $ref: '#/components/schemas/ServerConfigCustom'
441 summary: Set instance runtime configuration
449 description: successful operation
451 x-summary: field inconsistencies
454 - the emailer is disabled and the instance is open to registrations
455 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
457 summary: Delete instance runtime configuration
465 description: successful operation
468 summary: List instance jobs
478 description: The state of the job ('' for for no filter)
488 - $ref: '#/components/parameters/jobType'
489 - $ref: '#/components/parameters/start'
490 - $ref: '#/components/parameters/count'
491 - $ref: '#/components/parameters/sort'
494 description: successful operation
507 $ref: '#/components/schemas/Job'
513 summary: List instances following the server
515 - $ref: '#/components/parameters/followState'
516 - $ref: '#/components/parameters/actorType'
517 - $ref: '#/components/parameters/start'
518 - $ref: '#/components/parameters/count'
519 - $ref: '#/components/parameters/sort'
522 description: successful operation
534 $ref: '#/components/schemas/Follow'
535 '/server/followers/{nameWithHost}':
537 summary: Remove or reject a follower to your server
547 description: The remote actor handle to remove from your followers
553 description: successful operation
555 description: follower not found
556 '/server/followers/{nameWithHost}/reject':
558 summary: Reject a pending follower to your server
568 description: The remote actor handle to remove from your followers
574 description: successful operation
576 description: follower not found
577 '/server/followers/{nameWithHost}/accept':
579 summary: Accept a pending follower to your server
589 description: The remote actor handle to remove from your followers
595 description: successful operation
597 description: follower not found
603 summary: List instances followed by the server
605 - $ref: '#/components/parameters/followState'
606 - $ref: '#/components/parameters/actorType'
607 - $ref: '#/components/parameters/start'
608 - $ref: '#/components/parameters/count'
609 - $ref: '#/components/parameters/sort'
612 description: successful operation
624 $ref: '#/components/schemas/Follow'
631 summary: Follow a list of servers
634 description: successful operation
636 description: cannot follow a non-HTTPS server
649 '/server/following/{host}':
651 summary: Unfollow a server
661 description: The host to unfollow
667 description: successful operation
669 description: host not found
673 summary: Create a user
674 operationId: createUser
682 description: user created
686 $ref: '#/components/schemas/AddUserResponse'
690 operationId: getUserId
692 id: '$response.body#/user/id'
695 operationId: putUserId
697 id: '$response.body#/user/id'
700 operationId: delUserId
702 id: '$response.body#/user/id'
704 description: insufficient authority to create an admin or moderator
709 $ref: '#/components/schemas/AddUser'
711 If the smtp server is configured, you can leave the password empty and an email will be sent
712 asking the user to set it first.
722 - $ref: '#/components/parameters/usersSearch'
723 - $ref: '#/components/parameters/usersBlocked'
724 - $ref: '#/components/parameters/start'
725 - $ref: '#/components/parameters/count'
726 - $ref: '#/components/parameters/usersSort'
729 description: successful operation
735 $ref: '#/components/schemas/User'
738 - $ref: '#/components/parameters/id'
740 summary: Delete a user
746 operationId: delUserId
749 description: successful operation
756 operationId: getUserId
760 description: include statistics about the user (only available as a moderator/admin)
765 x-summary: successful operation
767 As an admin/moderator, you can request a response augmented with statistics about the user's
768 moderation relations and videos usage, by using the `withStats` parameter.
773 - $ref: '#/components/schemas/User'
774 - $ref: '#/components/schemas/UserWithStats'
776 summary: Update a user
781 operationId: putUserId
784 description: successful operation
789 $ref: '#/components/schemas/UpdateUser'
792 /oauth-clients/local:
794 summary: Login prerequisite
795 description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken).
796 operationId: getOAuthClient
801 description: successful operation
805 $ref: '#/components/schemas/OAuthClient'
807 UseOAuthClientToLogin:
808 operationId: getOAuthToken
810 client_id: '$response.body#/client_id'
811 client_secret: '$response.body#/client_secret'
815 API="https://peertube2.cpy.re/api/v1"
818 curl -s "$API/oauth-clients/local"
822 operationId: getOAuthToken
823 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
828 application/x-www-form-urlencoded:
831 - $ref: '#/components/schemas/OAuthToken-password'
832 - $ref: '#/components/schemas/OAuthToken-refresh_token'
834 propertyName: grant_type
836 password: '#/components/schemas/OAuthToken-password'
837 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
840 description: successful operation
851 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
852 description: valid for 1 day
855 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
856 description: valid for 2 weeks
861 refresh_token_expires_in:
869 API="https://peertube2.cpy.re/api/v1"
870 USERNAME="<your_username>"
871 PASSWORD="<your_password>"
874 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
875 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
876 curl -s "$API/users/token" \
877 --data client_id="$client_id" \
878 --data client_secret="$client_secret" \
879 --data grant_type=password \
880 --data username="$USERNAME" \
881 --data password="$PASSWORD" \
882 | jq -r ".access_token"
886 description: Revokes your access token and its associated refresh token, destroying your current session.
887 operationId: revokeOAuthToken
894 description: successful operation
898 summary: Register a user
904 description: successful operation
909 $ref: '#/components/schemas/RegisterUser'
911 /users/{id}/verify-email:
913 summary: Verify a user
915 Following a user registration, the new user will receive an email asking to click a link
921 - $ref: '#/components/parameters/id'
937 description: successful operation
939 description: invalid verification string
941 description: user not found
942 /users/ask-send-verify-email:
944 summary: Resend user verification link
950 description: successful operation
954 summary: Get my user information
962 description: successful operation
968 $ref: '#/components/schemas/User'
970 summary: Update my user information
978 description: successful operation
983 $ref: '#/components/schemas/UpdateMe'
985 /users/me/videos/imports:
987 summary: Get video imports of my user
995 - $ref: '#/components/parameters/start'
996 - $ref: '#/components/parameters/count'
997 - $ref: '#/components/parameters/sort'
1000 description: successful operation
1004 $ref: '#/components/schemas/VideoImportsList'
1005 /users/me/video-quota-used:
1007 summary: Get my user used quota
1015 description: successful operation
1023 description: The user video quota used so far in bytes
1024 example: 16810141515
1025 videoQuotaUsedDaily:
1027 description: The user video quota used today in bytes
1029 '/users/me/videos/{videoId}/rating':
1031 summary: Get rate of my user for a video
1041 description: The video id
1043 $ref: '#/components/schemas/Video/properties/id'
1046 description: successful operation
1050 $ref: '#/components/schemas/GetMeVideoRating'
1053 summary: Get videos of my user
1061 - $ref: '#/components/parameters/start'
1062 - $ref: '#/components/parameters/count'
1063 - $ref: '#/components/parameters/sort'
1066 description: successful operation
1070 $ref: '#/components/schemas/VideoListResponse'
1071 /users/me/subscriptions:
1073 summary: Get my user subscriptions
1080 - $ref: '#/components/parameters/start'
1081 - $ref: '#/components/parameters/count'
1082 - $ref: '#/components/parameters/sort'
1085 description: successful operation
1089 $ref: '#/components/schemas/VideoChannelList'
1093 summary: Add subscription to my user
1106 description: uri of the video channels to subscribe to
1112 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1115 description: successful operation
1116 /users/me/subscriptions/exist:
1118 summary: Get if subscriptions exist for my user
1125 - $ref: '#/components/parameters/subscriptionsUris'
1128 description: successful operation
1133 /users/me/subscriptions/videos:
1135 summary: List videos of subscriptions of my user
1143 - $ref: '#/components/parameters/categoryOneOf'
1144 - $ref: '#/components/parameters/isLive'
1145 - $ref: '#/components/parameters/tagsOneOf'
1146 - $ref: '#/components/parameters/tagsAllOf'
1147 - $ref: '#/components/parameters/licenceOneOf'
1148 - $ref: '#/components/parameters/languageOneOf'
1149 - $ref: '#/components/parameters/nsfw'
1150 - $ref: '#/components/parameters/filter'
1151 - $ref: '#/components/parameters/skipCount'
1152 - $ref: '#/components/parameters/start'
1153 - $ref: '#/components/parameters/count'
1154 - $ref: '#/components/parameters/videosSort'
1157 description: successful operation
1161 $ref: '#/components/schemas/VideoListResponse'
1162 '/users/me/subscriptions/{subscriptionHandle}':
1164 summary: Get subscription of my user
1171 - $ref: '#/components/parameters/subscriptionHandle'
1174 description: successful operation
1178 $ref: '#/components/schemas/VideoChannel'
1180 summary: Delete subscription of my user
1187 - $ref: '#/components/parameters/subscriptionHandle'
1190 description: successful operation
1191 /users/me/notifications:
1193 summary: List my notifications
1201 description: only list unread notifications
1204 - $ref: '#/components/parameters/start'
1205 - $ref: '#/components/parameters/count'
1206 - $ref: '#/components/parameters/sort'
1209 description: successful operation
1213 $ref: '#/components/schemas/NotificationListResponse'
1214 /users/me/notifications/read:
1216 summary: Mark notifications as read by their id
1229 description: ids of the notifications to mark as read
1236 description: successful operation
1237 /users/me/notifications/read-all:
1239 summary: Mark all my notification as read
1246 description: successful operation
1247 /users/me/notification-settings:
1249 summary: Update my notification settings
1260 newVideoFromSubscription:
1261 $ref: '#/components/schemas/NotificationSettingValue'
1262 newCommentOnMyVideo:
1263 $ref: '#/components/schemas/NotificationSettingValue'
1265 $ref: '#/components/schemas/NotificationSettingValue'
1266 videoAutoBlacklistAsModerator:
1267 $ref: '#/components/schemas/NotificationSettingValue'
1269 $ref: '#/components/schemas/NotificationSettingValue'
1271 $ref: '#/components/schemas/NotificationSettingValue'
1272 myVideoImportFinished:
1273 $ref: '#/components/schemas/NotificationSettingValue'
1275 $ref: '#/components/schemas/NotificationSettingValue'
1276 newUserRegistration:
1277 $ref: '#/components/schemas/NotificationSettingValue'
1279 $ref: '#/components/schemas/NotificationSettingValue'
1280 newInstanceFollower:
1281 $ref: '#/components/schemas/NotificationSettingValue'
1282 autoInstanceFollowing:
1283 $ref: '#/components/schemas/NotificationSettingValue'
1286 description: successful operation
1287 /users/me/history/videos:
1289 summary: List watched videos history
1295 - $ref: '#/components/parameters/start'
1296 - $ref: '#/components/parameters/count'
1297 - $ref: '#/components/parameters/search'
1300 description: successful operation
1304 $ref: '#/components/schemas/VideoListResponse'
1305 /users/me/history/videos/remove:
1307 summary: Clear video history
1314 multipart/form-data:
1319 description: history before this date will be deleted
1324 description: successful operation
1325 /users/me/avatar/pick:
1327 summary: Update my user avatar
1334 description: successful operation
1341 $ref: '#/components/schemas/ActorImage'
1343 description: image file too large
1345 X-File-Maximum-Size:
1349 description: Maximum file size for the avatar
1352 multipart/form-data:
1357 description: The file to upload
1362 contentType: image/png, image/jpeg
1365 summary: Delete my avatar
1372 description: successful operation
1376 summary: List video ownership changes
1378 - Video Ownership Change
1383 description: successful operation
1384 '/videos/ownership/{id}/accept':
1386 summary: Accept ownership change request
1388 - Video Ownership Change
1392 - $ref: '#/components/parameters/idOrUUID'
1395 description: successful operation
1397 description: cannot terminate an ownership change of another user
1399 description: video owneship change not found
1400 '/videos/ownership/{id}/refuse':
1402 summary: Refuse ownership change request
1404 - Video Ownership Change
1408 - $ref: '#/components/parameters/idOrUUID'
1411 description: successful operation
1413 description: cannot terminate an ownership change of another user
1415 description: video owneship change not found
1416 '/videos/{id}/give-ownership':
1418 summary: Request ownership change
1420 - Video Ownership Change
1424 - $ref: '#/components/parameters/idOrUUID'
1428 application/x-www-form-urlencoded:
1438 description: successful operation
1440 description: changing video ownership to a remote account is not supported yet
1442 description: video not found
1445 summary: List videos
1449 - $ref: '#/components/parameters/categoryOneOf'
1450 - $ref: '#/components/parameters/isLive'
1451 - $ref: '#/components/parameters/tagsOneOf'
1452 - $ref: '#/components/parameters/tagsAllOf'
1453 - $ref: '#/components/parameters/licenceOneOf'
1454 - $ref: '#/components/parameters/languageOneOf'
1455 - $ref: '#/components/parameters/nsfw'
1456 - $ref: '#/components/parameters/filter'
1457 - $ref: '#/components/parameters/skipCount'
1458 - $ref: '#/components/parameters/start'
1459 - $ref: '#/components/parameters/count'
1460 - $ref: '#/components/parameters/videosSort'
1463 description: successful operation
1467 $ref: '#/components/schemas/VideoListResponse'
1470 summary: List available video categories
1471 operationId: getCategories
1476 description: successful operation
1485 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1488 summary: List available video licences
1489 operationId: getLicences
1494 description: successful operation
1503 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1506 summary: List available video languages
1507 operationId: getLanguages
1512 description: successful operation
1521 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1524 summary: List available video privacy policies
1525 operationId: getPrivacyPolicies
1530 description: successful operation
1539 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1542 summary: Update a video
1548 - $ref: '#/components/parameters/idOrUUID'
1551 description: successful operation
1554 multipart/form-data:
1559 description: Video thumbnail file
1563 description: Video preview file
1567 $ref: '#/components/schemas/VideoCategorySet'
1569 $ref: '#/components/schemas/VideoLicenceSet'
1571 $ref: '#/components/schemas/VideoLanguageSet'
1573 $ref: '#/components/schemas/VideoPrivacySet'
1575 description: Video description
1578 description: Whether or not we wait transcoding before publish the video
1581 description: A text tell the audience how to support the video creator
1582 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1585 description: Whether or not this video contains sensitive content
1588 description: Video name
1593 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1602 description: Enable or disable comments for this video
1604 originallyPublishedAt:
1605 description: Date when the content was originally published
1609 $ref: '#/components/schemas/VideoScheduledUpdate'
1612 contentType: image/jpeg
1614 contentType: image/jpeg
1616 summary: Get a video
1620 - $ref: '#/components/parameters/idOrUUID'
1623 description: successful operation
1627 $ref: '#/components/schemas/VideoDetails'
1629 summary: Delete a video
1635 - $ref: '#/components/parameters/idOrUUID'
1638 description: successful operation
1639 '/videos/{id}/description':
1641 summary: Get complete video description
1645 - $ref: '#/components/parameters/idOrUUID'
1648 description: successful operation
1657 **[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)**
1658 '/videos/{id}/views':
1660 summary: Add a view to a video
1664 - $ref: '#/components/parameters/idOrUUID'
1667 description: successful operation
1668 '/videos/{id}/watching':
1670 summary: Set watching progress of a video
1676 - $ref: '#/components/parameters/idOrUUID'
1681 $ref: '#/components/schemas/UserWatchingVideo'
1685 description: successful operation
1688 summary: Upload a video
1689 description: Uses a single request to upload a video.
1690 operationId: uploadLegacy
1698 description: successful operation
1702 $ref: '#/components/schemas/VideoUploadResponse'
1704 description: invalid file field, schedule date or parameter
1706 description: video didn't pass upload filter
1708 description: upload has timed out
1710 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1712 X-File-Maximum-Size:
1716 description: Maximum file size for the video
1718 description: video type unsupported
1720 description: video unreadable
1723 multipart/form-data:
1725 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1728 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1730 contentType: image/jpeg
1732 contentType: image/jpeg
1737 USERNAME="<your_username>"
1738 PASSWORD="<your_password>"
1739 FILE_PATH="<your_file_path>"
1740 CHANNEL_ID="<your_channel_id>"
1742 API="https://peertube2.cpy.re/api/v1"
1745 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1746 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1747 token=$(curl -s "$API/users/token" \
1748 --data client_id="$client_id" \
1749 --data client_secret="$client_secret" \
1750 --data grant_type=password \
1751 --data username="$USERNAME" \
1752 --data password="$PASSWORD" \
1753 | jq -r ".access_token")
1756 curl -s "$API/videos/upload" \
1757 -H "Authorization: Bearer $token" \
1759 --form videofile=@"$FILE_PATH" \
1760 --form channelId=$CHANNEL_ID \
1762 /videos/upload-resumable:
1764 summary: Initialize the resumable upload of a video
1765 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1766 operationId: uploadResumableInit
1773 - name: X-Upload-Content-Length
1779 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1780 - name: X-Upload-Content-Type
1787 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1792 $ref: '#/components/schemas/VideoUploadRequestResumable'
1795 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1797 description: created
1803 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1809 description: invalid file field, schedule date or parameter
1811 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1813 description: video type unsupported
1815 summary: Send chunk for the resumable upload of a video
1816 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
1817 operationId: uploadResumable
1828 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1829 not valid anymore and you need to initialize a new upload.
1832 - name: Content-Range
1836 example: bytes 0-262143/2469036
1839 Specifies the bytes in the file that the request is uploading.
1841 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1842 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1843 - name: Content-Length
1850 Size of the chunk that the request is sending.
1852 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)
1853 doesn't mandate for chunks to have the same size throughout the upload sequence.
1855 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1856 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1859 application/octet-stream:
1865 description: last chunk received
1873 $ref: '#/components/schemas/VideoUploadResponse'
1875 description: resume incomplete
1880 example: bytes=0-262143
1886 description: video didn't pass upload filter
1888 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1890 description: video unreadable
1892 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1893 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1894 operationId: uploadResumableCancel
1905 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1906 not valid anymore and the upload session has already been deleted with its data ;-)
1909 - name: Content-Length
1917 description: upload cancelled
1925 summary: Import a video
1926 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1927 operationId: importVideo
1935 multipart/form-data:
1937 $ref: '#/components/schemas/VideoCreateImport'
1940 contentType: application/x-bittorrent
1942 contentType: image/jpeg
1944 contentType: image/jpeg
1947 description: successful operation
1951 $ref: '#/components/schemas/VideoUploadResponse'
1953 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1955 description: video didn't pass pre-import filter
1957 description: HTTP or Torrent/magnetURI import not enabled
1961 summary: Create a live
1962 operationId: createLive
1970 description: successful operation
1974 $ref: '#/components/schemas/VideoUploadResponse'
1976 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
1979 multipart/form-data:
1984 description: Channel id that will contain this live video
1989 description: User can stream multiple times in a permanent live
1992 description: Live video/replay thumbnail file
1996 description: Live video/replay preview file
2000 $ref: '#/components/schemas/VideoPrivacySet'
2002 $ref: '#/components/schemas/VideoCategorySet'
2004 $ref: '#/components/schemas/VideoLicenceSet'
2006 $ref: '#/components/schemas/VideoLanguageSet'
2008 description: Live video/replay description
2011 description: A text tell the audience how to support the creator
2012 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2015 description: Whether or not this live video/replay contains sensitive content
2018 description: Live video/replay name
2023 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2032 description: Enable or disable comments for this live video/replay
2035 description: Enable or disable downloading for the replay of this live
2042 contentType: image/jpeg
2044 contentType: image/jpeg
2048 summary: Get information about a live
2049 operationId: getLiveId
2056 - $ref: '#/components/parameters/idOrUUID'
2059 description: successful operation
2063 $ref: '#/components/schemas/LiveVideoResponse'
2065 summary: Update information about a live
2066 operationId: updateLiveId
2073 - $ref: '#/components/parameters/idOrUUID'
2078 $ref: '#/components/schemas/LiveVideoUpdate'
2081 description: successful operation
2083 description: bad parameters or trying to update a live that has already started
2085 description: trying to save replay of the live but saving replay is not enabled on the instance
2089 summary: List my abuses
2090 operationId: getMyAbuses
2099 description: only list the report with this id
2105 $ref: '#/components/schemas/AbuseStateSet'
2106 - $ref: '#/components/parameters/abusesSort'
2107 - $ref: '#/components/parameters/start'
2108 - $ref: '#/components/parameters/count'
2111 description: successful operation
2123 $ref: '#/components/schemas/Abuse'
2127 summary: List abuses
2128 operationId: getAbuses
2138 description: only list the report with this id
2141 - name: predefinedReason
2143 description: predefined reason the listed reports should contain
2145 $ref: '#/components/schemas/PredefinedAbuseReasons'
2148 description: plain search that will match with video titles, reporter names and more
2154 $ref: '#/components/schemas/AbuseStateSet'
2155 - name: searchReporter
2157 description: only list reports of a specific reporter
2160 - name: searchReportee
2161 description: only list reports of a specific reportee
2167 description: only list reports of a specific video
2170 - name: searchVideoChannel
2172 description: only list reports of a specific video channel
2177 description: only list blacklisted or deleted videos
2185 description: only list account, comment or video reports
2192 - $ref: '#/components/parameters/start'
2193 - $ref: '#/components/parameters/count'
2194 - $ref: '#/components/parameters/abusesSort'
2197 description: successful operation
2209 $ref: '#/components/schemas/Abuse'
2212 summary: Report an abuse
2225 description: Reason why the user reports this video
2230 $ref: '#/components/schemas/PredefinedAbuseReasons'
2235 description: Video id to report
2237 - $ref: '#/components/schemas/Video/properties/id'
2241 description: Timestamp in the video that marks the beginning of the report
2246 description: Timestamp in the video that marks the ending of the report
2252 description: Comment id to report
2254 - $ref: '#/components/schemas/VideoComment/properties/id'
2259 description: Account id to report
2265 description: successful operation
2275 $ref: '#/components/schemas/id'
2277 description: incorrect request parameters
2278 '/abuses/{abuseId}':
2280 summary: Update an abuse
2288 - $ref: '#/components/parameters/abuseId'
2296 $ref: '#/components/schemas/AbuseStateSet'
2299 description: Update the report comment visible only to the moderation team
2304 description: successful operation
2306 description: abuse not found
2310 summary: Delete an abuse
2316 - $ref: '#/components/parameters/abuseId'
2319 description: successful operation
2321 description: block not found
2322 '/abuses/{abuseId}/messages':
2324 summary: List messages of an abuse
2330 - $ref: '#/components/parameters/abuseId'
2333 description: successful operation
2345 $ref: '#/components/schemas/AbuseMessage'
2348 summary: Add message to an abuse
2354 - $ref: '#/components/parameters/abuseId'
2363 description: Message to send
2371 description: successful operation
2373 description: incorrect request parameters
2374 '/abuses/{abuseId}/messages/{abuseMessageId}':
2376 summary: Delete an abuse message
2382 - $ref: '#/components/parameters/abuseId'
2383 - $ref: '#/components/parameters/abuseMessageId'
2386 description: successful operation
2388 '/videos/{id}/blacklist':
2390 summary: Block a video
2398 - $ref: '#/components/parameters/idOrUUID'
2401 description: successful operation
2403 summary: Unblock a video by its id
2411 - $ref: '#/components/parameters/idOrUUID'
2414 description: successful operation
2416 description: block not found
2421 summary: List video blocks
2430 list only blocks that match this type:
2434 - `2`: automatic block that needs review
2442 description: plain search that will match with video titles, and more
2445 - $ref: '#/components/parameters/start'
2446 - $ref: '#/components/parameters/count'
2447 - $ref: '#/components/parameters/blacklistsSort'
2450 description: successful operation
2462 $ref: '#/components/schemas/VideoBlacklist'
2463 /videos/{id}/captions:
2465 summary: List captions of a video
2469 - $ref: '#/components/parameters/idOrUUID'
2472 description: successful operation
2484 $ref: '#/components/schemas/VideoCaption'
2485 /videos/{id}/captions/{captionLanguage}:
2487 summary: Add or replace a video caption
2494 - $ref: '#/components/parameters/idOrUUID'
2495 - $ref: '#/components/parameters/captionLanguage'
2498 multipart/form-data:
2503 description: The file to upload.
2508 contentType: text/vtt, application/x-subrip, text/plain
2511 description: successful operation
2513 description: video or language not found
2515 summary: Delete a video caption
2522 - $ref: '#/components/parameters/idOrUUID'
2523 - $ref: '#/components/parameters/captionLanguage'
2526 description: successful operation
2528 description: video or language or caption for that language not found
2531 summary: List video channels
2532 operationId: getVideoChannels
2536 - $ref: '#/components/parameters/start'
2537 - $ref: '#/components/parameters/count'
2538 - $ref: '#/components/parameters/sort'
2541 description: successful operation
2545 $ref: '#/components/schemas/VideoChannelList'
2547 summary: Create a video channel
2548 operationId: createVideoChannel
2555 description: successful operation
2565 $ref: '#/components/schemas/VideoChannel/properties/id'
2570 $ref: '#/components/schemas/VideoChannelCreate'
2571 '/video-channels/{channelHandle}':
2573 summary: Get a video channel
2574 operationId: getVideoChannel
2578 - $ref: '#/components/parameters/channelHandle'
2581 description: successful operation
2585 $ref: '#/components/schemas/VideoChannel'
2587 summary: Update a video channel
2593 - $ref: '#/components/parameters/channelHandle'
2596 description: successful operation
2601 $ref: '#/components/schemas/VideoChannelUpdate'
2603 summary: Delete a video channel
2609 - $ref: '#/components/parameters/channelHandle'
2612 description: successful operation
2613 '/video-channels/{channelHandle}/videos':
2615 summary: List videos of a video channel
2620 - $ref: '#/components/parameters/channelHandle'
2621 - $ref: '#/components/parameters/categoryOneOf'
2622 - $ref: '#/components/parameters/isLive'
2623 - $ref: '#/components/parameters/tagsOneOf'
2624 - $ref: '#/components/parameters/tagsAllOf'
2625 - $ref: '#/components/parameters/licenceOneOf'
2626 - $ref: '#/components/parameters/languageOneOf'
2627 - $ref: '#/components/parameters/nsfw'
2628 - $ref: '#/components/parameters/filter'
2629 - $ref: '#/components/parameters/skipCount'
2630 - $ref: '#/components/parameters/start'
2631 - $ref: '#/components/parameters/count'
2632 - $ref: '#/components/parameters/videosSort'
2635 description: successful operation
2639 $ref: '#/components/schemas/VideoListResponse'
2640 '/video-channels/{channelHandle}/avatar/pick':
2642 summary: Update channel avatar
2648 - $ref: '#/components/parameters/channelHandle'
2651 description: successful operation
2658 $ref: '#/components/schemas/ActorImage'
2660 description: image file too large
2662 X-File-Maximum-Size:
2666 description: Maximum file size for the avatar
2669 multipart/form-data:
2674 description: The file to upload.
2679 contentType: image/png, image/jpeg
2680 '/video-channels/{channelHandle}/avatar':
2682 summary: Delete channel avatar
2688 - $ref: '#/components/parameters/channelHandle'
2691 description: successful operation
2694 '/video-channels/{channelHandle}/banner/pick':
2696 summary: Update channel banner
2702 - $ref: '#/components/parameters/channelHandle'
2705 description: successful operation
2712 $ref: '#/components/schemas/ActorImage'
2714 description: image file too large
2716 X-File-Maximum-Size:
2720 description: Maximum file size for the banner
2723 multipart/form-data:
2728 description: The file to upload.
2733 contentType: image/png, image/jpeg
2734 '/video-channels/{channelHandle}/banner':
2736 summary: Delete channel banner
2742 - $ref: '#/components/parameters/channelHandle'
2745 description: successful operation
2747 /video-playlists/privacies:
2749 summary: List available playlist privacy policies
2750 operationId: getPlaylistPrivacyPolicies
2755 description: successful operation
2764 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2768 summary: List video playlists
2769 operationId: getPlaylists
2773 - $ref: '#/components/parameters/start'
2774 - $ref: '#/components/parameters/count'
2775 - $ref: '#/components/parameters/sort'
2778 description: successful operation
2790 $ref: '#/components/schemas/VideoPlaylist'
2792 summary: Create a video playlist
2793 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2794 operationId: createPlaylist
2801 description: successful operation
2811 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2813 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2816 multipart/form-data:
2821 description: Video playlist display name
2826 description: Video playlist thumbnail file
2830 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2832 description: Video playlist description
2838 - $ref: '#/components/schemas/id'
2839 description: Video channel in which the playlist will be published
2844 contentType: image/jpeg
2846 /video-playlists/{playlistId}:
2848 summary: Get a video playlist
2852 - $ref: '#/components/parameters/playlistId'
2855 description: successful operation
2859 $ref: '#/components/schemas/VideoPlaylist'
2861 summary: Update a video playlist
2862 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2869 description: successful operation
2871 - $ref: '#/components/parameters/playlistId'
2874 multipart/form-data:
2879 description: Video playlist display name
2884 description: Video playlist thumbnail file
2888 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2890 description: Video playlist description
2894 - $ref: '#/components/schemas/id'
2895 description: Video channel in which the playlist will be published
2898 contentType: image/jpeg
2900 summary: Delete a video playlist
2906 - $ref: '#/components/parameters/playlistId'
2909 description: successful operation
2911 /video-playlists/{playlistId}/videos:
2913 summary: 'List videos of a playlist'
2918 - $ref: '#/components/parameters/playlistId'
2921 description: successful operation
2925 $ref: '#/components/schemas/VideoListResponse'
2927 summary: Add a video in a playlist
2934 - $ref: '#/components/parameters/playlistId'
2937 description: successful operation
2943 videoPlaylistElement:
2957 - $ref: '#/components/schemas/Video/properties/uuid'
2958 - $ref: '#/components/schemas/Video/properties/id'
2959 description: Video to add in the playlist
2963 description: Start the video at this specific timestamp
2967 description: Stop the video at this specific timestamp
2971 /video-playlists/{playlistId}/videos/reorder:
2973 summary: 'Reorder a playlist'
2979 - $ref: '#/components/parameters/playlistId'
2982 description: successful operation
2991 description: 'Start position of the element to reorder'
2993 insertAfterPosition:
2995 description: 'New position for the block to reorder, to add the block before the first element'
2999 description: 'How many element from `startPosition` to reorder'
3003 - insertAfterPosition
3005 /video-playlists/{playlistId}/videos/{playlistElementId}:
3007 summary: Update a playlist element
3013 - $ref: '#/components/parameters/playlistId'
3014 - $ref: '#/components/parameters/playlistElementId'
3017 description: successful operation
3027 description: Start the video at this specific timestamp
3031 description: Stop the video at this specific timestamp
3033 summary: Delete an element from a playlist
3039 - $ref: '#/components/parameters/playlistId'
3040 - $ref: '#/components/parameters/playlistElementId'
3043 description: successful operation
3045 '/users/me/video-playlists/videos-exist':
3047 summary: Check video exists in my playlists
3056 description: The video ids to check
3060 $ref: '#/components/schemas/Video/properties/id'
3063 description: successful operation
3085 '/accounts/{name}/video-channels':
3087 summary: List video channels of an account
3092 - $ref: '#/components/parameters/name'
3095 description: include view statistics for the last 30 days (only if authentified as the account user)
3098 - $ref: '#/components/parameters/start'
3099 - $ref: '#/components/parameters/count'
3100 - $ref: '#/components/parameters/sort'
3103 description: successful operation
3107 $ref: '#/components/schemas/VideoChannelList'
3108 '/accounts/{name}/ratings':
3110 summary: List ratings of an account
3116 - $ref: '#/components/parameters/name'
3117 - $ref: '#/components/parameters/start'
3118 - $ref: '#/components/parameters/count'
3119 - $ref: '#/components/parameters/sort'
3123 description: Optionally filter which ratings to retrieve
3131 description: successful operation
3137 $ref: '#/components/schemas/VideoRating'
3138 '/videos/{id}/comment-threads':
3140 summary: List threads of a video
3144 - $ref: '#/components/parameters/idOrUUID'
3145 - $ref: '#/components/parameters/start'
3146 - $ref: '#/components/parameters/count'
3147 - $ref: '#/components/parameters/commentsSort'
3150 description: successful operation
3154 $ref: '#/components/schemas/CommentThreadResponse'
3156 summary: Create a thread
3162 - $ref: '#/components/parameters/idOrUUID'
3165 description: successful operation
3169 $ref: '#/components/schemas/CommentThreadPostResponse'
3171 description: video does not exist
3180 - $ref: '#/components/schemas/VideoComment/properties/text'
3186 '/videos/{id}/comment-threads/{threadId}':
3188 summary: Get a thread
3192 - $ref: '#/components/parameters/idOrUUID'
3193 - $ref: '#/components/parameters/threadId'
3196 description: successful operation
3200 $ref: '#/components/schemas/VideoCommentThreadTree'
3201 '/videos/{id}/comments/{commentId}':
3203 summary: Reply to a thread of a video
3209 - $ref: '#/components/parameters/idOrUUID'
3210 - $ref: '#/components/parameters/commentId'
3213 description: successful operation
3217 $ref: '#/components/schemas/CommentThreadPostResponse'
3219 description: thread or video does not exist
3228 - $ref: '#/components/schemas/VideoComment/properties/text'
3235 summary: Delete a comment or a reply
3241 - $ref: '#/components/parameters/idOrUUID'
3242 - $ref: '#/components/parameters/commentId'
3245 description: successful operation
3247 description: cannot remove comment of another user
3249 description: comment or video does not exist
3251 description: comment is already deleted
3252 '/videos/{id}/rate':
3254 summary: Like/dislike a video
3260 - $ref: '#/components/parameters/idOrUUID'
3276 description: successful operation
3278 description: video does not exist
3283 summary: Search videos
3288 allowEmptyValue: false
3290 String to search. If the user can make a remote URI search, and the string is an URI then the
3291 PeerTube instance will fetch the remote object and add it to its database. Then,
3292 you can use the REST API to fetch the complete video information and interact with it.
3295 - $ref: '#/components/parameters/categoryOneOf'
3296 - $ref: '#/components/parameters/isLive'
3297 - $ref: '#/components/parameters/tagsOneOf'
3298 - $ref: '#/components/parameters/tagsAllOf'
3299 - $ref: '#/components/parameters/licenceOneOf'
3300 - $ref: '#/components/parameters/languageOneOf'
3301 - $ref: '#/components/parameters/nsfw'
3302 - $ref: '#/components/parameters/filter'
3303 - $ref: '#/components/parameters/skipCount'
3304 - $ref: '#/components/parameters/start'
3305 - $ref: '#/components/parameters/count'
3306 - $ref: '#/components/parameters/searchTarget'
3307 - $ref: '#/components/parameters/videosSearchSort'
3310 description: Get videos that are published after this date
3316 description: Get videos that are published before this date
3320 - name: originallyPublishedStartDate
3322 description: Get videos that are originally published after this date
3326 - name: originallyPublishedEndDate
3328 description: Get videos that are originally published before this date
3334 description: Get videos that have this minimum duration
3339 description: Get videos that have this maximum duration
3343 'searchTarget === search-index':
3344 $ref: '#/components/callbacks/searchIndex'
3347 description: successful operation
3351 $ref: '#/components/schemas/VideoListResponse'
3353 description: search index unavailable
3354 /search/video-channels:
3358 summary: Search channels
3364 String to search. If the user can make a remote URI search, and the string is an URI then the
3365 PeerTube instance will fetch the remote object and add it to its database. Then,
3366 you can use the REST API to fetch the complete channel information and interact with it.
3369 - $ref: '#/components/parameters/start'
3370 - $ref: '#/components/parameters/count'
3371 - $ref: '#/components/parameters/searchTarget'
3372 - $ref: '#/components/parameters/sort'
3374 'searchTarget === search-index':
3375 $ref: '#/components/callbacks/searchIndex'
3378 description: successful operation
3382 $ref: '#/components/schemas/VideoChannelList'
3384 description: search index unavailable
3386 /server/blocklist/accounts:
3390 summary: List account blocks
3395 - $ref: '#/components/parameters/start'
3396 - $ref: '#/components/parameters/count'
3397 - $ref: '#/components/parameters/sort'
3400 description: successful operation
3404 summary: Block an account
3416 example: chocobozzz@example.org
3417 description: account to block, in the form `username@domain`
3422 description: successful operation
3424 description: self-blocking forbidden
3425 '/server/blocklist/accounts/{accountName}':
3429 summary: Unblock an account by its handle
3437 description: account to unblock, in the form `username@domain`
3442 description: successful operation
3444 description: account or account block does not exist
3446 /server/blocklist/servers:
3450 summary: List server blocks
3455 - $ref: '#/components/parameters/start'
3456 - $ref: '#/components/parameters/count'
3457 - $ref: '#/components/parameters/sort'
3460 description: successful operation
3464 summary: Block a server
3477 description: server domain to block
3482 description: successful operation
3484 description: self-blocking forbidden
3485 '/server/blocklist/servers/{host}':
3489 summary: Unblock a server by its domain
3497 description: server domain to unblock
3503 description: successful operation
3505 description: account block does not exist
3507 /server/redundancy/{host}:
3510 - Instance Redundancy
3511 summary: Update a server redundancy policy
3519 description: server domain to mirror
3531 description: allow mirroring of the host's local videos
3536 description: successful operation
3538 description: server is not already known
3539 /server/redundancy/videos:
3543 summary: List videos being mirrored
3551 description: direction of the mirror
3557 - $ref: '#/components/parameters/start'
3558 - $ref: '#/components/parameters/count'
3559 - $ref: '#/components/parameters/videoRedundanciesSort'
3562 description: successful operation
3568 $ref: '#/components/schemas/VideoRedundancy'
3572 summary: Mirror a video
3583 $ref: '#/components/schemas/Video/properties/id'
3588 description: successful operation
3590 description: cannot mirror a local video
3592 description: video does not exist
3594 description: video is already mirrored
3595 /server/redundancy/videos/{redundancyId}:
3599 summary: Delete a mirror done on a video
3604 - name: redundancyId
3607 description: id of an existing redundancy on a video
3612 description: successful operation
3614 description: video redundancy not found
3616 '/feeds/video-comments.{format}':
3620 summary: List comments on videos
3625 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3638 description: 'limit listing to a specific video'
3643 description: 'limit listing to a specific account'
3648 description: 'limit listing to a specific account'
3651 - name: videoChannelId
3653 description: 'limit listing to a specific video channel'
3656 - name: videoChannelName
3658 description: 'limit listing to a specific video channel'
3663 description: successful operation
3668 default: 'max-age=900' # 15 min cache
3672 $ref: '#/components/schemas/VideoCommentsForXML'
3675 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3676 application/rss+xml:
3678 $ref: '#/components/schemas/VideoCommentsForXML'
3681 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3684 $ref: '#/components/schemas/VideoCommentsForXML'
3687 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3688 application/atom+xml:
3690 $ref: '#/components/schemas/VideoCommentsForXML'
3693 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3699 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3701 x-summary: field inconsistencies
3704 - videoId filter is mixed with a channel filter
3706 description: video, video channel or account not found
3708 description: accept header unsupported
3709 '/feeds/videos.{format}':
3713 summary: List videos
3718 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3731 description: 'limit listing to a specific account'
3736 description: 'limit listing to a specific account'
3739 - name: videoChannelId
3741 description: 'limit listing to a specific video channel'
3744 - name: videoChannelName
3746 description: 'limit listing to a specific video channel'
3749 - $ref: '#/components/parameters/sort'
3750 - $ref: '#/components/parameters/nsfw'
3751 - $ref: '#/components/parameters/filter'
3754 description: successful operation
3759 default: 'max-age=900' # 15 min cache
3763 $ref: '#/components/schemas/VideosForXML'
3766 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3767 application/rss+xml:
3769 $ref: '#/components/schemas/VideosForXML'
3772 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3775 $ref: '#/components/schemas/VideosForXML'
3778 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3779 application/atom+xml:
3781 $ref: '#/components/schemas/VideosForXML'
3784 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3790 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3792 description: video channel or account not found
3794 description: accept header unsupported
3795 '/feeds/subscriptions.{format}':
3800 summary: List videos of subscriptions tied to a token
3805 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3818 description: limit listing to a specific account
3824 description: private token allowing access
3828 - $ref: '#/components/parameters/sort'
3829 - $ref: '#/components/parameters/nsfw'
3830 - $ref: '#/components/parameters/filter'
3833 description: successful operation
3838 default: 'max-age=900' # 15 min cache
3842 $ref: '#/components/schemas/VideosForXML'
3843 application/rss+xml:
3845 $ref: '#/components/schemas/VideosForXML'
3848 $ref: '#/components/schemas/VideosForXML'
3849 application/atom+xml:
3851 $ref: '#/components/schemas/VideosForXML'
3856 description: accept header unsupported
3861 summary: List plugins
3874 - $ref: '#/components/parameters/start'
3875 - $ref: '#/components/parameters/count'
3876 - $ref: '#/components/parameters/sort'
3879 description: successful operation
3883 $ref: '#/components/schemas/PluginResponse'
3888 summary: List available plugins
3901 - name: currentPeerTubeEngine
3905 - $ref: '#/components/parameters/start'
3906 - $ref: '#/components/parameters/count'
3907 - $ref: '#/components/parameters/sort'
3910 description: successful operation
3914 $ref: '#/components/schemas/PluginResponse'
3916 description: plugin index unavailable
3921 summary: Install a plugin
3934 example: peertube-plugin-auth-ldap
3937 additionalProperties: false
3944 additionalProperties: false
3947 description: successful operation
3949 description: should have either `npmName` or `path` set
3954 summary: Update a plugin
3967 example: peertube-plugin-auth-ldap
3970 additionalProperties: false
3977 additionalProperties: false
3980 description: successful operation
3982 description: should have either `npmName` or `path` set
3984 description: existing plugin not found
3989 summary: Uninstall a plugin
4001 description: name of the plugin/theme in its package.json
4002 example: peertube-plugin-auth-ldap
4007 description: successful operation
4009 description: existing plugin not found
4014 summary: Get a plugin
4019 - $ref: '#/components/parameters/npmName'
4022 description: successful operation
4026 $ref: '#/components/schemas/Plugin'
4028 description: plugin not found
4029 /plugins/{npmName}/settings:
4033 summary: Set a plugin's settings
4038 - $ref: '#/components/parameters/npmName'
4047 additionalProperties: true
4050 description: successful operation
4052 description: plugin not found
4053 /plugins/{npmName}/public-settings:
4057 summary: Get a plugin's public settings
4059 - $ref: '#/components/parameters/npmName'
4062 description: successful operation
4067 additionalProperties: true
4069 description: plugin not found
4070 /plugins/{npmName}/registered-settings:
4074 summary: Get a plugin's registered settings
4079 - $ref: '#/components/parameters/npmName'
4082 description: successful operation
4087 additionalProperties: true
4089 description: plugin not found
4091 - url: 'https://peertube2.cpy.re/api/v1'
4092 description: Live Test Server (live data - latest nightly version)
4093 - url: 'https://peertube3.cpy.re/api/v1'
4094 description: Live Test Server (live data - latest RC version)
4095 - url: 'https://peertube.cpy.re/api/v1'
4096 description: Live Test Server (live data - stable version)
4103 description: Offset used to paginate results
4111 description: "Number of items to return"
4121 description: Sort column
4129 description: Plain text search, applied to various parts of the model depending on endpoint
4137 If the administrator enabled search index support, you can override the default search target.
4140 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4141 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4142 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4143 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4144 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4145 * 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
4146 the data from the origin instance API
4156 description: Sort videos by criteria
4172 description: Sort videos by criteria
4187 description: Sort comments by criteria
4197 description: Sort blacklists by criteria
4213 description: Plain text search that will match with user usernames or emails
4220 description: Filter results down to (un)banned users
4227 description: Sort users by criteria
4238 description: Sort abuses by criteria
4245 videoRedundanciesSort:
4249 description: Sort abuses by criteria
4258 description: The username or handle of the account
4261 example: chocobozzz | chocobozzz@example.org
4266 description: The user id
4268 $ref: '#/components/schemas/id'
4273 description: The object id or uuid
4276 - $ref: '#/components/schemas/id'
4277 - $ref: '#/components/schemas/UUIDv4'
4282 description: Playlist id
4284 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4286 name: playlistElementId
4289 description: Playlist element id
4291 $ref: '#/components/schemas/id'
4296 description: Abuse id
4298 $ref: '#/components/schemas/Abuse/properties/id'
4300 name: abuseMessageId
4303 description: Abuse message id
4305 $ref: '#/components/schemas/AbuseMessage/properties/id'
4307 name: captionLanguage
4310 description: The caption language
4312 $ref: '#/components/schemas/VideoLanguageSet'
4317 description: The video channel handle
4320 example: my_username | my_username@example.com
4322 name: subscriptionHandle
4325 description: The subscription handle
4328 example: my_username | my_username@example.com
4333 description: The thread id (root comment id)
4335 $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
4340 description: The comment id
4342 $ref: '#/components/schemas/VideoComment/properties/id'
4347 description: whether or not the video is a live
4354 description: category id of the video (see [/videos/categories](#operation/getCategories))
4357 - $ref: '#/components/schemas/VideoCategorySet'
4360 $ref: '#/components/schemas/VideoCategorySet'
4367 description: tag(s) of the video
4381 description: tag(s) of the video, where all should be present in the video
4394 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4397 - $ref: '#/components/schemas/VideoLanguageSet'
4400 $ref: '#/components/schemas/VideoLanguageSet'
4407 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4410 - $ref: '#/components/schemas/VideoLicenceSet'
4413 $ref: '#/components/schemas/VideoLicenceSet'
4420 description: if you don't need the `total` in the response
4431 description: whether to include nsfw videos, if any
4442 Special filters which might require special rights:
4443 * `local` - only videos local to the instance
4444 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4445 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4455 description: list of uris to check if each is part of the user subscriptions
4465 description: name of the plugin/theme on npmjs.com or in its package.json
4468 example: peertube-plugin-auth-ldap
4473 description: job type
4477 - activitypub-follow
4478 - activitypub-http-broadcast
4479 - activitypub-http-fetcher
4480 - activitypub-http-unicast
4486 - activitypub-refresher
4511 Authenticating via OAuth requires the following steps:
4512 - Have an activated account
4513 - [Generate] an access token for that account at `/api/v1/users/token`.
4514 - Make requests with the *Authorization: Bearer <token\>* header
4515 - Profit, depending on the role assigned to the account
4517 Note that the __access token is valid for 1 day__ and is given
4518 along with a __refresh token valid for 2 weeks__.
4520 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4524 tokenUrl: /api/v1/users/token
4527 moderator: Moderator scope
4530 # Resuable core properties
4538 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4539 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4544 description: immutable name of the user, used to find or mention its actor
4546 pattern: '/^[a-z0-9._]+$/'
4551 description: immutable name of the channel, used to interact with its actor
4552 example: framasoft_videos
4553 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4564 description: category id of the video (see [/videos/categories](#operation/getCategories))
4566 VideoConstantNumber-Category:
4569 $ref: '#/components/schemas/VideoCategorySet'
4572 example: Science & Technology
4576 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4578 VideoConstantNumber-Licence:
4581 $ref: '#/components/schemas/VideoLicenceSet'
4584 example: Attribution - Share Alike
4588 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4590 VideoConstantString-Language:
4593 $ref: '#/components/schemas/VideoLanguageSet'
4598 VideoPlaylistPrivacySet:
4604 description: Video playlist privacy policy (see [/video-playlists/privacies])
4605 VideoPlaylistPrivacyConstant:
4608 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4612 VideoPlaylistTypeSet:
4617 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4618 VideoPlaylistTypeConstant:
4621 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4632 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4633 VideoPrivacyConstant:
4636 $ref: '#/components/schemas/VideoPrivacySet'
4653 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4660 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4671 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4681 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4685 $ref: '#/components/schemas/AbuseStateSet'
4688 AbusePredefinedReasons:
4701 example: [spamOrMisleading]
4706 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4708 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4710 VideoResolutionConstant:
4711 description: resolutions and their labels for the video
4714 $ref: '#/components/schemas/VideoResolutionSet'
4718 VideoScheduledUpdate:
4721 $ref: '#/components/schemas/VideoPrivacySet'
4725 description: When to update the video
4745 - $ref: '#/components/schemas/ActorImage'
4746 VideoChannelSummary:
4749 $ref: '#/components/schemas/id'
4763 - $ref: '#/components/schemas/ActorImage'
4777 - $ref: '#/components/schemas/Video'
4784 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4785 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
4786 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4788 $ref: '#/components/schemas/VideoResolutionConstant'
4791 description: Video file size in bytes
4794 description: Direct URL of the torrent file
4798 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4802 description: Direct URL of the video
4806 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4810 description: Frames per second of the video file
4814 description: URL dereferencing the output of ffprobe on the file
4815 VideoStreamingPlaylists:
4820 $ref: '#/components/schemas/id'
4828 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4829 VideoStreamingPlaylists-HLS:
4840 Video files associated to this playlist.
4842 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4844 $ref: '#/components/schemas/VideoFile'
4856 $ref: '#/components/schemas/Video/properties/id'
4858 $ref: '#/components/schemas/Video/properties/uuid'
4860 $ref: '#/components/schemas/Video/properties/name'
4864 description: object id for the video
4866 - $ref: '#/components/schemas/id'
4868 description: universal identifier for the video, that can be used across instances
4870 - $ref: '#/components/schemas/UUIDv4'
4876 example: 2017-10-01T10:52:46.396Z
4877 description: time at which the video object was first drafted
4881 example: 2018-10-01T10:52:46.396Z
4882 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4886 example: 2021-05-04T08:01:01.502Z
4887 description: last time the video's metadata was modified
4888 originallyPublishedAt:
4891 example: 2010-10-01T10:52:46.396Z
4892 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4895 - $ref: '#/components/schemas/VideoConstantNumber-Category'
4896 description: category in which the video is classified
4899 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
4900 description: licence under which the video is distributed
4903 - $ref: '#/components/schemas/VideoConstantString-Language'
4904 description: main language used in the video
4907 - $ref: '#/components/schemas/VideoPrivacyConstant'
4908 description: privacy policy used to distribute the video
4912 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4913 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4917 truncated description of the video, written in Markdown.
4918 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4923 description: duration of the video in seconds
4928 description: title of the video
4929 example: What is PeerTube?
4934 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4937 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4940 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4957 - $ref: '#/components/schemas/VideoStateConstant'
4958 description: represents the internal state of the video processing within the PeerTube instance
4962 - $ref: '#/components/schemas/VideoScheduledUpdate'
4970 $ref: '#/components/schemas/AccountSummary'
4972 $ref: '#/components/schemas/VideoChannelSummary'
4981 - $ref: '#/components/schemas/Video'
4986 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4987 description: path at which to get the full description of maximum `10000` characters
4990 description: A text tell the audience how to support the video creator
4991 example: Please support our work on https://soutenir.framasoft.org/en/ <3
4995 $ref: '#/components/schemas/VideoChannel'
4997 $ref: '#/components/schemas/Account'
4999 example: [flowers, gardening]
5017 - https://peertube2.cpy.re/tracker/announce
5018 - wss://peertube2.cpy.re/tracker/socket
5022 $ref: '#/components/schemas/VideoFile'
5024 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5026 - field will be empty
5027 - video files will be found in `streamingPlaylists[].files` field
5031 $ref: '#/components/schemas/VideoStreamingPlaylists'
5033 HLS playlists/manifest files. If HLS is disabled on the server:
5035 - field will be empty
5036 - video files will be found in `files` field
5037 FileRedundancyInformation:
5040 $ref: '#/components/schemas/id'
5065 $ref: '#/components/schemas/id'
5072 $ref: '#/components/schemas/UUIDv4'
5079 $ref: '#/components/schemas/FileRedundancyInformation'
5083 $ref: '#/components/schemas/FileRedundancyInformation'
5084 VideoImportStateConstant:
5092 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5099 additionalProperties: false
5103 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5104 required: [targetUrl]
5107 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5108 required: [magnetUri]
5111 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5112 required: [torrentfile]
5113 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5122 - $ref: '#/components/schemas/id'
5126 description: remote URL where to find the import's source video
5127 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5131 description: magnet URI allowing to resolve the import's source video
5132 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
5133 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5138 description: Torrent file containing only the video file
5145 - $ref: '#/components/schemas/VideoImportStateConstant'
5161 - $ref: '#/components/schemas/Video'
5171 $ref: '#/components/schemas/VideoImport'
5175 $ref: '#/components/schemas/id'
5178 example: The video is a spam
5182 $ref: '#/components/schemas/AbusePredefinedReasons'
5184 $ref: '#/components/schemas/Account'
5186 $ref: '#/components/schemas/AbuseStateConstant'
5189 example: Decided to ban the server since it spams us regularly
5193 $ref: '#/components/schemas/VideoInfo'
5200 $ref: '#/components/schemas/id'
5211 $ref: '#/components/schemas/AccountSummary'
5215 $ref: '#/components/schemas/id'
5217 $ref: '#/components/schemas/Video/properties/id'
5229 $ref: '#/components/schemas/UUIDv4'
5247 $ref: '#/components/schemas/id'
5249 $ref: '#/components/schemas/UUIDv4'
5272 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5274 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5276 $ref: '#/components/schemas/AccountSummary'
5278 $ref: '#/components/schemas/VideoChannelSummary'
5282 $ref: '#/components/schemas/id'
5289 description: Text of the comment
5291 example: This video is wonderful!
5293 $ref: '#/components/schemas/id'
5297 - $ref: '#/components/schemas/id'
5299 $ref: '#/components/schemas/Video/properties/id'
5314 totalRepliesFromVideoAuthor:
5321 $ref: '#/components/schemas/Account'
5322 VideoCommentThreadTree:
5325 $ref: '#/components/schemas/VideoComment'
5329 $ref: '#/components/schemas/VideoCommentThreadTree'
5333 $ref: '#/components/schemas/VideoConstantString-Language'
5349 $ref: '#/components/schemas/id'
5366 $ref: '#/components/schemas/id'
5371 description: immutable name of the actor, used to find or mention it
5373 - $ref: '#/components/schemas/username'
5377 description: server on which the actor is resident
5378 hostRedundancyAllowed:
5380 description: whether this actor's host allows redundancy of its videos
5384 description: number of actors subscribed to by this actor, as seen by this instance
5388 description: number of followers of this actor, as seen by this instance
5396 $ref: '#/components/schemas/ActorImage'
5399 - $ref: '#/components/schemas/Actor'
5402 description: object id for the user tied to this account
5404 - $ref: '#/components/schemas/User/properties/id'
5407 description: editable name of the account, displayed in its representations
5412 description: text or bio displayed on the account's profile
5418 description: timestamp within the video, in seconds
5485 allowedForCurrentIP:
5487 requiresEmailVerification:
5505 $ref: '#/components/schemas/VideoResolutionSet'
5590 example: 16810141515
5693 requiresEmailVerification:
5708 description: Settings that apply to new users, if registration is enabled
5712 example: 16810141515
5718 description: Settings pertaining to transcoding jobs
5722 allowAdditionalExtensions:
5724 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5727 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5730 description: Amount of threads used by ffmpeg for 1 transcoding job
5733 description: Amount of transcoding jobs to execute in parallel
5739 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5742 description: Resolutions to transcode _new videos_ to
5762 description: WebTorrent-specific settings
5768 description: HLS-specific settings
5812 $ref: '#/components/schemas/id'
5814 $ref: '#/components/schemas/Actor'
5816 $ref: '#/components/schemas/Actor'
5819 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5832 PredefinedAbuseReasons:
5833 description: Reason categories that help triage reports
5851 $ref: '#/components/schemas/id'
5863 - activitypub-http-unicast
5864 - activitypub-http-broadcast
5865 - activitypub-http-fetcher
5866 - activitypub-follow
5872 - activitypub-refresher
5876 additionalProperties: true
5879 additionalProperties: true
5895 $ref: '#/components/schemas/id'
5900 $ref: '#/components/schemas/id'
5901 VideoUploadRequestCommon:
5904 description: Video name
5906 example: What is PeerTube?
5910 description: Channel id that will contain this video
5915 $ref: '#/components/schemas/VideoPrivacySet'
5917 $ref: '#/components/schemas/VideoCategorySet'
5919 $ref: '#/components/schemas/VideoLicenceSet'
5921 $ref: '#/components/schemas/VideoLanguageSet'
5923 description: Video description
5926 **[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)**
5928 description: Whether or not we wait transcoding before publish the video
5931 description: A text tell the audience how to support the video creator
5932 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5935 description: Whether or not this video contains sensitive content
5938 description: Video tags (maximum 5 tags each between 2 and 30 characters)
5951 description: Enable or disable comments for this video
5954 description: Enable or disable downloading for this video
5956 originallyPublishedAt:
5957 description: Date when the content was originally published
5961 $ref: '#/components/schemas/VideoScheduledUpdate'
5963 description: Video thumbnail file
5967 description: Video preview file
5973 VideoUploadRequestLegacy:
5975 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5981 description: Video file
5984 VideoUploadRequestResumable:
5986 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5992 description: Video filename including extension
5995 example: what_is_peertube.mp4
5997 description: Video thumbnail file
6001 description: Video preview file
6004 VideoUploadResponse:
6010 $ref: '#/components/schemas/Video/properties/id'
6012 $ref: '#/components/schemas/Video/properties/uuid'
6013 CommentThreadResponse:
6022 $ref: '#/components/schemas/VideoComment'
6023 CommentThreadPostResponse:
6026 $ref: '#/components/schemas/VideoComment'
6036 $ref: '#/components/schemas/Video'
6040 $ref: '#/components/schemas/Account'
6043 description: Automatically start playing the upcoming video after the currently playing video
6044 autoPlayNextVideoPlaylist:
6046 description: Automatically start playing the video on the playlist after the currently playing video
6049 description: Automatically start playing the video on the watch page
6059 description: The user email
6062 description: Has the user confirmed their email address?
6065 - $ref: '#/components/schemas/id'
6069 description: Auth plugin to use to authenticate the user
6073 noInstanceConfigWarningModal:
6078 $ref: '#/components/schemas/NSFWPolicy'
6080 $ref: '#/components/schemas/UserRole'
6089 description: Theme enabled by this user
6091 $ref: '#/components/schemas/username'
6095 $ref: '#/components/schemas/VideoChannel'
6098 description: The user video quota in bytes
6102 description: The user daily video quota in bytes
6106 description: Enable P2P in the player
6109 - $ref: '#/components/schemas/User'
6111 # optionally present fields: they require WITH_STATS scope
6114 description: Count of videos published
6117 description: Count of reports/abuses of which the user is a target
6118 abusesAcceptedCount:
6120 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6123 description: Count of reports/abuses created by the user
6126 description: Count of comments published
6130 $ref: '#/components/schemas/username'
6132 $ref: '#/components/schemas/password'
6136 description: The user email
6139 description: The user video quota in bytes
6143 description: The user daily video quota in bytes
6146 $ref: '#/components/schemas/usernameChannel'
6148 $ref: '#/components/schemas/UserRole'
6150 $ref: '#/components/schemas/UserAdminFlags'
6161 description: The updated email of the user
6163 - $ref: '#/components/schemas/User/properties/email'
6166 description: Set the email as verified
6169 description: The updated video quota of the user in bytes
6172 description: The updated daily video quota of the user in bytes
6176 description: The auth plugin to use to authenticate the user
6177 example: 'peertube-plugin-auth-saml2'
6179 $ref: '#/components/schemas/UserRole'
6181 $ref: '#/components/schemas/UserAdminFlags'
6183 # see shared/models/users/user-update-me.model.ts:
6186 $ref: '#/components/schemas/password'
6188 $ref: '#/components/schemas/password'
6190 description: new email used for login and service communications
6192 - $ref: '#/components/schemas/User/properties/email'
6195 description: new name of the user in its representations
6200 description: new NSFW display policy
6207 description: whether to enable P2P in the player or not
6210 description: new preference regarding playing videos automatically
6213 description: new preference regarding playing following videos automatically
6214 autoPlayNextVideoPlaylist:
6216 description: new preference regarding playing following playlist videos automatically
6217 videosHistoryEnabled:
6219 description: whether to keep track of watched history or not
6224 description: list of languages to filter videos down to
6227 noInstanceConfigWarningModal:
6234 $ref: '#/components/schemas/id'
6241 description: Rating of the video
6248 $ref: '#/components/schemas/Video'
6255 description: Rating of the video
6262 description: immutable name of the user, used to find or mention its actor
6264 - $ref: '#/components/schemas/username'
6266 $ref: '#/components/schemas/password'
6270 description: email of the user, used for login or service communications
6273 description: editable name of the user, displayed in its representations
6278 description: channel base information used to create the first channel of the user
6281 $ref: '#/components/schemas/usernameChannel'
6283 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6293 pattern: /^[a-z0-9]$/
6296 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6299 pattern: /^[a-zA-Z0-9]$/
6302 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6303 OAuthToken-password:
6305 - $ref: '#/components/schemas/OAuthClient'
6315 $ref: '#/components/schemas/User/properties/username'
6317 $ref: '#/components/schemas/password'
6324 OAuthToken-refresh_token:
6326 - $ref: '#/components/schemas/OAuthClient'
6337 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6346 # GET/POST/PUT properties
6349 description: editable name of the channel, displayed in its representations
6350 example: Videos of Framasoft
6355 example: Videos made with <3 by Framasoft
6360 description: text shown by default on all videos of this channel, to tell the audience how to support it
6361 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6364 # GET-only properties
6368 - $ref: '#/components/schemas/id'
6384 $ref: '#/components/schemas/UUIDv4'
6387 - $ref: '#/components/schemas/VideoChannel'
6390 description: username of the channel to create
6392 - $ref: '#/components/schemas/usernameChannel'
6398 - $ref: '#/components/schemas/VideoChannel'
6400 bulkVideosSupportUpdate:
6402 description: Update the support field for all videos of this channel
6412 - $ref: '#/components/schemas/VideoChannel'
6413 - $ref: '#/components/schemas/Actor'
6418 name: 'media:peerLink'
6427 - application/x-bittorrent
6433 name: 'media:content'
6464 VideoCommentsForXML:
6499 description: video watch page URL
6502 description: video canonical URL
6506 description: video publication date
6509 description: video description
6512 description: video description
6515 description: publisher user name
6518 description: video category (MRSS)
6521 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6536 description: video embed path, relative to the canonical URL domain (MRSS)
6545 description: video watch path, relative to the canonical URL domain (MRSS)
6566 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6567 'media:description':
6574 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6577 description: main streamable file for the video
6587 - application/x-bittorrent
6596 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)
6599 - $ref: '#/components/schemas/MRSSPeerLink'
6600 - $ref: '#/components/schemas/MRSSGroupContent'
6601 NotificationSettingValue:
6618 $ref: '#/components/schemas/id'
6622 Notification type, following the `UserNotificationType` enum:
6624 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6626 - `2` NEW_COMMENT_ON_MY_VIDEO
6628 - `3` NEW_ABUSE_FOR_MODERATORS
6630 - `4` BLACKLIST_ON_MY_VIDEO
6632 - `5` UNBLACKLIST_ON_MY_VIDEO
6634 - `6` MY_VIDEO_PUBLISHED
6636 - `7` MY_VIDEO_IMPORT_SUCCESS
6638 - `8` MY_VIDEO_IMPORT_ERROR
6640 - `9` NEW_USER_REGISTRATION
6644 - `11` COMMENT_MENTION
6646 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6648 - `13` NEW_INSTANCE_FOLLOWER
6650 - `14` AUTO_INSTANCE_FOLLOWING
6656 - $ref: '#/components/schemas/VideoInfo'
6660 $ref: '#/components/schemas/ActorInfo'
6666 $ref: '#/components/schemas/id'
6669 $ref: '#/components/schemas/VideoInfo'
6674 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6684 $ref: '#/components/schemas/id'
6688 $ref: '#/components/schemas/VideoInfo'
6690 $ref: '#/components/schemas/ActorInfo'
6696 $ref: '#/components/schemas/id'
6699 - $ref: '#/components/schemas/VideoInfo'
6705 $ref: '#/components/schemas/id'
6708 - $ref: '#/components/schemas/VideoInfo'
6712 - $ref: '#/components/schemas/ActorInfo'
6718 $ref: '#/components/schemas/id'
6720 $ref: '#/components/schemas/ActorInfo'
6748 NotificationListResponse:
6757 $ref: '#/components/schemas/Notification'
6762 example: peertube-plugin-auth-ldap
6790 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6793 additionalProperties: true
6809 $ref: '#/components/schemas/Plugin'
6816 description: User can stream multiple times in a permanent live
6825 description: RTMP stream key to use to stream into this live video
6829 description: User can stream multiple times in a permanent live
6836 'https://search.example.org/api/v1/search/videos':
6838 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6841 description: successful operation
6845 $ref: '#/components/schemas/VideoListResponse'