6 name: PeerTube Community
7 url: https://joinpeertube.org
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
92 "msg": "Invalid value",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
98 "title": "Bad Request",
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
108 ### Deprecated error fields
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
128 You can get details about the current state of your rate limit by reading the
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
144 |------------------------- ---|
148 | `/live/segments-sha256/*` |
149 | `/.well-known/webfinger` |
151 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
153 url: https://docs.joinpeertube.org/api-rest-reference.html
157 As a visitor, you can use this API to open an account (if registrations are open on
158 that PeerTube instance). As an admin, you should use the dedicated [User creation
159 API](#operation/addUser) instead.
161 x-displayName: Login/Logout
163 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
166 Accounts encompass remote accounts discovered across the federation,
167 and correspond to the main Actor, along with video channels a user can create, which
170 When a comment is posted, it is done with your Account's Actor.
173 Using some features of PeerTube require authentication, for which User
174 provide different levels of permission as well as associated user
175 information. Each user has a corresponding local Account for federation.
178 Operations related to your own User, when logged-in.
179 - name: My Subscriptions
181 Operations related to your subscriptions to video channels, their
182 new videos, and how to keep up to date with their latest publications!
185 Operations related to your watch history.
186 - name: My Notifications
188 Notifications following new videos, follows or reports. They allow you
189 to keep track of the interactions and overall important information that
190 concerns you. You MAY set per-notification type delivery preference, to
191 receive the info either by mail, by in-browser notification or both.
194 Each server exposes public information regarding supported videos and
198 Jobs are long-running tasks enqueued and processed by the instance
199 itself. No additional worker registration is currently available.
200 - name: Instance Follows
202 Managing servers which the instance interacts with is crucial to the
203 concept of federation in PeerTube and external video indexation. The PeerTube
204 server then deals with inter-server ActivityPub operations and propagates
205 information across its social graph by posting activities to actors' inbox
208 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
209 - name: Instance Redundancy
211 Redundancy is part of the inter-server solidarity that PeerTube fosters.
212 Manage the list of instances you wish to help by seeding their videos according
213 to the policy of video selection of your choice. Note that you have a similar functionality
214 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
216 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
219 Managing plugins installed from a local path or from NPM, or search for new ones.
221 url: https://docs.joinpeertube.org/api-plugins
224 Abuses deal with reports of local or remote videos/comments/accounts alike.
227 Operations dealing with listing, uploading, fetching or modifying videos.
230 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
234 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
235 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
237 You can upload videos more reliably by using the resumable variant. Its protocol lets
238 you resume an upload operation after a network interruption or other transmission failure,
239 saving time and bandwidth in the event of network failures.
241 Favor using resumable uploads in any of the following cases:
242 - You are transferring large files
243 - The likelihood of a network interruption is high
244 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
245 such as a mobile device
249 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
250 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
253 The import function is practical when the desired video/audio is available online. It makes PeerTube
254 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
255 - name: Video Captions
256 description: Operations dealing with listing, adding and removing closed captions of a video.
257 - name: Video Channels
258 description: Operations dealing with the creation, modification and listing of videos within a channel.
259 - name: Video Comments
261 Operations dealing with comments to a video. Comments are organized in threads: adding a
262 comment in response to the video starts a thread, adding a reply to a comment adds it to
263 its root comment thread.
265 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
267 description: Like/dislike a video.
268 - name: Video Playlists
269 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
271 description: Server syndication feeds
274 The search helps to find _videos_ or _channels_ from within the instance and beyond.
275 Videos from other instances federated by the instance (that is, instances
276 followed by the instance) can be found via keywords and other criteria of
279 Administrators can also enable the use of a remote search system, indexing
280 videos and channels not could be not federated by the instance.
282 description: Get and update the custom homepage
283 - name: Video Mirroring
285 PeerTube instances can mirror videos from one another, and help distribute some videos.
287 For importing videos as your own, refer to [video imports](#operation/importVideo).
310 - Video Ownership Change
326 - name: Instance Configuration
330 - Instance Redundancy
340 summary: Get an account
341 operationId: getAccount
343 - $ref: '#/components/parameters/name'
346 description: successful operation
350 $ref: '#/components/schemas/Account'
352 description: account not found
354 '/accounts/{name}/videos':
359 summary: 'List videos of an account'
360 operationId: getAccountVideos
362 - $ref: '#/components/parameters/name'
363 - $ref: '#/components/parameters/categoryOneOf'
364 - $ref: '#/components/parameters/isLive'
365 - $ref: '#/components/parameters/tagsOneOf'
366 - $ref: '#/components/parameters/tagsAllOf'
367 - $ref: '#/components/parameters/licenceOneOf'
368 - $ref: '#/components/parameters/languageOneOf'
369 - $ref: '#/components/parameters/nsfw'
370 - $ref: '#/components/parameters/isLocal'
371 - $ref: '#/components/parameters/include'
372 - $ref: '#/components/parameters/hasHLSFiles'
373 - $ref: '#/components/parameters/hasWebtorrentFiles'
374 - $ref: '#/components/parameters/skipCount'
375 - $ref: '#/components/parameters/start'
376 - $ref: '#/components/parameters/count'
377 - $ref: '#/components/parameters/videosSort'
380 description: successful operation
384 $ref: '#/components/schemas/VideoListResponse'
388 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
389 .then(function(response) {
390 return response.json()
391 }).then(function(data) {
397 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
403 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
405 http = Net::HTTP.new(uri.host, uri.port)
408 response = http.get(uri.request_uri)
410 puts JSON.parse(response.read_body)
415 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
420 '/accounts/{name}/followers':
424 summary: 'List followers of an account'
427 operationId: getAccountFollowers
429 - $ref: '#/components/parameters/name'
430 - $ref: '#/components/parameters/start'
431 - $ref: '#/components/parameters/count'
432 - $ref: '#/components/parameters/followersSort'
433 - $ref: '#/components/parameters/search'
436 description: successful operation
448 $ref: '#/components/schemas/Follow'
454 summary: List accounts
455 operationId: getAccounts
457 - $ref: '#/components/parameters/start'
458 - $ref: '#/components/parameters/count'
459 - $ref: '#/components/parameters/sort'
462 description: successful operation
468 $ref: '#/components/schemas/Account'
474 summary: Get instance public configuration
475 operationId: getConfig
478 description: successful operation
482 $ref: '#/components/schemas/ServerConfig'
485 externalValue: https://peertube2.cpy.re/api/v1/config
489 summary: Get instance "About" information
490 operationId: getAbout
495 description: successful operation
499 $ref: '#/components/schemas/ServerConfigAbout'
502 externalValue: https://peertube2.cpy.re/api/v1/config/about
506 summary: Get instance runtime configuration
507 operationId: getCustomConfig
515 description: successful operation
519 $ref: '#/components/schemas/ServerConfigCustom'
521 summary: Set instance runtime configuration
522 operationId: putCustomConfig
530 description: successful operation
532 x-summary: field inconsistencies
535 - the emailer is disabled and the instance is open to registrations
536 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
538 summary: Delete instance runtime configuration
539 operationId: delCustomConfig
547 description: successful operation
549 /custom-pages/homepage/instance:
551 summary: Get instance custom homepage
556 description: No homepage set
558 description: successful operation
562 $ref: '#/components/schemas/CustomHomepage'
564 summary: Set instance custom homepage
578 description: content of the homepage, that will be injected in the client
581 description: successful operation
585 summary: List instance jobs
596 description: The state of the job ('' for for no filter)
606 - $ref: '#/components/parameters/jobType'
607 - $ref: '#/components/parameters/start'
608 - $ref: '#/components/parameters/count'
609 - $ref: '#/components/parameters/sort'
612 description: successful operation
625 $ref: '#/components/schemas/Job'
631 summary: List instances following the server
633 - $ref: '#/components/parameters/followState'
634 - $ref: '#/components/parameters/actorType'
635 - $ref: '#/components/parameters/start'
636 - $ref: '#/components/parameters/count'
637 - $ref: '#/components/parameters/sort'
640 description: successful operation
652 $ref: '#/components/schemas/Follow'
654 '/server/followers/{nameWithHost}':
656 summary: Remove or reject a follower to your server
666 description: The remote actor handle to remove from your followers
672 description: successful operation
674 description: follower not found
676 '/server/followers/{nameWithHost}/reject':
678 summary: Reject a pending follower to your server
688 description: The remote actor handle to remove from your followers
694 description: successful operation
696 description: follower not found
698 '/server/followers/{nameWithHost}/accept':
700 summary: Accept a pending follower to your server
710 description: The remote actor handle to remove from your followers
716 description: successful operation
718 description: follower not found
724 summary: List instances followed by the server
726 - $ref: '#/components/parameters/followState'
727 - $ref: '#/components/parameters/actorType'
728 - $ref: '#/components/parameters/start'
729 - $ref: '#/components/parameters/count'
730 - $ref: '#/components/parameters/sort'
733 description: successful operation
745 $ref: '#/components/schemas/Follow'
752 summary: Follow a list of actors (PeerTube instance, channel or account)
755 description: successful operation
757 description: cannot follow a non-HTTPS server
776 '/server/following/{hostOrHandle}':
778 summary: Unfollow an actor (PeerTube instance, channel or account)
788 description: The hostOrHandle to unfollow
793 description: successful operation
795 description: host or handle not found
799 summary: Create a user
808 description: user created
812 $ref: '#/components/schemas/AddUserResponse'
818 id: '$response.body#/user/id'
823 id: '$response.body#/user/id'
828 id: '$response.body#/user/id'
830 description: insufficient authority to create an admin or moderator
835 $ref: '#/components/schemas/AddUser'
837 If the smtp server is configured, you can leave the password empty and an email will be sent
838 asking the user to set it first.
842 operationId: getUsers
849 - $ref: '#/components/parameters/usersSearch'
850 - $ref: '#/components/parameters/usersBlocked'
851 - $ref: '#/components/parameters/start'
852 - $ref: '#/components/parameters/count'
853 - $ref: '#/components/parameters/usersSort'
856 description: successful operation
862 $ref: '#/components/schemas/User'
866 - $ref: '#/components/parameters/id'
868 summary: Delete a user
877 description: successful operation
888 description: include statistics about the user (only available as a moderator/admin)
893 x-summary: successful operation
895 As an admin/moderator, you can request a response augmented with statistics about the user's
896 moderation relations and videos usage, by using the `withStats` parameter.
901 - $ref: '#/components/schemas/User'
902 - $ref: '#/components/schemas/UserWithStats'
904 summary: Update a user
912 description: successful operation
917 $ref: '#/components/schemas/UpdateUser'
920 /oauth-clients/local:
922 summary: Login prerequisite
923 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
924 operationId: getOAuthClient
929 description: successful operation
933 $ref: '#/components/schemas/OAuthClient'
935 UseOAuthClientToLogin:
936 operationId: getOAuthToken
938 client_id: '$response.body#/client_id'
939 client_secret: '$response.body#/client_secret'
943 API="https://peertube2.cpy.re/api/v1"
946 curl -s "$API/oauth-clients/local"
951 operationId: getOAuthToken
952 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
957 application/x-www-form-urlencoded:
960 - $ref: '#/components/schemas/OAuthToken-password'
961 - $ref: '#/components/schemas/OAuthToken-refresh_token'
963 propertyName: grant_type
965 password: '#/components/schemas/OAuthToken-password'
966 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
969 description: successful operation
980 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
981 description: valid for 1 day
984 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
985 description: valid for 2 weeks
990 refresh_token_expires_in:
995 x-summary: client or credentials are invalid
997 Disambiguate via `type`:
998 - `invalid_client` for an unmatched `client_id`
999 - `invalid_grant` for unmatched credentials
1001 x-summary: token expired
1003 Disambiguate via `type`:
1004 - default value for a regular authentication failure
1005 - `invalid_token` for an expired token
1010 API="https://peertube2.cpy.re/api/v1"
1011 USERNAME="<your_username>"
1012 PASSWORD="<your_password>"
1015 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1016 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1017 curl -s "$API/users/token" \
1018 --data client_id="$client_id" \
1019 --data client_secret="$client_secret" \
1020 --data grant_type=password \
1021 --data username="$USERNAME" \
1022 --data password="$PASSWORD" \
1023 | jq -r ".access_token"
1025 /users/revoke-token:
1028 description: Revokes your access token and its associated refresh token, destroying your current session.
1029 operationId: revokeOAuthToken
1036 description: successful operation
1040 summary: Register a user
1041 operationId: registerUser
1047 description: successful operation
1052 $ref: '#/components/schemas/RegisterUser'
1055 /users/{id}/verify-email:
1057 summary: Verify a user
1058 operationId: verifyUser
1060 Following a user registration, the new user will receive an email asking to click a link
1061 containing a secret.
1066 - $ref: '#/components/parameters/id'
1079 - verificationString
1082 description: successful operation
1084 description: invalid verification string
1086 description: user not found
1088 /users/ask-send-verify-email:
1090 summary: Resend user verification link
1091 operationId: resendEmailToVerifyUser
1097 description: successful operation
1101 summary: Get my user information
1102 operationId: getUserInfo
1110 description: successful operation
1116 $ref: '#/components/schemas/User'
1118 summary: Update my user information
1119 operationId: putUserInfo
1127 description: successful operation
1132 $ref: '#/components/schemas/UpdateMe'
1135 /users/me/videos/imports:
1137 summary: Get video imports of my user
1145 - $ref: '#/components/parameters/start'
1146 - $ref: '#/components/parameters/count'
1147 - $ref: '#/components/parameters/sort'
1150 description: successful operation
1154 $ref: '#/components/schemas/VideoImportsList'
1156 /users/me/video-quota-used:
1158 summary: Get my user used quota
1166 description: successful operation
1174 description: The user video quota used so far in bytes
1175 example: 16810141515
1176 videoQuotaUsedDaily:
1178 description: The user video quota used today in bytes
1181 '/users/me/videos/{videoId}/rating':
1183 summary: Get rate of my user for a video
1193 description: The video id
1195 $ref: '#/components/schemas/Video/properties/id'
1198 description: successful operation
1202 $ref: '#/components/schemas/GetMeVideoRating'
1206 summary: Get videos of my user
1214 - $ref: '#/components/parameters/start'
1215 - $ref: '#/components/parameters/count'
1216 - $ref: '#/components/parameters/sort'
1219 description: successful operation
1223 $ref: '#/components/schemas/VideoListResponse'
1225 /users/me/subscriptions:
1227 summary: Get my user subscriptions
1234 - $ref: '#/components/parameters/start'
1235 - $ref: '#/components/parameters/count'
1236 - $ref: '#/components/parameters/sort'
1239 description: successful operation
1243 $ref: '#/components/schemas/VideoChannelList'
1247 summary: Add subscription to my user
1260 description: uri of the video channels to subscribe to
1266 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1269 description: successful operation
1271 /users/me/subscriptions/exist:
1273 summary: Get if subscriptions exist for my user
1280 - $ref: '#/components/parameters/subscriptionsUris'
1283 description: successful operation
1289 /users/me/subscriptions/videos:
1291 summary: List videos of subscriptions of my user
1299 - $ref: '#/components/parameters/categoryOneOf'
1300 - $ref: '#/components/parameters/isLive'
1301 - $ref: '#/components/parameters/tagsOneOf'
1302 - $ref: '#/components/parameters/tagsAllOf'
1303 - $ref: '#/components/parameters/licenceOneOf'
1304 - $ref: '#/components/parameters/languageOneOf'
1305 - $ref: '#/components/parameters/nsfw'
1306 - $ref: '#/components/parameters/isLocal'
1307 - $ref: '#/components/parameters/include'
1308 - $ref: '#/components/parameters/hasHLSFiles'
1309 - $ref: '#/components/parameters/hasWebtorrentFiles'
1310 - $ref: '#/components/parameters/skipCount'
1311 - $ref: '#/components/parameters/start'
1312 - $ref: '#/components/parameters/count'
1313 - $ref: '#/components/parameters/videosSort'
1316 description: successful operation
1320 $ref: '#/components/schemas/VideoListResponse'
1322 '/users/me/subscriptions/{subscriptionHandle}':
1324 summary: Get subscription of my user
1331 - $ref: '#/components/parameters/subscriptionHandle'
1334 description: successful operation
1338 $ref: '#/components/schemas/VideoChannel'
1340 summary: Delete subscription of my user
1347 - $ref: '#/components/parameters/subscriptionHandle'
1350 description: successful operation
1352 /users/me/notifications:
1354 summary: List my notifications
1362 description: only list unread notifications
1365 - $ref: '#/components/parameters/start'
1366 - $ref: '#/components/parameters/count'
1367 - $ref: '#/components/parameters/sort'
1370 description: successful operation
1374 $ref: '#/components/schemas/NotificationListResponse'
1376 /users/me/notifications/read:
1378 summary: Mark notifications as read by their id
1391 description: ids of the notifications to mark as read
1398 description: successful operation
1400 /users/me/notifications/read-all:
1402 summary: Mark all my notification as read
1409 description: successful operation
1411 /users/me/notification-settings:
1413 summary: Update my notification settings
1424 newVideoFromSubscription:
1425 $ref: '#/components/schemas/NotificationSettingValue'
1426 newCommentOnMyVideo:
1427 $ref: '#/components/schemas/NotificationSettingValue'
1429 $ref: '#/components/schemas/NotificationSettingValue'
1430 videoAutoBlacklistAsModerator:
1431 $ref: '#/components/schemas/NotificationSettingValue'
1433 $ref: '#/components/schemas/NotificationSettingValue'
1435 $ref: '#/components/schemas/NotificationSettingValue'
1436 myVideoImportFinished:
1437 $ref: '#/components/schemas/NotificationSettingValue'
1439 $ref: '#/components/schemas/NotificationSettingValue'
1440 newUserRegistration:
1441 $ref: '#/components/schemas/NotificationSettingValue'
1443 $ref: '#/components/schemas/NotificationSettingValue'
1444 newInstanceFollower:
1445 $ref: '#/components/schemas/NotificationSettingValue'
1446 autoInstanceFollowing:
1447 $ref: '#/components/schemas/NotificationSettingValue'
1450 description: successful operation
1452 /users/me/history/videos:
1454 summary: List watched videos history
1460 - $ref: '#/components/parameters/start'
1461 - $ref: '#/components/parameters/count'
1462 - $ref: '#/components/parameters/search'
1465 description: successful operation
1469 $ref: '#/components/schemas/VideoListResponse'
1471 /users/me/history/videos/remove:
1473 summary: Clear video history
1480 multipart/form-data:
1485 description: history before this date will be deleted
1490 description: successful operation
1492 /users/me/avatar/pick:
1494 summary: Update my user avatar
1501 description: successful operation
1508 $ref: '#/components/schemas/ActorImage'
1510 description: image file too large
1512 X-File-Maximum-Size:
1516 description: Maximum file size for the avatar
1519 multipart/form-data:
1524 description: The file to upload
1529 contentType: image/png, image/jpeg
1533 summary: Delete my avatar
1540 description: successful operation
1544 summary: List video ownership changes
1546 - Video Ownership Change
1551 description: successful operation
1553 '/videos/ownership/{id}/accept':
1555 summary: Accept ownership change request
1557 - Video Ownership Change
1561 - $ref: '#/components/parameters/idOrUUID'
1564 description: successful operation
1566 description: cannot terminate an ownership change of another user
1568 description: video owneship change not found
1570 '/videos/ownership/{id}/refuse':
1572 summary: Refuse ownership change request
1574 - Video Ownership Change
1578 - $ref: '#/components/parameters/idOrUUID'
1581 description: successful operation
1583 description: cannot terminate an ownership change of another user
1585 description: video owneship change not found
1587 '/videos/{id}/give-ownership':
1589 summary: Request ownership change
1591 - Video Ownership Change
1595 - $ref: '#/components/parameters/idOrUUID'
1599 application/x-www-form-urlencoded:
1609 description: successful operation
1611 description: changing video ownership to a remote account is not supported yet
1613 description: video not found
1617 summary: List videos
1618 operationId: getVideos
1622 - $ref: '#/components/parameters/categoryOneOf'
1623 - $ref: '#/components/parameters/isLive'
1624 - $ref: '#/components/parameters/tagsOneOf'
1625 - $ref: '#/components/parameters/tagsAllOf'
1626 - $ref: '#/components/parameters/licenceOneOf'
1627 - $ref: '#/components/parameters/languageOneOf'
1628 - $ref: '#/components/parameters/nsfw'
1629 - $ref: '#/components/parameters/isLocal'
1630 - $ref: '#/components/parameters/include'
1631 - $ref: '#/components/parameters/hasHLSFiles'
1632 - $ref: '#/components/parameters/hasWebtorrentFiles'
1633 - $ref: '#/components/parameters/skipCount'
1634 - $ref: '#/components/parameters/start'
1635 - $ref: '#/components/parameters/count'
1636 - $ref: '#/components/parameters/videosSort'
1639 description: successful operation
1643 $ref: '#/components/schemas/VideoListResponse'
1647 summary: List available video categories
1648 operationId: getCategories
1653 description: successful operation
1662 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1666 summary: List available video licences
1667 operationId: getLicences
1672 description: successful operation
1681 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1685 summary: List available video languages
1686 operationId: getLanguages
1691 description: successful operation
1700 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1704 summary: List available video privacy policies
1705 operationId: getPrivacyPolicies
1710 description: successful operation
1719 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1723 summary: Update a video
1724 operationId: putVideo
1730 - $ref: '#/components/parameters/idOrUUID'
1733 description: successful operation
1736 multipart/form-data:
1741 description: Video thumbnail file
1745 description: Video preview file
1749 $ref: '#/components/schemas/VideoCategorySet'
1751 $ref: '#/components/schemas/VideoLicenceSet'
1753 $ref: '#/components/schemas/VideoLanguageSet'
1755 $ref: '#/components/schemas/VideoPrivacySet'
1757 description: Video description
1760 description: Whether or not we wait transcoding before publish the video
1763 description: A text tell the audience how to support the video creator
1764 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1767 description: Whether or not this video contains sensitive content
1770 description: Video name
1775 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1784 description: Enable or disable comments for this video
1787 description: Enable or disable downloading for this video
1789 originallyPublishedAt:
1790 description: Date when the content was originally published
1794 $ref: '#/components/schemas/VideoScheduledUpdate'
1797 contentType: image/jpeg
1799 contentType: image/jpeg
1801 summary: Get a video
1802 operationId: getVideo
1806 - $ref: '#/components/parameters/idOrUUID'
1809 description: successful operation
1813 $ref: '#/components/schemas/VideoDetails'
1815 summary: Delete a video
1816 operationId: delVideo
1822 - $ref: '#/components/parameters/idOrUUID'
1825 description: successful operation
1827 '/videos/{id}/description':
1829 summary: Get complete video description
1830 operationId: getVideoDesc
1834 - $ref: '#/components/parameters/idOrUUID'
1837 description: successful operation
1846 **[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)**
1848 '/videos/{id}/views':
1850 summary: Add a view to a video
1851 operationId: addView
1855 - $ref: '#/components/parameters/idOrUUID'
1858 description: successful operation
1860 '/videos/{id}/watching':
1862 summary: Set watching progress of a video
1863 operationId: setProgress
1869 - $ref: '#/components/parameters/idOrUUID'
1874 $ref: '#/components/schemas/UserWatchingVideo'
1878 description: successful operation
1882 summary: Upload a video
1883 description: Uses a single request to upload a video.
1884 operationId: uploadLegacy
1892 description: successful operation
1896 $ref: '#/components/schemas/VideoUploadResponse'
1898 description: video didn't pass upload filter
1900 description: upload has timed out
1902 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1904 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1905 - `quota_reached` for quota limits wether daily or global
1907 X-File-Maximum-Size:
1911 description: Maximum file size for the video
1913 description: video type unsupported
1915 description: video unreadable
1918 multipart/form-data:
1920 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1923 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1925 contentType: image/jpeg
1927 contentType: image/jpeg
1932 USERNAME="<your_username>"
1933 PASSWORD="<your_password>"
1934 FILE_PATH="<your_file_path>"
1935 CHANNEL_ID="<your_channel_id>"
1937 API="https://peertube2.cpy.re/api/v1"
1940 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1941 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1942 token=$(curl -s "$API/users/token" \
1943 --data client_id="$client_id" \
1944 --data client_secret="$client_secret" \
1945 --data grant_type=password \
1946 --data username="$USERNAME" \
1947 --data password="$PASSWORD" \
1948 | jq -r ".access_token")
1951 curl -s "$API/videos/upload" \
1952 -H "Authorization: Bearer $token" \
1954 --form videofile=@"$FILE_PATH" \
1955 --form channelId=$CHANNEL_ID \
1958 /videos/upload-resumable:
1960 summary: Initialize the resumable upload of a video
1961 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1962 operationId: uploadResumableInit
1969 - name: X-Upload-Content-Length
1975 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1976 - name: X-Upload-Content-Type
1983 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1988 $ref: '#/components/schemas/VideoUploadRequestResumable'
1991 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1993 description: created
1999 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2005 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2007 Disambiguate via `type`:
2008 - `max_file_size_reached` for the absolute file size limit
2009 - `quota_reached` for quota limits whether daily or global
2011 description: video type unsupported
2013 summary: Send chunk for the resumable upload of a video
2014 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
2015 operationId: uploadResumable
2026 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2027 not valid anymore and you need to initialize a new upload.
2030 - name: Content-Range
2034 example: bytes 0-262143/2469036
2037 Specifies the bytes in the file that the request is uploading.
2039 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2040 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2041 - name: Content-Length
2048 Size of the chunk that the request is sending.
2050 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)
2051 doesn't mandate for chunks to have the same size throughout the upload sequence.
2053 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2054 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2057 application/octet-stream:
2063 description: last chunk received
2071 $ref: '#/components/schemas/VideoUploadResponse'
2073 description: resume incomplete
2078 example: bytes=0-262143
2084 description: video didn't pass upload filter
2086 description: upload not found
2088 description: chunk doesn't match range
2090 description: video unreadable
2092 description: too many concurrent requests
2094 description: upload is already being processed
2101 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2102 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2103 operationId: uploadResumableCancel
2114 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2115 not valid anymore and the upload session has already been deleted with its data ;-)
2118 - name: Content-Length
2126 description: upload cancelled
2133 description: upload not found
2137 summary: Import a video
2138 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2139 operationId: importVideo
2147 multipart/form-data:
2149 $ref: '#/components/schemas/VideoCreateImport'
2152 contentType: application/x-bittorrent
2154 contentType: image/jpeg
2156 contentType: image/jpeg
2159 description: successful operation
2163 $ref: '#/components/schemas/VideoUploadResponse'
2165 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2167 description: video didn't pass pre-import filter
2169 description: HTTP or Torrent/magnetURI import not enabled
2173 summary: Create a live
2174 operationId: addLive
2182 description: successful operation
2186 $ref: '#/components/schemas/VideoUploadResponse'
2188 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2190 Disambiguate via `type`:
2191 - default type for a validation error
2192 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2194 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2196 Disambiguate via `type`:
2197 - `live_not_enabled` for a disabled live feature
2198 - `live_not_allowing_replay` for a disabled replay feature
2199 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2200 - `max_user_lives_limit_reached` for the user concurrent live limit
2203 multipart/form-data:
2208 description: Channel id that will contain this live video
2213 description: User can stream multiple times in a permanent live
2216 description: Live video/replay thumbnail file
2220 description: Live video/replay preview file
2224 $ref: '#/components/schemas/VideoPrivacySet'
2226 $ref: '#/components/schemas/VideoCategorySet'
2228 $ref: '#/components/schemas/VideoLicenceSet'
2230 $ref: '#/components/schemas/VideoLanguageSet'
2232 description: Live video/replay description
2235 description: A text tell the audience how to support the creator
2236 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2239 description: Whether or not this live video/replay contains sensitive content
2242 description: Live video/replay name
2247 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2256 description: Enable or disable comments for this live video/replay
2259 description: Enable or disable downloading for the replay of this live video
2266 contentType: image/jpeg
2268 contentType: image/jpeg
2272 summary: Get information about a live
2273 operationId: getLiveId
2280 - $ref: '#/components/parameters/idOrUUID'
2283 description: successful operation
2287 $ref: '#/components/schemas/LiveVideoResponse'
2289 summary: Update information about a live
2290 operationId: updateLiveId
2297 - $ref: '#/components/parameters/idOrUUID'
2302 $ref: '#/components/schemas/LiveVideoUpdate'
2305 description: successful operation
2307 description: bad parameters or trying to update a live that has already started
2309 description: trying to save replay of the live but saving replay is not enabled on the instance
2313 summary: List my abuses
2314 operationId: getMyAbuses
2323 description: only list the report with this id
2329 $ref: '#/components/schemas/AbuseStateSet'
2330 - $ref: '#/components/parameters/abusesSort'
2331 - $ref: '#/components/parameters/start'
2332 - $ref: '#/components/parameters/count'
2335 description: successful operation
2347 $ref: '#/components/schemas/Abuse'
2351 summary: List abuses
2352 operationId: getAbuses
2362 description: only list the report with this id
2365 - name: predefinedReason
2367 description: predefined reason the listed reports should contain
2369 $ref: '#/components/schemas/PredefinedAbuseReasons'
2372 description: plain search that will match with video titles, reporter names and more
2378 $ref: '#/components/schemas/AbuseStateSet'
2379 - name: searchReporter
2381 description: only list reports of a specific reporter
2384 - name: searchReportee
2385 description: only list reports of a specific reportee
2391 description: only list reports of a specific video
2394 - name: searchVideoChannel
2396 description: only list reports of a specific video channel
2401 description: only list deleted or blocklisted videos
2409 description: only list account, comment or video reports
2416 - $ref: '#/components/parameters/start'
2417 - $ref: '#/components/parameters/count'
2418 - $ref: '#/components/parameters/abusesSort'
2421 description: successful operation
2433 $ref: '#/components/schemas/Abuse'
2435 summary: Report an abuse
2448 description: Reason why the user reports this video
2453 $ref: '#/components/schemas/PredefinedAbuseReasons'
2458 description: Video id to report
2460 - $ref: '#/components/schemas/Video/properties/id'
2464 description: Timestamp in the video that marks the beginning of the report
2469 description: Timestamp in the video that marks the ending of the report
2475 description: Comment id to report
2477 - $ref: '#/components/schemas/VideoComment/properties/id'
2482 description: Account id to report
2488 description: successful operation
2498 $ref: '#/components/schemas/id'
2500 description: incorrect request parameters
2502 '/abuses/{abuseId}':
2504 summary: Update an abuse
2512 - $ref: '#/components/parameters/abuseId'
2520 $ref: '#/components/schemas/AbuseStateSet'
2523 description: Update the report comment visible only to the moderation team
2528 description: successful operation
2530 description: abuse not found
2534 summary: Delete an abuse
2540 - $ref: '#/components/parameters/abuseId'
2543 description: successful operation
2545 description: block not found
2547 '/abuses/{abuseId}/messages':
2549 summary: List messages of an abuse
2555 - $ref: '#/components/parameters/abuseId'
2558 description: successful operation
2570 $ref: '#/components/schemas/AbuseMessage'
2572 summary: Add message to an abuse
2578 - $ref: '#/components/parameters/abuseId'
2587 description: Message to send
2595 description: successful operation
2597 description: incorrect request parameters
2599 '/abuses/{abuseId}/messages/{abuseMessageId}':
2601 summary: Delete an abuse message
2607 - $ref: '#/components/parameters/abuseId'
2608 - $ref: '#/components/parameters/abuseMessageId'
2611 description: successful operation
2613 '/videos/{id}/blacklist':
2615 summary: Block a video
2616 operationId: addVideoBlock
2624 - $ref: '#/components/parameters/idOrUUID'
2627 description: successful operation
2629 summary: Unblock a video by its id
2630 operationId: delVideoBlock
2638 - $ref: '#/components/parameters/idOrUUID'
2641 description: successful operation
2643 description: block not found
2649 summary: List video blocks
2650 operationId: getVideoBlocks
2659 list only blocks that match this type:
2663 - `2`: automatic block that needs review
2671 description: plain search that will match with video titles, and more
2674 - $ref: '#/components/parameters/start'
2675 - $ref: '#/components/parameters/count'
2676 - $ref: '#/components/parameters/blacklistsSort'
2679 description: successful operation
2691 $ref: '#/components/schemas/VideoBlacklist'
2693 /videos/{id}/captions:
2695 summary: List captions of a video
2696 operationId: getVideoCaptions
2700 - $ref: '#/components/parameters/idOrUUID'
2703 description: successful operation
2715 $ref: '#/components/schemas/VideoCaption'
2717 /videos/{id}/captions/{captionLanguage}:
2719 summary: Add or replace a video caption
2720 operationId: addVideoCaption
2727 - $ref: '#/components/parameters/idOrUUID'
2728 - $ref: '#/components/parameters/captionLanguage'
2731 multipart/form-data:
2736 description: The file to upload.
2741 contentType: text/vtt, application/x-subrip, text/plain
2744 description: successful operation
2746 description: video or language not found
2748 summary: Delete a video caption
2749 operationId: delVideoCaption
2756 - $ref: '#/components/parameters/idOrUUID'
2757 - $ref: '#/components/parameters/captionLanguage'
2760 description: successful operation
2762 description: video or language or caption for that language not found
2766 summary: List video channels
2767 operationId: getVideoChannels
2771 - $ref: '#/components/parameters/start'
2772 - $ref: '#/components/parameters/count'
2773 - $ref: '#/components/parameters/sort'
2776 description: successful operation
2780 $ref: '#/components/schemas/VideoChannelList'
2782 summary: Create a video channel
2783 operationId: addVideoChannel
2790 description: successful operation
2800 $ref: '#/components/schemas/VideoChannel/properties/id'
2805 $ref: '#/components/schemas/VideoChannelCreate'
2807 '/video-channels/{channelHandle}':
2809 summary: Get a video channel
2810 operationId: getVideoChannel
2814 - $ref: '#/components/parameters/channelHandle'
2817 description: successful operation
2821 $ref: '#/components/schemas/VideoChannel'
2823 summary: Update a video channel
2824 operationId: putVideoChannel
2830 - $ref: '#/components/parameters/channelHandle'
2833 description: successful operation
2838 $ref: '#/components/schemas/VideoChannelUpdate'
2840 summary: Delete a video channel
2841 operationId: delVideoChannel
2847 - $ref: '#/components/parameters/channelHandle'
2850 description: successful operation
2852 '/video-channels/{channelHandle}/videos':
2854 summary: List videos of a video channel
2855 operationId: getVideoChannelVideos
2860 - $ref: '#/components/parameters/channelHandle'
2861 - $ref: '#/components/parameters/categoryOneOf'
2862 - $ref: '#/components/parameters/isLive'
2863 - $ref: '#/components/parameters/tagsOneOf'
2864 - $ref: '#/components/parameters/tagsAllOf'
2865 - $ref: '#/components/parameters/licenceOneOf'
2866 - $ref: '#/components/parameters/languageOneOf'
2867 - $ref: '#/components/parameters/nsfw'
2868 - $ref: '#/components/parameters/isLocal'
2869 - $ref: '#/components/parameters/include'
2870 - $ref: '#/components/parameters/hasHLSFiles'
2871 - $ref: '#/components/parameters/hasWebtorrentFiles'
2872 - $ref: '#/components/parameters/skipCount'
2873 - $ref: '#/components/parameters/start'
2874 - $ref: '#/components/parameters/count'
2875 - $ref: '#/components/parameters/videosSort'
2878 description: successful operation
2882 $ref: '#/components/schemas/VideoListResponse'
2884 '/video-channels/{channelHandle}/followers':
2888 summary: 'List followers of a video channel'
2891 operationId: getVideoChannelFollowers
2893 - $ref: '#/components/parameters/channelHandle'
2894 - $ref: '#/components/parameters/start'
2895 - $ref: '#/components/parameters/count'
2896 - $ref: '#/components/parameters/followersSort'
2897 - $ref: '#/components/parameters/search'
2900 description: successful operation
2912 $ref: '#/components/schemas/Follow'
2914 '/video-channels/{channelHandle}/avatar/pick':
2916 summary: Update channel avatar
2922 - $ref: '#/components/parameters/channelHandle'
2925 description: successful operation
2932 $ref: '#/components/schemas/ActorImage'
2934 description: image file too large
2936 X-File-Maximum-Size:
2940 description: Maximum file size for the avatar
2943 multipart/form-data:
2948 description: The file to upload.
2953 contentType: image/png, image/jpeg
2955 '/video-channels/{channelHandle}/avatar':
2957 summary: Delete channel avatar
2963 - $ref: '#/components/parameters/channelHandle'
2966 description: successful operation
2968 '/video-channels/{channelHandle}/banner/pick':
2970 summary: Update channel banner
2976 - $ref: '#/components/parameters/channelHandle'
2979 description: successful operation
2986 $ref: '#/components/schemas/ActorImage'
2988 description: image file too large
2990 X-File-Maximum-Size:
2994 description: Maximum file size for the banner
2997 multipart/form-data:
3002 description: The file to upload.
3007 contentType: image/png, image/jpeg
3009 '/video-channels/{channelHandle}/banner':
3011 summary: Delete channel banner
3017 - $ref: '#/components/parameters/channelHandle'
3020 description: successful operation
3022 /video-playlists/privacies:
3024 summary: List available playlist privacy policies
3025 operationId: getPlaylistPrivacyPolicies
3030 description: successful operation
3039 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3043 summary: List video playlists
3044 operationId: getPlaylists
3048 - $ref: '#/components/parameters/start'
3049 - $ref: '#/components/parameters/count'
3050 - $ref: '#/components/parameters/sort'
3053 description: successful operation
3065 $ref: '#/components/schemas/VideoPlaylist'
3067 summary: Create a video playlist
3068 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3069 operationId: addPlaylist
3076 description: successful operation
3086 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3088 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3090 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3093 multipart/form-data:
3098 description: Video playlist display name
3103 description: Video playlist thumbnail file
3107 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3109 description: Video playlist description
3115 - $ref: '#/components/schemas/id'
3116 description: Video channel in which the playlist will be published
3121 contentType: image/jpeg
3123 /video-playlists/{playlistId}:
3125 summary: Get a video playlist
3129 - $ref: '#/components/parameters/playlistId'
3132 description: successful operation
3136 $ref: '#/components/schemas/VideoPlaylist'
3138 summary: Update a video playlist
3139 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3146 description: successful operation
3148 - $ref: '#/components/parameters/playlistId'
3151 multipart/form-data:
3156 description: Video playlist display name
3161 description: Video playlist thumbnail file
3165 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3167 description: Video playlist description
3171 - $ref: '#/components/schemas/id'
3172 description: Video channel in which the playlist will be published
3175 contentType: image/jpeg
3177 summary: Delete a video playlist
3183 - $ref: '#/components/parameters/playlistId'
3186 description: successful operation
3188 /video-playlists/{playlistId}/videos:
3190 summary: 'List videos of a playlist'
3191 operationId: getVideoPlaylistVideos
3196 - $ref: '#/components/parameters/playlistId'
3197 - $ref: '#/components/parameters/start'
3198 - $ref: '#/components/parameters/count'
3201 description: successful operation
3205 $ref: '#/components/schemas/VideoListResponse'
3207 summary: Add a video in a playlist
3208 operationId: addVideoPlaylistVideo
3215 - $ref: '#/components/parameters/playlistId'
3218 description: successful operation
3224 videoPlaylistElement:
3238 - $ref: '#/components/schemas/Video/properties/uuid'
3239 - $ref: '#/components/schemas/Video/properties/id'
3240 description: Video to add in the playlist
3244 description: Start the video at this specific timestamp
3248 description: Stop the video at this specific timestamp
3252 /video-playlists/{playlistId}/videos/reorder:
3254 summary: 'Reorder a playlist'
3255 operationId: reorderVideoPlaylist
3261 - $ref: '#/components/parameters/playlistId'
3264 description: successful operation
3273 description: 'Start position of the element to reorder'
3275 insertAfterPosition:
3277 description: 'New position for the block to reorder, to add the block before the first element'
3281 description: 'How many element from `startPosition` to reorder'
3285 - insertAfterPosition
3287 /video-playlists/{playlistId}/videos/{playlistElementId}:
3289 summary: Update a playlist element
3290 operationId: putVideoPlaylistVideo
3296 - $ref: '#/components/parameters/playlistId'
3297 - $ref: '#/components/parameters/playlistElementId'
3300 description: successful operation
3310 description: Start the video at this specific timestamp
3314 description: Stop the video at this specific timestamp
3316 summary: Delete an element from a playlist
3317 operationId: delVideoPlaylistVideo
3323 - $ref: '#/components/parameters/playlistId'
3324 - $ref: '#/components/parameters/playlistElementId'
3327 description: successful operation
3329 '/users/me/video-playlists/videos-exist':
3331 summary: Check video exists in my playlists
3340 description: The video ids to check
3344 $ref: '#/components/schemas/Video/properties/id'
3347 description: successful operation
3369 '/accounts/{name}/video-channels':
3371 summary: List video channels of an account
3376 - $ref: '#/components/parameters/name'
3379 description: include view statistics for the last 30 days (only if authentified as the account user)
3382 - $ref: '#/components/parameters/start'
3383 - $ref: '#/components/parameters/count'
3384 - $ref: '#/components/parameters/sort'
3387 description: successful operation
3391 $ref: '#/components/schemas/VideoChannelList'
3393 '/accounts/{name}/ratings':
3395 summary: List ratings of an account
3401 - $ref: '#/components/parameters/name'
3402 - $ref: '#/components/parameters/start'
3403 - $ref: '#/components/parameters/count'
3404 - $ref: '#/components/parameters/sort'
3408 description: Optionally filter which ratings to retrieve
3416 description: successful operation
3422 $ref: '#/components/schemas/VideoRating'
3424 '/videos/{id}/comment-threads':
3426 summary: List threads of a video
3430 - $ref: '#/components/parameters/idOrUUID'
3431 - $ref: '#/components/parameters/start'
3432 - $ref: '#/components/parameters/count'
3433 - $ref: '#/components/parameters/commentsSort'
3436 description: successful operation
3440 $ref: '#/components/schemas/CommentThreadResponse'
3442 summary: Create a thread
3448 - $ref: '#/components/parameters/idOrUUID'
3451 description: successful operation
3455 $ref: '#/components/schemas/CommentThreadPostResponse'
3457 description: video does not exist
3466 - $ref: '#/components/schemas/VideoComment/properties/text'
3472 '/videos/{id}/comment-threads/{threadId}':
3474 summary: Get a thread
3478 - $ref: '#/components/parameters/idOrUUID'
3479 - $ref: '#/components/parameters/threadId'
3482 description: successful operation
3486 $ref: '#/components/schemas/VideoCommentThreadTree'
3488 '/videos/{id}/comments/{commentId}':
3490 summary: Reply to a thread of a video
3496 - $ref: '#/components/parameters/idOrUUID'
3497 - $ref: '#/components/parameters/commentId'
3500 description: successful operation
3504 $ref: '#/components/schemas/CommentThreadPostResponse'
3506 description: thread or video does not exist
3515 - $ref: '#/components/schemas/VideoComment/properties/text'
3521 summary: Delete a comment or a reply
3527 - $ref: '#/components/parameters/idOrUUID'
3528 - $ref: '#/components/parameters/commentId'
3531 description: successful operation
3533 description: cannot remove comment of another user
3535 description: comment or video does not exist
3537 description: comment is already deleted
3539 '/videos/{id}/rate':
3541 summary: Like/dislike a video
3547 - $ref: '#/components/parameters/idOrUUID'
3563 description: successful operation
3565 description: video does not exist
3571 summary: Search videos
3572 operationId: searchVideos
3577 allowEmptyValue: false
3579 String to search. If the user can make a remote URI search, and the string is an URI then the
3580 PeerTube instance will fetch the remote object and add it to its database. Then,
3581 you can use the REST API to fetch the complete video information and interact with it.
3584 - $ref: '#/components/parameters/categoryOneOf'
3585 - $ref: '#/components/parameters/isLive'
3586 - $ref: '#/components/parameters/tagsOneOf'
3587 - $ref: '#/components/parameters/tagsAllOf'
3588 - $ref: '#/components/parameters/licenceOneOf'
3589 - $ref: '#/components/parameters/languageOneOf'
3590 - $ref: '#/components/parameters/nsfw'
3591 - $ref: '#/components/parameters/isLocal'
3592 - $ref: '#/components/parameters/include'
3593 - $ref: '#/components/parameters/hasHLSFiles'
3594 - $ref: '#/components/parameters/hasWebtorrentFiles'
3595 - $ref: '#/components/parameters/skipCount'
3596 - $ref: '#/components/parameters/start'
3597 - $ref: '#/components/parameters/count'
3598 - $ref: '#/components/parameters/searchTarget'
3599 - $ref: '#/components/parameters/videosSearchSort'
3602 description: Get videos that are published after this date
3608 description: Get videos that are published before this date
3612 - name: originallyPublishedStartDate
3614 description: Get videos that are originally published after this date
3618 - name: originallyPublishedEndDate
3620 description: Get videos that are originally published before this date
3626 description: Get videos that have this minimum duration
3631 description: Get videos that have this maximum duration
3635 'searchTarget === search-index':
3636 $ref: '#/components/callbacks/searchIndex'
3639 description: successful operation
3643 $ref: '#/components/schemas/VideoListResponse'
3645 description: search index unavailable
3647 /search/video-channels:
3651 summary: Search channels
3652 operationId: searchChannels
3658 String to search. If the user can make a remote URI search, and the string is an URI then the
3659 PeerTube instance will fetch the remote object and add it to its database. Then,
3660 you can use the REST API to fetch the complete channel information and interact with it.
3663 - $ref: '#/components/parameters/start'
3664 - $ref: '#/components/parameters/count'
3665 - $ref: '#/components/parameters/searchTarget'
3666 - $ref: '#/components/parameters/sort'
3668 'searchTarget === search-index':
3669 $ref: '#/components/callbacks/searchIndex'
3672 description: successful operation
3676 $ref: '#/components/schemas/VideoChannelList'
3678 description: search index unavailable
3680 /search/video-playlists:
3684 summary: Search playlists
3685 operationId: searchPlaylists
3691 String to search. If the user can make a remote URI search, and the string is an URI then the
3692 PeerTube instance will fetch the remote object and add it to its database. Then,
3693 you can use the REST API to fetch the complete playlist information and interact with it.
3696 - $ref: '#/components/parameters/start'
3697 - $ref: '#/components/parameters/count'
3698 - $ref: '#/components/parameters/searchTarget'
3699 - $ref: '#/components/parameters/sort'
3701 'searchTarget === search-index':
3702 $ref: '#/components/callbacks/searchIndex'
3705 description: successful operation
3717 $ref: '#/components/schemas/VideoPlaylist'
3719 description: search index unavailable
3721 /server/blocklist/accounts:
3725 summary: List account blocks
3730 - $ref: '#/components/parameters/start'
3731 - $ref: '#/components/parameters/count'
3732 - $ref: '#/components/parameters/sort'
3735 description: successful operation
3739 summary: Block an account
3751 example: chocobozzz@example.org
3752 description: account to block, in the form `username@domain`
3757 description: successful operation
3759 description: self-blocking forbidden
3761 '/server/blocklist/accounts/{accountName}':
3765 summary: Unblock an account by its handle
3773 description: account to unblock, in the form `username@domain`
3778 description: successful operation
3780 description: account or account block does not exist
3782 /server/blocklist/servers:
3786 summary: List server blocks
3791 - $ref: '#/components/parameters/start'
3792 - $ref: '#/components/parameters/count'
3793 - $ref: '#/components/parameters/sort'
3796 description: successful operation
3800 summary: Block a server
3813 description: server domain to block
3818 description: successful operation
3820 description: self-blocking forbidden
3822 '/server/blocklist/servers/{host}':
3826 summary: Unblock a server by its domain
3834 description: server domain to unblock
3840 description: successful operation
3842 description: account block does not exist
3844 /server/redundancy/{host}:
3847 - Instance Redundancy
3848 summary: Update a server redundancy policy
3856 description: server domain to mirror
3868 description: allow mirroring of the host's local videos
3873 description: successful operation
3875 description: server is not already known
3877 /server/redundancy/videos:
3881 summary: List videos being mirrored
3882 operationId: getMirroredVideos
3890 description: direction of the mirror
3896 - $ref: '#/components/parameters/start'
3897 - $ref: '#/components/parameters/count'
3898 - $ref: '#/components/parameters/videoRedundanciesSort'
3901 description: successful operation
3907 $ref: '#/components/schemas/VideoRedundancy'
3911 summary: Mirror a video
3912 operationId: putMirroredVideo
3923 $ref: '#/components/schemas/Video/properties/id'
3928 description: successful operation
3930 description: cannot mirror a local video
3932 description: video does not exist
3934 description: video is already mirrored
3936 /server/redundancy/videos/{redundancyId}:
3940 summary: Delete a mirror done on a video
3941 operationId: delMirroredVideo
3946 - name: redundancyId
3949 description: id of an existing redundancy on a video
3954 description: successful operation
3956 description: video redundancy not found
3958 '/feeds/video-comments.{format}':
3962 summary: List comments on videos
3963 operationId: getSyndicatedComments
3968 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3981 description: 'limit listing to a specific video'
3986 description: 'limit listing to a specific account'
3991 description: 'limit listing to a specific account'
3994 - name: videoChannelId
3996 description: 'limit listing to a specific video channel'
3999 - name: videoChannelName
4001 description: 'limit listing to a specific video channel'
4006 description: successful operation
4011 default: 'max-age=900' # 15 min cache
4015 $ref: '#/components/schemas/VideoCommentsForXML'
4018 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4019 application/rss+xml:
4021 $ref: '#/components/schemas/VideoCommentsForXML'
4024 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4027 $ref: '#/components/schemas/VideoCommentsForXML'
4030 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4031 application/atom+xml:
4033 $ref: '#/components/schemas/VideoCommentsForXML'
4036 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4042 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4044 x-summary: field inconsistencies
4047 - videoId filter is mixed with a channel filter
4049 description: video, video channel or account not found
4051 description: accept header unsupported
4053 '/feeds/videos.{format}':
4057 summary: List videos
4058 operationId: getSyndicatedVideos
4063 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4076 description: 'limit listing to a specific account'
4081 description: 'limit listing to a specific account'
4084 - name: videoChannelId
4086 description: 'limit listing to a specific video channel'
4089 - name: videoChannelName
4091 description: 'limit listing to a specific video channel'
4094 - $ref: '#/components/parameters/sort'
4095 - $ref: '#/components/parameters/nsfw'
4096 - $ref: '#/components/parameters/isLocal'
4097 - $ref: '#/components/parameters/include'
4098 - $ref: '#/components/parameters/hasHLSFiles'
4099 - $ref: '#/components/parameters/hasWebtorrentFiles'
4102 description: successful operation
4107 default: 'max-age=900' # 15 min cache
4111 $ref: '#/components/schemas/VideosForXML'
4114 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4115 application/rss+xml:
4117 $ref: '#/components/schemas/VideosForXML'
4120 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4123 $ref: '#/components/schemas/VideosForXML'
4126 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4127 application/atom+xml:
4129 $ref: '#/components/schemas/VideosForXML'
4132 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4138 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4140 description: video channel or account not found
4142 description: accept header unsupported
4144 '/feeds/subscriptions.{format}':
4149 summary: List videos of subscriptions tied to a token
4150 operationId: getSyndicatedSubscriptionVideos
4155 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4168 description: limit listing to a specific account
4174 description: private token allowing access
4178 - $ref: '#/components/parameters/sort'
4179 - $ref: '#/components/parameters/nsfw'
4180 - $ref: '#/components/parameters/isLocal'
4181 - $ref: '#/components/parameters/include'
4182 - $ref: '#/components/parameters/hasHLSFiles'
4183 - $ref: '#/components/parameters/hasWebtorrentFiles'
4186 description: successful operation
4191 default: 'max-age=900' # 15 min cache
4195 $ref: '#/components/schemas/VideosForXML'
4196 application/rss+xml:
4198 $ref: '#/components/schemas/VideosForXML'
4201 $ref: '#/components/schemas/VideosForXML'
4202 application/atom+xml:
4204 $ref: '#/components/schemas/VideosForXML'
4209 description: accept header unsupported
4215 summary: List plugins
4216 operationId: getPlugins
4229 - $ref: '#/components/parameters/start'
4230 - $ref: '#/components/parameters/count'
4231 - $ref: '#/components/parameters/sort'
4234 description: successful operation
4238 $ref: '#/components/schemas/PluginResponse'
4244 summary: List available plugins
4245 operationId: getAvailablePlugins
4258 - name: currentPeerTubeEngine
4262 - $ref: '#/components/parameters/start'
4263 - $ref: '#/components/parameters/count'
4264 - $ref: '#/components/parameters/sort'
4267 description: successful operation
4271 $ref: '#/components/schemas/PluginResponse'
4273 description: plugin index unavailable
4279 summary: Install a plugin
4280 operationId: addPlugin
4293 example: peertube-plugin-auth-ldap
4296 additionalProperties: false
4303 additionalProperties: false
4306 description: successful operation
4308 description: should have either `npmName` or `path` set
4314 summary: Update a plugin
4315 operationId: updatePlugin
4328 example: peertube-plugin-auth-ldap
4331 additionalProperties: false
4338 additionalProperties: false
4341 description: successful operation
4343 description: should have either `npmName` or `path` set
4345 description: existing plugin not found
4351 summary: Uninstall a plugin
4352 operationId: uninstallPlugin
4364 description: name of the plugin/theme in its package.json
4365 example: peertube-plugin-auth-ldap
4370 description: successful operation
4372 description: existing plugin not found
4378 summary: Get a plugin
4379 operationId: getPlugin
4384 - $ref: '#/components/parameters/npmName'
4387 description: successful operation
4391 $ref: '#/components/schemas/Plugin'
4393 description: plugin not found
4395 /plugins/{npmName}/settings:
4399 summary: Set a plugin's settings
4404 - $ref: '#/components/parameters/npmName'
4413 additionalProperties: true
4416 description: successful operation
4418 description: plugin not found
4420 /plugins/{npmName}/public-settings:
4424 summary: Get a plugin's public settings
4426 - $ref: '#/components/parameters/npmName'
4429 description: successful operation
4434 additionalProperties: true
4436 description: plugin not found
4438 /plugins/{npmName}/registered-settings:
4442 summary: Get a plugin's registered settings
4447 - $ref: '#/components/parameters/npmName'
4450 description: successful operation
4455 additionalProperties: true
4457 description: plugin not found
4460 - url: 'https://peertube2.cpy.re/api/v1'
4461 description: Live Test Server (live data - latest nightly version)
4462 - url: 'https://peertube3.cpy.re/api/v1'
4463 description: Live Test Server (live data - latest RC version)
4464 - url: 'https://peertube.cpy.re/api/v1'
4465 description: Live Test Server (live data - stable version)
4472 description: Offset used to paginate results
4480 description: "Number of items to return"
4490 description: Sort column
4498 description: Plain text search, applied to various parts of the model depending on endpoint
4506 If the administrator enabled search index support, you can override the default search target.
4509 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4510 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4511 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4512 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4513 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4514 * 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
4515 the data from the origin instance API
4525 description: Sort videos by criteria
4541 description: Sort videos by criteria
4556 description: Sort comments by criteria
4566 description: Sort blocklists by criteria
4582 description: Plain text search that will match with user usernames or emails
4589 description: Filter results down to (un)banned users
4596 description: Sort users by criteria
4607 description: Sort abuses by criteria
4614 videoRedundanciesSort:
4618 description: Sort abuses by criteria
4627 description: Sort followers by criteria
4636 description: The username or handle of the account
4639 example: chocobozzz | chocobozzz@example.org
4644 description: The user id
4646 $ref: '#/components/schemas/id'
4651 description: The object id, uuid or short uuid
4654 - $ref: '#/components/schemas/id'
4655 - $ref: '#/components/schemas/UUIDv4'
4656 - $ref: '#/components/schemas/shortUUID'
4661 description: Playlist id
4663 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4665 name: playlistElementId
4668 description: Playlist element id
4670 $ref: '#/components/schemas/id'
4675 description: Abuse id
4677 $ref: '#/components/schemas/Abuse/properties/id'
4679 name: abuseMessageId
4682 description: Abuse message id
4684 $ref: '#/components/schemas/AbuseMessage/properties/id'
4686 name: captionLanguage
4689 description: The caption language
4691 $ref: '#/components/schemas/VideoLanguageSet'
4696 description: The video channel handle
4699 example: my_username | my_username@example.com
4701 name: subscriptionHandle
4704 description: The subscription handle
4707 example: my_username | my_username@example.com
4712 description: The thread id (root comment id)
4719 description: The comment id
4721 $ref: '#/components/schemas/VideoComment/properties/id'
4726 description: whether or not the video is a live
4733 description: category id of the video (see [/videos/categories](#operation/getCategories))
4736 - $ref: '#/components/schemas/VideoCategorySet'
4739 $ref: '#/components/schemas/VideoCategorySet'
4746 description: tag(s) of the video
4760 description: tag(s) of the video, where all should be present in the video
4773 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4776 - $ref: '#/components/schemas/VideoLanguageSet'
4779 $ref: '#/components/schemas/VideoLanguageSet'
4786 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4789 - $ref: '#/components/schemas/VideoLicenceSet'
4792 $ref: '#/components/schemas/VideoLicenceSet'
4799 description: if you don't need the `total` in the response
4810 description: whether to include nsfw videos, if any
4822 description: '**PeerTube >= 4.0** Display only local or remote videos'
4829 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
4831 name: hasWebtorrentFiles
4836 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
4850 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
4854 - `1` NOT_PUBLISHED_STATE
4856 - `2` HIDDEN_PRIVACY
4865 description: list of uris to check if each is part of the user subscriptions
4875 description: name of the plugin/theme on npmjs.com or in its package.json
4878 example: peertube-plugin-auth-ldap
4883 description: job type
4887 - activitypub-follow
4888 - activitypub-http-broadcast
4889 - activitypub-http-fetcher
4890 - activitypub-http-unicast
4896 - activitypub-refresher
4921 Authenticating via OAuth requires the following steps:
4922 - Have an activated account
4923 - [Generate] an access token for that account at `/api/v1/users/token`.
4924 - Make requests with the *Authorization: Bearer <token\>* header
4925 - Profit, depending on the role assigned to the account
4927 Note that the __access token is valid for 1 day__ and is given
4928 along with a __refresh token valid for 2 weeks__.
4930 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4934 tokenUrl: /api/v1/users/token
4937 moderator: Moderator scope
4940 # Resuable core properties
4948 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4949 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4954 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4955 example: 2y84q2MQUMWPbiEcxNXMgC
4958 description: immutable name of the user, used to find or mention its actor
4960 pattern: '/^[a-z0-9._]+$/'
4965 description: immutable name of the channel, used to interact with its actor
4966 example: framasoft_videos
4967 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4978 description: category id of the video (see [/videos/categories](#operation/getCategories))
4980 VideoConstantNumber-Category:
4983 $ref: '#/components/schemas/VideoCategorySet'
4986 example: Science & Technology
4990 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4992 VideoConstantNumber-Licence:
4995 $ref: '#/components/schemas/VideoLicenceSet'
4998 example: Attribution - Share Alike
5002 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5004 VideoConstantString-Language:
5007 $ref: '#/components/schemas/VideoLanguageSet'
5012 VideoPlaylistPrivacySet:
5018 description: Video playlist privacy policy (see [/video-playlists/privacies])
5019 VideoPlaylistPrivacyConstant:
5022 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5026 VideoPlaylistTypeSet:
5031 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5032 VideoPlaylistTypeConstant:
5035 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5046 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5047 VideoPrivacyConstant:
5050 $ref: '#/components/schemas/VideoPrivacySet'
5067 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5074 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5085 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5095 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5099 $ref: '#/components/schemas/AbuseStateSet'
5102 AbusePredefinedReasons:
5115 example: [spamOrMisleading]
5120 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5122 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5124 VideoResolutionConstant:
5125 description: resolutions and their labels for the video
5128 $ref: '#/components/schemas/VideoResolutionSet'
5132 VideoScheduledUpdate:
5135 $ref: '#/components/schemas/VideoPrivacySet'
5139 description: When to update the video
5159 - $ref: '#/components/schemas/ActorImage'
5160 VideoChannelSummary:
5163 $ref: '#/components/schemas/id'
5177 - $ref: '#/components/schemas/ActorImage'
5191 - $ref: '#/components/schemas/Video'
5198 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5199 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5201 $ref: '#/components/schemas/VideoResolutionConstant'
5204 description: Video file size in bytes
5207 description: Direct URL of the torrent file
5211 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5215 description: Direct URL of the video
5219 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5223 description: Frames per second of the video file
5227 description: URL dereferencing the output of ffprobe on the file
5228 VideoStreamingPlaylists:
5233 $ref: '#/components/schemas/id'
5241 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5242 VideoStreamingPlaylists-HLS:
5253 Video files associated to this playlist.
5255 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5257 $ref: '#/components/schemas/VideoFile'
5269 $ref: '#/components/schemas/Video/properties/id'
5271 $ref: '#/components/schemas/Video/properties/uuid'
5273 $ref: '#/components/schemas/Video/properties/name'
5277 description: object id for the video
5279 - $ref: '#/components/schemas/id'
5281 description: universal identifier for the video, that can be used across instances
5283 - $ref: '#/components/schemas/UUIDv4'
5286 - $ref: '#/components/schemas/shortUUID'
5292 example: 2017-10-01T10:52:46.396Z
5293 description: time at which the video object was first drafted
5297 example: 2018-10-01T10:52:46.396Z
5298 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5302 example: 2021-05-04T08:01:01.502Z
5303 description: last time the video's metadata was modified
5304 originallyPublishedAt:
5307 example: 2010-10-01T10:52:46.396Z
5308 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5311 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5312 description: category in which the video is classified
5315 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5316 description: licence under which the video is distributed
5319 - $ref: '#/components/schemas/VideoConstantString-Language'
5320 description: main language used in the video
5323 - $ref: '#/components/schemas/VideoPrivacyConstant'
5324 description: privacy policy used to distribute the video
5328 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5329 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5333 truncated description of the video, written in Markdown.
5334 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5339 description: duration of the video in seconds
5344 description: title of the video
5345 example: What is PeerTube?
5350 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5353 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5356 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5373 - $ref: '#/components/schemas/VideoStateConstant'
5374 description: represents the internal state of the video processing within the PeerTube instance
5378 - $ref: '#/components/schemas/VideoScheduledUpdate'
5386 $ref: '#/components/schemas/AccountSummary'
5388 $ref: '#/components/schemas/VideoChannelSummary'
5397 - $ref: '#/components/schemas/Video'
5402 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5403 description: path at which to get the full description of maximum `10000` characters
5406 description: A text tell the audience how to support the video creator
5407 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5411 $ref: '#/components/schemas/VideoChannel'
5413 $ref: '#/components/schemas/Account'
5415 example: [flowers, gardening]
5433 - https://peertube2.cpy.re/tracker/announce
5434 - wss://peertube2.cpy.re/tracker/socket
5438 $ref: '#/components/schemas/VideoFile'
5440 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5442 - field will be empty
5443 - video files will be found in `streamingPlaylists[].files` field
5447 $ref: '#/components/schemas/VideoStreamingPlaylists'
5449 HLS playlists/manifest files. If HLS is disabled on the server:
5451 - field will be empty
5452 - video files will be found in `files` field
5453 FileRedundancyInformation:
5456 $ref: '#/components/schemas/id'
5481 $ref: '#/components/schemas/id'
5488 $ref: '#/components/schemas/UUIDv4'
5495 $ref: '#/components/schemas/FileRedundancyInformation'
5499 $ref: '#/components/schemas/FileRedundancyInformation'
5500 VideoImportStateConstant:
5508 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5515 additionalProperties: false
5519 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5520 required: [targetUrl]
5523 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5524 required: [magnetUri]
5527 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5528 required: [torrentfile]
5529 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5538 - $ref: '#/components/schemas/id'
5542 description: remote URL where to find the import's source video
5543 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5547 description: magnet URI allowing to resolve the import's source video
5548 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5553 description: Torrent file containing only the video file
5560 - $ref: '#/components/schemas/VideoImportStateConstant'
5576 - $ref: '#/components/schemas/Video'
5586 $ref: '#/components/schemas/VideoImport'
5590 $ref: '#/components/schemas/id'
5593 example: The video is a spam
5597 $ref: '#/components/schemas/AbusePredefinedReasons'
5599 $ref: '#/components/schemas/Account'
5601 $ref: '#/components/schemas/AbuseStateConstant'
5604 example: Decided to ban the server since it spams us regularly
5608 $ref: '#/components/schemas/VideoInfo'
5615 $ref: '#/components/schemas/id'
5626 $ref: '#/components/schemas/AccountSummary'
5630 $ref: '#/components/schemas/id'
5632 $ref: '#/components/schemas/Video/properties/id'
5644 $ref: '#/components/schemas/UUIDv4'
5662 $ref: '#/components/schemas/id'
5664 $ref: '#/components/schemas/UUIDv4'
5667 - $ref: '#/components/schemas/shortUUID'
5690 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5692 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5694 $ref: '#/components/schemas/AccountSummary'
5696 $ref: '#/components/schemas/VideoChannelSummary'
5700 $ref: '#/components/schemas/id'
5707 description: Text of the comment
5709 example: This video is wonderful!
5711 $ref: '#/components/schemas/id'
5715 - $ref: '#/components/schemas/id'
5717 $ref: '#/components/schemas/Video/properties/id'
5732 totalRepliesFromVideoAuthor:
5739 $ref: '#/components/schemas/Account'
5740 VideoCommentThreadTree:
5743 $ref: '#/components/schemas/VideoComment'
5747 $ref: '#/components/schemas/VideoCommentThreadTree'
5751 $ref: '#/components/schemas/VideoConstantString-Language'
5767 $ref: '#/components/schemas/id'
5784 $ref: '#/components/schemas/id'
5789 description: immutable name of the actor, used to find or mention it
5791 - $ref: '#/components/schemas/username'
5795 description: server on which the actor is resident
5796 hostRedundancyAllowed:
5798 description: whether this actor's host allows redundancy of its videos
5802 description: number of actors subscribed to by this actor, as seen by this instance
5806 description: number of followers of this actor, as seen by this instance
5814 $ref: '#/components/schemas/ActorImage'
5817 - $ref: '#/components/schemas/Actor'
5820 description: object id for the user tied to this account
5822 - $ref: '#/components/schemas/User/properties/id'
5825 description: editable name of the account, displayed in its representations
5830 description: text or bio displayed on the account's profile
5836 description: timestamp within the video, in seconds
5903 allowedForCurrentIP:
5905 requiresEmailVerification:
5923 $ref: '#/components/schemas/VideoResolutionSet'
6008 example: 16810141515
6117 requiresEmailVerification:
6132 description: Settings that apply to new users, if registration is enabled
6136 example: 16810141515
6142 description: Settings pertaining to transcoding jobs
6146 allowAdditionalExtensions:
6148 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6151 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6154 description: Amount of threads used by ffmpeg for 1 transcoding job
6157 description: Amount of transcoding jobs to execute in parallel
6163 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6166 description: Resolutions to transcode _new videos_ to
6188 description: WebTorrent-specific settings
6194 description: HLS-specific settings
6244 $ref: '#/components/schemas/id'
6246 $ref: '#/components/schemas/Actor'
6248 $ref: '#/components/schemas/Actor'
6251 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6264 PredefinedAbuseReasons:
6265 description: Reason categories that help triage reports
6283 $ref: '#/components/schemas/id'
6295 - activitypub-http-unicast
6296 - activitypub-http-broadcast
6297 - activitypub-http-fetcher
6298 - activitypub-follow
6304 - activitypub-refresher
6308 additionalProperties: true
6311 additionalProperties: true
6327 $ref: '#/components/schemas/id'
6332 $ref: '#/components/schemas/id'
6333 VideoUploadRequestCommon:
6336 description: Video name
6338 example: What is PeerTube?
6342 description: Channel id that will contain this video
6347 $ref: '#/components/schemas/VideoPrivacySet'
6349 $ref: '#/components/schemas/VideoCategorySet'
6351 $ref: '#/components/schemas/VideoLicenceSet'
6353 $ref: '#/components/schemas/VideoLanguageSet'
6355 description: Video description
6358 **[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)**
6360 description: Whether or not we wait transcoding before publish the video
6363 description: A text tell the audience how to support the video creator
6364 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6367 description: Whether or not this video contains sensitive content
6370 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6383 description: Enable or disable comments for this video
6386 description: Enable or disable downloading for this video
6388 originallyPublishedAt:
6389 description: Date when the content was originally published
6393 $ref: '#/components/schemas/VideoScheduledUpdate'
6395 description: Video thumbnail file
6399 description: Video preview file
6405 VideoUploadRequestLegacy:
6407 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6413 description: Video file
6416 VideoUploadRequestResumable:
6418 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6424 description: Video filename including extension
6427 example: what_is_peertube.mp4
6429 description: Video thumbnail file
6433 description: Video preview file
6436 VideoUploadResponse:
6442 $ref: '#/components/schemas/Video/properties/id'
6444 $ref: '#/components/schemas/Video/properties/uuid'
6446 $ref: '#/components/schemas/Video/properties/shortUUID'
6447 CommentThreadResponse:
6456 $ref: '#/components/schemas/VideoComment'
6457 CommentThreadPostResponse:
6460 $ref: '#/components/schemas/VideoComment'
6470 $ref: '#/components/schemas/Video'
6474 $ref: '#/components/schemas/Account'
6477 description: Automatically start playing the upcoming video after the currently playing video
6478 autoPlayNextVideoPlaylist:
6480 description: Automatically start playing the video on the playlist after the currently playing video
6483 description: Automatically start playing the video on the watch page
6493 description: The user email
6496 description: Has the user confirmed their email address?
6499 - $ref: '#/components/schemas/id'
6503 description: Auth plugin to use to authenticate the user
6507 noInstanceConfigWarningModal:
6509 noAccountSetupWarningModal:
6514 $ref: '#/components/schemas/NSFWPolicy'
6516 $ref: '#/components/schemas/UserRole'
6525 description: Theme enabled by this user
6527 $ref: '#/components/schemas/username'
6531 $ref: '#/components/schemas/VideoChannel'
6534 description: The user video quota in bytes
6538 description: The user daily video quota in bytes
6542 description: Enable P2P in the player
6545 - $ref: '#/components/schemas/User'
6547 # optionally present fields: they require WITH_STATS scope
6550 description: Count of videos published
6553 description: Count of reports/abuses of which the user is a target
6554 abusesAcceptedCount:
6556 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6559 description: Count of reports/abuses created by the user
6562 description: Count of comments published
6566 $ref: '#/components/schemas/username'
6568 $ref: '#/components/schemas/password'
6572 description: The user email
6575 description: The user video quota in bytes
6579 description: The user daily video quota in bytes
6582 $ref: '#/components/schemas/usernameChannel'
6584 $ref: '#/components/schemas/UserRole'
6586 $ref: '#/components/schemas/UserAdminFlags'
6597 description: The updated email of the user
6599 - $ref: '#/components/schemas/User/properties/email'
6602 description: Set the email as verified
6605 description: The updated video quota of the user in bytes
6608 description: The updated daily video quota of the user in bytes
6612 description: The auth plugin to use to authenticate the user
6613 example: 'peertube-plugin-auth-saml2'
6615 $ref: '#/components/schemas/UserRole'
6617 $ref: '#/components/schemas/UserAdminFlags'
6619 # see shared/models/users/user-update-me.model.ts:
6622 $ref: '#/components/schemas/password'
6624 $ref: '#/components/schemas/password'
6626 description: new email used for login and service communications
6628 - $ref: '#/components/schemas/User/properties/email'
6631 description: new name of the user in its representations
6636 description: new NSFW display policy
6643 description: whether to enable P2P in the player or not
6646 description: new preference regarding playing videos automatically
6649 description: new preference regarding playing following videos automatically
6650 autoPlayNextVideoPlaylist:
6652 description: new preference regarding playing following playlist videos automatically
6653 videosHistoryEnabled:
6655 description: whether to keep track of watched history or not
6660 description: list of languages to filter videos down to
6663 noInstanceConfigWarningModal:
6665 noAccountSetupWarningModal:
6672 $ref: '#/components/schemas/id'
6679 description: Rating of the video
6686 $ref: '#/components/schemas/Video'
6693 description: Rating of the video
6700 description: immutable name of the user, used to find or mention its actor
6702 - $ref: '#/components/schemas/username'
6704 $ref: '#/components/schemas/password'
6708 description: email of the user, used for login or service communications
6711 description: editable name of the user, displayed in its representations
6716 description: channel base information used to create the first channel of the user
6719 $ref: '#/components/schemas/usernameChannel'
6721 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6731 pattern: /^[a-z0-9]$/
6734 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6737 pattern: /^[a-zA-Z0-9]$/
6740 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6741 OAuthToken-password:
6743 - $ref: '#/components/schemas/OAuthClient'
6753 $ref: '#/components/schemas/User/properties/username'
6755 $ref: '#/components/schemas/password'
6762 OAuthToken-refresh_token:
6764 - $ref: '#/components/schemas/OAuthClient'
6775 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6784 # GET/POST/PUT properties
6787 description: editable name of the channel, displayed in its representations
6788 example: Videos of Framasoft
6793 example: Videos made with <3 by Framasoft
6798 description: text shown by default on all videos of this channel, to tell the audience how to support it
6799 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6802 # GET-only properties
6806 - $ref: '#/components/schemas/id'
6822 $ref: '#/components/schemas/UUIDv4'
6825 - $ref: '#/components/schemas/VideoChannel'
6828 description: username of the channel to create
6830 - $ref: '#/components/schemas/usernameChannel'
6836 - $ref: '#/components/schemas/VideoChannel'
6838 bulkVideosSupportUpdate:
6840 description: Update the support field for all videos of this channel
6850 - $ref: '#/components/schemas/VideoChannel'
6851 - $ref: '#/components/schemas/Actor'
6856 name: 'media:peerLink'
6865 - application/x-bittorrent
6871 name: 'media:content'
6902 VideoCommentsForXML:
6937 description: video watch page URL
6940 description: video canonical URL
6944 description: video publication date
6947 description: video description
6950 description: video description
6953 description: publisher user name
6956 description: video category (MRSS)
6959 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6974 description: video embed path, relative to the canonical URL domain (MRSS)
6983 description: video watch path, relative to the canonical URL domain (MRSS)
7004 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7005 'media:description':
7012 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7015 description: main streamable file for the video
7025 - application/x-bittorrent
7034 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)
7037 - $ref: '#/components/schemas/MRSSPeerLink'
7038 - $ref: '#/components/schemas/MRSSGroupContent'
7039 NotificationSettingValue:
7056 $ref: '#/components/schemas/id'
7060 Notification type, following the `UserNotificationType` enum:
7062 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7064 - `2` NEW_COMMENT_ON_MY_VIDEO
7066 - `3` NEW_ABUSE_FOR_MODERATORS
7068 - `4` BLACKLIST_ON_MY_VIDEO
7070 - `5` UNBLACKLIST_ON_MY_VIDEO
7072 - `6` MY_VIDEO_PUBLISHED
7074 - `7` MY_VIDEO_IMPORT_SUCCESS
7076 - `8` MY_VIDEO_IMPORT_ERROR
7078 - `9` NEW_USER_REGISTRATION
7082 - `11` COMMENT_MENTION
7084 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7086 - `13` NEW_INSTANCE_FOLLOWER
7088 - `14` AUTO_INSTANCE_FOLLOWING
7094 - $ref: '#/components/schemas/VideoInfo'
7098 $ref: '#/components/schemas/ActorInfo'
7104 $ref: '#/components/schemas/id'
7107 $ref: '#/components/schemas/VideoInfo'
7112 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7122 $ref: '#/components/schemas/id'
7126 $ref: '#/components/schemas/VideoInfo'
7128 $ref: '#/components/schemas/ActorInfo'
7134 $ref: '#/components/schemas/id'
7137 - $ref: '#/components/schemas/VideoInfo'
7143 $ref: '#/components/schemas/id'
7146 - $ref: '#/components/schemas/VideoInfo'
7150 - $ref: '#/components/schemas/ActorInfo'
7156 $ref: '#/components/schemas/id'
7158 $ref: '#/components/schemas/ActorInfo'
7186 NotificationListResponse:
7195 $ref: '#/components/schemas/Notification'
7200 example: peertube-plugin-auth-ldap
7228 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7231 additionalProperties: true
7247 $ref: '#/components/schemas/Plugin'
7254 description: User can stream multiple times in a permanent live
7263 description: RTMP stream key to use to stream into this live video
7267 description: User can stream multiple times in a permanent live
7274 'https://search.example.org/api/v1/search/videos':
7276 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7279 description: successful operation
7283 $ref: '#/components/schemas/VideoListResponse'