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: Operations on video files
272 - name: Video Transcoding
273 description: Video transcoding related operations
275 description: Server syndication feeds
278 The search helps to find _videos_ or _channels_ from within the instance and beyond.
279 Videos from other instances federated by the instance (that is, instances
280 followed by the instance) can be found via keywords and other criteria of
283 Administrators can also enable the use of a remote search system, indexing
284 videos and channels not could be not federated by the instance.
286 description: Get and update the custom homepage
287 - name: Video Mirroring
289 PeerTube instances can mirror videos from one another, and help distribute some videos.
291 For importing videos as your own, refer to [video imports](#operation/importVideo).
314 - Video Ownership Change
332 - name: Instance Configuration
336 - Instance Redundancy
346 summary: Get an account
347 operationId: getAccount
349 - $ref: '#/components/parameters/name'
352 description: successful operation
356 $ref: '#/components/schemas/Account'
358 description: account not found
360 '/accounts/{name}/videos':
365 summary: 'List videos of an account'
366 operationId: getAccountVideos
368 - $ref: '#/components/parameters/name'
369 - $ref: '#/components/parameters/categoryOneOf'
370 - $ref: '#/components/parameters/isLive'
371 - $ref: '#/components/parameters/tagsOneOf'
372 - $ref: '#/components/parameters/tagsAllOf'
373 - $ref: '#/components/parameters/licenceOneOf'
374 - $ref: '#/components/parameters/languageOneOf'
375 - $ref: '#/components/parameters/nsfw'
376 - $ref: '#/components/parameters/isLocal'
377 - $ref: '#/components/parameters/include'
378 - $ref: '#/components/parameters/privacyOneOf'
379 - $ref: '#/components/parameters/hasHLSFiles'
380 - $ref: '#/components/parameters/hasWebtorrentFiles'
381 - $ref: '#/components/parameters/skipCount'
382 - $ref: '#/components/parameters/start'
383 - $ref: '#/components/parameters/count'
384 - $ref: '#/components/parameters/videosSort'
387 description: successful operation
391 $ref: '#/components/schemas/VideoListResponse'
395 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
396 .then(function(response) {
397 return response.json()
398 }).then(function(data) {
404 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
410 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
412 http = Net::HTTP.new(uri.host, uri.port)
415 response = http.get(uri.request_uri)
417 puts JSON.parse(response.read_body)
422 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
427 '/accounts/{name}/followers':
431 summary: 'List followers of an account'
434 operationId: getAccountFollowers
436 - $ref: '#/components/parameters/name'
437 - $ref: '#/components/parameters/start'
438 - $ref: '#/components/parameters/count'
439 - $ref: '#/components/parameters/followersSort'
440 - $ref: '#/components/parameters/search'
443 description: successful operation
455 $ref: '#/components/schemas/Follow'
461 summary: List accounts
462 operationId: getAccounts
464 - $ref: '#/components/parameters/start'
465 - $ref: '#/components/parameters/count'
466 - $ref: '#/components/parameters/sort'
469 description: successful operation
475 $ref: '#/components/schemas/Account'
481 summary: Get instance public configuration
482 operationId: getConfig
485 description: successful operation
489 $ref: '#/components/schemas/ServerConfig'
492 externalValue: https://peertube2.cpy.re/api/v1/config
496 summary: Get instance "About" information
497 operationId: getAbout
502 description: successful operation
506 $ref: '#/components/schemas/ServerConfigAbout'
509 externalValue: https://peertube2.cpy.re/api/v1/config/about
513 summary: Get instance runtime configuration
514 operationId: getCustomConfig
522 description: successful operation
526 $ref: '#/components/schemas/ServerConfigCustom'
528 summary: Set instance runtime configuration
529 operationId: putCustomConfig
537 description: successful operation
539 x-summary: field inconsistencies
542 - the emailer is disabled and the instance is open to registrations
543 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
545 summary: Delete instance runtime configuration
546 operationId: delCustomConfig
554 description: successful operation
556 /custom-pages/homepage/instance:
558 summary: Get instance custom homepage
563 description: No homepage set
565 description: successful operation
569 $ref: '#/components/schemas/CustomHomepage'
571 summary: Set instance custom homepage
585 description: content of the homepage, that will be injected in the client
588 description: successful operation
592 summary: List instance jobs
603 description: The state of the job ('' for for no filter)
613 - $ref: '#/components/parameters/jobType'
614 - $ref: '#/components/parameters/start'
615 - $ref: '#/components/parameters/count'
616 - $ref: '#/components/parameters/sort'
619 description: successful operation
632 $ref: '#/components/schemas/Job'
638 summary: List instances following the server
640 - $ref: '#/components/parameters/followState'
641 - $ref: '#/components/parameters/actorType'
642 - $ref: '#/components/parameters/start'
643 - $ref: '#/components/parameters/count'
644 - $ref: '#/components/parameters/sort'
647 description: successful operation
659 $ref: '#/components/schemas/Follow'
661 '/server/followers/{nameWithHost}':
663 summary: Remove or reject a follower to your server
673 description: The remote actor handle to remove from your followers
679 description: successful operation
681 description: follower not found
683 '/server/followers/{nameWithHost}/reject':
685 summary: Reject a pending follower to your server
695 description: The remote actor handle to remove from your followers
701 description: successful operation
703 description: follower not found
705 '/server/followers/{nameWithHost}/accept':
707 summary: Accept a pending follower to your server
717 description: The remote actor handle to remove from your followers
723 description: successful operation
725 description: follower not found
731 summary: List instances followed by the server
733 - $ref: '#/components/parameters/followState'
734 - $ref: '#/components/parameters/actorType'
735 - $ref: '#/components/parameters/start'
736 - $ref: '#/components/parameters/count'
737 - $ref: '#/components/parameters/sort'
740 description: successful operation
752 $ref: '#/components/schemas/Follow'
759 summary: Follow a list of actors (PeerTube instance, channel or account)
762 description: successful operation
764 description: cannot follow a non-HTTPS server
783 '/server/following/{hostOrHandle}':
785 summary: Unfollow an actor (PeerTube instance, channel or account)
795 description: The hostOrHandle to unfollow
800 description: successful operation
802 description: host or handle not found
806 summary: Create a user
815 description: user created
819 $ref: '#/components/schemas/AddUserResponse'
825 id: '$response.body#/user/id'
830 id: '$response.body#/user/id'
835 id: '$response.body#/user/id'
837 description: insufficient authority to create an admin or moderator
842 $ref: '#/components/schemas/AddUser'
844 If the smtp server is configured, you can leave the password empty and an email will be sent
845 asking the user to set it first.
849 operationId: getUsers
856 - $ref: '#/components/parameters/usersSearch'
857 - $ref: '#/components/parameters/usersBlocked'
858 - $ref: '#/components/parameters/start'
859 - $ref: '#/components/parameters/count'
860 - $ref: '#/components/parameters/usersSort'
863 description: successful operation
869 $ref: '#/components/schemas/User'
873 - $ref: '#/components/parameters/id'
875 summary: Delete a user
884 description: successful operation
895 description: include statistics about the user (only available as a moderator/admin)
900 x-summary: successful operation
902 As an admin/moderator, you can request a response augmented with statistics about the user's
903 moderation relations and videos usage, by using the `withStats` parameter.
908 - $ref: '#/components/schemas/User'
909 - $ref: '#/components/schemas/UserWithStats'
911 summary: Update a user
919 description: successful operation
924 $ref: '#/components/schemas/UpdateUser'
927 /oauth-clients/local:
929 summary: Login prerequisite
930 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
931 operationId: getOAuthClient
936 description: successful operation
940 $ref: '#/components/schemas/OAuthClient'
942 UseOAuthClientToLogin:
943 operationId: getOAuthToken
945 client_id: '$response.body#/client_id'
946 client_secret: '$response.body#/client_secret'
950 API="https://peertube2.cpy.re/api/v1"
953 curl -s "$API/oauth-clients/local"
958 operationId: getOAuthToken
959 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
964 application/x-www-form-urlencoded:
967 - $ref: '#/components/schemas/OAuthToken-password'
968 - $ref: '#/components/schemas/OAuthToken-refresh_token'
970 propertyName: grant_type
972 password: '#/components/schemas/OAuthToken-password'
973 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
976 description: successful operation
987 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
988 description: valid for 1 day
991 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
992 description: valid for 2 weeks
997 refresh_token_expires_in:
1002 x-summary: client or credentials are invalid
1004 Disambiguate via `type`:
1005 - `invalid_client` for an unmatched `client_id`
1006 - `invalid_grant` for unmatched credentials
1008 x-summary: token expired
1010 Disambiguate via `type`:
1011 - default value for a regular authentication failure
1012 - `invalid_token` for an expired token
1017 API="https://peertube2.cpy.re/api/v1"
1018 USERNAME="<your_username>"
1019 PASSWORD="<your_password>"
1022 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1023 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1024 curl -s "$API/users/token" \
1025 --data client_id="$client_id" \
1026 --data client_secret="$client_secret" \
1027 --data grant_type=password \
1028 --data username="$USERNAME" \
1029 --data password="$PASSWORD" \
1030 | jq -r ".access_token"
1032 /users/revoke-token:
1035 description: Revokes your access token and its associated refresh token, destroying your current session.
1036 operationId: revokeOAuthToken
1043 description: successful operation
1047 summary: Register a user
1048 operationId: registerUser
1054 description: successful operation
1059 $ref: '#/components/schemas/RegisterUser'
1062 /users/{id}/verify-email:
1064 summary: Verify a user
1065 operationId: verifyUser
1067 Following a user registration, the new user will receive an email asking to click a link
1068 containing a secret.
1073 - $ref: '#/components/parameters/id'
1086 - verificationString
1089 description: successful operation
1091 description: invalid verification string
1093 description: user not found
1095 /users/ask-send-verify-email:
1097 summary: Resend user verification link
1098 operationId: resendEmailToVerifyUser
1104 description: successful operation
1108 summary: Get my user information
1109 operationId: getUserInfo
1117 description: successful operation
1123 $ref: '#/components/schemas/User'
1125 summary: Update my user information
1126 operationId: putUserInfo
1134 description: successful operation
1139 $ref: '#/components/schemas/UpdateMe'
1142 /users/me/videos/imports:
1144 summary: Get video imports of my user
1152 - $ref: '#/components/parameters/start'
1153 - $ref: '#/components/parameters/count'
1154 - $ref: '#/components/parameters/sort'
1157 description: successful operation
1161 $ref: '#/components/schemas/VideoImportsList'
1163 /users/me/video-quota-used:
1165 summary: Get my user used quota
1173 description: successful operation
1181 description: The user video quota used so far in bytes
1182 example: 16810141515
1183 videoQuotaUsedDaily:
1185 description: The user video quota used today in bytes
1188 '/users/me/videos/{videoId}/rating':
1190 summary: Get rate of my user for a video
1200 description: The video id
1202 $ref: '#/components/schemas/Video/properties/id'
1205 description: successful operation
1209 $ref: '#/components/schemas/GetMeVideoRating'
1213 summary: Get videos of my user
1221 - $ref: '#/components/parameters/start'
1222 - $ref: '#/components/parameters/count'
1223 - $ref: '#/components/parameters/sort'
1226 description: successful operation
1230 $ref: '#/components/schemas/VideoListResponse'
1232 /users/me/subscriptions:
1234 summary: Get my user subscriptions
1241 - $ref: '#/components/parameters/start'
1242 - $ref: '#/components/parameters/count'
1243 - $ref: '#/components/parameters/sort'
1246 description: successful operation
1250 $ref: '#/components/schemas/VideoChannelList'
1254 summary: Add subscription to my user
1267 description: uri of the video channels to subscribe to
1273 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1276 description: successful operation
1278 /users/me/subscriptions/exist:
1280 summary: Get if subscriptions exist for my user
1287 - $ref: '#/components/parameters/subscriptionsUris'
1290 description: successful operation
1296 /users/me/subscriptions/videos:
1298 summary: List videos of subscriptions of my user
1306 - $ref: '#/components/parameters/categoryOneOf'
1307 - $ref: '#/components/parameters/isLive'
1308 - $ref: '#/components/parameters/tagsOneOf'
1309 - $ref: '#/components/parameters/tagsAllOf'
1310 - $ref: '#/components/parameters/licenceOneOf'
1311 - $ref: '#/components/parameters/languageOneOf'
1312 - $ref: '#/components/parameters/nsfw'
1313 - $ref: '#/components/parameters/isLocal'
1314 - $ref: '#/components/parameters/include'
1315 - $ref: '#/components/parameters/privacyOneOf'
1316 - $ref: '#/components/parameters/hasHLSFiles'
1317 - $ref: '#/components/parameters/hasWebtorrentFiles'
1318 - $ref: '#/components/parameters/skipCount'
1319 - $ref: '#/components/parameters/start'
1320 - $ref: '#/components/parameters/count'
1321 - $ref: '#/components/parameters/videosSort'
1324 description: successful operation
1328 $ref: '#/components/schemas/VideoListResponse'
1330 '/users/me/subscriptions/{subscriptionHandle}':
1332 summary: Get subscription of my user
1339 - $ref: '#/components/parameters/subscriptionHandle'
1342 description: successful operation
1346 $ref: '#/components/schemas/VideoChannel'
1348 summary: Delete subscription of my user
1355 - $ref: '#/components/parameters/subscriptionHandle'
1358 description: successful operation
1360 /users/me/notifications:
1362 summary: List my notifications
1370 description: only list unread notifications
1373 - $ref: '#/components/parameters/start'
1374 - $ref: '#/components/parameters/count'
1375 - $ref: '#/components/parameters/sort'
1378 description: successful operation
1382 $ref: '#/components/schemas/NotificationListResponse'
1384 /users/me/notifications/read:
1386 summary: Mark notifications as read by their id
1399 description: ids of the notifications to mark as read
1406 description: successful operation
1408 /users/me/notifications/read-all:
1410 summary: Mark all my notification as read
1417 description: successful operation
1419 /users/me/notification-settings:
1421 summary: Update my notification settings
1432 newVideoFromSubscription:
1433 $ref: '#/components/schemas/NotificationSettingValue'
1434 newCommentOnMyVideo:
1435 $ref: '#/components/schemas/NotificationSettingValue'
1437 $ref: '#/components/schemas/NotificationSettingValue'
1438 videoAutoBlacklistAsModerator:
1439 $ref: '#/components/schemas/NotificationSettingValue'
1441 $ref: '#/components/schemas/NotificationSettingValue'
1443 $ref: '#/components/schemas/NotificationSettingValue'
1444 myVideoImportFinished:
1445 $ref: '#/components/schemas/NotificationSettingValue'
1447 $ref: '#/components/schemas/NotificationSettingValue'
1448 newUserRegistration:
1449 $ref: '#/components/schemas/NotificationSettingValue'
1451 $ref: '#/components/schemas/NotificationSettingValue'
1452 newInstanceFollower:
1453 $ref: '#/components/schemas/NotificationSettingValue'
1454 autoInstanceFollowing:
1455 $ref: '#/components/schemas/NotificationSettingValue'
1458 description: successful operation
1460 /users/me/history/videos:
1462 summary: List watched videos history
1468 - $ref: '#/components/parameters/start'
1469 - $ref: '#/components/parameters/count'
1470 - $ref: '#/components/parameters/search'
1473 description: successful operation
1477 $ref: '#/components/schemas/VideoListResponse'
1479 /users/me/history/videos/remove:
1481 summary: Clear video history
1488 multipart/form-data:
1493 description: history before this date will be deleted
1498 description: successful operation
1500 /users/me/avatar/pick:
1502 summary: Update my user avatar
1509 description: successful operation
1516 $ref: '#/components/schemas/ActorImage'
1518 description: image file too large
1520 X-File-Maximum-Size:
1524 description: Maximum file size for the avatar
1527 multipart/form-data:
1532 description: The file to upload
1537 contentType: image/png, image/jpeg
1541 summary: Delete my avatar
1548 description: successful operation
1552 summary: List video ownership changes
1554 - Video Ownership Change
1559 description: successful operation
1561 '/videos/ownership/{id}/accept':
1563 summary: Accept ownership change request
1565 - Video Ownership Change
1569 - $ref: '#/components/parameters/idOrUUID'
1572 description: successful operation
1574 description: cannot terminate an ownership change of another user
1576 description: video owneship change not found
1578 '/videos/ownership/{id}/refuse':
1580 summary: Refuse ownership change request
1582 - Video Ownership Change
1586 - $ref: '#/components/parameters/idOrUUID'
1589 description: successful operation
1591 description: cannot terminate an ownership change of another user
1593 description: video owneship change not found
1595 '/videos/{id}/give-ownership':
1597 summary: Request ownership change
1599 - Video Ownership Change
1603 - $ref: '#/components/parameters/idOrUUID'
1607 application/x-www-form-urlencoded:
1617 description: successful operation
1619 description: changing video ownership to a remote account is not supported yet
1621 description: video not found
1625 summary: List videos
1626 operationId: getVideos
1630 - $ref: '#/components/parameters/categoryOneOf'
1631 - $ref: '#/components/parameters/isLive'
1632 - $ref: '#/components/parameters/tagsOneOf'
1633 - $ref: '#/components/parameters/tagsAllOf'
1634 - $ref: '#/components/parameters/licenceOneOf'
1635 - $ref: '#/components/parameters/languageOneOf'
1636 - $ref: '#/components/parameters/nsfw'
1637 - $ref: '#/components/parameters/isLocal'
1638 - $ref: '#/components/parameters/include'
1639 - $ref: '#/components/parameters/privacyOneOf'
1640 - $ref: '#/components/parameters/hasHLSFiles'
1641 - $ref: '#/components/parameters/hasWebtorrentFiles'
1642 - $ref: '#/components/parameters/skipCount'
1643 - $ref: '#/components/parameters/start'
1644 - $ref: '#/components/parameters/count'
1645 - $ref: '#/components/parameters/videosSort'
1648 description: successful operation
1652 $ref: '#/components/schemas/VideoListResponse'
1656 summary: List available video categories
1657 operationId: getCategories
1662 description: successful operation
1671 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1675 summary: List available video licences
1676 operationId: getLicences
1681 description: successful operation
1690 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1694 summary: List available video languages
1695 operationId: getLanguages
1700 description: successful operation
1709 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1713 summary: List available video privacy policies
1714 operationId: getPrivacyPolicies
1719 description: successful operation
1728 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1732 summary: Update a video
1733 operationId: putVideo
1739 - $ref: '#/components/parameters/idOrUUID'
1742 description: successful operation
1745 multipart/form-data:
1750 description: Video thumbnail file
1754 description: Video preview file
1758 $ref: '#/components/schemas/VideoCategorySet'
1760 $ref: '#/components/schemas/VideoLicenceSet'
1762 $ref: '#/components/schemas/VideoLanguageSet'
1764 $ref: '#/components/schemas/VideoPrivacySet'
1766 description: Video description
1769 description: Whether or not we wait transcoding before publish the video
1772 description: A text tell the audience how to support the video creator
1773 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1776 description: Whether or not this video contains sensitive content
1779 description: Video name
1784 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1793 description: Enable or disable comments for this video
1796 description: Enable or disable downloading for this video
1798 originallyPublishedAt:
1799 description: Date when the content was originally published
1803 $ref: '#/components/schemas/VideoScheduledUpdate'
1806 contentType: image/jpeg
1808 contentType: image/jpeg
1810 summary: Get a video
1811 operationId: getVideo
1815 - $ref: '#/components/parameters/idOrUUID'
1818 description: successful operation
1822 $ref: '#/components/schemas/VideoDetails'
1824 summary: Delete a video
1825 operationId: delVideo
1831 - $ref: '#/components/parameters/idOrUUID'
1834 description: successful operation
1836 '/videos/{id}/description':
1838 summary: Get complete video description
1839 operationId: getVideoDesc
1843 - $ref: '#/components/parameters/idOrUUID'
1846 description: successful operation
1855 **[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)**
1857 '/videos/{id}/views':
1859 summary: Add a view to a video
1860 operationId: addView
1864 - $ref: '#/components/parameters/idOrUUID'
1867 description: successful operation
1869 '/videos/{id}/watching':
1871 summary: Set watching progress of a video
1872 operationId: setProgress
1878 - $ref: '#/components/parameters/idOrUUID'
1883 $ref: '#/components/schemas/UserWatchingVideo'
1887 description: successful operation
1891 summary: Upload a video
1892 description: Uses a single request to upload a video.
1893 operationId: uploadLegacy
1901 description: successful operation
1905 $ref: '#/components/schemas/VideoUploadResponse'
1907 description: video didn't pass upload filter
1909 description: upload has timed out
1911 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1913 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1914 - `quota_reached` for quota limits wether daily or global
1916 X-File-Maximum-Size:
1920 description: Maximum file size for the video
1922 description: video type unsupported
1924 description: video unreadable
1927 multipart/form-data:
1929 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1932 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1934 contentType: image/jpeg
1936 contentType: image/jpeg
1941 USERNAME="<your_username>"
1942 PASSWORD="<your_password>"
1943 FILE_PATH="<your_file_path>"
1944 CHANNEL_ID="<your_channel_id>"
1946 API="https://peertube2.cpy.re/api/v1"
1949 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1950 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1951 token=$(curl -s "$API/users/token" \
1952 --data client_id="$client_id" \
1953 --data client_secret="$client_secret" \
1954 --data grant_type=password \
1955 --data username="$USERNAME" \
1956 --data password="$PASSWORD" \
1957 | jq -r ".access_token")
1960 curl -s "$API/videos/upload" \
1961 -H "Authorization: Bearer $token" \
1963 --form videofile=@"$FILE_PATH" \
1964 --form channelId=$CHANNEL_ID \
1967 /videos/upload-resumable:
1969 summary: Initialize the resumable upload of a video
1970 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1971 operationId: uploadResumableInit
1978 - name: X-Upload-Content-Length
1984 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1985 - name: X-Upload-Content-Type
1992 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1997 $ref: '#/components/schemas/VideoUploadRequestResumable'
2000 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2002 description: created
2008 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2014 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2016 Disambiguate via `type`:
2017 - `max_file_size_reached` for the absolute file size limit
2018 - `quota_reached` for quota limits whether daily or global
2020 description: video type unsupported
2022 summary: Send chunk for the resumable upload of a video
2023 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
2024 operationId: uploadResumable
2035 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2036 not valid anymore and you need to initialize a new upload.
2039 - name: Content-Range
2043 example: bytes 0-262143/2469036
2046 Specifies the bytes in the file that the request is uploading.
2048 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2049 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2050 - name: Content-Length
2057 Size of the chunk that the request is sending.
2059 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)
2060 doesn't mandate for chunks to have the same size throughout the upload sequence.
2062 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2063 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2066 application/octet-stream:
2072 description: last chunk received
2080 $ref: '#/components/schemas/VideoUploadResponse'
2082 description: resume incomplete
2087 example: bytes=0-262143
2093 description: video didn't pass upload filter
2095 description: upload not found
2097 description: chunk doesn't match range
2099 description: video unreadable
2101 description: too many concurrent requests
2103 description: upload is already being processed
2110 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2111 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2112 operationId: uploadResumableCancel
2123 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2124 not valid anymore and the upload session has already been deleted with its data ;-)
2127 - name: Content-Length
2135 description: upload cancelled
2142 description: upload not found
2146 summary: Import a video
2147 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2148 operationId: importVideo
2156 multipart/form-data:
2158 $ref: '#/components/schemas/VideoCreateImport'
2161 contentType: application/x-bittorrent
2163 contentType: image/jpeg
2165 contentType: image/jpeg
2168 description: successful operation
2172 $ref: '#/components/schemas/VideoUploadResponse'
2174 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2176 description: video didn't pass pre-import filter
2178 description: HTTP or Torrent/magnetURI import not enabled
2182 summary: Create a live
2183 operationId: addLive
2191 description: successful operation
2195 $ref: '#/components/schemas/VideoUploadResponse'
2197 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2199 Disambiguate via `type`:
2200 - default type for a validation error
2201 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2203 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2205 Disambiguate via `type`:
2206 - `live_not_enabled` for a disabled live feature
2207 - `live_not_allowing_replay` for a disabled replay feature
2208 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2209 - `max_user_lives_limit_reached` for the user concurrent live limit
2212 multipart/form-data:
2217 description: Channel id that will contain this live video
2222 description: User can stream multiple times in a permanent live
2225 description: Live video/replay thumbnail file
2229 description: Live video/replay preview file
2233 $ref: '#/components/schemas/VideoPrivacySet'
2235 $ref: '#/components/schemas/VideoCategorySet'
2237 $ref: '#/components/schemas/VideoLicenceSet'
2239 $ref: '#/components/schemas/VideoLanguageSet'
2241 description: Live video/replay description
2244 description: A text tell the audience how to support the creator
2245 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2248 description: Whether or not this live video/replay contains sensitive content
2251 description: Live video/replay name
2256 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2265 description: Enable or disable comments for this live video/replay
2268 description: Enable or disable downloading for the replay of this live video
2275 contentType: image/jpeg
2277 contentType: image/jpeg
2281 summary: Get information about a live
2282 operationId: getLiveId
2289 - $ref: '#/components/parameters/idOrUUID'
2292 description: successful operation
2296 $ref: '#/components/schemas/LiveVideoResponse'
2298 summary: Update information about a live
2299 operationId: updateLiveId
2306 - $ref: '#/components/parameters/idOrUUID'
2311 $ref: '#/components/schemas/LiveVideoUpdate'
2314 description: successful operation
2316 description: bad parameters or trying to update a live that has already started
2318 description: trying to save replay of the live but saving replay is not enabled on the instance
2322 summary: List my abuses
2323 operationId: getMyAbuses
2332 description: only list the report with this id
2338 $ref: '#/components/schemas/AbuseStateSet'
2339 - $ref: '#/components/parameters/abusesSort'
2340 - $ref: '#/components/parameters/start'
2341 - $ref: '#/components/parameters/count'
2344 description: successful operation
2356 $ref: '#/components/schemas/Abuse'
2360 summary: List abuses
2361 operationId: getAbuses
2371 description: only list the report with this id
2374 - name: predefinedReason
2376 description: predefined reason the listed reports should contain
2378 $ref: '#/components/schemas/PredefinedAbuseReasons'
2381 description: plain search that will match with video titles, reporter names and more
2387 $ref: '#/components/schemas/AbuseStateSet'
2388 - name: searchReporter
2390 description: only list reports of a specific reporter
2393 - name: searchReportee
2394 description: only list reports of a specific reportee
2400 description: only list reports of a specific video
2403 - name: searchVideoChannel
2405 description: only list reports of a specific video channel
2410 description: only list deleted or blocklisted videos
2418 description: only list account, comment or video reports
2425 - $ref: '#/components/parameters/start'
2426 - $ref: '#/components/parameters/count'
2427 - $ref: '#/components/parameters/abusesSort'
2430 description: successful operation
2442 $ref: '#/components/schemas/Abuse'
2444 summary: Report an abuse
2457 description: Reason why the user reports this video
2462 $ref: '#/components/schemas/PredefinedAbuseReasons'
2467 description: Video id to report
2469 - $ref: '#/components/schemas/Video/properties/id'
2473 description: Timestamp in the video that marks the beginning of the report
2478 description: Timestamp in the video that marks the ending of the report
2484 description: Comment id to report
2486 - $ref: '#/components/schemas/VideoComment/properties/id'
2491 description: Account id to report
2497 description: successful operation
2507 $ref: '#/components/schemas/id'
2509 description: incorrect request parameters
2511 '/abuses/{abuseId}':
2513 summary: Update an abuse
2521 - $ref: '#/components/parameters/abuseId'
2529 $ref: '#/components/schemas/AbuseStateSet'
2532 description: Update the report comment visible only to the moderation team
2537 description: successful operation
2539 description: abuse not found
2543 summary: Delete an abuse
2549 - $ref: '#/components/parameters/abuseId'
2552 description: successful operation
2554 description: block not found
2556 '/abuses/{abuseId}/messages':
2558 summary: List messages of an abuse
2564 - $ref: '#/components/parameters/abuseId'
2567 description: successful operation
2579 $ref: '#/components/schemas/AbuseMessage'
2581 summary: Add message to an abuse
2587 - $ref: '#/components/parameters/abuseId'
2596 description: Message to send
2604 description: successful operation
2606 description: incorrect request parameters
2608 '/abuses/{abuseId}/messages/{abuseMessageId}':
2610 summary: Delete an abuse message
2616 - $ref: '#/components/parameters/abuseId'
2617 - $ref: '#/components/parameters/abuseMessageId'
2620 description: successful operation
2622 '/videos/{id}/blacklist':
2624 summary: Block a video
2625 operationId: addVideoBlock
2633 - $ref: '#/components/parameters/idOrUUID'
2636 description: successful operation
2638 summary: Unblock a video by its id
2639 operationId: delVideoBlock
2647 - $ref: '#/components/parameters/idOrUUID'
2650 description: successful operation
2652 description: block not found
2658 summary: List video blocks
2659 operationId: getVideoBlocks
2668 list only blocks that match this type:
2672 - `2`: automatic block that needs review
2680 description: plain search that will match with video titles, and more
2683 - $ref: '#/components/parameters/start'
2684 - $ref: '#/components/parameters/count'
2685 - $ref: '#/components/parameters/blacklistsSort'
2688 description: successful operation
2700 $ref: '#/components/schemas/VideoBlacklist'
2702 /videos/{id}/captions:
2704 summary: List captions of a video
2705 operationId: getVideoCaptions
2709 - $ref: '#/components/parameters/idOrUUID'
2712 description: successful operation
2724 $ref: '#/components/schemas/VideoCaption'
2726 /videos/{id}/captions/{captionLanguage}:
2728 summary: Add or replace a video caption
2729 operationId: addVideoCaption
2736 - $ref: '#/components/parameters/idOrUUID'
2737 - $ref: '#/components/parameters/captionLanguage'
2740 multipart/form-data:
2745 description: The file to upload.
2750 contentType: text/vtt, application/x-subrip, text/plain
2753 description: successful operation
2755 description: video or language not found
2757 summary: Delete a video caption
2758 operationId: delVideoCaption
2765 - $ref: '#/components/parameters/idOrUUID'
2766 - $ref: '#/components/parameters/captionLanguage'
2769 description: successful operation
2771 description: video or language or caption for that language not found
2775 summary: List video channels
2776 operationId: getVideoChannels
2780 - $ref: '#/components/parameters/start'
2781 - $ref: '#/components/parameters/count'
2782 - $ref: '#/components/parameters/sort'
2785 description: successful operation
2789 $ref: '#/components/schemas/VideoChannelList'
2791 summary: Create a video channel
2792 operationId: addVideoChannel
2799 description: successful operation
2809 $ref: '#/components/schemas/VideoChannel/properties/id'
2814 $ref: '#/components/schemas/VideoChannelCreate'
2816 '/video-channels/{channelHandle}':
2818 summary: Get a video channel
2819 operationId: getVideoChannel
2823 - $ref: '#/components/parameters/channelHandle'
2826 description: successful operation
2830 $ref: '#/components/schemas/VideoChannel'
2832 summary: Update a video channel
2833 operationId: putVideoChannel
2839 - $ref: '#/components/parameters/channelHandle'
2842 description: successful operation
2847 $ref: '#/components/schemas/VideoChannelUpdate'
2849 summary: Delete a video channel
2850 operationId: delVideoChannel
2856 - $ref: '#/components/parameters/channelHandle'
2859 description: successful operation
2861 '/video-channels/{channelHandle}/videos':
2863 summary: List videos of a video channel
2864 operationId: getVideoChannelVideos
2869 - $ref: '#/components/parameters/channelHandle'
2870 - $ref: '#/components/parameters/categoryOneOf'
2871 - $ref: '#/components/parameters/isLive'
2872 - $ref: '#/components/parameters/tagsOneOf'
2873 - $ref: '#/components/parameters/tagsAllOf'
2874 - $ref: '#/components/parameters/licenceOneOf'
2875 - $ref: '#/components/parameters/languageOneOf'
2876 - $ref: '#/components/parameters/nsfw'
2877 - $ref: '#/components/parameters/isLocal'
2878 - $ref: '#/components/parameters/include'
2879 - $ref: '#/components/parameters/privacyOneOf'
2880 - $ref: '#/components/parameters/hasHLSFiles'
2881 - $ref: '#/components/parameters/hasWebtorrentFiles'
2882 - $ref: '#/components/parameters/skipCount'
2883 - $ref: '#/components/parameters/start'
2884 - $ref: '#/components/parameters/count'
2885 - $ref: '#/components/parameters/videosSort'
2888 description: successful operation
2892 $ref: '#/components/schemas/VideoListResponse'
2894 '/video-channels/{channelHandle}/followers':
2898 summary: 'List followers of a video channel'
2901 operationId: getVideoChannelFollowers
2903 - $ref: '#/components/parameters/channelHandle'
2904 - $ref: '#/components/parameters/start'
2905 - $ref: '#/components/parameters/count'
2906 - $ref: '#/components/parameters/followersSort'
2907 - $ref: '#/components/parameters/search'
2910 description: successful operation
2922 $ref: '#/components/schemas/Follow'
2924 '/video-channels/{channelHandle}/avatar/pick':
2926 summary: Update channel avatar
2932 - $ref: '#/components/parameters/channelHandle'
2935 description: successful operation
2942 $ref: '#/components/schemas/ActorImage'
2944 description: image file too large
2946 X-File-Maximum-Size:
2950 description: Maximum file size for the avatar
2953 multipart/form-data:
2958 description: The file to upload.
2963 contentType: image/png, image/jpeg
2965 '/video-channels/{channelHandle}/avatar':
2967 summary: Delete channel avatar
2973 - $ref: '#/components/parameters/channelHandle'
2976 description: successful operation
2978 '/video-channels/{channelHandle}/banner/pick':
2980 summary: Update channel banner
2986 - $ref: '#/components/parameters/channelHandle'
2989 description: successful operation
2996 $ref: '#/components/schemas/ActorImage'
2998 description: image file too large
3000 X-File-Maximum-Size:
3004 description: Maximum file size for the banner
3007 multipart/form-data:
3012 description: The file to upload.
3017 contentType: image/png, image/jpeg
3019 '/video-channels/{channelHandle}/banner':
3021 summary: Delete channel banner
3027 - $ref: '#/components/parameters/channelHandle'
3030 description: successful operation
3032 /video-playlists/privacies:
3034 summary: List available playlist privacy policies
3035 operationId: getPlaylistPrivacyPolicies
3040 description: successful operation
3049 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3053 summary: List video playlists
3054 operationId: getPlaylists
3058 - $ref: '#/components/parameters/start'
3059 - $ref: '#/components/parameters/count'
3060 - $ref: '#/components/parameters/sort'
3063 description: successful operation
3075 $ref: '#/components/schemas/VideoPlaylist'
3077 summary: Create a video playlist
3078 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3079 operationId: addPlaylist
3086 description: successful operation
3096 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3098 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3100 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3103 multipart/form-data:
3108 description: Video playlist display name
3113 description: Video playlist thumbnail file
3117 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3119 description: Video playlist description
3125 - $ref: '#/components/schemas/id'
3126 description: Video channel in which the playlist will be published
3131 contentType: image/jpeg
3133 /video-playlists/{playlistId}:
3135 summary: Get a video playlist
3139 - $ref: '#/components/parameters/playlistId'
3142 description: successful operation
3146 $ref: '#/components/schemas/VideoPlaylist'
3148 summary: Update a video playlist
3149 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3156 description: successful operation
3158 - $ref: '#/components/parameters/playlistId'
3161 multipart/form-data:
3166 description: Video playlist display name
3171 description: Video playlist thumbnail file
3175 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3177 description: Video playlist description
3181 - $ref: '#/components/schemas/id'
3182 description: Video channel in which the playlist will be published
3185 contentType: image/jpeg
3187 summary: Delete a video playlist
3193 - $ref: '#/components/parameters/playlistId'
3196 description: successful operation
3198 /video-playlists/{playlistId}/videos:
3200 summary: 'List videos of a playlist'
3201 operationId: getVideoPlaylistVideos
3206 - $ref: '#/components/parameters/playlistId'
3207 - $ref: '#/components/parameters/start'
3208 - $ref: '#/components/parameters/count'
3211 description: successful operation
3215 $ref: '#/components/schemas/VideoListResponse'
3217 summary: Add a video in a playlist
3218 operationId: addVideoPlaylistVideo
3225 - $ref: '#/components/parameters/playlistId'
3228 description: successful operation
3234 videoPlaylistElement:
3248 - $ref: '#/components/schemas/Video/properties/uuid'
3249 - $ref: '#/components/schemas/Video/properties/id'
3250 description: Video to add in the playlist
3254 description: Start the video at this specific timestamp
3258 description: Stop the video at this specific timestamp
3262 /video-playlists/{playlistId}/videos/reorder:
3264 summary: 'Reorder a playlist'
3265 operationId: reorderVideoPlaylist
3271 - $ref: '#/components/parameters/playlistId'
3274 description: successful operation
3283 description: 'Start position of the element to reorder'
3285 insertAfterPosition:
3287 description: 'New position for the block to reorder, to add the block before the first element'
3291 description: 'How many element from `startPosition` to reorder'
3295 - insertAfterPosition
3297 /video-playlists/{playlistId}/videos/{playlistElementId}:
3299 summary: Update a playlist element
3300 operationId: putVideoPlaylistVideo
3306 - $ref: '#/components/parameters/playlistId'
3307 - $ref: '#/components/parameters/playlistElementId'
3310 description: successful operation
3320 description: Start the video at this specific timestamp
3324 description: Stop the video at this specific timestamp
3326 summary: Delete an element from a playlist
3327 operationId: delVideoPlaylistVideo
3333 - $ref: '#/components/parameters/playlistId'
3334 - $ref: '#/components/parameters/playlistElementId'
3337 description: successful operation
3339 '/users/me/video-playlists/videos-exist':
3341 summary: Check video exists in my playlists
3350 description: The video ids to check
3354 $ref: '#/components/schemas/Video/properties/id'
3357 description: successful operation
3379 '/accounts/{name}/video-channels':
3381 summary: List video channels of an account
3386 - $ref: '#/components/parameters/name'
3389 description: include view statistics for the last 30 days (only if authentified as the account user)
3392 - $ref: '#/components/parameters/start'
3393 - $ref: '#/components/parameters/count'
3394 - $ref: '#/components/parameters/sort'
3397 description: successful operation
3401 $ref: '#/components/schemas/VideoChannelList'
3403 '/accounts/{name}/ratings':
3405 summary: List ratings of an account
3411 - $ref: '#/components/parameters/name'
3412 - $ref: '#/components/parameters/start'
3413 - $ref: '#/components/parameters/count'
3414 - $ref: '#/components/parameters/sort'
3418 description: Optionally filter which ratings to retrieve
3426 description: successful operation
3432 $ref: '#/components/schemas/VideoRating'
3434 '/videos/{id}/comment-threads':
3436 summary: List threads of a video
3440 - $ref: '#/components/parameters/idOrUUID'
3441 - $ref: '#/components/parameters/start'
3442 - $ref: '#/components/parameters/count'
3443 - $ref: '#/components/parameters/commentsSort'
3446 description: successful operation
3450 $ref: '#/components/schemas/CommentThreadResponse'
3452 summary: Create a thread
3458 - $ref: '#/components/parameters/idOrUUID'
3461 description: successful operation
3465 $ref: '#/components/schemas/CommentThreadPostResponse'
3467 description: video does not exist
3476 - $ref: '#/components/schemas/VideoComment/properties/text'
3482 '/videos/{id}/comment-threads/{threadId}':
3484 summary: Get a thread
3488 - $ref: '#/components/parameters/idOrUUID'
3489 - $ref: '#/components/parameters/threadId'
3492 description: successful operation
3496 $ref: '#/components/schemas/VideoCommentThreadTree'
3498 '/videos/{id}/comments/{commentId}':
3500 summary: Reply to a thread of a video
3506 - $ref: '#/components/parameters/idOrUUID'
3507 - $ref: '#/components/parameters/commentId'
3510 description: successful operation
3514 $ref: '#/components/schemas/CommentThreadPostResponse'
3516 description: thread or video does not exist
3525 - $ref: '#/components/schemas/VideoComment/properties/text'
3531 summary: Delete a comment or a reply
3537 - $ref: '#/components/parameters/idOrUUID'
3538 - $ref: '#/components/parameters/commentId'
3541 description: successful operation
3543 description: cannot remove comment of another user
3545 description: comment or video does not exist
3547 description: comment is already deleted
3549 '/videos/{id}/rate':
3551 summary: Like/dislike a video
3557 - $ref: '#/components/parameters/idOrUUID'
3573 description: successful operation
3575 description: video does not exist
3579 summary: Delete video HLS files
3585 operationId: delVideoHLS
3587 - $ref: '#/components/parameters/idOrUUID'
3590 description: successful operation
3592 description: video does not exist
3593 '/videos/{id}/webtorrent':
3595 summary: Delete video WebTorrent files
3601 operationId: delVideoWebTorrent
3603 - $ref: '#/components/parameters/idOrUUID'
3606 description: successful operation
3608 description: video does not exist
3610 '/videos/{id}/transcoding':
3612 summary: Create a transcoding job
3618 operationId: createVideoTranscoding
3620 - $ref: '#/components/parameters/idOrUUID'
3636 description: successful operation
3638 description: video does not exist
3644 summary: Search videos
3645 operationId: searchVideos
3650 allowEmptyValue: false
3652 String to search. If the user can make a remote URI search, and the string is an URI then the
3653 PeerTube instance will fetch the remote object and add it to its database. Then,
3654 you can use the REST API to fetch the complete video information and interact with it.
3657 - $ref: '#/components/parameters/categoryOneOf'
3658 - $ref: '#/components/parameters/isLive'
3659 - $ref: '#/components/parameters/tagsOneOf'
3660 - $ref: '#/components/parameters/tagsAllOf'
3661 - $ref: '#/components/parameters/licenceOneOf'
3662 - $ref: '#/components/parameters/languageOneOf'
3663 - $ref: '#/components/parameters/nsfw'
3664 - $ref: '#/components/parameters/isLocal'
3665 - $ref: '#/components/parameters/include'
3666 - $ref: '#/components/parameters/privacyOneOf'
3667 - $ref: '#/components/parameters/hasHLSFiles'
3668 - $ref: '#/components/parameters/hasWebtorrentFiles'
3669 - $ref: '#/components/parameters/skipCount'
3670 - $ref: '#/components/parameters/start'
3671 - $ref: '#/components/parameters/count'
3672 - $ref: '#/components/parameters/searchTarget'
3673 - $ref: '#/components/parameters/videosSearchSort'
3676 description: Get videos that are published after this date
3682 description: Get videos that are published before this date
3686 - name: originallyPublishedStartDate
3688 description: Get videos that are originally published after this date
3692 - name: originallyPublishedEndDate
3694 description: Get videos that are originally published before this date
3700 description: Get videos that have this minimum duration
3705 description: Get videos that have this maximum duration
3709 'searchTarget === search-index':
3710 $ref: '#/components/callbacks/searchIndex'
3713 description: successful operation
3717 $ref: '#/components/schemas/VideoListResponse'
3719 description: search index unavailable
3721 /search/video-channels:
3725 summary: Search channels
3726 operationId: searchChannels
3732 String to search. If the user can make a remote URI search, and the string is an URI then the
3733 PeerTube instance will fetch the remote object and add it to its database. Then,
3734 you can use the REST API to fetch the complete channel information and interact with it.
3737 - $ref: '#/components/parameters/start'
3738 - $ref: '#/components/parameters/count'
3739 - $ref: '#/components/parameters/searchTarget'
3740 - $ref: '#/components/parameters/sort'
3742 'searchTarget === search-index':
3743 $ref: '#/components/callbacks/searchIndex'
3746 description: successful operation
3750 $ref: '#/components/schemas/VideoChannelList'
3752 description: search index unavailable
3754 /search/video-playlists:
3758 summary: Search playlists
3759 operationId: searchPlaylists
3765 String to search. If the user can make a remote URI search, and the string is an URI then the
3766 PeerTube instance will fetch the remote object and add it to its database. Then,
3767 you can use the REST API to fetch the complete playlist information and interact with it.
3770 - $ref: '#/components/parameters/start'
3771 - $ref: '#/components/parameters/count'
3772 - $ref: '#/components/parameters/searchTarget'
3773 - $ref: '#/components/parameters/sort'
3775 'searchTarget === search-index':
3776 $ref: '#/components/callbacks/searchIndex'
3779 description: successful operation
3791 $ref: '#/components/schemas/VideoPlaylist'
3793 description: search index unavailable
3795 /server/blocklist/accounts:
3799 summary: List account blocks
3804 - $ref: '#/components/parameters/start'
3805 - $ref: '#/components/parameters/count'
3806 - $ref: '#/components/parameters/sort'
3809 description: successful operation
3813 summary: Block an account
3825 example: chocobozzz@example.org
3826 description: account to block, in the form `username@domain`
3831 description: successful operation
3833 description: self-blocking forbidden
3835 '/server/blocklist/accounts/{accountName}':
3839 summary: Unblock an account by its handle
3847 description: account to unblock, in the form `username@domain`
3852 description: successful operation
3854 description: account or account block does not exist
3856 /server/blocklist/servers:
3860 summary: List server blocks
3865 - $ref: '#/components/parameters/start'
3866 - $ref: '#/components/parameters/count'
3867 - $ref: '#/components/parameters/sort'
3870 description: successful operation
3874 summary: Block a server
3887 description: server domain to block
3892 description: successful operation
3894 description: self-blocking forbidden
3896 '/server/blocklist/servers/{host}':
3900 summary: Unblock a server by its domain
3908 description: server domain to unblock
3914 description: successful operation
3916 description: account block does not exist
3918 /server/redundancy/{host}:
3921 - Instance Redundancy
3922 summary: Update a server redundancy policy
3930 description: server domain to mirror
3942 description: allow mirroring of the host's local videos
3947 description: successful operation
3949 description: server is not already known
3951 /server/redundancy/videos:
3955 summary: List videos being mirrored
3956 operationId: getMirroredVideos
3964 description: direction of the mirror
3970 - $ref: '#/components/parameters/start'
3971 - $ref: '#/components/parameters/count'
3972 - $ref: '#/components/parameters/videoRedundanciesSort'
3975 description: successful operation
3981 $ref: '#/components/schemas/VideoRedundancy'
3985 summary: Mirror a video
3986 operationId: putMirroredVideo
3997 $ref: '#/components/schemas/Video/properties/id'
4002 description: successful operation
4004 description: cannot mirror a local video
4006 description: video does not exist
4008 description: video is already mirrored
4010 /server/redundancy/videos/{redundancyId}:
4014 summary: Delete a mirror done on a video
4015 operationId: delMirroredVideo
4020 - name: redundancyId
4023 description: id of an existing redundancy on a video
4028 description: successful operation
4030 description: video redundancy not found
4032 '/feeds/video-comments.{format}':
4036 summary: List comments on videos
4037 operationId: getSyndicatedComments
4042 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4055 description: 'limit listing to a specific video'
4060 description: 'limit listing to a specific account'
4065 description: 'limit listing to a specific account'
4068 - name: videoChannelId
4070 description: 'limit listing to a specific video channel'
4073 - name: videoChannelName
4075 description: 'limit listing to a specific video channel'
4080 description: successful operation
4085 default: 'max-age=900' # 15 min cache
4089 $ref: '#/components/schemas/VideoCommentsForXML'
4092 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4093 application/rss+xml:
4095 $ref: '#/components/schemas/VideoCommentsForXML'
4098 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4101 $ref: '#/components/schemas/VideoCommentsForXML'
4104 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4105 application/atom+xml:
4107 $ref: '#/components/schemas/VideoCommentsForXML'
4110 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4116 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4118 x-summary: field inconsistencies
4121 - videoId filter is mixed with a channel filter
4123 description: video, video channel or account not found
4125 description: accept header unsupported
4127 '/feeds/videos.{format}':
4131 summary: List videos
4132 operationId: getSyndicatedVideos
4137 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4150 description: 'limit listing to a specific account'
4155 description: 'limit listing to a specific account'
4158 - name: videoChannelId
4160 description: 'limit listing to a specific video channel'
4163 - name: videoChannelName
4165 description: 'limit listing to a specific video channel'
4168 - $ref: '#/components/parameters/sort'
4169 - $ref: '#/components/parameters/nsfw'
4170 - $ref: '#/components/parameters/isLocal'
4171 - $ref: '#/components/parameters/include'
4172 - $ref: '#/components/parameters/privacyOneOf'
4173 - $ref: '#/components/parameters/hasHLSFiles'
4174 - $ref: '#/components/parameters/hasWebtorrentFiles'
4177 description: successful operation
4182 default: 'max-age=900' # 15 min cache
4186 $ref: '#/components/schemas/VideosForXML'
4189 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4190 application/rss+xml:
4192 $ref: '#/components/schemas/VideosForXML'
4195 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4198 $ref: '#/components/schemas/VideosForXML'
4201 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4202 application/atom+xml:
4204 $ref: '#/components/schemas/VideosForXML'
4207 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4213 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4215 description: video channel or account not found
4217 description: accept header unsupported
4219 '/feeds/subscriptions.{format}':
4224 summary: List videos of subscriptions tied to a token
4225 operationId: getSyndicatedSubscriptionVideos
4230 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4243 description: limit listing to a specific account
4249 description: private token allowing access
4253 - $ref: '#/components/parameters/sort'
4254 - $ref: '#/components/parameters/nsfw'
4255 - $ref: '#/components/parameters/isLocal'
4256 - $ref: '#/components/parameters/include'
4257 - $ref: '#/components/parameters/privacyOneOf'
4258 - $ref: '#/components/parameters/hasHLSFiles'
4259 - $ref: '#/components/parameters/hasWebtorrentFiles'
4262 description: successful operation
4267 default: 'max-age=900' # 15 min cache
4271 $ref: '#/components/schemas/VideosForXML'
4272 application/rss+xml:
4274 $ref: '#/components/schemas/VideosForXML'
4277 $ref: '#/components/schemas/VideosForXML'
4278 application/atom+xml:
4280 $ref: '#/components/schemas/VideosForXML'
4285 description: accept header unsupported
4291 summary: List plugins
4292 operationId: getPlugins
4305 - $ref: '#/components/parameters/start'
4306 - $ref: '#/components/parameters/count'
4307 - $ref: '#/components/parameters/sort'
4310 description: successful operation
4314 $ref: '#/components/schemas/PluginResponse'
4320 summary: List available plugins
4321 operationId: getAvailablePlugins
4334 - name: currentPeerTubeEngine
4338 - $ref: '#/components/parameters/start'
4339 - $ref: '#/components/parameters/count'
4340 - $ref: '#/components/parameters/sort'
4343 description: successful operation
4347 $ref: '#/components/schemas/PluginResponse'
4349 description: plugin index unavailable
4355 summary: Install a plugin
4356 operationId: addPlugin
4369 example: peertube-plugin-auth-ldap
4372 additionalProperties: false
4379 additionalProperties: false
4382 description: successful operation
4384 description: should have either `npmName` or `path` set
4390 summary: Update a plugin
4391 operationId: updatePlugin
4404 example: peertube-plugin-auth-ldap
4407 additionalProperties: false
4414 additionalProperties: false
4417 description: successful operation
4419 description: should have either `npmName` or `path` set
4421 description: existing plugin not found
4427 summary: Uninstall a plugin
4428 operationId: uninstallPlugin
4440 description: name of the plugin/theme in its package.json
4441 example: peertube-plugin-auth-ldap
4446 description: successful operation
4448 description: existing plugin not found
4454 summary: Get a plugin
4455 operationId: getPlugin
4460 - $ref: '#/components/parameters/npmName'
4463 description: successful operation
4467 $ref: '#/components/schemas/Plugin'
4469 description: plugin not found
4471 /plugins/{npmName}/settings:
4475 summary: Set a plugin's settings
4480 - $ref: '#/components/parameters/npmName'
4489 additionalProperties: true
4492 description: successful operation
4494 description: plugin not found
4496 /plugins/{npmName}/public-settings:
4500 summary: Get a plugin's public settings
4502 - $ref: '#/components/parameters/npmName'
4505 description: successful operation
4510 additionalProperties: true
4512 description: plugin not found
4514 /plugins/{npmName}/registered-settings:
4518 summary: Get a plugin's registered settings
4523 - $ref: '#/components/parameters/npmName'
4526 description: successful operation
4531 additionalProperties: true
4533 description: plugin not found
4536 - url: 'https://peertube2.cpy.re/api/v1'
4537 description: Live Test Server (live data - latest nightly version)
4538 - url: 'https://peertube3.cpy.re/api/v1'
4539 description: Live Test Server (live data - latest RC version)
4540 - url: 'https://peertube.cpy.re/api/v1'
4541 description: Live Test Server (live data - stable version)
4548 description: Offset used to paginate results
4556 description: "Number of items to return"
4566 description: Sort column
4574 description: Plain text search, applied to various parts of the model depending on endpoint
4582 If the administrator enabled search index support, you can override the default search target.
4585 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4586 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4587 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4588 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4589 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4590 * 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
4591 the data from the origin instance API
4601 description: Sort videos by criteria
4617 description: Sort videos by criteria
4632 description: Sort comments by criteria
4642 description: Sort blocklists by criteria
4658 description: Plain text search that will match with user usernames or emails
4665 description: Filter results down to (un)banned users
4672 description: Sort users by criteria
4683 description: Sort abuses by criteria
4690 videoRedundanciesSort:
4694 description: Sort abuses by criteria
4703 description: Sort followers by criteria
4712 description: The username or handle of the account
4715 example: chocobozzz | chocobozzz@example.org
4720 description: The user id
4722 $ref: '#/components/schemas/id'
4727 description: The object id, uuid or short uuid
4730 - $ref: '#/components/schemas/id'
4731 - $ref: '#/components/schemas/UUIDv4'
4732 - $ref: '#/components/schemas/shortUUID'
4737 description: Playlist id
4739 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4741 name: playlistElementId
4744 description: Playlist element id
4746 $ref: '#/components/schemas/id'
4751 description: Abuse id
4753 $ref: '#/components/schemas/Abuse/properties/id'
4755 name: abuseMessageId
4758 description: Abuse message id
4760 $ref: '#/components/schemas/AbuseMessage/properties/id'
4762 name: captionLanguage
4765 description: The caption language
4767 $ref: '#/components/schemas/VideoLanguageSet'
4772 description: The video channel handle
4775 example: my_username | my_username@example.com
4777 name: subscriptionHandle
4780 description: The subscription handle
4783 example: my_username | my_username@example.com
4788 description: The thread id (root comment id)
4795 description: The comment id
4797 $ref: '#/components/schemas/VideoComment/properties/id'
4802 description: whether or not the video is a live
4809 description: category id of the video (see [/videos/categories](#operation/getCategories))
4812 - $ref: '#/components/schemas/VideoCategorySet'
4815 $ref: '#/components/schemas/VideoCategorySet'
4822 description: tag(s) of the video
4836 description: tag(s) of the video, where all should be present in the video
4849 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4852 - $ref: '#/components/schemas/VideoLanguageSet'
4855 $ref: '#/components/schemas/VideoLanguageSet'
4862 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4865 - $ref: '#/components/schemas/VideoLicenceSet'
4868 $ref: '#/components/schemas/VideoLicenceSet'
4875 description: if you don't need the `total` in the response
4886 description: whether to include nsfw videos, if any
4898 description: '**PeerTube >= 4.0** Display only local or remote videos'
4905 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
4907 name: hasWebtorrentFiles
4912 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
4918 $ref: '#/components/schemas/VideoPrivacySet'
4919 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
4933 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
4937 - `1` NOT_PUBLISHED_STATE
4948 description: list of uris to check if each is part of the user subscriptions
4958 description: name of the plugin/theme on npmjs.com or in its package.json
4961 example: peertube-plugin-auth-ldap
4966 description: job type
4970 - activitypub-follow
4971 - activitypub-http-broadcast
4972 - activitypub-http-fetcher
4973 - activitypub-http-unicast
4978 - videos-views-stats
4979 - activitypub-refresher
5004 Authenticating via OAuth requires the following steps:
5005 - Have an activated account
5006 - [Generate] an access token for that account at `/api/v1/users/token`.
5007 - Make requests with the *Authorization: Bearer <token\>* header
5008 - Profit, depending on the role assigned to the account
5010 Note that the __access token is valid for 1 day__ and is given
5011 along with a __refresh token valid for 2 weeks__.
5013 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5017 tokenUrl: /api/v1/users/token
5020 moderator: Moderator scope
5023 # Resuable core properties
5031 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5032 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5037 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5038 example: 2y84q2MQUMWPbiEcxNXMgC
5041 description: immutable name of the user, used to find or mention its actor
5043 pattern: '/^[a-z0-9._]+$/'
5048 description: immutable name of the channel, used to interact with its actor
5049 example: framasoft_videos
5050 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5061 description: category id of the video (see [/videos/categories](#operation/getCategories))
5063 VideoConstantNumber-Category:
5066 $ref: '#/components/schemas/VideoCategorySet'
5069 example: Science & Technology
5073 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5075 VideoConstantNumber-Licence:
5078 $ref: '#/components/schemas/VideoLicenceSet'
5081 example: Attribution - Share Alike
5085 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5087 VideoConstantString-Language:
5090 $ref: '#/components/schemas/VideoLanguageSet'
5095 VideoPlaylistPrivacySet:
5101 description: Video playlist privacy policy (see [/video-playlists/privacies])
5102 VideoPlaylistPrivacyConstant:
5105 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5109 VideoPlaylistTypeSet:
5114 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5115 VideoPlaylistTypeConstant:
5118 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5129 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5130 VideoPrivacyConstant:
5133 $ref: '#/components/schemas/VideoPrivacySet'
5150 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5157 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5168 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5178 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5182 $ref: '#/components/schemas/AbuseStateSet'
5185 AbusePredefinedReasons:
5198 example: [spamOrMisleading]
5203 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5205 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5207 VideoResolutionConstant:
5208 description: resolutions and their labels for the video
5211 $ref: '#/components/schemas/VideoResolutionSet'
5215 VideoScheduledUpdate:
5218 $ref: '#/components/schemas/VideoPrivacySet'
5222 description: When to update the video
5242 - $ref: '#/components/schemas/ActorImage'
5243 VideoChannelSummary:
5246 $ref: '#/components/schemas/id'
5260 - $ref: '#/components/schemas/ActorImage'
5274 - $ref: '#/components/schemas/Video'
5281 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5282 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5284 $ref: '#/components/schemas/VideoResolutionConstant'
5287 description: Video file size in bytes
5290 description: Direct URL of the torrent file
5294 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5298 description: Direct URL of the video
5302 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5306 description: Frames per second of the video file
5310 description: URL dereferencing the output of ffprobe on the file
5311 VideoStreamingPlaylists:
5316 $ref: '#/components/schemas/id'
5324 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5325 VideoStreamingPlaylists-HLS:
5336 Video files associated to this playlist.
5338 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5340 $ref: '#/components/schemas/VideoFile'
5352 $ref: '#/components/schemas/Video/properties/id'
5354 $ref: '#/components/schemas/Video/properties/uuid'
5356 $ref: '#/components/schemas/Video/properties/name'
5360 description: object id for the video
5362 - $ref: '#/components/schemas/id'
5364 description: universal identifier for the video, that can be used across instances
5366 - $ref: '#/components/schemas/UUIDv4'
5369 - $ref: '#/components/schemas/shortUUID'
5375 example: 2017-10-01T10:52:46.396Z
5376 description: time at which the video object was first drafted
5380 example: 2018-10-01T10:52:46.396Z
5381 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5385 example: 2021-05-04T08:01:01.502Z
5386 description: last time the video's metadata was modified
5387 originallyPublishedAt:
5390 example: 2010-10-01T10:52:46.396Z
5391 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5394 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5395 description: category in which the video is classified
5398 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5399 description: licence under which the video is distributed
5402 - $ref: '#/components/schemas/VideoConstantString-Language'
5403 description: main language used in the video
5406 - $ref: '#/components/schemas/VideoPrivacyConstant'
5407 description: privacy policy used to distribute the video
5411 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5412 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5416 truncated description of the video, written in Markdown.
5417 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5422 description: duration of the video in seconds
5427 description: title of the video
5428 example: What is PeerTube?
5433 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5436 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5439 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5456 - $ref: '#/components/schemas/VideoStateConstant'
5457 description: represents the internal state of the video processing within the PeerTube instance
5461 - $ref: '#/components/schemas/VideoScheduledUpdate'
5469 $ref: '#/components/schemas/AccountSummary'
5471 $ref: '#/components/schemas/VideoChannelSummary'
5480 - $ref: '#/components/schemas/Video'
5485 description: If the video is a live, you have the amount of current viewers
5488 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5489 description: path at which to get the full description of maximum `10000` characters
5492 description: A text tell the audience how to support the video creator
5493 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5497 $ref: '#/components/schemas/VideoChannel'
5499 $ref: '#/components/schemas/Account'
5501 example: [flowers, gardening]
5519 - https://peertube2.cpy.re/tracker/announce
5520 - wss://peertube2.cpy.re/tracker/socket
5524 $ref: '#/components/schemas/VideoFile'
5526 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5528 - field will be empty
5529 - video files will be found in `streamingPlaylists[].files` field
5533 $ref: '#/components/schemas/VideoStreamingPlaylists'
5535 HLS playlists/manifest files. If HLS is disabled on the server:
5537 - field will be empty
5538 - video files will be found in `files` field
5539 FileRedundancyInformation:
5542 $ref: '#/components/schemas/id'
5567 $ref: '#/components/schemas/id'
5574 $ref: '#/components/schemas/UUIDv4'
5581 $ref: '#/components/schemas/FileRedundancyInformation'
5585 $ref: '#/components/schemas/FileRedundancyInformation'
5586 VideoImportStateConstant:
5594 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5601 additionalProperties: false
5605 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5606 required: [targetUrl]
5609 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5610 required: [magnetUri]
5613 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5614 required: [torrentfile]
5615 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5624 - $ref: '#/components/schemas/id'
5628 description: remote URL where to find the import's source video
5629 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5633 description: magnet URI allowing to resolve the import's source video
5634 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5639 description: Torrent file containing only the video file
5646 - $ref: '#/components/schemas/VideoImportStateConstant'
5662 - $ref: '#/components/schemas/Video'
5672 $ref: '#/components/schemas/VideoImport'
5676 $ref: '#/components/schemas/id'
5679 example: The video is a spam
5683 $ref: '#/components/schemas/AbusePredefinedReasons'
5685 $ref: '#/components/schemas/Account'
5687 $ref: '#/components/schemas/AbuseStateConstant'
5690 example: Decided to ban the server since it spams us regularly
5694 $ref: '#/components/schemas/VideoInfo'
5701 $ref: '#/components/schemas/id'
5712 $ref: '#/components/schemas/AccountSummary'
5716 $ref: '#/components/schemas/id'
5718 $ref: '#/components/schemas/Video/properties/id'
5730 $ref: '#/components/schemas/UUIDv4'
5748 $ref: '#/components/schemas/id'
5750 $ref: '#/components/schemas/UUIDv4'
5753 - $ref: '#/components/schemas/shortUUID'
5776 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5778 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5780 $ref: '#/components/schemas/AccountSummary'
5782 $ref: '#/components/schemas/VideoChannelSummary'
5786 $ref: '#/components/schemas/id'
5793 description: Text of the comment
5795 example: This video is wonderful!
5797 $ref: '#/components/schemas/id'
5801 - $ref: '#/components/schemas/id'
5803 $ref: '#/components/schemas/Video/properties/id'
5818 totalRepliesFromVideoAuthor:
5825 $ref: '#/components/schemas/Account'
5826 VideoCommentThreadTree:
5829 $ref: '#/components/schemas/VideoComment'
5833 $ref: '#/components/schemas/VideoCommentThreadTree'
5837 $ref: '#/components/schemas/VideoConstantString-Language'
5853 $ref: '#/components/schemas/id'
5870 $ref: '#/components/schemas/id'
5875 description: immutable name of the actor, used to find or mention it
5877 - $ref: '#/components/schemas/username'
5881 description: server on which the actor is resident
5882 hostRedundancyAllowed:
5884 description: whether this actor's host allows redundancy of its videos
5888 description: number of actors subscribed to by this actor, as seen by this instance
5892 description: number of followers of this actor, as seen by this instance
5900 $ref: '#/components/schemas/ActorImage'
5903 - $ref: '#/components/schemas/Actor'
5906 description: object id for the user tied to this account
5908 - $ref: '#/components/schemas/User/properties/id'
5911 description: editable name of the account, displayed in its representations
5916 description: text or bio displayed on the account's profile
5922 description: timestamp within the video, in seconds
5989 allowedForCurrentIP:
5991 requiresEmailVerification:
6009 $ref: '#/components/schemas/VideoResolutionSet'
6094 example: 16810141515
6203 requiresEmailVerification:
6218 description: Settings that apply to new users, if registration is enabled
6222 example: 16810141515
6228 description: Settings pertaining to transcoding jobs
6232 allowAdditionalExtensions:
6234 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6237 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6240 description: Amount of threads used by ffmpeg for 1 transcoding job
6243 description: Amount of transcoding jobs to execute in parallel
6249 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6252 description: Resolutions to transcode _new videos_ to
6274 description: WebTorrent-specific settings
6280 description: HLS-specific settings
6330 $ref: '#/components/schemas/id'
6332 $ref: '#/components/schemas/Actor'
6334 $ref: '#/components/schemas/Actor'
6337 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6350 PredefinedAbuseReasons:
6351 description: Reason categories that help triage reports
6369 $ref: '#/components/schemas/id'
6381 - activitypub-http-unicast
6382 - activitypub-http-broadcast
6383 - activitypub-http-fetcher
6384 - activitypub-follow
6389 - videos-views-stats
6390 - activitypub-refresher
6394 additionalProperties: true
6397 additionalProperties: true
6413 $ref: '#/components/schemas/id'
6418 $ref: '#/components/schemas/id'
6419 VideoUploadRequestCommon:
6422 description: Video name
6424 example: What is PeerTube?
6428 description: Channel id that will contain this video
6433 $ref: '#/components/schemas/VideoPrivacySet'
6435 $ref: '#/components/schemas/VideoCategorySet'
6437 $ref: '#/components/schemas/VideoLicenceSet'
6439 $ref: '#/components/schemas/VideoLanguageSet'
6441 description: Video description
6444 **[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)**
6446 description: Whether or not we wait transcoding before publish the video
6449 description: A text tell the audience how to support the video creator
6450 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6453 description: Whether or not this video contains sensitive content
6456 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6469 description: Enable or disable comments for this video
6472 description: Enable or disable downloading for this video
6474 originallyPublishedAt:
6475 description: Date when the content was originally published
6479 $ref: '#/components/schemas/VideoScheduledUpdate'
6481 description: Video thumbnail file
6485 description: Video preview file
6491 VideoUploadRequestLegacy:
6493 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6499 description: Video file
6502 VideoUploadRequestResumable:
6504 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6510 description: Video filename including extension
6513 example: what_is_peertube.mp4
6515 description: Video thumbnail file
6519 description: Video preview file
6522 VideoUploadResponse:
6528 $ref: '#/components/schemas/Video/properties/id'
6530 $ref: '#/components/schemas/Video/properties/uuid'
6532 $ref: '#/components/schemas/Video/properties/shortUUID'
6533 CommentThreadResponse:
6542 $ref: '#/components/schemas/VideoComment'
6543 CommentThreadPostResponse:
6546 $ref: '#/components/schemas/VideoComment'
6556 $ref: '#/components/schemas/Video'
6560 $ref: '#/components/schemas/Account'
6563 description: Automatically start playing the upcoming video after the currently playing video
6564 autoPlayNextVideoPlaylist:
6566 description: Automatically start playing the video on the playlist after the currently playing video
6569 description: Automatically start playing the video on the watch page
6579 description: The user email
6582 description: Has the user confirmed their email address?
6585 - $ref: '#/components/schemas/id'
6589 description: Auth plugin to use to authenticate the user
6593 noInstanceConfigWarningModal:
6595 noAccountSetupWarningModal:
6600 $ref: '#/components/schemas/NSFWPolicy'
6602 $ref: '#/components/schemas/UserRole'
6611 description: Theme enabled by this user
6613 $ref: '#/components/schemas/username'
6617 $ref: '#/components/schemas/VideoChannel'
6620 description: The user video quota in bytes
6624 description: The user daily video quota in bytes
6628 description: Enable P2P in the player
6631 - $ref: '#/components/schemas/User'
6633 # optionally present fields: they require WITH_STATS scope
6636 description: Count of videos published
6639 description: Count of reports/abuses of which the user is a target
6640 abusesAcceptedCount:
6642 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6645 description: Count of reports/abuses created by the user
6648 description: Count of comments published
6652 $ref: '#/components/schemas/username'
6654 $ref: '#/components/schemas/password'
6658 description: The user email
6661 description: The user video quota in bytes
6665 description: The user daily video quota in bytes
6668 $ref: '#/components/schemas/usernameChannel'
6670 $ref: '#/components/schemas/UserRole'
6672 $ref: '#/components/schemas/UserAdminFlags'
6683 description: The updated email of the user
6685 - $ref: '#/components/schemas/User/properties/email'
6688 description: Set the email as verified
6691 description: The updated video quota of the user in bytes
6694 description: The updated daily video quota of the user in bytes
6698 description: The auth plugin to use to authenticate the user
6699 example: 'peertube-plugin-auth-saml2'
6701 $ref: '#/components/schemas/UserRole'
6703 $ref: '#/components/schemas/UserAdminFlags'
6705 # see shared/models/users/user-update-me.model.ts:
6708 $ref: '#/components/schemas/password'
6710 $ref: '#/components/schemas/password'
6712 description: new email used for login and service communications
6714 - $ref: '#/components/schemas/User/properties/email'
6717 description: new name of the user in its representations
6722 description: new NSFW display policy
6729 description: whether to enable P2P in the player or not
6732 description: new preference regarding playing videos automatically
6735 description: new preference regarding playing following videos automatically
6736 autoPlayNextVideoPlaylist:
6738 description: new preference regarding playing following playlist videos automatically
6739 videosHistoryEnabled:
6741 description: whether to keep track of watched history or not
6746 description: list of languages to filter videos down to
6749 noInstanceConfigWarningModal:
6751 noAccountSetupWarningModal:
6758 $ref: '#/components/schemas/id'
6765 description: Rating of the video
6772 $ref: '#/components/schemas/Video'
6779 description: Rating of the video
6786 description: immutable name of the user, used to find or mention its actor
6788 - $ref: '#/components/schemas/username'
6790 $ref: '#/components/schemas/password'
6794 description: email of the user, used for login or service communications
6797 description: editable name of the user, displayed in its representations
6802 description: channel base information used to create the first channel of the user
6805 $ref: '#/components/schemas/usernameChannel'
6807 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6817 pattern: /^[a-z0-9]$/
6820 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6823 pattern: /^[a-zA-Z0-9]$/
6826 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6827 OAuthToken-password:
6829 - $ref: '#/components/schemas/OAuthClient'
6839 $ref: '#/components/schemas/User/properties/username'
6841 $ref: '#/components/schemas/password'
6848 OAuthToken-refresh_token:
6850 - $ref: '#/components/schemas/OAuthClient'
6861 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6870 # GET/POST/PUT properties
6873 description: editable name of the channel, displayed in its representations
6874 example: Videos of Framasoft
6879 example: Videos made with <3 by Framasoft
6884 description: text shown by default on all videos of this channel, to tell the audience how to support it
6885 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6888 # GET-only properties
6892 - $ref: '#/components/schemas/id'
6908 $ref: '#/components/schemas/UUIDv4'
6911 - $ref: '#/components/schemas/VideoChannel'
6914 description: username of the channel to create
6916 - $ref: '#/components/schemas/usernameChannel'
6922 - $ref: '#/components/schemas/VideoChannel'
6924 bulkVideosSupportUpdate:
6926 description: Update the support field for all videos of this channel
6936 - $ref: '#/components/schemas/VideoChannel'
6937 - $ref: '#/components/schemas/Actor'
6942 name: 'media:peerLink'
6951 - application/x-bittorrent
6957 name: 'media:content'
6988 VideoCommentsForXML:
7023 description: video watch page URL
7026 description: video canonical URL
7030 description: video publication date
7033 description: video description
7036 description: video description
7039 description: publisher user name
7042 description: video category (MRSS)
7045 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7060 description: video embed path, relative to the canonical URL domain (MRSS)
7069 description: video watch path, relative to the canonical URL domain (MRSS)
7090 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7091 'media:description':
7098 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7101 description: main streamable file for the video
7111 - application/x-bittorrent
7120 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)
7123 - $ref: '#/components/schemas/MRSSPeerLink'
7124 - $ref: '#/components/schemas/MRSSGroupContent'
7125 NotificationSettingValue:
7142 $ref: '#/components/schemas/id'
7146 Notification type, following the `UserNotificationType` enum:
7148 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7150 - `2` NEW_COMMENT_ON_MY_VIDEO
7152 - `3` NEW_ABUSE_FOR_MODERATORS
7154 - `4` BLACKLIST_ON_MY_VIDEO
7156 - `5` UNBLACKLIST_ON_MY_VIDEO
7158 - `6` MY_VIDEO_PUBLISHED
7160 - `7` MY_VIDEO_IMPORT_SUCCESS
7162 - `8` MY_VIDEO_IMPORT_ERROR
7164 - `9` NEW_USER_REGISTRATION
7168 - `11` COMMENT_MENTION
7170 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7172 - `13` NEW_INSTANCE_FOLLOWER
7174 - `14` AUTO_INSTANCE_FOLLOWING
7180 - $ref: '#/components/schemas/VideoInfo'
7184 $ref: '#/components/schemas/ActorInfo'
7190 $ref: '#/components/schemas/id'
7193 $ref: '#/components/schemas/VideoInfo'
7198 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7208 $ref: '#/components/schemas/id'
7212 $ref: '#/components/schemas/VideoInfo'
7214 $ref: '#/components/schemas/ActorInfo'
7220 $ref: '#/components/schemas/id'
7223 - $ref: '#/components/schemas/VideoInfo'
7229 $ref: '#/components/schemas/id'
7232 - $ref: '#/components/schemas/VideoInfo'
7236 - $ref: '#/components/schemas/ActorInfo'
7242 $ref: '#/components/schemas/id'
7244 $ref: '#/components/schemas/ActorInfo'
7272 NotificationListResponse:
7281 $ref: '#/components/schemas/Notification'
7286 example: peertube-plugin-auth-ldap
7314 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7317 additionalProperties: true
7333 $ref: '#/components/schemas/Plugin'
7340 description: User can stream multiple times in a permanent live
7351 description: RTMP stream key to use to stream into this live video
7355 description: User can stream multiple times in a permanent live
7362 'https://search.example.org/api/v1/search/videos':
7364 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7367 description: successful operation
7371 $ref: '#/components/schemas/VideoListResponse'