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
967 API="https://peertube2.cpy.re/api/v1"
968 USERNAME="<your_username>"
969 PASSWORD="<your_password>"
972 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
973 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
974 curl -s "$API/users/token" \
975 --data client_id="$client_id" \
976 --data client_secret="$client_secret" \
977 --data grant_type=password \
978 --data username="$USERNAME" \
979 --data password="$PASSWORD" \
980 | jq -r ".access_token"
985 description: Revokes your access token and its associated refresh token, destroying your current session.
986 operationId: revokeOAuthToken
993 description: successful operation
997 summary: Register a user
998 operationId: registerUser
1004 description: successful operation
1009 $ref: '#/components/schemas/RegisterUser'
1012 /users/{id}/verify-email:
1014 summary: Verify a user
1015 operationId: verifyUser
1017 Following a user registration, the new user will receive an email asking to click a link
1018 containing a secret.
1023 - $ref: '#/components/parameters/id'
1036 - verificationString
1039 description: successful operation
1041 description: invalid verification string
1043 description: user not found
1045 /users/ask-send-verify-email:
1047 summary: Resend user verification link
1048 operationId: resendEmailToVerifyUser
1054 description: successful operation
1058 summary: Get my user information
1059 operationId: getUserInfo
1067 description: successful operation
1073 $ref: '#/components/schemas/User'
1075 summary: Update my user information
1076 operationId: putUserInfo
1084 description: successful operation
1089 $ref: '#/components/schemas/UpdateMe'
1092 /users/me/videos/imports:
1094 summary: Get video imports of my user
1102 - $ref: '#/components/parameters/start'
1103 - $ref: '#/components/parameters/count'
1104 - $ref: '#/components/parameters/sort'
1107 description: successful operation
1111 $ref: '#/components/schemas/VideoImportsList'
1113 /users/me/video-quota-used:
1115 summary: Get my user used quota
1123 description: successful operation
1131 description: The user video quota used so far in bytes
1132 example: 16810141515
1133 videoQuotaUsedDaily:
1135 description: The user video quota used today in bytes
1138 '/users/me/videos/{videoId}/rating':
1140 summary: Get rate of my user for a video
1150 description: The video id
1152 $ref: '#/components/schemas/Video/properties/id'
1155 description: successful operation
1159 $ref: '#/components/schemas/GetMeVideoRating'
1163 summary: Get videos of my user
1171 - $ref: '#/components/parameters/start'
1172 - $ref: '#/components/parameters/count'
1173 - $ref: '#/components/parameters/sort'
1176 description: successful operation
1180 $ref: '#/components/schemas/VideoListResponse'
1182 /users/me/subscriptions:
1184 summary: Get my user subscriptions
1191 - $ref: '#/components/parameters/start'
1192 - $ref: '#/components/parameters/count'
1193 - $ref: '#/components/parameters/sort'
1196 description: successful operation
1200 $ref: '#/components/schemas/VideoChannelList'
1204 summary: Add subscription to my user
1217 description: uri of the video channels to subscribe to
1223 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1226 description: successful operation
1228 /users/me/subscriptions/exist:
1230 summary: Get if subscriptions exist for my user
1237 - $ref: '#/components/parameters/subscriptionsUris'
1240 description: successful operation
1246 /users/me/subscriptions/videos:
1248 summary: List videos of subscriptions of my user
1256 - $ref: '#/components/parameters/categoryOneOf'
1257 - $ref: '#/components/parameters/isLive'
1258 - $ref: '#/components/parameters/tagsOneOf'
1259 - $ref: '#/components/parameters/tagsAllOf'
1260 - $ref: '#/components/parameters/licenceOneOf'
1261 - $ref: '#/components/parameters/languageOneOf'
1262 - $ref: '#/components/parameters/nsfw'
1263 - $ref: '#/components/parameters/filter'
1264 - $ref: '#/components/parameters/skipCount'
1265 - $ref: '#/components/parameters/start'
1266 - $ref: '#/components/parameters/count'
1267 - $ref: '#/components/parameters/videosSort'
1270 description: successful operation
1274 $ref: '#/components/schemas/VideoListResponse'
1276 '/users/me/subscriptions/{subscriptionHandle}':
1278 summary: Get subscription of my user
1285 - $ref: '#/components/parameters/subscriptionHandle'
1288 description: successful operation
1292 $ref: '#/components/schemas/VideoChannel'
1294 summary: Delete subscription of my user
1301 - $ref: '#/components/parameters/subscriptionHandle'
1304 description: successful operation
1306 /users/me/notifications:
1308 summary: List my notifications
1316 description: only list unread notifications
1319 - $ref: '#/components/parameters/start'
1320 - $ref: '#/components/parameters/count'
1321 - $ref: '#/components/parameters/sort'
1324 description: successful operation
1328 $ref: '#/components/schemas/NotificationListResponse'
1330 /users/me/notifications/read:
1332 summary: Mark notifications as read by their id
1345 description: ids of the notifications to mark as read
1352 description: successful operation
1354 /users/me/notifications/read-all:
1356 summary: Mark all my notification as read
1363 description: successful operation
1365 /users/me/notification-settings:
1367 summary: Update my notification settings
1378 newVideoFromSubscription:
1379 $ref: '#/components/schemas/NotificationSettingValue'
1380 newCommentOnMyVideo:
1381 $ref: '#/components/schemas/NotificationSettingValue'
1383 $ref: '#/components/schemas/NotificationSettingValue'
1384 videoAutoBlacklistAsModerator:
1385 $ref: '#/components/schemas/NotificationSettingValue'
1387 $ref: '#/components/schemas/NotificationSettingValue'
1389 $ref: '#/components/schemas/NotificationSettingValue'
1390 myVideoImportFinished:
1391 $ref: '#/components/schemas/NotificationSettingValue'
1393 $ref: '#/components/schemas/NotificationSettingValue'
1394 newUserRegistration:
1395 $ref: '#/components/schemas/NotificationSettingValue'
1397 $ref: '#/components/schemas/NotificationSettingValue'
1398 newInstanceFollower:
1399 $ref: '#/components/schemas/NotificationSettingValue'
1400 autoInstanceFollowing:
1401 $ref: '#/components/schemas/NotificationSettingValue'
1404 description: successful operation
1406 /users/me/history/videos:
1408 summary: List watched videos history
1414 - $ref: '#/components/parameters/start'
1415 - $ref: '#/components/parameters/count'
1416 - $ref: '#/components/parameters/search'
1419 description: successful operation
1423 $ref: '#/components/schemas/VideoListResponse'
1425 /users/me/history/videos/remove:
1427 summary: Clear video history
1434 multipart/form-data:
1439 description: history before this date will be deleted
1444 description: successful operation
1446 /users/me/avatar/pick:
1448 summary: Update my user avatar
1455 description: successful operation
1462 $ref: '#/components/schemas/ActorImage'
1464 description: image file too large
1466 X-File-Maximum-Size:
1470 description: Maximum file size for the avatar
1473 multipart/form-data:
1478 description: The file to upload
1483 contentType: image/png, image/jpeg
1487 summary: Delete my avatar
1494 description: successful operation
1498 summary: List video ownership changes
1500 - Video Ownership Change
1505 description: successful operation
1507 '/videos/ownership/{id}/accept':
1509 summary: Accept ownership change request
1511 - Video Ownership Change
1515 - $ref: '#/components/parameters/idOrUUID'
1518 description: successful operation
1520 description: cannot terminate an ownership change of another user
1522 description: video owneship change not found
1524 '/videos/ownership/{id}/refuse':
1526 summary: Refuse ownership change request
1528 - Video Ownership Change
1532 - $ref: '#/components/parameters/idOrUUID'
1535 description: successful operation
1537 description: cannot terminate an ownership change of another user
1539 description: video owneship change not found
1541 '/videos/{id}/give-ownership':
1543 summary: Request ownership change
1545 - Video Ownership Change
1549 - $ref: '#/components/parameters/idOrUUID'
1553 application/x-www-form-urlencoded:
1563 description: successful operation
1565 description: changing video ownership to a remote account is not supported yet
1567 description: video not found
1571 summary: List videos
1572 operationId: getVideos
1576 - $ref: '#/components/parameters/categoryOneOf'
1577 - $ref: '#/components/parameters/isLive'
1578 - $ref: '#/components/parameters/tagsOneOf'
1579 - $ref: '#/components/parameters/tagsAllOf'
1580 - $ref: '#/components/parameters/licenceOneOf'
1581 - $ref: '#/components/parameters/languageOneOf'
1582 - $ref: '#/components/parameters/nsfw'
1583 - $ref: '#/components/parameters/filter'
1584 - $ref: '#/components/parameters/skipCount'
1585 - $ref: '#/components/parameters/start'
1586 - $ref: '#/components/parameters/count'
1587 - $ref: '#/components/parameters/videosSort'
1590 description: successful operation
1594 $ref: '#/components/schemas/VideoListResponse'
1598 summary: List available video categories
1599 operationId: getCategories
1604 description: successful operation
1613 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1617 summary: List available video licences
1618 operationId: getLicences
1623 description: successful operation
1632 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1636 summary: List available video languages
1637 operationId: getLanguages
1642 description: successful operation
1651 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1655 summary: List available video privacy policies
1656 operationId: getPrivacyPolicies
1661 description: successful operation
1670 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1674 summary: Update a video
1675 operationId: putVideo
1681 - $ref: '#/components/parameters/idOrUUID'
1684 description: successful operation
1687 multipart/form-data:
1692 description: Video thumbnail file
1696 description: Video preview file
1700 $ref: '#/components/schemas/VideoCategorySet'
1702 $ref: '#/components/schemas/VideoLicenceSet'
1704 $ref: '#/components/schemas/VideoLanguageSet'
1706 $ref: '#/components/schemas/VideoPrivacySet'
1708 description: Video description
1711 description: Whether or not we wait transcoding before publish the video
1714 description: A text tell the audience how to support the video creator
1715 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1718 description: Whether or not this video contains sensitive content
1721 description: Video name
1726 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1735 description: Enable or disable comments for this video
1737 originallyPublishedAt:
1738 description: Date when the content was originally published
1742 $ref: '#/components/schemas/VideoScheduledUpdate'
1745 contentType: image/jpeg
1747 contentType: image/jpeg
1749 summary: Get a video
1750 operationId: getVideo
1754 - $ref: '#/components/parameters/idOrUUID'
1757 description: successful operation
1761 $ref: '#/components/schemas/VideoDetails'
1763 summary: Delete a video
1764 operationId: delVideo
1770 - $ref: '#/components/parameters/idOrUUID'
1773 description: successful operation
1775 '/videos/{id}/description':
1777 summary: Get complete video description
1778 operationId: getVideoDesc
1782 - $ref: '#/components/parameters/idOrUUID'
1785 description: successful operation
1794 **[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)**
1796 '/videos/{id}/views':
1798 summary: Add a view to a video
1802 - $ref: '#/components/parameters/idOrUUID'
1805 description: successful operation
1807 '/videos/{id}/watching':
1809 summary: Set watching progress of a video
1815 - $ref: '#/components/parameters/idOrUUID'
1820 $ref: '#/components/schemas/UserWatchingVideo'
1824 description: successful operation
1828 summary: Upload a video
1829 description: Uses a single request to upload a video.
1830 operationId: uploadLegacy
1838 description: successful operation
1842 $ref: '#/components/schemas/VideoUploadResponse'
1844 description: video didn't pass upload filter
1846 description: upload has timed out
1848 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1850 X-File-Maximum-Size:
1854 description: Maximum file size for the video
1856 description: video type unsupported
1858 description: video unreadable
1861 multipart/form-data:
1863 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1866 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1868 contentType: image/jpeg
1870 contentType: image/jpeg
1875 USERNAME="<your_username>"
1876 PASSWORD="<your_password>"
1877 FILE_PATH="<your_file_path>"
1878 CHANNEL_ID="<your_channel_id>"
1880 API="https://peertube2.cpy.re/api/v1"
1883 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1884 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1885 token=$(curl -s "$API/users/token" \
1886 --data client_id="$client_id" \
1887 --data client_secret="$client_secret" \
1888 --data grant_type=password \
1889 --data username="$USERNAME" \
1890 --data password="$PASSWORD" \
1891 | jq -r ".access_token")
1894 curl -s "$API/videos/upload" \
1895 -H "Authorization: Bearer $token" \
1897 --form videofile=@"$FILE_PATH" \
1898 --form channelId=$CHANNEL_ID \
1901 /videos/upload-resumable:
1903 summary: Initialize the resumable upload of a video
1904 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1905 operationId: uploadResumableInit
1912 - name: X-Upload-Content-Length
1918 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1919 - name: X-Upload-Content-Type
1926 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1931 $ref: '#/components/schemas/VideoUploadRequestResumable'
1934 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1936 description: created
1942 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1948 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1950 description: video type unsupported
1952 summary: Send chunk for the resumable upload of a video
1953 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
1954 operationId: uploadResumable
1965 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1966 not valid anymore and you need to initialize a new upload.
1969 - name: Content-Range
1973 example: bytes 0-262143/2469036
1976 Specifies the bytes in the file that the request is uploading.
1978 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1979 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1980 - name: Content-Length
1987 Size of the chunk that the request is sending.
1989 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)
1990 doesn't mandate for chunks to have the same size throughout the upload sequence.
1992 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1993 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1996 application/octet-stream:
2002 description: last chunk received
2010 $ref: '#/components/schemas/VideoUploadResponse'
2012 description: resume incomplete
2017 example: bytes=0-262143
2023 description: video didn't pass upload filter
2025 description: video file too large, due to quota or max body size limit set by the reverse-proxy
2027 description: video unreadable
2029 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2030 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2031 operationId: uploadResumableCancel
2042 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2043 not valid anymore and the upload session has already been deleted with its data ;-)
2046 - name: Content-Length
2054 description: upload cancelled
2063 summary: Import a video
2064 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2065 operationId: importVideo
2073 multipart/form-data:
2075 $ref: '#/components/schemas/VideoCreateImport'
2078 contentType: application/x-bittorrent
2080 contentType: image/jpeg
2082 contentType: image/jpeg
2085 description: successful operation
2089 $ref: '#/components/schemas/VideoUploadResponse'
2091 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2093 description: video didn't pass pre-import filter
2095 description: HTTP or Torrent/magnetURI import not enabled
2099 summary: Create a live
2100 operationId: addLive
2108 description: successful operation
2112 $ref: '#/components/schemas/VideoUploadResponse'
2114 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2117 multipart/form-data:
2122 description: Channel id that will contain this live video
2127 description: User can stream multiple times in a permanent live
2130 description: Live video/replay thumbnail file
2134 description: Live video/replay preview file
2138 $ref: '#/components/schemas/VideoPrivacySet'
2140 $ref: '#/components/schemas/VideoCategorySet'
2142 $ref: '#/components/schemas/VideoLicenceSet'
2144 $ref: '#/components/schemas/VideoLanguageSet'
2146 description: Live video/replay description
2149 description: A text tell the audience how to support the creator
2150 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2153 description: Whether or not this live video/replay contains sensitive content
2156 description: Live video/replay name
2161 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2170 description: Enable or disable comments for this live video/replay
2173 description: Enable or disable downloading for the replay of this live
2180 contentType: image/jpeg
2182 contentType: image/jpeg
2186 summary: Get information about a live
2187 operationId: getLiveId
2194 - $ref: '#/components/parameters/idOrUUID'
2197 description: successful operation
2201 $ref: '#/components/schemas/LiveVideoResponse'
2203 summary: Update information about a live
2204 operationId: updateLiveId
2211 - $ref: '#/components/parameters/idOrUUID'
2216 $ref: '#/components/schemas/LiveVideoUpdate'
2219 description: successful operation
2221 description: bad parameters or trying to update a live that has already started
2223 description: trying to save replay of the live but saving replay is not enabled on the instance
2227 summary: List my abuses
2228 operationId: getMyAbuses
2237 description: only list the report with this id
2243 $ref: '#/components/schemas/AbuseStateSet'
2244 - $ref: '#/components/parameters/abusesSort'
2245 - $ref: '#/components/parameters/start'
2246 - $ref: '#/components/parameters/count'
2249 description: successful operation
2261 $ref: '#/components/schemas/Abuse'
2265 summary: List abuses
2266 operationId: getAbuses
2276 description: only list the report with this id
2279 - name: predefinedReason
2281 description: predefined reason the listed reports should contain
2283 $ref: '#/components/schemas/PredefinedAbuseReasons'
2286 description: plain search that will match with video titles, reporter names and more
2292 $ref: '#/components/schemas/AbuseStateSet'
2293 - name: searchReporter
2295 description: only list reports of a specific reporter
2298 - name: searchReportee
2299 description: only list reports of a specific reportee
2305 description: only list reports of a specific video
2308 - name: searchVideoChannel
2310 description: only list reports of a specific video channel
2315 description: only list blacklisted or deleted videos
2323 description: only list account, comment or video reports
2330 - $ref: '#/components/parameters/start'
2331 - $ref: '#/components/parameters/count'
2332 - $ref: '#/components/parameters/abusesSort'
2335 description: successful operation
2347 $ref: '#/components/schemas/Abuse'
2349 summary: Report an abuse
2362 description: Reason why the user reports this video
2367 $ref: '#/components/schemas/PredefinedAbuseReasons'
2372 description: Video id to report
2374 - $ref: '#/components/schemas/Video/properties/id'
2378 description: Timestamp in the video that marks the beginning of the report
2383 description: Timestamp in the video that marks the ending of the report
2389 description: Comment id to report
2391 - $ref: '#/components/schemas/VideoComment/properties/id'
2396 description: Account id to report
2402 description: successful operation
2412 $ref: '#/components/schemas/id'
2414 description: incorrect request parameters
2416 '/abuses/{abuseId}':
2418 summary: Update an abuse
2426 - $ref: '#/components/parameters/abuseId'
2434 $ref: '#/components/schemas/AbuseStateSet'
2437 description: Update the report comment visible only to the moderation team
2442 description: successful operation
2444 description: abuse not found
2448 summary: Delete an abuse
2454 - $ref: '#/components/parameters/abuseId'
2457 description: successful operation
2459 description: block not found
2461 '/abuses/{abuseId}/messages':
2463 summary: List messages of an abuse
2469 - $ref: '#/components/parameters/abuseId'
2472 description: successful operation
2484 $ref: '#/components/schemas/AbuseMessage'
2486 summary: Add message to an abuse
2492 - $ref: '#/components/parameters/abuseId'
2501 description: Message to send
2509 description: successful operation
2511 description: incorrect request parameters
2513 '/abuses/{abuseId}/messages/{abuseMessageId}':
2515 summary: Delete an abuse message
2521 - $ref: '#/components/parameters/abuseId'
2522 - $ref: '#/components/parameters/abuseMessageId'
2525 description: successful operation
2527 '/videos/{id}/blacklist':
2529 summary: Block a video
2530 operationId: addVideoBlock
2538 - $ref: '#/components/parameters/idOrUUID'
2541 description: successful operation
2543 summary: Unblock a video by its id
2544 operationId: delVideoBlock
2552 - $ref: '#/components/parameters/idOrUUID'
2555 description: successful operation
2557 description: block not found
2563 summary: List video blocks
2564 operationId: getVideoBlocks
2573 list only blocks that match this type:
2577 - `2`: automatic block that needs review
2585 description: plain search that will match with video titles, and more
2588 - $ref: '#/components/parameters/start'
2589 - $ref: '#/components/parameters/count'
2590 - $ref: '#/components/parameters/blacklistsSort'
2593 description: successful operation
2605 $ref: '#/components/schemas/VideoBlacklist'
2607 /videos/{id}/captions:
2609 summary: List captions of a video
2610 operationId: getVideoCaptions
2614 - $ref: '#/components/parameters/idOrUUID'
2617 description: successful operation
2629 $ref: '#/components/schemas/VideoCaption'
2631 /videos/{id}/captions/{captionLanguage}:
2633 summary: Add or replace a video caption
2634 operationId: addVideoCaption
2641 - $ref: '#/components/parameters/idOrUUID'
2642 - $ref: '#/components/parameters/captionLanguage'
2645 multipart/form-data:
2650 description: The file to upload.
2655 contentType: text/vtt, application/x-subrip, text/plain
2658 description: successful operation
2660 description: video or language not found
2662 summary: Delete a video caption
2663 operationId: delVideoCaption
2670 - $ref: '#/components/parameters/idOrUUID'
2671 - $ref: '#/components/parameters/captionLanguage'
2674 description: successful operation
2676 description: video or language or caption for that language not found
2680 summary: List video channels
2681 operationId: getVideoChannels
2685 - $ref: '#/components/parameters/start'
2686 - $ref: '#/components/parameters/count'
2687 - $ref: '#/components/parameters/sort'
2690 description: successful operation
2694 $ref: '#/components/schemas/VideoChannelList'
2696 summary: Create a video channel
2697 operationId: addVideoChannel
2704 description: successful operation
2714 $ref: '#/components/schemas/VideoChannel/properties/id'
2719 $ref: '#/components/schemas/VideoChannelCreate'
2721 '/video-channels/{channelHandle}':
2723 summary: Get a video channel
2724 operationId: getVideoChannel
2728 - $ref: '#/components/parameters/channelHandle'
2731 description: successful operation
2735 $ref: '#/components/schemas/VideoChannel'
2737 summary: Update a video channel
2738 operationId: putVideoChannel
2744 - $ref: '#/components/parameters/channelHandle'
2747 description: successful operation
2752 $ref: '#/components/schemas/VideoChannelUpdate'
2754 summary: Delete a video channel
2755 operationId: delVideoChannel
2761 - $ref: '#/components/parameters/channelHandle'
2764 description: successful operation
2766 '/video-channels/{channelHandle}/videos':
2768 summary: List videos of a video channel
2769 operationId: getVideoChannelVideos
2774 - $ref: '#/components/parameters/channelHandle'
2775 - $ref: '#/components/parameters/categoryOneOf'
2776 - $ref: '#/components/parameters/isLive'
2777 - $ref: '#/components/parameters/tagsOneOf'
2778 - $ref: '#/components/parameters/tagsAllOf'
2779 - $ref: '#/components/parameters/licenceOneOf'
2780 - $ref: '#/components/parameters/languageOneOf'
2781 - $ref: '#/components/parameters/nsfw'
2782 - $ref: '#/components/parameters/filter'
2783 - $ref: '#/components/parameters/skipCount'
2784 - $ref: '#/components/parameters/start'
2785 - $ref: '#/components/parameters/count'
2786 - $ref: '#/components/parameters/videosSort'
2789 description: successful operation
2793 $ref: '#/components/schemas/VideoListResponse'
2795 '/video-channels/{channelHandle}/avatar/pick':
2797 summary: Update channel avatar
2803 - $ref: '#/components/parameters/channelHandle'
2806 description: successful operation
2813 $ref: '#/components/schemas/ActorImage'
2815 description: image file too large
2817 X-File-Maximum-Size:
2821 description: Maximum file size for the avatar
2824 multipart/form-data:
2829 description: The file to upload.
2834 contentType: image/png, image/jpeg
2836 '/video-channels/{channelHandle}/avatar':
2838 summary: Delete channel avatar
2844 - $ref: '#/components/parameters/channelHandle'
2847 description: successful operation
2849 '/video-channels/{channelHandle}/banner/pick':
2851 summary: Update channel banner
2857 - $ref: '#/components/parameters/channelHandle'
2860 description: successful operation
2867 $ref: '#/components/schemas/ActorImage'
2869 description: image file too large
2871 X-File-Maximum-Size:
2875 description: Maximum file size for the banner
2878 multipart/form-data:
2883 description: The file to upload.
2888 contentType: image/png, image/jpeg
2890 '/video-channels/{channelHandle}/banner':
2892 summary: Delete channel banner
2898 - $ref: '#/components/parameters/channelHandle'
2901 description: successful operation
2903 /video-playlists/privacies:
2905 summary: List available playlist privacy policies
2906 operationId: getPlaylistPrivacyPolicies
2911 description: successful operation
2920 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2924 summary: List video playlists
2925 operationId: getPlaylists
2929 - $ref: '#/components/parameters/start'
2930 - $ref: '#/components/parameters/count'
2931 - $ref: '#/components/parameters/sort'
2934 description: successful operation
2946 $ref: '#/components/schemas/VideoPlaylist'
2948 summary: Create a video playlist
2949 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2950 operationId: addPlaylist
2957 description: successful operation
2967 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2969 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2972 multipart/form-data:
2977 description: Video playlist display name
2982 description: Video playlist thumbnail file
2986 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2988 description: Video playlist description
2994 - $ref: '#/components/schemas/id'
2995 description: Video channel in which the playlist will be published
3000 contentType: image/jpeg
3002 /video-playlists/{playlistId}:
3004 summary: Get a video playlist
3008 - $ref: '#/components/parameters/playlistId'
3011 description: successful operation
3015 $ref: '#/components/schemas/VideoPlaylist'
3017 summary: Update a video playlist
3018 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3025 description: successful operation
3027 - $ref: '#/components/parameters/playlistId'
3030 multipart/form-data:
3035 description: Video playlist display name
3040 description: Video playlist thumbnail file
3044 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3046 description: Video playlist description
3050 - $ref: '#/components/schemas/id'
3051 description: Video channel in which the playlist will be published
3054 contentType: image/jpeg
3056 summary: Delete a video playlist
3062 - $ref: '#/components/parameters/playlistId'
3065 description: successful operation
3067 /video-playlists/{playlistId}/videos:
3069 summary: 'List videos of a playlist'
3070 operationId: getVideoPlaylistVideos
3075 - $ref: '#/components/parameters/playlistId'
3078 description: successful operation
3082 $ref: '#/components/schemas/VideoListResponse'
3084 summary: Add a video in a playlist
3085 operationId: addVideoPlaylistVideo
3092 - $ref: '#/components/parameters/playlistId'
3095 description: successful operation
3101 videoPlaylistElement:
3115 - $ref: '#/components/schemas/Video/properties/uuid'
3116 - $ref: '#/components/schemas/Video/properties/id'
3117 description: Video to add in the playlist
3121 description: Start the video at this specific timestamp
3125 description: Stop the video at this specific timestamp
3129 /video-playlists/{playlistId}/videos/reorder:
3131 summary: 'Reorder a playlist'
3132 operationId: reorderVideoPlaylist
3138 - $ref: '#/components/parameters/playlistId'
3141 description: successful operation
3150 description: 'Start position of the element to reorder'
3152 insertAfterPosition:
3154 description: 'New position for the block to reorder, to add the block before the first element'
3158 description: 'How many element from `startPosition` to reorder'
3162 - insertAfterPosition
3164 /video-playlists/{playlistId}/videos/{playlistElementId}:
3166 summary: Update a playlist element
3167 operationId: putVideoPlaylistVideo
3173 - $ref: '#/components/parameters/playlistId'
3174 - $ref: '#/components/parameters/playlistElementId'
3177 description: successful operation
3187 description: Start the video at this specific timestamp
3191 description: Stop the video at this specific timestamp
3193 summary: Delete an element from a playlist
3194 operationId: delVideoPlaylistVideo
3200 - $ref: '#/components/parameters/playlistId'
3201 - $ref: '#/components/parameters/playlistElementId'
3204 description: successful operation
3206 '/users/me/video-playlists/videos-exist':
3208 summary: Check video exists in my playlists
3217 description: The video ids to check
3221 $ref: '#/components/schemas/Video/properties/id'
3224 description: successful operation
3246 '/accounts/{name}/video-channels':
3248 summary: List video channels of an account
3253 - $ref: '#/components/parameters/name'
3256 description: include view statistics for the last 30 days (only if authentified as the account user)
3259 - $ref: '#/components/parameters/start'
3260 - $ref: '#/components/parameters/count'
3261 - $ref: '#/components/parameters/sort'
3264 description: successful operation
3268 $ref: '#/components/schemas/VideoChannelList'
3270 '/accounts/{name}/ratings':
3272 summary: List ratings of an account
3278 - $ref: '#/components/parameters/name'
3279 - $ref: '#/components/parameters/start'
3280 - $ref: '#/components/parameters/count'
3281 - $ref: '#/components/parameters/sort'
3285 description: Optionally filter which ratings to retrieve
3293 description: successful operation
3299 $ref: '#/components/schemas/VideoRating'
3301 '/videos/{id}/comment-threads':
3303 summary: List threads of a video
3307 - $ref: '#/components/parameters/idOrUUID'
3308 - $ref: '#/components/parameters/start'
3309 - $ref: '#/components/parameters/count'
3310 - $ref: '#/components/parameters/commentsSort'
3313 description: successful operation
3317 $ref: '#/components/schemas/CommentThreadResponse'
3319 summary: Create a thread
3325 - $ref: '#/components/parameters/idOrUUID'
3328 description: successful operation
3332 $ref: '#/components/schemas/CommentThreadPostResponse'
3334 description: video does not exist
3343 - $ref: '#/components/schemas/VideoComment/properties/text'
3349 '/videos/{id}/comment-threads/{threadId}':
3351 summary: Get a thread
3355 - $ref: '#/components/parameters/idOrUUID'
3356 - $ref: '#/components/parameters/threadId'
3359 description: successful operation
3363 $ref: '#/components/schemas/VideoCommentThreadTree'
3365 '/videos/{id}/comments/{commentId}':
3367 summary: Reply to a thread of a video
3373 - $ref: '#/components/parameters/idOrUUID'
3374 - $ref: '#/components/parameters/commentId'
3377 description: successful operation
3381 $ref: '#/components/schemas/CommentThreadPostResponse'
3383 description: thread or video does not exist
3392 - $ref: '#/components/schemas/VideoComment/properties/text'
3398 summary: Delete a comment or a reply
3404 - $ref: '#/components/parameters/idOrUUID'
3405 - $ref: '#/components/parameters/commentId'
3408 description: successful operation
3410 description: cannot remove comment of another user
3412 description: comment or video does not exist
3414 description: comment is already deleted
3416 '/videos/{id}/rate':
3418 summary: Like/dislike a video
3424 - $ref: '#/components/parameters/idOrUUID'
3440 description: successful operation
3442 description: video does not exist
3448 summary: Search videos
3449 operationId: searchVideos
3454 allowEmptyValue: false
3456 String to search. If the user can make a remote URI search, and the string is an URI then the
3457 PeerTube instance will fetch the remote object and add it to its database. Then,
3458 you can use the REST API to fetch the complete video information and interact with it.
3461 - $ref: '#/components/parameters/categoryOneOf'
3462 - $ref: '#/components/parameters/isLive'
3463 - $ref: '#/components/parameters/tagsOneOf'
3464 - $ref: '#/components/parameters/tagsAllOf'
3465 - $ref: '#/components/parameters/licenceOneOf'
3466 - $ref: '#/components/parameters/languageOneOf'
3467 - $ref: '#/components/parameters/nsfw'
3468 - $ref: '#/components/parameters/filter'
3469 - $ref: '#/components/parameters/skipCount'
3470 - $ref: '#/components/parameters/start'
3471 - $ref: '#/components/parameters/count'
3472 - $ref: '#/components/parameters/searchTarget'
3473 - $ref: '#/components/parameters/videosSearchSort'
3476 description: Get videos that are published after this date
3482 description: Get videos that are published before this date
3486 - name: originallyPublishedStartDate
3488 description: Get videos that are originally published after this date
3492 - name: originallyPublishedEndDate
3494 description: Get videos that are originally published before this date
3500 description: Get videos that have this minimum duration
3505 description: Get videos that have this maximum duration
3509 'searchTarget === search-index':
3510 $ref: '#/components/callbacks/searchIndex'
3513 description: successful operation
3517 $ref: '#/components/schemas/VideoListResponse'
3519 description: search index unavailable
3521 /search/video-channels:
3525 summary: Search channels
3526 operationId: searchChannels
3532 String to search. If the user can make a remote URI search, and the string is an URI then the
3533 PeerTube instance will fetch the remote object and add it to its database. Then,
3534 you can use the REST API to fetch the complete channel information and interact with it.
3537 - $ref: '#/components/parameters/start'
3538 - $ref: '#/components/parameters/count'
3539 - $ref: '#/components/parameters/searchTarget'
3540 - $ref: '#/components/parameters/sort'
3542 'searchTarget === search-index':
3543 $ref: '#/components/callbacks/searchIndex'
3546 description: successful operation
3550 $ref: '#/components/schemas/VideoChannelList'
3552 description: search index unavailable
3554 /server/blocklist/accounts:
3558 summary: List account blocks
3563 - $ref: '#/components/parameters/start'
3564 - $ref: '#/components/parameters/count'
3565 - $ref: '#/components/parameters/sort'
3568 description: successful operation
3572 summary: Block an account
3584 example: chocobozzz@example.org
3585 description: account to block, in the form `username@domain`
3590 description: successful operation
3592 description: self-blocking forbidden
3594 '/server/blocklist/accounts/{accountName}':
3598 summary: Unblock an account by its handle
3606 description: account to unblock, in the form `username@domain`
3611 description: successful operation
3613 description: account or account block does not exist
3615 /server/blocklist/servers:
3619 summary: List server blocks
3624 - $ref: '#/components/parameters/start'
3625 - $ref: '#/components/parameters/count'
3626 - $ref: '#/components/parameters/sort'
3629 description: successful operation
3633 summary: Block a server
3646 description: server domain to block
3651 description: successful operation
3653 description: self-blocking forbidden
3655 '/server/blocklist/servers/{host}':
3659 summary: Unblock a server by its domain
3667 description: server domain to unblock
3673 description: successful operation
3675 description: account block does not exist
3677 /server/redundancy/{host}:
3680 - Instance Redundancy
3681 summary: Update a server redundancy policy
3689 description: server domain to mirror
3701 description: allow mirroring of the host's local videos
3706 description: successful operation
3708 description: server is not already known
3710 /server/redundancy/videos:
3714 summary: List videos being mirrored
3715 operationId: getMirroredVideos
3723 description: direction of the mirror
3729 - $ref: '#/components/parameters/start'
3730 - $ref: '#/components/parameters/count'
3731 - $ref: '#/components/parameters/videoRedundanciesSort'
3734 description: successful operation
3740 $ref: '#/components/schemas/VideoRedundancy'
3744 summary: Mirror a video
3745 operationId: putMirroredVideo
3756 $ref: '#/components/schemas/Video/properties/id'
3761 description: successful operation
3763 description: cannot mirror a local video
3765 description: video does not exist
3767 description: video is already mirrored
3769 /server/redundancy/videos/{redundancyId}:
3773 summary: Delete a mirror done on a video
3774 operationId: delMirroredVideo
3779 - name: redundancyId
3782 description: id of an existing redundancy on a video
3787 description: successful operation
3789 description: video redundancy not found
3791 '/feeds/video-comments.{format}':
3795 summary: List comments on videos
3796 operationId: getSyndicatedComments
3801 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3814 description: 'limit listing to a specific video'
3819 description: 'limit listing to a specific account'
3824 description: 'limit listing to a specific account'
3827 - name: videoChannelId
3829 description: 'limit listing to a specific video channel'
3832 - name: videoChannelName
3834 description: 'limit listing to a specific video channel'
3839 description: successful operation
3844 default: 'max-age=900' # 15 min cache
3848 $ref: '#/components/schemas/VideoCommentsForXML'
3851 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3852 application/rss+xml:
3854 $ref: '#/components/schemas/VideoCommentsForXML'
3857 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3860 $ref: '#/components/schemas/VideoCommentsForXML'
3863 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3864 application/atom+xml:
3866 $ref: '#/components/schemas/VideoCommentsForXML'
3869 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3875 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3877 x-summary: field inconsistencies
3880 - videoId filter is mixed with a channel filter
3882 description: video, video channel or account not found
3884 description: accept header unsupported
3886 '/feeds/videos.{format}':
3890 summary: List videos
3891 operationId: getSyndicatedVideos
3896 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3909 description: 'limit listing to a specific account'
3914 description: 'limit listing to a specific account'
3917 - name: videoChannelId
3919 description: 'limit listing to a specific video channel'
3922 - name: videoChannelName
3924 description: 'limit listing to a specific video channel'
3927 - $ref: '#/components/parameters/sort'
3928 - $ref: '#/components/parameters/nsfw'
3929 - $ref: '#/components/parameters/filter'
3932 description: successful operation
3937 default: 'max-age=900' # 15 min cache
3941 $ref: '#/components/schemas/VideosForXML'
3944 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3945 application/rss+xml:
3947 $ref: '#/components/schemas/VideosForXML'
3950 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3953 $ref: '#/components/schemas/VideosForXML'
3956 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3957 application/atom+xml:
3959 $ref: '#/components/schemas/VideosForXML'
3962 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3968 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3970 description: video channel or account not found
3972 description: accept header unsupported
3974 '/feeds/subscriptions.{format}':
3979 summary: List videos of subscriptions tied to a token
3980 operationId: getSyndicatedSubscriptionVideos
3985 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3998 description: limit listing to a specific account
4004 description: private token allowing access
4008 - $ref: '#/components/parameters/sort'
4009 - $ref: '#/components/parameters/nsfw'
4010 - $ref: '#/components/parameters/filter'
4013 description: successful operation
4018 default: 'max-age=900' # 15 min cache
4022 $ref: '#/components/schemas/VideosForXML'
4023 application/rss+xml:
4025 $ref: '#/components/schemas/VideosForXML'
4028 $ref: '#/components/schemas/VideosForXML'
4029 application/atom+xml:
4031 $ref: '#/components/schemas/VideosForXML'
4036 description: accept header unsupported
4042 summary: List plugins
4043 operationId: getPlugins
4056 - $ref: '#/components/parameters/start'
4057 - $ref: '#/components/parameters/count'
4058 - $ref: '#/components/parameters/sort'
4061 description: successful operation
4065 $ref: '#/components/schemas/PluginResponse'
4071 summary: List available plugins
4072 operationId: getAvailablePlugins
4085 - name: currentPeerTubeEngine
4089 - $ref: '#/components/parameters/start'
4090 - $ref: '#/components/parameters/count'
4091 - $ref: '#/components/parameters/sort'
4094 description: successful operation
4098 $ref: '#/components/schemas/PluginResponse'
4100 description: plugin index unavailable
4106 summary: Install a plugin
4107 operationId: addPlugin
4120 example: peertube-plugin-auth-ldap
4123 additionalProperties: false
4130 additionalProperties: false
4133 description: successful operation
4135 description: should have either `npmName` or `path` set
4141 summary: Update a plugin
4142 operationId: updatePlugin
4155 example: peertube-plugin-auth-ldap
4158 additionalProperties: false
4165 additionalProperties: false
4168 description: successful operation
4170 description: should have either `npmName` or `path` set
4172 description: existing plugin not found
4178 summary: Uninstall a plugin
4179 operationId: uninstallPlugin
4191 description: name of the plugin/theme in its package.json
4192 example: peertube-plugin-auth-ldap
4197 description: successful operation
4199 description: existing plugin not found
4205 summary: Get a plugin
4206 operationId: getPlugin
4211 - $ref: '#/components/parameters/npmName'
4214 description: successful operation
4218 $ref: '#/components/schemas/Plugin'
4220 description: plugin not found
4222 /plugins/{npmName}/settings:
4226 summary: Set a plugin's settings
4231 - $ref: '#/components/parameters/npmName'
4240 additionalProperties: true
4243 description: successful operation
4245 description: plugin not found
4247 /plugins/{npmName}/public-settings:
4251 summary: Get a plugin's public settings
4253 - $ref: '#/components/parameters/npmName'
4256 description: successful operation
4261 additionalProperties: true
4263 description: plugin not found
4265 /plugins/{npmName}/registered-settings:
4269 summary: Get a plugin's registered settings
4274 - $ref: '#/components/parameters/npmName'
4277 description: successful operation
4282 additionalProperties: true
4284 description: plugin not found
4287 - url: 'https://peertube2.cpy.re/api/v1'
4288 description: Live Test Server (live data - latest nightly version)
4289 - url: 'https://peertube3.cpy.re/api/v1'
4290 description: Live Test Server (live data - latest RC version)
4291 - url: 'https://peertube.cpy.re/api/v1'
4292 description: Live Test Server (live data - stable version)
4299 description: Offset used to paginate results
4307 description: "Number of items to return"
4317 description: Sort column
4325 description: Plain text search, applied to various parts of the model depending on endpoint
4333 If the administrator enabled search index support, you can override the default search target.
4336 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4337 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4338 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4339 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4340 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4341 * 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
4342 the data from the origin instance API
4352 description: Sort videos by criteria
4368 description: Sort videos by criteria
4383 description: Sort comments by criteria
4393 description: Sort blacklists by criteria
4409 description: Plain text search that will match with user usernames or emails
4416 description: Filter results down to (un)banned users
4423 description: Sort users by criteria
4434 description: Sort abuses by criteria
4441 videoRedundanciesSort:
4445 description: Sort abuses by criteria
4454 description: The username or handle of the account
4457 example: chocobozzz | chocobozzz@example.org
4462 description: The user id
4464 $ref: '#/components/schemas/id'
4469 description: The object id or uuid
4472 - $ref: '#/components/schemas/id'
4473 - $ref: '#/components/schemas/UUIDv4'
4478 description: Playlist id
4480 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4482 name: playlistElementId
4485 description: Playlist element id
4487 $ref: '#/components/schemas/id'
4492 description: Abuse id
4494 $ref: '#/components/schemas/Abuse/properties/id'
4496 name: abuseMessageId
4499 description: Abuse message id
4501 $ref: '#/components/schemas/AbuseMessage/properties/id'
4503 name: captionLanguage
4506 description: The caption language
4508 $ref: '#/components/schemas/VideoLanguageSet'
4513 description: The video channel handle
4516 example: my_username | my_username@example.com
4518 name: subscriptionHandle
4521 description: The subscription handle
4524 example: my_username | my_username@example.com
4529 description: The thread id (root comment id)
4536 description: The comment id
4538 $ref: '#/components/schemas/VideoComment/properties/id'
4543 description: whether or not the video is a live
4550 description: category id of the video (see [/videos/categories](#operation/getCategories))
4553 - $ref: '#/components/schemas/VideoCategorySet'
4556 $ref: '#/components/schemas/VideoCategorySet'
4563 description: tag(s) of the video
4577 description: tag(s) of the video, where all should be present in the video
4590 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4593 - $ref: '#/components/schemas/VideoLanguageSet'
4596 $ref: '#/components/schemas/VideoLanguageSet'
4603 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4606 - $ref: '#/components/schemas/VideoLicenceSet'
4609 $ref: '#/components/schemas/VideoLicenceSet'
4616 description: if you don't need the `total` in the response
4627 description: whether to include nsfw videos, if any
4638 Special filters which might require special rights:
4639 * `local` - only videos local to the instance
4640 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4641 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4651 description: list of uris to check if each is part of the user subscriptions
4661 description: name of the plugin/theme on npmjs.com or in its package.json
4664 example: peertube-plugin-auth-ldap
4669 description: job type
4673 - activitypub-follow
4674 - activitypub-http-broadcast
4675 - activitypub-http-fetcher
4676 - activitypub-http-unicast
4682 - activitypub-refresher
4707 Authenticating via OAuth requires the following steps:
4708 - Have an activated account
4709 - [Generate] an access token for that account at `/api/v1/users/token`.
4710 - Make requests with the *Authorization: Bearer <token\>* header
4711 - Profit, depending on the role assigned to the account
4713 Note that the __access token is valid for 1 day__ and is given
4714 along with a __refresh token valid for 2 weeks__.
4716 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4720 tokenUrl: /api/v1/users/token
4723 moderator: Moderator scope
4726 # Resuable core properties
4734 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4735 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4740 description: immutable name of the user, used to find or mention its actor
4742 pattern: '/^[a-z0-9._]+$/'
4747 description: immutable name of the channel, used to interact with its actor
4748 example: framasoft_videos
4749 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4760 description: category id of the video (see [/videos/categories](#operation/getCategories))
4762 VideoConstantNumber-Category:
4765 $ref: '#/components/schemas/VideoCategorySet'
4768 example: Science & Technology
4772 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4774 VideoConstantNumber-Licence:
4777 $ref: '#/components/schemas/VideoLicenceSet'
4780 example: Attribution - Share Alike
4784 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4786 VideoConstantString-Language:
4789 $ref: '#/components/schemas/VideoLanguageSet'
4794 VideoPlaylistPrivacySet:
4800 description: Video playlist privacy policy (see [/video-playlists/privacies])
4801 VideoPlaylistPrivacyConstant:
4804 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4808 VideoPlaylistTypeSet:
4813 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4814 VideoPlaylistTypeConstant:
4817 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4828 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4829 VideoPrivacyConstant:
4832 $ref: '#/components/schemas/VideoPrivacySet'
4849 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4856 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4867 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4877 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4881 $ref: '#/components/schemas/AbuseStateSet'
4884 AbusePredefinedReasons:
4897 example: [spamOrMisleading]
4902 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4904 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4906 VideoResolutionConstant:
4907 description: resolutions and their labels for the video
4910 $ref: '#/components/schemas/VideoResolutionSet'
4914 VideoScheduledUpdate:
4917 $ref: '#/components/schemas/VideoPrivacySet'
4921 description: When to update the video
4941 - $ref: '#/components/schemas/ActorImage'
4942 VideoChannelSummary:
4945 $ref: '#/components/schemas/id'
4959 - $ref: '#/components/schemas/ActorImage'
4973 - $ref: '#/components/schemas/Video'
4980 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4981 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
4982 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4984 $ref: '#/components/schemas/VideoResolutionConstant'
4987 description: Video file size in bytes
4990 description: Direct URL of the torrent file
4994 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4998 description: Direct URL of the video
5002 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5006 description: Frames per second of the video file
5010 description: URL dereferencing the output of ffprobe on the file
5011 VideoStreamingPlaylists:
5016 $ref: '#/components/schemas/id'
5024 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5025 VideoStreamingPlaylists-HLS:
5036 Video files associated to this playlist.
5038 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5040 $ref: '#/components/schemas/VideoFile'
5052 $ref: '#/components/schemas/Video/properties/id'
5054 $ref: '#/components/schemas/Video/properties/uuid'
5056 $ref: '#/components/schemas/Video/properties/name'
5060 description: object id for the video
5062 - $ref: '#/components/schemas/id'
5064 description: universal identifier for the video, that can be used across instances
5066 - $ref: '#/components/schemas/UUIDv4'
5072 example: 2017-10-01T10:52:46.396Z
5073 description: time at which the video object was first drafted
5077 example: 2018-10-01T10:52:46.396Z
5078 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5082 example: 2021-05-04T08:01:01.502Z
5083 description: last time the video's metadata was modified
5084 originallyPublishedAt:
5087 example: 2010-10-01T10:52:46.396Z
5088 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5091 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5092 description: category in which the video is classified
5095 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5096 description: licence under which the video is distributed
5099 - $ref: '#/components/schemas/VideoConstantString-Language'
5100 description: main language used in the video
5103 - $ref: '#/components/schemas/VideoPrivacyConstant'
5104 description: privacy policy used to distribute the video
5108 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5109 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5113 truncated description of the video, written in Markdown.
5114 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5119 description: duration of the video in seconds
5124 description: title of the video
5125 example: What is PeerTube?
5130 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5133 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5136 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5153 - $ref: '#/components/schemas/VideoStateConstant'
5154 description: represents the internal state of the video processing within the PeerTube instance
5158 - $ref: '#/components/schemas/VideoScheduledUpdate'
5166 $ref: '#/components/schemas/AccountSummary'
5168 $ref: '#/components/schemas/VideoChannelSummary'
5177 - $ref: '#/components/schemas/Video'
5182 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5183 description: path at which to get the full description of maximum `10000` characters
5186 description: A text tell the audience how to support the video creator
5187 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5191 $ref: '#/components/schemas/VideoChannel'
5193 $ref: '#/components/schemas/Account'
5195 example: [flowers, gardening]
5213 - https://peertube2.cpy.re/tracker/announce
5214 - wss://peertube2.cpy.re/tracker/socket
5218 $ref: '#/components/schemas/VideoFile'
5220 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5222 - field will be empty
5223 - video files will be found in `streamingPlaylists[].files` field
5227 $ref: '#/components/schemas/VideoStreamingPlaylists'
5229 HLS playlists/manifest files. If HLS is disabled on the server:
5231 - field will be empty
5232 - video files will be found in `files` field
5233 FileRedundancyInformation:
5236 $ref: '#/components/schemas/id'
5261 $ref: '#/components/schemas/id'
5268 $ref: '#/components/schemas/UUIDv4'
5275 $ref: '#/components/schemas/FileRedundancyInformation'
5279 $ref: '#/components/schemas/FileRedundancyInformation'
5280 VideoImportStateConstant:
5288 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5295 additionalProperties: false
5299 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5300 required: [targetUrl]
5303 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5304 required: [magnetUri]
5307 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5308 required: [torrentfile]
5309 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5318 - $ref: '#/components/schemas/id'
5322 description: remote URL where to find the import's source video
5323 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5327 description: magnet URI allowing to resolve the import's source video
5328 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
5329 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5334 description: Torrent file containing only the video file
5341 - $ref: '#/components/schemas/VideoImportStateConstant'
5357 - $ref: '#/components/schemas/Video'
5367 $ref: '#/components/schemas/VideoImport'
5371 $ref: '#/components/schemas/id'
5374 example: The video is a spam
5378 $ref: '#/components/schemas/AbusePredefinedReasons'
5380 $ref: '#/components/schemas/Account'
5382 $ref: '#/components/schemas/AbuseStateConstant'
5385 example: Decided to ban the server since it spams us regularly
5389 $ref: '#/components/schemas/VideoInfo'
5396 $ref: '#/components/schemas/id'
5407 $ref: '#/components/schemas/AccountSummary'
5411 $ref: '#/components/schemas/id'
5413 $ref: '#/components/schemas/Video/properties/id'
5425 $ref: '#/components/schemas/UUIDv4'
5443 $ref: '#/components/schemas/id'
5445 $ref: '#/components/schemas/UUIDv4'
5468 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5470 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5472 $ref: '#/components/schemas/AccountSummary'
5474 $ref: '#/components/schemas/VideoChannelSummary'
5478 $ref: '#/components/schemas/id'
5485 description: Text of the comment
5487 example: This video is wonderful!
5489 $ref: '#/components/schemas/id'
5493 - $ref: '#/components/schemas/id'
5495 $ref: '#/components/schemas/Video/properties/id'
5510 totalRepliesFromVideoAuthor:
5517 $ref: '#/components/schemas/Account'
5518 VideoCommentThreadTree:
5521 $ref: '#/components/schemas/VideoComment'
5525 $ref: '#/components/schemas/VideoCommentThreadTree'
5529 $ref: '#/components/schemas/VideoConstantString-Language'
5545 $ref: '#/components/schemas/id'
5562 $ref: '#/components/schemas/id'
5567 description: immutable name of the actor, used to find or mention it
5569 - $ref: '#/components/schemas/username'
5573 description: server on which the actor is resident
5574 hostRedundancyAllowed:
5576 description: whether this actor's host allows redundancy of its videos
5580 description: number of actors subscribed to by this actor, as seen by this instance
5584 description: number of followers of this actor, as seen by this instance
5592 $ref: '#/components/schemas/ActorImage'
5595 - $ref: '#/components/schemas/Actor'
5598 description: object id for the user tied to this account
5600 - $ref: '#/components/schemas/User/properties/id'
5603 description: editable name of the account, displayed in its representations
5608 description: text or bio displayed on the account's profile
5614 description: timestamp within the video, in seconds
5681 allowedForCurrentIP:
5683 requiresEmailVerification:
5701 $ref: '#/components/schemas/VideoResolutionSet'
5786 example: 16810141515
5895 requiresEmailVerification:
5910 description: Settings that apply to new users, if registration is enabled
5914 example: 16810141515
5920 description: Settings pertaining to transcoding jobs
5924 allowAdditionalExtensions:
5926 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5929 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5932 description: Amount of threads used by ffmpeg for 1 transcoding job
5935 description: Amount of transcoding jobs to execute in parallel
5941 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5944 description: Resolutions to transcode _new videos_ to
5964 description: WebTorrent-specific settings
5970 description: HLS-specific settings
6020 $ref: '#/components/schemas/id'
6022 $ref: '#/components/schemas/Actor'
6024 $ref: '#/components/schemas/Actor'
6027 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6040 PredefinedAbuseReasons:
6041 description: Reason categories that help triage reports
6059 $ref: '#/components/schemas/id'
6071 - activitypub-http-unicast
6072 - activitypub-http-broadcast
6073 - activitypub-http-fetcher
6074 - activitypub-follow
6080 - activitypub-refresher
6084 additionalProperties: true
6087 additionalProperties: true
6103 $ref: '#/components/schemas/id'
6108 $ref: '#/components/schemas/id'
6109 VideoUploadRequestCommon:
6112 description: Video name
6114 example: What is PeerTube?
6118 description: Channel id that will contain this video
6123 $ref: '#/components/schemas/VideoPrivacySet'
6125 $ref: '#/components/schemas/VideoCategorySet'
6127 $ref: '#/components/schemas/VideoLicenceSet'
6129 $ref: '#/components/schemas/VideoLanguageSet'
6131 description: Video description
6134 **[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)**
6136 description: Whether or not we wait transcoding before publish the video
6139 description: A text tell the audience how to support the video creator
6140 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6143 description: Whether or not this video contains sensitive content
6146 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6159 description: Enable or disable comments for this video
6162 description: Enable or disable downloading for this video
6164 originallyPublishedAt:
6165 description: Date when the content was originally published
6169 $ref: '#/components/schemas/VideoScheduledUpdate'
6171 description: Video thumbnail file
6175 description: Video preview file
6181 VideoUploadRequestLegacy:
6183 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6189 description: Video file
6192 VideoUploadRequestResumable:
6194 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6200 description: Video filename including extension
6203 example: what_is_peertube.mp4
6205 description: Video thumbnail file
6209 description: Video preview file
6212 VideoUploadResponse:
6218 $ref: '#/components/schemas/Video/properties/id'
6220 $ref: '#/components/schemas/Video/properties/uuid'
6221 CommentThreadResponse:
6230 $ref: '#/components/schemas/VideoComment'
6231 CommentThreadPostResponse:
6234 $ref: '#/components/schemas/VideoComment'
6244 $ref: '#/components/schemas/Video'
6248 $ref: '#/components/schemas/Account'
6251 description: Automatically start playing the upcoming video after the currently playing video
6252 autoPlayNextVideoPlaylist:
6254 description: Automatically start playing the video on the playlist after the currently playing video
6257 description: Automatically start playing the video on the watch page
6267 description: The user email
6270 description: Has the user confirmed their email address?
6273 - $ref: '#/components/schemas/id'
6277 description: Auth plugin to use to authenticate the user
6281 noInstanceConfigWarningModal:
6286 $ref: '#/components/schemas/NSFWPolicy'
6288 $ref: '#/components/schemas/UserRole'
6297 description: Theme enabled by this user
6299 $ref: '#/components/schemas/username'
6303 $ref: '#/components/schemas/VideoChannel'
6306 description: The user video quota in bytes
6310 description: The user daily video quota in bytes
6314 description: Enable P2P in the player
6317 - $ref: '#/components/schemas/User'
6319 # optionally present fields: they require WITH_STATS scope
6322 description: Count of videos published
6325 description: Count of reports/abuses of which the user is a target
6326 abusesAcceptedCount:
6328 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6331 description: Count of reports/abuses created by the user
6334 description: Count of comments published
6338 $ref: '#/components/schemas/username'
6340 $ref: '#/components/schemas/password'
6344 description: The user email
6347 description: The user video quota in bytes
6351 description: The user daily video quota in bytes
6354 $ref: '#/components/schemas/usernameChannel'
6356 $ref: '#/components/schemas/UserRole'
6358 $ref: '#/components/schemas/UserAdminFlags'
6369 description: The updated email of the user
6371 - $ref: '#/components/schemas/User/properties/email'
6374 description: Set the email as verified
6377 description: The updated video quota of the user in bytes
6380 description: The updated daily video quota of the user in bytes
6384 description: The auth plugin to use to authenticate the user
6385 example: 'peertube-plugin-auth-saml2'
6387 $ref: '#/components/schemas/UserRole'
6389 $ref: '#/components/schemas/UserAdminFlags'
6391 # see shared/models/users/user-update-me.model.ts:
6394 $ref: '#/components/schemas/password'
6396 $ref: '#/components/schemas/password'
6398 description: new email used for login and service communications
6400 - $ref: '#/components/schemas/User/properties/email'
6403 description: new name of the user in its representations
6408 description: new NSFW display policy
6415 description: whether to enable P2P in the player or not
6418 description: new preference regarding playing videos automatically
6421 description: new preference regarding playing following videos automatically
6422 autoPlayNextVideoPlaylist:
6424 description: new preference regarding playing following playlist videos automatically
6425 videosHistoryEnabled:
6427 description: whether to keep track of watched history or not
6432 description: list of languages to filter videos down to
6435 noInstanceConfigWarningModal:
6442 $ref: '#/components/schemas/id'
6449 description: Rating of the video
6456 $ref: '#/components/schemas/Video'
6463 description: Rating of the video
6470 description: immutable name of the user, used to find or mention its actor
6472 - $ref: '#/components/schemas/username'
6474 $ref: '#/components/schemas/password'
6478 description: email of the user, used for login or service communications
6481 description: editable name of the user, displayed in its representations
6486 description: channel base information used to create the first channel of the user
6489 $ref: '#/components/schemas/usernameChannel'
6491 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6501 pattern: /^[a-z0-9]$/
6504 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6507 pattern: /^[a-zA-Z0-9]$/
6510 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6511 OAuthToken-password:
6513 - $ref: '#/components/schemas/OAuthClient'
6523 $ref: '#/components/schemas/User/properties/username'
6525 $ref: '#/components/schemas/password'
6532 OAuthToken-refresh_token:
6534 - $ref: '#/components/schemas/OAuthClient'
6545 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6554 # GET/POST/PUT properties
6557 description: editable name of the channel, displayed in its representations
6558 example: Videos of Framasoft
6563 example: Videos made with <3 by Framasoft
6568 description: text shown by default on all videos of this channel, to tell the audience how to support it
6569 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6572 # GET-only properties
6576 - $ref: '#/components/schemas/id'
6592 $ref: '#/components/schemas/UUIDv4'
6595 - $ref: '#/components/schemas/VideoChannel'
6598 description: username of the channel to create
6600 - $ref: '#/components/schemas/usernameChannel'
6606 - $ref: '#/components/schemas/VideoChannel'
6608 bulkVideosSupportUpdate:
6610 description: Update the support field for all videos of this channel
6620 - $ref: '#/components/schemas/VideoChannel'
6621 - $ref: '#/components/schemas/Actor'
6626 name: 'media:peerLink'
6635 - application/x-bittorrent
6641 name: 'media:content'
6672 VideoCommentsForXML:
6707 description: video watch page URL
6710 description: video canonical URL
6714 description: video publication date
6717 description: video description
6720 description: video description
6723 description: publisher user name
6726 description: video category (MRSS)
6729 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6744 description: video embed path, relative to the canonical URL domain (MRSS)
6753 description: video watch path, relative to the canonical URL domain (MRSS)
6774 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6775 'media:description':
6782 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6785 description: main streamable file for the video
6795 - application/x-bittorrent
6804 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)
6807 - $ref: '#/components/schemas/MRSSPeerLink'
6808 - $ref: '#/components/schemas/MRSSGroupContent'
6809 NotificationSettingValue:
6826 $ref: '#/components/schemas/id'
6830 Notification type, following the `UserNotificationType` enum:
6832 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6834 - `2` NEW_COMMENT_ON_MY_VIDEO
6836 - `3` NEW_ABUSE_FOR_MODERATORS
6838 - `4` BLACKLIST_ON_MY_VIDEO
6840 - `5` UNBLACKLIST_ON_MY_VIDEO
6842 - `6` MY_VIDEO_PUBLISHED
6844 - `7` MY_VIDEO_IMPORT_SUCCESS
6846 - `8` MY_VIDEO_IMPORT_ERROR
6848 - `9` NEW_USER_REGISTRATION
6852 - `11` COMMENT_MENTION
6854 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6856 - `13` NEW_INSTANCE_FOLLOWER
6858 - `14` AUTO_INSTANCE_FOLLOWING
6864 - $ref: '#/components/schemas/VideoInfo'
6868 $ref: '#/components/schemas/ActorInfo'
6874 $ref: '#/components/schemas/id'
6877 $ref: '#/components/schemas/VideoInfo'
6882 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6892 $ref: '#/components/schemas/id'
6896 $ref: '#/components/schemas/VideoInfo'
6898 $ref: '#/components/schemas/ActorInfo'
6904 $ref: '#/components/schemas/id'
6907 - $ref: '#/components/schemas/VideoInfo'
6913 $ref: '#/components/schemas/id'
6916 - $ref: '#/components/schemas/VideoInfo'
6920 - $ref: '#/components/schemas/ActorInfo'
6926 $ref: '#/components/schemas/id'
6928 $ref: '#/components/schemas/ActorInfo'
6956 NotificationListResponse:
6965 $ref: '#/components/schemas/Notification'
6970 example: peertube-plugin-auth-ldap
6998 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7001 additionalProperties: true
7017 $ref: '#/components/schemas/Plugin'
7024 description: User can stream multiple times in a permanent live
7033 description: RTMP stream key to use to stream into this live video
7037 description: User can stream multiple times in a permanent live
7044 'https://search.example.org/api/v1/search/videos':
7046 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7049 description: successful operation
7053 $ref: '#/components/schemas/VideoListResponse'