6 name: PeerTube Community
7 url: https://joinpeertube.org
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
92 "msg": "Invalid value",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
98 "title": "Bad Request",
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
108 ### Deprecated error fields
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
128 You can get details about the current state of your rate limit by reading the
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
144 |------------------------- ---|
148 | `/live/segments-sha256/*` |
149 | `/.well-known/webfinger` |
151 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
153 url: https://docs.joinpeertube.org/api-rest-reference.html
157 As a visitor, you can use this API to open an account (if registrations are open on
158 that PeerTube instance). As an admin, you should use the dedicated [User creation
159 API](#operation/addUser) instead.
161 x-displayName: Login/Logout
163 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
166 Accounts encompass remote accounts discovered across the federation,
167 and correspond to the main Actor, along with video channels a user can create, which
170 When a comment is posted, it is done with your Account's Actor.
173 Using some features of PeerTube require authentication, for which User
174 provide different levels of permission as well as associated user
175 information. Each user has a corresponding local Account for federation.
178 Operations related to your own User, when logged-in.
179 - name: My Subscriptions
181 Operations related to your subscriptions to video channels, their
182 new videos, and how to keep up to date with their latest publications!
185 Operations related to your watch history.
186 - name: My Notifications
188 Notifications following new videos, follows or reports. They allow you
189 to keep track of the interactions and overall important information that
190 concerns you. You MAY set per-notification type delivery preference, to
191 receive the info either by mail, by in-browser notification or both.
194 Each server exposes public information regarding supported videos and
198 Jobs are long-running tasks enqueued and processed by the instance
199 itself. No additional worker registration is currently available.
200 - name: Instance Follows
202 Managing servers which the instance interacts with is crucial to the
203 concept of federation in PeerTube and external video indexation. The PeerTube
204 server then deals with inter-server ActivityPub operations and propagates
205 information across its social graph by posting activities to actors' inbox
208 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
209 - name: Instance Redundancy
211 Redundancy is part of the inter-server solidarity that PeerTube fosters.
212 Manage the list of instances you wish to help by seeding their videos according
213 to the policy of video selection of your choice. Note that you have a similar functionality
214 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
216 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
219 Managing plugins installed from a local path or from NPM, or search for new ones.
221 url: https://docs.joinpeertube.org/api-plugins
224 Abuses deal with reports of local or remote videos/comments/accounts alike.
227 Operations dealing with listing, uploading, fetching or modifying videos.
230 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
234 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
235 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
237 You can upload videos more reliably by using the resumable variant. Its protocol lets
238 you resume an upload operation after a network interruption or other transmission failure,
239 saving time and bandwidth in the event of network failures.
241 Favor using resumable uploads in any of the following cases:
242 - You are transferring large files
243 - The likelihood of a network interruption is high
244 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
245 such as a mobile device
249 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
250 - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file
253 The import function is practical when the desired video/audio is available online. It makes PeerTube
254 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
255 - name: Video Imports
256 description: Operations dealing with listing, adding and removing video imports.
257 - name: Channels Sync
258 description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms
259 - name: Video Captions
260 description: Operations dealing with listing, adding and removing closed captions of a video.
261 - name: Video Channels
262 description: Operations dealing with the creation, modification and listing of videos within a channel.
263 - name: Video Comments
265 Operations dealing with comments to a video. Comments are organized in threads: adding a
266 comment in response to the video starts a thread, adding a reply to a comment adds it to
267 its root comment thread.
269 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
271 description: Like/dislike a video.
272 - name: Video Playlists
273 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
275 description: Operations on video files
276 - name: Video Transcoding
277 description: Video transcoding related operations
279 description: Video statistics
281 description: Server syndication feeds
284 The search helps to find _videos_ or _channels_ from within the instance and beyond.
285 Videos from other instances federated by the instance (that is, instances
286 followed by the instance) can be found via keywords and other criteria of
289 Administrators can also enable the use of a remote search system, indexing
290 videos and channels not could be not federated by the instance.
292 description: Get and update the custom homepage
293 - name: Video Mirroring
295 PeerTube instances can mirror videos from one another, and help distribute some videos.
297 For importing videos as your own, refer to [video imports](#operation/importVideo).
326 - Video Ownership Change
347 - Instance Redundancy
357 summary: Get an account
358 operationId: getAccount
360 - $ref: '#/components/parameters/name'
363 description: successful operation
367 $ref: '#/components/schemas/Account'
369 description: account not found
371 '/accounts/{name}/videos':
376 summary: 'List videos of an account'
377 operationId: getAccountVideos
379 - $ref: '#/components/parameters/name'
380 - $ref: '#/components/parameters/categoryOneOf'
381 - $ref: '#/components/parameters/isLive'
382 - $ref: '#/components/parameters/tagsOneOf'
383 - $ref: '#/components/parameters/tagsAllOf'
384 - $ref: '#/components/parameters/licenceOneOf'
385 - $ref: '#/components/parameters/languageOneOf'
386 - $ref: '#/components/parameters/nsfw'
387 - $ref: '#/components/parameters/isLocal'
388 - $ref: '#/components/parameters/include'
389 - $ref: '#/components/parameters/privacyOneOf'
390 - $ref: '#/components/parameters/hasHLSFiles'
391 - $ref: '#/components/parameters/hasWebtorrentFiles'
392 - $ref: '#/components/parameters/skipCount'
393 - $ref: '#/components/parameters/start'
394 - $ref: '#/components/parameters/count'
395 - $ref: '#/components/parameters/videosSort'
398 description: successful operation
402 $ref: '#/components/schemas/VideoListResponse'
406 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
407 .then(function(response) {
408 return response.json()
409 }).then(function(data) {
415 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
421 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
423 http = Net::HTTP.new(uri.host, uri.port)
426 response = http.get(uri.request_uri)
428 puts JSON.parse(response.read_body)
433 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
438 '/accounts/{name}/followers':
442 summary: 'List followers of an account'
445 operationId: getAccountFollowers
447 - $ref: '#/components/parameters/name'
448 - $ref: '#/components/parameters/start'
449 - $ref: '#/components/parameters/count'
450 - $ref: '#/components/parameters/followersSort'
451 - $ref: '#/components/parameters/search'
454 description: successful operation
466 $ref: '#/components/schemas/Follow'
472 summary: List accounts
473 operationId: getAccounts
475 - $ref: '#/components/parameters/start'
476 - $ref: '#/components/parameters/count'
477 - $ref: '#/components/parameters/sort'
480 description: successful operation
486 $ref: '#/components/schemas/Account'
492 summary: Get instance public configuration
493 operationId: getConfig
496 description: successful operation
500 $ref: '#/components/schemas/ServerConfig'
503 externalValue: https://peertube2.cpy.re/api/v1/config
507 summary: Get instance "About" information
508 operationId: getAbout
513 description: successful operation
517 $ref: '#/components/schemas/ServerConfigAbout'
520 externalValue: https://peertube2.cpy.re/api/v1/config/about
524 summary: Get instance runtime configuration
525 operationId: getCustomConfig
533 description: successful operation
537 $ref: '#/components/schemas/ServerConfigCustom'
539 summary: Set instance runtime configuration
540 operationId: putCustomConfig
548 description: successful operation
550 x-summary: field inconsistencies
553 - the emailer is disabled and the instance is open to registrations
554 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
556 summary: Delete instance runtime configuration
557 operationId: delCustomConfig
565 description: successful operation
567 /custom-pages/homepage/instance:
569 summary: Get instance custom homepage
574 description: No homepage set
576 description: successful operation
580 $ref: '#/components/schemas/CustomHomepage'
582 summary: Set instance custom homepage
596 description: content of the homepage, that will be injected in the client
599 description: successful operation
603 summary: Pause job queue
611 description: successful operation
615 summary: Resume job queue
623 description: successful operation
627 summary: List instance jobs
638 description: The state of the job ('' for for no filter)
648 - $ref: '#/components/parameters/jobType'
649 - $ref: '#/components/parameters/start'
650 - $ref: '#/components/parameters/count'
651 - $ref: '#/components/parameters/sort'
654 description: successful operation
667 $ref: '#/components/schemas/Job'
673 summary: List instances following the server
675 - $ref: '#/components/parameters/followState'
676 - $ref: '#/components/parameters/actorType'
677 - $ref: '#/components/parameters/start'
678 - $ref: '#/components/parameters/count'
679 - $ref: '#/components/parameters/sort'
682 description: successful operation
694 $ref: '#/components/schemas/Follow'
696 '/server/followers/{nameWithHost}':
698 summary: Remove or reject a follower to your server
708 description: The remote actor handle to remove from your followers
714 description: successful operation
716 description: follower not found
718 '/server/followers/{nameWithHost}/reject':
720 summary: Reject a pending follower to your server
730 description: The remote actor handle to remove from your followers
736 description: successful operation
738 description: follower not found
740 '/server/followers/{nameWithHost}/accept':
742 summary: Accept a pending follower to your server
752 description: The remote actor handle to remove from your followers
758 description: successful operation
760 description: follower not found
766 summary: List instances followed by the server
768 - $ref: '#/components/parameters/followState'
769 - $ref: '#/components/parameters/actorType'
770 - $ref: '#/components/parameters/start'
771 - $ref: '#/components/parameters/count'
772 - $ref: '#/components/parameters/sort'
775 description: successful operation
787 $ref: '#/components/schemas/Follow'
794 summary: Follow a list of actors (PeerTube instance, channel or account)
797 description: successful operation
799 description: cannot follow a non-HTTPS server
818 '/server/following/{hostOrHandle}':
820 summary: Unfollow an actor (PeerTube instance, channel or account)
830 description: The hostOrHandle to unfollow
835 description: successful operation
837 description: host or handle not found
841 summary: Create a user
850 description: user created
854 $ref: '#/components/schemas/AddUserResponse'
860 id: '$response.body#/user/id'
865 id: '$response.body#/user/id'
870 id: '$response.body#/user/id'
872 description: insufficient authority to create an admin or moderator
877 $ref: '#/components/schemas/AddUser'
879 If the smtp server is configured, you can leave the password empty and an email will be sent
880 asking the user to set it first.
884 operationId: getUsers
891 - $ref: '#/components/parameters/usersSearch'
892 - $ref: '#/components/parameters/usersBlocked'
893 - $ref: '#/components/parameters/start'
894 - $ref: '#/components/parameters/count'
895 - $ref: '#/components/parameters/usersSort'
898 description: successful operation
904 $ref: '#/components/schemas/User'
908 - $ref: '#/components/parameters/id'
910 summary: Delete a user
919 description: successful operation
930 description: include statistics about the user (only available as a moderator/admin)
935 x-summary: successful operation
937 As an admin/moderator, you can request a response augmented with statistics about the user's
938 moderation relations and videos usage, by using the `withStats` parameter.
943 - $ref: '#/components/schemas/User'
944 - $ref: '#/components/schemas/UserWithStats'
946 summary: Update a user
954 description: successful operation
959 $ref: '#/components/schemas/UpdateUser'
962 /oauth-clients/local:
964 summary: Login prerequisite
965 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
966 operationId: getOAuthClient
971 description: successful operation
975 $ref: '#/components/schemas/OAuthClient'
977 UseOAuthClientToLogin:
978 operationId: getOAuthToken
980 client_id: '$response.body#/client_id'
981 client_secret: '$response.body#/client_secret'
985 API="https://peertube2.cpy.re/api/v1"
988 curl -s "$API/oauth-clients/local"
993 operationId: getOAuthToken
994 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
999 application/x-www-form-urlencoded:
1002 - $ref: '#/components/schemas/OAuthToken-password'
1003 - $ref: '#/components/schemas/OAuthToken-refresh_token'
1005 propertyName: grant_type
1007 password: '#/components/schemas/OAuthToken-password'
1008 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
1011 description: successful operation
1022 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
1023 description: valid for 1 day
1026 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
1027 description: valid for 2 weeks
1032 refresh_token_expires_in:
1037 x-summary: client or credentials are invalid
1039 Disambiguate via `type`:
1040 - `invalid_client` for an unmatched `client_id`
1041 - `invalid_grant` for unmatched credentials
1043 x-summary: token expired
1045 Disambiguate via `type`:
1046 - default value for a regular authentication failure
1047 - `invalid_token` for an expired token
1052 API="https://peertube2.cpy.re/api/v1"
1053 USERNAME="<your_username>"
1054 PASSWORD="<your_password>"
1057 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1058 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1059 curl -s "$API/users/token" \
1060 --data client_id="$client_id" \
1061 --data client_secret="$client_secret" \
1062 --data grant_type=password \
1063 --data username="$USERNAME" \
1064 --data password="$PASSWORD" \
1065 | jq -r ".access_token"
1067 /users/revoke-token:
1070 description: Revokes your access token and its associated refresh token, destroying your current session.
1071 operationId: revokeOAuthToken
1078 description: successful operation
1082 summary: Register a user
1083 operationId: registerUser
1089 description: successful operation
1094 $ref: '#/components/schemas/RegisterUser'
1097 /users/{id}/verify-email:
1099 summary: Verify a user
1100 operationId: verifyUser
1102 Following a user registration, the new user will receive an email asking to click a link
1103 containing a secret.
1108 - $ref: '#/components/parameters/id'
1121 - verificationString
1124 description: successful operation
1126 description: invalid verification string
1128 description: user not found
1130 /users/ask-send-verify-email:
1132 summary: Resend user verification link
1133 operationId: resendEmailToVerifyUser
1139 description: successful operation
1143 summary: Get my user information
1144 operationId: getUserInfo
1152 description: successful operation
1158 $ref: '#/components/schemas/User'
1160 summary: Update my user information
1161 operationId: putUserInfo
1169 description: successful operation
1174 $ref: '#/components/schemas/UpdateMe'
1177 /users/me/videos/imports:
1179 summary: Get video imports of my user
1187 - $ref: '#/components/parameters/start'
1188 - $ref: '#/components/parameters/count'
1189 - $ref: '#/components/parameters/sort'
1192 description: successful operation
1196 $ref: '#/components/schemas/VideoImportsList'
1198 /users/me/video-quota-used:
1200 summary: Get my user used quota
1208 description: successful operation
1216 description: The user video quota used so far in bytes
1217 example: 16810141515
1218 videoQuotaUsedDaily:
1220 description: The user video quota used today in bytes
1223 '/users/me/videos/{videoId}/rating':
1225 summary: Get rate of my user for a video
1235 description: The video id
1237 $ref: '#/components/schemas/Video/properties/id'
1240 description: successful operation
1244 $ref: '#/components/schemas/GetMeVideoRating'
1248 summary: Get videos of my user
1256 - $ref: '#/components/parameters/start'
1257 - $ref: '#/components/parameters/count'
1258 - $ref: '#/components/parameters/sort'
1261 description: successful operation
1265 $ref: '#/components/schemas/VideoListResponse'
1267 /users/me/subscriptions:
1269 summary: Get my user subscriptions
1276 - $ref: '#/components/parameters/start'
1277 - $ref: '#/components/parameters/count'
1278 - $ref: '#/components/parameters/sort'
1281 description: successful operation
1285 $ref: '#/components/schemas/VideoChannelList'
1289 summary: Add subscription to my user
1302 description: uri of the video channels to subscribe to
1308 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1311 description: successful operation
1313 /users/me/subscriptions/exist:
1315 summary: Get if subscriptions exist for my user
1322 - $ref: '#/components/parameters/subscriptionsUris'
1325 description: successful operation
1331 /users/me/subscriptions/videos:
1333 summary: List videos of subscriptions of my user
1341 - $ref: '#/components/parameters/categoryOneOf'
1342 - $ref: '#/components/parameters/isLive'
1343 - $ref: '#/components/parameters/tagsOneOf'
1344 - $ref: '#/components/parameters/tagsAllOf'
1345 - $ref: '#/components/parameters/licenceOneOf'
1346 - $ref: '#/components/parameters/languageOneOf'
1347 - $ref: '#/components/parameters/nsfw'
1348 - $ref: '#/components/parameters/isLocal'
1349 - $ref: '#/components/parameters/include'
1350 - $ref: '#/components/parameters/privacyOneOf'
1351 - $ref: '#/components/parameters/hasHLSFiles'
1352 - $ref: '#/components/parameters/hasWebtorrentFiles'
1353 - $ref: '#/components/parameters/skipCount'
1354 - $ref: '#/components/parameters/start'
1355 - $ref: '#/components/parameters/count'
1356 - $ref: '#/components/parameters/videosSort'
1359 description: successful operation
1363 $ref: '#/components/schemas/VideoListResponse'
1365 '/users/me/subscriptions/{subscriptionHandle}':
1367 summary: Get subscription of my user
1374 - $ref: '#/components/parameters/subscriptionHandle'
1377 description: successful operation
1381 $ref: '#/components/schemas/VideoChannel'
1383 summary: Delete subscription of my user
1390 - $ref: '#/components/parameters/subscriptionHandle'
1393 description: successful operation
1395 /users/me/notifications:
1397 summary: List my notifications
1405 description: only list unread notifications
1408 - $ref: '#/components/parameters/start'
1409 - $ref: '#/components/parameters/count'
1410 - $ref: '#/components/parameters/sort'
1413 description: successful operation
1417 $ref: '#/components/schemas/NotificationListResponse'
1419 /users/me/notifications/read:
1421 summary: Mark notifications as read by their id
1434 description: ids of the notifications to mark as read
1441 description: successful operation
1443 /users/me/notifications/read-all:
1445 summary: Mark all my notification as read
1452 description: successful operation
1454 /users/me/notification-settings:
1456 summary: Update my notification settings
1467 newVideoFromSubscription:
1468 $ref: '#/components/schemas/NotificationSettingValue'
1469 newCommentOnMyVideo:
1470 $ref: '#/components/schemas/NotificationSettingValue'
1472 $ref: '#/components/schemas/NotificationSettingValue'
1473 videoAutoBlacklistAsModerator:
1474 $ref: '#/components/schemas/NotificationSettingValue'
1476 $ref: '#/components/schemas/NotificationSettingValue'
1478 $ref: '#/components/schemas/NotificationSettingValue'
1479 myVideoImportFinished:
1480 $ref: '#/components/schemas/NotificationSettingValue'
1482 $ref: '#/components/schemas/NotificationSettingValue'
1483 newUserRegistration:
1484 $ref: '#/components/schemas/NotificationSettingValue'
1486 $ref: '#/components/schemas/NotificationSettingValue'
1487 newInstanceFollower:
1488 $ref: '#/components/schemas/NotificationSettingValue'
1489 autoInstanceFollowing:
1490 $ref: '#/components/schemas/NotificationSettingValue'
1493 description: successful operation
1495 /users/me/history/videos:
1497 summary: List watched videos history
1503 - $ref: '#/components/parameters/start'
1504 - $ref: '#/components/parameters/count'
1505 - $ref: '#/components/parameters/search'
1508 description: successful operation
1512 $ref: '#/components/schemas/VideoListResponse'
1514 /users/me/history/videos/{videoId}:
1516 summary: Delete history element
1526 $ref: '#/components/schemas/Video/properties/id'
1529 description: successful operation
1531 /users/me/history/videos/remove:
1533 summary: Clear video history
1540 multipart/form-data:
1545 description: history before this date will be deleted
1550 description: successful operation
1552 /users/me/avatar/pick:
1554 summary: Update my user avatar
1561 description: successful operation
1570 $ref: '#/components/schemas/ActorImage'
1572 description: image file too large
1574 X-File-Maximum-Size:
1578 description: Maximum file size for the avatar
1581 multipart/form-data:
1586 description: The file to upload
1591 contentType: image/png, image/jpeg
1595 summary: Delete my avatar
1602 description: successful operation
1606 summary: List video ownership changes
1608 - Video Ownership Change
1613 description: successful operation
1615 '/videos/ownership/{id}/accept':
1617 summary: Accept ownership change request
1619 - Video Ownership Change
1623 - $ref: '#/components/parameters/idOrUUID'
1626 description: successful operation
1628 description: cannot terminate an ownership change of another user
1630 description: video ownership change not found
1632 '/videos/ownership/{id}/refuse':
1634 summary: Refuse ownership change request
1636 - Video Ownership Change
1640 - $ref: '#/components/parameters/idOrUUID'
1643 description: successful operation
1645 description: cannot terminate an ownership change of another user
1647 description: video ownership change not found
1649 '/videos/{id}/give-ownership':
1651 summary: Request ownership change
1653 - Video Ownership Change
1657 - $ref: '#/components/parameters/idOrUUID'
1661 application/x-www-form-urlencoded:
1671 description: successful operation
1673 description: changing video ownership to a remote account is not supported yet
1675 description: video not found
1677 /videos/{id}/studio/edit:
1679 summary: Create a studio task
1683 description: Create a task to edit a video (cut, add intro/outro etc)
1687 - $ref: '#/components/parameters/idOrUUID'
1691 application/x-www-form-urlencoded:
1693 $ref: '#/components/schemas/VideoStudioCreateTask'
1696 description: successful operation
1698 description: incorrect parameters
1700 description: video not found
1704 summary: List videos
1705 operationId: getVideos
1709 - $ref: '#/components/parameters/categoryOneOf'
1710 - $ref: '#/components/parameters/isLive'
1711 - $ref: '#/components/parameters/tagsOneOf'
1712 - $ref: '#/components/parameters/tagsAllOf'
1713 - $ref: '#/components/parameters/licenceOneOf'
1714 - $ref: '#/components/parameters/languageOneOf'
1715 - $ref: '#/components/parameters/nsfw'
1716 - $ref: '#/components/parameters/isLocal'
1717 - $ref: '#/components/parameters/include'
1718 - $ref: '#/components/parameters/privacyOneOf'
1719 - $ref: '#/components/parameters/hasHLSFiles'
1720 - $ref: '#/components/parameters/hasWebtorrentFiles'
1721 - $ref: '#/components/parameters/skipCount'
1722 - $ref: '#/components/parameters/start'
1723 - $ref: '#/components/parameters/count'
1724 - $ref: '#/components/parameters/videosSort'
1727 description: successful operation
1731 $ref: '#/components/schemas/VideoListResponse'
1735 summary: List available video categories
1736 operationId: getCategories
1741 description: successful operation
1750 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1754 summary: List available video licences
1755 operationId: getLicences
1760 description: successful operation
1769 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1773 summary: List available video languages
1774 operationId: getLanguages
1779 description: successful operation
1788 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1792 summary: List available video privacy policies
1793 operationId: getPrivacyPolicies
1798 description: successful operation
1807 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1811 summary: Update a video
1812 operationId: putVideo
1818 - $ref: '#/components/parameters/idOrUUID'
1821 description: successful operation
1824 multipart/form-data:
1829 description: Video thumbnail file
1833 description: Video preview file
1837 $ref: '#/components/schemas/VideoCategorySet'
1839 $ref: '#/components/schemas/VideoLicenceSet'
1841 $ref: '#/components/schemas/VideoLanguageSet'
1843 $ref: '#/components/schemas/VideoPrivacySet'
1845 description: Video description
1848 description: Whether or not we wait transcoding before publish the video
1851 description: A text tell the audience how to support the video creator
1852 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1855 description: Whether or not this video contains sensitive content
1858 description: Video name
1863 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1872 description: Enable or disable comments for this video
1875 description: Enable or disable downloading for this video
1877 originallyPublishedAt:
1878 description: Date when the content was originally published
1882 $ref: '#/components/schemas/VideoScheduledUpdate'
1885 contentType: image/jpeg
1887 contentType: image/jpeg
1889 summary: Get a video
1890 operationId: getVideo
1894 - $ref: '#/components/parameters/idOrUUID'
1897 description: successful operation
1901 $ref: '#/components/schemas/VideoDetails'
1903 summary: Delete a video
1904 operationId: delVideo
1910 - $ref: '#/components/parameters/idOrUUID'
1913 description: successful operation
1915 '/videos/{id}/description':
1917 summary: Get complete video description
1918 operationId: getVideoDesc
1922 - $ref: '#/components/parameters/idOrUUID'
1925 description: successful operation
1934 **[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)**
1936 '/videos/{id}/source':
1938 summary: Get video source file metadata
1939 operationId: getVideoSource
1943 - $ref: '#/components/parameters/idOrUUID'
1946 description: successful operation
1950 $ref: '#/components/schemas/VideoSource'
1952 '/videos/{id}/views':
1954 summary: Notify user is watching a video
1955 description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
1956 operationId: addView
1960 - $ref: '#/components/parameters/idOrUUID'
1965 $ref: '#/components/schemas/UserViewingVideo'
1969 description: successful operation
1971 '/videos/{id}/watching':
1973 summary: Set watching progress of a video
1975 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
1981 - $ref: '#/components/parameters/idOrUUID'
1986 $ref: '#/components/schemas/UserViewingVideo'
1990 description: successful operation
1992 '/videos/{id}/stats/overall':
1994 summary: Get overall stats of a video
2000 - $ref: '#/components/parameters/idOrUUID'
2003 description: Filter stats by start date
2009 description: Filter stats by end date
2015 description: successful operation
2019 $ref: '#/components/schemas/VideoStatsOverall'
2021 '/videos/{id}/stats/retention':
2023 summary: Get retention stats of a video
2029 - $ref: '#/components/parameters/idOrUUID'
2032 description: successful operation
2036 $ref: '#/components/schemas/VideoStatsRetention'
2038 '/videos/{id}/stats/timeseries/{metric}':
2040 summary: Get timeserie stats of a video
2046 - $ref: '#/components/parameters/idOrUUID'
2051 description: The metric to get
2056 - 'aggregateWatchTime'
2059 description: Filter stats by start date
2065 description: Filter stats by end date
2071 description: successful operation
2075 $ref: '#/components/schemas/VideoStatsTimeserie'
2079 summary: Upload a video
2080 description: Uses a single request to upload a video.
2081 operationId: uploadLegacy
2089 description: successful operation
2093 $ref: '#/components/schemas/VideoUploadResponse'
2095 description: video didn't pass upload filter
2097 description: upload has timed out
2099 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2101 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2102 - `quota_reached` for quota limits whether daily or global
2104 X-File-Maximum-Size:
2108 description: Maximum file size for the video
2110 description: video type unsupported
2112 description: video unreadable
2115 multipart/form-data:
2117 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2120 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2122 contentType: image/jpeg
2124 contentType: image/jpeg
2129 USERNAME="<your_username>"
2130 PASSWORD="<your_password>"
2131 FILE_PATH="<your_file_path>"
2132 CHANNEL_ID="<your_channel_id>"
2134 API="https://peertube2.cpy.re/api/v1"
2137 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2138 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2139 token=$(curl -s "$API/users/token" \
2140 --data client_id="$client_id" \
2141 --data client_secret="$client_secret" \
2142 --data grant_type=password \
2143 --data username="$USERNAME" \
2144 --data password="$PASSWORD" \
2145 | jq -r ".access_token")
2148 curl -s "$API/videos/upload" \
2149 -H "Authorization: Bearer $token" \
2151 --form videofile=@"$FILE_PATH" \
2152 --form channelId=$CHANNEL_ID \
2155 /videos/upload-resumable:
2157 summary: Initialize the resumable upload of a video
2158 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2159 operationId: uploadResumableInit
2166 - name: X-Upload-Content-Length
2172 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2173 - name: X-Upload-Content-Type
2180 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2185 $ref: '#/components/schemas/VideoUploadRequestResumable'
2188 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2190 description: created
2196 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2202 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2204 Disambiguate via `type`:
2205 - `max_file_size_reached` for the absolute file size limit
2206 - `quota_reached` for quota limits whether daily or global
2208 description: video type unsupported
2210 summary: Send chunk for the resumable upload of a video
2211 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
2212 operationId: uploadResumable
2223 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2224 not valid anymore and you need to initialize a new upload.
2227 - name: Content-Range
2231 example: bytes 0-262143/2469036
2234 Specifies the bytes in the file that the request is uploading.
2236 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2237 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2238 - name: Content-Length
2245 Size of the chunk that the request is sending.
2247 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2248 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2251 application/octet-stream:
2257 description: last chunk received
2265 $ref: '#/components/schemas/VideoUploadResponse'
2267 description: resume incomplete
2272 example: bytes=0-262143
2278 description: video didn't pass upload filter
2280 description: upload not found
2282 description: chunk doesn't match range
2284 description: video unreadable
2286 description: too many concurrent requests
2288 description: upload is already being processed
2295 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2296 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2297 operationId: uploadResumableCancel
2308 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2309 not valid anymore and the upload session has already been deleted with its data ;-)
2312 - name: Content-Length
2320 description: upload cancelled
2327 description: upload not found
2331 summary: Import a video
2332 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2333 operationId: importVideo
2341 multipart/form-data:
2343 $ref: '#/components/schemas/VideoCreateImport'
2346 contentType: application/x-bittorrent
2348 contentType: image/jpeg
2350 contentType: image/jpeg
2353 description: successful operation
2357 $ref: '#/components/schemas/VideoUploadResponse'
2359 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2361 description: video didn't pass pre-import filter
2363 description: HTTP or Torrent/magnetURI import not enabled
2365 /videos/imports/{id}/cancel:
2367 summary: Cancel video import
2368 description: Cancel a pending video import
2374 - $ref: '#/components/parameters/id'
2377 description: successful operation
2379 /videos/imports/{id}:
2381 summary: Delete video import
2382 description: Delete ended video import
2388 - $ref: '#/components/parameters/id'
2391 description: successful operation
2395 summary: Create a live
2396 operationId: addLive
2404 description: successful operation
2408 $ref: '#/components/schemas/VideoUploadResponse'
2410 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2412 Disambiguate via `type`:
2413 - default type for a validation error
2414 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2416 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2418 Disambiguate via `type`:
2419 - `live_not_enabled` for a disabled live feature
2420 - `live_not_allowing_replay` for a disabled replay feature
2421 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2422 - `max_user_lives_limit_reached` for the user concurrent live limit
2425 multipart/form-data:
2430 description: Channel id that will contain this live video
2435 description: User can stream multiple times in a permanent live
2438 description: User can select live latency mode if enabled by the instance
2439 $ref: '#/components/schemas/LiveVideoLatencyMode'
2441 description: Live video/replay thumbnail file
2445 description: Live video/replay preview file
2449 $ref: '#/components/schemas/VideoPrivacySet'
2451 $ref: '#/components/schemas/VideoCategorySet'
2453 $ref: '#/components/schemas/VideoLicenceSet'
2455 $ref: '#/components/schemas/VideoLanguageSet'
2457 description: Live video/replay description
2460 description: A text tell the audience how to support the creator
2461 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2464 description: Whether or not this live video/replay contains sensitive content
2467 description: Live video/replay name
2472 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2481 description: Enable or disable comments for this live video/replay
2484 description: Enable or disable downloading for the replay of this live video
2491 contentType: image/jpeg
2493 contentType: image/jpeg
2497 summary: Get information about a live
2498 operationId: getLiveId
2505 - $ref: '#/components/parameters/idOrUUID'
2508 description: successful operation
2512 $ref: '#/components/schemas/LiveVideoResponse'
2514 summary: Update information about a live
2515 operationId: updateLiveId
2522 - $ref: '#/components/parameters/idOrUUID'
2527 $ref: '#/components/schemas/LiveVideoUpdate'
2530 description: successful operation
2532 description: bad parameters or trying to update a live that has already started
2534 description: trying to save replay of the live but saving replay is not enabled on the instance
2535 /videos/live/{id}/sessions:
2537 summary: List live sessions
2538 description: List all sessions created in a particular live
2544 - $ref: '#/components/parameters/idOrUUID'
2547 description: successful operation
2559 $ref: '#/components/schemas/LiveVideoSessionResponse'
2560 /videos/{id}/live-session:
2562 summary: Get live session of a replay
2563 description: If the video is a replay of a live, you can find the associated live session using this endpoint
2569 - $ref: '#/components/parameters/idOrUUID'
2572 description: successful operation
2576 $ref: '#/components/schemas/LiveVideoSessionResponse'
2580 summary: List my abuses
2581 operationId: getMyAbuses
2590 description: only list the report with this id
2596 $ref: '#/components/schemas/AbuseStateSet'
2597 - $ref: '#/components/parameters/abusesSort'
2598 - $ref: '#/components/parameters/start'
2599 - $ref: '#/components/parameters/count'
2602 description: successful operation
2614 $ref: '#/components/schemas/Abuse'
2618 summary: List abuses
2619 operationId: getAbuses
2629 description: only list the report with this id
2632 - name: predefinedReason
2634 description: predefined reason the listed reports should contain
2636 $ref: '#/components/schemas/PredefinedAbuseReasons'
2639 description: plain search that will match with video titles, reporter names and more
2645 $ref: '#/components/schemas/AbuseStateSet'
2646 - name: searchReporter
2648 description: only list reports of a specific reporter
2651 - name: searchReportee
2652 description: only list reports of a specific reportee
2658 description: only list reports of a specific video
2661 - name: searchVideoChannel
2663 description: only list reports of a specific video channel
2668 description: only list deleted or blocklisted videos
2676 description: only list account, comment or video reports
2683 - $ref: '#/components/parameters/start'
2684 - $ref: '#/components/parameters/count'
2685 - $ref: '#/components/parameters/abusesSort'
2688 description: successful operation
2700 $ref: '#/components/schemas/Abuse'
2702 summary: Report an abuse
2715 description: Reason why the user reports this video
2720 $ref: '#/components/schemas/PredefinedAbuseReasons'
2725 description: Video id to report
2727 - $ref: '#/components/schemas/Video/properties/id'
2731 description: Timestamp in the video that marks the beginning of the report
2736 description: Timestamp in the video that marks the ending of the report
2742 description: Comment id to report
2744 - $ref: '#/components/schemas/VideoComment/properties/id'
2749 description: Account id to report
2755 description: successful operation
2765 $ref: '#/components/schemas/id'
2767 description: incorrect request parameters
2769 '/abuses/{abuseId}':
2771 summary: Update an abuse
2779 - $ref: '#/components/parameters/abuseId'
2787 $ref: '#/components/schemas/AbuseStateSet'
2790 description: Update the report comment visible only to the moderation team
2795 description: successful operation
2797 description: abuse not found
2801 summary: Delete an abuse
2807 - $ref: '#/components/parameters/abuseId'
2810 description: successful operation
2812 description: block not found
2814 '/abuses/{abuseId}/messages':
2816 summary: List messages of an abuse
2822 - $ref: '#/components/parameters/abuseId'
2825 description: successful operation
2837 $ref: '#/components/schemas/AbuseMessage'
2839 summary: Add message to an abuse
2845 - $ref: '#/components/parameters/abuseId'
2854 description: Message to send
2862 description: successful operation
2864 description: incorrect request parameters
2866 '/abuses/{abuseId}/messages/{abuseMessageId}':
2868 summary: Delete an abuse message
2874 - $ref: '#/components/parameters/abuseId'
2875 - $ref: '#/components/parameters/abuseMessageId'
2878 description: successful operation
2880 '/videos/{id}/blacklist':
2882 summary: Block a video
2883 operationId: addVideoBlock
2891 - $ref: '#/components/parameters/idOrUUID'
2894 description: successful operation
2896 summary: Unblock a video by its id
2897 operationId: delVideoBlock
2905 - $ref: '#/components/parameters/idOrUUID'
2908 description: successful operation
2910 description: block not found
2916 summary: List video blocks
2917 operationId: getVideoBlocks
2926 list only blocks that match this type:
2930 - `2`: automatic block that needs review
2938 description: plain search that will match with video titles, and more
2941 - $ref: '#/components/parameters/start'
2942 - $ref: '#/components/parameters/count'
2943 - $ref: '#/components/parameters/blacklistsSort'
2946 description: successful operation
2958 $ref: '#/components/schemas/VideoBlacklist'
2960 /videos/{id}/captions:
2962 summary: List captions of a video
2963 operationId: getVideoCaptions
2967 - $ref: '#/components/parameters/idOrUUID'
2970 description: successful operation
2982 $ref: '#/components/schemas/VideoCaption'
2984 /videos/{id}/captions/{captionLanguage}:
2986 summary: Add or replace a video caption
2987 operationId: addVideoCaption
2994 - $ref: '#/components/parameters/idOrUUID'
2995 - $ref: '#/components/parameters/captionLanguage'
2998 multipart/form-data:
3003 description: The file to upload.
3008 contentType: text/vtt, application/x-subrip, text/plain
3011 description: successful operation
3013 description: video or language not found
3015 summary: Delete a video caption
3016 operationId: delVideoCaption
3023 - $ref: '#/components/parameters/idOrUUID'
3024 - $ref: '#/components/parameters/captionLanguage'
3027 description: successful operation
3029 description: video or language or caption for that language not found
3033 summary: List video channels
3034 operationId: getVideoChannels
3038 - $ref: '#/components/parameters/start'
3039 - $ref: '#/components/parameters/count'
3040 - $ref: '#/components/parameters/sort'
3043 description: successful operation
3047 $ref: '#/components/schemas/VideoChannelList'
3049 summary: Create a video channel
3050 operationId: addVideoChannel
3057 description: successful operation
3067 $ref: '#/components/schemas/id'
3072 $ref: '#/components/schemas/VideoChannelCreate'
3074 '/video-channels/{channelHandle}':
3076 summary: Get a video channel
3077 operationId: getVideoChannel
3081 - $ref: '#/components/parameters/channelHandle'
3084 description: successful operation
3088 $ref: '#/components/schemas/VideoChannel'
3090 summary: Update a video channel
3091 operationId: putVideoChannel
3097 - $ref: '#/components/parameters/channelHandle'
3100 description: successful operation
3105 $ref: '#/components/schemas/VideoChannelUpdate'
3107 summary: Delete a video channel
3108 operationId: delVideoChannel
3114 - $ref: '#/components/parameters/channelHandle'
3117 description: successful operation
3119 '/video-channels/{channelHandle}/videos':
3121 summary: List videos of a video channel
3122 operationId: getVideoChannelVideos
3127 - $ref: '#/components/parameters/channelHandle'
3128 - $ref: '#/components/parameters/categoryOneOf'
3129 - $ref: '#/components/parameters/isLive'
3130 - $ref: '#/components/parameters/tagsOneOf'
3131 - $ref: '#/components/parameters/tagsAllOf'
3132 - $ref: '#/components/parameters/licenceOneOf'
3133 - $ref: '#/components/parameters/languageOneOf'
3134 - $ref: '#/components/parameters/nsfw'
3135 - $ref: '#/components/parameters/isLocal'
3136 - $ref: '#/components/parameters/include'
3137 - $ref: '#/components/parameters/privacyOneOf'
3138 - $ref: '#/components/parameters/hasHLSFiles'
3139 - $ref: '#/components/parameters/hasWebtorrentFiles'
3140 - $ref: '#/components/parameters/skipCount'
3141 - $ref: '#/components/parameters/start'
3142 - $ref: '#/components/parameters/count'
3143 - $ref: '#/components/parameters/videosSort'
3146 description: successful operation
3150 $ref: '#/components/schemas/VideoListResponse'
3152 '/video-channels/{channelHandle}/followers':
3156 summary: 'List followers of a video channel'
3159 operationId: getVideoChannelFollowers
3161 - $ref: '#/components/parameters/channelHandle'
3162 - $ref: '#/components/parameters/start'
3163 - $ref: '#/components/parameters/count'
3164 - $ref: '#/components/parameters/followersSort'
3165 - $ref: '#/components/parameters/search'
3168 description: successful operation
3180 $ref: '#/components/schemas/Follow'
3182 '/video-channels/{channelHandle}/avatar/pick':
3184 summary: Update channel avatar
3190 - $ref: '#/components/parameters/channelHandle'
3193 description: successful operation
3202 $ref: '#/components/schemas/ActorImage'
3204 description: image file too large
3206 X-File-Maximum-Size:
3210 description: Maximum file size for the avatar
3213 multipart/form-data:
3218 description: The file to upload.
3223 contentType: image/png, image/jpeg
3225 '/video-channels/{channelHandle}/avatar':
3227 summary: Delete channel avatar
3233 - $ref: '#/components/parameters/channelHandle'
3236 description: successful operation
3238 '/video-channels/{channelHandle}/banner/pick':
3240 summary: Update channel banner
3246 - $ref: '#/components/parameters/channelHandle'
3249 description: successful operation
3258 $ref: '#/components/schemas/ActorImage'
3260 description: image file too large
3262 X-File-Maximum-Size:
3266 description: Maximum file size for the banner
3269 multipart/form-data:
3274 description: The file to upload.
3279 contentType: image/png, image/jpeg
3281 '/video-channels/{channelHandle}/banner':
3283 summary: Delete channel banner
3289 - $ref: '#/components/parameters/channelHandle'
3292 description: successful operation
3294 '/video-channel-syncs':
3296 summary: Create a synchronization for a video channel
3297 operationId: addVideoChannelSync
3306 $ref: '#/components/schemas/VideoChannelSyncCreate'
3309 description: successful operation
3316 $ref: "#/components/schemas/VideoChannelSync"
3318 '/video-channel-syncs/{channelSyncId}':
3320 summary: Delete a video channel synchronization
3321 operationId: delVideoChannelSync
3327 - $ref: '#/components/parameters/channelSyncId'
3330 description: successful operation
3332 '/video-channel-syncs/{channelSyncId}/sync':
3334 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
3335 operationId: triggerVideoChannelSync
3341 - $ref: '#/components/parameters/channelSyncId'
3344 description: successful operation
3347 /video-playlists/privacies:
3349 summary: List available playlist privacy policies
3350 operationId: getPlaylistPrivacyPolicies
3355 description: successful operation
3364 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3368 summary: List video playlists
3369 operationId: getPlaylists
3373 - $ref: '#/components/parameters/start'
3374 - $ref: '#/components/parameters/count'
3375 - $ref: '#/components/parameters/sort'
3378 description: successful operation
3390 $ref: '#/components/schemas/VideoPlaylist'
3392 summary: Create a video playlist
3393 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3394 operationId: addPlaylist
3401 description: successful operation
3411 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3413 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3415 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3418 multipart/form-data:
3423 description: Video playlist display name
3428 description: Video playlist thumbnail file
3432 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3434 description: Video playlist description
3440 - $ref: '#/components/schemas/id'
3441 description: Video channel in which the playlist will be published
3446 contentType: image/jpeg
3448 /video-playlists/{playlistId}:
3450 summary: Get a video playlist
3454 - $ref: '#/components/parameters/playlistId'
3457 description: successful operation
3461 $ref: '#/components/schemas/VideoPlaylist'
3463 summary: Update a video playlist
3464 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3471 description: successful operation
3473 - $ref: '#/components/parameters/playlistId'
3476 multipart/form-data:
3481 description: Video playlist display name
3486 description: Video playlist thumbnail file
3490 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3492 description: Video playlist description
3496 - $ref: '#/components/schemas/id'
3497 description: Video channel in which the playlist will be published
3500 contentType: image/jpeg
3502 summary: Delete a video playlist
3508 - $ref: '#/components/parameters/playlistId'
3511 description: successful operation
3513 /video-playlists/{playlistId}/videos:
3515 summary: 'List videos of a playlist'
3516 operationId: getVideoPlaylistVideos
3521 - $ref: '#/components/parameters/playlistId'
3522 - $ref: '#/components/parameters/start'
3523 - $ref: '#/components/parameters/count'
3526 description: successful operation
3530 $ref: '#/components/schemas/VideoListResponse'
3532 summary: Add a video in a playlist
3533 operationId: addVideoPlaylistVideo
3540 - $ref: '#/components/parameters/playlistId'
3543 description: successful operation
3549 videoPlaylistElement:
3563 - $ref: '#/components/schemas/Video/properties/uuid'
3564 - $ref: '#/components/schemas/Video/properties/id'
3565 description: Video to add in the playlist
3569 description: Start the video at this specific timestamp
3573 description: Stop the video at this specific timestamp
3577 /video-playlists/{playlistId}/videos/reorder:
3579 summary: 'Reorder a playlist'
3580 operationId: reorderVideoPlaylist
3586 - $ref: '#/components/parameters/playlistId'
3589 description: successful operation
3598 description: 'Start position of the element to reorder'
3600 insertAfterPosition:
3602 description: 'New position for the block to reorder, to add the block before the first element'
3606 description: 'How many element from `startPosition` to reorder'
3610 - insertAfterPosition
3612 /video-playlists/{playlistId}/videos/{playlistElementId}:
3614 summary: Update a playlist element
3615 operationId: putVideoPlaylistVideo
3621 - $ref: '#/components/parameters/playlistId'
3622 - $ref: '#/components/parameters/playlistElementId'
3625 description: successful operation
3635 description: Start the video at this specific timestamp
3639 description: Stop the video at this specific timestamp
3641 summary: Delete an element from a playlist
3642 operationId: delVideoPlaylistVideo
3648 - $ref: '#/components/parameters/playlistId'
3649 - $ref: '#/components/parameters/playlistElementId'
3652 description: successful operation
3654 '/users/me/video-playlists/videos-exist':
3656 summary: Check video exists in my playlists
3665 description: The video ids to check
3669 $ref: '#/components/schemas/Video/properties/id'
3672 description: successful operation
3694 '/accounts/{name}/video-channels':
3696 summary: List video channels of an account
3701 - $ref: '#/components/parameters/name'
3704 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
3707 - $ref: '#/components/parameters/start'
3708 - $ref: '#/components/parameters/count'
3709 - $ref: '#/components/parameters/sort'
3712 description: successful operation
3716 $ref: '#/components/schemas/VideoChannelList'
3718 '/accounts/{name}/video-channel-syncs':
3720 summary: List the synchronizations of video channels of an account
3726 - $ref: '#/components/parameters/name'
3727 - $ref: '#/components/parameters/start'
3728 - $ref: '#/components/parameters/count'
3729 - $ref: '#/components/parameters/sort'
3732 description: successful operation
3736 $ref: '#/components/schemas/VideoChannelSyncList'
3738 '/accounts/{name}/ratings':
3740 summary: List ratings of an account
3746 - $ref: '#/components/parameters/name'
3747 - $ref: '#/components/parameters/start'
3748 - $ref: '#/components/parameters/count'
3749 - $ref: '#/components/parameters/sort'
3753 description: Optionally filter which ratings to retrieve
3761 description: successful operation
3767 $ref: '#/components/schemas/VideoRating'
3769 '/videos/{id}/comment-threads':
3771 summary: List threads of a video
3775 - $ref: '#/components/parameters/idOrUUID'
3776 - $ref: '#/components/parameters/start'
3777 - $ref: '#/components/parameters/count'
3778 - $ref: '#/components/parameters/commentsSort'
3781 description: successful operation
3785 $ref: '#/components/schemas/CommentThreadResponse'
3787 summary: Create a thread
3793 - $ref: '#/components/parameters/idOrUUID'
3796 description: successful operation
3800 $ref: '#/components/schemas/CommentThreadPostResponse'
3802 description: video does not exist
3811 - $ref: '#/components/schemas/VideoComment/properties/text'
3817 '/videos/{id}/comment-threads/{threadId}':
3819 summary: Get a thread
3823 - $ref: '#/components/parameters/idOrUUID'
3824 - $ref: '#/components/parameters/threadId'
3827 description: successful operation
3831 $ref: '#/components/schemas/VideoCommentThreadTree'
3833 '/videos/{id}/comments/{commentId}':
3835 summary: Reply to a thread of a video
3841 - $ref: '#/components/parameters/idOrUUID'
3842 - $ref: '#/components/parameters/commentId'
3845 description: successful operation
3849 $ref: '#/components/schemas/CommentThreadPostResponse'
3851 description: thread or video does not exist
3860 - $ref: '#/components/schemas/VideoComment/properties/text'
3866 summary: Delete a comment or a reply
3872 - $ref: '#/components/parameters/idOrUUID'
3873 - $ref: '#/components/parameters/commentId'
3876 description: successful operation
3878 description: cannot remove comment of another user
3880 description: comment or video does not exist
3882 description: comment is already deleted
3884 '/videos/{id}/rate':
3886 summary: Like/dislike a video
3892 - $ref: '#/components/parameters/idOrUUID'
3908 description: successful operation
3910 description: video does not exist
3914 summary: Delete video HLS files
3920 operationId: delVideoHLS
3922 - $ref: '#/components/parameters/idOrUUID'
3925 description: successful operation
3927 description: video does not exist
3928 '/videos/{id}/webtorrent':
3930 summary: Delete video WebTorrent files
3936 operationId: delVideoWebTorrent
3938 - $ref: '#/components/parameters/idOrUUID'
3941 description: successful operation
3943 description: video does not exist
3945 '/videos/{id}/transcoding':
3947 summary: Create a transcoding job
3953 operationId: createVideoTranscoding
3955 - $ref: '#/components/parameters/idOrUUID'
3971 description: successful operation
3973 description: video does not exist
3979 summary: Search videos
3980 operationId: searchVideos
3985 allowEmptyValue: false
3987 String to search. If the user can make a remote URI search, and the string is an URI then the
3988 PeerTube instance will fetch the remote object and add it to its database. Then,
3989 you can use the REST API to fetch the complete video information and interact with it.
3992 - $ref: '#/components/parameters/categoryOneOf'
3993 - $ref: '#/components/parameters/isLive'
3994 - $ref: '#/components/parameters/tagsOneOf'
3995 - $ref: '#/components/parameters/tagsAllOf'
3996 - $ref: '#/components/parameters/licenceOneOf'
3997 - $ref: '#/components/parameters/languageOneOf'
3998 - $ref: '#/components/parameters/nsfw'
3999 - $ref: '#/components/parameters/isLocal'
4000 - $ref: '#/components/parameters/include'
4001 - $ref: '#/components/parameters/privacyOneOf'
4002 - $ref: '#/components/parameters/hasHLSFiles'
4003 - $ref: '#/components/parameters/hasWebtorrentFiles'
4004 - $ref: '#/components/parameters/skipCount'
4005 - $ref: '#/components/parameters/start'
4006 - $ref: '#/components/parameters/count'
4007 - $ref: '#/components/parameters/searchTarget'
4008 - $ref: '#/components/parameters/videosSearchSort'
4011 description: Get videos that are published after this date
4017 description: Get videos that are published before this date
4021 - name: originallyPublishedStartDate
4023 description: Get videos that are originally published after this date
4027 - name: originallyPublishedEndDate
4029 description: Get videos that are originally published before this date
4035 description: Get videos that have this minimum duration
4040 description: Get videos that have this maximum duration
4044 'searchTarget === search-index':
4045 $ref: '#/components/callbacks/searchIndex'
4048 description: successful operation
4052 $ref: '#/components/schemas/VideoListResponse'
4054 description: search index unavailable
4056 /search/video-channels:
4060 summary: Search channels
4061 operationId: searchChannels
4067 String to search. If the user can make a remote URI search, and the string is an URI then the
4068 PeerTube instance will fetch the remote object and add it to its database. Then,
4069 you can use the REST API to fetch the complete channel information and interact with it.
4072 - $ref: '#/components/parameters/start'
4073 - $ref: '#/components/parameters/count'
4074 - $ref: '#/components/parameters/searchTarget'
4075 - $ref: '#/components/parameters/sort'
4077 'searchTarget === search-index':
4078 $ref: '#/components/callbacks/searchIndex'
4081 description: successful operation
4085 $ref: '#/components/schemas/VideoChannelList'
4087 description: search index unavailable
4089 /search/video-playlists:
4093 summary: Search playlists
4094 operationId: searchPlaylists
4100 String to search. If the user can make a remote URI search, and the string is an URI then the
4101 PeerTube instance will fetch the remote object and add it to its database. Then,
4102 you can use the REST API to fetch the complete playlist information and interact with it.
4105 - $ref: '#/components/parameters/start'
4106 - $ref: '#/components/parameters/count'
4107 - $ref: '#/components/parameters/searchTarget'
4108 - $ref: '#/components/parameters/sort'
4110 'searchTarget === search-index':
4111 $ref: '#/components/callbacks/searchIndex'
4114 description: successful operation
4126 $ref: '#/components/schemas/VideoPlaylist'
4128 description: search index unavailable
4135 summary: Get block status of accounts/hosts
4140 description: 'Check if these accounts are blocked'
4141 example: [ 'goofy@example.com', 'donald@example.com' ]
4149 description: 'Check if these hosts are blocked'
4150 example: [ 'example.com' ]
4157 description: successful operation
4161 $ref: '#/components/schemas/BlockStatus'
4163 /server/blocklist/accounts:
4167 summary: List account blocks
4172 - $ref: '#/components/parameters/start'
4173 - $ref: '#/components/parameters/count'
4174 - $ref: '#/components/parameters/sort'
4177 description: successful operation
4181 summary: Block an account
4193 example: chocobozzz@example.org
4194 description: account to block, in the form `username@domain`
4199 description: successful operation
4201 description: self-blocking forbidden
4203 '/server/blocklist/accounts/{accountName}':
4207 summary: Unblock an account by its handle
4215 description: account to unblock, in the form `username@domain`
4220 description: successful operation
4222 description: account or account block does not exist
4224 /server/blocklist/servers:
4228 summary: List server blocks
4233 - $ref: '#/components/parameters/start'
4234 - $ref: '#/components/parameters/count'
4235 - $ref: '#/components/parameters/sort'
4238 description: successful operation
4242 summary: Block a server
4255 description: server domain to block
4260 description: successful operation
4262 description: self-blocking forbidden
4264 '/server/blocklist/servers/{host}':
4268 summary: Unblock a server by its domain
4276 description: server domain to unblock
4282 description: successful operation
4284 description: account block does not exist
4286 /server/redundancy/{host}:
4289 - Instance Redundancy
4290 summary: Update a server redundancy policy
4298 description: server domain to mirror
4310 description: allow mirroring of the host's local videos
4315 description: successful operation
4317 description: server is not already known
4319 /server/redundancy/videos:
4323 summary: List videos being mirrored
4324 operationId: getMirroredVideos
4332 description: direction of the mirror
4338 - $ref: '#/components/parameters/start'
4339 - $ref: '#/components/parameters/count'
4340 - $ref: '#/components/parameters/videoRedundanciesSort'
4343 description: successful operation
4349 $ref: '#/components/schemas/VideoRedundancy'
4353 summary: Mirror a video
4354 operationId: putMirroredVideo
4365 $ref: '#/components/schemas/Video/properties/id'
4370 description: successful operation
4372 description: cannot mirror a local video
4374 description: video does not exist
4376 description: video is already mirrored
4378 /server/redundancy/videos/{redundancyId}:
4382 summary: Delete a mirror done on a video
4383 operationId: delMirroredVideo
4388 - name: redundancyId
4391 description: id of an existing redundancy on a video
4396 description: successful operation
4398 description: video redundancy not found
4404 summary: Get instance stats
4405 description: Get instance public statistics. This endpoint is cached.
4406 operationId: getInstanceStats
4409 description: successful operation
4413 $ref: '#/components/schemas/ServerStats'
4415 /server/logs/client:
4419 summary: Send client log
4420 operationId: sendClientLog
4425 $ref: '#/components/schemas/SendClientLog'
4428 description: successful operation
4434 summary: Get instance logs
4435 operationId: getInstanceLogs
4441 description: successful operation
4453 summary: Get instance audit logs
4454 operationId: getInstanceAuditLogs
4460 description: successful operation
4468 '/feeds/video-comments.{format}':
4472 summary: List comments on videos
4473 operationId: getSyndicatedComments
4478 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4491 description: 'limit listing to a specific video'
4496 description: 'limit listing to a specific account'
4501 description: 'limit listing to a specific account'
4504 - name: videoChannelId
4506 description: 'limit listing to a specific video channel'
4509 - name: videoChannelName
4511 description: 'limit listing to a specific video channel'
4516 description: successful operation
4521 default: 'max-age=900' # 15 min cache
4525 $ref: '#/components/schemas/VideoCommentsForXML'
4528 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4529 application/rss+xml:
4531 $ref: '#/components/schemas/VideoCommentsForXML'
4534 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4537 $ref: '#/components/schemas/VideoCommentsForXML'
4540 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4541 application/atom+xml:
4543 $ref: '#/components/schemas/VideoCommentsForXML'
4546 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4552 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4554 x-summary: field inconsistencies
4557 - videoId filter is mixed with a channel filter
4559 description: video, video channel or account not found
4561 description: accept header unsupported
4563 '/feeds/videos.{format}':
4567 summary: List videos
4568 operationId: getSyndicatedVideos
4573 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4586 description: 'limit listing to a specific account'
4591 description: 'limit listing to a specific account'
4594 - name: videoChannelId
4596 description: 'limit listing to a specific video channel'
4599 - name: videoChannelName
4601 description: 'limit listing to a specific video channel'
4604 - $ref: '#/components/parameters/sort'
4605 - $ref: '#/components/parameters/nsfw'
4606 - $ref: '#/components/parameters/isLocal'
4607 - $ref: '#/components/parameters/include'
4608 - $ref: '#/components/parameters/privacyOneOf'
4609 - $ref: '#/components/parameters/hasHLSFiles'
4610 - $ref: '#/components/parameters/hasWebtorrentFiles'
4613 description: successful operation
4618 default: 'max-age=900' # 15 min cache
4622 $ref: '#/components/schemas/VideosForXML'
4625 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4626 application/rss+xml:
4628 $ref: '#/components/schemas/VideosForXML'
4631 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4634 $ref: '#/components/schemas/VideosForXML'
4637 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4638 application/atom+xml:
4640 $ref: '#/components/schemas/VideosForXML'
4643 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4649 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4651 description: video channel or account not found
4653 description: accept header unsupported
4655 '/feeds/subscriptions.{format}':
4660 summary: List videos of subscriptions tied to a token
4661 operationId: getSyndicatedSubscriptionVideos
4666 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4679 description: limit listing to a specific account
4685 description: private token allowing access
4689 - $ref: '#/components/parameters/sort'
4690 - $ref: '#/components/parameters/nsfw'
4691 - $ref: '#/components/parameters/isLocal'
4692 - $ref: '#/components/parameters/include'
4693 - $ref: '#/components/parameters/privacyOneOf'
4694 - $ref: '#/components/parameters/hasHLSFiles'
4695 - $ref: '#/components/parameters/hasWebtorrentFiles'
4698 description: successful operation
4703 default: 'max-age=900' # 15 min cache
4707 $ref: '#/components/schemas/VideosForXML'
4708 application/rss+xml:
4710 $ref: '#/components/schemas/VideosForXML'
4713 $ref: '#/components/schemas/VideosForXML'
4714 application/atom+xml:
4716 $ref: '#/components/schemas/VideosForXML'
4721 description: accept header unsupported
4727 summary: List plugins
4728 operationId: getPlugins
4741 - $ref: '#/components/parameters/start'
4742 - $ref: '#/components/parameters/count'
4743 - $ref: '#/components/parameters/sort'
4746 description: successful operation
4750 $ref: '#/components/schemas/PluginResponse'
4756 summary: List available plugins
4757 operationId: getAvailablePlugins
4770 - name: currentPeerTubeEngine
4774 - $ref: '#/components/parameters/start'
4775 - $ref: '#/components/parameters/count'
4776 - $ref: '#/components/parameters/sort'
4779 description: successful operation
4783 $ref: '#/components/schemas/PluginResponse'
4785 description: plugin index unavailable
4791 summary: Install a plugin
4792 operationId: addPlugin
4805 example: peertube-plugin-auth-ldap
4808 additionalProperties: false
4815 additionalProperties: false
4818 description: successful operation
4820 description: should have either `npmName` or `path` set
4826 summary: Update a plugin
4827 operationId: updatePlugin
4840 example: peertube-plugin-auth-ldap
4843 additionalProperties: false
4850 additionalProperties: false
4853 description: successful operation
4855 description: should have either `npmName` or `path` set
4857 description: existing plugin not found
4863 summary: Uninstall a plugin
4864 operationId: uninstallPlugin
4876 description: name of the plugin/theme in its package.json
4877 example: peertube-plugin-auth-ldap
4882 description: successful operation
4884 description: existing plugin not found
4890 summary: Get a plugin
4891 operationId: getPlugin
4896 - $ref: '#/components/parameters/npmName'
4899 description: successful operation
4903 $ref: '#/components/schemas/Plugin'
4905 description: plugin not found
4907 /plugins/{npmName}/settings:
4911 summary: Set a plugin's settings
4916 - $ref: '#/components/parameters/npmName'
4925 additionalProperties: true
4928 description: successful operation
4930 description: plugin not found
4932 /plugins/{npmName}/public-settings:
4936 summary: Get a plugin's public settings
4938 - $ref: '#/components/parameters/npmName'
4941 description: successful operation
4946 additionalProperties: true
4948 description: plugin not found
4950 /plugins/{npmName}/registered-settings:
4954 summary: Get a plugin's registered settings
4959 - $ref: '#/components/parameters/npmName'
4962 description: successful operation
4967 additionalProperties: true
4969 description: plugin not found
4972 - url: 'https://peertube2.cpy.re/api/v1'
4973 description: Live Test Server (live data - latest nightly version)
4974 - url: 'https://peertube3.cpy.re/api/v1'
4975 description: Live Test Server (live data - latest RC version)
4976 - url: 'https://peertube.cpy.re/api/v1'
4977 description: Live Test Server (live data - stable version)
4984 description: Offset used to paginate results
4992 description: "Number of items to return"
5002 description: Sort column
5010 description: Plain text search, applied to various parts of the model depending on endpoint
5018 If the administrator enabled search index support, you can override the default search target.
5021 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5022 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5023 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5024 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5025 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5026 * 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
5027 the data from the origin instance API
5050 Sort videos by criteria (prefixing with `-` means `DESC` order):
5051 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5052 * `best` - Same than `hot`, but also takes into account user video history
5053 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5054 * `views` - Sort videos using their `views` counter
5055 * `publishedAt` - Sort by video publication date (when it became publicly available)
5061 Sort videos by criteria (prefixing with `-` means `DESC` order):
5076 description: Sort comments by criteria
5086 description: Sort blocklists by criteria
5102 description: Plain text search that will match with user usernames or emails
5109 description: Filter results down to (un)banned users
5116 description: Sort users by criteria
5127 description: Sort abuses by criteria
5134 videoRedundanciesSort:
5138 description: Sort abuses by criteria
5147 description: Sort followers by criteria
5156 description: The username or handle of the account
5159 example: chocobozzz | chocobozzz@example.org
5164 description: Entity id
5166 $ref: '#/components/schemas/id'
5171 description: The object id, uuid or short uuid
5174 - $ref: '#/components/schemas/id'
5175 - $ref: '#/components/schemas/UUIDv4'
5176 - $ref: '#/components/schemas/shortUUID'
5181 description: Playlist id
5183 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5185 name: playlistElementId
5188 description: Playlist element id
5190 $ref: '#/components/schemas/id'
5195 description: Abuse id
5197 $ref: '#/components/schemas/Abuse/properties/id'
5199 name: abuseMessageId
5202 description: Abuse message id
5204 $ref: '#/components/schemas/AbuseMessage/properties/id'
5206 name: captionLanguage
5209 description: The caption language
5211 $ref: '#/components/schemas/VideoLanguageSet'
5216 description: The video channel handle
5219 example: my_username | my_username@example.com
5224 description: Channel Sync id
5226 $ref: '#/components/schemas/Abuse/properties/id'
5228 name: subscriptionHandle
5231 description: The subscription handle
5234 example: my_username | my_username@example.com
5239 description: The thread id (root comment id)
5246 description: The comment id
5248 $ref: '#/components/schemas/VideoComment/properties/id'
5253 description: whether or not the video is a live
5260 description: category id of the video (see [/videos/categories](#operation/getCategories))
5263 - $ref: '#/components/schemas/VideoCategorySet'
5266 $ref: '#/components/schemas/VideoCategorySet'
5273 description: tag(s) of the video
5287 description: tag(s) of the video, where all should be present in the video
5300 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5303 - $ref: '#/components/schemas/VideoLanguageSet'
5306 $ref: '#/components/schemas/VideoLanguageSet'
5313 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5316 - $ref: '#/components/schemas/VideoLicenceSet'
5319 $ref: '#/components/schemas/VideoLicenceSet'
5326 description: if you don't need the `total` in the response
5337 description: whether to include nsfw videos, if any
5349 description: '**PeerTube >= 4.0** Display only local or remote videos'
5356 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5358 name: hasWebtorrentFiles
5363 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5369 $ref: '#/components/schemas/VideoPrivacySet'
5370 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5384 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5388 - `1` NOT_PUBLISHED_STATE
5399 description: list of uris to check if each is part of the user subscriptions
5409 description: name of the plugin/theme on npmjs.com or in its package.json
5412 example: peertube-plugin-auth-ldap
5417 description: job type
5421 - activitypub-follow
5422 - activitypub-http-broadcast
5423 - activitypub-http-fetcher
5424 - activitypub-http-unicast
5429 - videos-views-stats
5430 - activitypub-refresher
5433 - video-channel-import
5456 Authenticating via OAuth requires the following steps:
5457 - Have an activated account
5458 - [Generate] an access token for that account at `/api/v1/users/token`.
5459 - Make requests with the *Authorization: Bearer <token\>* header
5460 - Profit, depending on the role assigned to the account
5462 Note that the __access token is valid for 1 day__ and is given
5463 along with a __refresh token valid for 2 weeks__.
5465 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5469 tokenUrl: /api/v1/users/token
5472 moderator: Moderator scope
5475 # Reusable core properties
5483 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5484 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5489 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5490 example: 2y84q2MQUMWPbiEcxNXMgC
5493 description: immutable name of the user, used to find or mention its actor
5495 pattern: '/^[a-z0-9._]+$/'
5500 description: immutable name of the channel, used to interact with its actor
5501 example: framasoft_videos
5502 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5513 description: category id of the video (see [/videos/categories](#operation/getCategories))
5515 VideoConstantNumber-Category:
5518 $ref: '#/components/schemas/VideoCategorySet'
5521 example: Science & Technology
5525 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5527 VideoConstantNumber-Licence:
5530 $ref: '#/components/schemas/VideoLicenceSet'
5533 example: Attribution - Share Alike
5537 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5539 VideoConstantString-Language:
5542 $ref: '#/components/schemas/VideoLanguageSet'
5547 VideoPlaylistPrivacySet:
5553 description: Video playlist privacy policy (see [/video-playlists/privacies])
5554 VideoPlaylistPrivacyConstant:
5557 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5561 VideoPlaylistTypeSet:
5566 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5567 VideoPlaylistTypeConstant:
5570 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5581 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5582 VideoPrivacyConstant:
5585 $ref: '#/components/schemas/VideoPrivacySet'
5593 additionalProperties:
5594 x-additionalPropertiesName: account
5603 additionalProperties:
5604 x-additionalPropertiesName: host
5625 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5632 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5635 LiveVideoLatencyMode:
5641 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
5662 - `4`: Waiting for live stream
5664 - `6`: To move to an external storage (object storage...)
5665 - `7`: Transcoding failed
5666 - `8`: Moving to an external storage failed
5667 - `9`: To edit using studio edition feature
5677 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5681 $ref: '#/components/schemas/AbuseStateSet'
5684 AbusePredefinedReasons:
5697 example: [spamOrMisleading]
5702 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5704 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5706 VideoResolutionConstant:
5707 description: resolutions and their labels for the video
5710 $ref: '#/components/schemas/VideoResolutionSet'
5714 VideoScheduledUpdate:
5717 $ref: '#/components/schemas/VideoPrivacySet'
5721 description: When to update the video
5741 $ref: '#/components/schemas/ActorImage'
5742 VideoChannelSummary:
5745 $ref: '#/components/schemas/id'
5759 $ref: '#/components/schemas/ActorImage'
5773 - $ref: '#/components/schemas/Video'
5778 $ref: '#/components/schemas/id'
5782 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5783 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5785 $ref: '#/components/schemas/VideoResolutionConstant'
5788 description: Video file size in bytes
5791 description: Direct URL of the torrent file
5795 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5799 description: Direct URL of the video
5803 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5807 description: Frames per second of the video file
5811 description: URL dereferencing the output of ffprobe on the file
5812 VideoStreamingPlaylists:
5817 $ref: '#/components/schemas/id'
5825 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5826 VideoStreamingPlaylists-HLS:
5837 Video files associated to this playlist.
5839 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5841 $ref: '#/components/schemas/VideoFile'
5853 $ref: '#/components/schemas/Video/properties/id'
5855 $ref: '#/components/schemas/Video/properties/uuid'
5857 $ref: '#/components/schemas/Video/properties/name'
5861 description: object id for the video
5863 - $ref: '#/components/schemas/id'
5865 description: universal identifier for the video, that can be used across instances
5867 - $ref: '#/components/schemas/UUIDv4'
5870 - $ref: '#/components/schemas/shortUUID'
5876 example: 2017-10-01T10:52:46.396Z
5877 description: time at which the video object was first drafted
5881 example: 2018-10-01T10:52:46.396Z
5882 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5886 example: 2021-05-04T08:01:01.502Z
5887 description: last time the video's metadata was modified
5888 originallyPublishedAt:
5891 example: 2010-10-01T10:52:46.396Z
5892 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5895 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5896 description: category in which the video is classified
5899 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5900 description: licence under which the video is distributed
5903 - $ref: '#/components/schemas/VideoConstantString-Language'
5904 description: main language used in the video
5907 - $ref: '#/components/schemas/VideoPrivacyConstant'
5908 description: privacy policy used to distribute the video
5912 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5913 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5917 truncated description of the video, written in Markdown.
5918 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5923 description: duration of the video in seconds
5928 description: title of the video
5929 example: What is PeerTube?
5934 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5937 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5940 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5957 - $ref: '#/components/schemas/VideoStateConstant'
5958 description: represents the internal state of the video processing within the PeerTube instance
5962 - $ref: '#/components/schemas/VideoScheduledUpdate'
5970 $ref: '#/components/schemas/AccountSummary'
5972 $ref: '#/components/schemas/VideoChannelSummary'
5981 - $ref: '#/components/schemas/Video'
5986 description: If the video is a live, you have the amount of current viewers
5989 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5990 description: path at which to get the full description of maximum `10000` characters
5993 description: A text tell the audience how to support the video creator
5994 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5998 $ref: '#/components/schemas/VideoChannel'
6000 $ref: '#/components/schemas/Account'
6002 example: [flowers, gardening]
6020 - https://peertube2.cpy.re/tracker/announce
6021 - wss://peertube2.cpy.re/tracker/socket
6025 $ref: '#/components/schemas/VideoFile'
6027 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6029 - field will be empty
6030 - video files will be found in `streamingPlaylists[].files` field
6034 $ref: '#/components/schemas/VideoStreamingPlaylists'
6036 HLS playlists/manifest files. If HLS is disabled on the server:
6038 - field will be empty
6039 - video files will be found in `files` field
6040 FileRedundancyInformation:
6043 $ref: '#/components/schemas/id'
6068 $ref: '#/components/schemas/id'
6075 $ref: '#/components/schemas/UUIDv4'
6082 $ref: '#/components/schemas/FileRedundancyInformation'
6086 $ref: '#/components/schemas/FileRedundancyInformation'
6087 VideoImportStateConstant:
6095 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6102 additionalProperties: false
6106 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6107 required: [targetUrl]
6110 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6111 required: [magnetUri]
6114 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6115 required: [torrentfile]
6116 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6125 - $ref: '#/components/schemas/id'
6129 description: remote URL where to find the import's source video
6130 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6134 description: magnet URI allowing to resolve the import's source video
6135 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6140 description: Torrent file containing only the video file
6147 - $ref: '#/components/schemas/VideoImportStateConstant'
6163 - $ref: '#/components/schemas/Video'
6173 $ref: '#/components/schemas/VideoImport'
6177 $ref: '#/components/schemas/id'
6180 example: The video is a spam
6184 $ref: '#/components/schemas/AbusePredefinedReasons'
6186 $ref: '#/components/schemas/Account'
6188 $ref: '#/components/schemas/AbuseStateConstant'
6191 example: Decided to ban the server since it spams us regularly
6195 $ref: '#/components/schemas/VideoInfo'
6202 $ref: '#/components/schemas/id'
6213 $ref: '#/components/schemas/AccountSummary'
6217 $ref: '#/components/schemas/id'
6219 $ref: '#/components/schemas/Video/properties/id'
6231 $ref: '#/components/schemas/UUIDv4'
6249 $ref: '#/components/schemas/id'
6251 $ref: '#/components/schemas/UUIDv4'
6254 - $ref: '#/components/schemas/shortUUID'
6277 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6279 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6281 $ref: '#/components/schemas/AccountSummary'
6283 $ref: '#/components/schemas/VideoChannelSummary'
6287 $ref: '#/components/schemas/id'
6294 description: Text of the comment
6296 example: This video is wonderful!
6298 $ref: '#/components/schemas/id'
6302 - $ref: '#/components/schemas/id'
6304 $ref: '#/components/schemas/Video/properties/id'
6319 totalRepliesFromVideoAuthor:
6326 $ref: '#/components/schemas/Account'
6327 VideoCommentThreadTree:
6330 $ref: '#/components/schemas/VideoComment'
6334 $ref: '#/components/schemas/VideoCommentThreadTree'
6338 $ref: '#/components/schemas/VideoConstantString-Language'
6360 $ref: '#/components/schemas/id'
6371 $ref: '#/components/schemas/ActorImage'
6375 $ref: '#/components/schemas/id'
6380 description: immutable name of the actor, used to find or mention it
6382 - $ref: '#/components/schemas/username'
6386 description: server on which the actor is resident
6387 hostRedundancyAllowed:
6389 description: whether this actor's host allows redundancy of its videos
6393 description: number of actors subscribed to by this actor, as seen by this instance
6397 description: number of followers of this actor, as seen by this instance
6406 - $ref: '#/components/schemas/Actor'
6409 description: object id for the user tied to this account
6411 - $ref: '#/components/schemas/User/properties/id'
6414 description: editable name of the account, displayed in its representations
6419 description: text or bio displayed on the account's profile
6427 description: timestamp within the video, in seconds
6434 Event since last viewing call:
6435 * `seek` - If the user seeked the video
6458 VideoStatsRetention:
6470 VideoStatsTimeserie:
6547 allowedForCurrentIP:
6549 requiresEmailVerification:
6567 $ref: '#/components/schemas/VideoResolutionSet'
6584 videoChannelSynchronization:
6657 example: 16810141515
6698 description: URL of the current user page
6705 description: Stack trace of the error if there is one
6708 description: User agent of the web browser that sends the message
6711 description: Additional information regarding this log
6721 totalDailyActiveUsers:
6723 totalWeeklyActiveUsers:
6725 totalMonthlyActiveUsers:
6729 totalLocalVideoViews:
6731 description: Total video views made on the instance
6732 totalLocalVideoComments:
6734 description: Total comments made by local users
6735 totalLocalVideoFilesSize:
6741 totalLocalVideoChannels:
6743 totalLocalDailyActiveVideoChannels:
6745 totalLocalWeeklyActiveVideoChannels:
6747 totalLocalMonthlyActiveVideoChannels:
6749 totalLocalPlaylists:
6751 totalInstanceFollowers:
6753 totalInstanceFollowing:
6770 totalActivityPubMessagesProcessed:
6772 totalActivityPubMessagesSuccesses:
6774 totalActivityPubMessagesErrors:
6777 activityPubMessagesProcessedPerSecond:
6779 totalActivityPubMessagesWaiting:
6856 requiresEmailVerification:
6871 description: Settings that apply to new users, if registration is enabled
6875 example: 16810141515
6881 description: Settings pertaining to transcoding jobs
6885 allowAdditionalExtensions:
6887 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6890 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6893 description: Amount of threads used by ffmpeg for 1 transcoding job
6896 description: Amount of transcoding jobs to execute in parallel
6902 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6905 description: Resolutions to transcode _new videos_ to
6927 description: WebTorrent-specific settings
6933 description: HLS-specific settings
6953 video_channel_synchronization:
6988 $ref: '#/components/schemas/id'
6990 $ref: '#/components/schemas/Actor'
6992 $ref: '#/components/schemas/Actor'
6995 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7008 PredefinedAbuseReasons:
7009 description: Reason categories that help triage reports
7027 $ref: '#/components/schemas/id'
7039 - activitypub-http-unicast
7040 - activitypub-http-broadcast
7041 - activitypub-http-fetcher
7042 - activitypub-follow
7047 - videos-views-stats
7048 - activitypub-refresher
7050 - video-channel-import
7053 additionalProperties: true
7056 additionalProperties: true
7072 $ref: '#/components/schemas/id'
7077 $ref: '#/components/schemas/id'
7078 VideoUploadRequestCommon:
7081 description: Video name
7083 example: What is PeerTube?
7087 description: Channel id that will contain this video
7092 $ref: '#/components/schemas/VideoPrivacySet'
7094 $ref: '#/components/schemas/VideoCategorySet'
7096 $ref: '#/components/schemas/VideoLicenceSet'
7098 $ref: '#/components/schemas/VideoLanguageSet'
7100 description: Video description
7103 **[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)**
7105 description: Whether or not we wait transcoding before publish the video
7108 description: A text tell the audience how to support the video creator
7109 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7112 description: Whether or not this video contains sensitive content
7115 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7128 description: Enable or disable comments for this video
7131 description: Enable or disable downloading for this video
7133 originallyPublishedAt:
7134 description: Date when the content was originally published
7138 $ref: '#/components/schemas/VideoScheduledUpdate'
7140 description: Video thumbnail file
7144 description: Video preview file
7150 VideoUploadRequestLegacy:
7152 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7158 description: Video file
7161 VideoUploadRequestResumable:
7163 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7169 description: Video filename including extension
7172 example: what_is_peertube.mp4
7174 description: Video thumbnail file
7178 description: Video preview file
7181 VideoUploadResponse:
7187 $ref: '#/components/schemas/Video/properties/id'
7189 $ref: '#/components/schemas/Video/properties/uuid'
7191 $ref: '#/components/schemas/Video/properties/shortUUID'
7192 CommentThreadResponse:
7201 $ref: '#/components/schemas/VideoComment'
7202 CommentThreadPostResponse:
7205 $ref: '#/components/schemas/VideoComment'
7215 $ref: '#/components/schemas/Video'
7219 $ref: '#/components/schemas/Account'
7222 description: Automatically start playing the upcoming video after the currently playing video
7223 autoPlayNextVideoPlaylist:
7225 description: Automatically start playing the video on the playlist after the currently playing video
7228 description: Automatically start playing the video on the watch page
7238 description: The user email
7241 description: Has the user confirmed their email address?
7244 - $ref: '#/components/schemas/id'
7248 description: Auth plugin to use to authenticate the user
7252 noInstanceConfigWarningModal:
7254 noAccountSetupWarningModal:
7259 $ref: '#/components/schemas/NSFWPolicy'
7261 $ref: '#/components/schemas/UserRole'
7270 description: Theme enabled by this user
7272 $ref: '#/components/schemas/username'
7276 $ref: '#/components/schemas/VideoChannel'
7279 description: The user video quota in bytes
7283 description: The user daily video quota in bytes
7287 description: Enable P2P in the player
7290 - $ref: '#/components/schemas/User'
7292 # optionally present fields: they require WITH_STATS scope
7295 description: Count of videos published
7298 description: Count of reports/abuses of which the user is a target
7299 abusesAcceptedCount:
7301 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7304 description: Count of reports/abuses created by the user
7307 description: Count of comments published
7311 $ref: '#/components/schemas/username'
7313 $ref: '#/components/schemas/password'
7317 description: The user email
7320 description: The user video quota in bytes
7324 description: The user daily video quota in bytes
7327 $ref: '#/components/schemas/usernameChannel'
7329 $ref: '#/components/schemas/UserRole'
7331 $ref: '#/components/schemas/UserAdminFlags'
7342 description: The updated email of the user
7344 - $ref: '#/components/schemas/User/properties/email'
7347 description: Set the email as verified
7350 description: The updated video quota of the user in bytes
7353 description: The updated daily video quota of the user in bytes
7357 description: The auth plugin to use to authenticate the user
7358 example: 'peertube-plugin-auth-saml2'
7360 $ref: '#/components/schemas/UserRole'
7362 $ref: '#/components/schemas/UserAdminFlags'
7364 $ref: '#/components/schemas/password'
7366 # see shared/models/users/user-update-me.model.ts:
7369 $ref: '#/components/schemas/password'
7371 $ref: '#/components/schemas/password'
7373 description: new email used for login and service communications
7375 - $ref: '#/components/schemas/User/properties/email'
7378 description: new name of the user in its representations
7383 description: new NSFW display policy
7390 description: whether to enable P2P in the player or not
7393 description: new preference regarding playing videos automatically
7396 description: new preference regarding playing following videos automatically
7397 autoPlayNextVideoPlaylist:
7399 description: new preference regarding playing following playlist videos automatically
7400 videosHistoryEnabled:
7402 description: whether to keep track of watched history or not
7407 description: list of languages to filter videos down to
7410 noInstanceConfigWarningModal:
7412 noAccountSetupWarningModal:
7419 $ref: '#/components/schemas/id'
7426 description: Rating of the video
7433 $ref: '#/components/schemas/Video'
7440 description: Rating of the video
7447 description: immutable name of the user, used to find or mention its actor
7449 - $ref: '#/components/schemas/username'
7451 $ref: '#/components/schemas/password'
7455 description: email of the user, used for login or service communications
7458 description: editable name of the user, displayed in its representations
7463 description: channel base information used to create the first channel of the user
7466 $ref: '#/components/schemas/usernameChannel'
7478 pattern: /^[a-z0-9]$/
7481 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7484 pattern: /^[a-zA-Z0-9]$/
7487 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7488 OAuthToken-password:
7490 - $ref: '#/components/schemas/OAuthClient'
7500 $ref: '#/components/schemas/User/properties/username'
7502 $ref: '#/components/schemas/password'
7509 OAuthToken-refresh_token:
7511 - $ref: '#/components/schemas/OAuthClient'
7522 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7531 - $ref: '#/components/schemas/Actor'
7536 description: editable name of the channel, displayed in its representations
7537 example: Videos of Framasoft
7542 example: Videos made with <3 by Framasoft
7547 description: text shown by default on all videos of this channel, to tell the audience how to support it
7548 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7561 $ref: '#/components/schemas/ActorImage'
7570 $ref: '#/components/schemas/UUIDv4'
7574 - $ref: '#/components/schemas/VideoChannel'
7577 description: username of the channel to create
7579 - $ref: '#/components/schemas/usernameChannel'
7585 - $ref: '#/components/schemas/VideoChannel'
7587 bulkVideosSupportUpdate:
7589 description: Update the support field for all videos of this channel
7599 - $ref: '#/components/schemas/VideoChannel'
7600 - $ref: '#/components/schemas/Actor'
7606 $ref: '#/components/schemas/id'
7618 example: 'https://youtube.com/c/UC_myfancychannel'
7627 $ref: '#/components/schemas/VideoChannel'
7628 VideoChannelSyncList:
7638 - $ref: '#/components/schemas/VideoChannelSync'
7639 VideoChannelSyncCreate:
7644 example: https://youtube.com/c/UC_myfancychannel
7646 $ref: '#/components/schemas/id'
7650 name: 'media:peerLink'
7659 - application/x-bittorrent
7665 name: 'media:content'
7696 VideoCommentsForXML:
7731 description: video watch page URL
7734 description: video canonical URL
7738 description: video publication date
7741 description: video description
7744 description: video description
7747 description: publisher user name
7750 description: video category (MRSS)
7753 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7768 description: video embed path, relative to the canonical URL domain (MRSS)
7777 description: video watch path, relative to the canonical URL domain (MRSS)
7798 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7799 'media:description':
7806 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7809 description: main streamable file for the video
7819 - application/x-bittorrent
7828 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)
7831 - $ref: '#/components/schemas/MRSSPeerLink'
7832 - $ref: '#/components/schemas/MRSSGroupContent'
7833 NotificationSettingValue:
7850 $ref: '#/components/schemas/id'
7854 Notification type, following the `UserNotificationType` enum:
7856 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7858 - `2` NEW_COMMENT_ON_MY_VIDEO
7860 - `3` NEW_ABUSE_FOR_MODERATORS
7862 - `4` BLACKLIST_ON_MY_VIDEO
7864 - `5` UNBLACKLIST_ON_MY_VIDEO
7866 - `6` MY_VIDEO_PUBLISHED
7868 - `7` MY_VIDEO_IMPORT_SUCCESS
7870 - `8` MY_VIDEO_IMPORT_ERROR
7872 - `9` NEW_USER_REGISTRATION
7876 - `11` COMMENT_MENTION
7878 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7880 - `13` NEW_INSTANCE_FOLLOWER
7882 - `14` AUTO_INSTANCE_FOLLOWING
7884 - `15` ABUSE_STATE_CHANGE
7886 - `16` ABUSE_NEW_MESSAGE
7888 - `17` NEW_PLUGIN_VERSION
7890 - `18` NEW_PEERTUBE_VERSION
7896 - $ref: '#/components/schemas/VideoInfo'
7900 $ref: '#/components/schemas/ActorInfo'
7906 $ref: '#/components/schemas/id'
7909 $ref: '#/components/schemas/VideoInfo'
7914 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7924 $ref: '#/components/schemas/id'
7928 $ref: '#/components/schemas/VideoInfo'
7930 $ref: '#/components/schemas/ActorInfo'
7936 $ref: '#/components/schemas/id'
7939 - $ref: '#/components/schemas/VideoInfo'
7945 $ref: '#/components/schemas/id'
7948 - $ref: '#/components/schemas/VideoInfo'
7952 - $ref: '#/components/schemas/ActorInfo'
7958 $ref: '#/components/schemas/id'
7960 $ref: '#/components/schemas/ActorInfo'
7988 NotificationListResponse:
7997 $ref: '#/components/schemas/Notification'
8002 example: peertube-plugin-auth-ldap
8030 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8033 additionalProperties: true
8049 $ref: '#/components/schemas/Plugin'
8056 description: User can stream multiple times in a permanent live
8059 description: User can select live latency mode if enabled by the instance
8060 $ref: '#/components/schemas/LiveVideoLatencyMode'
8066 description: Included in the response if an appropriate token is provided
8069 description: Included in the response if an appropriate token is provided
8072 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8076 description: User can stream multiple times in a permanent live
8079 description: User can select live latency mode if enabled by the instance
8080 $ref: '#/components/schemas/LiveVideoLatencyMode'
8082 VideoStudioCreateTask:
8130 title: add-watermark
8144 LiveVideoSessionResponse:
8151 description: Start date of the live session
8156 description: End date of the live session
8167 Error type if an error occurred during the live session:
8168 - `1`: Bad socket health (transcoding is too slow)
8169 - `2`: Max duration exceeded
8170 - `3`: Quota exceeded
8171 - `4`: Quota FFmpeg error
8172 - `5`: Video has been blacklisted during the live
8175 description: Video replay information
8180 $ref: '#/components/schemas/UUIDv4'
8182 $ref: '#/components/schemas/shortUUID'
8186 'https://search.example.org/api/v1/search/videos':
8188 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8191 description: successful operation
8195 $ref: '#/components/schemas/VideoListResponse'