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 ressource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource 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 Captions
256 description: Operations dealing with listing, adding and removing closed captions of a video.
257 - name: Video Channels
258 description: Operations dealing with the creation, modification and listing of videos within a channel.
259 - name: Video Comments
261 Operations dealing with comments to a video. Comments are organized in threads: adding a
262 comment in response to the video starts a thread, adding a reply to a comment adds it to
263 its root comment thread.
265 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
267 description: Like/dislike a video.
268 - name: Video Playlists
269 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
271 description: Server syndication feeds
274 The search helps to find _videos_ or _channels_ from within the instance and beyond.
275 Videos from other instances federated by the instance (that is, instances
276 followed by the instance) can be found via keywords and other criteria of
279 Administrators can also enable the use of a remote search system, indexing
280 videos and channels not could be not federated by the instance.
282 description: Get and update the custom homepage
283 - name: Video Mirroring
285 PeerTube instances can mirror videos from one another, and help distribute some videos.
287 For importing videos as your own, refer to [video imports](#operation/importVideo).
310 - Video Ownership Change
326 - name: Instance Configuration
330 - Instance Redundancy
340 summary: Get an account
341 operationId: getAccount
343 - $ref: '#/components/parameters/name'
346 description: successful operation
350 $ref: '#/components/schemas/Account'
352 description: account not found
354 '/accounts/{name}/videos':
359 summary: 'List videos of an account'
360 operationId: getAccountVideos
362 - $ref: '#/components/parameters/name'
363 - $ref: '#/components/parameters/categoryOneOf'
364 - $ref: '#/components/parameters/isLive'
365 - $ref: '#/components/parameters/tagsOneOf'
366 - $ref: '#/components/parameters/tagsAllOf'
367 - $ref: '#/components/parameters/licenceOneOf'
368 - $ref: '#/components/parameters/languageOneOf'
369 - $ref: '#/components/parameters/nsfw'
370 - $ref: '#/components/parameters/isLocal'
371 - $ref: '#/components/parameters/include'
372 - $ref: '#/components/parameters/skipCount'
373 - $ref: '#/components/parameters/start'
374 - $ref: '#/components/parameters/count'
375 - $ref: '#/components/parameters/videosSort'
378 description: successful operation
382 $ref: '#/components/schemas/VideoListResponse'
386 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
387 .then(function(response) {
388 return response.json()
389 }).then(function(data) {
395 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
401 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
403 http = Net::HTTP.new(uri.host, uri.port)
406 response = http.get(uri.request_uri)
408 puts JSON.parse(response.read_body)
413 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
418 '/accounts/{name}/followers':
422 summary: 'List followers of an account'
425 operationId: getAccountFollowers
427 - $ref: '#/components/parameters/name'
428 - $ref: '#/components/parameters/start'
429 - $ref: '#/components/parameters/count'
430 - $ref: '#/components/parameters/followersSort'
431 - $ref: '#/components/parameters/search'
434 description: successful operation
446 $ref: '#/components/schemas/Follow'
452 summary: List accounts
453 operationId: getAccounts
455 - $ref: '#/components/parameters/start'
456 - $ref: '#/components/parameters/count'
457 - $ref: '#/components/parameters/sort'
460 description: successful operation
466 $ref: '#/components/schemas/Account'
472 summary: Get instance public configuration
473 operationId: getConfig
476 description: successful operation
480 $ref: '#/components/schemas/ServerConfig'
483 externalValue: https://peertube2.cpy.re/api/v1/config
487 summary: Get instance "About" information
488 operationId: getAbout
493 description: successful operation
497 $ref: '#/components/schemas/ServerConfigAbout'
500 externalValue: https://peertube2.cpy.re/api/v1/config/about
504 summary: Get instance runtime configuration
505 operationId: getCustomConfig
513 description: successful operation
517 $ref: '#/components/schemas/ServerConfigCustom'
519 summary: Set instance runtime configuration
520 operationId: putCustomConfig
528 description: successful operation
530 x-summary: field inconsistencies
533 - the emailer is disabled and the instance is open to registrations
534 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
536 summary: Delete instance runtime configuration
537 operationId: delCustomConfig
545 description: successful operation
547 /custom-pages/homepage/instance:
549 summary: Get instance custom homepage
554 description: No homepage set
556 description: successful operation
560 $ref: '#/components/schemas/CustomHomepage'
562 summary: Set instance custom homepage
576 description: content of the homepage, that will be injected in the client
579 description: successful operation
583 summary: List instance jobs
594 description: The state of the job ('' for for no filter)
604 - $ref: '#/components/parameters/jobType'
605 - $ref: '#/components/parameters/start'
606 - $ref: '#/components/parameters/count'
607 - $ref: '#/components/parameters/sort'
610 description: successful operation
623 $ref: '#/components/schemas/Job'
629 summary: List instances following the server
631 - $ref: '#/components/parameters/followState'
632 - $ref: '#/components/parameters/actorType'
633 - $ref: '#/components/parameters/start'
634 - $ref: '#/components/parameters/count'
635 - $ref: '#/components/parameters/sort'
638 description: successful operation
650 $ref: '#/components/schemas/Follow'
652 '/server/followers/{nameWithHost}':
654 summary: Remove or reject a follower to your server
664 description: The remote actor handle to remove from your followers
670 description: successful operation
672 description: follower not found
674 '/server/followers/{nameWithHost}/reject':
676 summary: Reject a pending follower to your server
686 description: The remote actor handle to remove from your followers
692 description: successful operation
694 description: follower not found
696 '/server/followers/{nameWithHost}/accept':
698 summary: Accept a pending follower to your server
708 description: The remote actor handle to remove from your followers
714 description: successful operation
716 description: follower not found
722 summary: List instances followed by the server
724 - $ref: '#/components/parameters/followState'
725 - $ref: '#/components/parameters/actorType'
726 - $ref: '#/components/parameters/start'
727 - $ref: '#/components/parameters/count'
728 - $ref: '#/components/parameters/sort'
731 description: successful operation
743 $ref: '#/components/schemas/Follow'
750 summary: Follow a list of actors (PeerTube instance, channel or account)
753 description: successful operation
755 description: cannot follow a non-HTTPS server
774 '/server/following/{hostOrHandle}':
776 summary: Unfollow an actor (PeerTube instance, channel or account)
786 description: The hostOrHandle to unfollow
791 description: successful operation
793 description: host or handle not found
797 summary: Create a user
806 description: user created
810 $ref: '#/components/schemas/AddUserResponse'
816 id: '$response.body#/user/id'
821 id: '$response.body#/user/id'
826 id: '$response.body#/user/id'
828 description: insufficient authority to create an admin or moderator
833 $ref: '#/components/schemas/AddUser'
835 If the smtp server is configured, you can leave the password empty and an email will be sent
836 asking the user to set it first.
840 operationId: getUsers
847 - $ref: '#/components/parameters/usersSearch'
848 - $ref: '#/components/parameters/usersBlocked'
849 - $ref: '#/components/parameters/start'
850 - $ref: '#/components/parameters/count'
851 - $ref: '#/components/parameters/usersSort'
854 description: successful operation
860 $ref: '#/components/schemas/User'
864 - $ref: '#/components/parameters/id'
866 summary: Delete a user
875 description: successful operation
886 description: include statistics about the user (only available as a moderator/admin)
891 x-summary: successful operation
893 As an admin/moderator, you can request a response augmented with statistics about the user's
894 moderation relations and videos usage, by using the `withStats` parameter.
899 - $ref: '#/components/schemas/User'
900 - $ref: '#/components/schemas/UserWithStats'
902 summary: Update a user
910 description: successful operation
915 $ref: '#/components/schemas/UpdateUser'
918 /oauth-clients/local:
920 summary: Login prerequisite
921 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
922 operationId: getOAuthClient
927 description: successful operation
931 $ref: '#/components/schemas/OAuthClient'
933 UseOAuthClientToLogin:
934 operationId: getOAuthToken
936 client_id: '$response.body#/client_id'
937 client_secret: '$response.body#/client_secret'
941 API="https://peertube2.cpy.re/api/v1"
944 curl -s "$API/oauth-clients/local"
949 operationId: getOAuthToken
950 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
955 application/x-www-form-urlencoded:
958 - $ref: '#/components/schemas/OAuthToken-password'
959 - $ref: '#/components/schemas/OAuthToken-refresh_token'
961 propertyName: grant_type
963 password: '#/components/schemas/OAuthToken-password'
964 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
967 description: successful operation
978 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
979 description: valid for 1 day
982 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
983 description: valid for 2 weeks
988 refresh_token_expires_in:
993 x-summary: client or credentials are invalid
995 Disambiguate via `type`:
996 - `invalid_client` for an unmatched `client_id`
997 - `invalid_grant` for unmatched credentials
999 x-summary: token expired
1001 Disambiguate via `type`:
1002 - default value for a regular authentication failure
1003 - `invalid_token` for an expired token
1008 API="https://peertube2.cpy.re/api/v1"
1009 USERNAME="<your_username>"
1010 PASSWORD="<your_password>"
1013 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1014 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1015 curl -s "$API/users/token" \
1016 --data client_id="$client_id" \
1017 --data client_secret="$client_secret" \
1018 --data grant_type=password \
1019 --data username="$USERNAME" \
1020 --data password="$PASSWORD" \
1021 | jq -r ".access_token"
1023 /users/revoke-token:
1026 description: Revokes your access token and its associated refresh token, destroying your current session.
1027 operationId: revokeOAuthToken
1034 description: successful operation
1038 summary: Register a user
1039 operationId: registerUser
1045 description: successful operation
1050 $ref: '#/components/schemas/RegisterUser'
1053 /users/{id}/verify-email:
1055 summary: Verify a user
1056 operationId: verifyUser
1058 Following a user registration, the new user will receive an email asking to click a link
1059 containing a secret.
1064 - $ref: '#/components/parameters/id'
1077 - verificationString
1080 description: successful operation
1082 description: invalid verification string
1084 description: user not found
1086 /users/ask-send-verify-email:
1088 summary: Resend user verification link
1089 operationId: resendEmailToVerifyUser
1095 description: successful operation
1099 summary: Get my user information
1100 operationId: getUserInfo
1108 description: successful operation
1114 $ref: '#/components/schemas/User'
1116 summary: Update my user information
1117 operationId: putUserInfo
1125 description: successful operation
1130 $ref: '#/components/schemas/UpdateMe'
1133 /users/me/videos/imports:
1135 summary: Get video imports of my user
1143 - $ref: '#/components/parameters/start'
1144 - $ref: '#/components/parameters/count'
1145 - $ref: '#/components/parameters/sort'
1148 description: successful operation
1152 $ref: '#/components/schemas/VideoImportsList'
1154 /users/me/video-quota-used:
1156 summary: Get my user used quota
1164 description: successful operation
1172 description: The user video quota used so far in bytes
1173 example: 16810141515
1174 videoQuotaUsedDaily:
1176 description: The user video quota used today in bytes
1179 '/users/me/videos/{videoId}/rating':
1181 summary: Get rate of my user for a video
1191 description: The video id
1193 $ref: '#/components/schemas/Video/properties/id'
1196 description: successful operation
1200 $ref: '#/components/schemas/GetMeVideoRating'
1204 summary: Get videos of my user
1212 - $ref: '#/components/parameters/start'
1213 - $ref: '#/components/parameters/count'
1214 - $ref: '#/components/parameters/sort'
1217 description: successful operation
1221 $ref: '#/components/schemas/VideoListResponse'
1223 /users/me/subscriptions:
1225 summary: Get my user subscriptions
1232 - $ref: '#/components/parameters/start'
1233 - $ref: '#/components/parameters/count'
1234 - $ref: '#/components/parameters/sort'
1237 description: successful operation
1241 $ref: '#/components/schemas/VideoChannelList'
1245 summary: Add subscription to my user
1258 description: uri of the video channels to subscribe to
1264 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1267 description: successful operation
1269 /users/me/subscriptions/exist:
1271 summary: Get if subscriptions exist for my user
1278 - $ref: '#/components/parameters/subscriptionsUris'
1281 description: successful operation
1287 /users/me/subscriptions/videos:
1289 summary: List videos of subscriptions of my user
1297 - $ref: '#/components/parameters/categoryOneOf'
1298 - $ref: '#/components/parameters/isLive'
1299 - $ref: '#/components/parameters/tagsOneOf'
1300 - $ref: '#/components/parameters/tagsAllOf'
1301 - $ref: '#/components/parameters/licenceOneOf'
1302 - $ref: '#/components/parameters/languageOneOf'
1303 - $ref: '#/components/parameters/nsfw'
1304 - $ref: '#/components/parameters/isLocal'
1305 - $ref: '#/components/parameters/include'
1306 - $ref: '#/components/parameters/skipCount'
1307 - $ref: '#/components/parameters/start'
1308 - $ref: '#/components/parameters/count'
1309 - $ref: '#/components/parameters/videosSort'
1312 description: successful operation
1316 $ref: '#/components/schemas/VideoListResponse'
1318 '/users/me/subscriptions/{subscriptionHandle}':
1320 summary: Get subscription of my user
1327 - $ref: '#/components/parameters/subscriptionHandle'
1330 description: successful operation
1334 $ref: '#/components/schemas/VideoChannel'
1336 summary: Delete subscription of my user
1343 - $ref: '#/components/parameters/subscriptionHandle'
1346 description: successful operation
1348 /users/me/notifications:
1350 summary: List my notifications
1358 description: only list unread notifications
1361 - $ref: '#/components/parameters/start'
1362 - $ref: '#/components/parameters/count'
1363 - $ref: '#/components/parameters/sort'
1366 description: successful operation
1370 $ref: '#/components/schemas/NotificationListResponse'
1372 /users/me/notifications/read:
1374 summary: Mark notifications as read by their id
1387 description: ids of the notifications to mark as read
1394 description: successful operation
1396 /users/me/notifications/read-all:
1398 summary: Mark all my notification as read
1405 description: successful operation
1407 /users/me/notification-settings:
1409 summary: Update my notification settings
1420 newVideoFromSubscription:
1421 $ref: '#/components/schemas/NotificationSettingValue'
1422 newCommentOnMyVideo:
1423 $ref: '#/components/schemas/NotificationSettingValue'
1425 $ref: '#/components/schemas/NotificationSettingValue'
1426 videoAutoBlacklistAsModerator:
1427 $ref: '#/components/schemas/NotificationSettingValue'
1429 $ref: '#/components/schemas/NotificationSettingValue'
1431 $ref: '#/components/schemas/NotificationSettingValue'
1432 myVideoImportFinished:
1433 $ref: '#/components/schemas/NotificationSettingValue'
1435 $ref: '#/components/schemas/NotificationSettingValue'
1436 newUserRegistration:
1437 $ref: '#/components/schemas/NotificationSettingValue'
1439 $ref: '#/components/schemas/NotificationSettingValue'
1440 newInstanceFollower:
1441 $ref: '#/components/schemas/NotificationSettingValue'
1442 autoInstanceFollowing:
1443 $ref: '#/components/schemas/NotificationSettingValue'
1446 description: successful operation
1448 /users/me/history/videos:
1450 summary: List watched videos history
1456 - $ref: '#/components/parameters/start'
1457 - $ref: '#/components/parameters/count'
1458 - $ref: '#/components/parameters/search'
1461 description: successful operation
1465 $ref: '#/components/schemas/VideoListResponse'
1467 /users/me/history/videos/remove:
1469 summary: Clear video history
1476 multipart/form-data:
1481 description: history before this date will be deleted
1486 description: successful operation
1488 /users/me/avatar/pick:
1490 summary: Update my user avatar
1497 description: successful operation
1504 $ref: '#/components/schemas/ActorImage'
1506 description: image file too large
1508 X-File-Maximum-Size:
1512 description: Maximum file size for the avatar
1515 multipart/form-data:
1520 description: The file to upload
1525 contentType: image/png, image/jpeg
1529 summary: Delete my avatar
1536 description: successful operation
1540 summary: List video ownership changes
1542 - Video Ownership Change
1547 description: successful operation
1549 '/videos/ownership/{id}/accept':
1551 summary: Accept ownership change request
1553 - Video Ownership Change
1557 - $ref: '#/components/parameters/idOrUUID'
1560 description: successful operation
1562 description: cannot terminate an ownership change of another user
1564 description: video owneship change not found
1566 '/videos/ownership/{id}/refuse':
1568 summary: Refuse ownership change request
1570 - Video Ownership Change
1574 - $ref: '#/components/parameters/idOrUUID'
1577 description: successful operation
1579 description: cannot terminate an ownership change of another user
1581 description: video owneship change not found
1583 '/videos/{id}/give-ownership':
1585 summary: Request ownership change
1587 - Video Ownership Change
1591 - $ref: '#/components/parameters/idOrUUID'
1595 application/x-www-form-urlencoded:
1605 description: successful operation
1607 description: changing video ownership to a remote account is not supported yet
1609 description: video not found
1613 summary: List videos
1614 operationId: getVideos
1618 - $ref: '#/components/parameters/categoryOneOf'
1619 - $ref: '#/components/parameters/isLive'
1620 - $ref: '#/components/parameters/tagsOneOf'
1621 - $ref: '#/components/parameters/tagsAllOf'
1622 - $ref: '#/components/parameters/licenceOneOf'
1623 - $ref: '#/components/parameters/languageOneOf'
1624 - $ref: '#/components/parameters/nsfw'
1625 - $ref: '#/components/parameters/isLocal'
1626 - $ref: '#/components/parameters/include'
1627 - $ref: '#/components/parameters/skipCount'
1628 - $ref: '#/components/parameters/start'
1629 - $ref: '#/components/parameters/count'
1630 - $ref: '#/components/parameters/videosSort'
1633 description: successful operation
1637 $ref: '#/components/schemas/VideoListResponse'
1641 summary: List available video categories
1642 operationId: getCategories
1647 description: successful operation
1656 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1660 summary: List available video licences
1661 operationId: getLicences
1666 description: successful operation
1675 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1679 summary: List available video languages
1680 operationId: getLanguages
1685 description: successful operation
1694 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1698 summary: List available video privacy policies
1699 operationId: getPrivacyPolicies
1704 description: successful operation
1713 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1717 summary: Update a video
1718 operationId: putVideo
1724 - $ref: '#/components/parameters/idOrUUID'
1727 description: successful operation
1730 multipart/form-data:
1735 description: Video thumbnail file
1739 description: Video preview file
1743 $ref: '#/components/schemas/VideoCategorySet'
1745 $ref: '#/components/schemas/VideoLicenceSet'
1747 $ref: '#/components/schemas/VideoLanguageSet'
1749 $ref: '#/components/schemas/VideoPrivacySet'
1751 description: Video description
1754 description: Whether or not we wait transcoding before publish the video
1757 description: A text tell the audience how to support the video creator
1758 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1761 description: Whether or not this video contains sensitive content
1764 description: Video name
1769 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1778 description: Enable or disable comments for this video
1781 description: Enable or disable downloading for this video
1783 originallyPublishedAt:
1784 description: Date when the content was originally published
1788 $ref: '#/components/schemas/VideoScheduledUpdate'
1791 contentType: image/jpeg
1793 contentType: image/jpeg
1795 summary: Get a video
1796 operationId: getVideo
1800 - $ref: '#/components/parameters/idOrUUID'
1803 description: successful operation
1807 $ref: '#/components/schemas/VideoDetails'
1809 summary: Delete a video
1810 operationId: delVideo
1816 - $ref: '#/components/parameters/idOrUUID'
1819 description: successful operation
1821 '/videos/{id}/description':
1823 summary: Get complete video description
1824 operationId: getVideoDesc
1828 - $ref: '#/components/parameters/idOrUUID'
1831 description: successful operation
1840 **[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)**
1842 '/videos/{id}/views':
1844 summary: Add a view to a video
1845 operationId: addView
1849 - $ref: '#/components/parameters/idOrUUID'
1852 description: successful operation
1854 '/videos/{id}/watching':
1856 summary: Set watching progress of a video
1857 operationId: setProgress
1863 - $ref: '#/components/parameters/idOrUUID'
1868 $ref: '#/components/schemas/UserWatchingVideo'
1872 description: successful operation
1876 summary: Upload a video
1877 description: Uses a single request to upload a video.
1878 operationId: uploadLegacy
1886 description: successful operation
1890 $ref: '#/components/schemas/VideoUploadResponse'
1892 description: video didn't pass upload filter
1894 description: upload has timed out
1896 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1898 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1899 - `quota_reached` for quota limits wether daily or global
1901 X-File-Maximum-Size:
1905 description: Maximum file size for the video
1907 description: video type unsupported
1909 description: video unreadable
1912 multipart/form-data:
1914 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1917 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1919 contentType: image/jpeg
1921 contentType: image/jpeg
1926 USERNAME="<your_username>"
1927 PASSWORD="<your_password>"
1928 FILE_PATH="<your_file_path>"
1929 CHANNEL_ID="<your_channel_id>"
1931 API="https://peertube2.cpy.re/api/v1"
1934 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1935 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1936 token=$(curl -s "$API/users/token" \
1937 --data client_id="$client_id" \
1938 --data client_secret="$client_secret" \
1939 --data grant_type=password \
1940 --data username="$USERNAME" \
1941 --data password="$PASSWORD" \
1942 | jq -r ".access_token")
1945 curl -s "$API/videos/upload" \
1946 -H "Authorization: Bearer $token" \
1948 --form videofile=@"$FILE_PATH" \
1949 --form channelId=$CHANNEL_ID \
1952 /videos/upload-resumable:
1954 summary: Initialize the resumable upload of a video
1955 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1956 operationId: uploadResumableInit
1963 - name: X-Upload-Content-Length
1969 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1970 - name: X-Upload-Content-Type
1977 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1982 $ref: '#/components/schemas/VideoUploadRequestResumable'
1985 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1987 description: created
1993 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1999 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2001 Disambiguate via `type`:
2002 - `max_file_size_reached` for the absolute file size limit
2003 - `quota_reached` for quota limits whether daily or global
2005 description: video type unsupported
2007 summary: Send chunk for the resumable upload of a video
2008 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
2009 operationId: uploadResumable
2020 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2021 not valid anymore and you need to initialize a new upload.
2024 - name: Content-Range
2028 example: bytes 0-262143/2469036
2031 Specifies the bytes in the file that the request is uploading.
2033 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2034 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2035 - name: Content-Length
2042 Size of the chunk that the request is sending.
2044 The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
2045 doesn't mandate for chunks to have the same size throughout the upload sequence.
2047 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2048 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2051 application/octet-stream:
2057 description: last chunk received
2065 $ref: '#/components/schemas/VideoUploadResponse'
2067 description: resume incomplete
2072 example: bytes=0-262143
2078 description: video didn't pass upload filter
2080 description: upload not found
2082 description: chunk doesn't match range
2084 description: video unreadable
2086 description: too many concurrent requests
2088 description: upload is already being processed
2095 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2096 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2097 operationId: uploadResumableCancel
2108 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2109 not valid anymore and the upload session has already been deleted with its data ;-)
2112 - name: Content-Length
2120 description: upload cancelled
2127 description: upload not found
2131 summary: Import a video
2132 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2133 operationId: importVideo
2141 multipart/form-data:
2143 $ref: '#/components/schemas/VideoCreateImport'
2146 contentType: application/x-bittorrent
2148 contentType: image/jpeg
2150 contentType: image/jpeg
2153 description: successful operation
2157 $ref: '#/components/schemas/VideoUploadResponse'
2159 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2161 description: video didn't pass pre-import filter
2163 description: HTTP or Torrent/magnetURI import not enabled
2167 summary: Create a live
2168 operationId: addLive
2176 description: successful operation
2180 $ref: '#/components/schemas/VideoUploadResponse'
2182 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2184 Disambiguate via `type`:
2185 - default type for a validation error
2186 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2188 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2190 Disambiguate via `type`:
2191 - `live_not_enabled` for a disabled live feature
2192 - `live_not_allowing_replay` for a disabled replay feature
2193 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2194 - `max_user_lives_limit_reached` for the user concurrent live limit
2197 multipart/form-data:
2202 description: Channel id that will contain this live video
2207 description: User can stream multiple times in a permanent live
2210 description: Live video/replay thumbnail file
2214 description: Live video/replay preview file
2218 $ref: '#/components/schemas/VideoPrivacySet'
2220 $ref: '#/components/schemas/VideoCategorySet'
2222 $ref: '#/components/schemas/VideoLicenceSet'
2224 $ref: '#/components/schemas/VideoLanguageSet'
2226 description: Live video/replay description
2229 description: A text tell the audience how to support the creator
2230 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2233 description: Whether or not this live video/replay contains sensitive content
2236 description: Live video/replay name
2241 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2250 description: Enable or disable comments for this live video/replay
2253 description: Enable or disable downloading for the replay of this live video
2260 contentType: image/jpeg
2262 contentType: image/jpeg
2266 summary: Get information about a live
2267 operationId: getLiveId
2274 - $ref: '#/components/parameters/idOrUUID'
2277 description: successful operation
2281 $ref: '#/components/schemas/LiveVideoResponse'
2283 summary: Update information about a live
2284 operationId: updateLiveId
2291 - $ref: '#/components/parameters/idOrUUID'
2296 $ref: '#/components/schemas/LiveVideoUpdate'
2299 description: successful operation
2301 description: bad parameters or trying to update a live that has already started
2303 description: trying to save replay of the live but saving replay is not enabled on the instance
2307 summary: List my abuses
2308 operationId: getMyAbuses
2317 description: only list the report with this id
2323 $ref: '#/components/schemas/AbuseStateSet'
2324 - $ref: '#/components/parameters/abusesSort'
2325 - $ref: '#/components/parameters/start'
2326 - $ref: '#/components/parameters/count'
2329 description: successful operation
2341 $ref: '#/components/schemas/Abuse'
2345 summary: List abuses
2346 operationId: getAbuses
2356 description: only list the report with this id
2359 - name: predefinedReason
2361 description: predefined reason the listed reports should contain
2363 $ref: '#/components/schemas/PredefinedAbuseReasons'
2366 description: plain search that will match with video titles, reporter names and more
2372 $ref: '#/components/schemas/AbuseStateSet'
2373 - name: searchReporter
2375 description: only list reports of a specific reporter
2378 - name: searchReportee
2379 description: only list reports of a specific reportee
2385 description: only list reports of a specific video
2388 - name: searchVideoChannel
2390 description: only list reports of a specific video channel
2395 description: only list deleted or blocklisted videos
2403 description: only list account, comment or video reports
2410 - $ref: '#/components/parameters/start'
2411 - $ref: '#/components/parameters/count'
2412 - $ref: '#/components/parameters/abusesSort'
2415 description: successful operation
2427 $ref: '#/components/schemas/Abuse'
2429 summary: Report an abuse
2442 description: Reason why the user reports this video
2447 $ref: '#/components/schemas/PredefinedAbuseReasons'
2452 description: Video id to report
2454 - $ref: '#/components/schemas/Video/properties/id'
2458 description: Timestamp in the video that marks the beginning of the report
2463 description: Timestamp in the video that marks the ending of the report
2469 description: Comment id to report
2471 - $ref: '#/components/schemas/VideoComment/properties/id'
2476 description: Account id to report
2482 description: successful operation
2492 $ref: '#/components/schemas/id'
2494 description: incorrect request parameters
2496 '/abuses/{abuseId}':
2498 summary: Update an abuse
2506 - $ref: '#/components/parameters/abuseId'
2514 $ref: '#/components/schemas/AbuseStateSet'
2517 description: Update the report comment visible only to the moderation team
2522 description: successful operation
2524 description: abuse not found
2528 summary: Delete an abuse
2534 - $ref: '#/components/parameters/abuseId'
2537 description: successful operation
2539 description: block not found
2541 '/abuses/{abuseId}/messages':
2543 summary: List messages of an abuse
2549 - $ref: '#/components/parameters/abuseId'
2552 description: successful operation
2564 $ref: '#/components/schemas/AbuseMessage'
2566 summary: Add message to an abuse
2572 - $ref: '#/components/parameters/abuseId'
2581 description: Message to send
2589 description: successful operation
2591 description: incorrect request parameters
2593 '/abuses/{abuseId}/messages/{abuseMessageId}':
2595 summary: Delete an abuse message
2601 - $ref: '#/components/parameters/abuseId'
2602 - $ref: '#/components/parameters/abuseMessageId'
2605 description: successful operation
2607 '/videos/{id}/blacklist':
2609 summary: Block a video
2610 operationId: addVideoBlock
2618 - $ref: '#/components/parameters/idOrUUID'
2621 description: successful operation
2623 summary: Unblock a video by its id
2624 operationId: delVideoBlock
2632 - $ref: '#/components/parameters/idOrUUID'
2635 description: successful operation
2637 description: block not found
2643 summary: List video blocks
2644 operationId: getVideoBlocks
2653 list only blocks that match this type:
2657 - `2`: automatic block that needs review
2665 description: plain search that will match with video titles, and more
2668 - $ref: '#/components/parameters/start'
2669 - $ref: '#/components/parameters/count'
2670 - $ref: '#/components/parameters/blacklistsSort'
2673 description: successful operation
2685 $ref: '#/components/schemas/VideoBlacklist'
2687 /videos/{id}/captions:
2689 summary: List captions of a video
2690 operationId: getVideoCaptions
2694 - $ref: '#/components/parameters/idOrUUID'
2697 description: successful operation
2709 $ref: '#/components/schemas/VideoCaption'
2711 /videos/{id}/captions/{captionLanguage}:
2713 summary: Add or replace a video caption
2714 operationId: addVideoCaption
2721 - $ref: '#/components/parameters/idOrUUID'
2722 - $ref: '#/components/parameters/captionLanguage'
2725 multipart/form-data:
2730 description: The file to upload.
2735 contentType: text/vtt, application/x-subrip, text/plain
2738 description: successful operation
2740 description: video or language not found
2742 summary: Delete a video caption
2743 operationId: delVideoCaption
2750 - $ref: '#/components/parameters/idOrUUID'
2751 - $ref: '#/components/parameters/captionLanguage'
2754 description: successful operation
2756 description: video or language or caption for that language not found
2760 summary: List video channels
2761 operationId: getVideoChannels
2765 - $ref: '#/components/parameters/start'
2766 - $ref: '#/components/parameters/count'
2767 - $ref: '#/components/parameters/sort'
2770 description: successful operation
2774 $ref: '#/components/schemas/VideoChannelList'
2776 summary: Create a video channel
2777 operationId: addVideoChannel
2784 description: successful operation
2794 $ref: '#/components/schemas/VideoChannel/properties/id'
2799 $ref: '#/components/schemas/VideoChannelCreate'
2801 '/video-channels/{channelHandle}':
2803 summary: Get a video channel
2804 operationId: getVideoChannel
2808 - $ref: '#/components/parameters/channelHandle'
2811 description: successful operation
2815 $ref: '#/components/schemas/VideoChannel'
2817 summary: Update a video channel
2818 operationId: putVideoChannel
2824 - $ref: '#/components/parameters/channelHandle'
2827 description: successful operation
2832 $ref: '#/components/schemas/VideoChannelUpdate'
2834 summary: Delete a video channel
2835 operationId: delVideoChannel
2841 - $ref: '#/components/parameters/channelHandle'
2844 description: successful operation
2846 '/video-channels/{channelHandle}/videos':
2848 summary: List videos of a video channel
2849 operationId: getVideoChannelVideos
2854 - $ref: '#/components/parameters/channelHandle'
2855 - $ref: '#/components/parameters/categoryOneOf'
2856 - $ref: '#/components/parameters/isLive'
2857 - $ref: '#/components/parameters/tagsOneOf'
2858 - $ref: '#/components/parameters/tagsAllOf'
2859 - $ref: '#/components/parameters/licenceOneOf'
2860 - $ref: '#/components/parameters/languageOneOf'
2861 - $ref: '#/components/parameters/nsfw'
2862 - $ref: '#/components/parameters/isLocal'
2863 - $ref: '#/components/parameters/include'
2864 - $ref: '#/components/parameters/skipCount'
2865 - $ref: '#/components/parameters/start'
2866 - $ref: '#/components/parameters/count'
2867 - $ref: '#/components/parameters/videosSort'
2870 description: successful operation
2874 $ref: '#/components/schemas/VideoListResponse'
2876 '/video-channels/{channelHandle}/followers':
2880 summary: 'List followers of a video channel'
2883 operationId: getVideoChannelFollowers
2885 - $ref: '#/components/parameters/channelHandle'
2886 - $ref: '#/components/parameters/start'
2887 - $ref: '#/components/parameters/count'
2888 - $ref: '#/components/parameters/followersSort'
2889 - $ref: '#/components/parameters/search'
2892 description: successful operation
2904 $ref: '#/components/schemas/Follow'
2906 '/video-channels/{channelHandle}/avatar/pick':
2908 summary: Update channel avatar
2914 - $ref: '#/components/parameters/channelHandle'
2917 description: successful operation
2924 $ref: '#/components/schemas/ActorImage'
2926 description: image file too large
2928 X-File-Maximum-Size:
2932 description: Maximum file size for the avatar
2935 multipart/form-data:
2940 description: The file to upload.
2945 contentType: image/png, image/jpeg
2947 '/video-channels/{channelHandle}/avatar':
2949 summary: Delete channel avatar
2955 - $ref: '#/components/parameters/channelHandle'
2958 description: successful operation
2960 '/video-channels/{channelHandle}/banner/pick':
2962 summary: Update channel banner
2968 - $ref: '#/components/parameters/channelHandle'
2971 description: successful operation
2978 $ref: '#/components/schemas/ActorImage'
2980 description: image file too large
2982 X-File-Maximum-Size:
2986 description: Maximum file size for the banner
2989 multipart/form-data:
2994 description: The file to upload.
2999 contentType: image/png, image/jpeg
3001 '/video-channels/{channelHandle}/banner':
3003 summary: Delete channel banner
3009 - $ref: '#/components/parameters/channelHandle'
3012 description: successful operation
3014 /video-playlists/privacies:
3016 summary: List available playlist privacy policies
3017 operationId: getPlaylistPrivacyPolicies
3022 description: successful operation
3031 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3035 summary: List video playlists
3036 operationId: getPlaylists
3040 - $ref: '#/components/parameters/start'
3041 - $ref: '#/components/parameters/count'
3042 - $ref: '#/components/parameters/sort'
3045 description: successful operation
3057 $ref: '#/components/schemas/VideoPlaylist'
3059 summary: Create a video playlist
3060 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3061 operationId: addPlaylist
3068 description: successful operation
3078 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3080 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3082 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3085 multipart/form-data:
3090 description: Video playlist display name
3095 description: Video playlist thumbnail file
3099 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3101 description: Video playlist description
3107 - $ref: '#/components/schemas/id'
3108 description: Video channel in which the playlist will be published
3113 contentType: image/jpeg
3115 /video-playlists/{playlistId}:
3117 summary: Get a video playlist
3121 - $ref: '#/components/parameters/playlistId'
3124 description: successful operation
3128 $ref: '#/components/schemas/VideoPlaylist'
3130 summary: Update a video playlist
3131 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3138 description: successful operation
3140 - $ref: '#/components/parameters/playlistId'
3143 multipart/form-data:
3148 description: Video playlist display name
3153 description: Video playlist thumbnail file
3157 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3159 description: Video playlist description
3163 - $ref: '#/components/schemas/id'
3164 description: Video channel in which the playlist will be published
3167 contentType: image/jpeg
3169 summary: Delete a video playlist
3175 - $ref: '#/components/parameters/playlistId'
3178 description: successful operation
3180 /video-playlists/{playlistId}/videos:
3182 summary: 'List videos of a playlist'
3183 operationId: getVideoPlaylistVideos
3188 - $ref: '#/components/parameters/playlistId'
3189 - $ref: '#/components/parameters/start'
3190 - $ref: '#/components/parameters/count'
3193 description: successful operation
3197 $ref: '#/components/schemas/VideoListResponse'
3199 summary: Add a video in a playlist
3200 operationId: addVideoPlaylistVideo
3207 - $ref: '#/components/parameters/playlistId'
3210 description: successful operation
3216 videoPlaylistElement:
3230 - $ref: '#/components/schemas/Video/properties/uuid'
3231 - $ref: '#/components/schemas/Video/properties/id'
3232 description: Video to add in the playlist
3236 description: Start the video at this specific timestamp
3240 description: Stop the video at this specific timestamp
3244 /video-playlists/{playlistId}/videos/reorder:
3246 summary: 'Reorder a playlist'
3247 operationId: reorderVideoPlaylist
3253 - $ref: '#/components/parameters/playlistId'
3256 description: successful operation
3265 description: 'Start position of the element to reorder'
3267 insertAfterPosition:
3269 description: 'New position for the block to reorder, to add the block before the first element'
3273 description: 'How many element from `startPosition` to reorder'
3277 - insertAfterPosition
3279 /video-playlists/{playlistId}/videos/{playlistElementId}:
3281 summary: Update a playlist element
3282 operationId: putVideoPlaylistVideo
3288 - $ref: '#/components/parameters/playlistId'
3289 - $ref: '#/components/parameters/playlistElementId'
3292 description: successful operation
3302 description: Start the video at this specific timestamp
3306 description: Stop the video at this specific timestamp
3308 summary: Delete an element from a playlist
3309 operationId: delVideoPlaylistVideo
3315 - $ref: '#/components/parameters/playlistId'
3316 - $ref: '#/components/parameters/playlistElementId'
3319 description: successful operation
3321 '/users/me/video-playlists/videos-exist':
3323 summary: Check video exists in my playlists
3332 description: The video ids to check
3336 $ref: '#/components/schemas/Video/properties/id'
3339 description: successful operation
3361 '/accounts/{name}/video-channels':
3363 summary: List video channels of an account
3368 - $ref: '#/components/parameters/name'
3371 description: include view statistics for the last 30 days (only if authentified as the account user)
3374 - $ref: '#/components/parameters/start'
3375 - $ref: '#/components/parameters/count'
3376 - $ref: '#/components/parameters/sort'
3379 description: successful operation
3383 $ref: '#/components/schemas/VideoChannelList'
3385 '/accounts/{name}/ratings':
3387 summary: List ratings of an account
3393 - $ref: '#/components/parameters/name'
3394 - $ref: '#/components/parameters/start'
3395 - $ref: '#/components/parameters/count'
3396 - $ref: '#/components/parameters/sort'
3400 description: Optionally filter which ratings to retrieve
3408 description: successful operation
3414 $ref: '#/components/schemas/VideoRating'
3416 '/videos/{id}/comment-threads':
3418 summary: List threads of a video
3422 - $ref: '#/components/parameters/idOrUUID'
3423 - $ref: '#/components/parameters/start'
3424 - $ref: '#/components/parameters/count'
3425 - $ref: '#/components/parameters/commentsSort'
3428 description: successful operation
3432 $ref: '#/components/schemas/CommentThreadResponse'
3434 summary: Create a thread
3440 - $ref: '#/components/parameters/idOrUUID'
3443 description: successful operation
3447 $ref: '#/components/schemas/CommentThreadPostResponse'
3449 description: video does not exist
3458 - $ref: '#/components/schemas/VideoComment/properties/text'
3464 '/videos/{id}/comment-threads/{threadId}':
3466 summary: Get a thread
3470 - $ref: '#/components/parameters/idOrUUID'
3471 - $ref: '#/components/parameters/threadId'
3474 description: successful operation
3478 $ref: '#/components/schemas/VideoCommentThreadTree'
3480 '/videos/{id}/comments/{commentId}':
3482 summary: Reply to a thread of a video
3488 - $ref: '#/components/parameters/idOrUUID'
3489 - $ref: '#/components/parameters/commentId'
3492 description: successful operation
3496 $ref: '#/components/schemas/CommentThreadPostResponse'
3498 description: thread or video does not exist
3507 - $ref: '#/components/schemas/VideoComment/properties/text'
3513 summary: Delete a comment or a reply
3519 - $ref: '#/components/parameters/idOrUUID'
3520 - $ref: '#/components/parameters/commentId'
3523 description: successful operation
3525 description: cannot remove comment of another user
3527 description: comment or video does not exist
3529 description: comment is already deleted
3531 '/videos/{id}/rate':
3533 summary: Like/dislike a video
3539 - $ref: '#/components/parameters/idOrUUID'
3555 description: successful operation
3557 description: video does not exist
3563 summary: Search videos
3564 operationId: searchVideos
3569 allowEmptyValue: false
3571 String to search. If the user can make a remote URI search, and the string is an URI then the
3572 PeerTube instance will fetch the remote object and add it to its database. Then,
3573 you can use the REST API to fetch the complete video information and interact with it.
3576 - $ref: '#/components/parameters/categoryOneOf'
3577 - $ref: '#/components/parameters/isLive'
3578 - $ref: '#/components/parameters/tagsOneOf'
3579 - $ref: '#/components/parameters/tagsAllOf'
3580 - $ref: '#/components/parameters/licenceOneOf'
3581 - $ref: '#/components/parameters/languageOneOf'
3582 - $ref: '#/components/parameters/nsfw'
3583 - $ref: '#/components/parameters/isLocal'
3584 - $ref: '#/components/parameters/include'
3585 - $ref: '#/components/parameters/skipCount'
3586 - $ref: '#/components/parameters/start'
3587 - $ref: '#/components/parameters/count'
3588 - $ref: '#/components/parameters/searchTarget'
3589 - $ref: '#/components/parameters/videosSearchSort'
3592 description: Get videos that are published after this date
3598 description: Get videos that are published before this date
3602 - name: originallyPublishedStartDate
3604 description: Get videos that are originally published after this date
3608 - name: originallyPublishedEndDate
3610 description: Get videos that are originally published before this date
3616 description: Get videos that have this minimum duration
3621 description: Get videos that have this maximum duration
3625 'searchTarget === search-index':
3626 $ref: '#/components/callbacks/searchIndex'
3629 description: successful operation
3633 $ref: '#/components/schemas/VideoListResponse'
3635 description: search index unavailable
3637 /search/video-channels:
3641 summary: Search channels
3642 operationId: searchChannels
3648 String to search. If the user can make a remote URI search, and the string is an URI then the
3649 PeerTube instance will fetch the remote object and add it to its database. Then,
3650 you can use the REST API to fetch the complete channel information and interact with it.
3653 - $ref: '#/components/parameters/start'
3654 - $ref: '#/components/parameters/count'
3655 - $ref: '#/components/parameters/searchTarget'
3656 - $ref: '#/components/parameters/sort'
3658 'searchTarget === search-index':
3659 $ref: '#/components/callbacks/searchIndex'
3662 description: successful operation
3666 $ref: '#/components/schemas/VideoChannelList'
3668 description: search index unavailable
3670 /search/video-playlists:
3674 summary: Search playlists
3675 operationId: searchPlaylists
3681 String to search. If the user can make a remote URI search, and the string is an URI then the
3682 PeerTube instance will fetch the remote object and add it to its database. Then,
3683 you can use the REST API to fetch the complete playlist information and interact with it.
3686 - $ref: '#/components/parameters/start'
3687 - $ref: '#/components/parameters/count'
3688 - $ref: '#/components/parameters/searchTarget'
3689 - $ref: '#/components/parameters/sort'
3691 'searchTarget === search-index':
3692 $ref: '#/components/callbacks/searchIndex'
3695 description: successful operation
3707 $ref: '#/components/schemas/VideoPlaylist'
3709 description: search index unavailable
3711 /server/blocklist/accounts:
3715 summary: List account blocks
3720 - $ref: '#/components/parameters/start'
3721 - $ref: '#/components/parameters/count'
3722 - $ref: '#/components/parameters/sort'
3725 description: successful operation
3729 summary: Block an account
3741 example: chocobozzz@example.org
3742 description: account to block, in the form `username@domain`
3747 description: successful operation
3749 description: self-blocking forbidden
3751 '/server/blocklist/accounts/{accountName}':
3755 summary: Unblock an account by its handle
3763 description: account to unblock, in the form `username@domain`
3768 description: successful operation
3770 description: account or account block does not exist
3772 /server/blocklist/servers:
3776 summary: List server blocks
3781 - $ref: '#/components/parameters/start'
3782 - $ref: '#/components/parameters/count'
3783 - $ref: '#/components/parameters/sort'
3786 description: successful operation
3790 summary: Block a server
3803 description: server domain to block
3808 description: successful operation
3810 description: self-blocking forbidden
3812 '/server/blocklist/servers/{host}':
3816 summary: Unblock a server by its domain
3824 description: server domain to unblock
3830 description: successful operation
3832 description: account block does not exist
3834 /server/redundancy/{host}:
3837 - Instance Redundancy
3838 summary: Update a server redundancy policy
3846 description: server domain to mirror
3858 description: allow mirroring of the host's local videos
3863 description: successful operation
3865 description: server is not already known
3867 /server/redundancy/videos:
3871 summary: List videos being mirrored
3872 operationId: getMirroredVideos
3880 description: direction of the mirror
3886 - $ref: '#/components/parameters/start'
3887 - $ref: '#/components/parameters/count'
3888 - $ref: '#/components/parameters/videoRedundanciesSort'
3891 description: successful operation
3897 $ref: '#/components/schemas/VideoRedundancy'
3901 summary: Mirror a video
3902 operationId: putMirroredVideo
3913 $ref: '#/components/schemas/Video/properties/id'
3918 description: successful operation
3920 description: cannot mirror a local video
3922 description: video does not exist
3924 description: video is already mirrored
3926 /server/redundancy/videos/{redundancyId}:
3930 summary: Delete a mirror done on a video
3931 operationId: delMirroredVideo
3936 - name: redundancyId
3939 description: id of an existing redundancy on a video
3944 description: successful operation
3946 description: video redundancy not found
3948 '/feeds/video-comments.{format}':
3952 summary: List comments on videos
3953 operationId: getSyndicatedComments
3958 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3971 description: 'limit listing to a specific video'
3976 description: 'limit listing to a specific account'
3981 description: 'limit listing to a specific account'
3984 - name: videoChannelId
3986 description: 'limit listing to a specific video channel'
3989 - name: videoChannelName
3991 description: 'limit listing to a specific video channel'
3996 description: successful operation
4001 default: 'max-age=900' # 15 min cache
4005 $ref: '#/components/schemas/VideoCommentsForXML'
4008 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4009 application/rss+xml:
4011 $ref: '#/components/schemas/VideoCommentsForXML'
4014 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4017 $ref: '#/components/schemas/VideoCommentsForXML'
4020 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4021 application/atom+xml:
4023 $ref: '#/components/schemas/VideoCommentsForXML'
4026 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4032 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4034 x-summary: field inconsistencies
4037 - videoId filter is mixed with a channel filter
4039 description: video, video channel or account not found
4041 description: accept header unsupported
4043 '/feeds/videos.{format}':
4047 summary: List videos
4048 operationId: getSyndicatedVideos
4053 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4066 description: 'limit listing to a specific account'
4071 description: 'limit listing to a specific account'
4074 - name: videoChannelId
4076 description: 'limit listing to a specific video channel'
4079 - name: videoChannelName
4081 description: 'limit listing to a specific video channel'
4084 - $ref: '#/components/parameters/sort'
4085 - $ref: '#/components/parameters/nsfw'
4086 - $ref: '#/components/parameters/isLocal'
4087 - $ref: '#/components/parameters/include'
4090 description: successful operation
4095 default: 'max-age=900' # 15 min cache
4099 $ref: '#/components/schemas/VideosForXML'
4102 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4103 application/rss+xml:
4105 $ref: '#/components/schemas/VideosForXML'
4108 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4111 $ref: '#/components/schemas/VideosForXML'
4114 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4115 application/atom+xml:
4117 $ref: '#/components/schemas/VideosForXML'
4120 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4126 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4128 description: video channel or account not found
4130 description: accept header unsupported
4132 '/feeds/subscriptions.{format}':
4137 summary: List videos of subscriptions tied to a token
4138 operationId: getSyndicatedSubscriptionVideos
4143 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4156 description: limit listing to a specific account
4162 description: private token allowing access
4166 - $ref: '#/components/parameters/sort'
4167 - $ref: '#/components/parameters/nsfw'
4168 - $ref: '#/components/parameters/isLocal'
4169 - $ref: '#/components/parameters/include'
4172 description: successful operation
4177 default: 'max-age=900' # 15 min cache
4181 $ref: '#/components/schemas/VideosForXML'
4182 application/rss+xml:
4184 $ref: '#/components/schemas/VideosForXML'
4187 $ref: '#/components/schemas/VideosForXML'
4188 application/atom+xml:
4190 $ref: '#/components/schemas/VideosForXML'
4195 description: accept header unsupported
4201 summary: List plugins
4202 operationId: getPlugins
4215 - $ref: '#/components/parameters/start'
4216 - $ref: '#/components/parameters/count'
4217 - $ref: '#/components/parameters/sort'
4220 description: successful operation
4224 $ref: '#/components/schemas/PluginResponse'
4230 summary: List available plugins
4231 operationId: getAvailablePlugins
4244 - name: currentPeerTubeEngine
4248 - $ref: '#/components/parameters/start'
4249 - $ref: '#/components/parameters/count'
4250 - $ref: '#/components/parameters/sort'
4253 description: successful operation
4257 $ref: '#/components/schemas/PluginResponse'
4259 description: plugin index unavailable
4265 summary: Install a plugin
4266 operationId: addPlugin
4279 example: peertube-plugin-auth-ldap
4282 additionalProperties: false
4289 additionalProperties: false
4292 description: successful operation
4294 description: should have either `npmName` or `path` set
4300 summary: Update a plugin
4301 operationId: updatePlugin
4314 example: peertube-plugin-auth-ldap
4317 additionalProperties: false
4324 additionalProperties: false
4327 description: successful operation
4329 description: should have either `npmName` or `path` set
4331 description: existing plugin not found
4337 summary: Uninstall a plugin
4338 operationId: uninstallPlugin
4350 description: name of the plugin/theme in its package.json
4351 example: peertube-plugin-auth-ldap
4356 description: successful operation
4358 description: existing plugin not found
4364 summary: Get a plugin
4365 operationId: getPlugin
4370 - $ref: '#/components/parameters/npmName'
4373 description: successful operation
4377 $ref: '#/components/schemas/Plugin'
4379 description: plugin not found
4381 /plugins/{npmName}/settings:
4385 summary: Set a plugin's settings
4390 - $ref: '#/components/parameters/npmName'
4399 additionalProperties: true
4402 description: successful operation
4404 description: plugin not found
4406 /plugins/{npmName}/public-settings:
4410 summary: Get a plugin's public settings
4412 - $ref: '#/components/parameters/npmName'
4415 description: successful operation
4420 additionalProperties: true
4422 description: plugin not found
4424 /plugins/{npmName}/registered-settings:
4428 summary: Get a plugin's registered settings
4433 - $ref: '#/components/parameters/npmName'
4436 description: successful operation
4441 additionalProperties: true
4443 description: plugin not found
4446 - url: 'https://peertube2.cpy.re/api/v1'
4447 description: Live Test Server (live data - latest nightly version)
4448 - url: 'https://peertube3.cpy.re/api/v1'
4449 description: Live Test Server (live data - latest RC version)
4450 - url: 'https://peertube.cpy.re/api/v1'
4451 description: Live Test Server (live data - stable version)
4458 description: Offset used to paginate results
4466 description: "Number of items to return"
4476 description: Sort column
4484 description: Plain text search, applied to various parts of the model depending on endpoint
4492 If the administrator enabled search index support, you can override the default search target.
4495 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4496 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4497 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4498 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4499 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4500 * 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
4501 the data from the origin instance API
4511 description: Sort videos by criteria
4527 description: Sort videos by criteria
4542 description: Sort comments by criteria
4552 description: Sort blocklists by criteria
4568 description: Plain text search that will match with user usernames or emails
4575 description: Filter results down to (un)banned users
4582 description: Sort users by criteria
4593 description: Sort abuses by criteria
4600 videoRedundanciesSort:
4604 description: Sort abuses by criteria
4613 description: Sort followers by criteria
4622 description: The username or handle of the account
4625 example: chocobozzz | chocobozzz@example.org
4630 description: The user id
4632 $ref: '#/components/schemas/id'
4637 description: The object id, uuid or short uuid
4640 - $ref: '#/components/schemas/id'
4641 - $ref: '#/components/schemas/UUIDv4'
4642 - $ref: '#/components/schemas/shortUUID'
4647 description: Playlist id
4649 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4651 name: playlistElementId
4654 description: Playlist element id
4656 $ref: '#/components/schemas/id'
4661 description: Abuse id
4663 $ref: '#/components/schemas/Abuse/properties/id'
4665 name: abuseMessageId
4668 description: Abuse message id
4670 $ref: '#/components/schemas/AbuseMessage/properties/id'
4672 name: captionLanguage
4675 description: The caption language
4677 $ref: '#/components/schemas/VideoLanguageSet'
4682 description: The video channel handle
4685 example: my_username | my_username@example.com
4687 name: subscriptionHandle
4690 description: The subscription handle
4693 example: my_username | my_username@example.com
4698 description: The thread id (root comment id)
4705 description: The comment id
4707 $ref: '#/components/schemas/VideoComment/properties/id'
4712 description: whether or not the video is a live
4719 description: category id of the video (see [/videos/categories](#operation/getCategories))
4722 - $ref: '#/components/schemas/VideoCategorySet'
4725 $ref: '#/components/schemas/VideoCategorySet'
4732 description: tag(s) of the video
4746 description: tag(s) of the video, where all should be present in the video
4759 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4762 - $ref: '#/components/schemas/VideoLanguageSet'
4765 $ref: '#/components/schemas/VideoLanguageSet'
4772 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4775 - $ref: '#/components/schemas/VideoLicenceSet'
4778 $ref: '#/components/schemas/VideoLicenceSet'
4785 description: if you don't need the `total` in the response
4796 description: whether to include nsfw videos, if any
4808 description: '**PeerTube >= 4.0** Display only local or remote videos'
4822 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
4826 - `1` NOT_PUBLISHED_STATE
4828 - `2` HIDDEN_PRIVACY
4837 description: list of uris to check if each is part of the user subscriptions
4847 description: name of the plugin/theme on npmjs.com or in its package.json
4850 example: peertube-plugin-auth-ldap
4855 description: job type
4859 - activitypub-follow
4860 - activitypub-http-broadcast
4861 - activitypub-http-fetcher
4862 - activitypub-http-unicast
4868 - activitypub-refresher
4893 Authenticating via OAuth requires the following steps:
4894 - Have an activated account
4895 - [Generate] an access token for that account at `/api/v1/users/token`.
4896 - Make requests with the *Authorization: Bearer <token\>* header
4897 - Profit, depending on the role assigned to the account
4899 Note that the __access token is valid for 1 day__ and is given
4900 along with a __refresh token valid for 2 weeks__.
4902 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4906 tokenUrl: /api/v1/users/token
4909 moderator: Moderator scope
4912 # Resuable core properties
4920 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4921 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4926 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4927 example: 2y84q2MQUMWPbiEcxNXMgC
4930 description: immutable name of the user, used to find or mention its actor
4932 pattern: '/^[a-z0-9._]+$/'
4937 description: immutable name of the channel, used to interact with its actor
4938 example: framasoft_videos
4939 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4950 description: category id of the video (see [/videos/categories](#operation/getCategories))
4952 VideoConstantNumber-Category:
4955 $ref: '#/components/schemas/VideoCategorySet'
4958 example: Science & Technology
4962 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4964 VideoConstantNumber-Licence:
4967 $ref: '#/components/schemas/VideoLicenceSet'
4970 example: Attribution - Share Alike
4974 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4976 VideoConstantString-Language:
4979 $ref: '#/components/schemas/VideoLanguageSet'
4984 VideoPlaylistPrivacySet:
4990 description: Video playlist privacy policy (see [/video-playlists/privacies])
4991 VideoPlaylistPrivacyConstant:
4994 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4998 VideoPlaylistTypeSet:
5003 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5004 VideoPlaylistTypeConstant:
5007 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5018 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5019 VideoPrivacyConstant:
5022 $ref: '#/components/schemas/VideoPrivacySet'
5039 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5046 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5057 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5067 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5071 $ref: '#/components/schemas/AbuseStateSet'
5074 AbusePredefinedReasons:
5087 example: [spamOrMisleading]
5092 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5094 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5096 VideoResolutionConstant:
5097 description: resolutions and their labels for the video
5100 $ref: '#/components/schemas/VideoResolutionSet'
5104 VideoScheduledUpdate:
5107 $ref: '#/components/schemas/VideoPrivacySet'
5111 description: When to update the video
5131 - $ref: '#/components/schemas/ActorImage'
5132 VideoChannelSummary:
5135 $ref: '#/components/schemas/id'
5149 - $ref: '#/components/schemas/ActorImage'
5163 - $ref: '#/components/schemas/Video'
5170 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5171 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5173 $ref: '#/components/schemas/VideoResolutionConstant'
5176 description: Video file size in bytes
5179 description: Direct URL of the torrent file
5183 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5187 description: Direct URL of the video
5191 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5195 description: Frames per second of the video file
5199 description: URL dereferencing the output of ffprobe on the file
5200 VideoStreamingPlaylists:
5205 $ref: '#/components/schemas/id'
5213 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5214 VideoStreamingPlaylists-HLS:
5225 Video files associated to this playlist.
5227 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5229 $ref: '#/components/schemas/VideoFile'
5241 $ref: '#/components/schemas/Video/properties/id'
5243 $ref: '#/components/schemas/Video/properties/uuid'
5245 $ref: '#/components/schemas/Video/properties/name'
5249 description: object id for the video
5251 - $ref: '#/components/schemas/id'
5253 description: universal identifier for the video, that can be used across instances
5255 - $ref: '#/components/schemas/UUIDv4'
5258 - $ref: '#/components/schemas/shortUUID'
5264 example: 2017-10-01T10:52:46.396Z
5265 description: time at which the video object was first drafted
5269 example: 2018-10-01T10:52:46.396Z
5270 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5274 example: 2021-05-04T08:01:01.502Z
5275 description: last time the video's metadata was modified
5276 originallyPublishedAt:
5279 example: 2010-10-01T10:52:46.396Z
5280 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5283 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5284 description: category in which the video is classified
5287 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5288 description: licence under which the video is distributed
5291 - $ref: '#/components/schemas/VideoConstantString-Language'
5292 description: main language used in the video
5295 - $ref: '#/components/schemas/VideoPrivacyConstant'
5296 description: privacy policy used to distribute the video
5300 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5301 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5305 truncated description of the video, written in Markdown.
5306 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5311 description: duration of the video in seconds
5316 description: title of the video
5317 example: What is PeerTube?
5322 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5325 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5328 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5345 - $ref: '#/components/schemas/VideoStateConstant'
5346 description: represents the internal state of the video processing within the PeerTube instance
5350 - $ref: '#/components/schemas/VideoScheduledUpdate'
5358 $ref: '#/components/schemas/AccountSummary'
5360 $ref: '#/components/schemas/VideoChannelSummary'
5369 - $ref: '#/components/schemas/Video'
5374 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5375 description: path at which to get the full description of maximum `10000` characters
5378 description: A text tell the audience how to support the video creator
5379 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5383 $ref: '#/components/schemas/VideoChannel'
5385 $ref: '#/components/schemas/Account'
5387 example: [flowers, gardening]
5405 - https://peertube2.cpy.re/tracker/announce
5406 - wss://peertube2.cpy.re/tracker/socket
5410 $ref: '#/components/schemas/VideoFile'
5412 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5414 - field will be empty
5415 - video files will be found in `streamingPlaylists[].files` field
5419 $ref: '#/components/schemas/VideoStreamingPlaylists'
5421 HLS playlists/manifest files. If HLS is disabled on the server:
5423 - field will be empty
5424 - video files will be found in `files` field
5425 FileRedundancyInformation:
5428 $ref: '#/components/schemas/id'
5453 $ref: '#/components/schemas/id'
5460 $ref: '#/components/schemas/UUIDv4'
5467 $ref: '#/components/schemas/FileRedundancyInformation'
5471 $ref: '#/components/schemas/FileRedundancyInformation'
5472 VideoImportStateConstant:
5480 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5487 additionalProperties: false
5491 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5492 required: [targetUrl]
5495 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5496 required: [magnetUri]
5499 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5500 required: [torrentfile]
5501 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5510 - $ref: '#/components/schemas/id'
5514 description: remote URL where to find the import's source video
5515 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5519 description: magnet URI allowing to resolve the import's source video
5520 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5525 description: Torrent file containing only the video file
5532 - $ref: '#/components/schemas/VideoImportStateConstant'
5548 - $ref: '#/components/schemas/Video'
5558 $ref: '#/components/schemas/VideoImport'
5562 $ref: '#/components/schemas/id'
5565 example: The video is a spam
5569 $ref: '#/components/schemas/AbusePredefinedReasons'
5571 $ref: '#/components/schemas/Account'
5573 $ref: '#/components/schemas/AbuseStateConstant'
5576 example: Decided to ban the server since it spams us regularly
5580 $ref: '#/components/schemas/VideoInfo'
5587 $ref: '#/components/schemas/id'
5598 $ref: '#/components/schemas/AccountSummary'
5602 $ref: '#/components/schemas/id'
5604 $ref: '#/components/schemas/Video/properties/id'
5616 $ref: '#/components/schemas/UUIDv4'
5634 $ref: '#/components/schemas/id'
5636 $ref: '#/components/schemas/UUIDv4'
5639 - $ref: '#/components/schemas/shortUUID'
5662 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5664 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5666 $ref: '#/components/schemas/AccountSummary'
5668 $ref: '#/components/schemas/VideoChannelSummary'
5672 $ref: '#/components/schemas/id'
5679 description: Text of the comment
5681 example: This video is wonderful!
5683 $ref: '#/components/schemas/id'
5687 - $ref: '#/components/schemas/id'
5689 $ref: '#/components/schemas/Video/properties/id'
5704 totalRepliesFromVideoAuthor:
5711 $ref: '#/components/schemas/Account'
5712 VideoCommentThreadTree:
5715 $ref: '#/components/schemas/VideoComment'
5719 $ref: '#/components/schemas/VideoCommentThreadTree'
5723 $ref: '#/components/schemas/VideoConstantString-Language'
5739 $ref: '#/components/schemas/id'
5756 $ref: '#/components/schemas/id'
5761 description: immutable name of the actor, used to find or mention it
5763 - $ref: '#/components/schemas/username'
5767 description: server on which the actor is resident
5768 hostRedundancyAllowed:
5770 description: whether this actor's host allows redundancy of its videos
5774 description: number of actors subscribed to by this actor, as seen by this instance
5778 description: number of followers of this actor, as seen by this instance
5786 $ref: '#/components/schemas/ActorImage'
5789 - $ref: '#/components/schemas/Actor'
5792 description: object id for the user tied to this account
5794 - $ref: '#/components/schemas/User/properties/id'
5797 description: editable name of the account, displayed in its representations
5802 description: text or bio displayed on the account's profile
5808 description: timestamp within the video, in seconds
5875 allowedForCurrentIP:
5877 requiresEmailVerification:
5895 $ref: '#/components/schemas/VideoResolutionSet'
5980 example: 16810141515
6089 requiresEmailVerification:
6104 description: Settings that apply to new users, if registration is enabled
6108 example: 16810141515
6114 description: Settings pertaining to transcoding jobs
6118 allowAdditionalExtensions:
6120 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6123 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6126 description: Amount of threads used by ffmpeg for 1 transcoding job
6129 description: Amount of transcoding jobs to execute in parallel
6135 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6138 description: Resolutions to transcode _new videos_ to
6158 description: WebTorrent-specific settings
6164 description: HLS-specific settings
6214 $ref: '#/components/schemas/id'
6216 $ref: '#/components/schemas/Actor'
6218 $ref: '#/components/schemas/Actor'
6221 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6234 PredefinedAbuseReasons:
6235 description: Reason categories that help triage reports
6253 $ref: '#/components/schemas/id'
6265 - activitypub-http-unicast
6266 - activitypub-http-broadcast
6267 - activitypub-http-fetcher
6268 - activitypub-follow
6274 - activitypub-refresher
6278 additionalProperties: true
6281 additionalProperties: true
6297 $ref: '#/components/schemas/id'
6302 $ref: '#/components/schemas/id'
6303 VideoUploadRequestCommon:
6306 description: Video name
6308 example: What is PeerTube?
6312 description: Channel id that will contain this video
6317 $ref: '#/components/schemas/VideoPrivacySet'
6319 $ref: '#/components/schemas/VideoCategorySet'
6321 $ref: '#/components/schemas/VideoLicenceSet'
6323 $ref: '#/components/schemas/VideoLanguageSet'
6325 description: Video description
6328 **[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)**
6330 description: Whether or not we wait transcoding before publish the video
6333 description: A text tell the audience how to support the video creator
6334 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6337 description: Whether or not this video contains sensitive content
6340 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6353 description: Enable or disable comments for this video
6356 description: Enable or disable downloading for this video
6358 originallyPublishedAt:
6359 description: Date when the content was originally published
6363 $ref: '#/components/schemas/VideoScheduledUpdate'
6365 description: Video thumbnail file
6369 description: Video preview file
6375 VideoUploadRequestLegacy:
6377 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6383 description: Video file
6386 VideoUploadRequestResumable:
6388 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6394 description: Video filename including extension
6397 example: what_is_peertube.mp4
6399 description: Video thumbnail file
6403 description: Video preview file
6406 VideoUploadResponse:
6412 $ref: '#/components/schemas/Video/properties/id'
6414 $ref: '#/components/schemas/Video/properties/uuid'
6416 $ref: '#/components/schemas/Video/properties/shortUUID'
6417 CommentThreadResponse:
6426 $ref: '#/components/schemas/VideoComment'
6427 CommentThreadPostResponse:
6430 $ref: '#/components/schemas/VideoComment'
6440 $ref: '#/components/schemas/Video'
6444 $ref: '#/components/schemas/Account'
6447 description: Automatically start playing the upcoming video after the currently playing video
6448 autoPlayNextVideoPlaylist:
6450 description: Automatically start playing the video on the playlist after the currently playing video
6453 description: Automatically start playing the video on the watch page
6463 description: The user email
6466 description: Has the user confirmed their email address?
6469 - $ref: '#/components/schemas/id'
6473 description: Auth plugin to use to authenticate the user
6477 noInstanceConfigWarningModal:
6479 noAccountSetupWarningModal:
6484 $ref: '#/components/schemas/NSFWPolicy'
6486 $ref: '#/components/schemas/UserRole'
6495 description: Theme enabled by this user
6497 $ref: '#/components/schemas/username'
6501 $ref: '#/components/schemas/VideoChannel'
6504 description: The user video quota in bytes
6508 description: The user daily video quota in bytes
6512 description: Enable P2P in the player
6515 - $ref: '#/components/schemas/User'
6517 # optionally present fields: they require WITH_STATS scope
6520 description: Count of videos published
6523 description: Count of reports/abuses of which the user is a target
6524 abusesAcceptedCount:
6526 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6529 description: Count of reports/abuses created by the user
6532 description: Count of comments published
6536 $ref: '#/components/schemas/username'
6538 $ref: '#/components/schemas/password'
6542 description: The user email
6545 description: The user video quota in bytes
6549 description: The user daily video quota in bytes
6552 $ref: '#/components/schemas/usernameChannel'
6554 $ref: '#/components/schemas/UserRole'
6556 $ref: '#/components/schemas/UserAdminFlags'
6567 description: The updated email of the user
6569 - $ref: '#/components/schemas/User/properties/email'
6572 description: Set the email as verified
6575 description: The updated video quota of the user in bytes
6578 description: The updated daily video quota of the user in bytes
6582 description: The auth plugin to use to authenticate the user
6583 example: 'peertube-plugin-auth-saml2'
6585 $ref: '#/components/schemas/UserRole'
6587 $ref: '#/components/schemas/UserAdminFlags'
6589 # see shared/models/users/user-update-me.model.ts:
6592 $ref: '#/components/schemas/password'
6594 $ref: '#/components/schemas/password'
6596 description: new email used for login and service communications
6598 - $ref: '#/components/schemas/User/properties/email'
6601 description: new name of the user in its representations
6606 description: new NSFW display policy
6613 description: whether to enable P2P in the player or not
6616 description: new preference regarding playing videos automatically
6619 description: new preference regarding playing following videos automatically
6620 autoPlayNextVideoPlaylist:
6622 description: new preference regarding playing following playlist videos automatically
6623 videosHistoryEnabled:
6625 description: whether to keep track of watched history or not
6630 description: list of languages to filter videos down to
6633 noInstanceConfigWarningModal:
6635 noAccountSetupWarningModal:
6642 $ref: '#/components/schemas/id'
6649 description: Rating of the video
6656 $ref: '#/components/schemas/Video'
6663 description: Rating of the video
6670 description: immutable name of the user, used to find or mention its actor
6672 - $ref: '#/components/schemas/username'
6674 $ref: '#/components/schemas/password'
6678 description: email of the user, used for login or service communications
6681 description: editable name of the user, displayed in its representations
6686 description: channel base information used to create the first channel of the user
6689 $ref: '#/components/schemas/usernameChannel'
6691 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6701 pattern: /^[a-z0-9]$/
6704 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6707 pattern: /^[a-zA-Z0-9]$/
6710 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6711 OAuthToken-password:
6713 - $ref: '#/components/schemas/OAuthClient'
6723 $ref: '#/components/schemas/User/properties/username'
6725 $ref: '#/components/schemas/password'
6732 OAuthToken-refresh_token:
6734 - $ref: '#/components/schemas/OAuthClient'
6745 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6754 # GET/POST/PUT properties
6757 description: editable name of the channel, displayed in its representations
6758 example: Videos of Framasoft
6763 example: Videos made with <3 by Framasoft
6768 description: text shown by default on all videos of this channel, to tell the audience how to support it
6769 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6772 # GET-only properties
6776 - $ref: '#/components/schemas/id'
6792 $ref: '#/components/schemas/UUIDv4'
6795 - $ref: '#/components/schemas/VideoChannel'
6798 description: username of the channel to create
6800 - $ref: '#/components/schemas/usernameChannel'
6806 - $ref: '#/components/schemas/VideoChannel'
6808 bulkVideosSupportUpdate:
6810 description: Update the support field for all videos of this channel
6820 - $ref: '#/components/schemas/VideoChannel'
6821 - $ref: '#/components/schemas/Actor'
6826 name: 'media:peerLink'
6835 - application/x-bittorrent
6841 name: 'media:content'
6872 VideoCommentsForXML:
6907 description: video watch page URL
6910 description: video canonical URL
6914 description: video publication date
6917 description: video description
6920 description: video description
6923 description: publisher user name
6926 description: video category (MRSS)
6929 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6944 description: video embed path, relative to the canonical URL domain (MRSS)
6953 description: video watch path, relative to the canonical URL domain (MRSS)
6974 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6975 'media:description':
6982 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6985 description: main streamable file for the video
6995 - application/x-bittorrent
7004 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)
7007 - $ref: '#/components/schemas/MRSSPeerLink'
7008 - $ref: '#/components/schemas/MRSSGroupContent'
7009 NotificationSettingValue:
7026 $ref: '#/components/schemas/id'
7030 Notification type, following the `UserNotificationType` enum:
7032 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7034 - `2` NEW_COMMENT_ON_MY_VIDEO
7036 - `3` NEW_ABUSE_FOR_MODERATORS
7038 - `4` BLACKLIST_ON_MY_VIDEO
7040 - `5` UNBLACKLIST_ON_MY_VIDEO
7042 - `6` MY_VIDEO_PUBLISHED
7044 - `7` MY_VIDEO_IMPORT_SUCCESS
7046 - `8` MY_VIDEO_IMPORT_ERROR
7048 - `9` NEW_USER_REGISTRATION
7052 - `11` COMMENT_MENTION
7054 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7056 - `13` NEW_INSTANCE_FOLLOWER
7058 - `14` AUTO_INSTANCE_FOLLOWING
7064 - $ref: '#/components/schemas/VideoInfo'
7068 $ref: '#/components/schemas/ActorInfo'
7074 $ref: '#/components/schemas/id'
7077 $ref: '#/components/schemas/VideoInfo'
7082 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7092 $ref: '#/components/schemas/id'
7096 $ref: '#/components/schemas/VideoInfo'
7098 $ref: '#/components/schemas/ActorInfo'
7104 $ref: '#/components/schemas/id'
7107 - $ref: '#/components/schemas/VideoInfo'
7113 $ref: '#/components/schemas/id'
7116 - $ref: '#/components/schemas/VideoInfo'
7120 - $ref: '#/components/schemas/ActorInfo'
7126 $ref: '#/components/schemas/id'
7128 $ref: '#/components/schemas/ActorInfo'
7156 NotificationListResponse:
7165 $ref: '#/components/schemas/Notification'
7170 example: peertube-plugin-auth-ldap
7198 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7201 additionalProperties: true
7217 $ref: '#/components/schemas/Plugin'
7224 description: User can stream multiple times in a permanent live
7233 description: RTMP stream key to use to stream into this live video
7237 description: User can stream multiple times in a permanent live
7244 'https://search.example.org/api/v1/search/videos':
7246 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7249 description: successful operation
7253 $ref: '#/components/schemas/VideoListResponse'