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
1744 description: Enable or disable downloading for this video
1746 originallyPublishedAt:
1747 description: Date when the content was originally published
1751 $ref: '#/components/schemas/VideoScheduledUpdate'
1754 contentType: image/jpeg
1756 contentType: image/jpeg
1758 summary: Get a video
1759 operationId: getVideo
1763 - $ref: '#/components/parameters/idOrUUID'
1766 description: successful operation
1770 $ref: '#/components/schemas/VideoDetails'
1772 summary: Delete a video
1773 operationId: delVideo
1779 - $ref: '#/components/parameters/idOrUUID'
1782 description: successful operation
1784 '/videos/{id}/description':
1786 summary: Get complete video description
1787 operationId: getVideoDesc
1791 - $ref: '#/components/parameters/idOrUUID'
1794 description: successful operation
1803 **[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)**
1805 '/videos/{id}/views':
1807 summary: Add a view to a video
1808 operationId: addView
1812 - $ref: '#/components/parameters/idOrUUID'
1815 description: successful operation
1817 '/videos/{id}/watching':
1819 summary: Set watching progress of a video
1820 operationId: setProgress
1826 - $ref: '#/components/parameters/idOrUUID'
1831 $ref: '#/components/schemas/UserWatchingVideo'
1835 description: successful operation
1839 summary: Upload a video
1840 description: Uses a single request to upload a video.
1841 operationId: uploadLegacy
1849 description: successful operation
1853 $ref: '#/components/schemas/VideoUploadResponse'
1855 description: video didn't pass upload filter
1857 description: upload has timed out
1859 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1861 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1862 - `quota_reached` for quota limits wether daily or global
1864 X-File-Maximum-Size:
1868 description: Maximum file size for the video
1870 description: video type unsupported
1872 description: video unreadable
1875 multipart/form-data:
1877 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1880 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1882 contentType: image/jpeg
1884 contentType: image/jpeg
1889 USERNAME="<your_username>"
1890 PASSWORD="<your_password>"
1891 FILE_PATH="<your_file_path>"
1892 CHANNEL_ID="<your_channel_id>"
1894 API="https://peertube2.cpy.re/api/v1"
1897 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1898 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1899 token=$(curl -s "$API/users/token" \
1900 --data client_id="$client_id" \
1901 --data client_secret="$client_secret" \
1902 --data grant_type=password \
1903 --data username="$USERNAME" \
1904 --data password="$PASSWORD" \
1905 | jq -r ".access_token")
1908 curl -s "$API/videos/upload" \
1909 -H "Authorization: Bearer $token" \
1911 --form videofile=@"$FILE_PATH" \
1912 --form channelId=$CHANNEL_ID \
1915 /videos/upload-resumable:
1917 summary: Initialize the resumable upload of a video
1918 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1919 operationId: uploadResumableInit
1926 - name: X-Upload-Content-Length
1932 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1933 - name: X-Upload-Content-Type
1940 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1945 $ref: '#/components/schemas/VideoUploadRequestResumable'
1948 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1950 description: created
1956 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1962 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1964 Disambiguate via `type`:
1965 - `max_file_size_reached` for the absolute file size limit
1966 - `quota_reached` for quota limits whether daily or global
1968 description: video type unsupported
1970 summary: Send chunk for the resumable upload of a video
1971 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
1972 operationId: uploadResumable
1983 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1984 not valid anymore and you need to initialize a new upload.
1987 - name: Content-Range
1991 example: bytes 0-262143/2469036
1994 Specifies the bytes in the file that the request is uploading.
1996 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1997 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1998 - name: Content-Length
2005 Size of the chunk that the request is sending.
2007 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)
2008 doesn't mandate for chunks to have the same size throughout the upload sequence.
2010 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2011 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2014 application/octet-stream:
2020 description: last chunk received
2028 $ref: '#/components/schemas/VideoUploadResponse'
2030 description: resume incomplete
2035 example: bytes=0-262143
2041 description: video didn't pass upload filter
2043 description: upload not found
2045 description: chunk doesn't match range
2047 description: video unreadable
2049 description: too many concurrent requests
2051 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2052 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2053 operationId: uploadResumableCancel
2064 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2065 not valid anymore and the upload session has already been deleted with its data ;-)
2068 - name: Content-Length
2076 description: upload cancelled
2083 description: upload not found
2087 summary: Import a video
2088 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2089 operationId: importVideo
2097 multipart/form-data:
2099 $ref: '#/components/schemas/VideoCreateImport'
2102 contentType: application/x-bittorrent
2104 contentType: image/jpeg
2106 contentType: image/jpeg
2109 description: successful operation
2113 $ref: '#/components/schemas/VideoUploadResponse'
2115 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2117 description: video didn't pass pre-import filter
2119 description: HTTP or Torrent/magnetURI import not enabled
2123 summary: Create a live
2124 operationId: addLive
2132 description: successful operation
2136 $ref: '#/components/schemas/VideoUploadResponse'
2138 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2140 Disambiguate via `type`:
2141 - default type for a validation error
2142 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2144 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2146 Disambiguate via `type`:
2147 - `live_not_enabled` for a disabled live feature
2148 - `live_not_allowing_replay` for a disabled replay feature
2149 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2150 - `max_user_lives_limit_reached` for the user concurrent live limit
2153 multipart/form-data:
2158 description: Channel id that will contain this live video
2163 description: User can stream multiple times in a permanent live
2166 description: Live video/replay thumbnail file
2170 description: Live video/replay preview file
2174 $ref: '#/components/schemas/VideoPrivacySet'
2176 $ref: '#/components/schemas/VideoCategorySet'
2178 $ref: '#/components/schemas/VideoLicenceSet'
2180 $ref: '#/components/schemas/VideoLanguageSet'
2182 description: Live video/replay description
2185 description: A text tell the audience how to support the creator
2186 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2189 description: Whether or not this live video/replay contains sensitive content
2192 description: Live video/replay name
2197 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2206 description: Enable or disable comments for this live video/replay
2209 description: Enable or disable downloading for the replay of this live video
2216 contentType: image/jpeg
2218 contentType: image/jpeg
2222 summary: Get information about a live
2223 operationId: getLiveId
2230 - $ref: '#/components/parameters/idOrUUID'
2233 description: successful operation
2237 $ref: '#/components/schemas/LiveVideoResponse'
2239 summary: Update information about a live
2240 operationId: updateLiveId
2247 - $ref: '#/components/parameters/idOrUUID'
2252 $ref: '#/components/schemas/LiveVideoUpdate'
2255 description: successful operation
2257 description: bad parameters or trying to update a live that has already started
2259 description: trying to save replay of the live but saving replay is not enabled on the instance
2263 summary: List my abuses
2264 operationId: getMyAbuses
2273 description: only list the report with this id
2279 $ref: '#/components/schemas/AbuseStateSet'
2280 - $ref: '#/components/parameters/abusesSort'
2281 - $ref: '#/components/parameters/start'
2282 - $ref: '#/components/parameters/count'
2285 description: successful operation
2297 $ref: '#/components/schemas/Abuse'
2301 summary: List abuses
2302 operationId: getAbuses
2312 description: only list the report with this id
2315 - name: predefinedReason
2317 description: predefined reason the listed reports should contain
2319 $ref: '#/components/schemas/PredefinedAbuseReasons'
2322 description: plain search that will match with video titles, reporter names and more
2328 $ref: '#/components/schemas/AbuseStateSet'
2329 - name: searchReporter
2331 description: only list reports of a specific reporter
2334 - name: searchReportee
2335 description: only list reports of a specific reportee
2341 description: only list reports of a specific video
2344 - name: searchVideoChannel
2346 description: only list reports of a specific video channel
2351 description: only list deleted or blocklisted videos
2359 description: only list account, comment or video reports
2366 - $ref: '#/components/parameters/start'
2367 - $ref: '#/components/parameters/count'
2368 - $ref: '#/components/parameters/abusesSort'
2371 description: successful operation
2383 $ref: '#/components/schemas/Abuse'
2385 summary: Report an abuse
2398 description: Reason why the user reports this video
2403 $ref: '#/components/schemas/PredefinedAbuseReasons'
2408 description: Video id to report
2410 - $ref: '#/components/schemas/Video/properties/id'
2414 description: Timestamp in the video that marks the beginning of the report
2419 description: Timestamp in the video that marks the ending of the report
2425 description: Comment id to report
2427 - $ref: '#/components/schemas/VideoComment/properties/id'
2432 description: Account id to report
2438 description: successful operation
2448 $ref: '#/components/schemas/id'
2450 description: incorrect request parameters
2452 '/abuses/{abuseId}':
2454 summary: Update an abuse
2462 - $ref: '#/components/parameters/abuseId'
2470 $ref: '#/components/schemas/AbuseStateSet'
2473 description: Update the report comment visible only to the moderation team
2478 description: successful operation
2480 description: abuse not found
2484 summary: Delete an abuse
2490 - $ref: '#/components/parameters/abuseId'
2493 description: successful operation
2495 description: block not found
2497 '/abuses/{abuseId}/messages':
2499 summary: List messages of an abuse
2505 - $ref: '#/components/parameters/abuseId'
2508 description: successful operation
2520 $ref: '#/components/schemas/AbuseMessage'
2522 summary: Add message to an abuse
2528 - $ref: '#/components/parameters/abuseId'
2537 description: Message to send
2545 description: successful operation
2547 description: incorrect request parameters
2549 '/abuses/{abuseId}/messages/{abuseMessageId}':
2551 summary: Delete an abuse message
2557 - $ref: '#/components/parameters/abuseId'
2558 - $ref: '#/components/parameters/abuseMessageId'
2561 description: successful operation
2563 '/videos/{id}/blacklist':
2565 summary: Block a video
2566 operationId: addVideoBlock
2574 - $ref: '#/components/parameters/idOrUUID'
2577 description: successful operation
2579 summary: Unblock a video by its id
2580 operationId: delVideoBlock
2588 - $ref: '#/components/parameters/idOrUUID'
2591 description: successful operation
2593 description: block not found
2599 summary: List video blocks
2600 operationId: getVideoBlocks
2609 list only blocks that match this type:
2613 - `2`: automatic block that needs review
2621 description: plain search that will match with video titles, and more
2624 - $ref: '#/components/parameters/start'
2625 - $ref: '#/components/parameters/count'
2626 - $ref: '#/components/parameters/blacklistsSort'
2629 description: successful operation
2641 $ref: '#/components/schemas/VideoBlacklist'
2643 /videos/{id}/captions:
2645 summary: List captions of a video
2646 operationId: getVideoCaptions
2650 - $ref: '#/components/parameters/idOrUUID'
2653 description: successful operation
2665 $ref: '#/components/schemas/VideoCaption'
2667 /videos/{id}/captions/{captionLanguage}:
2669 summary: Add or replace a video caption
2670 operationId: addVideoCaption
2677 - $ref: '#/components/parameters/idOrUUID'
2678 - $ref: '#/components/parameters/captionLanguage'
2681 multipart/form-data:
2686 description: The file to upload.
2691 contentType: text/vtt, application/x-subrip, text/plain
2694 description: successful operation
2696 description: video or language not found
2698 summary: Delete a video caption
2699 operationId: delVideoCaption
2706 - $ref: '#/components/parameters/idOrUUID'
2707 - $ref: '#/components/parameters/captionLanguage'
2710 description: successful operation
2712 description: video or language or caption for that language not found
2716 summary: List video channels
2717 operationId: getVideoChannels
2721 - $ref: '#/components/parameters/start'
2722 - $ref: '#/components/parameters/count'
2723 - $ref: '#/components/parameters/sort'
2726 description: successful operation
2730 $ref: '#/components/schemas/VideoChannelList'
2732 summary: Create a video channel
2733 operationId: addVideoChannel
2740 description: successful operation
2750 $ref: '#/components/schemas/VideoChannel/properties/id'
2755 $ref: '#/components/schemas/VideoChannelCreate'
2757 '/video-channels/{channelHandle}':
2759 summary: Get a video channel
2760 operationId: getVideoChannel
2764 - $ref: '#/components/parameters/channelHandle'
2767 description: successful operation
2771 $ref: '#/components/schemas/VideoChannel'
2773 summary: Update a video channel
2774 operationId: putVideoChannel
2780 - $ref: '#/components/parameters/channelHandle'
2783 description: successful operation
2788 $ref: '#/components/schemas/VideoChannelUpdate'
2790 summary: Delete a video channel
2791 operationId: delVideoChannel
2797 - $ref: '#/components/parameters/channelHandle'
2800 description: successful operation
2802 '/video-channels/{channelHandle}/videos':
2804 summary: List videos of a video channel
2805 operationId: getVideoChannelVideos
2810 - $ref: '#/components/parameters/channelHandle'
2811 - $ref: '#/components/parameters/categoryOneOf'
2812 - $ref: '#/components/parameters/isLive'
2813 - $ref: '#/components/parameters/tagsOneOf'
2814 - $ref: '#/components/parameters/tagsAllOf'
2815 - $ref: '#/components/parameters/licenceOneOf'
2816 - $ref: '#/components/parameters/languageOneOf'
2817 - $ref: '#/components/parameters/nsfw'
2818 - $ref: '#/components/parameters/filter'
2819 - $ref: '#/components/parameters/skipCount'
2820 - $ref: '#/components/parameters/start'
2821 - $ref: '#/components/parameters/count'
2822 - $ref: '#/components/parameters/videosSort'
2825 description: successful operation
2829 $ref: '#/components/schemas/VideoListResponse'
2831 '/video-channels/{channelHandle}/avatar/pick':
2833 summary: Update channel avatar
2839 - $ref: '#/components/parameters/channelHandle'
2842 description: successful operation
2849 $ref: '#/components/schemas/ActorImage'
2851 description: image file too large
2853 X-File-Maximum-Size:
2857 description: Maximum file size for the avatar
2860 multipart/form-data:
2865 description: The file to upload.
2870 contentType: image/png, image/jpeg
2872 '/video-channels/{channelHandle}/avatar':
2874 summary: Delete channel avatar
2880 - $ref: '#/components/parameters/channelHandle'
2883 description: successful operation
2885 '/video-channels/{channelHandle}/banner/pick':
2887 summary: Update channel banner
2893 - $ref: '#/components/parameters/channelHandle'
2896 description: successful operation
2903 $ref: '#/components/schemas/ActorImage'
2905 description: image file too large
2907 X-File-Maximum-Size:
2911 description: Maximum file size for the banner
2914 multipart/form-data:
2919 description: The file to upload.
2924 contentType: image/png, image/jpeg
2926 '/video-channels/{channelHandle}/banner':
2928 summary: Delete channel banner
2934 - $ref: '#/components/parameters/channelHandle'
2937 description: successful operation
2939 /video-playlists/privacies:
2941 summary: List available playlist privacy policies
2942 operationId: getPlaylistPrivacyPolicies
2947 description: successful operation
2956 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2960 summary: List video playlists
2961 operationId: getPlaylists
2965 - $ref: '#/components/parameters/start'
2966 - $ref: '#/components/parameters/count'
2967 - $ref: '#/components/parameters/sort'
2970 description: successful operation
2982 $ref: '#/components/schemas/VideoPlaylist'
2984 summary: Create a video playlist
2985 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2986 operationId: addPlaylist
2993 description: successful operation
3003 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3005 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3007 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3010 multipart/form-data:
3015 description: Video playlist display name
3020 description: Video playlist thumbnail file
3024 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3026 description: Video playlist description
3032 - $ref: '#/components/schemas/id'
3033 description: Video channel in which the playlist will be published
3038 contentType: image/jpeg
3040 /video-playlists/{playlistId}:
3042 summary: Get a video playlist
3046 - $ref: '#/components/parameters/playlistId'
3049 description: successful operation
3053 $ref: '#/components/schemas/VideoPlaylist'
3055 summary: Update a video playlist
3056 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3063 description: successful operation
3065 - $ref: '#/components/parameters/playlistId'
3068 multipart/form-data:
3073 description: Video playlist display name
3078 description: Video playlist thumbnail file
3082 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3084 description: Video playlist description
3088 - $ref: '#/components/schemas/id'
3089 description: Video channel in which the playlist will be published
3092 contentType: image/jpeg
3094 summary: Delete a video playlist
3100 - $ref: '#/components/parameters/playlistId'
3103 description: successful operation
3105 /video-playlists/{playlistId}/videos:
3107 summary: 'List videos of a playlist'
3108 operationId: getVideoPlaylistVideos
3113 - $ref: '#/components/parameters/playlistId'
3116 description: successful operation
3120 $ref: '#/components/schemas/VideoListResponse'
3122 summary: Add a video in a playlist
3123 operationId: addVideoPlaylistVideo
3130 - $ref: '#/components/parameters/playlistId'
3133 description: successful operation
3139 videoPlaylistElement:
3153 - $ref: '#/components/schemas/Video/properties/uuid'
3154 - $ref: '#/components/schemas/Video/properties/id'
3155 description: Video to add in the playlist
3159 description: Start the video at this specific timestamp
3163 description: Stop the video at this specific timestamp
3167 /video-playlists/{playlistId}/videos/reorder:
3169 summary: 'Reorder a playlist'
3170 operationId: reorderVideoPlaylist
3176 - $ref: '#/components/parameters/playlistId'
3179 description: successful operation
3188 description: 'Start position of the element to reorder'
3190 insertAfterPosition:
3192 description: 'New position for the block to reorder, to add the block before the first element'
3196 description: 'How many element from `startPosition` to reorder'
3200 - insertAfterPosition
3202 /video-playlists/{playlistId}/videos/{playlistElementId}:
3204 summary: Update a playlist element
3205 operationId: putVideoPlaylistVideo
3211 - $ref: '#/components/parameters/playlistId'
3212 - $ref: '#/components/parameters/playlistElementId'
3215 description: successful operation
3225 description: Start the video at this specific timestamp
3229 description: Stop the video at this specific timestamp
3231 summary: Delete an element from a playlist
3232 operationId: delVideoPlaylistVideo
3238 - $ref: '#/components/parameters/playlistId'
3239 - $ref: '#/components/parameters/playlistElementId'
3242 description: successful operation
3244 '/users/me/video-playlists/videos-exist':
3246 summary: Check video exists in my playlists
3255 description: The video ids to check
3259 $ref: '#/components/schemas/Video/properties/id'
3262 description: successful operation
3284 '/accounts/{name}/video-channels':
3286 summary: List video channels of an account
3291 - $ref: '#/components/parameters/name'
3294 description: include view statistics for the last 30 days (only if authentified as the account user)
3297 - $ref: '#/components/parameters/start'
3298 - $ref: '#/components/parameters/count'
3299 - $ref: '#/components/parameters/sort'
3302 description: successful operation
3306 $ref: '#/components/schemas/VideoChannelList'
3308 '/accounts/{name}/ratings':
3310 summary: List ratings of an account
3316 - $ref: '#/components/parameters/name'
3317 - $ref: '#/components/parameters/start'
3318 - $ref: '#/components/parameters/count'
3319 - $ref: '#/components/parameters/sort'
3323 description: Optionally filter which ratings to retrieve
3331 description: successful operation
3337 $ref: '#/components/schemas/VideoRating'
3339 '/videos/{id}/comment-threads':
3341 summary: List threads of a video
3345 - $ref: '#/components/parameters/idOrUUID'
3346 - $ref: '#/components/parameters/start'
3347 - $ref: '#/components/parameters/count'
3348 - $ref: '#/components/parameters/commentsSort'
3351 description: successful operation
3355 $ref: '#/components/schemas/CommentThreadResponse'
3357 summary: Create a thread
3363 - $ref: '#/components/parameters/idOrUUID'
3366 description: successful operation
3370 $ref: '#/components/schemas/CommentThreadPostResponse'
3372 description: video does not exist
3381 - $ref: '#/components/schemas/VideoComment/properties/text'
3387 '/videos/{id}/comment-threads/{threadId}':
3389 summary: Get a thread
3393 - $ref: '#/components/parameters/idOrUUID'
3394 - $ref: '#/components/parameters/threadId'
3397 description: successful operation
3401 $ref: '#/components/schemas/VideoCommentThreadTree'
3403 '/videos/{id}/comments/{commentId}':
3405 summary: Reply to a thread of a video
3411 - $ref: '#/components/parameters/idOrUUID'
3412 - $ref: '#/components/parameters/commentId'
3415 description: successful operation
3419 $ref: '#/components/schemas/CommentThreadPostResponse'
3421 description: thread or video does not exist
3430 - $ref: '#/components/schemas/VideoComment/properties/text'
3436 summary: Delete a comment or a reply
3442 - $ref: '#/components/parameters/idOrUUID'
3443 - $ref: '#/components/parameters/commentId'
3446 description: successful operation
3448 description: cannot remove comment of another user
3450 description: comment or video does not exist
3452 description: comment is already deleted
3454 '/videos/{id}/rate':
3456 summary: Like/dislike a video
3462 - $ref: '#/components/parameters/idOrUUID'
3478 description: successful operation
3480 description: video does not exist
3486 summary: Search videos
3487 operationId: searchVideos
3492 allowEmptyValue: false
3494 String to search. If the user can make a remote URI search, and the string is an URI then the
3495 PeerTube instance will fetch the remote object and add it to its database. Then,
3496 you can use the REST API to fetch the complete video information and interact with it.
3499 - $ref: '#/components/parameters/categoryOneOf'
3500 - $ref: '#/components/parameters/isLive'
3501 - $ref: '#/components/parameters/tagsOneOf'
3502 - $ref: '#/components/parameters/tagsAllOf'
3503 - $ref: '#/components/parameters/licenceOneOf'
3504 - $ref: '#/components/parameters/languageOneOf'
3505 - $ref: '#/components/parameters/nsfw'
3506 - $ref: '#/components/parameters/filter'
3507 - $ref: '#/components/parameters/skipCount'
3508 - $ref: '#/components/parameters/start'
3509 - $ref: '#/components/parameters/count'
3510 - $ref: '#/components/parameters/searchTarget'
3511 - $ref: '#/components/parameters/videosSearchSort'
3514 description: Get videos that are published after this date
3520 description: Get videos that are published before this date
3524 - name: originallyPublishedStartDate
3526 description: Get videos that are originally published after this date
3530 - name: originallyPublishedEndDate
3532 description: Get videos that are originally published before this date
3538 description: Get videos that have this minimum duration
3543 description: Get videos that have this maximum duration
3547 'searchTarget === search-index':
3548 $ref: '#/components/callbacks/searchIndex'
3551 description: successful operation
3555 $ref: '#/components/schemas/VideoListResponse'
3557 description: search index unavailable
3559 /search/video-channels:
3563 summary: Search channels
3564 operationId: searchChannels
3570 String to search. If the user can make a remote URI search, and the string is an URI then the
3571 PeerTube instance will fetch the remote object and add it to its database. Then,
3572 you can use the REST API to fetch the complete channel information and interact with it.
3575 - $ref: '#/components/parameters/start'
3576 - $ref: '#/components/parameters/count'
3577 - $ref: '#/components/parameters/searchTarget'
3578 - $ref: '#/components/parameters/sort'
3580 'searchTarget === search-index':
3581 $ref: '#/components/callbacks/searchIndex'
3584 description: successful operation
3588 $ref: '#/components/schemas/VideoChannelList'
3590 description: search index unavailable
3592 /search/video-playlists:
3596 summary: Search playlists
3597 operationId: searchPlaylists
3603 String to search. If the user can make a remote URI search, and the string is an URI then the
3604 PeerTube instance will fetch the remote object and add it to its database. Then,
3605 you can use the REST API to fetch the complete playlist information and interact with it.
3608 - $ref: '#/components/parameters/start'
3609 - $ref: '#/components/parameters/count'
3610 - $ref: '#/components/parameters/searchTarget'
3611 - $ref: '#/components/parameters/sort'
3613 'searchTarget === search-index':
3614 $ref: '#/components/callbacks/searchIndex'
3617 description: successful operation
3629 $ref: '#/components/schemas/VideoPlaylist'
3631 description: search index unavailable
3633 /server/blocklist/accounts:
3637 summary: List account blocks
3642 - $ref: '#/components/parameters/start'
3643 - $ref: '#/components/parameters/count'
3644 - $ref: '#/components/parameters/sort'
3647 description: successful operation
3651 summary: Block an account
3663 example: chocobozzz@example.org
3664 description: account to block, in the form `username@domain`
3669 description: successful operation
3671 description: self-blocking forbidden
3673 '/server/blocklist/accounts/{accountName}':
3677 summary: Unblock an account by its handle
3685 description: account to unblock, in the form `username@domain`
3690 description: successful operation
3692 description: account or account block does not exist
3694 /server/blocklist/servers:
3698 summary: List server blocks
3703 - $ref: '#/components/parameters/start'
3704 - $ref: '#/components/parameters/count'
3705 - $ref: '#/components/parameters/sort'
3708 description: successful operation
3712 summary: Block a server
3725 description: server domain to block
3730 description: successful operation
3732 description: self-blocking forbidden
3734 '/server/blocklist/servers/{host}':
3738 summary: Unblock a server by its domain
3746 description: server domain to unblock
3752 description: successful operation
3754 description: account block does not exist
3756 /server/redundancy/{host}:
3759 - Instance Redundancy
3760 summary: Update a server redundancy policy
3768 description: server domain to mirror
3780 description: allow mirroring of the host's local videos
3785 description: successful operation
3787 description: server is not already known
3789 /server/redundancy/videos:
3793 summary: List videos being mirrored
3794 operationId: getMirroredVideos
3802 description: direction of the mirror
3808 - $ref: '#/components/parameters/start'
3809 - $ref: '#/components/parameters/count'
3810 - $ref: '#/components/parameters/videoRedundanciesSort'
3813 description: successful operation
3819 $ref: '#/components/schemas/VideoRedundancy'
3823 summary: Mirror a video
3824 operationId: putMirroredVideo
3835 $ref: '#/components/schemas/Video/properties/id'
3840 description: successful operation
3842 description: cannot mirror a local video
3844 description: video does not exist
3846 description: video is already mirrored
3848 /server/redundancy/videos/{redundancyId}:
3852 summary: Delete a mirror done on a video
3853 operationId: delMirroredVideo
3858 - name: redundancyId
3861 description: id of an existing redundancy on a video
3866 description: successful operation
3868 description: video redundancy not found
3870 '/feeds/video-comments.{format}':
3874 summary: List comments on videos
3875 operationId: getSyndicatedComments
3880 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3893 description: 'limit listing to a specific video'
3898 description: 'limit listing to a specific account'
3903 description: 'limit listing to a specific account'
3906 - name: videoChannelId
3908 description: 'limit listing to a specific video channel'
3911 - name: videoChannelName
3913 description: 'limit listing to a specific video channel'
3918 description: successful operation
3923 default: 'max-age=900' # 15 min cache
3927 $ref: '#/components/schemas/VideoCommentsForXML'
3930 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3931 application/rss+xml:
3933 $ref: '#/components/schemas/VideoCommentsForXML'
3936 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3939 $ref: '#/components/schemas/VideoCommentsForXML'
3942 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3943 application/atom+xml:
3945 $ref: '#/components/schemas/VideoCommentsForXML'
3948 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3954 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3956 x-summary: field inconsistencies
3959 - videoId filter is mixed with a channel filter
3961 description: video, video channel or account not found
3963 description: accept header unsupported
3965 '/feeds/videos.{format}':
3969 summary: List videos
3970 operationId: getSyndicatedVideos
3975 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3988 description: 'limit listing to a specific account'
3993 description: 'limit listing to a specific account'
3996 - name: videoChannelId
3998 description: 'limit listing to a specific video channel'
4001 - name: videoChannelName
4003 description: 'limit listing to a specific video channel'
4006 - $ref: '#/components/parameters/sort'
4007 - $ref: '#/components/parameters/nsfw'
4008 - $ref: '#/components/parameters/filter'
4011 description: successful operation
4016 default: 'max-age=900' # 15 min cache
4020 $ref: '#/components/schemas/VideosForXML'
4023 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4024 application/rss+xml:
4026 $ref: '#/components/schemas/VideosForXML'
4029 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4032 $ref: '#/components/schemas/VideosForXML'
4035 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4036 application/atom+xml:
4038 $ref: '#/components/schemas/VideosForXML'
4041 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4047 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4049 description: video channel or account not found
4051 description: accept header unsupported
4053 '/feeds/subscriptions.{format}':
4058 summary: List videos of subscriptions tied to a token
4059 operationId: getSyndicatedSubscriptionVideos
4064 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4077 description: limit listing to a specific account
4083 description: private token allowing access
4087 - $ref: '#/components/parameters/sort'
4088 - $ref: '#/components/parameters/nsfw'
4089 - $ref: '#/components/parameters/filter'
4092 description: successful operation
4097 default: 'max-age=900' # 15 min cache
4101 $ref: '#/components/schemas/VideosForXML'
4102 application/rss+xml:
4104 $ref: '#/components/schemas/VideosForXML'
4107 $ref: '#/components/schemas/VideosForXML'
4108 application/atom+xml:
4110 $ref: '#/components/schemas/VideosForXML'
4115 description: accept header unsupported
4121 summary: List plugins
4122 operationId: getPlugins
4135 - $ref: '#/components/parameters/start'
4136 - $ref: '#/components/parameters/count'
4137 - $ref: '#/components/parameters/sort'
4140 description: successful operation
4144 $ref: '#/components/schemas/PluginResponse'
4150 summary: List available plugins
4151 operationId: getAvailablePlugins
4164 - name: currentPeerTubeEngine
4168 - $ref: '#/components/parameters/start'
4169 - $ref: '#/components/parameters/count'
4170 - $ref: '#/components/parameters/sort'
4173 description: successful operation
4177 $ref: '#/components/schemas/PluginResponse'
4179 description: plugin index unavailable
4185 summary: Install a plugin
4186 operationId: addPlugin
4199 example: peertube-plugin-auth-ldap
4202 additionalProperties: false
4209 additionalProperties: false
4212 description: successful operation
4214 description: should have either `npmName` or `path` set
4220 summary: Update a plugin
4221 operationId: updatePlugin
4234 example: peertube-plugin-auth-ldap
4237 additionalProperties: false
4244 additionalProperties: false
4247 description: successful operation
4249 description: should have either `npmName` or `path` set
4251 description: existing plugin not found
4257 summary: Uninstall a plugin
4258 operationId: uninstallPlugin
4270 description: name of the plugin/theme in its package.json
4271 example: peertube-plugin-auth-ldap
4276 description: successful operation
4278 description: existing plugin not found
4284 summary: Get a plugin
4285 operationId: getPlugin
4290 - $ref: '#/components/parameters/npmName'
4293 description: successful operation
4297 $ref: '#/components/schemas/Plugin'
4299 description: plugin not found
4301 /plugins/{npmName}/settings:
4305 summary: Set a plugin's settings
4310 - $ref: '#/components/parameters/npmName'
4319 additionalProperties: true
4322 description: successful operation
4324 description: plugin not found
4326 /plugins/{npmName}/public-settings:
4330 summary: Get a plugin's public settings
4332 - $ref: '#/components/parameters/npmName'
4335 description: successful operation
4340 additionalProperties: true
4342 description: plugin not found
4344 /plugins/{npmName}/registered-settings:
4348 summary: Get a plugin's registered settings
4353 - $ref: '#/components/parameters/npmName'
4356 description: successful operation
4361 additionalProperties: true
4363 description: plugin not found
4366 - url: 'https://peertube2.cpy.re/api/v1'
4367 description: Live Test Server (live data - latest nightly version)
4368 - url: 'https://peertube3.cpy.re/api/v1'
4369 description: Live Test Server (live data - latest RC version)
4370 - url: 'https://peertube.cpy.re/api/v1'
4371 description: Live Test Server (live data - stable version)
4378 description: Offset used to paginate results
4386 description: "Number of items to return"
4396 description: Sort column
4404 description: Plain text search, applied to various parts of the model depending on endpoint
4412 If the administrator enabled search index support, you can override the default search target.
4415 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4416 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4417 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4418 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4419 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4420 * 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
4421 the data from the origin instance API
4431 description: Sort videos by criteria
4447 description: Sort videos by criteria
4462 description: Sort comments by criteria
4472 description: Sort blocklists by criteria
4488 description: Plain text search that will match with user usernames or emails
4495 description: Filter results down to (un)banned users
4502 description: Sort users by criteria
4513 description: Sort abuses by criteria
4520 videoRedundanciesSort:
4524 description: Sort abuses by criteria
4533 description: The username or handle of the account
4536 example: chocobozzz | chocobozzz@example.org
4541 description: The user id
4543 $ref: '#/components/schemas/id'
4548 description: The object id, uuid or short uuid
4551 - $ref: '#/components/schemas/id'
4552 - $ref: '#/components/schemas/UUIDv4'
4553 - $ref: '#/components/schemas/shortUUID'
4558 description: Playlist id
4560 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4562 name: playlistElementId
4565 description: Playlist element id
4567 $ref: '#/components/schemas/id'
4572 description: Abuse id
4574 $ref: '#/components/schemas/Abuse/properties/id'
4576 name: abuseMessageId
4579 description: Abuse message id
4581 $ref: '#/components/schemas/AbuseMessage/properties/id'
4583 name: captionLanguage
4586 description: The caption language
4588 $ref: '#/components/schemas/VideoLanguageSet'
4593 description: The video channel handle
4596 example: my_username | my_username@example.com
4598 name: subscriptionHandle
4601 description: The subscription handle
4604 example: my_username | my_username@example.com
4609 description: The thread id (root comment id)
4616 description: The comment id
4618 $ref: '#/components/schemas/VideoComment/properties/id'
4623 description: whether or not the video is a live
4630 description: category id of the video (see [/videos/categories](#operation/getCategories))
4633 - $ref: '#/components/schemas/VideoCategorySet'
4636 $ref: '#/components/schemas/VideoCategorySet'
4643 description: tag(s) of the video
4657 description: tag(s) of the video, where all should be present in the video
4670 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4673 - $ref: '#/components/schemas/VideoLanguageSet'
4676 $ref: '#/components/schemas/VideoLanguageSet'
4683 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4686 - $ref: '#/components/schemas/VideoLicenceSet'
4689 $ref: '#/components/schemas/VideoLicenceSet'
4696 description: if you don't need the `total` in the response
4707 description: whether to include nsfw videos, if any
4718 Special filters which might require special rights:
4719 * `local` - only videos local to the instance
4720 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4721 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4731 description: list of uris to check if each is part of the user subscriptions
4741 description: name of the plugin/theme on npmjs.com or in its package.json
4744 example: peertube-plugin-auth-ldap
4749 description: job type
4753 - activitypub-follow
4754 - activitypub-http-broadcast
4755 - activitypub-http-fetcher
4756 - activitypub-http-unicast
4762 - activitypub-refresher
4787 Authenticating via OAuth requires the following steps:
4788 - Have an activated account
4789 - [Generate] an access token for that account at `/api/v1/users/token`.
4790 - Make requests with the *Authorization: Bearer <token\>* header
4791 - Profit, depending on the role assigned to the account
4793 Note that the __access token is valid for 1 day__ and is given
4794 along with a __refresh token valid for 2 weeks__.
4796 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4800 tokenUrl: /api/v1/users/token
4803 moderator: Moderator scope
4806 # Resuable core properties
4814 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4815 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4820 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4821 example: 2y84q2MQUMWPbiEcxNXMgC
4824 description: immutable name of the user, used to find or mention its actor
4826 pattern: '/^[a-z0-9._]+$/'
4831 description: immutable name of the channel, used to interact with its actor
4832 example: framasoft_videos
4833 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4844 description: category id of the video (see [/videos/categories](#operation/getCategories))
4846 VideoConstantNumber-Category:
4849 $ref: '#/components/schemas/VideoCategorySet'
4852 example: Science & Technology
4856 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4858 VideoConstantNumber-Licence:
4861 $ref: '#/components/schemas/VideoLicenceSet'
4864 example: Attribution - Share Alike
4868 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4870 VideoConstantString-Language:
4873 $ref: '#/components/schemas/VideoLanguageSet'
4878 VideoPlaylistPrivacySet:
4884 description: Video playlist privacy policy (see [/video-playlists/privacies])
4885 VideoPlaylistPrivacyConstant:
4888 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4892 VideoPlaylistTypeSet:
4897 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4898 VideoPlaylistTypeConstant:
4901 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4912 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4913 VideoPrivacyConstant:
4916 $ref: '#/components/schemas/VideoPrivacySet'
4933 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4940 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
4951 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4961 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4965 $ref: '#/components/schemas/AbuseStateSet'
4968 AbusePredefinedReasons:
4981 example: [spamOrMisleading]
4986 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4988 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4990 VideoResolutionConstant:
4991 description: resolutions and their labels for the video
4994 $ref: '#/components/schemas/VideoResolutionSet'
4998 VideoScheduledUpdate:
5001 $ref: '#/components/schemas/VideoPrivacySet'
5005 description: When to update the video
5025 - $ref: '#/components/schemas/ActorImage'
5026 VideoChannelSummary:
5029 $ref: '#/components/schemas/id'
5043 - $ref: '#/components/schemas/ActorImage'
5057 - $ref: '#/components/schemas/Video'
5064 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5065 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
5066 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5068 $ref: '#/components/schemas/VideoResolutionConstant'
5071 description: Video file size in bytes
5074 description: Direct URL of the torrent file
5078 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5082 description: Direct URL of the video
5086 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5090 description: Frames per second of the video file
5094 description: URL dereferencing the output of ffprobe on the file
5095 VideoStreamingPlaylists:
5100 $ref: '#/components/schemas/id'
5108 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5109 VideoStreamingPlaylists-HLS:
5120 Video files associated to this playlist.
5122 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5124 $ref: '#/components/schemas/VideoFile'
5136 $ref: '#/components/schemas/Video/properties/id'
5138 $ref: '#/components/schemas/Video/properties/uuid'
5140 $ref: '#/components/schemas/Video/properties/name'
5144 description: object id for the video
5146 - $ref: '#/components/schemas/id'
5148 description: universal identifier for the video, that can be used across instances
5150 - $ref: '#/components/schemas/UUIDv4'
5153 - $ref: '#/components/schemas/shortUUID'
5159 example: 2017-10-01T10:52:46.396Z
5160 description: time at which the video object was first drafted
5164 example: 2018-10-01T10:52:46.396Z
5165 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5169 example: 2021-05-04T08:01:01.502Z
5170 description: last time the video's metadata was modified
5171 originallyPublishedAt:
5174 example: 2010-10-01T10:52:46.396Z
5175 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5178 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5179 description: category in which the video is classified
5182 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5183 description: licence under which the video is distributed
5186 - $ref: '#/components/schemas/VideoConstantString-Language'
5187 description: main language used in the video
5190 - $ref: '#/components/schemas/VideoPrivacyConstant'
5191 description: privacy policy used to distribute the video
5195 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5196 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5200 truncated description of the video, written in Markdown.
5201 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5206 description: duration of the video in seconds
5211 description: title of the video
5212 example: What is PeerTube?
5217 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5220 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5223 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5240 - $ref: '#/components/schemas/VideoStateConstant'
5241 description: represents the internal state of the video processing within the PeerTube instance
5245 - $ref: '#/components/schemas/VideoScheduledUpdate'
5253 $ref: '#/components/schemas/AccountSummary'
5255 $ref: '#/components/schemas/VideoChannelSummary'
5264 - $ref: '#/components/schemas/Video'
5269 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5270 description: path at which to get the full description of maximum `10000` characters
5273 description: A text tell the audience how to support the video creator
5274 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5278 $ref: '#/components/schemas/VideoChannel'
5280 $ref: '#/components/schemas/Account'
5282 example: [flowers, gardening]
5300 - https://peertube2.cpy.re/tracker/announce
5301 - wss://peertube2.cpy.re/tracker/socket
5305 $ref: '#/components/schemas/VideoFile'
5307 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5309 - field will be empty
5310 - video files will be found in `streamingPlaylists[].files` field
5314 $ref: '#/components/schemas/VideoStreamingPlaylists'
5316 HLS playlists/manifest files. If HLS is disabled on the server:
5318 - field will be empty
5319 - video files will be found in `files` field
5320 FileRedundancyInformation:
5323 $ref: '#/components/schemas/id'
5348 $ref: '#/components/schemas/id'
5355 $ref: '#/components/schemas/UUIDv4'
5362 $ref: '#/components/schemas/FileRedundancyInformation'
5366 $ref: '#/components/schemas/FileRedundancyInformation'
5367 VideoImportStateConstant:
5375 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5382 additionalProperties: false
5386 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5387 required: [targetUrl]
5390 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5391 required: [magnetUri]
5394 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5395 required: [torrentfile]
5396 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5405 - $ref: '#/components/schemas/id'
5409 description: remote URL where to find the import's source video
5410 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5414 description: magnet URI allowing to resolve the import's source video
5415 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
5416 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5421 description: Torrent file containing only the video file
5428 - $ref: '#/components/schemas/VideoImportStateConstant'
5444 - $ref: '#/components/schemas/Video'
5454 $ref: '#/components/schemas/VideoImport'
5458 $ref: '#/components/schemas/id'
5461 example: The video is a spam
5465 $ref: '#/components/schemas/AbusePredefinedReasons'
5467 $ref: '#/components/schemas/Account'
5469 $ref: '#/components/schemas/AbuseStateConstant'
5472 example: Decided to ban the server since it spams us regularly
5476 $ref: '#/components/schemas/VideoInfo'
5483 $ref: '#/components/schemas/id'
5494 $ref: '#/components/schemas/AccountSummary'
5498 $ref: '#/components/schemas/id'
5500 $ref: '#/components/schemas/Video/properties/id'
5512 $ref: '#/components/schemas/UUIDv4'
5530 $ref: '#/components/schemas/id'
5532 $ref: '#/components/schemas/UUIDv4'
5535 - $ref: '#/components/schemas/shortUUID'
5558 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5560 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5562 $ref: '#/components/schemas/AccountSummary'
5564 $ref: '#/components/schemas/VideoChannelSummary'
5568 $ref: '#/components/schemas/id'
5575 description: Text of the comment
5577 example: This video is wonderful!
5579 $ref: '#/components/schemas/id'
5583 - $ref: '#/components/schemas/id'
5585 $ref: '#/components/schemas/Video/properties/id'
5600 totalRepliesFromVideoAuthor:
5607 $ref: '#/components/schemas/Account'
5608 VideoCommentThreadTree:
5611 $ref: '#/components/schemas/VideoComment'
5615 $ref: '#/components/schemas/VideoCommentThreadTree'
5619 $ref: '#/components/schemas/VideoConstantString-Language'
5635 $ref: '#/components/schemas/id'
5652 $ref: '#/components/schemas/id'
5657 description: immutable name of the actor, used to find or mention it
5659 - $ref: '#/components/schemas/username'
5663 description: server on which the actor is resident
5664 hostRedundancyAllowed:
5666 description: whether this actor's host allows redundancy of its videos
5670 description: number of actors subscribed to by this actor, as seen by this instance
5674 description: number of followers of this actor, as seen by this instance
5682 $ref: '#/components/schemas/ActorImage'
5685 - $ref: '#/components/schemas/Actor'
5688 description: object id for the user tied to this account
5690 - $ref: '#/components/schemas/User/properties/id'
5693 description: editable name of the account, displayed in its representations
5698 description: text or bio displayed on the account's profile
5704 description: timestamp within the video, in seconds
5771 allowedForCurrentIP:
5773 requiresEmailVerification:
5791 $ref: '#/components/schemas/VideoResolutionSet'
5876 example: 16810141515
5985 requiresEmailVerification:
6000 description: Settings that apply to new users, if registration is enabled
6004 example: 16810141515
6010 description: Settings pertaining to transcoding jobs
6014 allowAdditionalExtensions:
6016 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6019 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6022 description: Amount of threads used by ffmpeg for 1 transcoding job
6025 description: Amount of transcoding jobs to execute in parallel
6031 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6034 description: Resolutions to transcode _new videos_ to
6054 description: WebTorrent-specific settings
6060 description: HLS-specific settings
6110 $ref: '#/components/schemas/id'
6112 $ref: '#/components/schemas/Actor'
6114 $ref: '#/components/schemas/Actor'
6117 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6130 PredefinedAbuseReasons:
6131 description: Reason categories that help triage reports
6149 $ref: '#/components/schemas/id'
6161 - activitypub-http-unicast
6162 - activitypub-http-broadcast
6163 - activitypub-http-fetcher
6164 - activitypub-follow
6170 - activitypub-refresher
6174 additionalProperties: true
6177 additionalProperties: true
6193 $ref: '#/components/schemas/id'
6198 $ref: '#/components/schemas/id'
6199 VideoUploadRequestCommon:
6202 description: Video name
6204 example: What is PeerTube?
6208 description: Channel id that will contain this video
6213 $ref: '#/components/schemas/VideoPrivacySet'
6215 $ref: '#/components/schemas/VideoCategorySet'
6217 $ref: '#/components/schemas/VideoLicenceSet'
6219 $ref: '#/components/schemas/VideoLanguageSet'
6221 description: Video description
6224 **[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)**
6226 description: Whether or not we wait transcoding before publish the video
6229 description: A text tell the audience how to support the video creator
6230 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6233 description: Whether or not this video contains sensitive content
6236 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6249 description: Enable or disable comments for this video
6252 description: Enable or disable downloading for this video
6254 originallyPublishedAt:
6255 description: Date when the content was originally published
6259 $ref: '#/components/schemas/VideoScheduledUpdate'
6261 description: Video thumbnail file
6265 description: Video preview file
6271 VideoUploadRequestLegacy:
6273 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6279 description: Video file
6282 VideoUploadRequestResumable:
6284 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6290 description: Video filename including extension
6293 example: what_is_peertube.mp4
6295 description: Video thumbnail file
6299 description: Video preview file
6302 VideoUploadResponse:
6308 $ref: '#/components/schemas/Video/properties/id'
6310 $ref: '#/components/schemas/Video/properties/uuid'
6312 $ref: '#/components/schemas/Video/properties/shortUUID'
6313 CommentThreadResponse:
6322 $ref: '#/components/schemas/VideoComment'
6323 CommentThreadPostResponse:
6326 $ref: '#/components/schemas/VideoComment'
6336 $ref: '#/components/schemas/Video'
6340 $ref: '#/components/schemas/Account'
6343 description: Automatically start playing the upcoming video after the currently playing video
6344 autoPlayNextVideoPlaylist:
6346 description: Automatically start playing the video on the playlist after the currently playing video
6349 description: Automatically start playing the video on the watch page
6359 description: The user email
6362 description: Has the user confirmed their email address?
6365 - $ref: '#/components/schemas/id'
6369 description: Auth plugin to use to authenticate the user
6373 noInstanceConfigWarningModal:
6378 $ref: '#/components/schemas/NSFWPolicy'
6380 $ref: '#/components/schemas/UserRole'
6389 description: Theme enabled by this user
6391 $ref: '#/components/schemas/username'
6395 $ref: '#/components/schemas/VideoChannel'
6398 description: The user video quota in bytes
6402 description: The user daily video quota in bytes
6406 description: Enable P2P in the player
6409 - $ref: '#/components/schemas/User'
6411 # optionally present fields: they require WITH_STATS scope
6414 description: Count of videos published
6417 description: Count of reports/abuses of which the user is a target
6418 abusesAcceptedCount:
6420 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6423 description: Count of reports/abuses created by the user
6426 description: Count of comments published
6430 $ref: '#/components/schemas/username'
6432 $ref: '#/components/schemas/password'
6436 description: The user email
6439 description: The user video quota in bytes
6443 description: The user daily video quota in bytes
6446 $ref: '#/components/schemas/usernameChannel'
6448 $ref: '#/components/schemas/UserRole'
6450 $ref: '#/components/schemas/UserAdminFlags'
6461 description: The updated email of the user
6463 - $ref: '#/components/schemas/User/properties/email'
6466 description: Set the email as verified
6469 description: The updated video quota of the user in bytes
6472 description: The updated daily video quota of the user in bytes
6476 description: The auth plugin to use to authenticate the user
6477 example: 'peertube-plugin-auth-saml2'
6479 $ref: '#/components/schemas/UserRole'
6481 $ref: '#/components/schemas/UserAdminFlags'
6483 # see shared/models/users/user-update-me.model.ts:
6486 $ref: '#/components/schemas/password'
6488 $ref: '#/components/schemas/password'
6490 description: new email used for login and service communications
6492 - $ref: '#/components/schemas/User/properties/email'
6495 description: new name of the user in its representations
6500 description: new NSFW display policy
6507 description: whether to enable P2P in the player or not
6510 description: new preference regarding playing videos automatically
6513 description: new preference regarding playing following videos automatically
6514 autoPlayNextVideoPlaylist:
6516 description: new preference regarding playing following playlist videos automatically
6517 videosHistoryEnabled:
6519 description: whether to keep track of watched history or not
6524 description: list of languages to filter videos down to
6527 noInstanceConfigWarningModal:
6534 $ref: '#/components/schemas/id'
6541 description: Rating of the video
6548 $ref: '#/components/schemas/Video'
6555 description: Rating of the video
6562 description: immutable name of the user, used to find or mention its actor
6564 - $ref: '#/components/schemas/username'
6566 $ref: '#/components/schemas/password'
6570 description: email of the user, used for login or service communications
6573 description: editable name of the user, displayed in its representations
6578 description: channel base information used to create the first channel of the user
6581 $ref: '#/components/schemas/usernameChannel'
6583 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6593 pattern: /^[a-z0-9]$/
6596 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6599 pattern: /^[a-zA-Z0-9]$/
6602 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6603 OAuthToken-password:
6605 - $ref: '#/components/schemas/OAuthClient'
6615 $ref: '#/components/schemas/User/properties/username'
6617 $ref: '#/components/schemas/password'
6624 OAuthToken-refresh_token:
6626 - $ref: '#/components/schemas/OAuthClient'
6637 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6646 # GET/POST/PUT properties
6649 description: editable name of the channel, displayed in its representations
6650 example: Videos of Framasoft
6655 example: Videos made with <3 by Framasoft
6660 description: text shown by default on all videos of this channel, to tell the audience how to support it
6661 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6664 # GET-only properties
6668 - $ref: '#/components/schemas/id'
6684 $ref: '#/components/schemas/UUIDv4'
6687 - $ref: '#/components/schemas/VideoChannel'
6690 description: username of the channel to create
6692 - $ref: '#/components/schemas/usernameChannel'
6698 - $ref: '#/components/schemas/VideoChannel'
6700 bulkVideosSupportUpdate:
6702 description: Update the support field for all videos of this channel
6712 - $ref: '#/components/schemas/VideoChannel'
6713 - $ref: '#/components/schemas/Actor'
6718 name: 'media:peerLink'
6727 - application/x-bittorrent
6733 name: 'media:content'
6764 VideoCommentsForXML:
6799 description: video watch page URL
6802 description: video canonical URL
6806 description: video publication date
6809 description: video description
6812 description: video description
6815 description: publisher user name
6818 description: video category (MRSS)
6821 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6836 description: video embed path, relative to the canonical URL domain (MRSS)
6845 description: video watch path, relative to the canonical URL domain (MRSS)
6866 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6867 'media:description':
6874 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6877 description: main streamable file for the video
6887 - application/x-bittorrent
6896 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)
6899 - $ref: '#/components/schemas/MRSSPeerLink'
6900 - $ref: '#/components/schemas/MRSSGroupContent'
6901 NotificationSettingValue:
6918 $ref: '#/components/schemas/id'
6922 Notification type, following the `UserNotificationType` enum:
6924 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6926 - `2` NEW_COMMENT_ON_MY_VIDEO
6928 - `3` NEW_ABUSE_FOR_MODERATORS
6930 - `4` BLACKLIST_ON_MY_VIDEO
6932 - `5` UNBLACKLIST_ON_MY_VIDEO
6934 - `6` MY_VIDEO_PUBLISHED
6936 - `7` MY_VIDEO_IMPORT_SUCCESS
6938 - `8` MY_VIDEO_IMPORT_ERROR
6940 - `9` NEW_USER_REGISTRATION
6944 - `11` COMMENT_MENTION
6946 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6948 - `13` NEW_INSTANCE_FOLLOWER
6950 - `14` AUTO_INSTANCE_FOLLOWING
6956 - $ref: '#/components/schemas/VideoInfo'
6960 $ref: '#/components/schemas/ActorInfo'
6966 $ref: '#/components/schemas/id'
6969 $ref: '#/components/schemas/VideoInfo'
6974 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6984 $ref: '#/components/schemas/id'
6988 $ref: '#/components/schemas/VideoInfo'
6990 $ref: '#/components/schemas/ActorInfo'
6996 $ref: '#/components/schemas/id'
6999 - $ref: '#/components/schemas/VideoInfo'
7005 $ref: '#/components/schemas/id'
7008 - $ref: '#/components/schemas/VideoInfo'
7012 - $ref: '#/components/schemas/ActorInfo'
7018 $ref: '#/components/schemas/id'
7020 $ref: '#/components/schemas/ActorInfo'
7048 NotificationListResponse:
7057 $ref: '#/components/schemas/Notification'
7062 example: peertube-plugin-auth-ldap
7090 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7093 additionalProperties: true
7109 $ref: '#/components/schemas/Plugin'
7116 description: User can stream multiple times in a permanent live
7125 description: RTMP stream key to use to stream into this live video
7129 description: User can stream multiple times in a permanent live
7136 'https://search.example.org/api/v1/search/videos':
7138 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7141 description: successful operation
7145 $ref: '#/components/schemas/VideoListResponse'