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
41 of the API call. The body of the response will be JSON in the following
46 "error": "Account not found" // error debug message
50 Validation errors benefit from a more detailed error type and return the HTTP `400 Bad Request` status code.
55 "id": { // where 'id' is the name of the parameter concerned by the error.
56 "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error.
57 "msg": "Should have an valid id", // error debug message
59 "location": "params" // 'params', 'body', 'header', 'query' or 'cookies'
67 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
69 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
70 |------------------------------|---------------|--------------|
71 | `/*` | 50 | 10 seconds |
72 | `POST /users/token` | 15 | 5 minutes |
73 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
74 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
76 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
77 limit is announced by a `429 Too Many Requests` status code.
79 You can get details about the current state of your rate limit by reading the
82 | Header | Description |
83 |-------------------------|------------------------------------------------------------|
84 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
85 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
86 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
87 | `Retry-After` | Seconds to delay after the first `429` is received |
91 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
92 allowing cross-domain communication from the browser for some routes:
95 |------------------------- ---|
99 | `/live/segments-sha256/*` |
100 | `/.well-known/webfinger` |
102 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
104 url: https://docs.joinpeertube.org/api-rest-reference.html
108 As a visitor, you can use this API to open an account (if registrations are open on
109 that PeerTube instance). As an admin, you should use the dedicated [User creation
110 API](#operation/createUser) instead.
112 x-displayName: Login/Logout
114 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
117 Accounts encompass remote accounts discovered across the federation,
118 and correspond to the main Actor, along with video channels a user can create, which
121 When a comment is posted, it is done with your Account's Actor.
124 Using some features of PeerTube require authentication, for which User
125 provide different levels of permission as well as associated user
126 information. Each user has a corresponding local Account for federation.
129 Operations related to your own User, when logged-in.
130 - name: My Subscriptions
132 Operations related to your subscriptions to video channels, their
133 new videos, and how to keep up to date with their latest publications!
136 Operations related to your watch history.
137 - name: My Notifications
139 Notifications following new videos, follows or reports. They allow you
140 to keep track of the interactions and overall important information that
141 concerns you. You MAY set per-notification type delivery preference, to
142 receive the info either by mail, by in-browser notification or both.
145 Each server exposes public information regarding supported videos and
149 Jobs are long-running tasks enqueued and processed by the instance
150 itself. No additional worker registration is currently available.
151 - name: Instance Follows
153 Managing servers which the instance interacts with is crucial to the
154 concept of federation in PeerTube and external video indexation. The PeerTube
155 server then deals with inter-server ActivityPub operations and propagates
156 information across its social graph by posting activities to actors' inbox
159 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
160 - name: Instance Redundancy
162 Redundancy is part of the inter-server solidarity that PeerTube fosters.
163 Manage the list of instances you wish to help by seeding their videos according
164 to the policy of video selection of your choice. Note that you have a similar functionality
165 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
167 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
170 Managing plugins installed from a local path or from NPM, or search for new ones.
172 url: https://docs.joinpeertube.org/api-plugins
175 Abuses deal with reports of local or remote videos/comments/accounts alike.
178 Operations dealing with listing, uploading, fetching or modifying videos.
181 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
185 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
186 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
188 You can upload videos more reliably by using the resumable variant. Its protocol lets
189 you resume an upload operation after a network interruption or other transmission failure,
190 saving time and bandwidth in the event of network failures.
192 Favor using resumable uploads in any of the following cases:
193 - You are transferring large files
194 - The likelihood of a network interruption is high
195 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
196 such as a mobile device
200 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
201 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
202 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
204 The import function is practical when the desired video/audio is available online. It makes PeerTube
205 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
206 - name: Video Captions
207 description: Operations dealing with listing, adding and removing closed captions of a video.
208 - name: Video Channels
209 description: Operations dealing with the creation, modification and listing of videos within a channel.
210 - name: Video Comments
212 Operations dealing with comments to a video. Comments are organized in threads: adding a
213 comment in response to the video starts a thread, adding a reply to a comment adds it to
214 its root comment thread.
216 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
218 description: Like/dislike a video.
219 - name: Video Playlists
220 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
222 description: Server syndication feeds
225 The search helps to find _videos_ or _channels_ from within the instance and beyond.
226 Videos from other instances federated by the instance (that is, instances
227 followed by the instance) can be found via keywords and other criteria of
230 Administrators can also enable the use of a remote search system, indexing
231 videos and channels not could be not federated by the instance.
232 - name: Video Mirroring
234 PeerTube instances can mirror videos from one another, and help distribute some videos.
236 For importing videos as your own, refer to [video imports](#operation/importVideo).
259 - Video Ownership Change
272 - name: Instance Configuration
276 - Instance Redundancy
286 summary: Get an account
288 - $ref: '#/components/parameters/name'
291 description: successful operation
295 $ref: '#/components/schemas/Account'
297 description: account not found
298 '/accounts/{name}/videos':
303 summary: 'List videos of an account'
305 - $ref: '#/components/parameters/name'
306 - $ref: '#/components/parameters/categoryOneOf'
307 - $ref: '#/components/parameters/isLive'
308 - $ref: '#/components/parameters/tagsOneOf'
309 - $ref: '#/components/parameters/tagsAllOf'
310 - $ref: '#/components/parameters/licenceOneOf'
311 - $ref: '#/components/parameters/languageOneOf'
312 - $ref: '#/components/parameters/nsfw'
313 - $ref: '#/components/parameters/filter'
314 - $ref: '#/components/parameters/skipCount'
315 - $ref: '#/components/parameters/start'
316 - $ref: '#/components/parameters/count'
317 - $ref: '#/components/parameters/videosSort'
320 description: successful operation
324 $ref: '#/components/schemas/VideoListResponse'
328 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
329 .then(function(response) {
330 return response.json()
331 }).then(function(data) {
337 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
343 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
345 http = Net::HTTP.new(uri.host, uri.port)
348 response = http.get(uri.request_uri)
350 puts JSON.parse(response.read_body)
355 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
363 summary: List accounts
365 - $ref: '#/components/parameters/start'
366 - $ref: '#/components/parameters/count'
367 - $ref: '#/components/parameters/sort'
370 description: successful operation
376 $ref: '#/components/schemas/Account'
381 summary: Get instance public configuration
384 description: successful operation
388 $ref: '#/components/schemas/ServerConfig'
391 externalValue: https://peertube2.cpy.re/api/v1/config
394 summary: Get instance "About" information
399 description: successful operation
403 $ref: '#/components/schemas/ServerConfigAbout'
406 externalValue: https://peertube2.cpy.re/api/v1/config/about
409 summary: Get instance runtime configuration
417 description: successful operation
421 $ref: '#/components/schemas/ServerConfigCustom'
423 summary: Set instance runtime configuration
431 description: successful operation
433 x-summary: field inconsistencies
436 - the emailer is disabled and the instance is open to registrations
437 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
439 summary: Delete instance runtime configuration
447 description: successful operation
450 summary: List instance jobs
460 description: The state of the job ('' for for no filter)
470 - $ref: '#/components/parameters/jobType'
471 - $ref: '#/components/parameters/start'
472 - $ref: '#/components/parameters/count'
473 - $ref: '#/components/parameters/sort'
476 description: successful operation
489 $ref: '#/components/schemas/Job'
490 '/server/following/{host}':
497 summary: Unfollow a server
502 description: 'The host to unfollow '
508 description: successful operation
513 summary: List instance followers
515 - $ref: '#/components/parameters/start'
516 - $ref: '#/components/parameters/count'
517 - $ref: '#/components/parameters/sort'
520 description: successful operation
526 $ref: '#/components/schemas/Follow'
531 summary: List instances followed by the server
550 - $ref: '#/components/parameters/start'
551 - $ref: '#/components/parameters/count'
552 - $ref: '#/components/parameters/sort'
555 description: successful operation
561 $ref: '#/components/schemas/Follow'
568 summary: Follow a server
571 description: successful operation
573 description: cannot follow a non-HTTPS server
588 summary: Create a user
589 operationId: createUser
597 description: user created
601 $ref: '#/components/schemas/AddUserResponse'
605 operationId: getUserId
607 id: '$response.body#/user/id'
610 operationId: putUserId
612 id: '$response.body#/user/id'
615 operationId: delUserId
617 id: '$response.body#/user/id'
619 description: insufficient authority to create an admin or moderator
624 $ref: '#/components/schemas/AddUser'
626 If the smtp server is configured, you can leave the password empty and an email will be sent
627 asking the user to set it first.
637 - $ref: '#/components/parameters/usersSearch'
638 - $ref: '#/components/parameters/usersBlocked'
639 - $ref: '#/components/parameters/start'
640 - $ref: '#/components/parameters/count'
641 - $ref: '#/components/parameters/usersSort'
644 description: successful operation
650 $ref: '#/components/schemas/User'
653 - $ref: '#/components/parameters/id'
655 summary: Delete a user
661 operationId: delUserId
664 description: successful operation
671 operationId: getUserId
675 description: include statistics about the user (only available as a moderator/admin)
680 x-summary: successful operation
682 As an admin/moderator, you can request a response augmented with statistics about the user's
683 moderation relations and videos usage, by using the `withStats` parameter.
688 - $ref: '#/components/schemas/User'
689 - $ref: '#/components/schemas/UserWithStats'
691 summary: Update a user
696 operationId: putUserId
699 description: successful operation
704 $ref: '#/components/schemas/UpdateUser'
707 /oauth-clients/local:
709 summary: Login prerequisite
710 description: You need to retrieve a client id and secret before [logging in](#operation/getOauthToken).
711 operationId: getOAuthClient
716 description: successful operation
720 $ref: '#/components/schemas/OAuthClient'
722 UseOAuthClientToLogin:
723 operationId: getOAuthToken
725 client_id: '$response.body#/client_id'
726 client_secret: '$response.body#/client_secret'
730 operationId: getOAuthToken
731 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
736 application/x-www-form-urlencoded:
739 - $ref: '#/components/schemas/OAuthToken-password'
740 - $ref: '#/components/schemas/OAuthToken-refresh_token'
742 propertyName: grant_type
744 password: '#/components/schemas/OAuthToken-password'
745 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
748 description: successful operation
759 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
760 description: valid for 1 day
763 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
764 description: valid for 2 weeks
769 refresh_token_expires_in:
776 description: Revokes your access token and its associated refresh token, destroying your current session.
777 operationId: revokeOAuthToken
784 description: successful operation
788 summary: Register a user
794 description: successful operation
799 $ref: '#/components/schemas/RegisterUser'
801 /users/{id}/verify-email:
803 summary: Verify a user
805 Following a user registration, the new user will receive an email asking to click a link
811 - $ref: '#/components/parameters/id'
827 description: successful operation
829 description: invalid verification string
831 description: user not found
832 /users/ask-send-verify-email:
834 summary: Resend user verification link
840 description: successful operation
844 summary: Get my user information
852 description: successful operation
858 $ref: '#/components/schemas/User'
860 summary: Update my user information
868 description: successful operation
873 $ref: '#/components/schemas/UpdateMe'
875 /users/me/videos/imports:
877 summary: Get video imports of my user
885 - $ref: '#/components/parameters/start'
886 - $ref: '#/components/parameters/count'
887 - $ref: '#/components/parameters/sort'
890 description: successful operation
894 $ref: '#/components/schemas/VideoImportsList'
895 /users/me/video-quota-used:
897 summary: Get my user used quota
905 description: successful operation
913 description: The user video quota used so far in bytes
917 description: The user video quota used today in bytes
919 '/users/me/videos/{videoId}/rating':
921 summary: Get rate of my user for a video
931 description: The video id
933 $ref: '#/components/schemas/Video/properties/id'
936 description: successful operation
940 $ref: '#/components/schemas/GetMeVideoRating'
943 summary: Get videos of my user
951 - $ref: '#/components/parameters/start'
952 - $ref: '#/components/parameters/count'
953 - $ref: '#/components/parameters/sort'
956 description: successful operation
960 $ref: '#/components/schemas/VideoListResponse'
961 /users/me/subscriptions:
963 summary: Get my user subscriptions
970 - $ref: '#/components/parameters/start'
971 - $ref: '#/components/parameters/count'
972 - $ref: '#/components/parameters/sort'
975 description: successful operation
979 $ref: '#/components/schemas/VideoChannelList'
983 summary: Add subscription to my user
996 description: uri of the video channels to subscribe to
1002 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1005 description: successful operation
1006 /users/me/subscriptions/exist:
1008 summary: Get if subscriptions exist for my user
1015 - $ref: '#/components/parameters/subscriptionsUris'
1018 description: successful operation
1023 /users/me/subscriptions/videos:
1025 summary: List videos of subscriptions of my user
1033 - $ref: '#/components/parameters/categoryOneOf'
1034 - $ref: '#/components/parameters/isLive'
1035 - $ref: '#/components/parameters/tagsOneOf'
1036 - $ref: '#/components/parameters/tagsAllOf'
1037 - $ref: '#/components/parameters/licenceOneOf'
1038 - $ref: '#/components/parameters/languageOneOf'
1039 - $ref: '#/components/parameters/nsfw'
1040 - $ref: '#/components/parameters/filter'
1041 - $ref: '#/components/parameters/skipCount'
1042 - $ref: '#/components/parameters/start'
1043 - $ref: '#/components/parameters/count'
1044 - $ref: '#/components/parameters/videosSort'
1047 description: successful operation
1051 $ref: '#/components/schemas/VideoListResponse'
1052 '/users/me/subscriptions/{subscriptionHandle}':
1054 summary: Get subscription of my user
1061 - $ref: '#/components/parameters/subscriptionHandle'
1064 description: successful operation
1068 $ref: '#/components/schemas/VideoChannel'
1070 summary: Delete subscription of my user
1077 - $ref: '#/components/parameters/subscriptionHandle'
1080 description: successful operation
1081 /users/me/notifications:
1083 summary: List my notifications
1091 description: only list unread notifications
1094 - $ref: '#/components/parameters/start'
1095 - $ref: '#/components/parameters/count'
1096 - $ref: '#/components/parameters/sort'
1099 description: successful operation
1103 $ref: '#/components/schemas/NotificationListResponse'
1104 /users/me/notifications/read:
1106 summary: Mark notifications as read by their id
1119 description: ids of the notifications to mark as read
1126 description: successful operation
1127 /users/me/notifications/read-all:
1129 summary: Mark all my notification as read
1136 description: successful operation
1137 /users/me/notification-settings:
1139 summary: Update my notification settings
1150 newVideoFromSubscription:
1151 $ref: '#/components/schemas/NotificationSettingValue'
1152 newCommentOnMyVideo:
1153 $ref: '#/components/schemas/NotificationSettingValue'
1155 $ref: '#/components/schemas/NotificationSettingValue'
1156 videoAutoBlacklistAsModerator:
1157 $ref: '#/components/schemas/NotificationSettingValue'
1159 $ref: '#/components/schemas/NotificationSettingValue'
1161 $ref: '#/components/schemas/NotificationSettingValue'
1162 myVideoImportFinished:
1163 $ref: '#/components/schemas/NotificationSettingValue'
1165 $ref: '#/components/schemas/NotificationSettingValue'
1166 newUserRegistration:
1167 $ref: '#/components/schemas/NotificationSettingValue'
1169 $ref: '#/components/schemas/NotificationSettingValue'
1170 newInstanceFollower:
1171 $ref: '#/components/schemas/NotificationSettingValue'
1172 autoInstanceFollowing:
1173 $ref: '#/components/schemas/NotificationSettingValue'
1176 description: successful operation
1177 /users/me/history/videos:
1179 summary: List watched videos history
1185 - $ref: '#/components/parameters/start'
1186 - $ref: '#/components/parameters/count'
1187 - $ref: '#/components/parameters/search'
1190 description: successful operation
1194 $ref: '#/components/schemas/VideoListResponse'
1195 /users/me/history/videos/remove:
1197 summary: Clear video history
1204 multipart/form-data:
1209 description: history before this date will be deleted
1214 description: successful operation
1215 /users/me/avatar/pick:
1217 summary: Update my user avatar
1224 description: successful operation
1231 $ref: '#/components/schemas/ActorImage'
1233 description: image file too large
1235 X-File-Maximum-Size:
1239 description: Maximum file size for the avatar
1242 multipart/form-data:
1247 description: The file to upload
1252 contentType: image/png, image/jpeg
1255 summary: Delete my avatar
1262 description: successful operation
1266 summary: List video ownership changes
1268 - Video Ownership Change
1273 description: successful operation
1274 '/videos/ownership/{id}/accept':
1276 summary: Accept ownership change request
1278 - Video Ownership Change
1282 - $ref: '#/components/parameters/idOrUUID'
1285 description: successful operation
1287 description: cannot terminate an ownership change of another user
1289 description: video owneship change not found
1290 '/videos/ownership/{id}/refuse':
1292 summary: Refuse ownership change request
1294 - Video Ownership Change
1298 - $ref: '#/components/parameters/idOrUUID'
1301 description: successful operation
1303 description: cannot terminate an ownership change of another user
1305 description: video owneship change not found
1306 '/videos/{id}/give-ownership':
1308 summary: Request ownership change
1310 - Video Ownership Change
1314 - $ref: '#/components/parameters/idOrUUID'
1318 application/x-www-form-urlencoded:
1328 description: successful operation
1330 description: changing video ownership to a remote account is not supported yet
1332 description: video not found
1335 summary: List videos
1339 - $ref: '#/components/parameters/categoryOneOf'
1340 - $ref: '#/components/parameters/isLive'
1341 - $ref: '#/components/parameters/tagsOneOf'
1342 - $ref: '#/components/parameters/tagsAllOf'
1343 - $ref: '#/components/parameters/licenceOneOf'
1344 - $ref: '#/components/parameters/languageOneOf'
1345 - $ref: '#/components/parameters/nsfw'
1346 - $ref: '#/components/parameters/filter'
1347 - $ref: '#/components/parameters/skipCount'
1348 - $ref: '#/components/parameters/start'
1349 - $ref: '#/components/parameters/count'
1350 - $ref: '#/components/parameters/videosSort'
1353 description: successful operation
1357 $ref: '#/components/schemas/VideoListResponse'
1360 summary: List available video categories
1361 operationId: getCategories
1366 description: successful operation
1375 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1378 summary: List available video licences
1379 operationId: getLicences
1384 description: successful operation
1393 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1396 summary: List available video languages
1397 operationId: getLanguages
1402 description: successful operation
1411 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1414 summary: List available video privacy policies
1415 operationId: getPrivacyPolicies
1420 description: successful operation
1429 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1432 summary: Update a video
1438 - $ref: '#/components/parameters/idOrUUID'
1441 description: successful operation
1444 multipart/form-data:
1449 description: Video thumbnail file
1453 description: Video preview file
1457 $ref: '#/components/schemas/VideoCategorySet'
1459 $ref: '#/components/schemas/VideoLicenceSet'
1461 $ref: '#/components/schemas/VideoLanguageSet'
1463 $ref: '#/components/schemas/VideoPrivacySet'
1465 description: Video description
1468 description: Whether or not we wait transcoding before publish the video
1471 description: A text tell the audience how to support the video creator
1472 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1475 description: Whether or not this video contains sensitive content
1478 description: Video name
1483 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1492 description: Enable or disable comments for this video
1494 originallyPublishedAt:
1495 description: Date when the content was originally published
1499 $ref: '#/components/schemas/VideoScheduledUpdate'
1502 contentType: image/jpeg
1504 contentType: image/jpeg
1506 summary: Get a video
1510 - $ref: '#/components/parameters/idOrUUID'
1513 description: successful operation
1517 $ref: '#/components/schemas/VideoDetails'
1519 summary: Delete a video
1525 - $ref: '#/components/parameters/idOrUUID'
1528 description: successful operation
1529 '/videos/{id}/description':
1531 summary: Get complete video description
1535 - $ref: '#/components/parameters/idOrUUID'
1538 description: successful operation
1547 **[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)**
1548 '/videos/{id}/views':
1550 summary: Add a view to a video
1554 - $ref: '#/components/parameters/idOrUUID'
1557 description: successful operation
1558 '/videos/{id}/watching':
1560 summary: Set watching progress of a video
1566 - $ref: '#/components/parameters/idOrUUID'
1571 $ref: '#/components/schemas/UserWatchingVideo'
1575 description: successful operation
1578 summary: Upload a video
1579 description: Uses a single request to upload a video.
1580 operationId: uploadLegacy
1588 description: successful operation
1592 $ref: '#/components/schemas/VideoUploadResponse'
1594 description: invalid file field, schedule date or parameter
1596 description: video didn't pass upload filter
1598 description: upload has timed out
1600 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1602 X-File-Maximum-Size:
1606 description: Maximum file size for the video
1608 description: video type unsupported
1610 description: video unreadable
1613 multipart/form-data:
1615 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1618 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1620 contentType: image/jpeg
1622 contentType: image/jpeg
1627 USERNAME="<your_username>"
1628 PASSWORD="<your_password>"
1629 FILE_PATH="<your_file_path>"
1630 CHANNEL_ID="<your_channel_id>"
1633 API_PATH="https://peertube2.cpy.re/api/v1"
1635 client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1636 client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1637 token=$(curl -s "$API_PATH/users/token" \
1638 --data client_id="$client_id" \
1639 --data client_secret="$client_secret" \
1640 --data grant_type=password \
1641 --data response_type=code \
1642 --data username="$USERNAME" \
1643 --data password="$PASSWORD" \
1644 | jq -r ".access_token")
1646 curl -s "$API_PATH/videos/upload" \
1647 -H "Authorization: Bearer $token" \
1649 --form videofile=@"$FILE_PATH" \
1650 --form channelId=$CHANNEL_ID \
1652 /videos/upload-resumable:
1654 summary: Initialize the resumable upload of a video
1655 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1656 operationId: uploadResumableInit
1663 - name: X-Upload-Content-Length
1669 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1670 - name: X-Upload-Content-Type
1677 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1682 $ref: '#/components/schemas/VideoUploadRequestResumable'
1685 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1687 description: created
1693 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1699 description: invalid file field, schedule date or parameter
1701 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1703 description: video type unsupported
1705 summary: Send chunk for the resumable upload of a video
1706 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
1707 operationId: uploadResumable
1718 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1719 not valid anymore and you need to initialize a new upload.
1722 - name: Content-Range
1726 example: bytes 0-262143/2469036
1729 Specifies the bytes in the file that the request is uploading.
1731 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1732 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1733 - name: Content-Length
1740 Size of the chunk that the request is sending.
1742 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)
1743 doesn't mandate for chunks to have the same size throughout the upload sequence.
1745 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1746 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1749 application/octet-stream:
1755 description: last chunk received
1763 $ref: '#/components/schemas/VideoUploadResponse'
1765 description: resume incomplete
1770 example: bytes=0-262143
1776 description: video didn't pass upload filter
1778 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1780 description: video unreadable
1782 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1783 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1784 operationId: uploadResumableCancel
1795 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1796 not valid anymore and the upload session has already been deleted with its data ;-)
1799 - name: Content-Length
1807 description: upload cancelled
1815 summary: Import a video
1816 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1817 operationId: importVideo
1825 multipart/form-data:
1827 $ref: '#/components/schemas/VideoCreateImport'
1830 contentType: application/x-bittorrent
1832 contentType: image/jpeg
1834 contentType: image/jpeg
1837 description: successful operation
1841 $ref: '#/components/schemas/VideoUploadResponse'
1843 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1845 description: video didn't pass pre-import filter
1847 description: HTTP or Torrent/magnetURI import not enabled
1851 summary: Create a live
1852 operationId: createLive
1860 description: successful operation
1864 $ref: '#/components/schemas/VideoUploadResponse'
1866 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
1869 multipart/form-data:
1874 description: Channel id that will contain this live video
1879 description: User can stream multiple times in a permanent live
1882 description: Live video/replay thumbnail file
1886 description: Live video/replay preview file
1890 $ref: '#/components/schemas/VideoPrivacySet'
1892 $ref: '#/components/schemas/VideoCategorySet'
1894 $ref: '#/components/schemas/VideoLicenceSet'
1896 $ref: '#/components/schemas/VideoLanguageSet'
1898 description: Live video/replay description
1901 description: A text tell the audience how to support the creator
1902 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1905 description: Whether or not this live video/replay contains sensitive content
1908 description: Live video/replay name
1913 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
1922 description: Enable or disable comments for this live video/replay
1925 description: Enable or disable downloading for the replay of this live
1932 contentType: image/jpeg
1934 contentType: image/jpeg
1938 summary: Get information about a live
1939 operationId: getLiveId
1946 - $ref: '#/components/parameters/idOrUUID'
1949 description: successful operation
1953 $ref: '#/components/schemas/LiveVideoResponse'
1955 summary: Update information about a live
1956 operationId: updateLiveId
1963 - $ref: '#/components/parameters/idOrUUID'
1968 $ref: '#/components/schemas/LiveVideoUpdate'
1971 description: successful operation
1973 description: bad parameters or trying to update a live that has already started
1975 description: trying to save replay of the live but saving replay is not enabled on the instance
1979 summary: List my abuses
1980 operationId: getMyAbuses
1989 description: only list the report with this id
1995 $ref: '#/components/schemas/AbuseStateSet'
1996 - $ref: '#/components/parameters/abusesSort'
1997 - $ref: '#/components/parameters/start'
1998 - $ref: '#/components/parameters/count'
2001 description: successful operation
2013 $ref: '#/components/schemas/Abuse'
2017 summary: List abuses
2018 operationId: getAbuses
2028 description: only list the report with this id
2031 - name: predefinedReason
2033 description: predefined reason the listed reports should contain
2035 $ref: '#/components/schemas/PredefinedAbuseReasons'
2038 description: plain search that will match with video titles, reporter names and more
2044 $ref: '#/components/schemas/AbuseStateSet'
2045 - name: searchReporter
2047 description: only list reports of a specific reporter
2050 - name: searchReportee
2051 description: only list reports of a specific reportee
2057 description: only list reports of a specific video
2060 - name: searchVideoChannel
2062 description: only list reports of a specific video channel
2067 description: only list blacklisted or deleted videos
2075 description: only list account, comment or video reports
2082 - $ref: '#/components/parameters/start'
2083 - $ref: '#/components/parameters/count'
2084 - $ref: '#/components/parameters/abusesSort'
2087 description: successful operation
2099 $ref: '#/components/schemas/Abuse'
2102 summary: Report an abuse
2115 description: Reason why the user reports this video
2120 $ref: '#/components/schemas/PredefinedAbuseReasons'
2125 description: Video id to report
2127 - $ref: '#/components/schemas/Video/properties/id'
2131 description: Timestamp in the video that marks the beginning of the report
2136 description: Timestamp in the video that marks the ending of the report
2142 description: Comment id to report
2144 - $ref: '#/components/schemas/VideoComment/properties/id'
2149 description: Account id to report
2155 description: successful operation
2157 description: incorrect request parameters
2158 '/abuses/{abuseId}':
2160 summary: Update an abuse
2168 - $ref: '#/components/parameters/abuseId'
2176 $ref: '#/components/schemas/AbuseStateSet'
2179 description: Update the report comment visible only to the moderation team
2184 description: successful operation
2186 description: abuse not found
2190 summary: Delete an abuse
2196 - $ref: '#/components/parameters/abuseId'
2199 description: successful operation
2201 description: block not found
2202 '/abuses/{abuseId}/messages':
2204 summary: List messages of an abuse
2210 - $ref: '#/components/parameters/abuseId'
2213 description: successful operation
2219 $ref: '#/components/schemas/AbuseMessage'
2222 summary: Add message to an abuse
2228 - $ref: '#/components/parameters/abuseId'
2237 description: Message to send
2245 description: successful operation
2247 description: incorrect request parameters
2248 '/abuses/{abuseId}/messages/{abuseMessageId}':
2250 summary: Delete an abuse message
2256 - $ref: '#/components/parameters/abuseId'
2257 - $ref: '#/components/parameters/abuseMessageId'
2260 description: successful operation
2262 '/videos/{id}/blacklist':
2264 summary: Block a video
2272 - $ref: '#/components/parameters/idOrUUID'
2275 description: successful operation
2277 summary: Unblock a video by its id
2285 - $ref: '#/components/parameters/idOrUUID'
2288 description: successful operation
2290 description: block not found
2295 summary: List video blocks
2304 list only blocks that match this type:
2308 - `2`: automatic block that needs review
2316 description: plain search that will match with video titles, and more
2319 - $ref: '#/components/parameters/start'
2320 - $ref: '#/components/parameters/count'
2321 - $ref: '#/components/parameters/blacklistsSort'
2324 description: successful operation
2336 $ref: '#/components/schemas/VideoBlacklist'
2337 /videos/{id}/captions:
2339 summary: List captions of a video
2343 - $ref: '#/components/parameters/idOrUUID'
2346 description: successful operation
2358 $ref: '#/components/schemas/VideoCaption'
2359 /videos/{id}/captions/{captionLanguage}:
2361 summary: Add or replace a video caption
2368 - $ref: '#/components/parameters/idOrUUID'
2369 - $ref: '#/components/parameters/captionLanguage'
2372 multipart/form-data:
2377 description: The file to upload.
2382 contentType: text/vtt, application/x-subrip, text/plain
2385 description: successful operation
2387 description: video or language not found
2389 summary: Delete a video caption
2396 - $ref: '#/components/parameters/idOrUUID'
2397 - $ref: '#/components/parameters/captionLanguage'
2400 description: successful operation
2402 description: video or language or caption for that language not found
2405 summary: List video channels
2406 operationId: getVideoChannels
2410 - $ref: '#/components/parameters/start'
2411 - $ref: '#/components/parameters/count'
2412 - $ref: '#/components/parameters/sort'
2415 description: successful operation
2419 $ref: '#/components/schemas/VideoChannelList'
2421 summary: Create a video channel
2422 operationId: createVideoChannel
2429 description: successful operation
2439 $ref: '#/components/schemas/VideoChannel/properties/id'
2444 $ref: '#/components/schemas/VideoChannelCreate'
2445 '/video-channels/{channelHandle}':
2447 summary: Get a video channel
2448 operationId: getVideoChannel
2452 - $ref: '#/components/parameters/channelHandle'
2455 description: successful operation
2459 $ref: '#/components/schemas/VideoChannel'
2461 summary: Update a video channel
2467 - $ref: '#/components/parameters/channelHandle'
2470 description: successful operation
2475 $ref: '#/components/schemas/VideoChannelUpdate'
2477 summary: Delete a video channel
2483 - $ref: '#/components/parameters/channelHandle'
2486 description: successful operation
2487 '/video-channels/{channelHandle}/videos':
2489 summary: List videos of a video channel
2494 - $ref: '#/components/parameters/channelHandle'
2495 - $ref: '#/components/parameters/categoryOneOf'
2496 - $ref: '#/components/parameters/isLive'
2497 - $ref: '#/components/parameters/tagsOneOf'
2498 - $ref: '#/components/parameters/tagsAllOf'
2499 - $ref: '#/components/parameters/licenceOneOf'
2500 - $ref: '#/components/parameters/languageOneOf'
2501 - $ref: '#/components/parameters/nsfw'
2502 - $ref: '#/components/parameters/filter'
2503 - $ref: '#/components/parameters/skipCount'
2504 - $ref: '#/components/parameters/start'
2505 - $ref: '#/components/parameters/count'
2506 - $ref: '#/components/parameters/videosSort'
2509 description: successful operation
2513 $ref: '#/components/schemas/VideoListResponse'
2514 '/video-channels/{channelHandle}/avatar/pick':
2516 summary: Update channel avatar
2522 - $ref: '#/components/parameters/channelHandle'
2525 description: successful operation
2532 $ref: '#/components/schemas/ActorImage'
2534 description: image file too large
2536 X-File-Maximum-Size:
2540 description: Maximum file size for the avatar
2543 multipart/form-data:
2548 description: The file to upload.
2553 contentType: image/png, image/jpeg
2554 '/video-channels/{channelHandle}/avatar':
2556 summary: Delete channel avatar
2562 - $ref: '#/components/parameters/channelHandle'
2565 description: successful operation
2568 '/video-channels/{channelHandle}/banner/pick':
2570 summary: Update channel banner
2576 - $ref: '#/components/parameters/channelHandle'
2579 description: successful operation
2586 $ref: '#/components/schemas/ActorImage'
2588 description: image file too large
2590 X-File-Maximum-Size:
2594 description: Maximum file size for the banner
2597 multipart/form-data:
2602 description: The file to upload.
2607 contentType: image/png, image/jpeg
2608 '/video-channels/{channelHandle}/banner':
2610 summary: Delete channel banner
2616 - $ref: '#/components/parameters/channelHandle'
2619 description: successful operation
2621 /video-playlists/privacies:
2623 summary: List available playlist privacy policies
2624 operationId: getPlaylistPrivacyPolicies
2629 description: successful operation
2638 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2642 summary: List video playlists
2643 operationId: getPlaylists
2647 - $ref: '#/components/parameters/start'
2648 - $ref: '#/components/parameters/count'
2649 - $ref: '#/components/parameters/sort'
2652 description: successful operation
2664 $ref: '#/components/schemas/VideoPlaylist'
2666 summary: Create a video playlist
2667 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2668 operationId: createPlaylist
2675 description: successful operation
2685 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2687 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2690 multipart/form-data:
2695 description: Video playlist display name
2700 description: Video playlist thumbnail file
2704 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2706 description: Video playlist description
2712 - $ref: '#/components/schemas/id'
2713 description: Video channel in which the playlist will be published
2718 contentType: image/jpeg
2720 /video-playlists/{playlistId}:
2722 summary: Get a video playlist
2726 - $ref: '#/components/parameters/playlistId'
2729 description: successful operation
2733 $ref: '#/components/schemas/VideoPlaylist'
2735 summary: Update a video playlist
2736 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2743 description: successful operation
2745 - $ref: '#/components/parameters/playlistId'
2748 multipart/form-data:
2753 description: Video playlist display name
2758 description: Video playlist thumbnail file
2762 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2764 description: Video playlist description
2768 - $ref: '#/components/schemas/id'
2769 description: Video channel in which the playlist will be published
2772 contentType: image/jpeg
2774 summary: Delete a video playlist
2780 - $ref: '#/components/parameters/playlistId'
2783 description: successful operation
2785 /video-playlists/{playlistId}/videos:
2787 summary: 'List videos of a playlist'
2792 - $ref: '#/components/parameters/playlistId'
2795 description: successful operation
2799 $ref: '#/components/schemas/VideoListResponse'
2801 summary: Add a video in a playlist
2808 - $ref: '#/components/parameters/playlistId'
2811 description: successful operation
2817 videoPlaylistElement:
2831 - $ref: '#/components/schemas/Video/properties/uuid'
2832 - $ref: '#/components/schemas/Video/properties/id'
2833 description: Video to add in the playlist
2837 description: Start the video at this specific timestamp
2841 description: Stop the video at this specific timestamp
2845 /video-playlists/{playlistId}/videos/reorder:
2847 summary: 'Reorder a playlist'
2853 - $ref: '#/components/parameters/playlistId'
2856 description: successful operation
2865 description: 'Start position of the element to reorder'
2867 insertAfterPosition:
2869 description: 'New position for the block to reorder, to add the block before the first element'
2873 description: 'How many element from `startPosition` to reorder'
2877 - insertAfterPosition
2879 /video-playlists/{playlistId}/videos/{playlistElementId}:
2881 summary: Update a playlist element
2887 - $ref: '#/components/parameters/playlistId'
2888 - $ref: '#/components/parameters/playlistElementId'
2891 description: successful operation
2901 description: Start the video at this specific timestamp
2905 description: Stop the video at this specific timestamp
2907 summary: Delete an element from a playlist
2913 - $ref: '#/components/parameters/playlistId'
2914 - $ref: '#/components/parameters/playlistElementId'
2917 description: successful operation
2919 '/users/me/video-playlists/videos-exist':
2921 summary: Check video exists in my playlists
2930 description: The video ids to check
2934 $ref: '#/components/schemas/Video/properties/id'
2937 description: successful operation
2959 '/accounts/{name}/video-channels':
2961 summary: List video channels of an account
2966 - $ref: '#/components/parameters/name'
2969 description: include view statistics for the last 30 days (only if authentified as the account user)
2972 - $ref: '#/components/parameters/start'
2973 - $ref: '#/components/parameters/count'
2974 - $ref: '#/components/parameters/sort'
2977 description: successful operation
2981 $ref: '#/components/schemas/VideoChannelList'
2982 '/accounts/{name}/ratings':
2984 summary: List ratings of an account
2990 - $ref: '#/components/parameters/name'
2991 - $ref: '#/components/parameters/start'
2992 - $ref: '#/components/parameters/count'
2993 - $ref: '#/components/parameters/sort'
2997 description: Optionally filter which ratings to retrieve
3005 description: successful operation
3011 $ref: '#/components/schemas/VideoRating'
3012 '/videos/{id}/comment-threads':
3014 summary: List threads of a video
3018 - $ref: '#/components/parameters/idOrUUID'
3019 - $ref: '#/components/parameters/start'
3020 - $ref: '#/components/parameters/count'
3021 - $ref: '#/components/parameters/commentsSort'
3024 description: successful operation
3028 $ref: '#/components/schemas/CommentThreadResponse'
3030 summary: Create a thread
3036 - $ref: '#/components/parameters/idOrUUID'
3039 description: successful operation
3043 $ref: '#/components/schemas/CommentThreadPostResponse'
3045 description: video does not exist
3054 - $ref: '#/components/schemas/VideoComment/properties/text'
3060 '/videos/{id}/comment-threads/{threadId}':
3062 summary: Get a thread
3066 - $ref: '#/components/parameters/idOrUUID'
3067 - $ref: '#/components/parameters/threadId'
3070 description: successful operation
3074 $ref: '#/components/schemas/VideoCommentThreadTree'
3075 '/videos/{id}/comments/{commentId}':
3077 summary: Reply to a thread of a video
3083 - $ref: '#/components/parameters/idOrUUID'
3084 - $ref: '#/components/parameters/commentId'
3087 description: successful operation
3091 $ref: '#/components/schemas/CommentThreadPostResponse'
3093 description: thread or video does not exist
3102 - $ref: '#/components/schemas/VideoComment/properties/text'
3109 summary: Delete a comment or a reply
3115 - $ref: '#/components/parameters/idOrUUID'
3116 - $ref: '#/components/parameters/commentId'
3119 description: successful operation
3121 description: cannot remove comment of another user
3123 description: comment or video does not exist
3125 description: comment is already deleted
3126 '/videos/{id}/rate':
3128 summary: Like/dislike a video
3134 - $ref: '#/components/parameters/idOrUUID'
3150 description: successful operation
3152 description: video does not exist
3157 summary: Search videos
3162 allowEmptyValue: false
3164 String to search. If the user can make a remote URI search, and the string is an URI then the
3165 PeerTube instance will fetch the remote object and add it to its database. Then,
3166 you can use the REST API to fetch the complete video information and interact with it.
3169 - $ref: '#/components/parameters/categoryOneOf'
3170 - $ref: '#/components/parameters/isLive'
3171 - $ref: '#/components/parameters/tagsOneOf'
3172 - $ref: '#/components/parameters/tagsAllOf'
3173 - $ref: '#/components/parameters/licenceOneOf'
3174 - $ref: '#/components/parameters/languageOneOf'
3175 - $ref: '#/components/parameters/nsfw'
3176 - $ref: '#/components/parameters/filter'
3177 - $ref: '#/components/parameters/skipCount'
3178 - $ref: '#/components/parameters/start'
3179 - $ref: '#/components/parameters/count'
3180 - $ref: '#/components/parameters/searchTarget'
3181 - $ref: '#/components/parameters/videosSearchSort'
3184 description: Get videos that are published after this date
3190 description: Get videos that are published before this date
3194 - name: originallyPublishedStartDate
3196 description: Get videos that are originally published after this date
3200 - name: originallyPublishedEndDate
3202 description: Get videos that are originally published before this date
3208 description: Get videos that have this minimum duration
3213 description: Get videos that have this maximum duration
3217 'searchTarget === search-index':
3218 $ref: '#/components/callbacks/searchIndex'
3221 description: successful operation
3225 $ref: '#/components/schemas/VideoListResponse'
3227 description: search index unavailable
3228 /search/video-channels:
3232 summary: Search channels
3238 String to search. If the user can make a remote URI search, and the string is an URI then the
3239 PeerTube instance will fetch the remote object and add it to its database. Then,
3240 you can use the REST API to fetch the complete channel information and interact with it.
3243 - $ref: '#/components/parameters/start'
3244 - $ref: '#/components/parameters/count'
3245 - $ref: '#/components/parameters/searchTarget'
3246 - $ref: '#/components/parameters/sort'
3248 'searchTarget === search-index':
3249 $ref: '#/components/callbacks/searchIndex'
3252 description: successful operation
3256 $ref: '#/components/schemas/VideoChannelList'
3258 description: search index unavailable
3259 /blocklist/accounts:
3263 summary: List account blocks
3268 - $ref: '#/components/parameters/start'
3269 - $ref: '#/components/parameters/count'
3270 - $ref: '#/components/parameters/sort'
3273 description: successful operation
3277 summary: Block an account
3289 example: chocobozzz@example.org
3290 description: account to block, in the form `username@domain`
3295 description: successful operation
3297 description: self-blocking forbidden
3298 '/blocklist/accounts/{accountName}':
3302 summary: Unblock an account by its handle
3310 description: account to unblock, in the form `username@domain`
3315 description: successful operation
3317 description: account or account block does not exist
3322 summary: List server blocks
3327 - $ref: '#/components/parameters/start'
3328 - $ref: '#/components/parameters/count'
3329 - $ref: '#/components/parameters/sort'
3332 description: successful operation
3336 summary: Block a server
3349 description: server domain to block
3354 description: successful operation
3356 description: self-blocking forbidden
3357 '/blocklist/servers/{host}':
3361 summary: Unblock a server by its domain
3369 description: server domain to unblock
3375 description: successful operation
3377 description: account block does not exist
3381 - Instance Redundancy
3382 summary: Update a server redundancy policy
3390 description: server domain to mirror
3402 description: allow mirroring of the host's local videos
3407 description: successful operation
3409 description: server is not already known
3414 summary: List videos being mirrored
3422 description: direction of the mirror
3428 - $ref: '#/components/parameters/start'
3429 - $ref: '#/components/parameters/count'
3430 - $ref: '#/components/parameters/videoRedundanciesSort'
3433 description: successful operation
3439 $ref: '#/components/schemas/VideoRedundancy'
3443 summary: Mirror a video
3454 $ref: '#/components/schemas/Video/properties/id'
3459 description: successful operation
3461 description: cannot mirror a local video
3463 description: video does not exist
3465 description: video is already mirrored
3466 /redundancy/videos/{redundancyId}:
3470 summary: Delete a mirror done on a video
3475 - name: redundancyId
3478 description: id of an existing redundancy on a video
3483 description: successful operation
3485 description: video redundancy not found
3486 '/feeds/video-comments.{format}':
3490 summary: List comments on videos
3495 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3508 description: 'limit listing to a specific video'
3513 description: 'limit listing to a specific account'
3518 description: 'limit listing to a specific account'
3521 - name: videoChannelId
3523 description: 'limit listing to a specific video channel'
3526 - name: videoChannelName
3528 description: 'limit listing to a specific video channel'
3533 description: successful operation
3538 default: 'max-age=900' # 15 min cache
3542 $ref: '#/components/schemas/VideoCommentsForXML'
3545 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3546 application/rss+xml:
3548 $ref: '#/components/schemas/VideoCommentsForXML'
3551 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3554 $ref: '#/components/schemas/VideoCommentsForXML'
3557 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3558 application/atom+xml:
3560 $ref: '#/components/schemas/VideoCommentsForXML'
3563 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3569 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3571 x-summary: field inconsistencies
3574 - videoId filter is mixed with a channel filter
3576 description: video, video channel or account not found
3578 description: accept header unsupported
3579 '/feeds/videos.{format}':
3583 summary: List videos
3588 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3601 description: 'limit listing to a specific account'
3606 description: 'limit listing to a specific account'
3609 - name: videoChannelId
3611 description: 'limit listing to a specific video channel'
3614 - name: videoChannelName
3616 description: 'limit listing to a specific video channel'
3619 - $ref: '#/components/parameters/sort'
3620 - $ref: '#/components/parameters/nsfw'
3621 - $ref: '#/components/parameters/filter'
3624 description: successful operation
3629 default: 'max-age=900' # 15 min cache
3633 $ref: '#/components/schemas/VideosForXML'
3636 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3637 application/rss+xml:
3639 $ref: '#/components/schemas/VideosForXML'
3642 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3645 $ref: '#/components/schemas/VideosForXML'
3648 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3649 application/atom+xml:
3651 $ref: '#/components/schemas/VideosForXML'
3654 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3660 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3662 description: video channel or account not found
3664 description: accept header unsupported
3665 '/feeds/subscriptions.{format}':
3670 summary: List videos of subscriptions tied to a token
3675 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3688 description: limit listing to a specific account
3694 description: private token allowing access
3698 - $ref: '#/components/parameters/sort'
3699 - $ref: '#/components/parameters/nsfw'
3700 - $ref: '#/components/parameters/filter'
3703 description: successful operation
3708 default: 'max-age=900' # 15 min cache
3712 $ref: '#/components/schemas/VideosForXML'
3713 application/rss+xml:
3715 $ref: '#/components/schemas/VideosForXML'
3718 $ref: '#/components/schemas/VideosForXML'
3719 application/atom+xml:
3721 $ref: '#/components/schemas/VideosForXML'
3726 description: accept header unsupported
3731 summary: List plugins
3744 - $ref: '#/components/parameters/start'
3745 - $ref: '#/components/parameters/count'
3746 - $ref: '#/components/parameters/sort'
3749 description: successful operation
3753 $ref: '#/components/schemas/PluginResponse'
3758 summary: List available plugins
3771 - name: currentPeerTubeEngine
3775 - $ref: '#/components/parameters/start'
3776 - $ref: '#/components/parameters/count'
3777 - $ref: '#/components/parameters/sort'
3780 description: successful operation
3784 $ref: '#/components/schemas/PluginResponse'
3786 description: plugin index unavailable
3791 summary: Install a plugin
3804 example: peertube-plugin-auth-ldap
3807 additionalProperties: false
3814 additionalProperties: false
3817 description: successful operation
3819 description: should have either `npmName` or `path` set
3824 summary: Update a plugin
3837 example: peertube-plugin-auth-ldap
3840 additionalProperties: false
3847 additionalProperties: false
3850 description: successful operation
3852 description: should have either `npmName` or `path` set
3854 description: existing plugin not found
3859 summary: Uninstall a plugin
3871 description: name of the plugin/theme in its package.json
3872 example: peertube-plugin-auth-ldap
3877 description: successful operation
3879 description: existing plugin not found
3884 summary: Get a plugin
3889 - $ref: '#/components/parameters/npmName'
3892 description: successful operation
3896 $ref: '#/components/schemas/Plugin'
3898 description: plugin not found
3899 /plugins/{npmName}/settings:
3903 summary: Set a plugin's settings
3908 - $ref: '#/components/parameters/npmName'
3917 additionalProperties: true
3920 description: successful operation
3922 description: plugin not found
3923 /plugins/{npmName}/public-settings:
3927 summary: Get a plugin's public settings
3929 - $ref: '#/components/parameters/npmName'
3932 description: successful operation
3937 additionalProperties: true
3939 description: plugin not found
3940 /plugins/{npmName}/registered-settings:
3944 summary: Get a plugin's registered settings
3949 - $ref: '#/components/parameters/npmName'
3952 description: successful operation
3957 additionalProperties: true
3959 description: plugin not found
3961 - url: 'https://peertube2.cpy.re/api/v1'
3962 description: Live Test Server (live data - latest nightly version)
3963 - url: 'https://peertube3.cpy.re/api/v1'
3964 description: Live Test Server (live data - latest RC version)
3965 - url: 'https://peertube.cpy.re/api/v1'
3966 description: Live Test Server (live data - stable version)
3973 description: Offset used to paginate results
3981 description: "Number of items to return"
3991 description: Sort column
3999 description: Plain text search, applied to various parts of the model depending on endpoint
4007 If the administrator enabled search index support, you can override the default search target.
4010 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4011 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4012 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4013 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4014 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4015 * 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
4016 the data from the origin instance API
4026 description: Sort videos by criteria
4042 description: Sort videos by criteria
4057 description: Sort comments by criteria
4067 description: Sort blacklists by criteria
4083 description: Plain text search that will match with user usernames or emails
4090 description: Filter results down to (un)banned users
4097 description: Sort users by criteria
4108 description: Sort abuses by criteria
4115 videoRedundanciesSort:
4119 description: Sort abuses by criteria
4128 description: The username or handle of the account
4131 example: chocobozzz | chocobozzz@example.org
4136 description: The user id
4138 $ref: '#/components/schemas/id'
4143 description: The object id or uuid
4146 - $ref: '#/components/schemas/id'
4147 - $ref: '#/components/schemas/UUIDv4'
4152 description: Playlist id
4154 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4156 name: playlistElementId
4159 description: Playlist element id
4161 $ref: '#/components/schemas/id'
4166 description: Abuse id
4168 $ref: '#/components/schemas/Abuse/properties/id'
4170 name: abuseMessageId
4173 description: Abuse message id
4175 $ref: '#/components/schemas/AbuseMessage/properties/id'
4177 name: captionLanguage
4180 description: The caption language
4182 $ref: '#/components/schemas/VideoLanguageSet'
4187 description: The video channel handle
4190 example: my_username | my_username@example.com
4192 name: subscriptionHandle
4195 description: The subscription handle
4198 example: my_username | my_username@example.com
4203 description: The thread id (root comment id)
4205 $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
4210 description: The comment id
4212 $ref: '#/components/schemas/VideoComment/properties/id'
4217 description: whether or not the video is a live
4224 description: category id of the video (see [/videos/categories](#operation/getCategories))
4227 - $ref: '#/components/schemas/VideoCategorySet'
4230 $ref: '#/components/schemas/VideoCategorySet'
4237 description: tag(s) of the video
4251 description: tag(s) of the video, where all should be present in the video
4264 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4267 - $ref: '#/components/schemas/VideoLanguageSet'
4270 $ref: '#/components/schemas/VideoLanguageSet'
4277 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4280 - $ref: '#/components/schemas/VideoLicenceSet'
4283 $ref: '#/components/schemas/VideoLicenceSet'
4290 description: if you don't need the `total` in the response
4301 description: whether to include nsfw videos, if any
4312 Special filters which might require special rights:
4313 * `local` - only videos local to the instance
4314 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4315 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4325 description: list of uris to check if each is part of the user subscriptions
4335 description: name of the plugin/theme on npmjs.com or in its package.json
4338 example: peertube-plugin-auth-ldap
4343 description: job type
4347 - activitypub-follow
4348 - activitypub-http-broadcast
4349 - activitypub-http-fetcher
4350 - activitypub-http-unicast
4356 - activitypub-refresher
4362 Authenticating via OAuth requires the following steps:
4363 - Have an activated account
4364 - [Generate] an access token for that account at `/api/v1/users/token`.
4365 - Make requests with the *Authorization: Bearer <token\>* header
4366 - Profit, depending on the role assigned to the account
4368 Note that the __access token is valid for 1 day__ and is given
4369 along with a __refresh token valid for 2 weeks__.
4371 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4375 tokenUrl: /api/v1/users/token
4378 moderator: Moderator scope
4381 # Resuable core properties
4389 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4390 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4395 description: immutable name of the user, used to find or mention its actor
4397 pattern: '/^[a-z0-9._]+$/'
4402 description: immutable name of the channel, used to interact with its actor
4403 example: framasoft_videos
4404 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4415 description: category id of the video (see [/videos/categories](#operation/getCategories))
4417 VideoConstantNumber-Category:
4420 $ref: '#/components/schemas/VideoCategorySet'
4423 example: Science & Technology
4427 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4429 VideoConstantNumber-Licence:
4432 $ref: '#/components/schemas/VideoLicenceSet'
4435 example: Attribution - Share Alike
4439 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4441 VideoConstantString-Language:
4444 $ref: '#/components/schemas/VideoLanguageSet'
4449 VideoPlaylistPrivacySet:
4455 description: Video playlist privacy policy (see [/video-playlists/privacies])
4456 VideoPlaylistPrivacyConstant:
4459 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4463 VideoPlaylistTypeSet:
4468 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4469 VideoPlaylistTypeConstant:
4472 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4483 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4484 VideoPrivacyConstant:
4487 $ref: '#/components/schemas/VideoPrivacySet'
4504 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4511 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4522 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4532 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4536 $ref: '#/components/schemas/AbuseStateSet'
4539 AbusePredefinedReasons:
4552 example: [spamOrMisleading]
4557 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4559 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4561 VideoResolutionConstant:
4562 description: resolutions and their labels for the video
4565 $ref: '#/components/schemas/VideoResolutionSet'
4569 VideoScheduledUpdate:
4572 $ref: '#/components/schemas/VideoPrivacySet'
4576 description: When to update the video
4596 - $ref: '#/components/schemas/ActorImage'
4597 VideoChannelSummary:
4600 $ref: '#/components/schemas/id'
4614 - $ref: '#/components/schemas/ActorImage'
4628 - $ref: '#/components/schemas/Video'
4635 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4636 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
4637 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4639 $ref: '#/components/schemas/VideoResolutionConstant'
4642 description: Video file size in bytes
4645 description: Direct URL of the torrent file
4649 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4653 description: Direct URL of the video
4657 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4661 description: Frames per second of the video file
4665 description: URL dereferencing the output of ffprobe on the file
4666 VideoStreamingPlaylists:
4671 $ref: '#/components/schemas/id'
4679 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4680 VideoStreamingPlaylists-HLS:
4691 Video files associated to this playlist.
4693 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4695 $ref: '#/components/schemas/VideoFile'
4707 $ref: '#/components/schemas/Video/properties/id'
4709 $ref: '#/components/schemas/Video/properties/uuid'
4711 $ref: '#/components/schemas/Video/properties/name'
4715 description: object id for the video
4717 - $ref: '#/components/schemas/id'
4719 description: universal identifier for the video, that can be used across instances
4721 - $ref: '#/components/schemas/UUIDv4'
4727 example: 2017-10-01T10:52:46.396Z
4728 description: time at which the video object was first drafted
4732 example: 2018-10-01T10:52:46.396Z
4733 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4737 example: 2021-05-04T08:01:01.502Z
4738 description: last time the video's metadata was modified
4739 originallyPublishedAt:
4742 example: 2010-10-01T10:52:46.396Z
4743 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4746 - $ref: '#/components/schemas/VideoConstantNumber-Category'
4747 description: category in which the video is classified
4750 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
4751 description: licence under which the video is distributed
4754 - $ref: '#/components/schemas/VideoConstantString-Language'
4755 description: main language used in the video
4758 - $ref: '#/components/schemas/VideoPrivacyConstant'
4759 description: privacy policy used to distribute the video
4763 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4764 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4768 truncated description of the video, written in Markdown.
4769 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4774 description: duration of the video in seconds
4779 description: title of the video
4780 example: What is PeerTube?
4785 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4788 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4791 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4808 - $ref: '#/components/schemas/VideoStateConstant'
4809 description: represents the internal state of the video processing within the PeerTube instance
4813 - $ref: '#/components/schemas/VideoScheduledUpdate'
4821 $ref: '#/components/schemas/AccountSummary'
4823 $ref: '#/components/schemas/VideoChannelSummary'
4832 - $ref: '#/components/schemas/Video'
4837 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4838 description: path at which to get the full description of maximum `10000` characters
4841 description: A text tell the audience how to support the video creator
4842 example: Please support our work on https://soutenir.framasoft.org/en/ <3
4846 $ref: '#/components/schemas/VideoChannel'
4848 $ref: '#/components/schemas/Account'
4850 example: [flowers, gardening]
4868 - https://peertube2.cpy.re/tracker/announce
4869 - wss://peertube2.cpy.re/tracker/socket
4873 $ref: '#/components/schemas/VideoFile'
4875 WebTorrent/raw video files. If WebTorrent is disabled on the server:
4877 - field will be empty
4878 - video files will be found in `streamingPlaylists[].files` field
4882 $ref: '#/components/schemas/VideoStreamingPlaylists'
4884 HLS playlists/manifest files. If HLS is disabled on the server:
4886 - field will be empty
4887 - video files will be found in `files` field
4888 FileRedundancyInformation:
4891 $ref: '#/components/schemas/id'
4916 $ref: '#/components/schemas/id'
4923 $ref: '#/components/schemas/UUIDv4'
4930 $ref: '#/components/schemas/FileRedundancyInformation'
4934 $ref: '#/components/schemas/FileRedundancyInformation'
4935 VideoImportStateConstant:
4943 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4950 additionalProperties: false
4954 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
4955 required: [targetUrl]
4958 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
4959 required: [magnetUri]
4962 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
4963 required: [torrentfile]
4964 - $ref: '#/components/schemas/VideoUploadRequestCommon'
4973 - $ref: '#/components/schemas/id'
4977 description: remote URL where to find the import's source video
4978 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4982 description: magnet URI allowing to resolve the import's source video
4983 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
4984 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4989 description: Torrent file containing only the video file
4996 - $ref: '#/components/schemas/VideoImportStateConstant'
5012 - $ref: '#/components/schemas/Video'
5022 $ref: '#/components/schemas/VideoImport'
5026 $ref: '#/components/schemas/id'
5029 example: The video is a spam
5033 $ref: '#/components/schemas/AbusePredefinedReasons'
5035 $ref: '#/components/schemas/Account'
5037 $ref: '#/components/schemas/AbuseStateConstant'
5040 example: Decided to ban the server since it spams us regularly
5044 $ref: '#/components/schemas/VideoInfo'
5051 $ref: '#/components/schemas/id'
5062 $ref: '#/components/schemas/AccountSummary'
5066 $ref: '#/components/schemas/id'
5068 $ref: '#/components/schemas/Video/properties/id'
5080 $ref: '#/components/schemas/UUIDv4'
5098 $ref: '#/components/schemas/id'
5100 $ref: '#/components/schemas/UUIDv4'
5123 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5125 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5127 $ref: '#/components/schemas/AccountSummary'
5129 $ref: '#/components/schemas/VideoChannelSummary'
5133 $ref: '#/components/schemas/id'
5140 description: Text of the comment
5142 example: This video is wonderful!
5144 $ref: '#/components/schemas/id'
5148 - $ref: '#/components/schemas/id'
5150 $ref: '#/components/schemas/Video/properties/id'
5165 totalRepliesFromVideoAuthor:
5172 $ref: '#/components/schemas/Account'
5173 VideoCommentThreadTree:
5176 $ref: '#/components/schemas/VideoComment'
5180 $ref: '#/components/schemas/VideoCommentThreadTree'
5184 $ref: '#/components/schemas/VideoConstantString-Language'
5200 $ref: '#/components/schemas/id'
5217 $ref: '#/components/schemas/id'
5222 description: immutable name of the actor, used to find or mention it
5224 - $ref: '#/components/schemas/username'
5228 description: server on which the actor is resident
5229 hostRedundancyAllowed:
5231 description: whether this actor's host allows redundancy of its videos
5235 description: number of actors subscribed to by this actor, as seen by this instance
5239 description: number of followers of this actor, as seen by this instance
5247 $ref: '#/components/schemas/ActorImage'
5250 - $ref: '#/components/schemas/Actor'
5253 description: object id for the user tied to this account
5255 - $ref: '#/components/schemas/User/properties/id'
5258 description: editable name of the account, displayed in its representations
5263 description: text or bio displayed on the account's profile
5269 description: timestamp within the video, in seconds
5336 allowedForCurrentIP:
5338 requiresEmailVerification:
5356 $ref: '#/components/schemas/VideoResolutionSet'
5441 example: 16810141515
5544 requiresEmailVerification:
5559 description: Settings that apply to new users, if registration is enabled
5563 example: 16810141515
5569 description: Settings pertaining to transcoding jobs
5573 allowAdditionalExtensions:
5575 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5578 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5581 description: Amount of threads used by ffmpeg for 1 transcoding job
5584 description: Amount of transcoding jobs to execute in parallel
5590 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5593 description: Resolutions to transcode _new videos_ to
5613 description: WebTorrent-specific settings
5619 description: HLS-specific settings
5663 $ref: '#/components/schemas/id'
5665 $ref: '#/components/schemas/Actor'
5667 $ref: '#/components/schemas/Actor'
5670 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5683 PredefinedAbuseReasons:
5684 description: Reason categories that help triage reports
5702 $ref: '#/components/schemas/id'
5714 - activitypub-http-unicast
5715 - activitypub-http-broadcast
5716 - activitypub-http-fetcher
5717 - activitypub-follow
5723 - activitypub-refresher
5727 additionalProperties: true
5730 additionalProperties: true
5746 $ref: '#/components/schemas/id'
5751 $ref: '#/components/schemas/id'
5752 VideoUploadRequestCommon:
5755 description: Video name
5757 example: What is PeerTube?
5761 description: Channel id that will contain this video
5766 $ref: '#/components/schemas/VideoPrivacySet'
5768 $ref: '#/components/schemas/VideoCategorySet'
5770 $ref: '#/components/schemas/VideoLicenceSet'
5772 $ref: '#/components/schemas/VideoLanguageSet'
5774 description: Video description
5777 **[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)**
5779 description: Whether or not we wait transcoding before publish the video
5782 description: A text tell the audience how to support the video creator
5783 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5786 description: Whether or not this video contains sensitive content
5789 description: Video tags (maximum 5 tags each between 2 and 30 characters)
5802 description: Enable or disable comments for this video
5805 description: Enable or disable downloading for this video
5807 originallyPublishedAt:
5808 description: Date when the content was originally published
5812 $ref: '#/components/schemas/VideoScheduledUpdate'
5814 description: Video thumbnail file
5818 description: Video preview file
5824 VideoUploadRequestLegacy:
5826 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5832 description: Video file
5835 VideoUploadRequestResumable:
5837 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5843 description: Video filename including extension
5846 example: what_is_peertube.mp4
5848 description: Video thumbnail file
5852 description: Video preview file
5855 VideoUploadResponse:
5861 $ref: '#/components/schemas/Video/properties/id'
5863 $ref: '#/components/schemas/Video/properties/uuid'
5864 CommentThreadResponse:
5873 $ref: '#/components/schemas/VideoComment'
5874 CommentThreadPostResponse:
5877 $ref: '#/components/schemas/VideoComment'
5887 $ref: '#/components/schemas/Video'
5891 $ref: '#/components/schemas/Account'
5894 description: Automatically start playing the upcoming video after the currently playing video
5895 autoPlayNextVideoPlaylist:
5897 description: Automatically start playing the video on the playlist after the currently playing video
5900 description: Automatically start playing the video on the watch page
5910 description: The user email
5913 description: Has the user confirmed their email address?
5916 - $ref: '#/components/schemas/id'
5920 description: Auth plugin to use to authenticate the user
5924 noInstanceConfigWarningModal:
5929 $ref: '#/components/schemas/NSFWPolicy'
5931 $ref: '#/components/schemas/UserRole'
5940 description: Theme enabled by this user
5942 $ref: '#/components/schemas/username'
5946 $ref: '#/components/schemas/VideoChannel'
5949 description: The user video quota in bytes
5953 description: The user daily video quota in bytes
5957 description: Enable P2P in the player
5960 - $ref: '#/components/schemas/User'
5962 # optionally present fields: they require WITH_STATS scope
5965 description: Count of videos published
5968 description: Count of reports/abuses of which the user is a target
5969 abusesAcceptedCount:
5971 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
5974 description: Count of reports/abuses created by the user
5977 description: Count of comments published
5981 $ref: '#/components/schemas/username'
5983 $ref: '#/components/schemas/password'
5987 description: The user email
5990 description: The user video quota in bytes
5994 description: The user daily video quota in bytes
5997 $ref: '#/components/schemas/usernameChannel'
5999 $ref: '#/components/schemas/UserRole'
6001 $ref: '#/components/schemas/UserAdminFlags'
6012 description: The updated email of the user
6014 - $ref: '#/components/schemas/User/properties/email'
6017 description: Set the email as verified
6020 description: The updated video quota of the user in bytes
6023 description: The updated daily video quota of the user in bytes
6027 description: The auth plugin to use to authenticate the user
6028 example: 'peertube-plugin-auth-saml2'
6030 $ref: '#/components/schemas/UserRole'
6032 $ref: '#/components/schemas/UserAdminFlags'
6034 # see shared/models/users/user-update-me.model.ts:
6037 $ref: '#/components/schemas/password'
6039 $ref: '#/components/schemas/password'
6041 description: new email used for login and service communications
6043 - $ref: '#/components/schemas/User/properties/email'
6046 description: new name of the user in its representations
6051 description: new NSFW display policy
6058 description: whether to enable P2P in the player or not
6061 description: new preference regarding playing videos automatically
6064 description: new preference regarding playing following videos automatically
6065 autoPlayNextVideoPlaylist:
6067 description: new preference regarding playing following playlist videos automatically
6068 videosHistoryEnabled:
6070 description: whether to keep track of watched history or not
6075 description: list of languages to filter videos down to
6078 noInstanceConfigWarningModal:
6085 $ref: '#/components/schemas/id'
6092 description: Rating of the video
6099 $ref: '#/components/schemas/Video'
6106 description: Rating of the video
6113 description: immutable name of the user, used to find or mention its actor
6115 - $ref: '#/components/schemas/username'
6117 $ref: '#/components/schemas/password'
6121 description: email of the user, used for login or service communications
6124 description: editable name of the user, displayed in its representations
6129 description: channel base information used to create the first channel of the user
6132 $ref: '#/components/schemas/usernameChannel'
6134 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6144 pattern: /^[a-z0-9]$/
6147 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6150 pattern: /^[a-zA-Z0-9]$/
6153 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6154 OAuthToken-password:
6156 - $ref: '#/components/schemas/OAuthClient'
6166 $ref: '#/components/schemas/User/properties/username'
6168 $ref: '#/components/schemas/password'
6175 OAuthToken-refresh_token:
6177 - $ref: '#/components/schemas/OAuthClient'
6188 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6197 # GET/POST/PUT properties
6200 description: editable name of the channel, displayed in its representations
6201 example: Videos of Framasoft
6206 example: Videos made with <3 by Framasoft
6211 description: text shown by default on all videos of this channel, to tell the audience how to support it
6212 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6215 # GET-only properties
6219 - $ref: '#/components/schemas/id'
6235 $ref: '#/components/schemas/UUIDv4'
6238 - $ref: '#/components/schemas/VideoChannel'
6241 description: username of the channel to create
6243 - $ref: '#/components/schemas/usernameChannel'
6249 - $ref: '#/components/schemas/VideoChannel'
6251 bulkVideosSupportUpdate:
6253 description: Update the support field for all videos of this channel
6263 - $ref: '#/components/schemas/VideoChannel'
6264 - $ref: '#/components/schemas/Actor'
6269 name: 'media:peerLink'
6278 - application/x-bittorrent
6284 name: 'media:content'
6315 VideoCommentsForXML:
6350 description: video watch page URL
6353 description: video canonical URL
6357 description: video publication date
6360 description: video description
6363 description: video description
6366 description: publisher user name
6369 description: video category (MRSS)
6372 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6387 description: video embed path, relative to the canonical URL domain (MRSS)
6396 description: video watch path, relative to the canonical URL domain (MRSS)
6417 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6418 'media:description':
6425 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6428 description: main streamable file for the video
6438 - application/x-bittorrent
6447 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)
6450 - $ref: '#/components/schemas/MRSSPeerLink'
6451 - $ref: '#/components/schemas/MRSSGroupContent'
6452 NotificationSettingValue:
6469 $ref: '#/components/schemas/id'
6473 Notification type, following the `UserNotificationType` enum:
6475 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6477 - `2` NEW_COMMENT_ON_MY_VIDEO
6479 - `3` NEW_ABUSE_FOR_MODERATORS
6481 - `4` BLACKLIST_ON_MY_VIDEO
6483 - `5` UNBLACKLIST_ON_MY_VIDEO
6485 - `6` MY_VIDEO_PUBLISHED
6487 - `7` MY_VIDEO_IMPORT_SUCCESS
6489 - `8` MY_VIDEO_IMPORT_ERROR
6491 - `9` NEW_USER_REGISTRATION
6495 - `11` COMMENT_MENTION
6497 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6499 - `13` NEW_INSTANCE_FOLLOWER
6501 - `14` AUTO_INSTANCE_FOLLOWING
6507 - $ref: '#/components/schemas/VideoInfo'
6511 $ref: '#/components/schemas/ActorInfo'
6517 $ref: '#/components/schemas/id'
6520 $ref: '#/components/schemas/VideoInfo'
6525 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6535 $ref: '#/components/schemas/id'
6539 $ref: '#/components/schemas/VideoInfo'
6541 $ref: '#/components/schemas/ActorInfo'
6547 $ref: '#/components/schemas/id'
6550 - $ref: '#/components/schemas/VideoInfo'
6556 $ref: '#/components/schemas/id'
6559 - $ref: '#/components/schemas/VideoInfo'
6563 - $ref: '#/components/schemas/ActorInfo'
6569 $ref: '#/components/schemas/id'
6571 $ref: '#/components/schemas/ActorInfo'
6599 NotificationListResponse:
6608 $ref: '#/components/schemas/Notification'
6613 example: peertube-plugin-auth-ldap
6641 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6644 additionalProperties: true
6660 $ref: '#/components/schemas/Plugin'
6667 description: User can stream multiple times in a permanent live
6676 description: RTMP stream key to use to stream into this live video
6680 description: User can stream multiple times in a permanent live
6687 'https://search.example.org/api/v1/search/videos':
6689 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6692 description: successful operation
6696 $ref: '#/components/schemas/VideoListResponse'