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")
421 summary: List accounts
422 operationId: getAccounts
424 - $ref: '#/components/parameters/start'
425 - $ref: '#/components/parameters/count'
426 - $ref: '#/components/parameters/sort'
429 description: successful operation
435 $ref: '#/components/schemas/Account'
441 summary: Get instance public configuration
442 operationId: getConfig
445 description: successful operation
449 $ref: '#/components/schemas/ServerConfig'
452 externalValue: https://peertube2.cpy.re/api/v1/config
456 summary: Get instance "About" information
457 operationId: getAbout
462 description: successful operation
466 $ref: '#/components/schemas/ServerConfigAbout'
469 externalValue: https://peertube2.cpy.re/api/v1/config/about
473 summary: Get instance runtime configuration
474 operationId: getCustomConfig
482 description: successful operation
486 $ref: '#/components/schemas/ServerConfigCustom'
488 summary: Set instance runtime configuration
489 operationId: putCustomConfig
497 description: successful operation
499 x-summary: field inconsistencies
502 - the emailer is disabled and the instance is open to registrations
503 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
505 summary: Delete instance runtime configuration
506 operationId: delCustomConfig
514 description: successful operation
516 /custom-pages/homepage/instance:
518 summary: Get instance custom homepage
523 description: No homepage set
525 description: successful operation
529 $ref: '#/components/schemas/CustomHomepage'
531 summary: Set instance custom homepage
545 description: content of the homepage, that will be injected in the client
548 description: successful operation
552 summary: List instance jobs
563 description: The state of the job ('' for for no filter)
573 - $ref: '#/components/parameters/jobType'
574 - $ref: '#/components/parameters/start'
575 - $ref: '#/components/parameters/count'
576 - $ref: '#/components/parameters/sort'
579 description: successful operation
592 $ref: '#/components/schemas/Job'
598 summary: List instances following the server
600 - $ref: '#/components/parameters/followState'
601 - $ref: '#/components/parameters/actorType'
602 - $ref: '#/components/parameters/start'
603 - $ref: '#/components/parameters/count'
604 - $ref: '#/components/parameters/sort'
607 description: successful operation
619 $ref: '#/components/schemas/Follow'
621 '/server/followers/{nameWithHost}':
623 summary: Remove or reject a follower to your server
633 description: The remote actor handle to remove from your followers
639 description: successful operation
641 description: follower not found
643 '/server/followers/{nameWithHost}/reject':
645 summary: Reject a pending follower to your server
655 description: The remote actor handle to remove from your followers
661 description: successful operation
663 description: follower not found
665 '/server/followers/{nameWithHost}/accept':
667 summary: Accept a pending follower to your server
677 description: The remote actor handle to remove from your followers
683 description: successful operation
685 description: follower not found
691 summary: List instances followed by the server
693 - $ref: '#/components/parameters/followState'
694 - $ref: '#/components/parameters/actorType'
695 - $ref: '#/components/parameters/start'
696 - $ref: '#/components/parameters/count'
697 - $ref: '#/components/parameters/sort'
700 description: successful operation
712 $ref: '#/components/schemas/Follow'
719 summary: Follow a list of servers
722 description: successful operation
724 description: cannot follow a non-HTTPS server
738 '/server/following/{host}':
740 summary: Unfollow a server
750 description: The host to unfollow
756 description: successful operation
758 description: host not found
762 summary: Create a user
771 description: user created
775 $ref: '#/components/schemas/AddUserResponse'
781 id: '$response.body#/user/id'
786 id: '$response.body#/user/id'
791 id: '$response.body#/user/id'
793 description: insufficient authority to create an admin or moderator
798 $ref: '#/components/schemas/AddUser'
800 If the smtp server is configured, you can leave the password empty and an email will be sent
801 asking the user to set it first.
805 operationId: getUsers
812 - $ref: '#/components/parameters/usersSearch'
813 - $ref: '#/components/parameters/usersBlocked'
814 - $ref: '#/components/parameters/start'
815 - $ref: '#/components/parameters/count'
816 - $ref: '#/components/parameters/usersSort'
819 description: successful operation
825 $ref: '#/components/schemas/User'
829 - $ref: '#/components/parameters/id'
831 summary: Delete a user
840 description: successful operation
851 description: include statistics about the user (only available as a moderator/admin)
856 x-summary: successful operation
858 As an admin/moderator, you can request a response augmented with statistics about the user's
859 moderation relations and videos usage, by using the `withStats` parameter.
864 - $ref: '#/components/schemas/User'
865 - $ref: '#/components/schemas/UserWithStats'
867 summary: Update a user
875 description: successful operation
880 $ref: '#/components/schemas/UpdateUser'
883 /oauth-clients/local:
885 summary: Login prerequisite
886 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
887 operationId: getOAuthClient
892 description: successful operation
896 $ref: '#/components/schemas/OAuthClient'
898 UseOAuthClientToLogin:
899 operationId: getOAuthToken
901 client_id: '$response.body#/client_id'
902 client_secret: '$response.body#/client_secret'
906 API="https://peertube2.cpy.re/api/v1"
909 curl -s "$API/oauth-clients/local"
914 operationId: getOAuthToken
915 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
920 application/x-www-form-urlencoded:
923 - $ref: '#/components/schemas/OAuthToken-password'
924 - $ref: '#/components/schemas/OAuthToken-refresh_token'
926 propertyName: grant_type
928 password: '#/components/schemas/OAuthToken-password'
929 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
932 description: successful operation
943 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
944 description: valid for 1 day
947 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
948 description: valid for 2 weeks
953 refresh_token_expires_in:
958 x-summary: client or credentials are invalid
960 Disambiguate via `type`:
961 - `invalid_client` for an unmatched `client_id`
962 - `invalid_grant` for unmatched credentials
964 x-summary: token expired
966 Disambiguate via `type`:
967 - default value for a regular authentication failure
968 - `invalid_token` for an expired token
973 API="https://peertube2.cpy.re/api/v1"
974 USERNAME="<your_username>"
975 PASSWORD="<your_password>"
978 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
979 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
980 curl -s "$API/users/token" \
981 --data client_id="$client_id" \
982 --data client_secret="$client_secret" \
983 --data grant_type=password \
984 --data username="$USERNAME" \
985 --data password="$PASSWORD" \
986 | jq -r ".access_token"
991 description: Revokes your access token and its associated refresh token, destroying your current session.
992 operationId: revokeOAuthToken
999 description: successful operation
1003 summary: Register a user
1004 operationId: registerUser
1010 description: successful operation
1015 $ref: '#/components/schemas/RegisterUser'
1018 /users/{id}/verify-email:
1020 summary: Verify a user
1021 operationId: verifyUser
1023 Following a user registration, the new user will receive an email asking to click a link
1024 containing a secret.
1029 - $ref: '#/components/parameters/id'
1042 - verificationString
1045 description: successful operation
1047 description: invalid verification string
1049 description: user not found
1051 /users/ask-send-verify-email:
1053 summary: Resend user verification link
1054 operationId: resendEmailToVerifyUser
1060 description: successful operation
1064 summary: Get my user information
1065 operationId: getUserInfo
1073 description: successful operation
1079 $ref: '#/components/schemas/User'
1081 summary: Update my user information
1082 operationId: putUserInfo
1090 description: successful operation
1095 $ref: '#/components/schemas/UpdateMe'
1098 /users/me/videos/imports:
1100 summary: Get video imports of my user
1108 - $ref: '#/components/parameters/start'
1109 - $ref: '#/components/parameters/count'
1110 - $ref: '#/components/parameters/sort'
1113 description: successful operation
1117 $ref: '#/components/schemas/VideoImportsList'
1119 /users/me/video-quota-used:
1121 summary: Get my user used quota
1129 description: successful operation
1137 description: The user video quota used so far in bytes
1138 example: 16810141515
1139 videoQuotaUsedDaily:
1141 description: The user video quota used today in bytes
1144 '/users/me/videos/{videoId}/rating':
1146 summary: Get rate of my user for a video
1156 description: The video id
1158 $ref: '#/components/schemas/Video/properties/id'
1161 description: successful operation
1165 $ref: '#/components/schemas/GetMeVideoRating'
1169 summary: Get videos of my user
1177 - $ref: '#/components/parameters/start'
1178 - $ref: '#/components/parameters/count'
1179 - $ref: '#/components/parameters/sort'
1182 description: successful operation
1186 $ref: '#/components/schemas/VideoListResponse'
1188 /users/me/subscriptions:
1190 summary: Get my user subscriptions
1197 - $ref: '#/components/parameters/start'
1198 - $ref: '#/components/parameters/count'
1199 - $ref: '#/components/parameters/sort'
1202 description: successful operation
1206 $ref: '#/components/schemas/VideoChannelList'
1210 summary: Add subscription to my user
1223 description: uri of the video channels to subscribe to
1229 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1232 description: successful operation
1234 /users/me/subscriptions/exist:
1236 summary: Get if subscriptions exist for my user
1243 - $ref: '#/components/parameters/subscriptionsUris'
1246 description: successful operation
1252 /users/me/subscriptions/videos:
1254 summary: List videos of subscriptions of my user
1262 - $ref: '#/components/parameters/categoryOneOf'
1263 - $ref: '#/components/parameters/isLive'
1264 - $ref: '#/components/parameters/tagsOneOf'
1265 - $ref: '#/components/parameters/tagsAllOf'
1266 - $ref: '#/components/parameters/licenceOneOf'
1267 - $ref: '#/components/parameters/languageOneOf'
1268 - $ref: '#/components/parameters/nsfw'
1269 - $ref: '#/components/parameters/filter'
1270 - $ref: '#/components/parameters/skipCount'
1271 - $ref: '#/components/parameters/start'
1272 - $ref: '#/components/parameters/count'
1273 - $ref: '#/components/parameters/videosSort'
1276 description: successful operation
1280 $ref: '#/components/schemas/VideoListResponse'
1282 '/users/me/subscriptions/{subscriptionHandle}':
1284 summary: Get subscription of my user
1291 - $ref: '#/components/parameters/subscriptionHandle'
1294 description: successful operation
1298 $ref: '#/components/schemas/VideoChannel'
1300 summary: Delete subscription of my user
1307 - $ref: '#/components/parameters/subscriptionHandle'
1310 description: successful operation
1312 /users/me/notifications:
1314 summary: List my notifications
1322 description: only list unread notifications
1325 - $ref: '#/components/parameters/start'
1326 - $ref: '#/components/parameters/count'
1327 - $ref: '#/components/parameters/sort'
1330 description: successful operation
1334 $ref: '#/components/schemas/NotificationListResponse'
1336 /users/me/notifications/read:
1338 summary: Mark notifications as read by their id
1351 description: ids of the notifications to mark as read
1358 description: successful operation
1360 /users/me/notifications/read-all:
1362 summary: Mark all my notification as read
1369 description: successful operation
1371 /users/me/notification-settings:
1373 summary: Update my notification settings
1384 newVideoFromSubscription:
1385 $ref: '#/components/schemas/NotificationSettingValue'
1386 newCommentOnMyVideo:
1387 $ref: '#/components/schemas/NotificationSettingValue'
1389 $ref: '#/components/schemas/NotificationSettingValue'
1390 videoAutoBlacklistAsModerator:
1391 $ref: '#/components/schemas/NotificationSettingValue'
1393 $ref: '#/components/schemas/NotificationSettingValue'
1395 $ref: '#/components/schemas/NotificationSettingValue'
1396 myVideoImportFinished:
1397 $ref: '#/components/schemas/NotificationSettingValue'
1399 $ref: '#/components/schemas/NotificationSettingValue'
1400 newUserRegistration:
1401 $ref: '#/components/schemas/NotificationSettingValue'
1403 $ref: '#/components/schemas/NotificationSettingValue'
1404 newInstanceFollower:
1405 $ref: '#/components/schemas/NotificationSettingValue'
1406 autoInstanceFollowing:
1407 $ref: '#/components/schemas/NotificationSettingValue'
1410 description: successful operation
1412 /users/me/history/videos:
1414 summary: List watched videos history
1420 - $ref: '#/components/parameters/start'
1421 - $ref: '#/components/parameters/count'
1422 - $ref: '#/components/parameters/search'
1425 description: successful operation
1429 $ref: '#/components/schemas/VideoListResponse'
1431 /users/me/history/videos/remove:
1433 summary: Clear video history
1440 multipart/form-data:
1445 description: history before this date will be deleted
1450 description: successful operation
1452 /users/me/avatar/pick:
1454 summary: Update my user avatar
1461 description: successful operation
1468 $ref: '#/components/schemas/ActorImage'
1470 description: image file too large
1472 X-File-Maximum-Size:
1476 description: Maximum file size for the avatar
1479 multipart/form-data:
1484 description: The file to upload
1489 contentType: image/png, image/jpeg
1493 summary: Delete my avatar
1500 description: successful operation
1504 summary: List video ownership changes
1506 - Video Ownership Change
1511 description: successful operation
1513 '/videos/ownership/{id}/accept':
1515 summary: Accept ownership change request
1517 - Video Ownership Change
1521 - $ref: '#/components/parameters/idOrUUID'
1524 description: successful operation
1526 description: cannot terminate an ownership change of another user
1528 description: video owneship change not found
1530 '/videos/ownership/{id}/refuse':
1532 summary: Refuse ownership change request
1534 - Video Ownership Change
1538 - $ref: '#/components/parameters/idOrUUID'
1541 description: successful operation
1543 description: cannot terminate an ownership change of another user
1545 description: video owneship change not found
1547 '/videos/{id}/give-ownership':
1549 summary: Request ownership change
1551 - Video Ownership Change
1555 - $ref: '#/components/parameters/idOrUUID'
1559 application/x-www-form-urlencoded:
1569 description: successful operation
1571 description: changing video ownership to a remote account is not supported yet
1573 description: video not found
1577 summary: List videos
1578 operationId: getVideos
1582 - $ref: '#/components/parameters/categoryOneOf'
1583 - $ref: '#/components/parameters/isLive'
1584 - $ref: '#/components/parameters/tagsOneOf'
1585 - $ref: '#/components/parameters/tagsAllOf'
1586 - $ref: '#/components/parameters/licenceOneOf'
1587 - $ref: '#/components/parameters/languageOneOf'
1588 - $ref: '#/components/parameters/nsfw'
1589 - $ref: '#/components/parameters/filter'
1590 - $ref: '#/components/parameters/skipCount'
1591 - $ref: '#/components/parameters/start'
1592 - $ref: '#/components/parameters/count'
1593 - $ref: '#/components/parameters/videosSort'
1596 description: successful operation
1600 $ref: '#/components/schemas/VideoListResponse'
1604 summary: List available video categories
1605 operationId: getCategories
1610 description: successful operation
1619 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1623 summary: List available video licences
1624 operationId: getLicences
1629 description: successful operation
1638 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1642 summary: List available video languages
1643 operationId: getLanguages
1648 description: successful operation
1657 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1661 summary: List available video privacy policies
1662 operationId: getPrivacyPolicies
1667 description: successful operation
1676 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1680 summary: Update a video
1681 operationId: putVideo
1687 - $ref: '#/components/parameters/idOrUUID'
1690 description: successful operation
1693 multipart/form-data:
1698 description: Video thumbnail file
1702 description: Video preview file
1706 $ref: '#/components/schemas/VideoCategorySet'
1708 $ref: '#/components/schemas/VideoLicenceSet'
1710 $ref: '#/components/schemas/VideoLanguageSet'
1712 $ref: '#/components/schemas/VideoPrivacySet'
1714 description: Video description
1717 description: Whether or not we wait transcoding before publish the video
1720 description: A text tell the audience how to support the video creator
1721 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1724 description: Whether or not this video contains sensitive content
1727 description: Video name
1732 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1741 description: Enable or disable comments for this video
1743 originallyPublishedAt:
1744 description: Date when the content was originally published
1748 $ref: '#/components/schemas/VideoScheduledUpdate'
1751 contentType: image/jpeg
1753 contentType: image/jpeg
1755 summary: Get a video
1756 operationId: getVideo
1760 - $ref: '#/components/parameters/idOrUUID'
1763 description: successful operation
1767 $ref: '#/components/schemas/VideoDetails'
1769 summary: Delete a video
1770 operationId: delVideo
1776 - $ref: '#/components/parameters/idOrUUID'
1779 description: successful operation
1781 '/videos/{id}/description':
1783 summary: Get complete video description
1784 operationId: getVideoDesc
1788 - $ref: '#/components/parameters/idOrUUID'
1791 description: successful operation
1800 **[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)**
1802 '/videos/{id}/views':
1804 summary: Add a view to a video
1808 - $ref: '#/components/parameters/idOrUUID'
1811 description: successful operation
1813 '/videos/{id}/watching':
1815 summary: Set watching progress of a video
1821 - $ref: '#/components/parameters/idOrUUID'
1826 $ref: '#/components/schemas/UserWatchingVideo'
1830 description: successful operation
1834 summary: Upload a video
1835 description: Uses a single request to upload a video.
1836 operationId: uploadLegacy
1844 description: successful operation
1848 $ref: '#/components/schemas/VideoUploadResponse'
1850 description: video didn't pass upload filter
1852 description: upload has timed out
1854 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1856 X-File-Maximum-Size:
1860 description: Maximum file size for the video
1862 description: video type unsupported
1864 description: video unreadable
1867 multipart/form-data:
1869 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1872 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1874 contentType: image/jpeg
1876 contentType: image/jpeg
1881 USERNAME="<your_username>"
1882 PASSWORD="<your_password>"
1883 FILE_PATH="<your_file_path>"
1884 CHANNEL_ID="<your_channel_id>"
1886 API="https://peertube2.cpy.re/api/v1"
1889 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1890 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1891 token=$(curl -s "$API/users/token" \
1892 --data client_id="$client_id" \
1893 --data client_secret="$client_secret" \
1894 --data grant_type=password \
1895 --data username="$USERNAME" \
1896 --data password="$PASSWORD" \
1897 | jq -r ".access_token")
1900 curl -s "$API/videos/upload" \
1901 -H "Authorization: Bearer $token" \
1903 --form videofile=@"$FILE_PATH" \
1904 --form channelId=$CHANNEL_ID \
1907 /videos/upload-resumable:
1909 summary: Initialize the resumable upload of a video
1910 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1911 operationId: uploadResumableInit
1918 - name: X-Upload-Content-Length
1924 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1925 - name: X-Upload-Content-Type
1932 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1937 $ref: '#/components/schemas/VideoUploadRequestResumable'
1940 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1942 description: created
1948 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1954 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1956 description: video type unsupported
1958 summary: Send chunk for the resumable upload of a video
1959 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
1960 operationId: uploadResumable
1971 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1972 not valid anymore and you need to initialize a new upload.
1975 - name: Content-Range
1979 example: bytes 0-262143/2469036
1982 Specifies the bytes in the file that the request is uploading.
1984 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1985 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1986 - name: Content-Length
1993 Size of the chunk that the request is sending.
1995 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)
1996 doesn't mandate for chunks to have the same size throughout the upload sequence.
1998 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1999 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2002 application/octet-stream:
2008 description: last chunk received
2016 $ref: '#/components/schemas/VideoUploadResponse'
2018 description: resume incomplete
2023 example: bytes=0-262143
2029 description: video didn't pass upload filter
2031 description: video file too large, due to quota or max body size limit set by the reverse-proxy
2033 description: video unreadable
2035 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2036 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2037 operationId: uploadResumableCancel
2048 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2049 not valid anymore and the upload session has already been deleted with its data ;-)
2052 - name: Content-Length
2060 description: upload cancelled
2069 summary: Import a video
2070 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2071 operationId: importVideo
2079 multipart/form-data:
2081 $ref: '#/components/schemas/VideoCreateImport'
2084 contentType: application/x-bittorrent
2086 contentType: image/jpeg
2088 contentType: image/jpeg
2091 description: successful operation
2095 $ref: '#/components/schemas/VideoUploadResponse'
2097 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2099 description: video didn't pass pre-import filter
2101 description: HTTP or Torrent/magnetURI import not enabled
2105 summary: Create a live
2106 operationId: addLive
2114 description: successful operation
2118 $ref: '#/components/schemas/VideoUploadResponse'
2120 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2123 multipart/form-data:
2128 description: Channel id that will contain this live video
2133 description: User can stream multiple times in a permanent live
2136 description: Live video/replay thumbnail file
2140 description: Live video/replay preview file
2144 $ref: '#/components/schemas/VideoPrivacySet'
2146 $ref: '#/components/schemas/VideoCategorySet'
2148 $ref: '#/components/schemas/VideoLicenceSet'
2150 $ref: '#/components/schemas/VideoLanguageSet'
2152 description: Live video/replay description
2155 description: A text tell the audience how to support the creator
2156 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2159 description: Whether or not this live video/replay contains sensitive content
2162 description: Live video/replay name
2167 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2176 description: Enable or disable comments for this live video/replay
2179 description: Enable or disable downloading for the replay of this live
2186 contentType: image/jpeg
2188 contentType: image/jpeg
2192 summary: Get information about a live
2193 operationId: getLiveId
2200 - $ref: '#/components/parameters/idOrUUID'
2203 description: successful operation
2207 $ref: '#/components/schemas/LiveVideoResponse'
2209 summary: Update information about a live
2210 operationId: updateLiveId
2217 - $ref: '#/components/parameters/idOrUUID'
2222 $ref: '#/components/schemas/LiveVideoUpdate'
2225 description: successful operation
2227 description: bad parameters or trying to update a live that has already started
2229 description: trying to save replay of the live but saving replay is not enabled on the instance
2233 summary: List my abuses
2234 operationId: getMyAbuses
2243 description: only list the report with this id
2249 $ref: '#/components/schemas/AbuseStateSet'
2250 - $ref: '#/components/parameters/abusesSort'
2251 - $ref: '#/components/parameters/start'
2252 - $ref: '#/components/parameters/count'
2255 description: successful operation
2267 $ref: '#/components/schemas/Abuse'
2271 summary: List abuses
2272 operationId: getAbuses
2282 description: only list the report with this id
2285 - name: predefinedReason
2287 description: predefined reason the listed reports should contain
2289 $ref: '#/components/schemas/PredefinedAbuseReasons'
2292 description: plain search that will match with video titles, reporter names and more
2298 $ref: '#/components/schemas/AbuseStateSet'
2299 - name: searchReporter
2301 description: only list reports of a specific reporter
2304 - name: searchReportee
2305 description: only list reports of a specific reportee
2311 description: only list reports of a specific video
2314 - name: searchVideoChannel
2316 description: only list reports of a specific video channel
2321 description: only list blacklisted or deleted videos
2329 description: only list account, comment or video reports
2336 - $ref: '#/components/parameters/start'
2337 - $ref: '#/components/parameters/count'
2338 - $ref: '#/components/parameters/abusesSort'
2341 description: successful operation
2353 $ref: '#/components/schemas/Abuse'
2355 summary: Report an abuse
2368 description: Reason why the user reports this video
2373 $ref: '#/components/schemas/PredefinedAbuseReasons'
2378 description: Video id to report
2380 - $ref: '#/components/schemas/Video/properties/id'
2384 description: Timestamp in the video that marks the beginning of the report
2389 description: Timestamp in the video that marks the ending of the report
2395 description: Comment id to report
2397 - $ref: '#/components/schemas/VideoComment/properties/id'
2402 description: Account id to report
2408 description: successful operation
2418 $ref: '#/components/schemas/id'
2420 description: incorrect request parameters
2422 '/abuses/{abuseId}':
2424 summary: Update an abuse
2432 - $ref: '#/components/parameters/abuseId'
2440 $ref: '#/components/schemas/AbuseStateSet'
2443 description: Update the report comment visible only to the moderation team
2448 description: successful operation
2450 description: abuse not found
2454 summary: Delete an abuse
2460 - $ref: '#/components/parameters/abuseId'
2463 description: successful operation
2465 description: block not found
2467 '/abuses/{abuseId}/messages':
2469 summary: List messages of an abuse
2475 - $ref: '#/components/parameters/abuseId'
2478 description: successful operation
2490 $ref: '#/components/schemas/AbuseMessage'
2492 summary: Add message to an abuse
2498 - $ref: '#/components/parameters/abuseId'
2507 description: Message to send
2515 description: successful operation
2517 description: incorrect request parameters
2519 '/abuses/{abuseId}/messages/{abuseMessageId}':
2521 summary: Delete an abuse message
2527 - $ref: '#/components/parameters/abuseId'
2528 - $ref: '#/components/parameters/abuseMessageId'
2531 description: successful operation
2533 '/videos/{id}/blacklist':
2535 summary: Block a video
2536 operationId: addVideoBlock
2544 - $ref: '#/components/parameters/idOrUUID'
2547 description: successful operation
2549 summary: Unblock a video by its id
2550 operationId: delVideoBlock
2558 - $ref: '#/components/parameters/idOrUUID'
2561 description: successful operation
2563 description: block not found
2569 summary: List video blocks
2570 operationId: getVideoBlocks
2579 list only blocks that match this type:
2583 - `2`: automatic block that needs review
2591 description: plain search that will match with video titles, and more
2594 - $ref: '#/components/parameters/start'
2595 - $ref: '#/components/parameters/count'
2596 - $ref: '#/components/parameters/blacklistsSort'
2599 description: successful operation
2611 $ref: '#/components/schemas/VideoBlacklist'
2613 /videos/{id}/captions:
2615 summary: List captions of a video
2616 operationId: getVideoCaptions
2620 - $ref: '#/components/parameters/idOrUUID'
2623 description: successful operation
2635 $ref: '#/components/schemas/VideoCaption'
2637 /videos/{id}/captions/{captionLanguage}:
2639 summary: Add or replace a video caption
2640 operationId: addVideoCaption
2647 - $ref: '#/components/parameters/idOrUUID'
2648 - $ref: '#/components/parameters/captionLanguage'
2651 multipart/form-data:
2656 description: The file to upload.
2661 contentType: text/vtt, application/x-subrip, text/plain
2664 description: successful operation
2666 description: video or language not found
2668 summary: Delete a video caption
2669 operationId: delVideoCaption
2676 - $ref: '#/components/parameters/idOrUUID'
2677 - $ref: '#/components/parameters/captionLanguage'
2680 description: successful operation
2682 description: video or language or caption for that language not found
2686 summary: List video channels
2687 operationId: getVideoChannels
2691 - $ref: '#/components/parameters/start'
2692 - $ref: '#/components/parameters/count'
2693 - $ref: '#/components/parameters/sort'
2696 description: successful operation
2700 $ref: '#/components/schemas/VideoChannelList'
2702 summary: Create a video channel
2703 operationId: addVideoChannel
2710 description: successful operation
2720 $ref: '#/components/schemas/VideoChannel/properties/id'
2725 $ref: '#/components/schemas/VideoChannelCreate'
2727 '/video-channels/{channelHandle}':
2729 summary: Get a video channel
2730 operationId: getVideoChannel
2734 - $ref: '#/components/parameters/channelHandle'
2737 description: successful operation
2741 $ref: '#/components/schemas/VideoChannel'
2743 summary: Update a video channel
2744 operationId: putVideoChannel
2750 - $ref: '#/components/parameters/channelHandle'
2753 description: successful operation
2758 $ref: '#/components/schemas/VideoChannelUpdate'
2760 summary: Delete a video channel
2761 operationId: delVideoChannel
2767 - $ref: '#/components/parameters/channelHandle'
2770 description: successful operation
2772 '/video-channels/{channelHandle}/videos':
2774 summary: List videos of a video channel
2775 operationId: getVideoChannelVideos
2780 - $ref: '#/components/parameters/channelHandle'
2781 - $ref: '#/components/parameters/categoryOneOf'
2782 - $ref: '#/components/parameters/isLive'
2783 - $ref: '#/components/parameters/tagsOneOf'
2784 - $ref: '#/components/parameters/tagsAllOf'
2785 - $ref: '#/components/parameters/licenceOneOf'
2786 - $ref: '#/components/parameters/languageOneOf'
2787 - $ref: '#/components/parameters/nsfw'
2788 - $ref: '#/components/parameters/filter'
2789 - $ref: '#/components/parameters/skipCount'
2790 - $ref: '#/components/parameters/start'
2791 - $ref: '#/components/parameters/count'
2792 - $ref: '#/components/parameters/videosSort'
2795 description: successful operation
2799 $ref: '#/components/schemas/VideoListResponse'
2801 '/video-channels/{channelHandle}/avatar/pick':
2803 summary: Update channel avatar
2809 - $ref: '#/components/parameters/channelHandle'
2812 description: successful operation
2819 $ref: '#/components/schemas/ActorImage'
2821 description: image file too large
2823 X-File-Maximum-Size:
2827 description: Maximum file size for the avatar
2830 multipart/form-data:
2835 description: The file to upload.
2840 contentType: image/png, image/jpeg
2842 '/video-channels/{channelHandle}/avatar':
2844 summary: Delete channel avatar
2850 - $ref: '#/components/parameters/channelHandle'
2853 description: successful operation
2855 '/video-channels/{channelHandle}/banner/pick':
2857 summary: Update channel banner
2863 - $ref: '#/components/parameters/channelHandle'
2866 description: successful operation
2873 $ref: '#/components/schemas/ActorImage'
2875 description: image file too large
2877 X-File-Maximum-Size:
2881 description: Maximum file size for the banner
2884 multipart/form-data:
2889 description: The file to upload.
2894 contentType: image/png, image/jpeg
2896 '/video-channels/{channelHandle}/banner':
2898 summary: Delete channel banner
2904 - $ref: '#/components/parameters/channelHandle'
2907 description: successful operation
2909 /video-playlists/privacies:
2911 summary: List available playlist privacy policies
2912 operationId: getPlaylistPrivacyPolicies
2917 description: successful operation
2926 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2930 summary: List video playlists
2931 operationId: getPlaylists
2935 - $ref: '#/components/parameters/start'
2936 - $ref: '#/components/parameters/count'
2937 - $ref: '#/components/parameters/sort'
2940 description: successful operation
2952 $ref: '#/components/schemas/VideoPlaylist'
2954 summary: Create a video playlist
2955 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2956 operationId: addPlaylist
2963 description: successful operation
2973 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2975 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2978 multipart/form-data:
2983 description: Video playlist display name
2988 description: Video playlist thumbnail file
2992 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2994 description: Video playlist description
3000 - $ref: '#/components/schemas/id'
3001 description: Video channel in which the playlist will be published
3006 contentType: image/jpeg
3008 /video-playlists/{playlistId}:
3010 summary: Get a video playlist
3014 - $ref: '#/components/parameters/playlistId'
3017 description: successful operation
3021 $ref: '#/components/schemas/VideoPlaylist'
3023 summary: Update a video playlist
3024 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3031 description: successful operation
3033 - $ref: '#/components/parameters/playlistId'
3036 multipart/form-data:
3041 description: Video playlist display name
3046 description: Video playlist thumbnail file
3050 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3052 description: Video playlist description
3056 - $ref: '#/components/schemas/id'
3057 description: Video channel in which the playlist will be published
3060 contentType: image/jpeg
3062 summary: Delete a video playlist
3068 - $ref: '#/components/parameters/playlistId'
3071 description: successful operation
3073 /video-playlists/{playlistId}/videos:
3075 summary: 'List videos of a playlist'
3076 operationId: getVideoPlaylistVideos
3081 - $ref: '#/components/parameters/playlistId'
3084 description: successful operation
3088 $ref: '#/components/schemas/VideoListResponse'
3090 summary: Add a video in a playlist
3091 operationId: addVideoPlaylistVideo
3098 - $ref: '#/components/parameters/playlistId'
3101 description: successful operation
3107 videoPlaylistElement:
3121 - $ref: '#/components/schemas/Video/properties/uuid'
3122 - $ref: '#/components/schemas/Video/properties/id'
3123 description: Video to add in the playlist
3127 description: Start the video at this specific timestamp
3131 description: Stop the video at this specific timestamp
3135 /video-playlists/{playlistId}/videos/reorder:
3137 summary: 'Reorder a playlist'
3138 operationId: reorderVideoPlaylist
3144 - $ref: '#/components/parameters/playlistId'
3147 description: successful operation
3156 description: 'Start position of the element to reorder'
3158 insertAfterPosition:
3160 description: 'New position for the block to reorder, to add the block before the first element'
3164 description: 'How many element from `startPosition` to reorder'
3168 - insertAfterPosition
3170 /video-playlists/{playlistId}/videos/{playlistElementId}:
3172 summary: Update a playlist element
3173 operationId: putVideoPlaylistVideo
3179 - $ref: '#/components/parameters/playlistId'
3180 - $ref: '#/components/parameters/playlistElementId'
3183 description: successful operation
3193 description: Start the video at this specific timestamp
3197 description: Stop the video at this specific timestamp
3199 summary: Delete an element from a playlist
3200 operationId: delVideoPlaylistVideo
3206 - $ref: '#/components/parameters/playlistId'
3207 - $ref: '#/components/parameters/playlistElementId'
3210 description: successful operation
3212 '/users/me/video-playlists/videos-exist':
3214 summary: Check video exists in my playlists
3223 description: The video ids to check
3227 $ref: '#/components/schemas/Video/properties/id'
3230 description: successful operation
3252 '/accounts/{name}/video-channels':
3254 summary: List video channels of an account
3259 - $ref: '#/components/parameters/name'
3262 description: include view statistics for the last 30 days (only if authentified as the account user)
3265 - $ref: '#/components/parameters/start'
3266 - $ref: '#/components/parameters/count'
3267 - $ref: '#/components/parameters/sort'
3270 description: successful operation
3274 $ref: '#/components/schemas/VideoChannelList'
3276 '/accounts/{name}/ratings':
3278 summary: List ratings of an account
3284 - $ref: '#/components/parameters/name'
3285 - $ref: '#/components/parameters/start'
3286 - $ref: '#/components/parameters/count'
3287 - $ref: '#/components/parameters/sort'
3291 description: Optionally filter which ratings to retrieve
3299 description: successful operation
3305 $ref: '#/components/schemas/VideoRating'
3307 '/videos/{id}/comment-threads':
3309 summary: List threads of a video
3313 - $ref: '#/components/parameters/idOrUUID'
3314 - $ref: '#/components/parameters/start'
3315 - $ref: '#/components/parameters/count'
3316 - $ref: '#/components/parameters/commentsSort'
3319 description: successful operation
3323 $ref: '#/components/schemas/CommentThreadResponse'
3325 summary: Create a thread
3331 - $ref: '#/components/parameters/idOrUUID'
3334 description: successful operation
3338 $ref: '#/components/schemas/CommentThreadPostResponse'
3340 description: video does not exist
3349 - $ref: '#/components/schemas/VideoComment/properties/text'
3355 '/videos/{id}/comment-threads/{threadId}':
3357 summary: Get a thread
3361 - $ref: '#/components/parameters/idOrUUID'
3362 - $ref: '#/components/parameters/threadId'
3365 description: successful operation
3369 $ref: '#/components/schemas/VideoCommentThreadTree'
3371 '/videos/{id}/comments/{commentId}':
3373 summary: Reply to a thread of a video
3379 - $ref: '#/components/parameters/idOrUUID'
3380 - $ref: '#/components/parameters/commentId'
3383 description: successful operation
3387 $ref: '#/components/schemas/CommentThreadPostResponse'
3389 description: thread or video does not exist
3398 - $ref: '#/components/schemas/VideoComment/properties/text'
3404 summary: Delete a comment or a reply
3410 - $ref: '#/components/parameters/idOrUUID'
3411 - $ref: '#/components/parameters/commentId'
3414 description: successful operation
3416 description: cannot remove comment of another user
3418 description: comment or video does not exist
3420 description: comment is already deleted
3422 '/videos/{id}/rate':
3424 summary: Like/dislike a video
3430 - $ref: '#/components/parameters/idOrUUID'
3446 description: successful operation
3448 description: video does not exist
3454 summary: Search videos
3455 operationId: searchVideos
3460 allowEmptyValue: false
3462 String to search. If the user can make a remote URI search, and the string is an URI then the
3463 PeerTube instance will fetch the remote object and add it to its database. Then,
3464 you can use the REST API to fetch the complete video information and interact with it.
3467 - $ref: '#/components/parameters/categoryOneOf'
3468 - $ref: '#/components/parameters/isLive'
3469 - $ref: '#/components/parameters/tagsOneOf'
3470 - $ref: '#/components/parameters/tagsAllOf'
3471 - $ref: '#/components/parameters/licenceOneOf'
3472 - $ref: '#/components/parameters/languageOneOf'
3473 - $ref: '#/components/parameters/nsfw'
3474 - $ref: '#/components/parameters/filter'
3475 - $ref: '#/components/parameters/skipCount'
3476 - $ref: '#/components/parameters/start'
3477 - $ref: '#/components/parameters/count'
3478 - $ref: '#/components/parameters/searchTarget'
3479 - $ref: '#/components/parameters/videosSearchSort'
3482 description: Get videos that are published after this date
3488 description: Get videos that are published before this date
3492 - name: originallyPublishedStartDate
3494 description: Get videos that are originally published after this date
3498 - name: originallyPublishedEndDate
3500 description: Get videos that are originally published before this date
3506 description: Get videos that have this minimum duration
3511 description: Get videos that have this maximum duration
3515 'searchTarget === search-index':
3516 $ref: '#/components/callbacks/searchIndex'
3519 description: successful operation
3523 $ref: '#/components/schemas/VideoListResponse'
3525 description: search index unavailable
3527 /search/video-channels:
3531 summary: Search channels
3532 operationId: searchChannels
3538 String to search. If the user can make a remote URI search, and the string is an URI then the
3539 PeerTube instance will fetch the remote object and add it to its database. Then,
3540 you can use the REST API to fetch the complete channel information and interact with it.
3543 - $ref: '#/components/parameters/start'
3544 - $ref: '#/components/parameters/count'
3545 - $ref: '#/components/parameters/searchTarget'
3546 - $ref: '#/components/parameters/sort'
3548 'searchTarget === search-index':
3549 $ref: '#/components/callbacks/searchIndex'
3552 description: successful operation
3556 $ref: '#/components/schemas/VideoChannelList'
3558 description: search index unavailable
3560 /server/blocklist/accounts:
3564 summary: List account blocks
3569 - $ref: '#/components/parameters/start'
3570 - $ref: '#/components/parameters/count'
3571 - $ref: '#/components/parameters/sort'
3574 description: successful operation
3578 summary: Block an account
3590 example: chocobozzz@example.org
3591 description: account to block, in the form `username@domain`
3596 description: successful operation
3598 description: self-blocking forbidden
3600 '/server/blocklist/accounts/{accountName}':
3604 summary: Unblock an account by its handle
3612 description: account to unblock, in the form `username@domain`
3617 description: successful operation
3619 description: account or account block does not exist
3621 /server/blocklist/servers:
3625 summary: List server blocks
3630 - $ref: '#/components/parameters/start'
3631 - $ref: '#/components/parameters/count'
3632 - $ref: '#/components/parameters/sort'
3635 description: successful operation
3639 summary: Block a server
3652 description: server domain to block
3657 description: successful operation
3659 description: self-blocking forbidden
3661 '/server/blocklist/servers/{host}':
3665 summary: Unblock a server by its domain
3673 description: server domain to unblock
3679 description: successful operation
3681 description: account block does not exist
3683 /server/redundancy/{host}:
3686 - Instance Redundancy
3687 summary: Update a server redundancy policy
3695 description: server domain to mirror
3707 description: allow mirroring of the host's local videos
3712 description: successful operation
3714 description: server is not already known
3716 /server/redundancy/videos:
3720 summary: List videos being mirrored
3721 operationId: getMirroredVideos
3729 description: direction of the mirror
3735 - $ref: '#/components/parameters/start'
3736 - $ref: '#/components/parameters/count'
3737 - $ref: '#/components/parameters/videoRedundanciesSort'
3740 description: successful operation
3746 $ref: '#/components/schemas/VideoRedundancy'
3750 summary: Mirror a video
3751 operationId: putMirroredVideo
3762 $ref: '#/components/schemas/Video/properties/id'
3767 description: successful operation
3769 description: cannot mirror a local video
3771 description: video does not exist
3773 description: video is already mirrored
3775 /server/redundancy/videos/{redundancyId}:
3779 summary: Delete a mirror done on a video
3780 operationId: delMirroredVideo
3785 - name: redundancyId
3788 description: id of an existing redundancy on a video
3793 description: successful operation
3795 description: video redundancy not found
3797 '/feeds/video-comments.{format}':
3801 summary: List comments on videos
3802 operationId: getSyndicatedComments
3807 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3820 description: 'limit listing to a specific video'
3825 description: 'limit listing to a specific account'
3830 description: 'limit listing to a specific account'
3833 - name: videoChannelId
3835 description: 'limit listing to a specific video channel'
3838 - name: videoChannelName
3840 description: 'limit listing to a specific video channel'
3845 description: successful operation
3850 default: 'max-age=900' # 15 min cache
3854 $ref: '#/components/schemas/VideoCommentsForXML'
3857 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3858 application/rss+xml:
3860 $ref: '#/components/schemas/VideoCommentsForXML'
3863 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3866 $ref: '#/components/schemas/VideoCommentsForXML'
3869 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3870 application/atom+xml:
3872 $ref: '#/components/schemas/VideoCommentsForXML'
3875 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3881 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3883 x-summary: field inconsistencies
3886 - videoId filter is mixed with a channel filter
3888 description: video, video channel or account not found
3890 description: accept header unsupported
3892 '/feeds/videos.{format}':
3896 summary: List videos
3897 operationId: getSyndicatedVideos
3902 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3915 description: 'limit listing to a specific account'
3920 description: 'limit listing to a specific account'
3923 - name: videoChannelId
3925 description: 'limit listing to a specific video channel'
3928 - name: videoChannelName
3930 description: 'limit listing to a specific video channel'
3933 - $ref: '#/components/parameters/sort'
3934 - $ref: '#/components/parameters/nsfw'
3935 - $ref: '#/components/parameters/filter'
3938 description: successful operation
3943 default: 'max-age=900' # 15 min cache
3947 $ref: '#/components/schemas/VideosForXML'
3950 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3951 application/rss+xml:
3953 $ref: '#/components/schemas/VideosForXML'
3956 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3959 $ref: '#/components/schemas/VideosForXML'
3962 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3963 application/atom+xml:
3965 $ref: '#/components/schemas/VideosForXML'
3968 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3974 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3976 description: video channel or account not found
3978 description: accept header unsupported
3980 '/feeds/subscriptions.{format}':
3985 summary: List videos of subscriptions tied to a token
3986 operationId: getSyndicatedSubscriptionVideos
3991 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4004 description: limit listing to a specific account
4010 description: private token allowing access
4014 - $ref: '#/components/parameters/sort'
4015 - $ref: '#/components/parameters/nsfw'
4016 - $ref: '#/components/parameters/filter'
4019 description: successful operation
4024 default: 'max-age=900' # 15 min cache
4028 $ref: '#/components/schemas/VideosForXML'
4029 application/rss+xml:
4031 $ref: '#/components/schemas/VideosForXML'
4034 $ref: '#/components/schemas/VideosForXML'
4035 application/atom+xml:
4037 $ref: '#/components/schemas/VideosForXML'
4042 description: accept header unsupported
4048 summary: List plugins
4049 operationId: getPlugins
4062 - $ref: '#/components/parameters/start'
4063 - $ref: '#/components/parameters/count'
4064 - $ref: '#/components/parameters/sort'
4067 description: successful operation
4071 $ref: '#/components/schemas/PluginResponse'
4077 summary: List available plugins
4078 operationId: getAvailablePlugins
4091 - name: currentPeerTubeEngine
4095 - $ref: '#/components/parameters/start'
4096 - $ref: '#/components/parameters/count'
4097 - $ref: '#/components/parameters/sort'
4100 description: successful operation
4104 $ref: '#/components/schemas/PluginResponse'
4106 description: plugin index unavailable
4112 summary: Install a plugin
4113 operationId: addPlugin
4126 example: peertube-plugin-auth-ldap
4129 additionalProperties: false
4136 additionalProperties: false
4139 description: successful operation
4141 description: should have either `npmName` or `path` set
4147 summary: Update a plugin
4148 operationId: updatePlugin
4161 example: peertube-plugin-auth-ldap
4164 additionalProperties: false
4171 additionalProperties: false
4174 description: successful operation
4176 description: should have either `npmName` or `path` set
4178 description: existing plugin not found
4184 summary: Uninstall a plugin
4185 operationId: uninstallPlugin
4197 description: name of the plugin/theme in its package.json
4198 example: peertube-plugin-auth-ldap
4203 description: successful operation
4205 description: existing plugin not found
4211 summary: Get a plugin
4212 operationId: getPlugin
4217 - $ref: '#/components/parameters/npmName'
4220 description: successful operation
4224 $ref: '#/components/schemas/Plugin'
4226 description: plugin not found
4228 /plugins/{npmName}/settings:
4232 summary: Set a plugin's settings
4237 - $ref: '#/components/parameters/npmName'
4246 additionalProperties: true
4249 description: successful operation
4251 description: plugin not found
4253 /plugins/{npmName}/public-settings:
4257 summary: Get a plugin's public settings
4259 - $ref: '#/components/parameters/npmName'
4262 description: successful operation
4267 additionalProperties: true
4269 description: plugin not found
4271 /plugins/{npmName}/registered-settings:
4275 summary: Get a plugin's registered settings
4280 - $ref: '#/components/parameters/npmName'
4283 description: successful operation
4288 additionalProperties: true
4290 description: plugin not found
4293 - url: 'https://peertube2.cpy.re/api/v1'
4294 description: Live Test Server (live data - latest nightly version)
4295 - url: 'https://peertube3.cpy.re/api/v1'
4296 description: Live Test Server (live data - latest RC version)
4297 - url: 'https://peertube.cpy.re/api/v1'
4298 description: Live Test Server (live data - stable version)
4305 description: Offset used to paginate results
4313 description: "Number of items to return"
4323 description: Sort column
4331 description: Plain text search, applied to various parts of the model depending on endpoint
4339 If the administrator enabled search index support, you can override the default search target.
4342 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4343 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4344 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4345 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4346 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4347 * 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
4348 the data from the origin instance API
4358 description: Sort videos by criteria
4374 description: Sort videos by criteria
4389 description: Sort comments by criteria
4399 description: Sort blacklists by criteria
4415 description: Plain text search that will match with user usernames or emails
4422 description: Filter results down to (un)banned users
4429 description: Sort users by criteria
4440 description: Sort abuses by criteria
4447 videoRedundanciesSort:
4451 description: Sort abuses by criteria
4460 description: The username or handle of the account
4463 example: chocobozzz | chocobozzz@example.org
4468 description: The user id
4470 $ref: '#/components/schemas/id'
4475 description: The object id or uuid
4478 - $ref: '#/components/schemas/id'
4479 - $ref: '#/components/schemas/UUIDv4'
4484 description: Playlist id
4486 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4488 name: playlistElementId
4491 description: Playlist element id
4493 $ref: '#/components/schemas/id'
4498 description: Abuse id
4500 $ref: '#/components/schemas/Abuse/properties/id'
4502 name: abuseMessageId
4505 description: Abuse message id
4507 $ref: '#/components/schemas/AbuseMessage/properties/id'
4509 name: captionLanguage
4512 description: The caption language
4514 $ref: '#/components/schemas/VideoLanguageSet'
4519 description: The video channel handle
4522 example: my_username | my_username@example.com
4524 name: subscriptionHandle
4527 description: The subscription handle
4530 example: my_username | my_username@example.com
4535 description: The thread id (root comment id)
4542 description: The comment id
4544 $ref: '#/components/schemas/VideoComment/properties/id'
4549 description: whether or not the video is a live
4556 description: category id of the video (see [/videos/categories](#operation/getCategories))
4559 - $ref: '#/components/schemas/VideoCategorySet'
4562 $ref: '#/components/schemas/VideoCategorySet'
4569 description: tag(s) of the video
4583 description: tag(s) of the video, where all should be present in the video
4596 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4599 - $ref: '#/components/schemas/VideoLanguageSet'
4602 $ref: '#/components/schemas/VideoLanguageSet'
4609 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4612 - $ref: '#/components/schemas/VideoLicenceSet'
4615 $ref: '#/components/schemas/VideoLicenceSet'
4622 description: if you don't need the `total` in the response
4633 description: whether to include nsfw videos, if any
4644 Special filters which might require special rights:
4645 * `local` - only videos local to the instance
4646 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4647 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4657 description: list of uris to check if each is part of the user subscriptions
4667 description: name of the plugin/theme on npmjs.com or in its package.json
4670 example: peertube-plugin-auth-ldap
4675 description: job type
4679 - activitypub-follow
4680 - activitypub-http-broadcast
4681 - activitypub-http-fetcher
4682 - activitypub-http-unicast
4688 - activitypub-refresher
4713 Authenticating via OAuth requires the following steps:
4714 - Have an activated account
4715 - [Generate] an access token for that account at `/api/v1/users/token`.
4716 - Make requests with the *Authorization: Bearer <token\>* header
4717 - Profit, depending on the role assigned to the account
4719 Note that the __access token is valid for 1 day__ and is given
4720 along with a __refresh token valid for 2 weeks__.
4722 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4726 tokenUrl: /api/v1/users/token
4729 moderator: Moderator scope
4732 # Resuable core properties
4740 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4741 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4746 description: immutable name of the user, used to find or mention its actor
4748 pattern: '/^[a-z0-9._]+$/'
4753 description: immutable name of the channel, used to interact with its actor
4754 example: framasoft_videos
4755 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4766 description: category id of the video (see [/videos/categories](#operation/getCategories))
4768 VideoConstantNumber-Category:
4771 $ref: '#/components/schemas/VideoCategorySet'
4774 example: Science & Technology
4778 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4780 VideoConstantNumber-Licence:
4783 $ref: '#/components/schemas/VideoLicenceSet'
4786 example: Attribution - Share Alike
4790 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4792 VideoConstantString-Language:
4795 $ref: '#/components/schemas/VideoLanguageSet'
4800 VideoPlaylistPrivacySet:
4806 description: Video playlist privacy policy (see [/video-playlists/privacies])
4807 VideoPlaylistPrivacyConstant:
4810 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4814 VideoPlaylistTypeSet:
4819 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4820 VideoPlaylistTypeConstant:
4823 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4834 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4835 VideoPrivacyConstant:
4838 $ref: '#/components/schemas/VideoPrivacySet'
4855 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4862 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4873 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4883 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4887 $ref: '#/components/schemas/AbuseStateSet'
4890 AbusePredefinedReasons:
4903 example: [spamOrMisleading]
4908 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4910 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4912 VideoResolutionConstant:
4913 description: resolutions and their labels for the video
4916 $ref: '#/components/schemas/VideoResolutionSet'
4920 VideoScheduledUpdate:
4923 $ref: '#/components/schemas/VideoPrivacySet'
4927 description: When to update the video
4947 - $ref: '#/components/schemas/ActorImage'
4948 VideoChannelSummary:
4951 $ref: '#/components/schemas/id'
4965 - $ref: '#/components/schemas/ActorImage'
4979 - $ref: '#/components/schemas/Video'
4986 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4987 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
4988 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4990 $ref: '#/components/schemas/VideoResolutionConstant'
4993 description: Video file size in bytes
4996 description: Direct URL of the torrent file
5000 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5004 description: Direct URL of the video
5008 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5012 description: Frames per second of the video file
5016 description: URL dereferencing the output of ffprobe on the file
5017 VideoStreamingPlaylists:
5022 $ref: '#/components/schemas/id'
5030 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5031 VideoStreamingPlaylists-HLS:
5042 Video files associated to this playlist.
5044 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5046 $ref: '#/components/schemas/VideoFile'
5058 $ref: '#/components/schemas/Video/properties/id'
5060 $ref: '#/components/schemas/Video/properties/uuid'
5062 $ref: '#/components/schemas/Video/properties/name'
5066 description: object id for the video
5068 - $ref: '#/components/schemas/id'
5070 description: universal identifier for the video, that can be used across instances
5072 - $ref: '#/components/schemas/UUIDv4'
5078 example: 2017-10-01T10:52:46.396Z
5079 description: time at which the video object was first drafted
5083 example: 2018-10-01T10:52:46.396Z
5084 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5088 example: 2021-05-04T08:01:01.502Z
5089 description: last time the video's metadata was modified
5090 originallyPublishedAt:
5093 example: 2010-10-01T10:52:46.396Z
5094 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5097 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5098 description: category in which the video is classified
5101 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5102 description: licence under which the video is distributed
5105 - $ref: '#/components/schemas/VideoConstantString-Language'
5106 description: main language used in the video
5109 - $ref: '#/components/schemas/VideoPrivacyConstant'
5110 description: privacy policy used to distribute the video
5114 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5115 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5119 truncated description of the video, written in Markdown.
5120 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5125 description: duration of the video in seconds
5130 description: title of the video
5131 example: What is PeerTube?
5136 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5139 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5142 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5159 - $ref: '#/components/schemas/VideoStateConstant'
5160 description: represents the internal state of the video processing within the PeerTube instance
5164 - $ref: '#/components/schemas/VideoScheduledUpdate'
5172 $ref: '#/components/schemas/AccountSummary'
5174 $ref: '#/components/schemas/VideoChannelSummary'
5183 - $ref: '#/components/schemas/Video'
5188 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5189 description: path at which to get the full description of maximum `10000` characters
5192 description: A text tell the audience how to support the video creator
5193 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5197 $ref: '#/components/schemas/VideoChannel'
5199 $ref: '#/components/schemas/Account'
5201 example: [flowers, gardening]
5219 - https://peertube2.cpy.re/tracker/announce
5220 - wss://peertube2.cpy.re/tracker/socket
5224 $ref: '#/components/schemas/VideoFile'
5226 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5228 - field will be empty
5229 - video files will be found in `streamingPlaylists[].files` field
5233 $ref: '#/components/schemas/VideoStreamingPlaylists'
5235 HLS playlists/manifest files. If HLS is disabled on the server:
5237 - field will be empty
5238 - video files will be found in `files` field
5239 FileRedundancyInformation:
5242 $ref: '#/components/schemas/id'
5267 $ref: '#/components/schemas/id'
5274 $ref: '#/components/schemas/UUIDv4'
5281 $ref: '#/components/schemas/FileRedundancyInformation'
5285 $ref: '#/components/schemas/FileRedundancyInformation'
5286 VideoImportStateConstant:
5294 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5301 additionalProperties: false
5305 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5306 required: [targetUrl]
5309 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5310 required: [magnetUri]
5313 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5314 required: [torrentfile]
5315 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5324 - $ref: '#/components/schemas/id'
5328 description: remote URL where to find the import's source video
5329 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5333 description: magnet URI allowing to resolve the import's source video
5334 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
5335 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5340 description: Torrent file containing only the video file
5347 - $ref: '#/components/schemas/VideoImportStateConstant'
5363 - $ref: '#/components/schemas/Video'
5373 $ref: '#/components/schemas/VideoImport'
5377 $ref: '#/components/schemas/id'
5380 example: The video is a spam
5384 $ref: '#/components/schemas/AbusePredefinedReasons'
5386 $ref: '#/components/schemas/Account'
5388 $ref: '#/components/schemas/AbuseStateConstant'
5391 example: Decided to ban the server since it spams us regularly
5395 $ref: '#/components/schemas/VideoInfo'
5402 $ref: '#/components/schemas/id'
5413 $ref: '#/components/schemas/AccountSummary'
5417 $ref: '#/components/schemas/id'
5419 $ref: '#/components/schemas/Video/properties/id'
5431 $ref: '#/components/schemas/UUIDv4'
5449 $ref: '#/components/schemas/id'
5451 $ref: '#/components/schemas/UUIDv4'
5474 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5476 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5478 $ref: '#/components/schemas/AccountSummary'
5480 $ref: '#/components/schemas/VideoChannelSummary'
5484 $ref: '#/components/schemas/id'
5491 description: Text of the comment
5493 example: This video is wonderful!
5495 $ref: '#/components/schemas/id'
5499 - $ref: '#/components/schemas/id'
5501 $ref: '#/components/schemas/Video/properties/id'
5516 totalRepliesFromVideoAuthor:
5523 $ref: '#/components/schemas/Account'
5524 VideoCommentThreadTree:
5527 $ref: '#/components/schemas/VideoComment'
5531 $ref: '#/components/schemas/VideoCommentThreadTree'
5535 $ref: '#/components/schemas/VideoConstantString-Language'
5551 $ref: '#/components/schemas/id'
5568 $ref: '#/components/schemas/id'
5573 description: immutable name of the actor, used to find or mention it
5575 - $ref: '#/components/schemas/username'
5579 description: server on which the actor is resident
5580 hostRedundancyAllowed:
5582 description: whether this actor's host allows redundancy of its videos
5586 description: number of actors subscribed to by this actor, as seen by this instance
5590 description: number of followers of this actor, as seen by this instance
5598 $ref: '#/components/schemas/ActorImage'
5601 - $ref: '#/components/schemas/Actor'
5604 description: object id for the user tied to this account
5606 - $ref: '#/components/schemas/User/properties/id'
5609 description: editable name of the account, displayed in its representations
5614 description: text or bio displayed on the account's profile
5620 description: timestamp within the video, in seconds
5687 allowedForCurrentIP:
5689 requiresEmailVerification:
5707 $ref: '#/components/schemas/VideoResolutionSet'
5792 example: 16810141515
5901 requiresEmailVerification:
5916 description: Settings that apply to new users, if registration is enabled
5920 example: 16810141515
5926 description: Settings pertaining to transcoding jobs
5930 allowAdditionalExtensions:
5932 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5935 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5938 description: Amount of threads used by ffmpeg for 1 transcoding job
5941 description: Amount of transcoding jobs to execute in parallel
5947 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5950 description: Resolutions to transcode _new videos_ to
5970 description: WebTorrent-specific settings
5976 description: HLS-specific settings
6026 $ref: '#/components/schemas/id'
6028 $ref: '#/components/schemas/Actor'
6030 $ref: '#/components/schemas/Actor'
6033 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6046 PredefinedAbuseReasons:
6047 description: Reason categories that help triage reports
6065 $ref: '#/components/schemas/id'
6077 - activitypub-http-unicast
6078 - activitypub-http-broadcast
6079 - activitypub-http-fetcher
6080 - activitypub-follow
6086 - activitypub-refresher
6090 additionalProperties: true
6093 additionalProperties: true
6109 $ref: '#/components/schemas/id'
6114 $ref: '#/components/schemas/id'
6115 VideoUploadRequestCommon:
6118 description: Video name
6120 example: What is PeerTube?
6124 description: Channel id that will contain this video
6129 $ref: '#/components/schemas/VideoPrivacySet'
6131 $ref: '#/components/schemas/VideoCategorySet'
6133 $ref: '#/components/schemas/VideoLicenceSet'
6135 $ref: '#/components/schemas/VideoLanguageSet'
6137 description: Video description
6140 **[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)**
6142 description: Whether or not we wait transcoding before publish the video
6145 description: A text tell the audience how to support the video creator
6146 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6149 description: Whether or not this video contains sensitive content
6152 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6165 description: Enable or disable comments for this video
6168 description: Enable or disable downloading for this video
6170 originallyPublishedAt:
6171 description: Date when the content was originally published
6175 $ref: '#/components/schemas/VideoScheduledUpdate'
6177 description: Video thumbnail file
6181 description: Video preview file
6187 VideoUploadRequestLegacy:
6189 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6195 description: Video file
6198 VideoUploadRequestResumable:
6200 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6206 description: Video filename including extension
6209 example: what_is_peertube.mp4
6211 description: Video thumbnail file
6215 description: Video preview file
6218 VideoUploadResponse:
6224 $ref: '#/components/schemas/Video/properties/id'
6226 $ref: '#/components/schemas/Video/properties/uuid'
6227 CommentThreadResponse:
6236 $ref: '#/components/schemas/VideoComment'
6237 CommentThreadPostResponse:
6240 $ref: '#/components/schemas/VideoComment'
6250 $ref: '#/components/schemas/Video'
6254 $ref: '#/components/schemas/Account'
6257 description: Automatically start playing the upcoming video after the currently playing video
6258 autoPlayNextVideoPlaylist:
6260 description: Automatically start playing the video on the playlist after the currently playing video
6263 description: Automatically start playing the video on the watch page
6273 description: The user email
6276 description: Has the user confirmed their email address?
6279 - $ref: '#/components/schemas/id'
6283 description: Auth plugin to use to authenticate the user
6287 noInstanceConfigWarningModal:
6292 $ref: '#/components/schemas/NSFWPolicy'
6294 $ref: '#/components/schemas/UserRole'
6303 description: Theme enabled by this user
6305 $ref: '#/components/schemas/username'
6309 $ref: '#/components/schemas/VideoChannel'
6312 description: The user video quota in bytes
6316 description: The user daily video quota in bytes
6320 description: Enable P2P in the player
6323 - $ref: '#/components/schemas/User'
6325 # optionally present fields: they require WITH_STATS scope
6328 description: Count of videos published
6331 description: Count of reports/abuses of which the user is a target
6332 abusesAcceptedCount:
6334 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6337 description: Count of reports/abuses created by the user
6340 description: Count of comments published
6344 $ref: '#/components/schemas/username'
6346 $ref: '#/components/schemas/password'
6350 description: The user email
6353 description: The user video quota in bytes
6357 description: The user daily video quota in bytes
6360 $ref: '#/components/schemas/usernameChannel'
6362 $ref: '#/components/schemas/UserRole'
6364 $ref: '#/components/schemas/UserAdminFlags'
6375 description: The updated email of the user
6377 - $ref: '#/components/schemas/User/properties/email'
6380 description: Set the email as verified
6383 description: The updated video quota of the user in bytes
6386 description: The updated daily video quota of the user in bytes
6390 description: The auth plugin to use to authenticate the user
6391 example: 'peertube-plugin-auth-saml2'
6393 $ref: '#/components/schemas/UserRole'
6395 $ref: '#/components/schemas/UserAdminFlags'
6397 # see shared/models/users/user-update-me.model.ts:
6400 $ref: '#/components/schemas/password'
6402 $ref: '#/components/schemas/password'
6404 description: new email used for login and service communications
6406 - $ref: '#/components/schemas/User/properties/email'
6409 description: new name of the user in its representations
6414 description: new NSFW display policy
6421 description: whether to enable P2P in the player or not
6424 description: new preference regarding playing videos automatically
6427 description: new preference regarding playing following videos automatically
6428 autoPlayNextVideoPlaylist:
6430 description: new preference regarding playing following playlist videos automatically
6431 videosHistoryEnabled:
6433 description: whether to keep track of watched history or not
6438 description: list of languages to filter videos down to
6441 noInstanceConfigWarningModal:
6448 $ref: '#/components/schemas/id'
6455 description: Rating of the video
6462 $ref: '#/components/schemas/Video'
6469 description: Rating of the video
6476 description: immutable name of the user, used to find or mention its actor
6478 - $ref: '#/components/schemas/username'
6480 $ref: '#/components/schemas/password'
6484 description: email of the user, used for login or service communications
6487 description: editable name of the user, displayed in its representations
6492 description: channel base information used to create the first channel of the user
6495 $ref: '#/components/schemas/usernameChannel'
6497 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6507 pattern: /^[a-z0-9]$/
6510 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6513 pattern: /^[a-zA-Z0-9]$/
6516 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6517 OAuthToken-password:
6519 - $ref: '#/components/schemas/OAuthClient'
6529 $ref: '#/components/schemas/User/properties/username'
6531 $ref: '#/components/schemas/password'
6538 OAuthToken-refresh_token:
6540 - $ref: '#/components/schemas/OAuthClient'
6551 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6560 # GET/POST/PUT properties
6563 description: editable name of the channel, displayed in its representations
6564 example: Videos of Framasoft
6569 example: Videos made with <3 by Framasoft
6574 description: text shown by default on all videos of this channel, to tell the audience how to support it
6575 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6578 # GET-only properties
6582 - $ref: '#/components/schemas/id'
6598 $ref: '#/components/schemas/UUIDv4'
6601 - $ref: '#/components/schemas/VideoChannel'
6604 description: username of the channel to create
6606 - $ref: '#/components/schemas/usernameChannel'
6612 - $ref: '#/components/schemas/VideoChannel'
6614 bulkVideosSupportUpdate:
6616 description: Update the support field for all videos of this channel
6626 - $ref: '#/components/schemas/VideoChannel'
6627 - $ref: '#/components/schemas/Actor'
6632 name: 'media:peerLink'
6641 - application/x-bittorrent
6647 name: 'media:content'
6678 VideoCommentsForXML:
6713 description: video watch page URL
6716 description: video canonical URL
6720 description: video publication date
6723 description: video description
6726 description: video description
6729 description: publisher user name
6732 description: video category (MRSS)
6735 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6750 description: video embed path, relative to the canonical URL domain (MRSS)
6759 description: video watch path, relative to the canonical URL domain (MRSS)
6780 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6781 'media:description':
6788 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6791 description: main streamable file for the video
6801 - application/x-bittorrent
6810 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)
6813 - $ref: '#/components/schemas/MRSSPeerLink'
6814 - $ref: '#/components/schemas/MRSSGroupContent'
6815 NotificationSettingValue:
6832 $ref: '#/components/schemas/id'
6836 Notification type, following the `UserNotificationType` enum:
6838 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6840 - `2` NEW_COMMENT_ON_MY_VIDEO
6842 - `3` NEW_ABUSE_FOR_MODERATORS
6844 - `4` BLACKLIST_ON_MY_VIDEO
6846 - `5` UNBLACKLIST_ON_MY_VIDEO
6848 - `6` MY_VIDEO_PUBLISHED
6850 - `7` MY_VIDEO_IMPORT_SUCCESS
6852 - `8` MY_VIDEO_IMPORT_ERROR
6854 - `9` NEW_USER_REGISTRATION
6858 - `11` COMMENT_MENTION
6860 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6862 - `13` NEW_INSTANCE_FOLLOWER
6864 - `14` AUTO_INSTANCE_FOLLOWING
6870 - $ref: '#/components/schemas/VideoInfo'
6874 $ref: '#/components/schemas/ActorInfo'
6880 $ref: '#/components/schemas/id'
6883 $ref: '#/components/schemas/VideoInfo'
6888 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6898 $ref: '#/components/schemas/id'
6902 $ref: '#/components/schemas/VideoInfo'
6904 $ref: '#/components/schemas/ActorInfo'
6910 $ref: '#/components/schemas/id'
6913 - $ref: '#/components/schemas/VideoInfo'
6919 $ref: '#/components/schemas/id'
6922 - $ref: '#/components/schemas/VideoInfo'
6926 - $ref: '#/components/schemas/ActorInfo'
6932 $ref: '#/components/schemas/id'
6934 $ref: '#/components/schemas/ActorInfo'
6962 NotificationListResponse:
6971 $ref: '#/components/schemas/Notification'
6976 example: peertube-plugin-auth-ldap
7004 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7007 additionalProperties: true
7023 $ref: '#/components/schemas/Plugin'
7030 description: User can stream multiple times in a permanent live
7039 description: RTMP stream key to use to stream into this live video
7043 description: User can stream multiple times in a permanent live
7050 'https://search.example.org/api/v1/search/videos':
7052 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7055 description: successful operation
7059 $ref: '#/components/schemas/VideoListResponse'