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'
1194 description: Filter on import target URL
1198 name: videoChannelSyncId
1201 description: Filter on imports created by a specific channel synchronization
1206 description: successful operation
1210 $ref: '#/components/schemas/VideoImportsList'
1212 /users/me/video-quota-used:
1214 summary: Get my user used quota
1222 description: successful operation
1230 description: The user video quota used so far in bytes
1231 example: 16810141515
1232 videoQuotaUsedDaily:
1234 description: The user video quota used today in bytes
1237 '/users/me/videos/{videoId}/rating':
1239 summary: Get rate of my user for a video
1249 description: The video id
1251 $ref: '#/components/schemas/Video/properties/id'
1254 description: successful operation
1258 $ref: '#/components/schemas/GetMeVideoRating'
1262 summary: Get videos of my user
1270 - $ref: '#/components/parameters/start'
1271 - $ref: '#/components/parameters/count'
1272 - $ref: '#/components/parameters/sort'
1275 description: successful operation
1279 $ref: '#/components/schemas/VideoListResponse'
1281 /users/me/subscriptions:
1283 summary: Get my user subscriptions
1290 - $ref: '#/components/parameters/start'
1291 - $ref: '#/components/parameters/count'
1292 - $ref: '#/components/parameters/sort'
1295 description: successful operation
1299 $ref: '#/components/schemas/VideoChannelList'
1303 summary: Add subscription to my user
1316 description: uri of the video channels to subscribe to
1322 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1325 description: successful operation
1327 /users/me/subscriptions/exist:
1329 summary: Get if subscriptions exist for my user
1336 - $ref: '#/components/parameters/subscriptionsUris'
1339 description: successful operation
1345 /users/me/subscriptions/videos:
1347 summary: List videos of subscriptions of my user
1355 - $ref: '#/components/parameters/categoryOneOf'
1356 - $ref: '#/components/parameters/isLive'
1357 - $ref: '#/components/parameters/tagsOneOf'
1358 - $ref: '#/components/parameters/tagsAllOf'
1359 - $ref: '#/components/parameters/licenceOneOf'
1360 - $ref: '#/components/parameters/languageOneOf'
1361 - $ref: '#/components/parameters/nsfw'
1362 - $ref: '#/components/parameters/isLocal'
1363 - $ref: '#/components/parameters/include'
1364 - $ref: '#/components/parameters/privacyOneOf'
1365 - $ref: '#/components/parameters/hasHLSFiles'
1366 - $ref: '#/components/parameters/hasWebtorrentFiles'
1367 - $ref: '#/components/parameters/skipCount'
1368 - $ref: '#/components/parameters/start'
1369 - $ref: '#/components/parameters/count'
1370 - $ref: '#/components/parameters/videosSort'
1373 description: successful operation
1377 $ref: '#/components/schemas/VideoListResponse'
1379 '/users/me/subscriptions/{subscriptionHandle}':
1381 summary: Get subscription of my user
1388 - $ref: '#/components/parameters/subscriptionHandle'
1391 description: successful operation
1395 $ref: '#/components/schemas/VideoChannel'
1397 summary: Delete subscription of my user
1404 - $ref: '#/components/parameters/subscriptionHandle'
1407 description: successful operation
1409 /users/me/notifications:
1411 summary: List my notifications
1419 description: only list unread notifications
1422 - $ref: '#/components/parameters/start'
1423 - $ref: '#/components/parameters/count'
1424 - $ref: '#/components/parameters/sort'
1427 description: successful operation
1431 $ref: '#/components/schemas/NotificationListResponse'
1433 /users/me/notifications/read:
1435 summary: Mark notifications as read by their id
1448 description: ids of the notifications to mark as read
1455 description: successful operation
1457 /users/me/notifications/read-all:
1459 summary: Mark all my notification as read
1466 description: successful operation
1468 /users/me/notification-settings:
1470 summary: Update my notification settings
1481 newVideoFromSubscription:
1482 $ref: '#/components/schemas/NotificationSettingValue'
1483 newCommentOnMyVideo:
1484 $ref: '#/components/schemas/NotificationSettingValue'
1486 $ref: '#/components/schemas/NotificationSettingValue'
1487 videoAutoBlacklistAsModerator:
1488 $ref: '#/components/schemas/NotificationSettingValue'
1490 $ref: '#/components/schemas/NotificationSettingValue'
1492 $ref: '#/components/schemas/NotificationSettingValue'
1493 myVideoImportFinished:
1494 $ref: '#/components/schemas/NotificationSettingValue'
1496 $ref: '#/components/schemas/NotificationSettingValue'
1497 newUserRegistration:
1498 $ref: '#/components/schemas/NotificationSettingValue'
1500 $ref: '#/components/schemas/NotificationSettingValue'
1501 newInstanceFollower:
1502 $ref: '#/components/schemas/NotificationSettingValue'
1503 autoInstanceFollowing:
1504 $ref: '#/components/schemas/NotificationSettingValue'
1507 description: successful operation
1509 /users/me/history/videos:
1511 summary: List watched videos history
1517 - $ref: '#/components/parameters/start'
1518 - $ref: '#/components/parameters/count'
1519 - $ref: '#/components/parameters/search'
1522 description: successful operation
1526 $ref: '#/components/schemas/VideoListResponse'
1528 /users/me/history/videos/{videoId}:
1530 summary: Delete history element
1540 $ref: '#/components/schemas/Video/properties/id'
1543 description: successful operation
1545 /users/me/history/videos/remove:
1547 summary: Clear video history
1554 multipart/form-data:
1559 description: history before this date will be deleted
1564 description: successful operation
1566 /users/me/avatar/pick:
1568 summary: Update my user avatar
1575 description: successful operation
1584 $ref: '#/components/schemas/ActorImage'
1586 description: image file too large
1588 X-File-Maximum-Size:
1592 description: Maximum file size for the avatar
1595 multipart/form-data:
1600 description: The file to upload
1605 contentType: image/png, image/jpeg
1609 summary: Delete my avatar
1616 description: successful operation
1620 summary: List video ownership changes
1622 - Video Ownership Change
1627 description: successful operation
1629 '/videos/ownership/{id}/accept':
1631 summary: Accept ownership change request
1633 - Video Ownership Change
1637 - $ref: '#/components/parameters/idOrUUID'
1640 description: successful operation
1642 description: cannot terminate an ownership change of another user
1644 description: video ownership change not found
1646 '/videos/ownership/{id}/refuse':
1648 summary: Refuse ownership change request
1650 - Video Ownership Change
1654 - $ref: '#/components/parameters/idOrUUID'
1657 description: successful operation
1659 description: cannot terminate an ownership change of another user
1661 description: video ownership change not found
1663 '/videos/{id}/give-ownership':
1665 summary: Request ownership change
1667 - Video Ownership Change
1671 - $ref: '#/components/parameters/idOrUUID'
1675 application/x-www-form-urlencoded:
1685 description: successful operation
1687 description: changing video ownership to a remote account is not supported yet
1689 description: video not found
1691 /videos/{id}/studio/edit:
1693 summary: Create a studio task
1697 description: Create a task to edit a video (cut, add intro/outro etc)
1701 - $ref: '#/components/parameters/idOrUUID'
1705 application/x-www-form-urlencoded:
1707 $ref: '#/components/schemas/VideoStudioCreateTask'
1710 description: successful operation
1712 description: incorrect parameters
1714 description: video not found
1718 summary: List videos
1719 operationId: getVideos
1723 - $ref: '#/components/parameters/categoryOneOf'
1724 - $ref: '#/components/parameters/isLive'
1725 - $ref: '#/components/parameters/tagsOneOf'
1726 - $ref: '#/components/parameters/tagsAllOf'
1727 - $ref: '#/components/parameters/licenceOneOf'
1728 - $ref: '#/components/parameters/languageOneOf'
1729 - $ref: '#/components/parameters/nsfw'
1730 - $ref: '#/components/parameters/isLocal'
1731 - $ref: '#/components/parameters/include'
1732 - $ref: '#/components/parameters/privacyOneOf'
1733 - $ref: '#/components/parameters/hasHLSFiles'
1734 - $ref: '#/components/parameters/hasWebtorrentFiles'
1735 - $ref: '#/components/parameters/skipCount'
1736 - $ref: '#/components/parameters/start'
1737 - $ref: '#/components/parameters/count'
1738 - $ref: '#/components/parameters/videosSort'
1741 description: successful operation
1745 $ref: '#/components/schemas/VideoListResponse'
1749 summary: List available video categories
1750 operationId: getCategories
1755 description: successful operation
1764 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1768 summary: List available video licences
1769 operationId: getLicences
1774 description: successful operation
1783 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1787 summary: List available video languages
1788 operationId: getLanguages
1793 description: successful operation
1802 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1806 summary: List available video privacy policies
1807 operationId: getPrivacyPolicies
1812 description: successful operation
1821 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1825 summary: Update a video
1826 operationId: putVideo
1832 - $ref: '#/components/parameters/idOrUUID'
1835 description: successful operation
1838 multipart/form-data:
1843 description: Video thumbnail file
1847 description: Video preview file
1851 $ref: '#/components/schemas/VideoCategorySet'
1853 $ref: '#/components/schemas/VideoLicenceSet'
1855 $ref: '#/components/schemas/VideoLanguageSet'
1857 $ref: '#/components/schemas/VideoPrivacySet'
1859 description: Video description
1862 description: Whether or not we wait transcoding before publish the video
1865 description: A text tell the audience how to support the video creator
1866 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1869 description: Whether or not this video contains sensitive content
1872 description: Video name
1877 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1886 description: Enable or disable comments for this video
1889 description: Enable or disable downloading for this video
1891 originallyPublishedAt:
1892 description: Date when the content was originally published
1896 $ref: '#/components/schemas/VideoScheduledUpdate'
1899 contentType: image/jpeg
1901 contentType: image/jpeg
1903 summary: Get a video
1904 operationId: getVideo
1908 - $ref: '#/components/parameters/idOrUUID'
1911 description: successful operation
1915 $ref: '#/components/schemas/VideoDetails'
1917 summary: Delete a video
1918 operationId: delVideo
1924 - $ref: '#/components/parameters/idOrUUID'
1927 description: successful operation
1929 '/videos/{id}/description':
1931 summary: Get complete video description
1932 operationId: getVideoDesc
1936 - $ref: '#/components/parameters/idOrUUID'
1939 description: successful operation
1948 **[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)**
1950 '/videos/{id}/source':
1952 summary: Get video source file metadata
1953 operationId: getVideoSource
1957 - $ref: '#/components/parameters/idOrUUID'
1960 description: successful operation
1964 $ref: '#/components/schemas/VideoSource'
1966 '/videos/{id}/views':
1968 summary: Notify user is watching a video
1969 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.
1970 operationId: addView
1974 - $ref: '#/components/parameters/idOrUUID'
1979 $ref: '#/components/schemas/UserViewingVideo'
1983 description: successful operation
1985 '/videos/{id}/watching':
1987 summary: Set watching progress of a video
1989 description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
1995 - $ref: '#/components/parameters/idOrUUID'
2000 $ref: '#/components/schemas/UserViewingVideo'
2004 description: successful operation
2006 '/videos/{id}/stats/overall':
2008 summary: Get overall stats of a video
2014 - $ref: '#/components/parameters/idOrUUID'
2017 description: Filter stats by start date
2023 description: Filter stats by end date
2029 description: successful operation
2033 $ref: '#/components/schemas/VideoStatsOverall'
2035 '/videos/{id}/stats/retention':
2037 summary: Get retention stats of a video
2043 - $ref: '#/components/parameters/idOrUUID'
2046 description: successful operation
2050 $ref: '#/components/schemas/VideoStatsRetention'
2052 '/videos/{id}/stats/timeseries/{metric}':
2054 summary: Get timeserie stats of a video
2060 - $ref: '#/components/parameters/idOrUUID'
2065 description: The metric to get
2070 - 'aggregateWatchTime'
2073 description: Filter stats by start date
2079 description: Filter stats by end date
2085 description: successful operation
2089 $ref: '#/components/schemas/VideoStatsTimeserie'
2093 summary: Upload a video
2094 description: Uses a single request to upload a video.
2095 operationId: uploadLegacy
2103 description: successful operation
2107 $ref: '#/components/schemas/VideoUploadResponse'
2109 description: video didn't pass upload filter
2111 description: upload has timed out
2113 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
2115 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
2116 - `quota_reached` for quota limits whether daily or global
2118 X-File-Maximum-Size:
2122 description: Maximum file size for the video
2124 description: video type unsupported
2126 description: video unreadable
2129 multipart/form-data:
2131 $ref: '#/components/schemas/VideoUploadRequestLegacy'
2134 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
2136 contentType: image/jpeg
2138 contentType: image/jpeg
2143 USERNAME="<your_username>"
2144 PASSWORD="<your_password>"
2145 FILE_PATH="<your_file_path>"
2146 CHANNEL_ID="<your_channel_id>"
2148 API="https://peertube2.cpy.re/api/v1"
2151 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
2152 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
2153 token=$(curl -s "$API/users/token" \
2154 --data client_id="$client_id" \
2155 --data client_secret="$client_secret" \
2156 --data grant_type=password \
2157 --data username="$USERNAME" \
2158 --data password="$PASSWORD" \
2159 | jq -r ".access_token")
2162 curl -s "$API/videos/upload" \
2163 -H "Authorization: Bearer $token" \
2165 --form videofile=@"$FILE_PATH" \
2166 --form channelId=$CHANNEL_ID \
2169 /videos/upload-resumable:
2171 summary: Initialize the resumable upload of a video
2172 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
2173 operationId: uploadResumableInit
2180 - name: X-Upload-Content-Length
2186 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2187 - name: X-Upload-Content-Type
2194 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2199 $ref: '#/components/schemas/VideoUploadRequestResumable'
2202 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2204 description: created
2210 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2216 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2218 Disambiguate via `type`:
2219 - `max_file_size_reached` for the absolute file size limit
2220 - `quota_reached` for quota limits whether daily or global
2222 description: video type unsupported
2224 summary: Send chunk for the resumable upload of a video
2225 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
2226 operationId: uploadResumable
2237 Created session id to proceed with. If you didn't send chunks in the last hour, it is
2238 not valid anymore and you need to initialize a new upload.
2241 - name: Content-Range
2245 example: bytes 0-262143/2469036
2248 Specifies the bytes in the file that the request is uploading.
2250 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2251 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2252 - name: Content-Length
2259 Size of the chunk that the request is sending.
2261 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2262 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2265 application/octet-stream:
2271 description: last chunk received
2279 $ref: '#/components/schemas/VideoUploadResponse'
2281 description: resume incomplete
2286 example: bytes=0-262143
2292 description: video didn't pass upload filter
2294 description: upload not found
2296 description: chunk doesn't match range
2298 description: video unreadable
2300 description: too many concurrent requests
2302 description: upload is already being processed
2309 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2310 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2311 operationId: uploadResumableCancel
2322 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2323 not valid anymore and the upload session has already been deleted with its data ;-)
2326 - name: Content-Length
2334 description: upload cancelled
2341 description: upload not found
2345 summary: Import a video
2346 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2347 operationId: importVideo
2355 multipart/form-data:
2357 $ref: '#/components/schemas/VideoCreateImport'
2360 contentType: application/x-bittorrent
2362 contentType: image/jpeg
2364 contentType: image/jpeg
2367 description: successful operation
2371 $ref: '#/components/schemas/VideoUploadResponse'
2373 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2375 description: video didn't pass pre-import filter
2377 description: HTTP or Torrent/magnetURI import not enabled
2379 /videos/imports/{id}/cancel:
2381 summary: Cancel video import
2382 description: Cancel a pending video import
2388 - $ref: '#/components/parameters/id'
2391 description: successful operation
2393 /videos/imports/{id}:
2395 summary: Delete video import
2396 description: Delete ended video import
2402 - $ref: '#/components/parameters/id'
2405 description: successful operation
2409 summary: Create a live
2410 operationId: addLive
2418 description: successful operation
2422 $ref: '#/components/schemas/VideoUploadResponse'
2424 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2426 Disambiguate via `type`:
2427 - default type for a validation error
2428 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2430 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2432 Disambiguate via `type`:
2433 - `live_not_enabled` for a disabled live feature
2434 - `live_not_allowing_replay` for a disabled replay feature
2435 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2436 - `max_user_lives_limit_reached` for the user concurrent live limit
2439 multipart/form-data:
2444 description: Channel id that will contain this live video
2449 description: User can stream multiple times in a permanent live
2452 description: User can select live latency mode if enabled by the instance
2453 $ref: '#/components/schemas/LiveVideoLatencyMode'
2455 description: Live video/replay thumbnail file
2459 description: Live video/replay preview file
2463 $ref: '#/components/schemas/VideoPrivacySet'
2465 $ref: '#/components/schemas/VideoCategorySet'
2467 $ref: '#/components/schemas/VideoLicenceSet'
2469 $ref: '#/components/schemas/VideoLanguageSet'
2471 description: Live video/replay description
2474 description: A text tell the audience how to support the creator
2475 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2478 description: Whether or not this live video/replay contains sensitive content
2481 description: Live video/replay name
2486 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2495 description: Enable or disable comments for this live video/replay
2498 description: Enable or disable downloading for the replay of this live video
2505 contentType: image/jpeg
2507 contentType: image/jpeg
2511 summary: Get information about a live
2512 operationId: getLiveId
2519 - $ref: '#/components/parameters/idOrUUID'
2522 description: successful operation
2526 $ref: '#/components/schemas/LiveVideoResponse'
2528 summary: Update information about a live
2529 operationId: updateLiveId
2536 - $ref: '#/components/parameters/idOrUUID'
2541 $ref: '#/components/schemas/LiveVideoUpdate'
2544 description: successful operation
2546 description: bad parameters or trying to update a live that has already started
2548 description: trying to save replay of the live but saving replay is not enabled on the instance
2549 /videos/live/{id}/sessions:
2551 summary: List live sessions
2552 description: List all sessions created in a particular live
2558 - $ref: '#/components/parameters/idOrUUID'
2561 description: successful operation
2573 $ref: '#/components/schemas/LiveVideoSessionResponse'
2574 /videos/{id}/live-session:
2576 summary: Get live session of a replay
2577 description: If the video is a replay of a live, you can find the associated live session using this endpoint
2583 - $ref: '#/components/parameters/idOrUUID'
2586 description: successful operation
2590 $ref: '#/components/schemas/LiveVideoSessionResponse'
2594 summary: List my abuses
2595 operationId: getMyAbuses
2604 description: only list the report with this id
2610 $ref: '#/components/schemas/AbuseStateSet'
2611 - $ref: '#/components/parameters/abusesSort'
2612 - $ref: '#/components/parameters/start'
2613 - $ref: '#/components/parameters/count'
2616 description: successful operation
2628 $ref: '#/components/schemas/Abuse'
2632 summary: List abuses
2633 operationId: getAbuses
2643 description: only list the report with this id
2646 - name: predefinedReason
2648 description: predefined reason the listed reports should contain
2650 $ref: '#/components/schemas/PredefinedAbuseReasons'
2653 description: plain search that will match with video titles, reporter names and more
2659 $ref: '#/components/schemas/AbuseStateSet'
2660 - name: searchReporter
2662 description: only list reports of a specific reporter
2665 - name: searchReportee
2666 description: only list reports of a specific reportee
2672 description: only list reports of a specific video
2675 - name: searchVideoChannel
2677 description: only list reports of a specific video channel
2682 description: only list deleted or blocklisted videos
2690 description: only list account, comment or video reports
2697 - $ref: '#/components/parameters/start'
2698 - $ref: '#/components/parameters/count'
2699 - $ref: '#/components/parameters/abusesSort'
2702 description: successful operation
2714 $ref: '#/components/schemas/Abuse'
2716 summary: Report an abuse
2729 description: Reason why the user reports this video
2734 $ref: '#/components/schemas/PredefinedAbuseReasons'
2739 description: Video id to report
2741 - $ref: '#/components/schemas/Video/properties/id'
2745 description: Timestamp in the video that marks the beginning of the report
2750 description: Timestamp in the video that marks the ending of the report
2756 description: Comment id to report
2758 - $ref: '#/components/schemas/VideoComment/properties/id'
2763 description: Account id to report
2769 description: successful operation
2779 $ref: '#/components/schemas/id'
2781 description: incorrect request parameters
2783 '/abuses/{abuseId}':
2785 summary: Update an abuse
2793 - $ref: '#/components/parameters/abuseId'
2801 $ref: '#/components/schemas/AbuseStateSet'
2804 description: Update the report comment visible only to the moderation team
2809 description: successful operation
2811 description: abuse not found
2815 summary: Delete an abuse
2821 - $ref: '#/components/parameters/abuseId'
2824 description: successful operation
2826 description: block not found
2828 '/abuses/{abuseId}/messages':
2830 summary: List messages of an abuse
2836 - $ref: '#/components/parameters/abuseId'
2839 description: successful operation
2851 $ref: '#/components/schemas/AbuseMessage'
2853 summary: Add message to an abuse
2859 - $ref: '#/components/parameters/abuseId'
2868 description: Message to send
2876 description: successful operation
2878 description: incorrect request parameters
2880 '/abuses/{abuseId}/messages/{abuseMessageId}':
2882 summary: Delete an abuse message
2888 - $ref: '#/components/parameters/abuseId'
2889 - $ref: '#/components/parameters/abuseMessageId'
2892 description: successful operation
2894 '/videos/{id}/blacklist':
2896 summary: Block a video
2897 operationId: addVideoBlock
2905 - $ref: '#/components/parameters/idOrUUID'
2908 description: successful operation
2910 summary: Unblock a video by its id
2911 operationId: delVideoBlock
2919 - $ref: '#/components/parameters/idOrUUID'
2922 description: successful operation
2924 description: block not found
2930 summary: List video blocks
2931 operationId: getVideoBlocks
2940 list only blocks that match this type:
2944 - `2`: automatic block that needs review
2952 description: plain search that will match with video titles, and more
2955 - $ref: '#/components/parameters/start'
2956 - $ref: '#/components/parameters/count'
2957 - $ref: '#/components/parameters/blacklistsSort'
2960 description: successful operation
2972 $ref: '#/components/schemas/VideoBlacklist'
2974 /videos/{id}/captions:
2976 summary: List captions of a video
2977 operationId: getVideoCaptions
2981 - $ref: '#/components/parameters/idOrUUID'
2984 description: successful operation
2996 $ref: '#/components/schemas/VideoCaption'
2998 /videos/{id}/captions/{captionLanguage}:
3000 summary: Add or replace a video caption
3001 operationId: addVideoCaption
3008 - $ref: '#/components/parameters/idOrUUID'
3009 - $ref: '#/components/parameters/captionLanguage'
3012 multipart/form-data:
3017 description: The file to upload.
3022 contentType: text/vtt, application/x-subrip, text/plain
3025 description: successful operation
3027 description: video or language not found
3029 summary: Delete a video caption
3030 operationId: delVideoCaption
3037 - $ref: '#/components/parameters/idOrUUID'
3038 - $ref: '#/components/parameters/captionLanguage'
3041 description: successful operation
3043 description: video or language or caption for that language not found
3047 summary: List video channels
3048 operationId: getVideoChannels
3052 - $ref: '#/components/parameters/start'
3053 - $ref: '#/components/parameters/count'
3054 - $ref: '#/components/parameters/sort'
3057 description: successful operation
3061 $ref: '#/components/schemas/VideoChannelList'
3063 summary: Create a video channel
3064 operationId: addVideoChannel
3071 description: successful operation
3081 $ref: '#/components/schemas/id'
3086 $ref: '#/components/schemas/VideoChannelCreate'
3088 '/video-channels/{channelHandle}':
3090 summary: Get a video channel
3091 operationId: getVideoChannel
3095 - $ref: '#/components/parameters/channelHandle'
3098 description: successful operation
3102 $ref: '#/components/schemas/VideoChannel'
3104 summary: Update a video channel
3105 operationId: putVideoChannel
3111 - $ref: '#/components/parameters/channelHandle'
3114 description: successful operation
3119 $ref: '#/components/schemas/VideoChannelUpdate'
3121 summary: Delete a video channel
3122 operationId: delVideoChannel
3128 - $ref: '#/components/parameters/channelHandle'
3131 description: successful operation
3133 '/video-channels/{channelHandle}/videos':
3135 summary: List videos of a video channel
3136 operationId: getVideoChannelVideos
3141 - $ref: '#/components/parameters/channelHandle'
3142 - $ref: '#/components/parameters/categoryOneOf'
3143 - $ref: '#/components/parameters/isLive'
3144 - $ref: '#/components/parameters/tagsOneOf'
3145 - $ref: '#/components/parameters/tagsAllOf'
3146 - $ref: '#/components/parameters/licenceOneOf'
3147 - $ref: '#/components/parameters/languageOneOf'
3148 - $ref: '#/components/parameters/nsfw'
3149 - $ref: '#/components/parameters/isLocal'
3150 - $ref: '#/components/parameters/include'
3151 - $ref: '#/components/parameters/privacyOneOf'
3152 - $ref: '#/components/parameters/hasHLSFiles'
3153 - $ref: '#/components/parameters/hasWebtorrentFiles'
3154 - $ref: '#/components/parameters/skipCount'
3155 - $ref: '#/components/parameters/start'
3156 - $ref: '#/components/parameters/count'
3157 - $ref: '#/components/parameters/videosSort'
3160 description: successful operation
3164 $ref: '#/components/schemas/VideoListResponse'
3166 '/video-channels/{channelHandle}/followers':
3170 summary: 'List followers of a video channel'
3173 operationId: getVideoChannelFollowers
3175 - $ref: '#/components/parameters/channelHandle'
3176 - $ref: '#/components/parameters/start'
3177 - $ref: '#/components/parameters/count'
3178 - $ref: '#/components/parameters/followersSort'
3179 - $ref: '#/components/parameters/search'
3182 description: successful operation
3194 $ref: '#/components/schemas/Follow'
3196 '/video-channels/{channelHandle}/avatar/pick':
3198 summary: Update channel avatar
3204 - $ref: '#/components/parameters/channelHandle'
3207 description: successful operation
3216 $ref: '#/components/schemas/ActorImage'
3218 description: image file too large
3220 X-File-Maximum-Size:
3224 description: Maximum file size for the avatar
3227 multipart/form-data:
3232 description: The file to upload.
3237 contentType: image/png, image/jpeg
3239 '/video-channels/{channelHandle}/avatar':
3241 summary: Delete channel avatar
3247 - $ref: '#/components/parameters/channelHandle'
3250 description: successful operation
3252 '/video-channels/{channelHandle}/banner/pick':
3254 summary: Update channel banner
3260 - $ref: '#/components/parameters/channelHandle'
3263 description: successful operation
3272 $ref: '#/components/schemas/ActorImage'
3274 description: image file too large
3276 X-File-Maximum-Size:
3280 description: Maximum file size for the banner
3283 multipart/form-data:
3288 description: The file to upload.
3293 contentType: image/png, image/jpeg
3295 '/video-channels/{channelHandle}/banner':
3297 summary: Delete channel banner
3303 - $ref: '#/components/parameters/channelHandle'
3306 description: successful operation
3308 '/video-channel-syncs':
3310 summary: Create a synchronization for a video channel
3311 operationId: addVideoChannelSync
3320 $ref: '#/components/schemas/VideoChannelSyncCreate'
3323 description: successful operation
3330 $ref: "#/components/schemas/VideoChannelSync"
3332 '/video-channel-syncs/{channelSyncId}':
3334 summary: Delete a video channel synchronization
3335 operationId: delVideoChannelSync
3341 - $ref: '#/components/parameters/channelSyncId'
3344 description: successful operation
3346 '/video-channel-syncs/{channelSyncId}/sync':
3348 summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
3349 operationId: triggerVideoChannelSync
3355 - $ref: '#/components/parameters/channelSyncId'
3358 description: successful operation
3361 /video-playlists/privacies:
3363 summary: List available playlist privacy policies
3364 operationId: getPlaylistPrivacyPolicies
3369 description: successful operation
3378 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3382 summary: List video playlists
3383 operationId: getPlaylists
3387 - $ref: '#/components/parameters/start'
3388 - $ref: '#/components/parameters/count'
3389 - $ref: '#/components/parameters/sort'
3392 description: successful operation
3404 $ref: '#/components/schemas/VideoPlaylist'
3406 summary: Create a video playlist
3407 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3408 operationId: addPlaylist
3415 description: successful operation
3425 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3427 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3429 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3432 multipart/form-data:
3437 description: Video playlist display name
3442 description: Video playlist thumbnail file
3446 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3448 description: Video playlist description
3454 - $ref: '#/components/schemas/id'
3455 description: Video channel in which the playlist will be published
3460 contentType: image/jpeg
3462 /video-playlists/{playlistId}:
3464 summary: Get a video playlist
3468 - $ref: '#/components/parameters/playlistId'
3471 description: successful operation
3475 $ref: '#/components/schemas/VideoPlaylist'
3477 summary: Update a video playlist
3478 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3485 description: successful operation
3487 - $ref: '#/components/parameters/playlistId'
3490 multipart/form-data:
3495 description: Video playlist display name
3500 description: Video playlist thumbnail file
3504 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3506 description: Video playlist description
3510 - $ref: '#/components/schemas/id'
3511 description: Video channel in which the playlist will be published
3514 contentType: image/jpeg
3516 summary: Delete a video playlist
3522 - $ref: '#/components/parameters/playlistId'
3525 description: successful operation
3527 /video-playlists/{playlistId}/videos:
3529 summary: 'List videos of a playlist'
3530 operationId: getVideoPlaylistVideos
3535 - $ref: '#/components/parameters/playlistId'
3536 - $ref: '#/components/parameters/start'
3537 - $ref: '#/components/parameters/count'
3540 description: successful operation
3544 $ref: '#/components/schemas/VideoListResponse'
3546 summary: Add a video in a playlist
3547 operationId: addVideoPlaylistVideo
3554 - $ref: '#/components/parameters/playlistId'
3557 description: successful operation
3563 videoPlaylistElement:
3577 - $ref: '#/components/schemas/Video/properties/uuid'
3578 - $ref: '#/components/schemas/Video/properties/id'
3579 description: Video to add in the playlist
3583 description: Start the video at this specific timestamp
3587 description: Stop the video at this specific timestamp
3591 /video-playlists/{playlistId}/videos/reorder:
3593 summary: 'Reorder a playlist'
3594 operationId: reorderVideoPlaylist
3600 - $ref: '#/components/parameters/playlistId'
3603 description: successful operation
3612 description: 'Start position of the element to reorder'
3614 insertAfterPosition:
3616 description: 'New position for the block to reorder, to add the block before the first element'
3620 description: 'How many element from `startPosition` to reorder'
3624 - insertAfterPosition
3626 /video-playlists/{playlistId}/videos/{playlistElementId}:
3628 summary: Update a playlist element
3629 operationId: putVideoPlaylistVideo
3635 - $ref: '#/components/parameters/playlistId'
3636 - $ref: '#/components/parameters/playlistElementId'
3639 description: successful operation
3649 description: Start the video at this specific timestamp
3653 description: Stop the video at this specific timestamp
3655 summary: Delete an element from a playlist
3656 operationId: delVideoPlaylistVideo
3662 - $ref: '#/components/parameters/playlistId'
3663 - $ref: '#/components/parameters/playlistElementId'
3666 description: successful operation
3668 '/users/me/video-playlists/videos-exist':
3670 summary: Check video exists in my playlists
3679 description: The video ids to check
3683 $ref: '#/components/schemas/Video/properties/id'
3686 description: successful operation
3708 '/accounts/{name}/video-channels':
3710 summary: List video channels of an account
3715 - $ref: '#/components/parameters/name'
3718 description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
3721 - $ref: '#/components/parameters/start'
3722 - $ref: '#/components/parameters/count'
3723 - $ref: '#/components/parameters/sort'
3726 description: successful operation
3730 $ref: '#/components/schemas/VideoChannelList'
3732 '/accounts/{name}/video-channel-syncs':
3734 summary: List the synchronizations of video channels of an account
3740 - $ref: '#/components/parameters/name'
3741 - $ref: '#/components/parameters/start'
3742 - $ref: '#/components/parameters/count'
3743 - $ref: '#/components/parameters/sort'
3746 description: successful operation
3750 $ref: '#/components/schemas/VideoChannelSyncList'
3752 '/accounts/{name}/ratings':
3754 summary: List ratings of an account
3760 - $ref: '#/components/parameters/name'
3761 - $ref: '#/components/parameters/start'
3762 - $ref: '#/components/parameters/count'
3763 - $ref: '#/components/parameters/sort'
3767 description: Optionally filter which ratings to retrieve
3775 description: successful operation
3781 $ref: '#/components/schemas/VideoRating'
3783 '/videos/{id}/comment-threads':
3785 summary: List threads of a video
3789 - $ref: '#/components/parameters/idOrUUID'
3790 - $ref: '#/components/parameters/start'
3791 - $ref: '#/components/parameters/count'
3792 - $ref: '#/components/parameters/commentsSort'
3795 description: successful operation
3799 $ref: '#/components/schemas/CommentThreadResponse'
3801 summary: Create a thread
3807 - $ref: '#/components/parameters/idOrUUID'
3810 description: successful operation
3814 $ref: '#/components/schemas/CommentThreadPostResponse'
3816 description: video does not exist
3825 - $ref: '#/components/schemas/VideoComment/properties/text'
3831 '/videos/{id}/comment-threads/{threadId}':
3833 summary: Get a thread
3837 - $ref: '#/components/parameters/idOrUUID'
3838 - $ref: '#/components/parameters/threadId'
3841 description: successful operation
3845 $ref: '#/components/schemas/VideoCommentThreadTree'
3847 '/videos/{id}/comments/{commentId}':
3849 summary: Reply to a thread of a video
3855 - $ref: '#/components/parameters/idOrUUID'
3856 - $ref: '#/components/parameters/commentId'
3859 description: successful operation
3863 $ref: '#/components/schemas/CommentThreadPostResponse'
3865 description: thread or video does not exist
3874 - $ref: '#/components/schemas/VideoComment/properties/text'
3880 summary: Delete a comment or a reply
3886 - $ref: '#/components/parameters/idOrUUID'
3887 - $ref: '#/components/parameters/commentId'
3890 description: successful operation
3892 description: cannot remove comment of another user
3894 description: comment or video does not exist
3896 description: comment is already deleted
3898 '/videos/{id}/rate':
3900 summary: Like/dislike a video
3906 - $ref: '#/components/parameters/idOrUUID'
3922 description: successful operation
3924 description: video does not exist
3928 summary: Delete video HLS files
3934 operationId: delVideoHLS
3936 - $ref: '#/components/parameters/idOrUUID'
3939 description: successful operation
3941 description: video does not exist
3942 '/videos/{id}/webtorrent':
3944 summary: Delete video WebTorrent files
3950 operationId: delVideoWebTorrent
3952 - $ref: '#/components/parameters/idOrUUID'
3955 description: successful operation
3957 description: video does not exist
3959 '/videos/{id}/transcoding':
3961 summary: Create a transcoding job
3967 operationId: createVideoTranscoding
3969 - $ref: '#/components/parameters/idOrUUID'
3985 description: successful operation
3987 description: video does not exist
3993 summary: Search videos
3994 operationId: searchVideos
3999 allowEmptyValue: false
4001 String to search. If the user can make a remote URI search, and the string is an URI then the
4002 PeerTube instance will fetch the remote object and add it to its database. Then,
4003 you can use the REST API to fetch the complete video information and interact with it.
4006 - $ref: '#/components/parameters/categoryOneOf'
4007 - $ref: '#/components/parameters/isLive'
4008 - $ref: '#/components/parameters/tagsOneOf'
4009 - $ref: '#/components/parameters/tagsAllOf'
4010 - $ref: '#/components/parameters/licenceOneOf'
4011 - $ref: '#/components/parameters/languageOneOf'
4012 - $ref: '#/components/parameters/nsfw'
4013 - $ref: '#/components/parameters/isLocal'
4014 - $ref: '#/components/parameters/include'
4015 - $ref: '#/components/parameters/privacyOneOf'
4016 - $ref: '#/components/parameters/hasHLSFiles'
4017 - $ref: '#/components/parameters/hasWebtorrentFiles'
4018 - $ref: '#/components/parameters/skipCount'
4019 - $ref: '#/components/parameters/start'
4020 - $ref: '#/components/parameters/count'
4021 - $ref: '#/components/parameters/searchTarget'
4022 - $ref: '#/components/parameters/videosSearchSort'
4025 description: Get videos that are published after this date
4031 description: Get videos that are published before this date
4035 - name: originallyPublishedStartDate
4037 description: Get videos that are originally published after this date
4041 - name: originallyPublishedEndDate
4043 description: Get videos that are originally published before this date
4049 description: Get videos that have this minimum duration
4054 description: Get videos that have this maximum duration
4058 'searchTarget === search-index':
4059 $ref: '#/components/callbacks/searchIndex'
4062 description: successful operation
4066 $ref: '#/components/schemas/VideoListResponse'
4068 description: search index unavailable
4070 /search/video-channels:
4074 summary: Search channels
4075 operationId: searchChannels
4081 String to search. If the user can make a remote URI search, and the string is an URI then the
4082 PeerTube instance will fetch the remote object and add it to its database. Then,
4083 you can use the REST API to fetch the complete channel information and interact with it.
4086 - $ref: '#/components/parameters/start'
4087 - $ref: '#/components/parameters/count'
4088 - $ref: '#/components/parameters/searchTarget'
4089 - $ref: '#/components/parameters/sort'
4091 'searchTarget === search-index':
4092 $ref: '#/components/callbacks/searchIndex'
4095 description: successful operation
4099 $ref: '#/components/schemas/VideoChannelList'
4101 description: search index unavailable
4103 /search/video-playlists:
4107 summary: Search playlists
4108 operationId: searchPlaylists
4114 String to search. If the user can make a remote URI search, and the string is an URI then the
4115 PeerTube instance will fetch the remote object and add it to its database. Then,
4116 you can use the REST API to fetch the complete playlist information and interact with it.
4119 - $ref: '#/components/parameters/start'
4120 - $ref: '#/components/parameters/count'
4121 - $ref: '#/components/parameters/searchTarget'
4122 - $ref: '#/components/parameters/sort'
4124 'searchTarget === search-index':
4125 $ref: '#/components/callbacks/searchIndex'
4128 description: successful operation
4140 $ref: '#/components/schemas/VideoPlaylist'
4142 description: search index unavailable
4149 summary: Get block status of accounts/hosts
4154 description: 'Check if these accounts are blocked'
4155 example: [ 'goofy@example.com', 'donald@example.com' ]
4163 description: 'Check if these hosts are blocked'
4164 example: [ 'example.com' ]
4171 description: successful operation
4175 $ref: '#/components/schemas/BlockStatus'
4177 /server/blocklist/accounts:
4181 summary: List account blocks
4186 - $ref: '#/components/parameters/start'
4187 - $ref: '#/components/parameters/count'
4188 - $ref: '#/components/parameters/sort'
4191 description: successful operation
4195 summary: Block an account
4207 example: chocobozzz@example.org
4208 description: account to block, in the form `username@domain`
4213 description: successful operation
4215 description: self-blocking forbidden
4217 '/server/blocklist/accounts/{accountName}':
4221 summary: Unblock an account by its handle
4229 description: account to unblock, in the form `username@domain`
4234 description: successful operation
4236 description: account or account block does not exist
4238 /server/blocklist/servers:
4242 summary: List server blocks
4247 - $ref: '#/components/parameters/start'
4248 - $ref: '#/components/parameters/count'
4249 - $ref: '#/components/parameters/sort'
4252 description: successful operation
4256 summary: Block a server
4269 description: server domain to block
4274 description: successful operation
4276 description: self-blocking forbidden
4278 '/server/blocklist/servers/{host}':
4282 summary: Unblock a server by its domain
4290 description: server domain to unblock
4296 description: successful operation
4298 description: account block does not exist
4300 /server/redundancy/{host}:
4303 - Instance Redundancy
4304 summary: Update a server redundancy policy
4312 description: server domain to mirror
4324 description: allow mirroring of the host's local videos
4329 description: successful operation
4331 description: server is not already known
4333 /server/redundancy/videos:
4337 summary: List videos being mirrored
4338 operationId: getMirroredVideos
4346 description: direction of the mirror
4352 - $ref: '#/components/parameters/start'
4353 - $ref: '#/components/parameters/count'
4354 - $ref: '#/components/parameters/videoRedundanciesSort'
4357 description: successful operation
4363 $ref: '#/components/schemas/VideoRedundancy'
4367 summary: Mirror a video
4368 operationId: putMirroredVideo
4379 $ref: '#/components/schemas/Video/properties/id'
4384 description: successful operation
4386 description: cannot mirror a local video
4388 description: video does not exist
4390 description: video is already mirrored
4392 /server/redundancy/videos/{redundancyId}:
4396 summary: Delete a mirror done on a video
4397 operationId: delMirroredVideo
4402 - name: redundancyId
4405 description: id of an existing redundancy on a video
4410 description: successful operation
4412 description: video redundancy not found
4418 summary: Get instance stats
4419 description: Get instance public statistics. This endpoint is cached.
4420 operationId: getInstanceStats
4423 description: successful operation
4427 $ref: '#/components/schemas/ServerStats'
4429 /server/logs/client:
4433 summary: Send client log
4434 operationId: sendClientLog
4439 $ref: '#/components/schemas/SendClientLog'
4442 description: successful operation
4448 summary: Get instance logs
4449 operationId: getInstanceLogs
4455 description: successful operation
4467 summary: Get instance audit logs
4468 operationId: getInstanceAuditLogs
4474 description: successful operation
4482 '/feeds/video-comments.{format}':
4486 summary: List comments on videos
4487 operationId: getSyndicatedComments
4492 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4505 description: 'limit listing to a specific video'
4510 description: 'limit listing to a specific account'
4515 description: 'limit listing to a specific account'
4518 - name: videoChannelId
4520 description: 'limit listing to a specific video channel'
4523 - name: videoChannelName
4525 description: 'limit listing to a specific video channel'
4530 description: successful operation
4535 default: 'max-age=900' # 15 min cache
4539 $ref: '#/components/schemas/VideoCommentsForXML'
4542 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4543 application/rss+xml:
4545 $ref: '#/components/schemas/VideoCommentsForXML'
4548 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4551 $ref: '#/components/schemas/VideoCommentsForXML'
4554 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4555 application/atom+xml:
4557 $ref: '#/components/schemas/VideoCommentsForXML'
4560 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4566 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4568 x-summary: field inconsistencies
4571 - videoId filter is mixed with a channel filter
4573 description: video, video channel or account not found
4575 description: accept header unsupported
4577 '/feeds/videos.{format}':
4581 summary: List videos
4582 operationId: getSyndicatedVideos
4587 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4600 description: 'limit listing to a specific account'
4605 description: 'limit listing to a specific account'
4608 - name: videoChannelId
4610 description: 'limit listing to a specific video channel'
4613 - name: videoChannelName
4615 description: 'limit listing to a specific video channel'
4618 - $ref: '#/components/parameters/sort'
4619 - $ref: '#/components/parameters/nsfw'
4620 - $ref: '#/components/parameters/isLocal'
4621 - $ref: '#/components/parameters/include'
4622 - $ref: '#/components/parameters/privacyOneOf'
4623 - $ref: '#/components/parameters/hasHLSFiles'
4624 - $ref: '#/components/parameters/hasWebtorrentFiles'
4627 description: successful operation
4632 default: 'max-age=900' # 15 min cache
4636 $ref: '#/components/schemas/VideosForXML'
4639 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4640 application/rss+xml:
4642 $ref: '#/components/schemas/VideosForXML'
4645 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4648 $ref: '#/components/schemas/VideosForXML'
4651 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4652 application/atom+xml:
4654 $ref: '#/components/schemas/VideosForXML'
4657 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4663 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4665 description: video channel or account not found
4667 description: accept header unsupported
4669 '/feeds/subscriptions.{format}':
4674 summary: List videos of subscriptions tied to a token
4675 operationId: getSyndicatedSubscriptionVideos
4680 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4693 description: limit listing to a specific account
4699 description: private token allowing access
4703 - $ref: '#/components/parameters/sort'
4704 - $ref: '#/components/parameters/nsfw'
4705 - $ref: '#/components/parameters/isLocal'
4706 - $ref: '#/components/parameters/include'
4707 - $ref: '#/components/parameters/privacyOneOf'
4708 - $ref: '#/components/parameters/hasHLSFiles'
4709 - $ref: '#/components/parameters/hasWebtorrentFiles'
4712 description: successful operation
4717 default: 'max-age=900' # 15 min cache
4721 $ref: '#/components/schemas/VideosForXML'
4722 application/rss+xml:
4724 $ref: '#/components/schemas/VideosForXML'
4727 $ref: '#/components/schemas/VideosForXML'
4728 application/atom+xml:
4730 $ref: '#/components/schemas/VideosForXML'
4735 description: accept header unsupported
4741 summary: List plugins
4742 operationId: getPlugins
4755 - $ref: '#/components/parameters/start'
4756 - $ref: '#/components/parameters/count'
4757 - $ref: '#/components/parameters/sort'
4760 description: successful operation
4764 $ref: '#/components/schemas/PluginResponse'
4770 summary: List available plugins
4771 operationId: getAvailablePlugins
4784 - name: currentPeerTubeEngine
4788 - $ref: '#/components/parameters/start'
4789 - $ref: '#/components/parameters/count'
4790 - $ref: '#/components/parameters/sort'
4793 description: successful operation
4797 $ref: '#/components/schemas/PluginResponse'
4799 description: plugin index unavailable
4805 summary: Install a plugin
4806 operationId: addPlugin
4819 example: peertube-plugin-auth-ldap
4822 additionalProperties: false
4829 additionalProperties: false
4832 description: successful operation
4834 description: should have either `npmName` or `path` set
4840 summary: Update a plugin
4841 operationId: updatePlugin
4854 example: peertube-plugin-auth-ldap
4857 additionalProperties: false
4864 additionalProperties: false
4867 description: successful operation
4869 description: should have either `npmName` or `path` set
4871 description: existing plugin not found
4877 summary: Uninstall a plugin
4878 operationId: uninstallPlugin
4890 description: name of the plugin/theme in its package.json
4891 example: peertube-plugin-auth-ldap
4896 description: successful operation
4898 description: existing plugin not found
4904 summary: Get a plugin
4905 operationId: getPlugin
4910 - $ref: '#/components/parameters/npmName'
4913 description: successful operation
4917 $ref: '#/components/schemas/Plugin'
4919 description: plugin not found
4921 /plugins/{npmName}/settings:
4925 summary: Set a plugin's settings
4930 - $ref: '#/components/parameters/npmName'
4939 additionalProperties: true
4942 description: successful operation
4944 description: plugin not found
4946 /plugins/{npmName}/public-settings:
4950 summary: Get a plugin's public settings
4952 - $ref: '#/components/parameters/npmName'
4955 description: successful operation
4960 additionalProperties: true
4962 description: plugin not found
4964 /plugins/{npmName}/registered-settings:
4968 summary: Get a plugin's registered settings
4973 - $ref: '#/components/parameters/npmName'
4976 description: successful operation
4981 additionalProperties: true
4983 description: plugin not found
4986 - url: 'https://peertube2.cpy.re/api/v1'
4987 description: Live Test Server (live data - latest nightly version)
4988 - url: 'https://peertube3.cpy.re/api/v1'
4989 description: Live Test Server (live data - latest RC version)
4990 - url: 'https://peertube.cpy.re/api/v1'
4991 description: Live Test Server (live data - stable version)
4998 description: Offset used to paginate results
5006 description: "Number of items to return"
5016 description: Sort column
5024 description: Plain text search, applied to various parts of the model depending on endpoint
5032 If the administrator enabled search index support, you can override the default search target.
5035 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
5036 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
5037 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
5038 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
5039 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
5040 * 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
5041 the data from the origin instance API
5064 Sort videos by criteria (prefixing with `-` means `DESC` order):
5065 * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
5066 * `best` - Same than `hot`, but also takes into account user video history
5067 * `trending` - Sort videos by recent views ("recent" is defined by the admin)
5068 * `views` - Sort videos using their `views` counter
5069 * `publishedAt` - Sort by video publication date (when it became publicly available)
5075 Sort videos by criteria (prefixing with `-` means `DESC` order):
5090 description: Sort comments by criteria
5100 description: Sort blocklists by criteria
5116 description: Plain text search that will match with user usernames or emails
5123 description: Filter results down to (un)banned users
5130 description: Sort users by criteria
5141 description: Sort abuses by criteria
5148 videoRedundanciesSort:
5152 description: Sort abuses by criteria
5161 description: Sort followers by criteria
5170 description: The username or handle of the account
5173 example: chocobozzz | chocobozzz@example.org
5178 description: Entity id
5180 $ref: '#/components/schemas/id'
5185 description: The object id, uuid or short uuid
5188 - $ref: '#/components/schemas/id'
5189 - $ref: '#/components/schemas/UUIDv4'
5190 - $ref: '#/components/schemas/shortUUID'
5195 description: Playlist id
5197 $ref: '#/components/schemas/VideoPlaylist/properties/id'
5199 name: playlistElementId
5202 description: Playlist element id
5204 $ref: '#/components/schemas/id'
5209 description: Abuse id
5211 $ref: '#/components/schemas/Abuse/properties/id'
5213 name: abuseMessageId
5216 description: Abuse message id
5218 $ref: '#/components/schemas/AbuseMessage/properties/id'
5220 name: captionLanguage
5223 description: The caption language
5225 $ref: '#/components/schemas/VideoLanguageSet'
5230 description: The video channel handle
5233 example: my_username | my_username@example.com
5238 description: Channel Sync id
5240 $ref: '#/components/schemas/Abuse/properties/id'
5242 name: subscriptionHandle
5245 description: The subscription handle
5248 example: my_username | my_username@example.com
5253 description: The thread id (root comment id)
5260 description: The comment id
5262 $ref: '#/components/schemas/VideoComment/properties/id'
5267 description: whether or not the video is a live
5274 description: category id of the video (see [/videos/categories](#operation/getCategories))
5277 - $ref: '#/components/schemas/VideoCategorySet'
5280 $ref: '#/components/schemas/VideoCategorySet'
5287 description: tag(s) of the video
5301 description: tag(s) of the video, where all should be present in the video
5314 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5317 - $ref: '#/components/schemas/VideoLanguageSet'
5320 $ref: '#/components/schemas/VideoLanguageSet'
5327 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5330 - $ref: '#/components/schemas/VideoLicenceSet'
5333 $ref: '#/components/schemas/VideoLicenceSet'
5340 description: if you don't need the `total` in the response
5351 description: whether to include nsfw videos, if any
5363 description: '**PeerTube >= 4.0** Display only local or remote videos'
5370 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5372 name: hasWebtorrentFiles
5377 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5383 $ref: '#/components/schemas/VideoPrivacySet'
5384 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5398 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5402 - `1` NOT_PUBLISHED_STATE
5413 description: list of uris to check if each is part of the user subscriptions
5423 description: name of the plugin/theme on npmjs.com or in its package.json
5426 example: peertube-plugin-auth-ldap
5431 description: job type
5435 - activitypub-follow
5436 - activitypub-http-broadcast
5437 - activitypub-http-fetcher
5438 - activitypub-http-unicast
5443 - videos-views-stats
5444 - activitypub-refresher
5447 - video-channel-import
5470 Authenticating via OAuth requires the following steps:
5471 - Have an activated account
5472 - [Generate] an access token for that account at `/api/v1/users/token`.
5473 - Make requests with the *Authorization: Bearer <token\>* header
5474 - Profit, depending on the role assigned to the account
5476 Note that the __access token is valid for 1 day__ and is given
5477 along with a __refresh token valid for 2 weeks__.
5479 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5483 tokenUrl: /api/v1/users/token
5486 moderator: Moderator scope
5489 # Reusable core properties
5497 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5498 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5503 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5504 example: 2y84q2MQUMWPbiEcxNXMgC
5507 description: immutable name of the user, used to find or mention its actor
5509 pattern: '/^[a-z0-9._]+$/'
5514 description: immutable name of the channel, used to interact with its actor
5515 example: framasoft_videos
5516 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5527 description: category id of the video (see [/videos/categories](#operation/getCategories))
5529 VideoConstantNumber-Category:
5532 $ref: '#/components/schemas/VideoCategorySet'
5535 example: Science & Technology
5539 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5541 VideoConstantNumber-Licence:
5544 $ref: '#/components/schemas/VideoLicenceSet'
5547 example: Attribution - Share Alike
5551 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5553 VideoConstantString-Language:
5556 $ref: '#/components/schemas/VideoLanguageSet'
5561 VideoPlaylistPrivacySet:
5567 description: Video playlist privacy policy (see [/video-playlists/privacies])
5568 VideoPlaylistPrivacyConstant:
5571 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5575 VideoPlaylistTypeSet:
5580 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5581 VideoPlaylistTypeConstant:
5584 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5595 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5596 VideoPrivacyConstant:
5599 $ref: '#/components/schemas/VideoPrivacySet'
5607 additionalProperties:
5608 x-additionalPropertiesName: account
5617 additionalProperties:
5618 x-additionalPropertiesName: host
5639 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5646 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5649 LiveVideoLatencyMode:
5655 description: 'The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)'
5676 - `4`: Waiting for live stream
5678 - `6`: To move to an external storage (object storage...)
5679 - `7`: Transcoding failed
5680 - `8`: Moving to an external storage failed
5681 - `9`: To edit using studio edition feature
5691 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5695 $ref: '#/components/schemas/AbuseStateSet'
5698 AbusePredefinedReasons:
5711 example: [spamOrMisleading]
5716 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5718 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5720 VideoResolutionConstant:
5721 description: resolutions and their labels for the video
5724 $ref: '#/components/schemas/VideoResolutionSet'
5728 VideoScheduledUpdate:
5731 $ref: '#/components/schemas/VideoPrivacySet'
5735 description: When to update the video
5755 $ref: '#/components/schemas/ActorImage'
5756 VideoChannelSummary:
5759 $ref: '#/components/schemas/id'
5773 $ref: '#/components/schemas/ActorImage'
5787 - $ref: '#/components/schemas/Video'
5792 $ref: '#/components/schemas/id'
5796 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5797 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5799 $ref: '#/components/schemas/VideoResolutionConstant'
5802 description: Video file size in bytes
5805 description: Direct URL of the torrent file
5809 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5813 description: Direct URL of the video
5817 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5821 description: Frames per second of the video file
5825 description: URL dereferencing the output of ffprobe on the file
5826 VideoStreamingPlaylists:
5831 $ref: '#/components/schemas/id'
5839 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5840 VideoStreamingPlaylists-HLS:
5851 Video files associated to this playlist.
5853 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5855 $ref: '#/components/schemas/VideoFile'
5867 $ref: '#/components/schemas/Video/properties/id'
5869 $ref: '#/components/schemas/Video/properties/uuid'
5871 $ref: '#/components/schemas/Video/properties/name'
5875 description: object id for the video
5877 - $ref: '#/components/schemas/id'
5879 description: universal identifier for the video, that can be used across instances
5881 - $ref: '#/components/schemas/UUIDv4'
5884 - $ref: '#/components/schemas/shortUUID'
5890 example: 2017-10-01T10:52:46.396Z
5891 description: time at which the video object was first drafted
5895 example: 2018-10-01T10:52:46.396Z
5896 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5900 example: 2021-05-04T08:01:01.502Z
5901 description: last time the video's metadata was modified
5902 originallyPublishedAt:
5905 example: 2010-10-01T10:52:46.396Z
5906 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5909 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5910 description: category in which the video is classified
5913 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5914 description: licence under which the video is distributed
5917 - $ref: '#/components/schemas/VideoConstantString-Language'
5918 description: main language used in the video
5921 - $ref: '#/components/schemas/VideoPrivacyConstant'
5922 description: privacy policy used to distribute the video
5926 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5927 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5931 truncated description of the video, written in Markdown.
5932 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5937 description: duration of the video in seconds
5942 description: title of the video
5943 example: What is PeerTube?
5948 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5951 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5954 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5971 - $ref: '#/components/schemas/VideoStateConstant'
5972 description: represents the internal state of the video processing within the PeerTube instance
5976 - $ref: '#/components/schemas/VideoScheduledUpdate'
5984 $ref: '#/components/schemas/AccountSummary'
5986 $ref: '#/components/schemas/VideoChannelSummary'
5995 - $ref: '#/components/schemas/Video'
6000 description: If the video is a live, you have the amount of current viewers
6003 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
6004 description: path at which to get the full description of maximum `10000` characters
6007 description: A text tell the audience how to support the video creator
6008 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6012 $ref: '#/components/schemas/VideoChannel'
6014 $ref: '#/components/schemas/Account'
6016 example: [flowers, gardening]
6034 - https://peertube2.cpy.re/tracker/announce
6035 - wss://peertube2.cpy.re/tracker/socket
6039 $ref: '#/components/schemas/VideoFile'
6041 WebTorrent/raw video files. If WebTorrent is disabled on the server:
6043 - field will be empty
6044 - video files will be found in `streamingPlaylists[].files` field
6048 $ref: '#/components/schemas/VideoStreamingPlaylists'
6050 HLS playlists/manifest files. If HLS is disabled on the server:
6052 - field will be empty
6053 - video files will be found in `files` field
6054 FileRedundancyInformation:
6057 $ref: '#/components/schemas/id'
6082 $ref: '#/components/schemas/id'
6089 $ref: '#/components/schemas/UUIDv4'
6096 $ref: '#/components/schemas/FileRedundancyInformation'
6100 $ref: '#/components/schemas/FileRedundancyInformation'
6101 VideoImportStateConstant:
6109 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
6116 additionalProperties: false
6120 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
6121 required: [targetUrl]
6124 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6125 required: [magnetUri]
6128 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
6129 required: [torrentfile]
6130 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6139 - $ref: '#/components/schemas/id'
6143 description: remote URL where to find the import's source video
6144 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
6148 description: magnet URI allowing to resolve the import's source video
6149 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
6154 description: Torrent file containing only the video file
6161 - $ref: '#/components/schemas/VideoImportStateConstant'
6177 - $ref: '#/components/schemas/Video'
6187 $ref: '#/components/schemas/VideoImport'
6191 $ref: '#/components/schemas/id'
6194 example: The video is a spam
6198 $ref: '#/components/schemas/AbusePredefinedReasons'
6200 $ref: '#/components/schemas/Account'
6202 $ref: '#/components/schemas/AbuseStateConstant'
6205 example: Decided to ban the server since it spams us regularly
6209 $ref: '#/components/schemas/VideoInfo'
6216 $ref: '#/components/schemas/id'
6227 $ref: '#/components/schemas/AccountSummary'
6231 $ref: '#/components/schemas/id'
6233 $ref: '#/components/schemas/Video/properties/id'
6245 $ref: '#/components/schemas/UUIDv4'
6263 $ref: '#/components/schemas/id'
6265 $ref: '#/components/schemas/UUIDv4'
6268 - $ref: '#/components/schemas/shortUUID'
6291 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6293 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6295 $ref: '#/components/schemas/AccountSummary'
6297 $ref: '#/components/schemas/VideoChannelSummary'
6301 $ref: '#/components/schemas/id'
6308 description: Text of the comment
6310 example: This video is wonderful!
6312 $ref: '#/components/schemas/id'
6316 - $ref: '#/components/schemas/id'
6318 $ref: '#/components/schemas/Video/properties/id'
6333 totalRepliesFromVideoAuthor:
6340 $ref: '#/components/schemas/Account'
6341 VideoCommentThreadTree:
6344 $ref: '#/components/schemas/VideoComment'
6348 $ref: '#/components/schemas/VideoCommentThreadTree'
6352 $ref: '#/components/schemas/VideoConstantString-Language'
6374 $ref: '#/components/schemas/id'
6385 $ref: '#/components/schemas/ActorImage'
6389 $ref: '#/components/schemas/id'
6394 description: immutable name of the actor, used to find or mention it
6396 - $ref: '#/components/schemas/username'
6400 description: server on which the actor is resident
6401 hostRedundancyAllowed:
6403 description: whether this actor's host allows redundancy of its videos
6407 description: number of actors subscribed to by this actor, as seen by this instance
6411 description: number of followers of this actor, as seen by this instance
6420 - $ref: '#/components/schemas/Actor'
6423 description: object id for the user tied to this account
6425 - $ref: '#/components/schemas/User/properties/id'
6428 description: editable name of the account, displayed in its representations
6433 description: text or bio displayed on the account's profile
6441 description: timestamp within the video, in seconds
6448 Event since last viewing call:
6449 * `seek` - If the user seeked the video
6472 VideoStatsRetention:
6484 VideoStatsTimeserie:
6561 allowedForCurrentIP:
6563 requiresEmailVerification:
6581 $ref: '#/components/schemas/VideoResolutionSet'
6598 videoChannelSynchronization:
6671 example: 16810141515
6712 description: URL of the current user page
6719 description: Stack trace of the error if there is one
6722 description: User agent of the web browser that sends the message
6725 description: Additional information regarding this log
6735 totalDailyActiveUsers:
6737 totalWeeklyActiveUsers:
6739 totalMonthlyActiveUsers:
6743 totalLocalVideoViews:
6745 description: Total video views made on the instance
6746 totalLocalVideoComments:
6748 description: Total comments made by local users
6749 totalLocalVideoFilesSize:
6755 totalLocalVideoChannels:
6757 totalLocalDailyActiveVideoChannels:
6759 totalLocalWeeklyActiveVideoChannels:
6761 totalLocalMonthlyActiveVideoChannels:
6763 totalLocalPlaylists:
6765 totalInstanceFollowers:
6767 totalInstanceFollowing:
6784 totalActivityPubMessagesProcessed:
6786 totalActivityPubMessagesSuccesses:
6788 totalActivityPubMessagesErrors:
6791 activityPubMessagesProcessedPerSecond:
6793 totalActivityPubMessagesWaiting:
6870 requiresEmailVerification:
6885 description: Settings that apply to new users, if registration is enabled
6889 example: 16810141515
6895 description: Settings pertaining to transcoding jobs
6899 allowAdditionalExtensions:
6901 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6904 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6907 description: Amount of threads used by ffmpeg for 1 transcoding job
6910 description: Amount of transcoding jobs to execute in parallel
6916 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6919 description: Resolutions to transcode _new videos_ to
6941 description: WebTorrent-specific settings
6947 description: HLS-specific settings
6967 video_channel_synchronization:
7002 $ref: '#/components/schemas/id'
7004 $ref: '#/components/schemas/Actor'
7006 $ref: '#/components/schemas/Actor'
7009 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
7022 PredefinedAbuseReasons:
7023 description: Reason categories that help triage reports
7041 $ref: '#/components/schemas/id'
7053 - activitypub-http-unicast
7054 - activitypub-http-broadcast
7055 - activitypub-http-fetcher
7056 - activitypub-follow
7061 - videos-views-stats
7062 - activitypub-refresher
7064 - video-channel-import
7067 additionalProperties: true
7070 additionalProperties: true
7086 $ref: '#/components/schemas/id'
7091 $ref: '#/components/schemas/id'
7092 VideoUploadRequestCommon:
7095 description: Video name
7097 example: What is PeerTube?
7101 description: Channel id that will contain this video
7106 $ref: '#/components/schemas/VideoPrivacySet'
7108 $ref: '#/components/schemas/VideoCategorySet'
7110 $ref: '#/components/schemas/VideoLicenceSet'
7112 $ref: '#/components/schemas/VideoLanguageSet'
7114 description: Video description
7117 **[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)**
7119 description: Whether or not we wait transcoding before publish the video
7122 description: A text tell the audience how to support the video creator
7123 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7126 description: Whether or not this video contains sensitive content
7129 description: Video tags (maximum 5 tags each between 2 and 30 characters)
7142 description: Enable or disable comments for this video
7145 description: Enable or disable downloading for this video
7147 originallyPublishedAt:
7148 description: Date when the content was originally published
7152 $ref: '#/components/schemas/VideoScheduledUpdate'
7154 description: Video thumbnail file
7158 description: Video preview file
7164 VideoUploadRequestLegacy:
7166 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7172 description: Video file
7175 VideoUploadRequestResumable:
7177 - $ref: '#/components/schemas/VideoUploadRequestCommon'
7183 description: Video filename including extension
7186 example: what_is_peertube.mp4
7188 description: Video thumbnail file
7192 description: Video preview file
7195 VideoUploadResponse:
7201 $ref: '#/components/schemas/Video/properties/id'
7203 $ref: '#/components/schemas/Video/properties/uuid'
7205 $ref: '#/components/schemas/Video/properties/shortUUID'
7206 CommentThreadResponse:
7215 $ref: '#/components/schemas/VideoComment'
7216 CommentThreadPostResponse:
7219 $ref: '#/components/schemas/VideoComment'
7229 $ref: '#/components/schemas/Video'
7233 $ref: '#/components/schemas/Account'
7236 description: Automatically start playing the upcoming video after the currently playing video
7237 autoPlayNextVideoPlaylist:
7239 description: Automatically start playing the video on the playlist after the currently playing video
7242 description: Automatically start playing the video on the watch page
7252 description: The user email
7255 description: Has the user confirmed their email address?
7258 - $ref: '#/components/schemas/id'
7262 description: Auth plugin to use to authenticate the user
7266 noInstanceConfigWarningModal:
7268 noAccountSetupWarningModal:
7273 $ref: '#/components/schemas/NSFWPolicy'
7275 $ref: '#/components/schemas/UserRole'
7284 description: Theme enabled by this user
7286 $ref: '#/components/schemas/username'
7290 $ref: '#/components/schemas/VideoChannel'
7293 description: The user video quota in bytes
7297 description: The user daily video quota in bytes
7301 description: Enable P2P in the player
7304 - $ref: '#/components/schemas/User'
7306 # optionally present fields: they require WITH_STATS scope
7309 description: Count of videos published
7312 description: Count of reports/abuses of which the user is a target
7313 abusesAcceptedCount:
7315 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
7318 description: Count of reports/abuses created by the user
7321 description: Count of comments published
7325 $ref: '#/components/schemas/username'
7327 $ref: '#/components/schemas/password'
7331 description: The user email
7334 description: The user video quota in bytes
7338 description: The user daily video quota in bytes
7341 $ref: '#/components/schemas/usernameChannel'
7343 $ref: '#/components/schemas/UserRole'
7345 $ref: '#/components/schemas/UserAdminFlags'
7356 description: The updated email of the user
7358 - $ref: '#/components/schemas/User/properties/email'
7361 description: Set the email as verified
7364 description: The updated video quota of the user in bytes
7367 description: The updated daily video quota of the user in bytes
7371 description: The auth plugin to use to authenticate the user
7372 example: 'peertube-plugin-auth-saml2'
7374 $ref: '#/components/schemas/UserRole'
7376 $ref: '#/components/schemas/UserAdminFlags'
7378 $ref: '#/components/schemas/password'
7380 # see shared/models/users/user-update-me.model.ts:
7383 $ref: '#/components/schemas/password'
7385 $ref: '#/components/schemas/password'
7387 description: new email used for login and service communications
7389 - $ref: '#/components/schemas/User/properties/email'
7392 description: new name of the user in its representations
7397 description: new NSFW display policy
7404 description: whether to enable P2P in the player or not
7407 description: new preference regarding playing videos automatically
7410 description: new preference regarding playing following videos automatically
7411 autoPlayNextVideoPlaylist:
7413 description: new preference regarding playing following playlist videos automatically
7414 videosHistoryEnabled:
7416 description: whether to keep track of watched history or not
7421 description: list of languages to filter videos down to
7424 noInstanceConfigWarningModal:
7426 noAccountSetupWarningModal:
7433 $ref: '#/components/schemas/id'
7440 description: Rating of the video
7447 $ref: '#/components/schemas/Video'
7454 description: Rating of the video
7461 description: immutable name of the user, used to find or mention its actor
7463 - $ref: '#/components/schemas/username'
7465 $ref: '#/components/schemas/password'
7469 description: email of the user, used for login or service communications
7472 description: editable name of the user, displayed in its representations
7477 description: channel base information used to create the first channel of the user
7480 $ref: '#/components/schemas/usernameChannel'
7492 pattern: /^[a-z0-9]$/
7495 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7498 pattern: /^[a-zA-Z0-9]$/
7501 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7502 OAuthToken-password:
7504 - $ref: '#/components/schemas/OAuthClient'
7514 $ref: '#/components/schemas/User/properties/username'
7516 $ref: '#/components/schemas/password'
7523 OAuthToken-refresh_token:
7525 - $ref: '#/components/schemas/OAuthClient'
7536 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7545 - $ref: '#/components/schemas/Actor'
7550 description: editable name of the channel, displayed in its representations
7551 example: Videos of Framasoft
7556 example: Videos made with <3 by Framasoft
7561 description: text shown by default on all videos of this channel, to tell the audience how to support it
7562 example: Please support our work on https://soutenir.framasoft.org/en/ <3
7575 $ref: '#/components/schemas/ActorImage'
7584 $ref: '#/components/schemas/UUIDv4'
7588 - $ref: '#/components/schemas/VideoChannel'
7591 description: username of the channel to create
7593 - $ref: '#/components/schemas/usernameChannel'
7599 - $ref: '#/components/schemas/VideoChannel'
7601 bulkVideosSupportUpdate:
7603 description: Update the support field for all videos of this channel
7613 - $ref: '#/components/schemas/VideoChannel'
7614 - $ref: '#/components/schemas/Actor'
7620 $ref: '#/components/schemas/id'
7632 example: 'https://youtube.com/c/UC_myfancychannel'
7641 $ref: '#/components/schemas/VideoChannel'
7642 VideoChannelSyncList:
7652 - $ref: '#/components/schemas/VideoChannelSync'
7653 VideoChannelSyncCreate:
7658 example: https://youtube.com/c/UC_myfancychannel
7660 $ref: '#/components/schemas/id'
7664 name: 'media:peerLink'
7673 - application/x-bittorrent
7679 name: 'media:content'
7710 VideoCommentsForXML:
7745 description: video watch page URL
7748 description: video canonical URL
7752 description: video publication date
7755 description: video description
7758 description: video description
7761 description: publisher user name
7764 description: video category (MRSS)
7767 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7782 description: video embed path, relative to the canonical URL domain (MRSS)
7791 description: video watch path, relative to the canonical URL domain (MRSS)
7812 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7813 'media:description':
7820 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7823 description: main streamable file for the video
7833 - application/x-bittorrent
7842 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)
7845 - $ref: '#/components/schemas/MRSSPeerLink'
7846 - $ref: '#/components/schemas/MRSSGroupContent'
7847 NotificationSettingValue:
7864 $ref: '#/components/schemas/id'
7868 Notification type, following the `UserNotificationType` enum:
7870 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7872 - `2` NEW_COMMENT_ON_MY_VIDEO
7874 - `3` NEW_ABUSE_FOR_MODERATORS
7876 - `4` BLACKLIST_ON_MY_VIDEO
7878 - `5` UNBLACKLIST_ON_MY_VIDEO
7880 - `6` MY_VIDEO_PUBLISHED
7882 - `7` MY_VIDEO_IMPORT_SUCCESS
7884 - `8` MY_VIDEO_IMPORT_ERROR
7886 - `9` NEW_USER_REGISTRATION
7890 - `11` COMMENT_MENTION
7892 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7894 - `13` NEW_INSTANCE_FOLLOWER
7896 - `14` AUTO_INSTANCE_FOLLOWING
7898 - `15` ABUSE_STATE_CHANGE
7900 - `16` ABUSE_NEW_MESSAGE
7902 - `17` NEW_PLUGIN_VERSION
7904 - `18` NEW_PEERTUBE_VERSION
7910 - $ref: '#/components/schemas/VideoInfo'
7914 $ref: '#/components/schemas/ActorInfo'
7920 $ref: '#/components/schemas/id'
7923 $ref: '#/components/schemas/VideoInfo'
7928 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7938 $ref: '#/components/schemas/id'
7942 $ref: '#/components/schemas/VideoInfo'
7944 $ref: '#/components/schemas/ActorInfo'
7950 $ref: '#/components/schemas/id'
7953 - $ref: '#/components/schemas/VideoInfo'
7959 $ref: '#/components/schemas/id'
7962 - $ref: '#/components/schemas/VideoInfo'
7966 - $ref: '#/components/schemas/ActorInfo'
7972 $ref: '#/components/schemas/id'
7974 $ref: '#/components/schemas/ActorInfo'
8002 NotificationListResponse:
8011 $ref: '#/components/schemas/Notification'
8016 example: peertube-plugin-auth-ldap
8044 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
8047 additionalProperties: true
8063 $ref: '#/components/schemas/Plugin'
8070 description: User can stream multiple times in a permanent live
8073 description: User can select live latency mode if enabled by the instance
8074 $ref: '#/components/schemas/LiveVideoLatencyMode'
8080 description: Included in the response if an appropriate token is provided
8083 description: Included in the response if an appropriate token is provided
8086 description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
8090 description: User can stream multiple times in a permanent live
8093 description: User can select live latency mode if enabled by the instance
8094 $ref: '#/components/schemas/LiveVideoLatencyMode'
8096 VideoStudioCreateTask:
8144 title: add-watermark
8158 LiveVideoSessionResponse:
8165 description: Start date of the live session
8170 description: End date of the live session
8181 Error type if an error occurred during the live session:
8182 - `1`: Bad socket health (transcoding is too slow)
8183 - `2`: Max duration exceeded
8184 - `3`: Quota exceeded
8185 - `4`: Quota FFmpeg error
8186 - `5`: Video has been blacklisted during the live
8189 description: Video replay information
8194 $ref: '#/components/schemas/UUIDv4'
8196 $ref: '#/components/schemas/shortUUID'
8200 'https://search.example.org/api/v1/search/videos':
8202 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
8205 description: successful operation
8209 $ref: '#/components/schemas/VideoListResponse'