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/filter'
371 - $ref: '#/components/parameters/skipCount'
372 - $ref: '#/components/parameters/start'
373 - $ref: '#/components/parameters/count'
374 - $ref: '#/components/parameters/videosSort'
377 description: successful operation
381 $ref: '#/components/schemas/VideoListResponse'
385 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
386 .then(function(response) {
387 return response.json()
388 }).then(function(data) {
394 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
400 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
402 http = Net::HTTP.new(uri.host, uri.port)
405 response = http.get(uri.request_uri)
407 puts JSON.parse(response.read_body)
412 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
417 '/accounts/{name}/followers':
421 summary: 'List followers of an account'
424 operationId: getAccountFollowers
426 - $ref: '#/components/parameters/name'
427 - $ref: '#/components/parameters/start'
428 - $ref: '#/components/parameters/count'
429 - $ref: '#/components/parameters/followersSort'
430 - $ref: '#/components/parameters/search'
433 description: successful operation
445 $ref: '#/components/schemas/Follow'
451 summary: List accounts
452 operationId: getAccounts
454 - $ref: '#/components/parameters/start'
455 - $ref: '#/components/parameters/count'
456 - $ref: '#/components/parameters/sort'
459 description: successful operation
465 $ref: '#/components/schemas/Account'
471 summary: Get instance public configuration
472 operationId: getConfig
475 description: successful operation
479 $ref: '#/components/schemas/ServerConfig'
482 externalValue: https://peertube2.cpy.re/api/v1/config
486 summary: Get instance "About" information
487 operationId: getAbout
492 description: successful operation
496 $ref: '#/components/schemas/ServerConfigAbout'
499 externalValue: https://peertube2.cpy.re/api/v1/config/about
503 summary: Get instance runtime configuration
504 operationId: getCustomConfig
512 description: successful operation
516 $ref: '#/components/schemas/ServerConfigCustom'
518 summary: Set instance runtime configuration
519 operationId: putCustomConfig
527 description: successful operation
529 x-summary: field inconsistencies
532 - the emailer is disabled and the instance is open to registrations
533 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
535 summary: Delete instance runtime configuration
536 operationId: delCustomConfig
544 description: successful operation
546 /custom-pages/homepage/instance:
548 summary: Get instance custom homepage
553 description: No homepage set
555 description: successful operation
559 $ref: '#/components/schemas/CustomHomepage'
561 summary: Set instance custom homepage
575 description: content of the homepage, that will be injected in the client
578 description: successful operation
582 summary: List instance jobs
593 description: The state of the job ('' for for no filter)
603 - $ref: '#/components/parameters/jobType'
604 - $ref: '#/components/parameters/start'
605 - $ref: '#/components/parameters/count'
606 - $ref: '#/components/parameters/sort'
609 description: successful operation
622 $ref: '#/components/schemas/Job'
628 summary: List instances following the server
630 - $ref: '#/components/parameters/followState'
631 - $ref: '#/components/parameters/actorType'
632 - $ref: '#/components/parameters/start'
633 - $ref: '#/components/parameters/count'
634 - $ref: '#/components/parameters/sort'
637 description: successful operation
649 $ref: '#/components/schemas/Follow'
651 '/server/followers/{nameWithHost}':
653 summary: Remove or reject a follower to your server
663 description: The remote actor handle to remove from your followers
669 description: successful operation
671 description: follower not found
673 '/server/followers/{nameWithHost}/reject':
675 summary: Reject a pending follower to your server
685 description: The remote actor handle to remove from your followers
691 description: successful operation
693 description: follower not found
695 '/server/followers/{nameWithHost}/accept':
697 summary: Accept a pending follower to your server
707 description: The remote actor handle to remove from your followers
713 description: successful operation
715 description: follower not found
721 summary: List instances followed by the server
723 - $ref: '#/components/parameters/followState'
724 - $ref: '#/components/parameters/actorType'
725 - $ref: '#/components/parameters/start'
726 - $ref: '#/components/parameters/count'
727 - $ref: '#/components/parameters/sort'
730 description: successful operation
742 $ref: '#/components/schemas/Follow'
749 summary: Follow a list of actors (PeerTube instance, channel or account)
752 description: successful operation
754 description: cannot follow a non-HTTPS server
773 '/server/following/{hostOrHandle}':
775 summary: Unfollow an actor (PeerTube instance, channel or account)
785 description: The hostOrHandle to unfollow
790 description: successful operation
792 description: host or handle not found
796 summary: Create a user
805 description: user created
809 $ref: '#/components/schemas/AddUserResponse'
815 id: '$response.body#/user/id'
820 id: '$response.body#/user/id'
825 id: '$response.body#/user/id'
827 description: insufficient authority to create an admin or moderator
832 $ref: '#/components/schemas/AddUser'
834 If the smtp server is configured, you can leave the password empty and an email will be sent
835 asking the user to set it first.
839 operationId: getUsers
846 - $ref: '#/components/parameters/usersSearch'
847 - $ref: '#/components/parameters/usersBlocked'
848 - $ref: '#/components/parameters/start'
849 - $ref: '#/components/parameters/count'
850 - $ref: '#/components/parameters/usersSort'
853 description: successful operation
859 $ref: '#/components/schemas/User'
863 - $ref: '#/components/parameters/id'
865 summary: Delete a user
874 description: successful operation
885 description: include statistics about the user (only available as a moderator/admin)
890 x-summary: successful operation
892 As an admin/moderator, you can request a response augmented with statistics about the user's
893 moderation relations and videos usage, by using the `withStats` parameter.
898 - $ref: '#/components/schemas/User'
899 - $ref: '#/components/schemas/UserWithStats'
901 summary: Update a user
909 description: successful operation
914 $ref: '#/components/schemas/UpdateUser'
917 /oauth-clients/local:
919 summary: Login prerequisite
920 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
921 operationId: getOAuthClient
926 description: successful operation
930 $ref: '#/components/schemas/OAuthClient'
932 UseOAuthClientToLogin:
933 operationId: getOAuthToken
935 client_id: '$response.body#/client_id'
936 client_secret: '$response.body#/client_secret'
940 API="https://peertube2.cpy.re/api/v1"
943 curl -s "$API/oauth-clients/local"
948 operationId: getOAuthToken
949 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
954 application/x-www-form-urlencoded:
957 - $ref: '#/components/schemas/OAuthToken-password'
958 - $ref: '#/components/schemas/OAuthToken-refresh_token'
960 propertyName: grant_type
962 password: '#/components/schemas/OAuthToken-password'
963 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
966 description: successful operation
977 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
978 description: valid for 1 day
981 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
982 description: valid for 2 weeks
987 refresh_token_expires_in:
992 x-summary: client or credentials are invalid
994 Disambiguate via `type`:
995 - `invalid_client` for an unmatched `client_id`
996 - `invalid_grant` for unmatched credentials
998 x-summary: token expired
1000 Disambiguate via `type`:
1001 - default value for a regular authentication failure
1002 - `invalid_token` for an expired token
1007 API="https://peertube2.cpy.re/api/v1"
1008 USERNAME="<your_username>"
1009 PASSWORD="<your_password>"
1012 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1013 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1014 curl -s "$API/users/token" \
1015 --data client_id="$client_id" \
1016 --data client_secret="$client_secret" \
1017 --data grant_type=password \
1018 --data username="$USERNAME" \
1019 --data password="$PASSWORD" \
1020 | jq -r ".access_token"
1022 /users/revoke-token:
1025 description: Revokes your access token and its associated refresh token, destroying your current session.
1026 operationId: revokeOAuthToken
1033 description: successful operation
1037 summary: Register a user
1038 operationId: registerUser
1044 description: successful operation
1049 $ref: '#/components/schemas/RegisterUser'
1052 /users/{id}/verify-email:
1054 summary: Verify a user
1055 operationId: verifyUser
1057 Following a user registration, the new user will receive an email asking to click a link
1058 containing a secret.
1063 - $ref: '#/components/parameters/id'
1076 - verificationString
1079 description: successful operation
1081 description: invalid verification string
1083 description: user not found
1085 /users/ask-send-verify-email:
1087 summary: Resend user verification link
1088 operationId: resendEmailToVerifyUser
1094 description: successful operation
1098 summary: Get my user information
1099 operationId: getUserInfo
1107 description: successful operation
1113 $ref: '#/components/schemas/User'
1115 summary: Update my user information
1116 operationId: putUserInfo
1124 description: successful operation
1129 $ref: '#/components/schemas/UpdateMe'
1132 /users/me/videos/imports:
1134 summary: Get video imports of my user
1142 - $ref: '#/components/parameters/start'
1143 - $ref: '#/components/parameters/count'
1144 - $ref: '#/components/parameters/sort'
1147 description: successful operation
1151 $ref: '#/components/schemas/VideoImportsList'
1153 /users/me/video-quota-used:
1155 summary: Get my user used quota
1163 description: successful operation
1171 description: The user video quota used so far in bytes
1172 example: 16810141515
1173 videoQuotaUsedDaily:
1175 description: The user video quota used today in bytes
1178 '/users/me/videos/{videoId}/rating':
1180 summary: Get rate of my user for a video
1190 description: The video id
1192 $ref: '#/components/schemas/Video/properties/id'
1195 description: successful operation
1199 $ref: '#/components/schemas/GetMeVideoRating'
1203 summary: Get videos of my user
1211 - $ref: '#/components/parameters/start'
1212 - $ref: '#/components/parameters/count'
1213 - $ref: '#/components/parameters/sort'
1216 description: successful operation
1220 $ref: '#/components/schemas/VideoListResponse'
1222 /users/me/subscriptions:
1224 summary: Get my user subscriptions
1231 - $ref: '#/components/parameters/start'
1232 - $ref: '#/components/parameters/count'
1233 - $ref: '#/components/parameters/sort'
1236 description: successful operation
1240 $ref: '#/components/schemas/VideoChannelList'
1244 summary: Add subscription to my user
1257 description: uri of the video channels to subscribe to
1263 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1266 description: successful operation
1268 /users/me/subscriptions/exist:
1270 summary: Get if subscriptions exist for my user
1277 - $ref: '#/components/parameters/subscriptionsUris'
1280 description: successful operation
1286 /users/me/subscriptions/videos:
1288 summary: List videos of subscriptions of my user
1296 - $ref: '#/components/parameters/categoryOneOf'
1297 - $ref: '#/components/parameters/isLive'
1298 - $ref: '#/components/parameters/tagsOneOf'
1299 - $ref: '#/components/parameters/tagsAllOf'
1300 - $ref: '#/components/parameters/licenceOneOf'
1301 - $ref: '#/components/parameters/languageOneOf'
1302 - $ref: '#/components/parameters/nsfw'
1303 - $ref: '#/components/parameters/filter'
1304 - $ref: '#/components/parameters/skipCount'
1305 - $ref: '#/components/parameters/start'
1306 - $ref: '#/components/parameters/count'
1307 - $ref: '#/components/parameters/videosSort'
1310 description: successful operation
1314 $ref: '#/components/schemas/VideoListResponse'
1316 '/users/me/subscriptions/{subscriptionHandle}':
1318 summary: Get subscription of my user
1325 - $ref: '#/components/parameters/subscriptionHandle'
1328 description: successful operation
1332 $ref: '#/components/schemas/VideoChannel'
1334 summary: Delete subscription of my user
1341 - $ref: '#/components/parameters/subscriptionHandle'
1344 description: successful operation
1346 /users/me/notifications:
1348 summary: List my notifications
1356 description: only list unread notifications
1359 - $ref: '#/components/parameters/start'
1360 - $ref: '#/components/parameters/count'
1361 - $ref: '#/components/parameters/sort'
1364 description: successful operation
1368 $ref: '#/components/schemas/NotificationListResponse'
1370 /users/me/notifications/read:
1372 summary: Mark notifications as read by their id
1385 description: ids of the notifications to mark as read
1392 description: successful operation
1394 /users/me/notifications/read-all:
1396 summary: Mark all my notification as read
1403 description: successful operation
1405 /users/me/notification-settings:
1407 summary: Update my notification settings
1418 newVideoFromSubscription:
1419 $ref: '#/components/schemas/NotificationSettingValue'
1420 newCommentOnMyVideo:
1421 $ref: '#/components/schemas/NotificationSettingValue'
1423 $ref: '#/components/schemas/NotificationSettingValue'
1424 videoAutoBlacklistAsModerator:
1425 $ref: '#/components/schemas/NotificationSettingValue'
1427 $ref: '#/components/schemas/NotificationSettingValue'
1429 $ref: '#/components/schemas/NotificationSettingValue'
1430 myVideoImportFinished:
1431 $ref: '#/components/schemas/NotificationSettingValue'
1433 $ref: '#/components/schemas/NotificationSettingValue'
1434 newUserRegistration:
1435 $ref: '#/components/schemas/NotificationSettingValue'
1437 $ref: '#/components/schemas/NotificationSettingValue'
1438 newInstanceFollower:
1439 $ref: '#/components/schemas/NotificationSettingValue'
1440 autoInstanceFollowing:
1441 $ref: '#/components/schemas/NotificationSettingValue'
1444 description: successful operation
1446 /users/me/history/videos:
1448 summary: List watched videos history
1454 - $ref: '#/components/parameters/start'
1455 - $ref: '#/components/parameters/count'
1456 - $ref: '#/components/parameters/search'
1459 description: successful operation
1463 $ref: '#/components/schemas/VideoListResponse'
1465 /users/me/history/videos/remove:
1467 summary: Clear video history
1474 multipart/form-data:
1479 description: history before this date will be deleted
1484 description: successful operation
1486 /users/me/avatar/pick:
1488 summary: Update my user avatar
1495 description: successful operation
1502 $ref: '#/components/schemas/ActorImage'
1504 description: image file too large
1506 X-File-Maximum-Size:
1510 description: Maximum file size for the avatar
1513 multipart/form-data:
1518 description: The file to upload
1523 contentType: image/png, image/jpeg
1527 summary: Delete my avatar
1534 description: successful operation
1538 summary: List video ownership changes
1540 - Video Ownership Change
1545 description: successful operation
1547 '/videos/ownership/{id}/accept':
1549 summary: Accept ownership change request
1551 - Video Ownership Change
1555 - $ref: '#/components/parameters/idOrUUID'
1558 description: successful operation
1560 description: cannot terminate an ownership change of another user
1562 description: video owneship change not found
1564 '/videos/ownership/{id}/refuse':
1566 summary: Refuse ownership change request
1568 - Video Ownership Change
1572 - $ref: '#/components/parameters/idOrUUID'
1575 description: successful operation
1577 description: cannot terminate an ownership change of another user
1579 description: video owneship change not found
1581 '/videos/{id}/give-ownership':
1583 summary: Request ownership change
1585 - Video Ownership Change
1589 - $ref: '#/components/parameters/idOrUUID'
1593 application/x-www-form-urlencoded:
1603 description: successful operation
1605 description: changing video ownership to a remote account is not supported yet
1607 description: video not found
1611 summary: List videos
1612 operationId: getVideos
1616 - $ref: '#/components/parameters/categoryOneOf'
1617 - $ref: '#/components/parameters/isLive'
1618 - $ref: '#/components/parameters/tagsOneOf'
1619 - $ref: '#/components/parameters/tagsAllOf'
1620 - $ref: '#/components/parameters/licenceOneOf'
1621 - $ref: '#/components/parameters/languageOneOf'
1622 - $ref: '#/components/parameters/nsfw'
1623 - $ref: '#/components/parameters/filter'
1624 - $ref: '#/components/parameters/skipCount'
1625 - $ref: '#/components/parameters/start'
1626 - $ref: '#/components/parameters/count'
1627 - $ref: '#/components/parameters/videosSort'
1630 description: successful operation
1634 $ref: '#/components/schemas/VideoListResponse'
1638 summary: List available video categories
1639 operationId: getCategories
1644 description: successful operation
1653 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1657 summary: List available video licences
1658 operationId: getLicences
1663 description: successful operation
1672 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1676 summary: List available video languages
1677 operationId: getLanguages
1682 description: successful operation
1691 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1695 summary: List available video privacy policies
1696 operationId: getPrivacyPolicies
1701 description: successful operation
1710 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1714 summary: Update a video
1715 operationId: putVideo
1721 - $ref: '#/components/parameters/idOrUUID'
1724 description: successful operation
1727 multipart/form-data:
1732 description: Video thumbnail file
1736 description: Video preview file
1740 $ref: '#/components/schemas/VideoCategorySet'
1742 $ref: '#/components/schemas/VideoLicenceSet'
1744 $ref: '#/components/schemas/VideoLanguageSet'
1746 $ref: '#/components/schemas/VideoPrivacySet'
1748 description: Video description
1751 description: Whether or not we wait transcoding before publish the video
1754 description: A text tell the audience how to support the video creator
1755 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1758 description: Whether or not this video contains sensitive content
1761 description: Video name
1766 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1775 description: Enable or disable comments for this video
1778 description: Enable or disable downloading for this video
1780 originallyPublishedAt:
1781 description: Date when the content was originally published
1785 $ref: '#/components/schemas/VideoScheduledUpdate'
1788 contentType: image/jpeg
1790 contentType: image/jpeg
1792 summary: Get a video
1793 operationId: getVideo
1797 - $ref: '#/components/parameters/idOrUUID'
1800 description: successful operation
1804 $ref: '#/components/schemas/VideoDetails'
1806 summary: Delete a video
1807 operationId: delVideo
1813 - $ref: '#/components/parameters/idOrUUID'
1816 description: successful operation
1818 '/videos/{id}/description':
1820 summary: Get complete video description
1821 operationId: getVideoDesc
1825 - $ref: '#/components/parameters/idOrUUID'
1828 description: successful operation
1837 **[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)**
1839 '/videos/{id}/views':
1841 summary: Add a view to a video
1842 operationId: addView
1846 - $ref: '#/components/parameters/idOrUUID'
1849 description: successful operation
1851 '/videos/{id}/watching':
1853 summary: Set watching progress of a video
1854 operationId: setProgress
1860 - $ref: '#/components/parameters/idOrUUID'
1865 $ref: '#/components/schemas/UserWatchingVideo'
1869 description: successful operation
1873 summary: Upload a video
1874 description: Uses a single request to upload a video.
1875 operationId: uploadLegacy
1883 description: successful operation
1887 $ref: '#/components/schemas/VideoUploadResponse'
1889 description: video didn't pass upload filter
1891 description: upload has timed out
1893 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1895 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1896 - `quota_reached` for quota limits wether daily or global
1898 X-File-Maximum-Size:
1902 description: Maximum file size for the video
1904 description: video type unsupported
1906 description: video unreadable
1909 multipart/form-data:
1911 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1914 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1916 contentType: image/jpeg
1918 contentType: image/jpeg
1923 USERNAME="<your_username>"
1924 PASSWORD="<your_password>"
1925 FILE_PATH="<your_file_path>"
1926 CHANNEL_ID="<your_channel_id>"
1928 API="https://peertube2.cpy.re/api/v1"
1931 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1932 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1933 token=$(curl -s "$API/users/token" \
1934 --data client_id="$client_id" \
1935 --data client_secret="$client_secret" \
1936 --data grant_type=password \
1937 --data username="$USERNAME" \
1938 --data password="$PASSWORD" \
1939 | jq -r ".access_token")
1942 curl -s "$API/videos/upload" \
1943 -H "Authorization: Bearer $token" \
1945 --form videofile=@"$FILE_PATH" \
1946 --form channelId=$CHANNEL_ID \
1949 /videos/upload-resumable:
1951 summary: Initialize the resumable upload of a video
1952 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1953 operationId: uploadResumableInit
1960 - name: X-Upload-Content-Length
1966 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1967 - name: X-Upload-Content-Type
1974 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1979 $ref: '#/components/schemas/VideoUploadRequestResumable'
1982 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1984 description: created
1990 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1996 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1998 Disambiguate via `type`:
1999 - `max_file_size_reached` for the absolute file size limit
2000 - `quota_reached` for quota limits whether daily or global
2002 description: video type unsupported
2004 summary: Send chunk for the resumable upload of a video
2005 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
2006 operationId: uploadResumable
2017 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2018 not valid anymore and you need to initialize a new upload.
2021 - name: Content-Range
2025 example: bytes 0-262143/2469036
2028 Specifies the bytes in the file that the request is uploading.
2030 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2031 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2032 - name: Content-Length
2039 Size of the chunk that the request is sending.
2041 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)
2042 doesn't mandate for chunks to have the same size throughout the upload sequence.
2044 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2045 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2048 application/octet-stream:
2054 description: last chunk received
2062 $ref: '#/components/schemas/VideoUploadResponse'
2064 description: resume incomplete
2069 example: bytes=0-262143
2075 description: video didn't pass upload filter
2077 description: upload not found
2079 description: chunk doesn't match range
2081 description: video unreadable
2083 description: too many concurrent requests
2085 description: upload is already being processed
2092 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2093 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2094 operationId: uploadResumableCancel
2105 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2106 not valid anymore and the upload session has already been deleted with its data ;-)
2109 - name: Content-Length
2117 description: upload cancelled
2124 description: upload not found
2128 summary: Import a video
2129 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2130 operationId: importVideo
2138 multipart/form-data:
2140 $ref: '#/components/schemas/VideoCreateImport'
2143 contentType: application/x-bittorrent
2145 contentType: image/jpeg
2147 contentType: image/jpeg
2150 description: successful operation
2154 $ref: '#/components/schemas/VideoUploadResponse'
2156 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2158 description: video didn't pass pre-import filter
2160 description: HTTP or Torrent/magnetURI import not enabled
2164 summary: Create a live
2165 operationId: addLive
2173 description: successful operation
2177 $ref: '#/components/schemas/VideoUploadResponse'
2179 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2181 Disambiguate via `type`:
2182 - default type for a validation error
2183 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2185 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2187 Disambiguate via `type`:
2188 - `live_not_enabled` for a disabled live feature
2189 - `live_not_allowing_replay` for a disabled replay feature
2190 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2191 - `max_user_lives_limit_reached` for the user concurrent live limit
2194 multipart/form-data:
2199 description: Channel id that will contain this live video
2204 description: User can stream multiple times in a permanent live
2207 description: Live video/replay thumbnail file
2211 description: Live video/replay preview file
2215 $ref: '#/components/schemas/VideoPrivacySet'
2217 $ref: '#/components/schemas/VideoCategorySet'
2219 $ref: '#/components/schemas/VideoLicenceSet'
2221 $ref: '#/components/schemas/VideoLanguageSet'
2223 description: Live video/replay description
2226 description: A text tell the audience how to support the creator
2227 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2230 description: Whether or not this live video/replay contains sensitive content
2233 description: Live video/replay name
2238 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2247 description: Enable or disable comments for this live video/replay
2250 description: Enable or disable downloading for the replay of this live video
2257 contentType: image/jpeg
2259 contentType: image/jpeg
2263 summary: Get information about a live
2264 operationId: getLiveId
2271 - $ref: '#/components/parameters/idOrUUID'
2274 description: successful operation
2278 $ref: '#/components/schemas/LiveVideoResponse'
2280 summary: Update information about a live
2281 operationId: updateLiveId
2288 - $ref: '#/components/parameters/idOrUUID'
2293 $ref: '#/components/schemas/LiveVideoUpdate'
2296 description: successful operation
2298 description: bad parameters or trying to update a live that has already started
2300 description: trying to save replay of the live but saving replay is not enabled on the instance
2304 summary: List my abuses
2305 operationId: getMyAbuses
2314 description: only list the report with this id
2320 $ref: '#/components/schemas/AbuseStateSet'
2321 - $ref: '#/components/parameters/abusesSort'
2322 - $ref: '#/components/parameters/start'
2323 - $ref: '#/components/parameters/count'
2326 description: successful operation
2338 $ref: '#/components/schemas/Abuse'
2342 summary: List abuses
2343 operationId: getAbuses
2353 description: only list the report with this id
2356 - name: predefinedReason
2358 description: predefined reason the listed reports should contain
2360 $ref: '#/components/schemas/PredefinedAbuseReasons'
2363 description: plain search that will match with video titles, reporter names and more
2369 $ref: '#/components/schemas/AbuseStateSet'
2370 - name: searchReporter
2372 description: only list reports of a specific reporter
2375 - name: searchReportee
2376 description: only list reports of a specific reportee
2382 description: only list reports of a specific video
2385 - name: searchVideoChannel
2387 description: only list reports of a specific video channel
2392 description: only list deleted or blocklisted videos
2400 description: only list account, comment or video reports
2407 - $ref: '#/components/parameters/start'
2408 - $ref: '#/components/parameters/count'
2409 - $ref: '#/components/parameters/abusesSort'
2412 description: successful operation
2424 $ref: '#/components/schemas/Abuse'
2426 summary: Report an abuse
2439 description: Reason why the user reports this video
2444 $ref: '#/components/schemas/PredefinedAbuseReasons'
2449 description: Video id to report
2451 - $ref: '#/components/schemas/Video/properties/id'
2455 description: Timestamp in the video that marks the beginning of the report
2460 description: Timestamp in the video that marks the ending of the report
2466 description: Comment id to report
2468 - $ref: '#/components/schemas/VideoComment/properties/id'
2473 description: Account id to report
2479 description: successful operation
2489 $ref: '#/components/schemas/id'
2491 description: incorrect request parameters
2493 '/abuses/{abuseId}':
2495 summary: Update an abuse
2503 - $ref: '#/components/parameters/abuseId'
2511 $ref: '#/components/schemas/AbuseStateSet'
2514 description: Update the report comment visible only to the moderation team
2519 description: successful operation
2521 description: abuse not found
2525 summary: Delete an abuse
2531 - $ref: '#/components/parameters/abuseId'
2534 description: successful operation
2536 description: block not found
2538 '/abuses/{abuseId}/messages':
2540 summary: List messages of an abuse
2546 - $ref: '#/components/parameters/abuseId'
2549 description: successful operation
2561 $ref: '#/components/schemas/AbuseMessage'
2563 summary: Add message to an abuse
2569 - $ref: '#/components/parameters/abuseId'
2578 description: Message to send
2586 description: successful operation
2588 description: incorrect request parameters
2590 '/abuses/{abuseId}/messages/{abuseMessageId}':
2592 summary: Delete an abuse message
2598 - $ref: '#/components/parameters/abuseId'
2599 - $ref: '#/components/parameters/abuseMessageId'
2602 description: successful operation
2604 '/videos/{id}/blacklist':
2606 summary: Block a video
2607 operationId: addVideoBlock
2615 - $ref: '#/components/parameters/idOrUUID'
2618 description: successful operation
2620 summary: Unblock a video by its id
2621 operationId: delVideoBlock
2629 - $ref: '#/components/parameters/idOrUUID'
2632 description: successful operation
2634 description: block not found
2640 summary: List video blocks
2641 operationId: getVideoBlocks
2650 list only blocks that match this type:
2654 - `2`: automatic block that needs review
2662 description: plain search that will match with video titles, and more
2665 - $ref: '#/components/parameters/start'
2666 - $ref: '#/components/parameters/count'
2667 - $ref: '#/components/parameters/blacklistsSort'
2670 description: successful operation
2682 $ref: '#/components/schemas/VideoBlacklist'
2684 /videos/{id}/captions:
2686 summary: List captions of a video
2687 operationId: getVideoCaptions
2691 - $ref: '#/components/parameters/idOrUUID'
2694 description: successful operation
2706 $ref: '#/components/schemas/VideoCaption'
2708 /videos/{id}/captions/{captionLanguage}:
2710 summary: Add or replace a video caption
2711 operationId: addVideoCaption
2718 - $ref: '#/components/parameters/idOrUUID'
2719 - $ref: '#/components/parameters/captionLanguage'
2722 multipart/form-data:
2727 description: The file to upload.
2732 contentType: text/vtt, application/x-subrip, text/plain
2735 description: successful operation
2737 description: video or language not found
2739 summary: Delete a video caption
2740 operationId: delVideoCaption
2747 - $ref: '#/components/parameters/idOrUUID'
2748 - $ref: '#/components/parameters/captionLanguage'
2751 description: successful operation
2753 description: video or language or caption for that language not found
2757 summary: List video channels
2758 operationId: getVideoChannels
2762 - $ref: '#/components/parameters/start'
2763 - $ref: '#/components/parameters/count'
2764 - $ref: '#/components/parameters/sort'
2767 description: successful operation
2771 $ref: '#/components/schemas/VideoChannelList'
2773 summary: Create a video channel
2774 operationId: addVideoChannel
2781 description: successful operation
2791 $ref: '#/components/schemas/VideoChannel/properties/id'
2796 $ref: '#/components/schemas/VideoChannelCreate'
2798 '/video-channels/{channelHandle}':
2800 summary: Get a video channel
2801 operationId: getVideoChannel
2805 - $ref: '#/components/parameters/channelHandle'
2808 description: successful operation
2812 $ref: '#/components/schemas/VideoChannel'
2814 summary: Update a video channel
2815 operationId: putVideoChannel
2821 - $ref: '#/components/parameters/channelHandle'
2824 description: successful operation
2829 $ref: '#/components/schemas/VideoChannelUpdate'
2831 summary: Delete a video channel
2832 operationId: delVideoChannel
2838 - $ref: '#/components/parameters/channelHandle'
2841 description: successful operation
2843 '/video-channels/{channelHandle}/videos':
2845 summary: List videos of a video channel
2846 operationId: getVideoChannelVideos
2851 - $ref: '#/components/parameters/channelHandle'
2852 - $ref: '#/components/parameters/categoryOneOf'
2853 - $ref: '#/components/parameters/isLive'
2854 - $ref: '#/components/parameters/tagsOneOf'
2855 - $ref: '#/components/parameters/tagsAllOf'
2856 - $ref: '#/components/parameters/licenceOneOf'
2857 - $ref: '#/components/parameters/languageOneOf'
2858 - $ref: '#/components/parameters/nsfw'
2859 - $ref: '#/components/parameters/filter'
2860 - $ref: '#/components/parameters/skipCount'
2861 - $ref: '#/components/parameters/start'
2862 - $ref: '#/components/parameters/count'
2863 - $ref: '#/components/parameters/videosSort'
2866 description: successful operation
2870 $ref: '#/components/schemas/VideoListResponse'
2872 '/video-channels/{channelHandle}/followers':
2876 summary: 'List followers of a video channel'
2879 operationId: getVideoChannelFollowers
2881 - $ref: '#/components/parameters/channelHandle'
2882 - $ref: '#/components/parameters/start'
2883 - $ref: '#/components/parameters/count'
2884 - $ref: '#/components/parameters/followersSort'
2885 - $ref: '#/components/parameters/search'
2888 description: successful operation
2900 $ref: '#/components/schemas/Follow'
2902 '/video-channels/{channelHandle}/avatar/pick':
2904 summary: Update channel avatar
2910 - $ref: '#/components/parameters/channelHandle'
2913 description: successful operation
2920 $ref: '#/components/schemas/ActorImage'
2922 description: image file too large
2924 X-File-Maximum-Size:
2928 description: Maximum file size for the avatar
2931 multipart/form-data:
2936 description: The file to upload.
2941 contentType: image/png, image/jpeg
2943 '/video-channels/{channelHandle}/avatar':
2945 summary: Delete channel avatar
2951 - $ref: '#/components/parameters/channelHandle'
2954 description: successful operation
2956 '/video-channels/{channelHandle}/banner/pick':
2958 summary: Update channel banner
2964 - $ref: '#/components/parameters/channelHandle'
2967 description: successful operation
2974 $ref: '#/components/schemas/ActorImage'
2976 description: image file too large
2978 X-File-Maximum-Size:
2982 description: Maximum file size for the banner
2985 multipart/form-data:
2990 description: The file to upload.
2995 contentType: image/png, image/jpeg
2997 '/video-channels/{channelHandle}/banner':
2999 summary: Delete channel banner
3005 - $ref: '#/components/parameters/channelHandle'
3008 description: successful operation
3010 /video-playlists/privacies:
3012 summary: List available playlist privacy policies
3013 operationId: getPlaylistPrivacyPolicies
3018 description: successful operation
3027 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3031 summary: List video playlists
3032 operationId: getPlaylists
3036 - $ref: '#/components/parameters/start'
3037 - $ref: '#/components/parameters/count'
3038 - $ref: '#/components/parameters/sort'
3041 description: successful operation
3053 $ref: '#/components/schemas/VideoPlaylist'
3055 summary: Create a video playlist
3056 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3057 operationId: addPlaylist
3064 description: successful operation
3074 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3076 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3078 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3081 multipart/form-data:
3086 description: Video playlist display name
3091 description: Video playlist thumbnail file
3095 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3097 description: Video playlist description
3103 - $ref: '#/components/schemas/id'
3104 description: Video channel in which the playlist will be published
3109 contentType: image/jpeg
3111 /video-playlists/{playlistId}:
3113 summary: Get a video playlist
3117 - $ref: '#/components/parameters/playlistId'
3120 description: successful operation
3124 $ref: '#/components/schemas/VideoPlaylist'
3126 summary: Update a video playlist
3127 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3134 description: successful operation
3136 - $ref: '#/components/parameters/playlistId'
3139 multipart/form-data:
3144 description: Video playlist display name
3149 description: Video playlist thumbnail file
3153 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3155 description: Video playlist description
3159 - $ref: '#/components/schemas/id'
3160 description: Video channel in which the playlist will be published
3163 contentType: image/jpeg
3165 summary: Delete a video playlist
3171 - $ref: '#/components/parameters/playlistId'
3174 description: successful operation
3176 /video-playlists/{playlistId}/videos:
3178 summary: 'List videos of a playlist'
3179 operationId: getVideoPlaylistVideos
3184 - $ref: '#/components/parameters/playlistId'
3185 - $ref: '#/components/parameters/start'
3186 - $ref: '#/components/parameters/count'
3189 description: successful operation
3193 $ref: '#/components/schemas/VideoListResponse'
3195 summary: Add a video in a playlist
3196 operationId: addVideoPlaylistVideo
3203 - $ref: '#/components/parameters/playlistId'
3206 description: successful operation
3212 videoPlaylistElement:
3226 - $ref: '#/components/schemas/Video/properties/uuid'
3227 - $ref: '#/components/schemas/Video/properties/id'
3228 description: Video to add in the playlist
3232 description: Start the video at this specific timestamp
3236 description: Stop the video at this specific timestamp
3240 /video-playlists/{playlistId}/videos/reorder:
3242 summary: 'Reorder a playlist'
3243 operationId: reorderVideoPlaylist
3249 - $ref: '#/components/parameters/playlistId'
3252 description: successful operation
3261 description: 'Start position of the element to reorder'
3263 insertAfterPosition:
3265 description: 'New position for the block to reorder, to add the block before the first element'
3269 description: 'How many element from `startPosition` to reorder'
3273 - insertAfterPosition
3275 /video-playlists/{playlistId}/videos/{playlistElementId}:
3277 summary: Update a playlist element
3278 operationId: putVideoPlaylistVideo
3284 - $ref: '#/components/parameters/playlistId'
3285 - $ref: '#/components/parameters/playlistElementId'
3288 description: successful operation
3298 description: Start the video at this specific timestamp
3302 description: Stop the video at this specific timestamp
3304 summary: Delete an element from a playlist
3305 operationId: delVideoPlaylistVideo
3311 - $ref: '#/components/parameters/playlistId'
3312 - $ref: '#/components/parameters/playlistElementId'
3315 description: successful operation
3317 '/users/me/video-playlists/videos-exist':
3319 summary: Check video exists in my playlists
3328 description: The video ids to check
3332 $ref: '#/components/schemas/Video/properties/id'
3335 description: successful operation
3357 '/accounts/{name}/video-channels':
3359 summary: List video channels of an account
3364 - $ref: '#/components/parameters/name'
3367 description: include view statistics for the last 30 days (only if authentified as the account user)
3370 - $ref: '#/components/parameters/start'
3371 - $ref: '#/components/parameters/count'
3372 - $ref: '#/components/parameters/sort'
3375 description: successful operation
3379 $ref: '#/components/schemas/VideoChannelList'
3381 '/accounts/{name}/ratings':
3383 summary: List ratings of an account
3389 - $ref: '#/components/parameters/name'
3390 - $ref: '#/components/parameters/start'
3391 - $ref: '#/components/parameters/count'
3392 - $ref: '#/components/parameters/sort'
3396 description: Optionally filter which ratings to retrieve
3404 description: successful operation
3410 $ref: '#/components/schemas/VideoRating'
3412 '/videos/{id}/comment-threads':
3414 summary: List threads of a video
3418 - $ref: '#/components/parameters/idOrUUID'
3419 - $ref: '#/components/parameters/start'
3420 - $ref: '#/components/parameters/count'
3421 - $ref: '#/components/parameters/commentsSort'
3424 description: successful operation
3428 $ref: '#/components/schemas/CommentThreadResponse'
3430 summary: Create a thread
3436 - $ref: '#/components/parameters/idOrUUID'
3439 description: successful operation
3443 $ref: '#/components/schemas/CommentThreadPostResponse'
3445 description: video does not exist
3454 - $ref: '#/components/schemas/VideoComment/properties/text'
3460 '/videos/{id}/comment-threads/{threadId}':
3462 summary: Get a thread
3466 - $ref: '#/components/parameters/idOrUUID'
3467 - $ref: '#/components/parameters/threadId'
3470 description: successful operation
3474 $ref: '#/components/schemas/VideoCommentThreadTree'
3476 '/videos/{id}/comments/{commentId}':
3478 summary: Reply to a thread of a video
3484 - $ref: '#/components/parameters/idOrUUID'
3485 - $ref: '#/components/parameters/commentId'
3488 description: successful operation
3492 $ref: '#/components/schemas/CommentThreadPostResponse'
3494 description: thread or video does not exist
3503 - $ref: '#/components/schemas/VideoComment/properties/text'
3509 summary: Delete a comment or a reply
3515 - $ref: '#/components/parameters/idOrUUID'
3516 - $ref: '#/components/parameters/commentId'
3519 description: successful operation
3521 description: cannot remove comment of another user
3523 description: comment or video does not exist
3525 description: comment is already deleted
3527 '/videos/{id}/rate':
3529 summary: Like/dislike a video
3535 - $ref: '#/components/parameters/idOrUUID'
3551 description: successful operation
3553 description: video does not exist
3559 summary: Search videos
3560 operationId: searchVideos
3565 allowEmptyValue: false
3567 String to search. If the user can make a remote URI search, and the string is an URI then the
3568 PeerTube instance will fetch the remote object and add it to its database. Then,
3569 you can use the REST API to fetch the complete video information and interact with it.
3572 - $ref: '#/components/parameters/categoryOneOf'
3573 - $ref: '#/components/parameters/isLive'
3574 - $ref: '#/components/parameters/tagsOneOf'
3575 - $ref: '#/components/parameters/tagsAllOf'
3576 - $ref: '#/components/parameters/licenceOneOf'
3577 - $ref: '#/components/parameters/languageOneOf'
3578 - $ref: '#/components/parameters/nsfw'
3579 - $ref: '#/components/parameters/filter'
3580 - $ref: '#/components/parameters/skipCount'
3581 - $ref: '#/components/parameters/start'
3582 - $ref: '#/components/parameters/count'
3583 - $ref: '#/components/parameters/searchTarget'
3584 - $ref: '#/components/parameters/videosSearchSort'
3587 description: Get videos that are published after this date
3593 description: Get videos that are published before this date
3597 - name: originallyPublishedStartDate
3599 description: Get videos that are originally published after this date
3603 - name: originallyPublishedEndDate
3605 description: Get videos that are originally published before this date
3611 description: Get videos that have this minimum duration
3616 description: Get videos that have this maximum duration
3620 'searchTarget === search-index':
3621 $ref: '#/components/callbacks/searchIndex'
3624 description: successful operation
3628 $ref: '#/components/schemas/VideoListResponse'
3630 description: search index unavailable
3632 /search/video-channels:
3636 summary: Search channels
3637 operationId: searchChannels
3643 String to search. If the user can make a remote URI search, and the string is an URI then the
3644 PeerTube instance will fetch the remote object and add it to its database. Then,
3645 you can use the REST API to fetch the complete channel information and interact with it.
3648 - $ref: '#/components/parameters/start'
3649 - $ref: '#/components/parameters/count'
3650 - $ref: '#/components/parameters/searchTarget'
3651 - $ref: '#/components/parameters/sort'
3653 'searchTarget === search-index':
3654 $ref: '#/components/callbacks/searchIndex'
3657 description: successful operation
3661 $ref: '#/components/schemas/VideoChannelList'
3663 description: search index unavailable
3665 /search/video-playlists:
3669 summary: Search playlists
3670 operationId: searchPlaylists
3676 String to search. If the user can make a remote URI search, and the string is an URI then the
3677 PeerTube instance will fetch the remote object and add it to its database. Then,
3678 you can use the REST API to fetch the complete playlist information and interact with it.
3681 - $ref: '#/components/parameters/start'
3682 - $ref: '#/components/parameters/count'
3683 - $ref: '#/components/parameters/searchTarget'
3684 - $ref: '#/components/parameters/sort'
3686 'searchTarget === search-index':
3687 $ref: '#/components/callbacks/searchIndex'
3690 description: successful operation
3702 $ref: '#/components/schemas/VideoPlaylist'
3704 description: search index unavailable
3706 /server/blocklist/accounts:
3710 summary: List account blocks
3715 - $ref: '#/components/parameters/start'
3716 - $ref: '#/components/parameters/count'
3717 - $ref: '#/components/parameters/sort'
3720 description: successful operation
3724 summary: Block an account
3736 example: chocobozzz@example.org
3737 description: account to block, in the form `username@domain`
3742 description: successful operation
3744 description: self-blocking forbidden
3746 '/server/blocklist/accounts/{accountName}':
3750 summary: Unblock an account by its handle
3758 description: account to unblock, in the form `username@domain`
3763 description: successful operation
3765 description: account or account block does not exist
3767 /server/blocklist/servers:
3771 summary: List server blocks
3776 - $ref: '#/components/parameters/start'
3777 - $ref: '#/components/parameters/count'
3778 - $ref: '#/components/parameters/sort'
3781 description: successful operation
3785 summary: Block a server
3798 description: server domain to block
3803 description: successful operation
3805 description: self-blocking forbidden
3807 '/server/blocklist/servers/{host}':
3811 summary: Unblock a server by its domain
3819 description: server domain to unblock
3825 description: successful operation
3827 description: account block does not exist
3829 /server/redundancy/{host}:
3832 - Instance Redundancy
3833 summary: Update a server redundancy policy
3841 description: server domain to mirror
3853 description: allow mirroring of the host's local videos
3858 description: successful operation
3860 description: server is not already known
3862 /server/redundancy/videos:
3866 summary: List videos being mirrored
3867 operationId: getMirroredVideos
3875 description: direction of the mirror
3881 - $ref: '#/components/parameters/start'
3882 - $ref: '#/components/parameters/count'
3883 - $ref: '#/components/parameters/videoRedundanciesSort'
3886 description: successful operation
3892 $ref: '#/components/schemas/VideoRedundancy'
3896 summary: Mirror a video
3897 operationId: putMirroredVideo
3908 $ref: '#/components/schemas/Video/properties/id'
3913 description: successful operation
3915 description: cannot mirror a local video
3917 description: video does not exist
3919 description: video is already mirrored
3921 /server/redundancy/videos/{redundancyId}:
3925 summary: Delete a mirror done on a video
3926 operationId: delMirroredVideo
3931 - name: redundancyId
3934 description: id of an existing redundancy on a video
3939 description: successful operation
3941 description: video redundancy not found
3943 '/feeds/video-comments.{format}':
3947 summary: List comments on videos
3948 operationId: getSyndicatedComments
3953 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3966 description: 'limit listing to a specific video'
3971 description: 'limit listing to a specific account'
3976 description: 'limit listing to a specific account'
3979 - name: videoChannelId
3981 description: 'limit listing to a specific video channel'
3984 - name: videoChannelName
3986 description: 'limit listing to a specific video channel'
3991 description: successful operation
3996 default: 'max-age=900' # 15 min cache
4000 $ref: '#/components/schemas/VideoCommentsForXML'
4003 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4004 application/rss+xml:
4006 $ref: '#/components/schemas/VideoCommentsForXML'
4009 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4012 $ref: '#/components/schemas/VideoCommentsForXML'
4015 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4016 application/atom+xml:
4018 $ref: '#/components/schemas/VideoCommentsForXML'
4021 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4027 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4029 x-summary: field inconsistencies
4032 - videoId filter is mixed with a channel filter
4034 description: video, video channel or account not found
4036 description: accept header unsupported
4038 '/feeds/videos.{format}':
4042 summary: List videos
4043 operationId: getSyndicatedVideos
4048 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4061 description: 'limit listing to a specific account'
4066 description: 'limit listing to a specific account'
4069 - name: videoChannelId
4071 description: 'limit listing to a specific video channel'
4074 - name: videoChannelName
4076 description: 'limit listing to a specific video channel'
4079 - $ref: '#/components/parameters/sort'
4080 - $ref: '#/components/parameters/nsfw'
4081 - $ref: '#/components/parameters/filter'
4084 description: successful operation
4089 default: 'max-age=900' # 15 min cache
4093 $ref: '#/components/schemas/VideosForXML'
4096 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4097 application/rss+xml:
4099 $ref: '#/components/schemas/VideosForXML'
4102 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4105 $ref: '#/components/schemas/VideosForXML'
4108 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4109 application/atom+xml:
4111 $ref: '#/components/schemas/VideosForXML'
4114 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4120 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4122 description: video channel or account not found
4124 description: accept header unsupported
4126 '/feeds/subscriptions.{format}':
4131 summary: List videos of subscriptions tied to a token
4132 operationId: getSyndicatedSubscriptionVideos
4137 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4150 description: limit listing to a specific account
4156 description: private token allowing access
4160 - $ref: '#/components/parameters/sort'
4161 - $ref: '#/components/parameters/nsfw'
4162 - $ref: '#/components/parameters/filter'
4165 description: successful operation
4170 default: 'max-age=900' # 15 min cache
4174 $ref: '#/components/schemas/VideosForXML'
4175 application/rss+xml:
4177 $ref: '#/components/schemas/VideosForXML'
4180 $ref: '#/components/schemas/VideosForXML'
4181 application/atom+xml:
4183 $ref: '#/components/schemas/VideosForXML'
4188 description: accept header unsupported
4194 summary: List plugins
4195 operationId: getPlugins
4208 - $ref: '#/components/parameters/start'
4209 - $ref: '#/components/parameters/count'
4210 - $ref: '#/components/parameters/sort'
4213 description: successful operation
4217 $ref: '#/components/schemas/PluginResponse'
4223 summary: List available plugins
4224 operationId: getAvailablePlugins
4237 - name: currentPeerTubeEngine
4241 - $ref: '#/components/parameters/start'
4242 - $ref: '#/components/parameters/count'
4243 - $ref: '#/components/parameters/sort'
4246 description: successful operation
4250 $ref: '#/components/schemas/PluginResponse'
4252 description: plugin index unavailable
4258 summary: Install a plugin
4259 operationId: addPlugin
4272 example: peertube-plugin-auth-ldap
4275 additionalProperties: false
4282 additionalProperties: false
4285 description: successful operation
4287 description: should have either `npmName` or `path` set
4293 summary: Update a plugin
4294 operationId: updatePlugin
4307 example: peertube-plugin-auth-ldap
4310 additionalProperties: false
4317 additionalProperties: false
4320 description: successful operation
4322 description: should have either `npmName` or `path` set
4324 description: existing plugin not found
4330 summary: Uninstall a plugin
4331 operationId: uninstallPlugin
4343 description: name of the plugin/theme in its package.json
4344 example: peertube-plugin-auth-ldap
4349 description: successful operation
4351 description: existing plugin not found
4357 summary: Get a plugin
4358 operationId: getPlugin
4363 - $ref: '#/components/parameters/npmName'
4366 description: successful operation
4370 $ref: '#/components/schemas/Plugin'
4372 description: plugin not found
4374 /plugins/{npmName}/settings:
4378 summary: Set a plugin's settings
4383 - $ref: '#/components/parameters/npmName'
4392 additionalProperties: true
4395 description: successful operation
4397 description: plugin not found
4399 /plugins/{npmName}/public-settings:
4403 summary: Get a plugin's public settings
4405 - $ref: '#/components/parameters/npmName'
4408 description: successful operation
4413 additionalProperties: true
4415 description: plugin not found
4417 /plugins/{npmName}/registered-settings:
4421 summary: Get a plugin's registered settings
4426 - $ref: '#/components/parameters/npmName'
4429 description: successful operation
4434 additionalProperties: true
4436 description: plugin not found
4439 - url: 'https://peertube2.cpy.re/api/v1'
4440 description: Live Test Server (live data - latest nightly version)
4441 - url: 'https://peertube3.cpy.re/api/v1'
4442 description: Live Test Server (live data - latest RC version)
4443 - url: 'https://peertube.cpy.re/api/v1'
4444 description: Live Test Server (live data - stable version)
4451 description: Offset used to paginate results
4459 description: "Number of items to return"
4469 description: Sort column
4477 description: Plain text search, applied to various parts of the model depending on endpoint
4485 If the administrator enabled search index support, you can override the default search target.
4488 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4489 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4490 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4491 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4492 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4493 * 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
4494 the data from the origin instance API
4504 description: Sort videos by criteria
4520 description: Sort videos by criteria
4535 description: Sort comments by criteria
4545 description: Sort blocklists by criteria
4561 description: Plain text search that will match with user usernames or emails
4568 description: Filter results down to (un)banned users
4575 description: Sort users by criteria
4586 description: Sort abuses by criteria
4593 videoRedundanciesSort:
4597 description: Sort abuses by criteria
4606 description: Sort followers by criteria
4615 description: The username or handle of the account
4618 example: chocobozzz | chocobozzz@example.org
4623 description: The user id
4625 $ref: '#/components/schemas/id'
4630 description: The object id, uuid or short uuid
4633 - $ref: '#/components/schemas/id'
4634 - $ref: '#/components/schemas/UUIDv4'
4635 - $ref: '#/components/schemas/shortUUID'
4640 description: Playlist id
4642 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4644 name: playlistElementId
4647 description: Playlist element id
4649 $ref: '#/components/schemas/id'
4654 description: Abuse id
4656 $ref: '#/components/schemas/Abuse/properties/id'
4658 name: abuseMessageId
4661 description: Abuse message id
4663 $ref: '#/components/schemas/AbuseMessage/properties/id'
4665 name: captionLanguage
4668 description: The caption language
4670 $ref: '#/components/schemas/VideoLanguageSet'
4675 description: The video channel handle
4678 example: my_username | my_username@example.com
4680 name: subscriptionHandle
4683 description: The subscription handle
4686 example: my_username | my_username@example.com
4691 description: The thread id (root comment id)
4698 description: The comment id
4700 $ref: '#/components/schemas/VideoComment/properties/id'
4705 description: whether or not the video is a live
4712 description: category id of the video (see [/videos/categories](#operation/getCategories))
4715 - $ref: '#/components/schemas/VideoCategorySet'
4718 $ref: '#/components/schemas/VideoCategorySet'
4725 description: tag(s) of the video
4739 description: tag(s) of the video, where all should be present in the video
4752 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4755 - $ref: '#/components/schemas/VideoLanguageSet'
4758 $ref: '#/components/schemas/VideoLanguageSet'
4765 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4768 - $ref: '#/components/schemas/VideoLicenceSet'
4771 $ref: '#/components/schemas/VideoLicenceSet'
4778 description: if you don't need the `total` in the response
4789 description: whether to include nsfw videos, if any
4800 Special filters which might require special rights:
4801 * `local` - only videos local to the instance
4802 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4803 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4813 description: list of uris to check if each is part of the user subscriptions
4823 description: name of the plugin/theme on npmjs.com or in its package.json
4826 example: peertube-plugin-auth-ldap
4831 description: job type
4835 - activitypub-follow
4836 - activitypub-http-broadcast
4837 - activitypub-http-fetcher
4838 - activitypub-http-unicast
4844 - activitypub-refresher
4869 Authenticating via OAuth requires the following steps:
4870 - Have an activated account
4871 - [Generate] an access token for that account at `/api/v1/users/token`.
4872 - Make requests with the *Authorization: Bearer <token\>* header
4873 - Profit, depending on the role assigned to the account
4875 Note that the __access token is valid for 1 day__ and is given
4876 along with a __refresh token valid for 2 weeks__.
4878 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4882 tokenUrl: /api/v1/users/token
4885 moderator: Moderator scope
4888 # Resuable core properties
4896 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4897 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4902 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4903 example: 2y84q2MQUMWPbiEcxNXMgC
4906 description: immutable name of the user, used to find or mention its actor
4908 pattern: '/^[a-z0-9._]+$/'
4913 description: immutable name of the channel, used to interact with its actor
4914 example: framasoft_videos
4915 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4926 description: category id of the video (see [/videos/categories](#operation/getCategories))
4928 VideoConstantNumber-Category:
4931 $ref: '#/components/schemas/VideoCategorySet'
4934 example: Science & Technology
4938 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4940 VideoConstantNumber-Licence:
4943 $ref: '#/components/schemas/VideoLicenceSet'
4946 example: Attribution - Share Alike
4950 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4952 VideoConstantString-Language:
4955 $ref: '#/components/schemas/VideoLanguageSet'
4960 VideoPlaylistPrivacySet:
4966 description: Video playlist privacy policy (see [/video-playlists/privacies])
4967 VideoPlaylistPrivacyConstant:
4970 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4974 VideoPlaylistTypeSet:
4979 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4980 VideoPlaylistTypeConstant:
4983 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4994 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4995 VideoPrivacyConstant:
4998 $ref: '#/components/schemas/VideoPrivacySet'
5015 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5022 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5033 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5043 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5047 $ref: '#/components/schemas/AbuseStateSet'
5050 AbusePredefinedReasons:
5063 example: [spamOrMisleading]
5068 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5070 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5072 VideoResolutionConstant:
5073 description: resolutions and their labels for the video
5076 $ref: '#/components/schemas/VideoResolutionSet'
5080 VideoScheduledUpdate:
5083 $ref: '#/components/schemas/VideoPrivacySet'
5087 description: When to update the video
5107 - $ref: '#/components/schemas/ActorImage'
5108 VideoChannelSummary:
5111 $ref: '#/components/schemas/id'
5125 - $ref: '#/components/schemas/ActorImage'
5139 - $ref: '#/components/schemas/Video'
5146 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5147 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5149 $ref: '#/components/schemas/VideoResolutionConstant'
5152 description: Video file size in bytes
5155 description: Direct URL of the torrent file
5159 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5163 description: Direct URL of the video
5167 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5171 description: Frames per second of the video file
5175 description: URL dereferencing the output of ffprobe on the file
5176 VideoStreamingPlaylists:
5181 $ref: '#/components/schemas/id'
5189 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5190 VideoStreamingPlaylists-HLS:
5201 Video files associated to this playlist.
5203 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5205 $ref: '#/components/schemas/VideoFile'
5217 $ref: '#/components/schemas/Video/properties/id'
5219 $ref: '#/components/schemas/Video/properties/uuid'
5221 $ref: '#/components/schemas/Video/properties/name'
5225 description: object id for the video
5227 - $ref: '#/components/schemas/id'
5229 description: universal identifier for the video, that can be used across instances
5231 - $ref: '#/components/schemas/UUIDv4'
5234 - $ref: '#/components/schemas/shortUUID'
5240 example: 2017-10-01T10:52:46.396Z
5241 description: time at which the video object was first drafted
5245 example: 2018-10-01T10:52:46.396Z
5246 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5250 example: 2021-05-04T08:01:01.502Z
5251 description: last time the video's metadata was modified
5252 originallyPublishedAt:
5255 example: 2010-10-01T10:52:46.396Z
5256 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5259 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5260 description: category in which the video is classified
5263 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5264 description: licence under which the video is distributed
5267 - $ref: '#/components/schemas/VideoConstantString-Language'
5268 description: main language used in the video
5271 - $ref: '#/components/schemas/VideoPrivacyConstant'
5272 description: privacy policy used to distribute the video
5276 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5277 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5281 truncated description of the video, written in Markdown.
5282 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5287 description: duration of the video in seconds
5292 description: title of the video
5293 example: What is PeerTube?
5298 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5301 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5304 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5321 - $ref: '#/components/schemas/VideoStateConstant'
5322 description: represents the internal state of the video processing within the PeerTube instance
5326 - $ref: '#/components/schemas/VideoScheduledUpdate'
5334 $ref: '#/components/schemas/AccountSummary'
5336 $ref: '#/components/schemas/VideoChannelSummary'
5345 - $ref: '#/components/schemas/Video'
5350 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5351 description: path at which to get the full description of maximum `10000` characters
5354 description: A text tell the audience how to support the video creator
5355 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5359 $ref: '#/components/schemas/VideoChannel'
5361 $ref: '#/components/schemas/Account'
5363 example: [flowers, gardening]
5381 - https://peertube2.cpy.re/tracker/announce
5382 - wss://peertube2.cpy.re/tracker/socket
5386 $ref: '#/components/schemas/VideoFile'
5388 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5390 - field will be empty
5391 - video files will be found in `streamingPlaylists[].files` field
5395 $ref: '#/components/schemas/VideoStreamingPlaylists'
5397 HLS playlists/manifest files. If HLS is disabled on the server:
5399 - field will be empty
5400 - video files will be found in `files` field
5401 FileRedundancyInformation:
5404 $ref: '#/components/schemas/id'
5429 $ref: '#/components/schemas/id'
5436 $ref: '#/components/schemas/UUIDv4'
5443 $ref: '#/components/schemas/FileRedundancyInformation'
5447 $ref: '#/components/schemas/FileRedundancyInformation'
5448 VideoImportStateConstant:
5456 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5463 additionalProperties: false
5467 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5468 required: [targetUrl]
5471 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5472 required: [magnetUri]
5475 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5476 required: [torrentfile]
5477 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5486 - $ref: '#/components/schemas/id'
5490 description: remote URL where to find the import's source video
5491 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5495 description: magnet URI allowing to resolve the import's source video
5496 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5501 description: Torrent file containing only the video file
5508 - $ref: '#/components/schemas/VideoImportStateConstant'
5524 - $ref: '#/components/schemas/Video'
5534 $ref: '#/components/schemas/VideoImport'
5538 $ref: '#/components/schemas/id'
5541 example: The video is a spam
5545 $ref: '#/components/schemas/AbusePredefinedReasons'
5547 $ref: '#/components/schemas/Account'
5549 $ref: '#/components/schemas/AbuseStateConstant'
5552 example: Decided to ban the server since it spams us regularly
5556 $ref: '#/components/schemas/VideoInfo'
5563 $ref: '#/components/schemas/id'
5574 $ref: '#/components/schemas/AccountSummary'
5578 $ref: '#/components/schemas/id'
5580 $ref: '#/components/schemas/Video/properties/id'
5592 $ref: '#/components/schemas/UUIDv4'
5610 $ref: '#/components/schemas/id'
5612 $ref: '#/components/schemas/UUIDv4'
5615 - $ref: '#/components/schemas/shortUUID'
5638 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5640 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5642 $ref: '#/components/schemas/AccountSummary'
5644 $ref: '#/components/schemas/VideoChannelSummary'
5648 $ref: '#/components/schemas/id'
5655 description: Text of the comment
5657 example: This video is wonderful!
5659 $ref: '#/components/schemas/id'
5663 - $ref: '#/components/schemas/id'
5665 $ref: '#/components/schemas/Video/properties/id'
5680 totalRepliesFromVideoAuthor:
5687 $ref: '#/components/schemas/Account'
5688 VideoCommentThreadTree:
5691 $ref: '#/components/schemas/VideoComment'
5695 $ref: '#/components/schemas/VideoCommentThreadTree'
5699 $ref: '#/components/schemas/VideoConstantString-Language'
5715 $ref: '#/components/schemas/id'
5732 $ref: '#/components/schemas/id'
5737 description: immutable name of the actor, used to find or mention it
5739 - $ref: '#/components/schemas/username'
5743 description: server on which the actor is resident
5744 hostRedundancyAllowed:
5746 description: whether this actor's host allows redundancy of its videos
5750 description: number of actors subscribed to by this actor, as seen by this instance
5754 description: number of followers of this actor, as seen by this instance
5762 $ref: '#/components/schemas/ActorImage'
5765 - $ref: '#/components/schemas/Actor'
5768 description: object id for the user tied to this account
5770 - $ref: '#/components/schemas/User/properties/id'
5773 description: editable name of the account, displayed in its representations
5778 description: text or bio displayed on the account's profile
5784 description: timestamp within the video, in seconds
5851 allowedForCurrentIP:
5853 requiresEmailVerification:
5871 $ref: '#/components/schemas/VideoResolutionSet'
5956 example: 16810141515
6065 requiresEmailVerification:
6080 description: Settings that apply to new users, if registration is enabled
6084 example: 16810141515
6090 description: Settings pertaining to transcoding jobs
6094 allowAdditionalExtensions:
6096 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6099 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6102 description: Amount of threads used by ffmpeg for 1 transcoding job
6105 description: Amount of transcoding jobs to execute in parallel
6111 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6114 description: Resolutions to transcode _new videos_ to
6134 description: WebTorrent-specific settings
6140 description: HLS-specific settings
6190 $ref: '#/components/schemas/id'
6192 $ref: '#/components/schemas/Actor'
6194 $ref: '#/components/schemas/Actor'
6197 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6210 PredefinedAbuseReasons:
6211 description: Reason categories that help triage reports
6229 $ref: '#/components/schemas/id'
6241 - activitypub-http-unicast
6242 - activitypub-http-broadcast
6243 - activitypub-http-fetcher
6244 - activitypub-follow
6250 - activitypub-refresher
6254 additionalProperties: true
6257 additionalProperties: true
6273 $ref: '#/components/schemas/id'
6278 $ref: '#/components/schemas/id'
6279 VideoUploadRequestCommon:
6282 description: Video name
6284 example: What is PeerTube?
6288 description: Channel id that will contain this video
6293 $ref: '#/components/schemas/VideoPrivacySet'
6295 $ref: '#/components/schemas/VideoCategorySet'
6297 $ref: '#/components/schemas/VideoLicenceSet'
6299 $ref: '#/components/schemas/VideoLanguageSet'
6301 description: Video description
6304 **[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)**
6306 description: Whether or not we wait transcoding before publish the video
6309 description: A text tell the audience how to support the video creator
6310 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6313 description: Whether or not this video contains sensitive content
6316 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6329 description: Enable or disable comments for this video
6332 description: Enable or disable downloading for this video
6334 originallyPublishedAt:
6335 description: Date when the content was originally published
6339 $ref: '#/components/schemas/VideoScheduledUpdate'
6341 description: Video thumbnail file
6345 description: Video preview file
6351 VideoUploadRequestLegacy:
6353 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6359 description: Video file
6362 VideoUploadRequestResumable:
6364 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6370 description: Video filename including extension
6373 example: what_is_peertube.mp4
6375 description: Video thumbnail file
6379 description: Video preview file
6382 VideoUploadResponse:
6388 $ref: '#/components/schemas/Video/properties/id'
6390 $ref: '#/components/schemas/Video/properties/uuid'
6392 $ref: '#/components/schemas/Video/properties/shortUUID'
6393 CommentThreadResponse:
6402 $ref: '#/components/schemas/VideoComment'
6403 CommentThreadPostResponse:
6406 $ref: '#/components/schemas/VideoComment'
6416 $ref: '#/components/schemas/Video'
6420 $ref: '#/components/schemas/Account'
6423 description: Automatically start playing the upcoming video after the currently playing video
6424 autoPlayNextVideoPlaylist:
6426 description: Automatically start playing the video on the playlist after the currently playing video
6429 description: Automatically start playing the video on the watch page
6439 description: The user email
6442 description: Has the user confirmed their email address?
6445 - $ref: '#/components/schemas/id'
6449 description: Auth plugin to use to authenticate the user
6453 noInstanceConfigWarningModal:
6455 noAccountSetupWarningModal:
6460 $ref: '#/components/schemas/NSFWPolicy'
6462 $ref: '#/components/schemas/UserRole'
6471 description: Theme enabled by this user
6473 $ref: '#/components/schemas/username'
6477 $ref: '#/components/schemas/VideoChannel'
6480 description: The user video quota in bytes
6484 description: The user daily video quota in bytes
6488 description: Enable P2P in the player
6491 - $ref: '#/components/schemas/User'
6493 # optionally present fields: they require WITH_STATS scope
6496 description: Count of videos published
6499 description: Count of reports/abuses of which the user is a target
6500 abusesAcceptedCount:
6502 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6505 description: Count of reports/abuses created by the user
6508 description: Count of comments published
6512 $ref: '#/components/schemas/username'
6514 $ref: '#/components/schemas/password'
6518 description: The user email
6521 description: The user video quota in bytes
6525 description: The user daily video quota in bytes
6528 $ref: '#/components/schemas/usernameChannel'
6530 $ref: '#/components/schemas/UserRole'
6532 $ref: '#/components/schemas/UserAdminFlags'
6543 description: The updated email of the user
6545 - $ref: '#/components/schemas/User/properties/email'
6548 description: Set the email as verified
6551 description: The updated video quota of the user in bytes
6554 description: The updated daily video quota of the user in bytes
6558 description: The auth plugin to use to authenticate the user
6559 example: 'peertube-plugin-auth-saml2'
6561 $ref: '#/components/schemas/UserRole'
6563 $ref: '#/components/schemas/UserAdminFlags'
6565 # see shared/models/users/user-update-me.model.ts:
6568 $ref: '#/components/schemas/password'
6570 $ref: '#/components/schemas/password'
6572 description: new email used for login and service communications
6574 - $ref: '#/components/schemas/User/properties/email'
6577 description: new name of the user in its representations
6582 description: new NSFW display policy
6589 description: whether to enable P2P in the player or not
6592 description: new preference regarding playing videos automatically
6595 description: new preference regarding playing following videos automatically
6596 autoPlayNextVideoPlaylist:
6598 description: new preference regarding playing following playlist videos automatically
6599 videosHistoryEnabled:
6601 description: whether to keep track of watched history or not
6606 description: list of languages to filter videos down to
6609 noInstanceConfigWarningModal:
6611 noAccountSetupWarningModal:
6618 $ref: '#/components/schemas/id'
6625 description: Rating of the video
6632 $ref: '#/components/schemas/Video'
6639 description: Rating of the video
6646 description: immutable name of the user, used to find or mention its actor
6648 - $ref: '#/components/schemas/username'
6650 $ref: '#/components/schemas/password'
6654 description: email of the user, used for login or service communications
6657 description: editable name of the user, displayed in its representations
6662 description: channel base information used to create the first channel of the user
6665 $ref: '#/components/schemas/usernameChannel'
6667 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6677 pattern: /^[a-z0-9]$/
6680 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6683 pattern: /^[a-zA-Z0-9]$/
6686 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6687 OAuthToken-password:
6689 - $ref: '#/components/schemas/OAuthClient'
6699 $ref: '#/components/schemas/User/properties/username'
6701 $ref: '#/components/schemas/password'
6708 OAuthToken-refresh_token:
6710 - $ref: '#/components/schemas/OAuthClient'
6721 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6730 # GET/POST/PUT properties
6733 description: editable name of the channel, displayed in its representations
6734 example: Videos of Framasoft
6739 example: Videos made with <3 by Framasoft
6744 description: text shown by default on all videos of this channel, to tell the audience how to support it
6745 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6748 # GET-only properties
6752 - $ref: '#/components/schemas/id'
6768 $ref: '#/components/schemas/UUIDv4'
6771 - $ref: '#/components/schemas/VideoChannel'
6774 description: username of the channel to create
6776 - $ref: '#/components/schemas/usernameChannel'
6782 - $ref: '#/components/schemas/VideoChannel'
6784 bulkVideosSupportUpdate:
6786 description: Update the support field for all videos of this channel
6796 - $ref: '#/components/schemas/VideoChannel'
6797 - $ref: '#/components/schemas/Actor'
6802 name: 'media:peerLink'
6811 - application/x-bittorrent
6817 name: 'media:content'
6848 VideoCommentsForXML:
6883 description: video watch page URL
6886 description: video canonical URL
6890 description: video publication date
6893 description: video description
6896 description: video description
6899 description: publisher user name
6902 description: video category (MRSS)
6905 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6920 description: video embed path, relative to the canonical URL domain (MRSS)
6929 description: video watch path, relative to the canonical URL domain (MRSS)
6950 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6951 'media:description':
6958 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6961 description: main streamable file for the video
6971 - application/x-bittorrent
6980 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)
6983 - $ref: '#/components/schemas/MRSSPeerLink'
6984 - $ref: '#/components/schemas/MRSSGroupContent'
6985 NotificationSettingValue:
7002 $ref: '#/components/schemas/id'
7006 Notification type, following the `UserNotificationType` enum:
7008 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7010 - `2` NEW_COMMENT_ON_MY_VIDEO
7012 - `3` NEW_ABUSE_FOR_MODERATORS
7014 - `4` BLACKLIST_ON_MY_VIDEO
7016 - `5` UNBLACKLIST_ON_MY_VIDEO
7018 - `6` MY_VIDEO_PUBLISHED
7020 - `7` MY_VIDEO_IMPORT_SUCCESS
7022 - `8` MY_VIDEO_IMPORT_ERROR
7024 - `9` NEW_USER_REGISTRATION
7028 - `11` COMMENT_MENTION
7030 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7032 - `13` NEW_INSTANCE_FOLLOWER
7034 - `14` AUTO_INSTANCE_FOLLOWING
7040 - $ref: '#/components/schemas/VideoInfo'
7044 $ref: '#/components/schemas/ActorInfo'
7050 $ref: '#/components/schemas/id'
7053 $ref: '#/components/schemas/VideoInfo'
7058 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7068 $ref: '#/components/schemas/id'
7072 $ref: '#/components/schemas/VideoInfo'
7074 $ref: '#/components/schemas/ActorInfo'
7080 $ref: '#/components/schemas/id'
7083 - $ref: '#/components/schemas/VideoInfo'
7089 $ref: '#/components/schemas/id'
7092 - $ref: '#/components/schemas/VideoInfo'
7096 - $ref: '#/components/schemas/ActorInfo'
7102 $ref: '#/components/schemas/id'
7104 $ref: '#/components/schemas/ActorInfo'
7132 NotificationListResponse:
7141 $ref: '#/components/schemas/Notification'
7146 example: peertube-plugin-auth-ldap
7174 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7177 additionalProperties: true
7193 $ref: '#/components/schemas/Plugin'
7200 description: User can stream multiple times in a permanent live
7209 description: RTMP stream key to use to stream into this live video
7213 description: User can stream multiple times in a permanent live
7220 'https://search.example.org/api/v1/search/videos':
7222 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7225 description: successful operation
7229 $ref: '#/components/schemas/VideoListResponse'