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/{videoId}:
1481 summary: Delete history element
1491 $ref: '#/components/schemas/Video/properties/id'
1494 description: successful operation
1496 /users/me/history/videos/remove:
1498 summary: Clear video history
1505 multipart/form-data:
1510 description: history before this date will be deleted
1515 description: successful operation
1517 /users/me/avatar/pick:
1519 summary: Update my user avatar
1526 description: successful operation
1533 $ref: '#/components/schemas/ActorImage'
1535 description: image file too large
1537 X-File-Maximum-Size:
1541 description: Maximum file size for the avatar
1544 multipart/form-data:
1549 description: The file to upload
1554 contentType: image/png, image/jpeg
1558 summary: Delete my avatar
1565 description: successful operation
1569 summary: List video ownership changes
1571 - Video Ownership Change
1576 description: successful operation
1578 '/videos/ownership/{id}/accept':
1580 summary: Accept 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/ownership/{id}/refuse':
1597 summary: Refuse ownership change request
1599 - Video Ownership Change
1603 - $ref: '#/components/parameters/idOrUUID'
1606 description: successful operation
1608 description: cannot terminate an ownership change of another user
1610 description: video owneship change not found
1612 '/videos/{id}/give-ownership':
1614 summary: Request ownership change
1616 - Video Ownership Change
1620 - $ref: '#/components/parameters/idOrUUID'
1624 application/x-www-form-urlencoded:
1634 description: successful operation
1636 description: changing video ownership to a remote account is not supported yet
1638 description: video not found
1642 summary: List videos
1643 operationId: getVideos
1647 - $ref: '#/components/parameters/categoryOneOf'
1648 - $ref: '#/components/parameters/isLive'
1649 - $ref: '#/components/parameters/tagsOneOf'
1650 - $ref: '#/components/parameters/tagsAllOf'
1651 - $ref: '#/components/parameters/licenceOneOf'
1652 - $ref: '#/components/parameters/languageOneOf'
1653 - $ref: '#/components/parameters/nsfw'
1654 - $ref: '#/components/parameters/isLocal'
1655 - $ref: '#/components/parameters/include'
1656 - $ref: '#/components/parameters/privacyOneOf'
1657 - $ref: '#/components/parameters/hasHLSFiles'
1658 - $ref: '#/components/parameters/hasWebtorrentFiles'
1659 - $ref: '#/components/parameters/skipCount'
1660 - $ref: '#/components/parameters/start'
1661 - $ref: '#/components/parameters/count'
1662 - $ref: '#/components/parameters/videosSort'
1665 description: successful operation
1669 $ref: '#/components/schemas/VideoListResponse'
1673 summary: List available video categories
1674 operationId: getCategories
1679 description: successful operation
1688 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1692 summary: List available video licences
1693 operationId: getLicences
1698 description: successful operation
1707 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1711 summary: List available video languages
1712 operationId: getLanguages
1717 description: successful operation
1726 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1730 summary: List available video privacy policies
1731 operationId: getPrivacyPolicies
1736 description: successful operation
1745 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1749 summary: Update a video
1750 operationId: putVideo
1756 - $ref: '#/components/parameters/idOrUUID'
1759 description: successful operation
1762 multipart/form-data:
1767 description: Video thumbnail file
1771 description: Video preview file
1775 $ref: '#/components/schemas/VideoCategorySet'
1777 $ref: '#/components/schemas/VideoLicenceSet'
1779 $ref: '#/components/schemas/VideoLanguageSet'
1781 $ref: '#/components/schemas/VideoPrivacySet'
1783 description: Video description
1786 description: Whether or not we wait transcoding before publish the video
1789 description: A text tell the audience how to support the video creator
1790 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1793 description: Whether or not this video contains sensitive content
1796 description: Video name
1801 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1810 description: Enable or disable comments for this video
1813 description: Enable or disable downloading for this video
1815 originallyPublishedAt:
1816 description: Date when the content was originally published
1820 $ref: '#/components/schemas/VideoScheduledUpdate'
1823 contentType: image/jpeg
1825 contentType: image/jpeg
1827 summary: Get a video
1828 operationId: getVideo
1832 - $ref: '#/components/parameters/idOrUUID'
1835 description: successful operation
1839 $ref: '#/components/schemas/VideoDetails'
1841 summary: Delete a video
1842 operationId: delVideo
1848 - $ref: '#/components/parameters/idOrUUID'
1851 description: successful operation
1853 '/videos/{id}/description':
1855 summary: Get complete video description
1856 operationId: getVideoDesc
1860 - $ref: '#/components/parameters/idOrUUID'
1863 description: successful operation
1872 **[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)**
1874 '/videos/{id}/views':
1876 summary: Add a view to a video
1877 operationId: addView
1881 - $ref: '#/components/parameters/idOrUUID'
1884 description: successful operation
1886 '/videos/{id}/watching':
1888 summary: Set watching progress of a video
1889 operationId: setProgress
1895 - $ref: '#/components/parameters/idOrUUID'
1900 $ref: '#/components/schemas/UserWatchingVideo'
1904 description: successful operation
1908 summary: Upload a video
1909 description: Uses a single request to upload a video.
1910 operationId: uploadLegacy
1918 description: successful operation
1922 $ref: '#/components/schemas/VideoUploadResponse'
1924 description: video didn't pass upload filter
1926 description: upload has timed out
1928 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1930 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1931 - `quota_reached` for quota limits wether daily or global
1933 X-File-Maximum-Size:
1937 description: Maximum file size for the video
1939 description: video type unsupported
1941 description: video unreadable
1944 multipart/form-data:
1946 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1949 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1951 contentType: image/jpeg
1953 contentType: image/jpeg
1958 USERNAME="<your_username>"
1959 PASSWORD="<your_password>"
1960 FILE_PATH="<your_file_path>"
1961 CHANNEL_ID="<your_channel_id>"
1963 API="https://peertube2.cpy.re/api/v1"
1966 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1967 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1968 token=$(curl -s "$API/users/token" \
1969 --data client_id="$client_id" \
1970 --data client_secret="$client_secret" \
1971 --data grant_type=password \
1972 --data username="$USERNAME" \
1973 --data password="$PASSWORD" \
1974 | jq -r ".access_token")
1977 curl -s "$API/videos/upload" \
1978 -H "Authorization: Bearer $token" \
1980 --form videofile=@"$FILE_PATH" \
1981 --form channelId=$CHANNEL_ID \
1984 /videos/upload-resumable:
1986 summary: Initialize the resumable upload of a video
1987 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1988 operationId: uploadResumableInit
1995 - name: X-Upload-Content-Length
2001 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
2002 - name: X-Upload-Content-Type
2009 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
2014 $ref: '#/components/schemas/VideoUploadRequestResumable'
2017 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2019 description: created
2025 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2031 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2033 Disambiguate via `type`:
2034 - `max_file_size_reached` for the absolute file size limit
2035 - `quota_reached` for quota limits whether daily or global
2037 description: video type unsupported
2039 summary: Send chunk for the resumable upload of a video
2040 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
2041 operationId: uploadResumable
2052 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2053 not valid anymore and you need to initialize a new upload.
2056 - name: Content-Range
2060 example: bytes 0-262143/2469036
2063 Specifies the bytes in the file that the request is uploading.
2065 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2066 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2067 - name: Content-Length
2074 Size of the chunk that the request is sending.
2076 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)
2077 doesn't mandate for chunks to have the same size throughout the upload sequence.
2079 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2080 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2083 application/octet-stream:
2089 description: last chunk received
2097 $ref: '#/components/schemas/VideoUploadResponse'
2099 description: resume incomplete
2104 example: bytes=0-262143
2110 description: video didn't pass upload filter
2112 description: upload not found
2114 description: chunk doesn't match range
2116 description: video unreadable
2118 description: too many concurrent requests
2120 description: upload is already being processed
2127 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2128 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2129 operationId: uploadResumableCancel
2140 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2141 not valid anymore and the upload session has already been deleted with its data ;-)
2144 - name: Content-Length
2152 description: upload cancelled
2159 description: upload not found
2163 summary: Import a video
2164 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2165 operationId: importVideo
2173 multipart/form-data:
2175 $ref: '#/components/schemas/VideoCreateImport'
2178 contentType: application/x-bittorrent
2180 contentType: image/jpeg
2182 contentType: image/jpeg
2185 description: successful operation
2189 $ref: '#/components/schemas/VideoUploadResponse'
2191 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2193 description: video didn't pass pre-import filter
2195 description: HTTP or Torrent/magnetURI import not enabled
2199 summary: Create a live
2200 operationId: addLive
2208 description: successful operation
2212 $ref: '#/components/schemas/VideoUploadResponse'
2214 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2216 Disambiguate via `type`:
2217 - default type for a validation error
2218 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2220 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2222 Disambiguate via `type`:
2223 - `live_not_enabled` for a disabled live feature
2224 - `live_not_allowing_replay` for a disabled replay feature
2225 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2226 - `max_user_lives_limit_reached` for the user concurrent live limit
2229 multipart/form-data:
2234 description: Channel id that will contain this live video
2239 description: User can stream multiple times in a permanent live
2242 description: Live video/replay thumbnail file
2246 description: Live video/replay preview file
2250 $ref: '#/components/schemas/VideoPrivacySet'
2252 $ref: '#/components/schemas/VideoCategorySet'
2254 $ref: '#/components/schemas/VideoLicenceSet'
2256 $ref: '#/components/schemas/VideoLanguageSet'
2258 description: Live video/replay description
2261 description: A text tell the audience how to support the creator
2262 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2265 description: Whether or not this live video/replay contains sensitive content
2268 description: Live video/replay name
2273 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2282 description: Enable or disable comments for this live video/replay
2285 description: Enable or disable downloading for the replay of this live video
2292 contentType: image/jpeg
2294 contentType: image/jpeg
2298 summary: Get information about a live
2299 operationId: getLiveId
2306 - $ref: '#/components/parameters/idOrUUID'
2309 description: successful operation
2313 $ref: '#/components/schemas/LiveVideoResponse'
2315 summary: Update information about a live
2316 operationId: updateLiveId
2323 - $ref: '#/components/parameters/idOrUUID'
2328 $ref: '#/components/schemas/LiveVideoUpdate'
2331 description: successful operation
2333 description: bad parameters or trying to update a live that has already started
2335 description: trying to save replay of the live but saving replay is not enabled on the instance
2339 summary: List my abuses
2340 operationId: getMyAbuses
2349 description: only list the report with this id
2355 $ref: '#/components/schemas/AbuseStateSet'
2356 - $ref: '#/components/parameters/abusesSort'
2357 - $ref: '#/components/parameters/start'
2358 - $ref: '#/components/parameters/count'
2361 description: successful operation
2373 $ref: '#/components/schemas/Abuse'
2377 summary: List abuses
2378 operationId: getAbuses
2388 description: only list the report with this id
2391 - name: predefinedReason
2393 description: predefined reason the listed reports should contain
2395 $ref: '#/components/schemas/PredefinedAbuseReasons'
2398 description: plain search that will match with video titles, reporter names and more
2404 $ref: '#/components/schemas/AbuseStateSet'
2405 - name: searchReporter
2407 description: only list reports of a specific reporter
2410 - name: searchReportee
2411 description: only list reports of a specific reportee
2417 description: only list reports of a specific video
2420 - name: searchVideoChannel
2422 description: only list reports of a specific video channel
2427 description: only list deleted or blocklisted videos
2435 description: only list account, comment or video reports
2442 - $ref: '#/components/parameters/start'
2443 - $ref: '#/components/parameters/count'
2444 - $ref: '#/components/parameters/abusesSort'
2447 description: successful operation
2459 $ref: '#/components/schemas/Abuse'
2461 summary: Report an abuse
2474 description: Reason why the user reports this video
2479 $ref: '#/components/schemas/PredefinedAbuseReasons'
2484 description: Video id to report
2486 - $ref: '#/components/schemas/Video/properties/id'
2490 description: Timestamp in the video that marks the beginning of the report
2495 description: Timestamp in the video that marks the ending of the report
2501 description: Comment id to report
2503 - $ref: '#/components/schemas/VideoComment/properties/id'
2508 description: Account id to report
2514 description: successful operation
2524 $ref: '#/components/schemas/id'
2526 description: incorrect request parameters
2528 '/abuses/{abuseId}':
2530 summary: Update an abuse
2538 - $ref: '#/components/parameters/abuseId'
2546 $ref: '#/components/schemas/AbuseStateSet'
2549 description: Update the report comment visible only to the moderation team
2554 description: successful operation
2556 description: abuse not found
2560 summary: Delete an abuse
2566 - $ref: '#/components/parameters/abuseId'
2569 description: successful operation
2571 description: block not found
2573 '/abuses/{abuseId}/messages':
2575 summary: List messages of an abuse
2581 - $ref: '#/components/parameters/abuseId'
2584 description: successful operation
2596 $ref: '#/components/schemas/AbuseMessage'
2598 summary: Add message to an abuse
2604 - $ref: '#/components/parameters/abuseId'
2613 description: Message to send
2621 description: successful operation
2623 description: incorrect request parameters
2625 '/abuses/{abuseId}/messages/{abuseMessageId}':
2627 summary: Delete an abuse message
2633 - $ref: '#/components/parameters/abuseId'
2634 - $ref: '#/components/parameters/abuseMessageId'
2637 description: successful operation
2639 '/videos/{id}/blacklist':
2641 summary: Block a video
2642 operationId: addVideoBlock
2650 - $ref: '#/components/parameters/idOrUUID'
2653 description: successful operation
2655 summary: Unblock a video by its id
2656 operationId: delVideoBlock
2664 - $ref: '#/components/parameters/idOrUUID'
2667 description: successful operation
2669 description: block not found
2675 summary: List video blocks
2676 operationId: getVideoBlocks
2685 list only blocks that match this type:
2689 - `2`: automatic block that needs review
2697 description: plain search that will match with video titles, and more
2700 - $ref: '#/components/parameters/start'
2701 - $ref: '#/components/parameters/count'
2702 - $ref: '#/components/parameters/blacklistsSort'
2705 description: successful operation
2717 $ref: '#/components/schemas/VideoBlacklist'
2719 /videos/{id}/captions:
2721 summary: List captions of a video
2722 operationId: getVideoCaptions
2726 - $ref: '#/components/parameters/idOrUUID'
2729 description: successful operation
2741 $ref: '#/components/schemas/VideoCaption'
2743 /videos/{id}/captions/{captionLanguage}:
2745 summary: Add or replace a video caption
2746 operationId: addVideoCaption
2753 - $ref: '#/components/parameters/idOrUUID'
2754 - $ref: '#/components/parameters/captionLanguage'
2757 multipart/form-data:
2762 description: The file to upload.
2767 contentType: text/vtt, application/x-subrip, text/plain
2770 description: successful operation
2772 description: video or language not found
2774 summary: Delete a video caption
2775 operationId: delVideoCaption
2782 - $ref: '#/components/parameters/idOrUUID'
2783 - $ref: '#/components/parameters/captionLanguage'
2786 description: successful operation
2788 description: video or language or caption for that language not found
2792 summary: List video channels
2793 operationId: getVideoChannels
2797 - $ref: '#/components/parameters/start'
2798 - $ref: '#/components/parameters/count'
2799 - $ref: '#/components/parameters/sort'
2802 description: successful operation
2806 $ref: '#/components/schemas/VideoChannelList'
2808 summary: Create a video channel
2809 operationId: addVideoChannel
2816 description: successful operation
2826 $ref: '#/components/schemas/VideoChannel/properties/id'
2831 $ref: '#/components/schemas/VideoChannelCreate'
2833 '/video-channels/{channelHandle}':
2835 summary: Get a video channel
2836 operationId: getVideoChannel
2840 - $ref: '#/components/parameters/channelHandle'
2843 description: successful operation
2847 $ref: '#/components/schemas/VideoChannel'
2849 summary: Update a video channel
2850 operationId: putVideoChannel
2856 - $ref: '#/components/parameters/channelHandle'
2859 description: successful operation
2864 $ref: '#/components/schemas/VideoChannelUpdate'
2866 summary: Delete a video channel
2867 operationId: delVideoChannel
2873 - $ref: '#/components/parameters/channelHandle'
2876 description: successful operation
2878 '/video-channels/{channelHandle}/videos':
2880 summary: List videos of a video channel
2881 operationId: getVideoChannelVideos
2886 - $ref: '#/components/parameters/channelHandle'
2887 - $ref: '#/components/parameters/categoryOneOf'
2888 - $ref: '#/components/parameters/isLive'
2889 - $ref: '#/components/parameters/tagsOneOf'
2890 - $ref: '#/components/parameters/tagsAllOf'
2891 - $ref: '#/components/parameters/licenceOneOf'
2892 - $ref: '#/components/parameters/languageOneOf'
2893 - $ref: '#/components/parameters/nsfw'
2894 - $ref: '#/components/parameters/isLocal'
2895 - $ref: '#/components/parameters/include'
2896 - $ref: '#/components/parameters/privacyOneOf'
2897 - $ref: '#/components/parameters/hasHLSFiles'
2898 - $ref: '#/components/parameters/hasWebtorrentFiles'
2899 - $ref: '#/components/parameters/skipCount'
2900 - $ref: '#/components/parameters/start'
2901 - $ref: '#/components/parameters/count'
2902 - $ref: '#/components/parameters/videosSort'
2905 description: successful operation
2909 $ref: '#/components/schemas/VideoListResponse'
2911 '/video-channels/{channelHandle}/followers':
2915 summary: 'List followers of a video channel'
2918 operationId: getVideoChannelFollowers
2920 - $ref: '#/components/parameters/channelHandle'
2921 - $ref: '#/components/parameters/start'
2922 - $ref: '#/components/parameters/count'
2923 - $ref: '#/components/parameters/followersSort'
2924 - $ref: '#/components/parameters/search'
2927 description: successful operation
2939 $ref: '#/components/schemas/Follow'
2941 '/video-channels/{channelHandle}/avatar/pick':
2943 summary: Update channel avatar
2949 - $ref: '#/components/parameters/channelHandle'
2952 description: successful operation
2959 $ref: '#/components/schemas/ActorImage'
2961 description: image file too large
2963 X-File-Maximum-Size:
2967 description: Maximum file size for the avatar
2970 multipart/form-data:
2975 description: The file to upload.
2980 contentType: image/png, image/jpeg
2982 '/video-channels/{channelHandle}/avatar':
2984 summary: Delete channel avatar
2990 - $ref: '#/components/parameters/channelHandle'
2993 description: successful operation
2995 '/video-channels/{channelHandle}/banner/pick':
2997 summary: Update channel banner
3003 - $ref: '#/components/parameters/channelHandle'
3006 description: successful operation
3013 $ref: '#/components/schemas/ActorImage'
3015 description: image file too large
3017 X-File-Maximum-Size:
3021 description: Maximum file size for the banner
3024 multipart/form-data:
3029 description: The file to upload.
3034 contentType: image/png, image/jpeg
3036 '/video-channels/{channelHandle}/banner':
3038 summary: Delete channel banner
3044 - $ref: '#/components/parameters/channelHandle'
3047 description: successful operation
3049 /video-playlists/privacies:
3051 summary: List available playlist privacy policies
3052 operationId: getPlaylistPrivacyPolicies
3057 description: successful operation
3066 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3070 summary: List video playlists
3071 operationId: getPlaylists
3075 - $ref: '#/components/parameters/start'
3076 - $ref: '#/components/parameters/count'
3077 - $ref: '#/components/parameters/sort'
3080 description: successful operation
3092 $ref: '#/components/schemas/VideoPlaylist'
3094 summary: Create a video playlist
3095 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3096 operationId: addPlaylist
3103 description: successful operation
3113 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3115 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3117 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3120 multipart/form-data:
3125 description: Video playlist display name
3130 description: Video playlist thumbnail file
3134 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3136 description: Video playlist description
3142 - $ref: '#/components/schemas/id'
3143 description: Video channel in which the playlist will be published
3148 contentType: image/jpeg
3150 /video-playlists/{playlistId}:
3152 summary: Get a video playlist
3156 - $ref: '#/components/parameters/playlistId'
3159 description: successful operation
3163 $ref: '#/components/schemas/VideoPlaylist'
3165 summary: Update a video playlist
3166 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3173 description: successful operation
3175 - $ref: '#/components/parameters/playlistId'
3178 multipart/form-data:
3183 description: Video playlist display name
3188 description: Video playlist thumbnail file
3192 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3194 description: Video playlist description
3198 - $ref: '#/components/schemas/id'
3199 description: Video channel in which the playlist will be published
3202 contentType: image/jpeg
3204 summary: Delete a video playlist
3210 - $ref: '#/components/parameters/playlistId'
3213 description: successful operation
3215 /video-playlists/{playlistId}/videos:
3217 summary: 'List videos of a playlist'
3218 operationId: getVideoPlaylistVideos
3223 - $ref: '#/components/parameters/playlistId'
3224 - $ref: '#/components/parameters/start'
3225 - $ref: '#/components/parameters/count'
3228 description: successful operation
3232 $ref: '#/components/schemas/VideoListResponse'
3234 summary: Add a video in a playlist
3235 operationId: addVideoPlaylistVideo
3242 - $ref: '#/components/parameters/playlistId'
3245 description: successful operation
3251 videoPlaylistElement:
3265 - $ref: '#/components/schemas/Video/properties/uuid'
3266 - $ref: '#/components/schemas/Video/properties/id'
3267 description: Video to add in the playlist
3271 description: Start the video at this specific timestamp
3275 description: Stop the video at this specific timestamp
3279 /video-playlists/{playlistId}/videos/reorder:
3281 summary: 'Reorder a playlist'
3282 operationId: reorderVideoPlaylist
3288 - $ref: '#/components/parameters/playlistId'
3291 description: successful operation
3300 description: 'Start position of the element to reorder'
3302 insertAfterPosition:
3304 description: 'New position for the block to reorder, to add the block before the first element'
3308 description: 'How many element from `startPosition` to reorder'
3312 - insertAfterPosition
3314 /video-playlists/{playlistId}/videos/{playlistElementId}:
3316 summary: Update a playlist element
3317 operationId: putVideoPlaylistVideo
3323 - $ref: '#/components/parameters/playlistId'
3324 - $ref: '#/components/parameters/playlistElementId'
3327 description: successful operation
3337 description: Start the video at this specific timestamp
3341 description: Stop the video at this specific timestamp
3343 summary: Delete an element from a playlist
3344 operationId: delVideoPlaylistVideo
3350 - $ref: '#/components/parameters/playlistId'
3351 - $ref: '#/components/parameters/playlistElementId'
3354 description: successful operation
3356 '/users/me/video-playlists/videos-exist':
3358 summary: Check video exists in my playlists
3367 description: The video ids to check
3371 $ref: '#/components/schemas/Video/properties/id'
3374 description: successful operation
3396 '/accounts/{name}/video-channels':
3398 summary: List video channels of an account
3403 - $ref: '#/components/parameters/name'
3406 description: include view statistics for the last 30 days (only if authentified as the account user)
3409 - $ref: '#/components/parameters/start'
3410 - $ref: '#/components/parameters/count'
3411 - $ref: '#/components/parameters/sort'
3414 description: successful operation
3418 $ref: '#/components/schemas/VideoChannelList'
3420 '/accounts/{name}/ratings':
3422 summary: List ratings of an account
3428 - $ref: '#/components/parameters/name'
3429 - $ref: '#/components/parameters/start'
3430 - $ref: '#/components/parameters/count'
3431 - $ref: '#/components/parameters/sort'
3435 description: Optionally filter which ratings to retrieve
3443 description: successful operation
3449 $ref: '#/components/schemas/VideoRating'
3451 '/videos/{id}/comment-threads':
3453 summary: List threads of a video
3457 - $ref: '#/components/parameters/idOrUUID'
3458 - $ref: '#/components/parameters/start'
3459 - $ref: '#/components/parameters/count'
3460 - $ref: '#/components/parameters/commentsSort'
3463 description: successful operation
3467 $ref: '#/components/schemas/CommentThreadResponse'
3469 summary: Create a thread
3475 - $ref: '#/components/parameters/idOrUUID'
3478 description: successful operation
3482 $ref: '#/components/schemas/CommentThreadPostResponse'
3484 description: video does not exist
3493 - $ref: '#/components/schemas/VideoComment/properties/text'
3499 '/videos/{id}/comment-threads/{threadId}':
3501 summary: Get a thread
3505 - $ref: '#/components/parameters/idOrUUID'
3506 - $ref: '#/components/parameters/threadId'
3509 description: successful operation
3513 $ref: '#/components/schemas/VideoCommentThreadTree'
3515 '/videos/{id}/comments/{commentId}':
3517 summary: Reply to a thread of a video
3523 - $ref: '#/components/parameters/idOrUUID'
3524 - $ref: '#/components/parameters/commentId'
3527 description: successful operation
3531 $ref: '#/components/schemas/CommentThreadPostResponse'
3533 description: thread or video does not exist
3542 - $ref: '#/components/schemas/VideoComment/properties/text'
3548 summary: Delete a comment or a reply
3554 - $ref: '#/components/parameters/idOrUUID'
3555 - $ref: '#/components/parameters/commentId'
3558 description: successful operation
3560 description: cannot remove comment of another user
3562 description: comment or video does not exist
3564 description: comment is already deleted
3566 '/videos/{id}/rate':
3568 summary: Like/dislike a video
3574 - $ref: '#/components/parameters/idOrUUID'
3590 description: successful operation
3592 description: video does not exist
3596 summary: Delete video HLS files
3602 operationId: delVideoHLS
3604 - $ref: '#/components/parameters/idOrUUID'
3607 description: successful operation
3609 description: video does not exist
3610 '/videos/{id}/webtorrent':
3612 summary: Delete video WebTorrent files
3618 operationId: delVideoWebTorrent
3620 - $ref: '#/components/parameters/idOrUUID'
3623 description: successful operation
3625 description: video does not exist
3627 '/videos/{id}/transcoding':
3629 summary: Create a transcoding job
3635 operationId: createVideoTranscoding
3637 - $ref: '#/components/parameters/idOrUUID'
3653 description: successful operation
3655 description: video does not exist
3661 summary: Search videos
3662 operationId: searchVideos
3667 allowEmptyValue: false
3669 String to search. If the user can make a remote URI search, and the string is an URI then the
3670 PeerTube instance will fetch the remote object and add it to its database. Then,
3671 you can use the REST API to fetch the complete video information and interact with it.
3674 - $ref: '#/components/parameters/categoryOneOf'
3675 - $ref: '#/components/parameters/isLive'
3676 - $ref: '#/components/parameters/tagsOneOf'
3677 - $ref: '#/components/parameters/tagsAllOf'
3678 - $ref: '#/components/parameters/licenceOneOf'
3679 - $ref: '#/components/parameters/languageOneOf'
3680 - $ref: '#/components/parameters/nsfw'
3681 - $ref: '#/components/parameters/isLocal'
3682 - $ref: '#/components/parameters/include'
3683 - $ref: '#/components/parameters/privacyOneOf'
3684 - $ref: '#/components/parameters/hasHLSFiles'
3685 - $ref: '#/components/parameters/hasWebtorrentFiles'
3686 - $ref: '#/components/parameters/skipCount'
3687 - $ref: '#/components/parameters/start'
3688 - $ref: '#/components/parameters/count'
3689 - $ref: '#/components/parameters/searchTarget'
3690 - $ref: '#/components/parameters/videosSearchSort'
3693 description: Get videos that are published after this date
3699 description: Get videos that are published before this date
3703 - name: originallyPublishedStartDate
3705 description: Get videos that are originally published after this date
3709 - name: originallyPublishedEndDate
3711 description: Get videos that are originally published before this date
3717 description: Get videos that have this minimum duration
3722 description: Get videos that have this maximum duration
3726 'searchTarget === search-index':
3727 $ref: '#/components/callbacks/searchIndex'
3730 description: successful operation
3734 $ref: '#/components/schemas/VideoListResponse'
3736 description: search index unavailable
3738 /search/video-channels:
3742 summary: Search channels
3743 operationId: searchChannels
3749 String to search. If the user can make a remote URI search, and the string is an URI then the
3750 PeerTube instance will fetch the remote object and add it to its database. Then,
3751 you can use the REST API to fetch the complete channel information and interact with it.
3754 - $ref: '#/components/parameters/start'
3755 - $ref: '#/components/parameters/count'
3756 - $ref: '#/components/parameters/searchTarget'
3757 - $ref: '#/components/parameters/sort'
3759 'searchTarget === search-index':
3760 $ref: '#/components/callbacks/searchIndex'
3763 description: successful operation
3767 $ref: '#/components/schemas/VideoChannelList'
3769 description: search index unavailable
3771 /search/video-playlists:
3775 summary: Search playlists
3776 operationId: searchPlaylists
3782 String to search. If the user can make a remote URI search, and the string is an URI then the
3783 PeerTube instance will fetch the remote object and add it to its database. Then,
3784 you can use the REST API to fetch the complete playlist information and interact with it.
3787 - $ref: '#/components/parameters/start'
3788 - $ref: '#/components/parameters/count'
3789 - $ref: '#/components/parameters/searchTarget'
3790 - $ref: '#/components/parameters/sort'
3792 'searchTarget === search-index':
3793 $ref: '#/components/callbacks/searchIndex'
3796 description: successful operation
3808 $ref: '#/components/schemas/VideoPlaylist'
3810 description: search index unavailable
3817 summary: Get block status of accounts/hosts
3822 description: 'Check if these accounts are blocked'
3823 example: [ 'goofy@example.com', 'donald@example.com' ]
3831 description: 'Check if these hosts are blocked'
3832 example: [ 'example.com' ]
3839 description: successful operation
3843 $ref: '#/components/schemas/BlockStatus'
3845 /server/blocklist/accounts:
3849 summary: List account blocks
3854 - $ref: '#/components/parameters/start'
3855 - $ref: '#/components/parameters/count'
3856 - $ref: '#/components/parameters/sort'
3859 description: successful operation
3863 summary: Block an account
3875 example: chocobozzz@example.org
3876 description: account to block, in the form `username@domain`
3881 description: successful operation
3883 description: self-blocking forbidden
3885 '/server/blocklist/accounts/{accountName}':
3889 summary: Unblock an account by its handle
3897 description: account to unblock, in the form `username@domain`
3902 description: successful operation
3904 description: account or account block does not exist
3906 /server/blocklist/servers:
3910 summary: List server blocks
3915 - $ref: '#/components/parameters/start'
3916 - $ref: '#/components/parameters/count'
3917 - $ref: '#/components/parameters/sort'
3920 description: successful operation
3924 summary: Block a server
3937 description: server domain to block
3942 description: successful operation
3944 description: self-blocking forbidden
3946 '/server/blocklist/servers/{host}':
3950 summary: Unblock a server by its domain
3958 description: server domain to unblock
3964 description: successful operation
3966 description: account block does not exist
3968 /server/redundancy/{host}:
3971 - Instance Redundancy
3972 summary: Update a server redundancy policy
3980 description: server domain to mirror
3992 description: allow mirroring of the host's local videos
3997 description: successful operation
3999 description: server is not already known
4001 /server/redundancy/videos:
4005 summary: List videos being mirrored
4006 operationId: getMirroredVideos
4014 description: direction of the mirror
4020 - $ref: '#/components/parameters/start'
4021 - $ref: '#/components/parameters/count'
4022 - $ref: '#/components/parameters/videoRedundanciesSort'
4025 description: successful operation
4031 $ref: '#/components/schemas/VideoRedundancy'
4035 summary: Mirror a video
4036 operationId: putMirroredVideo
4047 $ref: '#/components/schemas/Video/properties/id'
4052 description: successful operation
4054 description: cannot mirror a local video
4056 description: video does not exist
4058 description: video is already mirrored
4060 /server/redundancy/videos/{redundancyId}:
4064 summary: Delete a mirror done on a video
4065 operationId: delMirroredVideo
4070 - name: redundancyId
4073 description: id of an existing redundancy on a video
4078 description: successful operation
4080 description: video redundancy not found
4082 '/feeds/video-comments.{format}':
4086 summary: List comments on videos
4087 operationId: getSyndicatedComments
4092 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4105 description: 'limit listing to a specific video'
4110 description: 'limit listing to a specific account'
4115 description: 'limit listing to a specific account'
4118 - name: videoChannelId
4120 description: 'limit listing to a specific video channel'
4123 - name: videoChannelName
4125 description: 'limit listing to a specific video channel'
4130 description: successful operation
4135 default: 'max-age=900' # 15 min cache
4139 $ref: '#/components/schemas/VideoCommentsForXML'
4142 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4143 application/rss+xml:
4145 $ref: '#/components/schemas/VideoCommentsForXML'
4148 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4151 $ref: '#/components/schemas/VideoCommentsForXML'
4154 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4155 application/atom+xml:
4157 $ref: '#/components/schemas/VideoCommentsForXML'
4160 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4166 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4168 x-summary: field inconsistencies
4171 - videoId filter is mixed with a channel filter
4173 description: video, video channel or account not found
4175 description: accept header unsupported
4177 '/feeds/videos.{format}':
4181 summary: List videos
4182 operationId: getSyndicatedVideos
4187 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4200 description: 'limit listing to a specific account'
4205 description: 'limit listing to a specific account'
4208 - name: videoChannelId
4210 description: 'limit listing to a specific video channel'
4213 - name: videoChannelName
4215 description: 'limit listing to a specific video channel'
4218 - $ref: '#/components/parameters/sort'
4219 - $ref: '#/components/parameters/nsfw'
4220 - $ref: '#/components/parameters/isLocal'
4221 - $ref: '#/components/parameters/include'
4222 - $ref: '#/components/parameters/privacyOneOf'
4223 - $ref: '#/components/parameters/hasHLSFiles'
4224 - $ref: '#/components/parameters/hasWebtorrentFiles'
4227 description: successful operation
4232 default: 'max-age=900' # 15 min cache
4236 $ref: '#/components/schemas/VideosForXML'
4239 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4240 application/rss+xml:
4242 $ref: '#/components/schemas/VideosForXML'
4245 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4248 $ref: '#/components/schemas/VideosForXML'
4251 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4252 application/atom+xml:
4254 $ref: '#/components/schemas/VideosForXML'
4257 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4263 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4265 description: video channel or account not found
4267 description: accept header unsupported
4269 '/feeds/subscriptions.{format}':
4274 summary: List videos of subscriptions tied to a token
4275 operationId: getSyndicatedSubscriptionVideos
4280 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4293 description: limit listing to a specific account
4299 description: private token allowing access
4303 - $ref: '#/components/parameters/sort'
4304 - $ref: '#/components/parameters/nsfw'
4305 - $ref: '#/components/parameters/isLocal'
4306 - $ref: '#/components/parameters/include'
4307 - $ref: '#/components/parameters/privacyOneOf'
4308 - $ref: '#/components/parameters/hasHLSFiles'
4309 - $ref: '#/components/parameters/hasWebtorrentFiles'
4312 description: successful operation
4317 default: 'max-age=900' # 15 min cache
4321 $ref: '#/components/schemas/VideosForXML'
4322 application/rss+xml:
4324 $ref: '#/components/schemas/VideosForXML'
4327 $ref: '#/components/schemas/VideosForXML'
4328 application/atom+xml:
4330 $ref: '#/components/schemas/VideosForXML'
4335 description: accept header unsupported
4341 summary: List plugins
4342 operationId: getPlugins
4355 - $ref: '#/components/parameters/start'
4356 - $ref: '#/components/parameters/count'
4357 - $ref: '#/components/parameters/sort'
4360 description: successful operation
4364 $ref: '#/components/schemas/PluginResponse'
4370 summary: List available plugins
4371 operationId: getAvailablePlugins
4384 - name: currentPeerTubeEngine
4388 - $ref: '#/components/parameters/start'
4389 - $ref: '#/components/parameters/count'
4390 - $ref: '#/components/parameters/sort'
4393 description: successful operation
4397 $ref: '#/components/schemas/PluginResponse'
4399 description: plugin index unavailable
4405 summary: Install a plugin
4406 operationId: addPlugin
4419 example: peertube-plugin-auth-ldap
4422 additionalProperties: false
4429 additionalProperties: false
4432 description: successful operation
4434 description: should have either `npmName` or `path` set
4440 summary: Update a plugin
4441 operationId: updatePlugin
4454 example: peertube-plugin-auth-ldap
4457 additionalProperties: false
4464 additionalProperties: false
4467 description: successful operation
4469 description: should have either `npmName` or `path` set
4471 description: existing plugin not found
4477 summary: Uninstall a plugin
4478 operationId: uninstallPlugin
4490 description: name of the plugin/theme in its package.json
4491 example: peertube-plugin-auth-ldap
4496 description: successful operation
4498 description: existing plugin not found
4504 summary: Get a plugin
4505 operationId: getPlugin
4510 - $ref: '#/components/parameters/npmName'
4513 description: successful operation
4517 $ref: '#/components/schemas/Plugin'
4519 description: plugin not found
4521 /plugins/{npmName}/settings:
4525 summary: Set a plugin's settings
4530 - $ref: '#/components/parameters/npmName'
4539 additionalProperties: true
4542 description: successful operation
4544 description: plugin not found
4546 /plugins/{npmName}/public-settings:
4550 summary: Get a plugin's public settings
4552 - $ref: '#/components/parameters/npmName'
4555 description: successful operation
4560 additionalProperties: true
4562 description: plugin not found
4564 /plugins/{npmName}/registered-settings:
4568 summary: Get a plugin's registered settings
4573 - $ref: '#/components/parameters/npmName'
4576 description: successful operation
4581 additionalProperties: true
4583 description: plugin not found
4586 - url: 'https://peertube2.cpy.re/api/v1'
4587 description: Live Test Server (live data - latest nightly version)
4588 - url: 'https://peertube3.cpy.re/api/v1'
4589 description: Live Test Server (live data - latest RC version)
4590 - url: 'https://peertube.cpy.re/api/v1'
4591 description: Live Test Server (live data - stable version)
4598 description: Offset used to paginate results
4606 description: "Number of items to return"
4616 description: Sort column
4624 description: Plain text search, applied to various parts of the model depending on endpoint
4632 If the administrator enabled search index support, you can override the default search target.
4635 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4636 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4637 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4638 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4639 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4640 * 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
4641 the data from the origin instance API
4651 description: Sort videos by criteria
4667 description: Sort videos by criteria
4682 description: Sort comments by criteria
4692 description: Sort blocklists by criteria
4708 description: Plain text search that will match with user usernames or emails
4715 description: Filter results down to (un)banned users
4722 description: Sort users by criteria
4733 description: Sort abuses by criteria
4740 videoRedundanciesSort:
4744 description: Sort abuses by criteria
4753 description: Sort followers by criteria
4762 description: The username or handle of the account
4765 example: chocobozzz | chocobozzz@example.org
4770 description: The user id
4772 $ref: '#/components/schemas/id'
4777 description: The object id, uuid or short uuid
4780 - $ref: '#/components/schemas/id'
4781 - $ref: '#/components/schemas/UUIDv4'
4782 - $ref: '#/components/schemas/shortUUID'
4787 description: Playlist id
4789 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4791 name: playlistElementId
4794 description: Playlist element id
4796 $ref: '#/components/schemas/id'
4801 description: Abuse id
4803 $ref: '#/components/schemas/Abuse/properties/id'
4805 name: abuseMessageId
4808 description: Abuse message id
4810 $ref: '#/components/schemas/AbuseMessage/properties/id'
4812 name: captionLanguage
4815 description: The caption language
4817 $ref: '#/components/schemas/VideoLanguageSet'
4822 description: The video channel handle
4825 example: my_username | my_username@example.com
4827 name: subscriptionHandle
4830 description: The subscription handle
4833 example: my_username | my_username@example.com
4838 description: The thread id (root comment id)
4845 description: The comment id
4847 $ref: '#/components/schemas/VideoComment/properties/id'
4852 description: whether or not the video is a live
4859 description: category id of the video (see [/videos/categories](#operation/getCategories))
4862 - $ref: '#/components/schemas/VideoCategorySet'
4865 $ref: '#/components/schemas/VideoCategorySet'
4872 description: tag(s) of the video
4886 description: tag(s) of the video, where all should be present in the video
4899 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4902 - $ref: '#/components/schemas/VideoLanguageSet'
4905 $ref: '#/components/schemas/VideoLanguageSet'
4912 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4915 - $ref: '#/components/schemas/VideoLicenceSet'
4918 $ref: '#/components/schemas/VideoLicenceSet'
4925 description: if you don't need the `total` in the response
4936 description: whether to include nsfw videos, if any
4948 description: '**PeerTube >= 4.0** Display only local or remote videos'
4955 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
4957 name: hasWebtorrentFiles
4962 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
4968 $ref: '#/components/schemas/VideoPrivacySet'
4969 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
4983 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
4987 - `1` NOT_PUBLISHED_STATE
4998 description: list of uris to check if each is part of the user subscriptions
5008 description: name of the plugin/theme on npmjs.com or in its package.json
5011 example: peertube-plugin-auth-ldap
5016 description: job type
5020 - activitypub-follow
5021 - activitypub-http-broadcast
5022 - activitypub-http-fetcher
5023 - activitypub-http-unicast
5028 - videos-views-stats
5029 - activitypub-refresher
5054 Authenticating via OAuth requires the following steps:
5055 - Have an activated account
5056 - [Generate] an access token for that account at `/api/v1/users/token`.
5057 - Make requests with the *Authorization: Bearer <token\>* header
5058 - Profit, depending on the role assigned to the account
5060 Note that the __access token is valid for 1 day__ and is given
5061 along with a __refresh token valid for 2 weeks__.
5063 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5067 tokenUrl: /api/v1/users/token
5070 moderator: Moderator scope
5073 # Resuable core properties
5081 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5082 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5087 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5088 example: 2y84q2MQUMWPbiEcxNXMgC
5091 description: immutable name of the user, used to find or mention its actor
5093 pattern: '/^[a-z0-9._]+$/'
5098 description: immutable name of the channel, used to interact with its actor
5099 example: framasoft_videos
5100 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5111 description: category id of the video (see [/videos/categories](#operation/getCategories))
5113 VideoConstantNumber-Category:
5116 $ref: '#/components/schemas/VideoCategorySet'
5119 example: Science & Technology
5123 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5125 VideoConstantNumber-Licence:
5128 $ref: '#/components/schemas/VideoLicenceSet'
5131 example: Attribution - Share Alike
5135 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5137 VideoConstantString-Language:
5140 $ref: '#/components/schemas/VideoLanguageSet'
5145 VideoPlaylistPrivacySet:
5151 description: Video playlist privacy policy (see [/video-playlists/privacies])
5152 VideoPlaylistPrivacyConstant:
5155 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5159 VideoPlaylistTypeSet:
5164 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5165 VideoPlaylistTypeConstant:
5168 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5179 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5180 VideoPrivacyConstant:
5183 $ref: '#/components/schemas/VideoPrivacySet'
5191 additionalProperties:
5192 x-additionalPropertiesName: account
5201 additionalProperties:
5202 x-additionalPropertiesName: host
5223 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5230 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5241 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5251 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5255 $ref: '#/components/schemas/AbuseStateSet'
5258 AbusePredefinedReasons:
5271 example: [spamOrMisleading]
5276 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5278 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5280 VideoResolutionConstant:
5281 description: resolutions and their labels for the video
5284 $ref: '#/components/schemas/VideoResolutionSet'
5288 VideoScheduledUpdate:
5291 $ref: '#/components/schemas/VideoPrivacySet'
5295 description: When to update the video
5315 - $ref: '#/components/schemas/ActorImage'
5316 VideoChannelSummary:
5319 $ref: '#/components/schemas/id'
5333 - $ref: '#/components/schemas/ActorImage'
5347 - $ref: '#/components/schemas/Video'
5354 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5355 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5357 $ref: '#/components/schemas/VideoResolutionConstant'
5360 description: Video file size in bytes
5363 description: Direct URL of the torrent file
5367 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5371 description: Direct URL of the video
5375 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5379 description: Frames per second of the video file
5383 description: URL dereferencing the output of ffprobe on the file
5384 VideoStreamingPlaylists:
5389 $ref: '#/components/schemas/id'
5397 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5398 VideoStreamingPlaylists-HLS:
5409 Video files associated to this playlist.
5411 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5413 $ref: '#/components/schemas/VideoFile'
5425 $ref: '#/components/schemas/Video/properties/id'
5427 $ref: '#/components/schemas/Video/properties/uuid'
5429 $ref: '#/components/schemas/Video/properties/name'
5433 description: object id for the video
5435 - $ref: '#/components/schemas/id'
5437 description: universal identifier for the video, that can be used across instances
5439 - $ref: '#/components/schemas/UUIDv4'
5442 - $ref: '#/components/schemas/shortUUID'
5448 example: 2017-10-01T10:52:46.396Z
5449 description: time at which the video object was first drafted
5453 example: 2018-10-01T10:52:46.396Z
5454 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5458 example: 2021-05-04T08:01:01.502Z
5459 description: last time the video's metadata was modified
5460 originallyPublishedAt:
5463 example: 2010-10-01T10:52:46.396Z
5464 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5467 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5468 description: category in which the video is classified
5471 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5472 description: licence under which the video is distributed
5475 - $ref: '#/components/schemas/VideoConstantString-Language'
5476 description: main language used in the video
5479 - $ref: '#/components/schemas/VideoPrivacyConstant'
5480 description: privacy policy used to distribute the video
5484 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5485 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5489 truncated description of the video, written in Markdown.
5490 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5495 description: duration of the video in seconds
5500 description: title of the video
5501 example: What is PeerTube?
5506 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5509 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5512 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5529 - $ref: '#/components/schemas/VideoStateConstant'
5530 description: represents the internal state of the video processing within the PeerTube instance
5534 - $ref: '#/components/schemas/VideoScheduledUpdate'
5542 $ref: '#/components/schemas/AccountSummary'
5544 $ref: '#/components/schemas/VideoChannelSummary'
5553 - $ref: '#/components/schemas/Video'
5558 description: If the video is a live, you have the amount of current viewers
5561 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5562 description: path at which to get the full description of maximum `10000` characters
5565 description: A text tell the audience how to support the video creator
5566 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5570 $ref: '#/components/schemas/VideoChannel'
5572 $ref: '#/components/schemas/Account'
5574 example: [flowers, gardening]
5592 - https://peertube2.cpy.re/tracker/announce
5593 - wss://peertube2.cpy.re/tracker/socket
5597 $ref: '#/components/schemas/VideoFile'
5599 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5601 - field will be empty
5602 - video files will be found in `streamingPlaylists[].files` field
5606 $ref: '#/components/schemas/VideoStreamingPlaylists'
5608 HLS playlists/manifest files. If HLS is disabled on the server:
5610 - field will be empty
5611 - video files will be found in `files` field
5612 FileRedundancyInformation:
5615 $ref: '#/components/schemas/id'
5640 $ref: '#/components/schemas/id'
5647 $ref: '#/components/schemas/UUIDv4'
5654 $ref: '#/components/schemas/FileRedundancyInformation'
5658 $ref: '#/components/schemas/FileRedundancyInformation'
5659 VideoImportStateConstant:
5667 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5674 additionalProperties: false
5678 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5679 required: [targetUrl]
5682 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5683 required: [magnetUri]
5686 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5687 required: [torrentfile]
5688 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5697 - $ref: '#/components/schemas/id'
5701 description: remote URL where to find the import's source video
5702 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5706 description: magnet URI allowing to resolve the import's source video
5707 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5712 description: Torrent file containing only the video file
5719 - $ref: '#/components/schemas/VideoImportStateConstant'
5735 - $ref: '#/components/schemas/Video'
5745 $ref: '#/components/schemas/VideoImport'
5749 $ref: '#/components/schemas/id'
5752 example: The video is a spam
5756 $ref: '#/components/schemas/AbusePredefinedReasons'
5758 $ref: '#/components/schemas/Account'
5760 $ref: '#/components/schemas/AbuseStateConstant'
5763 example: Decided to ban the server since it spams us regularly
5767 $ref: '#/components/schemas/VideoInfo'
5774 $ref: '#/components/schemas/id'
5785 $ref: '#/components/schemas/AccountSummary'
5789 $ref: '#/components/schemas/id'
5791 $ref: '#/components/schemas/Video/properties/id'
5803 $ref: '#/components/schemas/UUIDv4'
5821 $ref: '#/components/schemas/id'
5823 $ref: '#/components/schemas/UUIDv4'
5826 - $ref: '#/components/schemas/shortUUID'
5849 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5851 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5853 $ref: '#/components/schemas/AccountSummary'
5855 $ref: '#/components/schemas/VideoChannelSummary'
5859 $ref: '#/components/schemas/id'
5866 description: Text of the comment
5868 example: This video is wonderful!
5870 $ref: '#/components/schemas/id'
5874 - $ref: '#/components/schemas/id'
5876 $ref: '#/components/schemas/Video/properties/id'
5891 totalRepliesFromVideoAuthor:
5898 $ref: '#/components/schemas/Account'
5899 VideoCommentThreadTree:
5902 $ref: '#/components/schemas/VideoComment'
5906 $ref: '#/components/schemas/VideoCommentThreadTree'
5910 $ref: '#/components/schemas/VideoConstantString-Language'
5926 $ref: '#/components/schemas/id'
5943 $ref: '#/components/schemas/id'
5948 description: immutable name of the actor, used to find or mention it
5950 - $ref: '#/components/schemas/username'
5954 description: server on which the actor is resident
5955 hostRedundancyAllowed:
5957 description: whether this actor's host allows redundancy of its videos
5961 description: number of actors subscribed to by this actor, as seen by this instance
5965 description: number of followers of this actor, as seen by this instance
5973 $ref: '#/components/schemas/ActorImage'
5976 - $ref: '#/components/schemas/Actor'
5979 description: object id for the user tied to this account
5981 - $ref: '#/components/schemas/User/properties/id'
5984 description: editable name of the account, displayed in its representations
5989 description: text or bio displayed on the account's profile
5995 description: timestamp within the video, in seconds
6062 allowedForCurrentIP:
6064 requiresEmailVerification:
6082 $ref: '#/components/schemas/VideoResolutionSet'
6167 example: 16810141515
6276 requiresEmailVerification:
6291 description: Settings that apply to new users, if registration is enabled
6295 example: 16810141515
6301 description: Settings pertaining to transcoding jobs
6305 allowAdditionalExtensions:
6307 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6310 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6313 description: Amount of threads used by ffmpeg for 1 transcoding job
6316 description: Amount of transcoding jobs to execute in parallel
6322 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6325 description: Resolutions to transcode _new videos_ to
6347 description: WebTorrent-specific settings
6353 description: HLS-specific settings
6403 $ref: '#/components/schemas/id'
6405 $ref: '#/components/schemas/Actor'
6407 $ref: '#/components/schemas/Actor'
6410 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6423 PredefinedAbuseReasons:
6424 description: Reason categories that help triage reports
6442 $ref: '#/components/schemas/id'
6454 - activitypub-http-unicast
6455 - activitypub-http-broadcast
6456 - activitypub-http-fetcher
6457 - activitypub-follow
6462 - videos-views-stats
6463 - activitypub-refresher
6467 additionalProperties: true
6470 additionalProperties: true
6486 $ref: '#/components/schemas/id'
6491 $ref: '#/components/schemas/id'
6492 VideoUploadRequestCommon:
6495 description: Video name
6497 example: What is PeerTube?
6501 description: Channel id that will contain this video
6506 $ref: '#/components/schemas/VideoPrivacySet'
6508 $ref: '#/components/schemas/VideoCategorySet'
6510 $ref: '#/components/schemas/VideoLicenceSet'
6512 $ref: '#/components/schemas/VideoLanguageSet'
6514 description: Video description
6517 **[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)**
6519 description: Whether or not we wait transcoding before publish the video
6522 description: A text tell the audience how to support the video creator
6523 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6526 description: Whether or not this video contains sensitive content
6529 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6542 description: Enable or disable comments for this video
6545 description: Enable or disable downloading for this video
6547 originallyPublishedAt:
6548 description: Date when the content was originally published
6552 $ref: '#/components/schemas/VideoScheduledUpdate'
6554 description: Video thumbnail file
6558 description: Video preview file
6564 VideoUploadRequestLegacy:
6566 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6572 description: Video file
6575 VideoUploadRequestResumable:
6577 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6583 description: Video filename including extension
6586 example: what_is_peertube.mp4
6588 description: Video thumbnail file
6592 description: Video preview file
6595 VideoUploadResponse:
6601 $ref: '#/components/schemas/Video/properties/id'
6603 $ref: '#/components/schemas/Video/properties/uuid'
6605 $ref: '#/components/schemas/Video/properties/shortUUID'
6606 CommentThreadResponse:
6615 $ref: '#/components/schemas/VideoComment'
6616 CommentThreadPostResponse:
6619 $ref: '#/components/schemas/VideoComment'
6629 $ref: '#/components/schemas/Video'
6633 $ref: '#/components/schemas/Account'
6636 description: Automatically start playing the upcoming video after the currently playing video
6637 autoPlayNextVideoPlaylist:
6639 description: Automatically start playing the video on the playlist after the currently playing video
6642 description: Automatically start playing the video on the watch page
6652 description: The user email
6655 description: Has the user confirmed their email address?
6658 - $ref: '#/components/schemas/id'
6662 description: Auth plugin to use to authenticate the user
6666 noInstanceConfigWarningModal:
6668 noAccountSetupWarningModal:
6673 $ref: '#/components/schemas/NSFWPolicy'
6675 $ref: '#/components/schemas/UserRole'
6684 description: Theme enabled by this user
6686 $ref: '#/components/schemas/username'
6690 $ref: '#/components/schemas/VideoChannel'
6693 description: The user video quota in bytes
6697 description: The user daily video quota in bytes
6701 description: Enable P2P in the player
6704 - $ref: '#/components/schemas/User'
6706 # optionally present fields: they require WITH_STATS scope
6709 description: Count of videos published
6712 description: Count of reports/abuses of which the user is a target
6713 abusesAcceptedCount:
6715 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6718 description: Count of reports/abuses created by the user
6721 description: Count of comments published
6725 $ref: '#/components/schemas/username'
6727 $ref: '#/components/schemas/password'
6731 description: The user email
6734 description: The user video quota in bytes
6738 description: The user daily video quota in bytes
6741 $ref: '#/components/schemas/usernameChannel'
6743 $ref: '#/components/schemas/UserRole'
6745 $ref: '#/components/schemas/UserAdminFlags'
6756 description: The updated email of the user
6758 - $ref: '#/components/schemas/User/properties/email'
6761 description: Set the email as verified
6764 description: The updated video quota of the user in bytes
6767 description: The updated daily video quota of the user in bytes
6771 description: The auth plugin to use to authenticate the user
6772 example: 'peertube-plugin-auth-saml2'
6774 $ref: '#/components/schemas/UserRole'
6776 $ref: '#/components/schemas/UserAdminFlags'
6778 $ref: '#/components/schemas/password'
6780 # see shared/models/users/user-update-me.model.ts:
6783 $ref: '#/components/schemas/password'
6785 $ref: '#/components/schemas/password'
6787 description: new email used for login and service communications
6789 - $ref: '#/components/schemas/User/properties/email'
6792 description: new name of the user in its representations
6797 description: new NSFW display policy
6804 description: whether to enable P2P in the player or not
6807 description: new preference regarding playing videos automatically
6810 description: new preference regarding playing following videos automatically
6811 autoPlayNextVideoPlaylist:
6813 description: new preference regarding playing following playlist videos automatically
6814 videosHistoryEnabled:
6816 description: whether to keep track of watched history or not
6821 description: list of languages to filter videos down to
6824 noInstanceConfigWarningModal:
6826 noAccountSetupWarningModal:
6833 $ref: '#/components/schemas/id'
6840 description: Rating of the video
6847 $ref: '#/components/schemas/Video'
6854 description: Rating of the video
6861 description: immutable name of the user, used to find or mention its actor
6863 - $ref: '#/components/schemas/username'
6865 $ref: '#/components/schemas/password'
6869 description: email of the user, used for login or service communications
6872 description: editable name of the user, displayed in its representations
6877 description: channel base information used to create the first channel of the user
6880 $ref: '#/components/schemas/usernameChannel'
6882 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6892 pattern: /^[a-z0-9]$/
6895 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6898 pattern: /^[a-zA-Z0-9]$/
6901 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6902 OAuthToken-password:
6904 - $ref: '#/components/schemas/OAuthClient'
6914 $ref: '#/components/schemas/User/properties/username'
6916 $ref: '#/components/schemas/password'
6923 OAuthToken-refresh_token:
6925 - $ref: '#/components/schemas/OAuthClient'
6936 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6945 # GET/POST/PUT properties
6948 description: editable name of the channel, displayed in its representations
6949 example: Videos of Framasoft
6954 example: Videos made with <3 by Framasoft
6959 description: text shown by default on all videos of this channel, to tell the audience how to support it
6960 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6963 # GET-only properties
6967 - $ref: '#/components/schemas/id'
6983 $ref: '#/components/schemas/UUIDv4'
6986 - $ref: '#/components/schemas/VideoChannel'
6989 description: username of the channel to create
6991 - $ref: '#/components/schemas/usernameChannel'
6997 - $ref: '#/components/schemas/VideoChannel'
6999 bulkVideosSupportUpdate:
7001 description: Update the support field for all videos of this channel
7011 - $ref: '#/components/schemas/VideoChannel'
7012 - $ref: '#/components/schemas/Actor'
7017 name: 'media:peerLink'
7026 - application/x-bittorrent
7032 name: 'media:content'
7063 VideoCommentsForXML:
7098 description: video watch page URL
7101 description: video canonical URL
7105 description: video publication date
7108 description: video description
7111 description: video description
7114 description: publisher user name
7117 description: video category (MRSS)
7120 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7135 description: video embed path, relative to the canonical URL domain (MRSS)
7144 description: video watch path, relative to the canonical URL domain (MRSS)
7165 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7166 'media:description':
7173 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7176 description: main streamable file for the video
7186 - application/x-bittorrent
7195 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)
7198 - $ref: '#/components/schemas/MRSSPeerLink'
7199 - $ref: '#/components/schemas/MRSSGroupContent'
7200 NotificationSettingValue:
7217 $ref: '#/components/schemas/id'
7221 Notification type, following the `UserNotificationType` enum:
7223 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7225 - `2` NEW_COMMENT_ON_MY_VIDEO
7227 - `3` NEW_ABUSE_FOR_MODERATORS
7229 - `4` BLACKLIST_ON_MY_VIDEO
7231 - `5` UNBLACKLIST_ON_MY_VIDEO
7233 - `6` MY_VIDEO_PUBLISHED
7235 - `7` MY_VIDEO_IMPORT_SUCCESS
7237 - `8` MY_VIDEO_IMPORT_ERROR
7239 - `9` NEW_USER_REGISTRATION
7243 - `11` COMMENT_MENTION
7245 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7247 - `13` NEW_INSTANCE_FOLLOWER
7249 - `14` AUTO_INSTANCE_FOLLOWING
7251 - `15` ABUSE_STATE_CHANGE
7253 - `16` ABUSE_NEW_MESSAGE
7255 - `17` NEW_PLUGIN_VERSION
7257 - `18` NEW_PEERTUBE_VERSION
7263 - $ref: '#/components/schemas/VideoInfo'
7267 $ref: '#/components/schemas/ActorInfo'
7273 $ref: '#/components/schemas/id'
7276 $ref: '#/components/schemas/VideoInfo'
7281 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7291 $ref: '#/components/schemas/id'
7295 $ref: '#/components/schemas/VideoInfo'
7297 $ref: '#/components/schemas/ActorInfo'
7303 $ref: '#/components/schemas/id'
7306 - $ref: '#/components/schemas/VideoInfo'
7312 $ref: '#/components/schemas/id'
7315 - $ref: '#/components/schemas/VideoInfo'
7319 - $ref: '#/components/schemas/ActorInfo'
7325 $ref: '#/components/schemas/id'
7327 $ref: '#/components/schemas/ActorInfo'
7355 NotificationListResponse:
7364 $ref: '#/components/schemas/Notification'
7369 example: peertube-plugin-auth-ldap
7397 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7400 additionalProperties: true
7416 $ref: '#/components/schemas/Plugin'
7423 description: User can stream multiple times in a permanent live
7434 description: RTMP stream key to use to stream into this live video
7438 description: User can stream multiple times in a permanent live
7445 'https://search.example.org/api/v1/search/videos':
7447 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7450 description: successful operation
7454 $ref: '#/components/schemas/VideoListResponse'