6 name: PeerTube Community
7 url: https://joinpeertube.org
10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
92 "msg": "Invalid value",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
98 "title": "Bad Request",
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
108 ### Deprecated error fields
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
128 You can get details about the current state of your rate limit by reading the
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
144 |------------------------- ---|
148 | `/live/segments-sha256/*` |
149 | `/.well-known/webfinger` |
151 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
153 url: https://docs.joinpeertube.org/api-rest-reference.html
157 As a visitor, you can use this API to open an account (if registrations are open on
158 that PeerTube instance). As an admin, you should use the dedicated [User creation
159 API](#operation/addUser) instead.
161 x-displayName: Login/Logout
163 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
166 Accounts encompass remote accounts discovered across the federation,
167 and correspond to the main Actor, along with video channels a user can create, which
170 When a comment is posted, it is done with your Account's Actor.
173 Using some features of PeerTube require authentication, for which User
174 provide different levels of permission as well as associated user
175 information. Each user has a corresponding local Account for federation.
178 Operations related to your own User, when logged-in.
179 - name: My Subscriptions
181 Operations related to your subscriptions to video channels, their
182 new videos, and how to keep up to date with their latest publications!
185 Operations related to your watch history.
186 - name: My Notifications
188 Notifications following new videos, follows or reports. They allow you
189 to keep track of the interactions and overall important information that
190 concerns you. You MAY set per-notification type delivery preference, to
191 receive the info either by mail, by in-browser notification or both.
194 Each server exposes public information regarding supported videos and
198 Jobs are long-running tasks enqueued and processed by the instance
199 itself. No additional worker registration is currently available.
200 - name: Instance Follows
202 Managing servers which the instance interacts with is crucial to the
203 concept of federation in PeerTube and external video indexation. The PeerTube
204 server then deals with inter-server ActivityPub operations and propagates
205 information across its social graph by posting activities to actors' inbox
208 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
209 - name: Instance Redundancy
211 Redundancy is part of the inter-server solidarity that PeerTube fosters.
212 Manage the list of instances you wish to help by seeding their videos according
213 to the policy of video selection of your choice. Note that you have a similar functionality
214 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
216 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
219 Managing plugins installed from a local path or from NPM, or search for new ones.
221 url: https://docs.joinpeertube.org/api-plugins
224 Abuses deal with reports of local or remote videos/comments/accounts alike.
227 Operations dealing with listing, uploading, fetching or modifying videos.
230 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
234 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
235 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
237 You can upload videos more reliably by using the resumable variant. Its protocol lets
238 you resume an upload operation after a network interruption or other transmission failure,
239 saving time and bandwidth in the event of network failures.
241 Favor using resumable uploads in any of the following cases:
242 - You are transferring large files
243 - The likelihood of a network interruption is high
244 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
245 such as a mobile device
249 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
250 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
253 The import function is practical when the desired video/audio is available online. It makes PeerTube
254 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
255 - name: Video Captions
256 description: Operations dealing with listing, adding and removing closed captions of a video.
257 - name: Video Channels
258 description: Operations dealing with the creation, modification and listing of videos within a channel.
259 - name: Video Comments
261 Operations dealing with comments to a video. Comments are organized in threads: adding a
262 comment in response to the video starts a thread, adding a reply to a comment adds it to
263 its root comment thread.
265 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
267 description: Like/dislike a video.
268 - name: Video Playlists
269 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
271 description: Server syndication feeds
274 The search helps to find _videos_ or _channels_ from within the instance and beyond.
275 Videos from other instances federated by the instance (that is, instances
276 followed by the instance) can be found via keywords and other criteria of
279 Administrators can also enable the use of a remote search system, indexing
280 videos and channels not could be not federated by the instance.
282 description: Get and update the custom homepage
283 - name: Video Mirroring
285 PeerTube instances can mirror videos from one another, and help distribute some videos.
287 For importing videos as your own, refer to [video imports](#operation/importVideo).
310 - Video Ownership Change
326 - name: Instance Configuration
330 - Instance Redundancy
340 summary: Get an account
341 operationId: getAccount
343 - $ref: '#/components/parameters/name'
346 description: successful operation
350 $ref: '#/components/schemas/Account'
352 description: account not found
354 '/accounts/{name}/videos':
359 summary: 'List videos of an account'
360 operationId: getAccountVideos
362 - $ref: '#/components/parameters/name'
363 - $ref: '#/components/parameters/categoryOneOf'
364 - $ref: '#/components/parameters/isLive'
365 - $ref: '#/components/parameters/tagsOneOf'
366 - $ref: '#/components/parameters/tagsAllOf'
367 - $ref: '#/components/parameters/licenceOneOf'
368 - $ref: '#/components/parameters/languageOneOf'
369 - $ref: '#/components/parameters/nsfw'
370 - $ref: '#/components/parameters/filter'
371 - $ref: '#/components/parameters/skipCount'
372 - $ref: '#/components/parameters/start'
373 - $ref: '#/components/parameters/count'
374 - $ref: '#/components/parameters/videosSort'
377 description: successful operation
381 $ref: '#/components/schemas/VideoListResponse'
385 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
386 .then(function(response) {
387 return response.json()
388 }).then(function(data) {
394 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
400 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
402 http = Net::HTTP.new(uri.host, uri.port)
405 response = http.get(uri.request_uri)
407 puts JSON.parse(response.read_body)
412 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
421 summary: List accounts
422 operationId: getAccounts
424 - $ref: '#/components/parameters/start'
425 - $ref: '#/components/parameters/count'
426 - $ref: '#/components/parameters/sort'
429 description: successful operation
435 $ref: '#/components/schemas/Account'
441 summary: Get instance public configuration
442 operationId: getConfig
445 description: successful operation
449 $ref: '#/components/schemas/ServerConfig'
452 externalValue: https://peertube2.cpy.re/api/v1/config
456 summary: Get instance "About" information
457 operationId: getAbout
462 description: successful operation
466 $ref: '#/components/schemas/ServerConfigAbout'
469 externalValue: https://peertube2.cpy.re/api/v1/config/about
473 summary: Get instance runtime configuration
474 operationId: getCustomConfig
482 description: successful operation
486 $ref: '#/components/schemas/ServerConfigCustom'
488 summary: Set instance runtime configuration
489 operationId: putCustomConfig
497 description: successful operation
499 x-summary: field inconsistencies
502 - the emailer is disabled and the instance is open to registrations
503 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
505 summary: Delete instance runtime configuration
506 operationId: delCustomConfig
514 description: successful operation
516 /custom-pages/homepage/instance:
518 summary: Get instance custom homepage
523 description: No homepage set
525 description: successful operation
529 $ref: '#/components/schemas/CustomHomepage'
531 summary: Set instance custom homepage
545 description: content of the homepage, that will be injected in the client
548 description: successful operation
552 summary: List instance jobs
563 description: The state of the job ('' for for no filter)
573 - $ref: '#/components/parameters/jobType'
574 - $ref: '#/components/parameters/start'
575 - $ref: '#/components/parameters/count'
576 - $ref: '#/components/parameters/sort'
579 description: successful operation
592 $ref: '#/components/schemas/Job'
598 summary: List instances following the server
600 - $ref: '#/components/parameters/followState'
601 - $ref: '#/components/parameters/actorType'
602 - $ref: '#/components/parameters/start'
603 - $ref: '#/components/parameters/count'
604 - $ref: '#/components/parameters/sort'
607 description: successful operation
619 $ref: '#/components/schemas/Follow'
621 '/server/followers/{nameWithHost}':
623 summary: Remove or reject a follower to your server
633 description: The remote actor handle to remove from your followers
639 description: successful operation
641 description: follower not found
643 '/server/followers/{nameWithHost}/reject':
645 summary: Reject a pending follower to your server
655 description: The remote actor handle to remove from your followers
661 description: successful operation
663 description: follower not found
665 '/server/followers/{nameWithHost}/accept':
667 summary: Accept a pending follower to your server
677 description: The remote actor handle to remove from your followers
683 description: successful operation
685 description: follower not found
691 summary: List instances followed by the server
693 - $ref: '#/components/parameters/followState'
694 - $ref: '#/components/parameters/actorType'
695 - $ref: '#/components/parameters/start'
696 - $ref: '#/components/parameters/count'
697 - $ref: '#/components/parameters/sort'
700 description: successful operation
712 $ref: '#/components/schemas/Follow'
719 summary: Follow a list of actors (PeerTube instance, channel or account)
722 description: successful operation
724 description: cannot follow a non-HTTPS server
743 '/server/following/{hostOrHandle}':
745 summary: Unfollow an actor (PeerTube instance, channel or account)
755 description: The hostOrHandle to unfollow
760 description: successful operation
762 description: host or handle not found
766 summary: Create a user
775 description: user created
779 $ref: '#/components/schemas/AddUserResponse'
785 id: '$response.body#/user/id'
790 id: '$response.body#/user/id'
795 id: '$response.body#/user/id'
797 description: insufficient authority to create an admin or moderator
802 $ref: '#/components/schemas/AddUser'
804 If the smtp server is configured, you can leave the password empty and an email will be sent
805 asking the user to set it first.
809 operationId: getUsers
816 - $ref: '#/components/parameters/usersSearch'
817 - $ref: '#/components/parameters/usersBlocked'
818 - $ref: '#/components/parameters/start'
819 - $ref: '#/components/parameters/count'
820 - $ref: '#/components/parameters/usersSort'
823 description: successful operation
829 $ref: '#/components/schemas/User'
833 - $ref: '#/components/parameters/id'
835 summary: Delete a user
844 description: successful operation
855 description: include statistics about the user (only available as a moderator/admin)
860 x-summary: successful operation
862 As an admin/moderator, you can request a response augmented with statistics about the user's
863 moderation relations and videos usage, by using the `withStats` parameter.
868 - $ref: '#/components/schemas/User'
869 - $ref: '#/components/schemas/UserWithStats'
871 summary: Update a user
879 description: successful operation
884 $ref: '#/components/schemas/UpdateUser'
887 /oauth-clients/local:
889 summary: Login prerequisite
890 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
891 operationId: getOAuthClient
896 description: successful operation
900 $ref: '#/components/schemas/OAuthClient'
902 UseOAuthClientToLogin:
903 operationId: getOAuthToken
905 client_id: '$response.body#/client_id'
906 client_secret: '$response.body#/client_secret'
910 API="https://peertube2.cpy.re/api/v1"
913 curl -s "$API/oauth-clients/local"
918 operationId: getOAuthToken
919 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
924 application/x-www-form-urlencoded:
927 - $ref: '#/components/schemas/OAuthToken-password'
928 - $ref: '#/components/schemas/OAuthToken-refresh_token'
930 propertyName: grant_type
932 password: '#/components/schemas/OAuthToken-password'
933 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
936 description: successful operation
947 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
948 description: valid for 1 day
951 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
952 description: valid for 2 weeks
957 refresh_token_expires_in:
962 x-summary: client or credentials are invalid
964 Disambiguate via `type`:
965 - `invalid_client` for an unmatched `client_id`
966 - `invalid_grant` for unmatched credentials
968 x-summary: token expired
970 Disambiguate via `type`:
971 - default value for a regular authentication failure
972 - `invalid_token` for an expired token
977 API="https://peertube2.cpy.re/api/v1"
978 USERNAME="<your_username>"
979 PASSWORD="<your_password>"
982 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
983 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
984 curl -s "$API/users/token" \
985 --data client_id="$client_id" \
986 --data client_secret="$client_secret" \
987 --data grant_type=password \
988 --data username="$USERNAME" \
989 --data password="$PASSWORD" \
990 | jq -r ".access_token"
995 description: Revokes your access token and its associated refresh token, destroying your current session.
996 operationId: revokeOAuthToken
1003 description: successful operation
1007 summary: Register a user
1008 operationId: registerUser
1014 description: successful operation
1019 $ref: '#/components/schemas/RegisterUser'
1022 /users/{id}/verify-email:
1024 summary: Verify a user
1025 operationId: verifyUser
1027 Following a user registration, the new user will receive an email asking to click a link
1028 containing a secret.
1033 - $ref: '#/components/parameters/id'
1046 - verificationString
1049 description: successful operation
1051 description: invalid verification string
1053 description: user not found
1055 /users/ask-send-verify-email:
1057 summary: Resend user verification link
1058 operationId: resendEmailToVerifyUser
1064 description: successful operation
1068 summary: Get my user information
1069 operationId: getUserInfo
1077 description: successful operation
1083 $ref: '#/components/schemas/User'
1085 summary: Update my user information
1086 operationId: putUserInfo
1094 description: successful operation
1099 $ref: '#/components/schemas/UpdateMe'
1102 /users/me/videos/imports:
1104 summary: Get video imports of my user
1112 - $ref: '#/components/parameters/start'
1113 - $ref: '#/components/parameters/count'
1114 - $ref: '#/components/parameters/sort'
1117 description: successful operation
1121 $ref: '#/components/schemas/VideoImportsList'
1123 /users/me/video-quota-used:
1125 summary: Get my user used quota
1133 description: successful operation
1141 description: The user video quota used so far in bytes
1142 example: 16810141515
1143 videoQuotaUsedDaily:
1145 description: The user video quota used today in bytes
1148 '/users/me/videos/{videoId}/rating':
1150 summary: Get rate of my user for a video
1160 description: The video id
1162 $ref: '#/components/schemas/Video/properties/id'
1165 description: successful operation
1169 $ref: '#/components/schemas/GetMeVideoRating'
1173 summary: Get videos of my user
1181 - $ref: '#/components/parameters/start'
1182 - $ref: '#/components/parameters/count'
1183 - $ref: '#/components/parameters/sort'
1186 description: successful operation
1190 $ref: '#/components/schemas/VideoListResponse'
1192 /users/me/subscriptions:
1194 summary: Get my user subscriptions
1201 - $ref: '#/components/parameters/start'
1202 - $ref: '#/components/parameters/count'
1203 - $ref: '#/components/parameters/sort'
1206 description: successful operation
1210 $ref: '#/components/schemas/VideoChannelList'
1214 summary: Add subscription to my user
1227 description: uri of the video channels to subscribe to
1233 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1236 description: successful operation
1238 /users/me/subscriptions/exist:
1240 summary: Get if subscriptions exist for my user
1247 - $ref: '#/components/parameters/subscriptionsUris'
1250 description: successful operation
1256 /users/me/subscriptions/videos:
1258 summary: List videos of subscriptions of my user
1266 - $ref: '#/components/parameters/categoryOneOf'
1267 - $ref: '#/components/parameters/isLive'
1268 - $ref: '#/components/parameters/tagsOneOf'
1269 - $ref: '#/components/parameters/tagsAllOf'
1270 - $ref: '#/components/parameters/licenceOneOf'
1271 - $ref: '#/components/parameters/languageOneOf'
1272 - $ref: '#/components/parameters/nsfw'
1273 - $ref: '#/components/parameters/filter'
1274 - $ref: '#/components/parameters/skipCount'
1275 - $ref: '#/components/parameters/start'
1276 - $ref: '#/components/parameters/count'
1277 - $ref: '#/components/parameters/videosSort'
1280 description: successful operation
1284 $ref: '#/components/schemas/VideoListResponse'
1286 '/users/me/subscriptions/{subscriptionHandle}':
1288 summary: Get subscription of my user
1295 - $ref: '#/components/parameters/subscriptionHandle'
1298 description: successful operation
1302 $ref: '#/components/schemas/VideoChannel'
1304 summary: Delete subscription of my user
1311 - $ref: '#/components/parameters/subscriptionHandle'
1314 description: successful operation
1316 /users/me/notifications:
1318 summary: List my notifications
1326 description: only list unread notifications
1329 - $ref: '#/components/parameters/start'
1330 - $ref: '#/components/parameters/count'
1331 - $ref: '#/components/parameters/sort'
1334 description: successful operation
1338 $ref: '#/components/schemas/NotificationListResponse'
1340 /users/me/notifications/read:
1342 summary: Mark notifications as read by their id
1355 description: ids of the notifications to mark as read
1362 description: successful operation
1364 /users/me/notifications/read-all:
1366 summary: Mark all my notification as read
1373 description: successful operation
1375 /users/me/notification-settings:
1377 summary: Update my notification settings
1388 newVideoFromSubscription:
1389 $ref: '#/components/schemas/NotificationSettingValue'
1390 newCommentOnMyVideo:
1391 $ref: '#/components/schemas/NotificationSettingValue'
1393 $ref: '#/components/schemas/NotificationSettingValue'
1394 videoAutoBlacklistAsModerator:
1395 $ref: '#/components/schemas/NotificationSettingValue'
1397 $ref: '#/components/schemas/NotificationSettingValue'
1399 $ref: '#/components/schemas/NotificationSettingValue'
1400 myVideoImportFinished:
1401 $ref: '#/components/schemas/NotificationSettingValue'
1403 $ref: '#/components/schemas/NotificationSettingValue'
1404 newUserRegistration:
1405 $ref: '#/components/schemas/NotificationSettingValue'
1407 $ref: '#/components/schemas/NotificationSettingValue'
1408 newInstanceFollower:
1409 $ref: '#/components/schemas/NotificationSettingValue'
1410 autoInstanceFollowing:
1411 $ref: '#/components/schemas/NotificationSettingValue'
1414 description: successful operation
1416 /users/me/history/videos:
1418 summary: List watched videos history
1424 - $ref: '#/components/parameters/start'
1425 - $ref: '#/components/parameters/count'
1426 - $ref: '#/components/parameters/search'
1429 description: successful operation
1433 $ref: '#/components/schemas/VideoListResponse'
1435 /users/me/history/videos/remove:
1437 summary: Clear video history
1444 multipart/form-data:
1449 description: history before this date will be deleted
1454 description: successful operation
1456 /users/me/avatar/pick:
1458 summary: Update my user avatar
1465 description: successful operation
1472 $ref: '#/components/schemas/ActorImage'
1474 description: image file too large
1476 X-File-Maximum-Size:
1480 description: Maximum file size for the avatar
1483 multipart/form-data:
1488 description: The file to upload
1493 contentType: image/png, image/jpeg
1497 summary: Delete my avatar
1504 description: successful operation
1508 summary: List video ownership changes
1510 - Video Ownership Change
1515 description: successful operation
1517 '/videos/ownership/{id}/accept':
1519 summary: Accept ownership change request
1521 - Video Ownership Change
1525 - $ref: '#/components/parameters/idOrUUID'
1528 description: successful operation
1530 description: cannot terminate an ownership change of another user
1532 description: video owneship change not found
1534 '/videos/ownership/{id}/refuse':
1536 summary: Refuse ownership change request
1538 - Video Ownership Change
1542 - $ref: '#/components/parameters/idOrUUID'
1545 description: successful operation
1547 description: cannot terminate an ownership change of another user
1549 description: video owneship change not found
1551 '/videos/{id}/give-ownership':
1553 summary: Request ownership change
1555 - Video Ownership Change
1559 - $ref: '#/components/parameters/idOrUUID'
1563 application/x-www-form-urlencoded:
1573 description: successful operation
1575 description: changing video ownership to a remote account is not supported yet
1577 description: video not found
1581 summary: List videos
1582 operationId: getVideos
1586 - $ref: '#/components/parameters/categoryOneOf'
1587 - $ref: '#/components/parameters/isLive'
1588 - $ref: '#/components/parameters/tagsOneOf'
1589 - $ref: '#/components/parameters/tagsAllOf'
1590 - $ref: '#/components/parameters/licenceOneOf'
1591 - $ref: '#/components/parameters/languageOneOf'
1592 - $ref: '#/components/parameters/nsfw'
1593 - $ref: '#/components/parameters/filter'
1594 - $ref: '#/components/parameters/skipCount'
1595 - $ref: '#/components/parameters/start'
1596 - $ref: '#/components/parameters/count'
1597 - $ref: '#/components/parameters/videosSort'
1600 description: successful operation
1604 $ref: '#/components/schemas/VideoListResponse'
1608 summary: List available video categories
1609 operationId: getCategories
1614 description: successful operation
1623 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1627 summary: List available video licences
1628 operationId: getLicences
1633 description: successful operation
1642 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1646 summary: List available video languages
1647 operationId: getLanguages
1652 description: successful operation
1661 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1665 summary: List available video privacy policies
1666 operationId: getPrivacyPolicies
1671 description: successful operation
1680 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1684 summary: Update a video
1685 operationId: putVideo
1691 - $ref: '#/components/parameters/idOrUUID'
1694 description: successful operation
1697 multipart/form-data:
1702 description: Video thumbnail file
1706 description: Video preview file
1710 $ref: '#/components/schemas/VideoCategorySet'
1712 $ref: '#/components/schemas/VideoLicenceSet'
1714 $ref: '#/components/schemas/VideoLanguageSet'
1716 $ref: '#/components/schemas/VideoPrivacySet'
1718 description: Video description
1721 description: Whether or not we wait transcoding before publish the video
1724 description: A text tell the audience how to support the video creator
1725 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1728 description: Whether or not this video contains sensitive content
1731 description: Video name
1736 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1745 description: Enable or disable comments for this video
1748 description: Enable or disable downloading for this video
1750 originallyPublishedAt:
1751 description: Date when the content was originally published
1755 $ref: '#/components/schemas/VideoScheduledUpdate'
1758 contentType: image/jpeg
1760 contentType: image/jpeg
1762 summary: Get a video
1763 operationId: getVideo
1767 - $ref: '#/components/parameters/idOrUUID'
1770 description: successful operation
1774 $ref: '#/components/schemas/VideoDetails'
1776 summary: Delete a video
1777 operationId: delVideo
1783 - $ref: '#/components/parameters/idOrUUID'
1786 description: successful operation
1788 '/videos/{id}/description':
1790 summary: Get complete video description
1791 operationId: getVideoDesc
1795 - $ref: '#/components/parameters/idOrUUID'
1798 description: successful operation
1807 **[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)**
1809 '/videos/{id}/views':
1811 summary: Add a view to a video
1812 operationId: addView
1816 - $ref: '#/components/parameters/idOrUUID'
1819 description: successful operation
1821 '/videos/{id}/watching':
1823 summary: Set watching progress of a video
1824 operationId: setProgress
1830 - $ref: '#/components/parameters/idOrUUID'
1835 $ref: '#/components/schemas/UserWatchingVideo'
1839 description: successful operation
1843 summary: Upload a video
1844 description: Uses a single request to upload a video.
1845 operationId: uploadLegacy
1853 description: successful operation
1857 $ref: '#/components/schemas/VideoUploadResponse'
1859 description: video didn't pass upload filter
1861 description: upload has timed out
1863 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1865 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1866 - `quota_reached` for quota limits wether daily or global
1868 X-File-Maximum-Size:
1872 description: Maximum file size for the video
1874 description: video type unsupported
1876 description: video unreadable
1879 multipart/form-data:
1881 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1884 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1886 contentType: image/jpeg
1888 contentType: image/jpeg
1893 USERNAME="<your_username>"
1894 PASSWORD="<your_password>"
1895 FILE_PATH="<your_file_path>"
1896 CHANNEL_ID="<your_channel_id>"
1898 API="https://peertube2.cpy.re/api/v1"
1901 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1902 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1903 token=$(curl -s "$API/users/token" \
1904 --data client_id="$client_id" \
1905 --data client_secret="$client_secret" \
1906 --data grant_type=password \
1907 --data username="$USERNAME" \
1908 --data password="$PASSWORD" \
1909 | jq -r ".access_token")
1912 curl -s "$API/videos/upload" \
1913 -H "Authorization: Bearer $token" \
1915 --form videofile=@"$FILE_PATH" \
1916 --form channelId=$CHANNEL_ID \
1919 /videos/upload-resumable:
1921 summary: Initialize the resumable upload of a video
1922 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1923 operationId: uploadResumableInit
1930 - name: X-Upload-Content-Length
1936 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1937 - name: X-Upload-Content-Type
1944 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1949 $ref: '#/components/schemas/VideoUploadRequestResumable'
1952 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1954 description: created
1960 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1966 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1968 Disambiguate via `type`:
1969 - `max_file_size_reached` for the absolute file size limit
1970 - `quota_reached` for quota limits whether daily or global
1972 description: video type unsupported
1974 summary: Send chunk for the resumable upload of a video
1975 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
1976 operationId: uploadResumable
1987 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1988 not valid anymore and you need to initialize a new upload.
1991 - name: Content-Range
1995 example: bytes 0-262143/2469036
1998 Specifies the bytes in the file that the request is uploading.
2000 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2001 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2002 - name: Content-Length
2009 Size of the chunk that the request is sending.
2011 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)
2012 doesn't mandate for chunks to have the same size throughout the upload sequence.
2014 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2015 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2018 application/octet-stream:
2024 description: last chunk received
2032 $ref: '#/components/schemas/VideoUploadResponse'
2034 description: resume incomplete
2039 example: bytes=0-262143
2045 description: video didn't pass upload filter
2047 description: upload not found
2049 description: chunk doesn't match range
2051 description: video unreadable
2053 description: too many concurrent requests
2055 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2056 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2057 operationId: uploadResumableCancel
2068 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2069 not valid anymore and the upload session has already been deleted with its data ;-)
2072 - name: Content-Length
2080 description: upload cancelled
2087 description: upload not found
2091 summary: Import a video
2092 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2093 operationId: importVideo
2101 multipart/form-data:
2103 $ref: '#/components/schemas/VideoCreateImport'
2106 contentType: application/x-bittorrent
2108 contentType: image/jpeg
2110 contentType: image/jpeg
2113 description: successful operation
2117 $ref: '#/components/schemas/VideoUploadResponse'
2119 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2121 description: video didn't pass pre-import filter
2123 description: HTTP or Torrent/magnetURI import not enabled
2127 summary: Create a live
2128 operationId: addLive
2136 description: successful operation
2140 $ref: '#/components/schemas/VideoUploadResponse'
2142 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2144 Disambiguate via `type`:
2145 - default type for a validation error
2146 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2148 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2150 Disambiguate via `type`:
2151 - `live_not_enabled` for a disabled live feature
2152 - `live_not_allowing_replay` for a disabled replay feature
2153 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2154 - `max_user_lives_limit_reached` for the user concurrent live limit
2157 multipart/form-data:
2162 description: Channel id that will contain this live video
2167 description: User can stream multiple times in a permanent live
2170 description: Live video/replay thumbnail file
2174 description: Live video/replay preview file
2178 $ref: '#/components/schemas/VideoPrivacySet'
2180 $ref: '#/components/schemas/VideoCategorySet'
2182 $ref: '#/components/schemas/VideoLicenceSet'
2184 $ref: '#/components/schemas/VideoLanguageSet'
2186 description: Live video/replay description
2189 description: A text tell the audience how to support the creator
2190 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2193 description: Whether or not this live video/replay contains sensitive content
2196 description: Live video/replay name
2201 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2210 description: Enable or disable comments for this live video/replay
2213 description: Enable or disable downloading for the replay of this live video
2220 contentType: image/jpeg
2222 contentType: image/jpeg
2226 summary: Get information about a live
2227 operationId: getLiveId
2234 - $ref: '#/components/parameters/idOrUUID'
2237 description: successful operation
2241 $ref: '#/components/schemas/LiveVideoResponse'
2243 summary: Update information about a live
2244 operationId: updateLiveId
2251 - $ref: '#/components/parameters/idOrUUID'
2256 $ref: '#/components/schemas/LiveVideoUpdate'
2259 description: successful operation
2261 description: bad parameters or trying to update a live that has already started
2263 description: trying to save replay of the live but saving replay is not enabled on the instance
2267 summary: List my abuses
2268 operationId: getMyAbuses
2277 description: only list the report with this id
2283 $ref: '#/components/schemas/AbuseStateSet'
2284 - $ref: '#/components/parameters/abusesSort'
2285 - $ref: '#/components/parameters/start'
2286 - $ref: '#/components/parameters/count'
2289 description: successful operation
2301 $ref: '#/components/schemas/Abuse'
2305 summary: List abuses
2306 operationId: getAbuses
2316 description: only list the report with this id
2319 - name: predefinedReason
2321 description: predefined reason the listed reports should contain
2323 $ref: '#/components/schemas/PredefinedAbuseReasons'
2326 description: plain search that will match with video titles, reporter names and more
2332 $ref: '#/components/schemas/AbuseStateSet'
2333 - name: searchReporter
2335 description: only list reports of a specific reporter
2338 - name: searchReportee
2339 description: only list reports of a specific reportee
2345 description: only list reports of a specific video
2348 - name: searchVideoChannel
2350 description: only list reports of a specific video channel
2355 description: only list deleted or blocklisted videos
2363 description: only list account, comment or video reports
2370 - $ref: '#/components/parameters/start'
2371 - $ref: '#/components/parameters/count'
2372 - $ref: '#/components/parameters/abusesSort'
2375 description: successful operation
2387 $ref: '#/components/schemas/Abuse'
2389 summary: Report an abuse
2402 description: Reason why the user reports this video
2407 $ref: '#/components/schemas/PredefinedAbuseReasons'
2412 description: Video id to report
2414 - $ref: '#/components/schemas/Video/properties/id'
2418 description: Timestamp in the video that marks the beginning of the report
2423 description: Timestamp in the video that marks the ending of the report
2429 description: Comment id to report
2431 - $ref: '#/components/schemas/VideoComment/properties/id'
2436 description: Account id to report
2442 description: successful operation
2452 $ref: '#/components/schemas/id'
2454 description: incorrect request parameters
2456 '/abuses/{abuseId}':
2458 summary: Update an abuse
2466 - $ref: '#/components/parameters/abuseId'
2474 $ref: '#/components/schemas/AbuseStateSet'
2477 description: Update the report comment visible only to the moderation team
2482 description: successful operation
2484 description: abuse not found
2488 summary: Delete an abuse
2494 - $ref: '#/components/parameters/abuseId'
2497 description: successful operation
2499 description: block not found
2501 '/abuses/{abuseId}/messages':
2503 summary: List messages of an abuse
2509 - $ref: '#/components/parameters/abuseId'
2512 description: successful operation
2524 $ref: '#/components/schemas/AbuseMessage'
2526 summary: Add message to an abuse
2532 - $ref: '#/components/parameters/abuseId'
2541 description: Message to send
2549 description: successful operation
2551 description: incorrect request parameters
2553 '/abuses/{abuseId}/messages/{abuseMessageId}':
2555 summary: Delete an abuse message
2561 - $ref: '#/components/parameters/abuseId'
2562 - $ref: '#/components/parameters/abuseMessageId'
2565 description: successful operation
2567 '/videos/{id}/blacklist':
2569 summary: Block a video
2570 operationId: addVideoBlock
2578 - $ref: '#/components/parameters/idOrUUID'
2581 description: successful operation
2583 summary: Unblock a video by its id
2584 operationId: delVideoBlock
2592 - $ref: '#/components/parameters/idOrUUID'
2595 description: successful operation
2597 description: block not found
2603 summary: List video blocks
2604 operationId: getVideoBlocks
2613 list only blocks that match this type:
2617 - `2`: automatic block that needs review
2625 description: plain search that will match with video titles, and more
2628 - $ref: '#/components/parameters/start'
2629 - $ref: '#/components/parameters/count'
2630 - $ref: '#/components/parameters/blacklistsSort'
2633 description: successful operation
2645 $ref: '#/components/schemas/VideoBlacklist'
2647 /videos/{id}/captions:
2649 summary: List captions of a video
2650 operationId: getVideoCaptions
2654 - $ref: '#/components/parameters/idOrUUID'
2657 description: successful operation
2669 $ref: '#/components/schemas/VideoCaption'
2671 /videos/{id}/captions/{captionLanguage}:
2673 summary: Add or replace a video caption
2674 operationId: addVideoCaption
2681 - $ref: '#/components/parameters/idOrUUID'
2682 - $ref: '#/components/parameters/captionLanguage'
2685 multipart/form-data:
2690 description: The file to upload.
2695 contentType: text/vtt, application/x-subrip, text/plain
2698 description: successful operation
2700 description: video or language not found
2702 summary: Delete a video caption
2703 operationId: delVideoCaption
2710 - $ref: '#/components/parameters/idOrUUID'
2711 - $ref: '#/components/parameters/captionLanguage'
2714 description: successful operation
2716 description: video or language or caption for that language not found
2720 summary: List video channels
2721 operationId: getVideoChannels
2725 - $ref: '#/components/parameters/start'
2726 - $ref: '#/components/parameters/count'
2727 - $ref: '#/components/parameters/sort'
2730 description: successful operation
2734 $ref: '#/components/schemas/VideoChannelList'
2736 summary: Create a video channel
2737 operationId: addVideoChannel
2744 description: successful operation
2754 $ref: '#/components/schemas/VideoChannel/properties/id'
2759 $ref: '#/components/schemas/VideoChannelCreate'
2761 '/video-channels/{channelHandle}':
2763 summary: Get a video channel
2764 operationId: getVideoChannel
2768 - $ref: '#/components/parameters/channelHandle'
2771 description: successful operation
2775 $ref: '#/components/schemas/VideoChannel'
2777 summary: Update a video channel
2778 operationId: putVideoChannel
2784 - $ref: '#/components/parameters/channelHandle'
2787 description: successful operation
2792 $ref: '#/components/schemas/VideoChannelUpdate'
2794 summary: Delete a video channel
2795 operationId: delVideoChannel
2801 - $ref: '#/components/parameters/channelHandle'
2804 description: successful operation
2806 '/video-channels/{channelHandle}/videos':
2808 summary: List videos of a video channel
2809 operationId: getVideoChannelVideos
2814 - $ref: '#/components/parameters/channelHandle'
2815 - $ref: '#/components/parameters/categoryOneOf'
2816 - $ref: '#/components/parameters/isLive'
2817 - $ref: '#/components/parameters/tagsOneOf'
2818 - $ref: '#/components/parameters/tagsAllOf'
2819 - $ref: '#/components/parameters/licenceOneOf'
2820 - $ref: '#/components/parameters/languageOneOf'
2821 - $ref: '#/components/parameters/nsfw'
2822 - $ref: '#/components/parameters/filter'
2823 - $ref: '#/components/parameters/skipCount'
2824 - $ref: '#/components/parameters/start'
2825 - $ref: '#/components/parameters/count'
2826 - $ref: '#/components/parameters/videosSort'
2829 description: successful operation
2833 $ref: '#/components/schemas/VideoListResponse'
2835 '/video-channels/{channelHandle}/avatar/pick':
2837 summary: Update channel avatar
2843 - $ref: '#/components/parameters/channelHandle'
2846 description: successful operation
2853 $ref: '#/components/schemas/ActorImage'
2855 description: image file too large
2857 X-File-Maximum-Size:
2861 description: Maximum file size for the avatar
2864 multipart/form-data:
2869 description: The file to upload.
2874 contentType: image/png, image/jpeg
2876 '/video-channels/{channelHandle}/avatar':
2878 summary: Delete channel avatar
2884 - $ref: '#/components/parameters/channelHandle'
2887 description: successful operation
2889 '/video-channels/{channelHandle}/banner/pick':
2891 summary: Update channel banner
2897 - $ref: '#/components/parameters/channelHandle'
2900 description: successful operation
2907 $ref: '#/components/schemas/ActorImage'
2909 description: image file too large
2911 X-File-Maximum-Size:
2915 description: Maximum file size for the banner
2918 multipart/form-data:
2923 description: The file to upload.
2928 contentType: image/png, image/jpeg
2930 '/video-channels/{channelHandle}/banner':
2932 summary: Delete channel banner
2938 - $ref: '#/components/parameters/channelHandle'
2941 description: successful operation
2943 /video-playlists/privacies:
2945 summary: List available playlist privacy policies
2946 operationId: getPlaylistPrivacyPolicies
2951 description: successful operation
2960 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2964 summary: List video playlists
2965 operationId: getPlaylists
2969 - $ref: '#/components/parameters/start'
2970 - $ref: '#/components/parameters/count'
2971 - $ref: '#/components/parameters/sort'
2974 description: successful operation
2986 $ref: '#/components/schemas/VideoPlaylist'
2988 summary: Create a video playlist
2989 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2990 operationId: addPlaylist
2997 description: successful operation
3007 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3009 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3011 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3014 multipart/form-data:
3019 description: Video playlist display name
3024 description: Video playlist thumbnail file
3028 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3030 description: Video playlist description
3036 - $ref: '#/components/schemas/id'
3037 description: Video channel in which the playlist will be published
3042 contentType: image/jpeg
3044 /video-playlists/{playlistId}:
3046 summary: Get a video playlist
3050 - $ref: '#/components/parameters/playlistId'
3053 description: successful operation
3057 $ref: '#/components/schemas/VideoPlaylist'
3059 summary: Update a video playlist
3060 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3067 description: successful operation
3069 - $ref: '#/components/parameters/playlistId'
3072 multipart/form-data:
3077 description: Video playlist display name
3082 description: Video playlist thumbnail file
3086 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3088 description: Video playlist description
3092 - $ref: '#/components/schemas/id'
3093 description: Video channel in which the playlist will be published
3096 contentType: image/jpeg
3098 summary: Delete a video playlist
3104 - $ref: '#/components/parameters/playlistId'
3107 description: successful operation
3109 /video-playlists/{playlistId}/videos:
3111 summary: 'List videos of a playlist'
3112 operationId: getVideoPlaylistVideos
3117 - $ref: '#/components/parameters/playlistId'
3118 - $ref: '#/components/parameters/start'
3119 - $ref: '#/components/parameters/count'
3122 description: successful operation
3126 $ref: '#/components/schemas/VideoListResponse'
3128 summary: Add a video in a playlist
3129 operationId: addVideoPlaylistVideo
3136 - $ref: '#/components/parameters/playlistId'
3139 description: successful operation
3145 videoPlaylistElement:
3159 - $ref: '#/components/schemas/Video/properties/uuid'
3160 - $ref: '#/components/schemas/Video/properties/id'
3161 description: Video to add in the playlist
3165 description: Start the video at this specific timestamp
3169 description: Stop the video at this specific timestamp
3173 /video-playlists/{playlistId}/videos/reorder:
3175 summary: 'Reorder a playlist'
3176 operationId: reorderVideoPlaylist
3182 - $ref: '#/components/parameters/playlistId'
3185 description: successful operation
3194 description: 'Start position of the element to reorder'
3196 insertAfterPosition:
3198 description: 'New position for the block to reorder, to add the block before the first element'
3202 description: 'How many element from `startPosition` to reorder'
3206 - insertAfterPosition
3208 /video-playlists/{playlistId}/videos/{playlistElementId}:
3210 summary: Update a playlist element
3211 operationId: putVideoPlaylistVideo
3217 - $ref: '#/components/parameters/playlistId'
3218 - $ref: '#/components/parameters/playlistElementId'
3221 description: successful operation
3231 description: Start the video at this specific timestamp
3235 description: Stop the video at this specific timestamp
3237 summary: Delete an element from a playlist
3238 operationId: delVideoPlaylistVideo
3244 - $ref: '#/components/parameters/playlistId'
3245 - $ref: '#/components/parameters/playlistElementId'
3248 description: successful operation
3250 '/users/me/video-playlists/videos-exist':
3252 summary: Check video exists in my playlists
3261 description: The video ids to check
3265 $ref: '#/components/schemas/Video/properties/id'
3268 description: successful operation
3290 '/accounts/{name}/video-channels':
3292 summary: List video channels of an account
3297 - $ref: '#/components/parameters/name'
3300 description: include view statistics for the last 30 days (only if authentified as the account user)
3303 - $ref: '#/components/parameters/start'
3304 - $ref: '#/components/parameters/count'
3305 - $ref: '#/components/parameters/sort'
3308 description: successful operation
3312 $ref: '#/components/schemas/VideoChannelList'
3314 '/accounts/{name}/ratings':
3316 summary: List ratings of an account
3322 - $ref: '#/components/parameters/name'
3323 - $ref: '#/components/parameters/start'
3324 - $ref: '#/components/parameters/count'
3325 - $ref: '#/components/parameters/sort'
3329 description: Optionally filter which ratings to retrieve
3337 description: successful operation
3343 $ref: '#/components/schemas/VideoRating'
3345 '/videos/{id}/comment-threads':
3347 summary: List threads of a video
3351 - $ref: '#/components/parameters/idOrUUID'
3352 - $ref: '#/components/parameters/start'
3353 - $ref: '#/components/parameters/count'
3354 - $ref: '#/components/parameters/commentsSort'
3357 description: successful operation
3361 $ref: '#/components/schemas/CommentThreadResponse'
3363 summary: Create a thread
3369 - $ref: '#/components/parameters/idOrUUID'
3372 description: successful operation
3376 $ref: '#/components/schemas/CommentThreadPostResponse'
3378 description: video does not exist
3387 - $ref: '#/components/schemas/VideoComment/properties/text'
3393 '/videos/{id}/comment-threads/{threadId}':
3395 summary: Get a thread
3399 - $ref: '#/components/parameters/idOrUUID'
3400 - $ref: '#/components/parameters/threadId'
3403 description: successful operation
3407 $ref: '#/components/schemas/VideoCommentThreadTree'
3409 '/videos/{id}/comments/{commentId}':
3411 summary: Reply to a thread of a video
3417 - $ref: '#/components/parameters/idOrUUID'
3418 - $ref: '#/components/parameters/commentId'
3421 description: successful operation
3425 $ref: '#/components/schemas/CommentThreadPostResponse'
3427 description: thread or video does not exist
3436 - $ref: '#/components/schemas/VideoComment/properties/text'
3442 summary: Delete a comment or a reply
3448 - $ref: '#/components/parameters/idOrUUID'
3449 - $ref: '#/components/parameters/commentId'
3452 description: successful operation
3454 description: cannot remove comment of another user
3456 description: comment or video does not exist
3458 description: comment is already deleted
3460 '/videos/{id}/rate':
3462 summary: Like/dislike a video
3468 - $ref: '#/components/parameters/idOrUUID'
3484 description: successful operation
3486 description: video does not exist
3492 summary: Search videos
3493 operationId: searchVideos
3498 allowEmptyValue: false
3500 String to search. If the user can make a remote URI search, and the string is an URI then the
3501 PeerTube instance will fetch the remote object and add it to its database. Then,
3502 you can use the REST API to fetch the complete video information and interact with it.
3505 - $ref: '#/components/parameters/categoryOneOf'
3506 - $ref: '#/components/parameters/isLive'
3507 - $ref: '#/components/parameters/tagsOneOf'
3508 - $ref: '#/components/parameters/tagsAllOf'
3509 - $ref: '#/components/parameters/licenceOneOf'
3510 - $ref: '#/components/parameters/languageOneOf'
3511 - $ref: '#/components/parameters/nsfw'
3512 - $ref: '#/components/parameters/filter'
3513 - $ref: '#/components/parameters/skipCount'
3514 - $ref: '#/components/parameters/start'
3515 - $ref: '#/components/parameters/count'
3516 - $ref: '#/components/parameters/searchTarget'
3517 - $ref: '#/components/parameters/videosSearchSort'
3520 description: Get videos that are published after this date
3526 description: Get videos that are published before this date
3530 - name: originallyPublishedStartDate
3532 description: Get videos that are originally published after this date
3536 - name: originallyPublishedEndDate
3538 description: Get videos that are originally published before this date
3544 description: Get videos that have this minimum duration
3549 description: Get videos that have this maximum duration
3553 'searchTarget === search-index':
3554 $ref: '#/components/callbacks/searchIndex'
3557 description: successful operation
3561 $ref: '#/components/schemas/VideoListResponse'
3563 description: search index unavailable
3565 /search/video-channels:
3569 summary: Search channels
3570 operationId: searchChannels
3576 String to search. If the user can make a remote URI search, and the string is an URI then the
3577 PeerTube instance will fetch the remote object and add it to its database. Then,
3578 you can use the REST API to fetch the complete channel information and interact with it.
3581 - $ref: '#/components/parameters/start'
3582 - $ref: '#/components/parameters/count'
3583 - $ref: '#/components/parameters/searchTarget'
3584 - $ref: '#/components/parameters/sort'
3586 'searchTarget === search-index':
3587 $ref: '#/components/callbacks/searchIndex'
3590 description: successful operation
3594 $ref: '#/components/schemas/VideoChannelList'
3596 description: search index unavailable
3598 /search/video-playlists:
3602 summary: Search playlists
3603 operationId: searchPlaylists
3609 String to search. If the user can make a remote URI search, and the string is an URI then the
3610 PeerTube instance will fetch the remote object and add it to its database. Then,
3611 you can use the REST API to fetch the complete playlist information and interact with it.
3614 - $ref: '#/components/parameters/start'
3615 - $ref: '#/components/parameters/count'
3616 - $ref: '#/components/parameters/searchTarget'
3617 - $ref: '#/components/parameters/sort'
3619 'searchTarget === search-index':
3620 $ref: '#/components/callbacks/searchIndex'
3623 description: successful operation
3635 $ref: '#/components/schemas/VideoPlaylist'
3637 description: search index unavailable
3639 /server/blocklist/accounts:
3643 summary: List account blocks
3648 - $ref: '#/components/parameters/start'
3649 - $ref: '#/components/parameters/count'
3650 - $ref: '#/components/parameters/sort'
3653 description: successful operation
3657 summary: Block an account
3669 example: chocobozzz@example.org
3670 description: account to block, in the form `username@domain`
3675 description: successful operation
3677 description: self-blocking forbidden
3679 '/server/blocklist/accounts/{accountName}':
3683 summary: Unblock an account by its handle
3691 description: account to unblock, in the form `username@domain`
3696 description: successful operation
3698 description: account or account block does not exist
3700 /server/blocklist/servers:
3704 summary: List server blocks
3709 - $ref: '#/components/parameters/start'
3710 - $ref: '#/components/parameters/count'
3711 - $ref: '#/components/parameters/sort'
3714 description: successful operation
3718 summary: Block a server
3731 description: server domain to block
3736 description: successful operation
3738 description: self-blocking forbidden
3740 '/server/blocklist/servers/{host}':
3744 summary: Unblock a server by its domain
3752 description: server domain to unblock
3758 description: successful operation
3760 description: account block does not exist
3762 /server/redundancy/{host}:
3765 - Instance Redundancy
3766 summary: Update a server redundancy policy
3774 description: server domain to mirror
3786 description: allow mirroring of the host's local videos
3791 description: successful operation
3793 description: server is not already known
3795 /server/redundancy/videos:
3799 summary: List videos being mirrored
3800 operationId: getMirroredVideos
3808 description: direction of the mirror
3814 - $ref: '#/components/parameters/start'
3815 - $ref: '#/components/parameters/count'
3816 - $ref: '#/components/parameters/videoRedundanciesSort'
3819 description: successful operation
3825 $ref: '#/components/schemas/VideoRedundancy'
3829 summary: Mirror a video
3830 operationId: putMirroredVideo
3841 $ref: '#/components/schemas/Video/properties/id'
3846 description: successful operation
3848 description: cannot mirror a local video
3850 description: video does not exist
3852 description: video is already mirrored
3854 /server/redundancy/videos/{redundancyId}:
3858 summary: Delete a mirror done on a video
3859 operationId: delMirroredVideo
3864 - name: redundancyId
3867 description: id of an existing redundancy on a video
3872 description: successful operation
3874 description: video redundancy not found
3876 '/feeds/video-comments.{format}':
3880 summary: List comments on videos
3881 operationId: getSyndicatedComments
3886 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3899 description: 'limit listing to a specific video'
3904 description: 'limit listing to a specific account'
3909 description: 'limit listing to a specific account'
3912 - name: videoChannelId
3914 description: 'limit listing to a specific video channel'
3917 - name: videoChannelName
3919 description: 'limit listing to a specific video channel'
3924 description: successful operation
3929 default: 'max-age=900' # 15 min cache
3933 $ref: '#/components/schemas/VideoCommentsForXML'
3936 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3937 application/rss+xml:
3939 $ref: '#/components/schemas/VideoCommentsForXML'
3942 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3945 $ref: '#/components/schemas/VideoCommentsForXML'
3948 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3949 application/atom+xml:
3951 $ref: '#/components/schemas/VideoCommentsForXML'
3954 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3960 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3962 x-summary: field inconsistencies
3965 - videoId filter is mixed with a channel filter
3967 description: video, video channel or account not found
3969 description: accept header unsupported
3971 '/feeds/videos.{format}':
3975 summary: List videos
3976 operationId: getSyndicatedVideos
3981 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3994 description: 'limit listing to a specific account'
3999 description: 'limit listing to a specific account'
4002 - name: videoChannelId
4004 description: 'limit listing to a specific video channel'
4007 - name: videoChannelName
4009 description: 'limit listing to a specific video channel'
4012 - $ref: '#/components/parameters/sort'
4013 - $ref: '#/components/parameters/nsfw'
4014 - $ref: '#/components/parameters/filter'
4017 description: successful operation
4022 default: 'max-age=900' # 15 min cache
4026 $ref: '#/components/schemas/VideosForXML'
4029 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4030 application/rss+xml:
4032 $ref: '#/components/schemas/VideosForXML'
4035 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4038 $ref: '#/components/schemas/VideosForXML'
4041 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4042 application/atom+xml:
4044 $ref: '#/components/schemas/VideosForXML'
4047 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4053 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4055 description: video channel or account not found
4057 description: accept header unsupported
4059 '/feeds/subscriptions.{format}':
4064 summary: List videos of subscriptions tied to a token
4065 operationId: getSyndicatedSubscriptionVideos
4070 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4083 description: limit listing to a specific account
4089 description: private token allowing access
4093 - $ref: '#/components/parameters/sort'
4094 - $ref: '#/components/parameters/nsfw'
4095 - $ref: '#/components/parameters/filter'
4098 description: successful operation
4103 default: 'max-age=900' # 15 min cache
4107 $ref: '#/components/schemas/VideosForXML'
4108 application/rss+xml:
4110 $ref: '#/components/schemas/VideosForXML'
4113 $ref: '#/components/schemas/VideosForXML'
4114 application/atom+xml:
4116 $ref: '#/components/schemas/VideosForXML'
4121 description: accept header unsupported
4127 summary: List plugins
4128 operationId: getPlugins
4141 - $ref: '#/components/parameters/start'
4142 - $ref: '#/components/parameters/count'
4143 - $ref: '#/components/parameters/sort'
4146 description: successful operation
4150 $ref: '#/components/schemas/PluginResponse'
4156 summary: List available plugins
4157 operationId: getAvailablePlugins
4170 - name: currentPeerTubeEngine
4174 - $ref: '#/components/parameters/start'
4175 - $ref: '#/components/parameters/count'
4176 - $ref: '#/components/parameters/sort'
4179 description: successful operation
4183 $ref: '#/components/schemas/PluginResponse'
4185 description: plugin index unavailable
4191 summary: Install a plugin
4192 operationId: addPlugin
4205 example: peertube-plugin-auth-ldap
4208 additionalProperties: false
4215 additionalProperties: false
4218 description: successful operation
4220 description: should have either `npmName` or `path` set
4226 summary: Update a plugin
4227 operationId: updatePlugin
4240 example: peertube-plugin-auth-ldap
4243 additionalProperties: false
4250 additionalProperties: false
4253 description: successful operation
4255 description: should have either `npmName` or `path` set
4257 description: existing plugin not found
4263 summary: Uninstall a plugin
4264 operationId: uninstallPlugin
4276 description: name of the plugin/theme in its package.json
4277 example: peertube-plugin-auth-ldap
4282 description: successful operation
4284 description: existing plugin not found
4290 summary: Get a plugin
4291 operationId: getPlugin
4296 - $ref: '#/components/parameters/npmName'
4299 description: successful operation
4303 $ref: '#/components/schemas/Plugin'
4305 description: plugin not found
4307 /plugins/{npmName}/settings:
4311 summary: Set a plugin's settings
4316 - $ref: '#/components/parameters/npmName'
4325 additionalProperties: true
4328 description: successful operation
4330 description: plugin not found
4332 /plugins/{npmName}/public-settings:
4336 summary: Get a plugin's public settings
4338 - $ref: '#/components/parameters/npmName'
4341 description: successful operation
4346 additionalProperties: true
4348 description: plugin not found
4350 /plugins/{npmName}/registered-settings:
4354 summary: Get a plugin's registered settings
4359 - $ref: '#/components/parameters/npmName'
4362 description: successful operation
4367 additionalProperties: true
4369 description: plugin not found
4372 - url: 'https://peertube2.cpy.re/api/v1'
4373 description: Live Test Server (live data - latest nightly version)
4374 - url: 'https://peertube3.cpy.re/api/v1'
4375 description: Live Test Server (live data - latest RC version)
4376 - url: 'https://peertube.cpy.re/api/v1'
4377 description: Live Test Server (live data - stable version)
4384 description: Offset used to paginate results
4392 description: "Number of items to return"
4402 description: Sort column
4410 description: Plain text search, applied to various parts of the model depending on endpoint
4418 If the administrator enabled search index support, you can override the default search target.
4421 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4422 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4423 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4424 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4425 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4426 * 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
4427 the data from the origin instance API
4437 description: Sort videos by criteria
4453 description: Sort videos by criteria
4468 description: Sort comments by criteria
4478 description: Sort blocklists by criteria
4494 description: Plain text search that will match with user usernames or emails
4501 description: Filter results down to (un)banned users
4508 description: Sort users by criteria
4519 description: Sort abuses by criteria
4526 videoRedundanciesSort:
4530 description: Sort abuses by criteria
4539 description: The username or handle of the account
4542 example: chocobozzz | chocobozzz@example.org
4547 description: The user id
4549 $ref: '#/components/schemas/id'
4554 description: The object id, uuid or short uuid
4557 - $ref: '#/components/schemas/id'
4558 - $ref: '#/components/schemas/UUIDv4'
4559 - $ref: '#/components/schemas/shortUUID'
4564 description: Playlist id
4566 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4568 name: playlistElementId
4571 description: Playlist element id
4573 $ref: '#/components/schemas/id'
4578 description: Abuse id
4580 $ref: '#/components/schemas/Abuse/properties/id'
4582 name: abuseMessageId
4585 description: Abuse message id
4587 $ref: '#/components/schemas/AbuseMessage/properties/id'
4589 name: captionLanguage
4592 description: The caption language
4594 $ref: '#/components/schemas/VideoLanguageSet'
4599 description: The video channel handle
4602 example: my_username | my_username@example.com
4604 name: subscriptionHandle
4607 description: The subscription handle
4610 example: my_username | my_username@example.com
4615 description: The thread id (root comment id)
4622 description: The comment id
4624 $ref: '#/components/schemas/VideoComment/properties/id'
4629 description: whether or not the video is a live
4636 description: category id of the video (see [/videos/categories](#operation/getCategories))
4639 - $ref: '#/components/schemas/VideoCategorySet'
4642 $ref: '#/components/schemas/VideoCategorySet'
4649 description: tag(s) of the video
4663 description: tag(s) of the video, where all should be present in the video
4676 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4679 - $ref: '#/components/schemas/VideoLanguageSet'
4682 $ref: '#/components/schemas/VideoLanguageSet'
4689 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4692 - $ref: '#/components/schemas/VideoLicenceSet'
4695 $ref: '#/components/schemas/VideoLicenceSet'
4702 description: if you don't need the `total` in the response
4713 description: whether to include nsfw videos, if any
4724 Special filters which might require special rights:
4725 * `local` - only videos local to the instance
4726 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4727 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4737 description: list of uris to check if each is part of the user subscriptions
4747 description: name of the plugin/theme on npmjs.com or in its package.json
4750 example: peertube-plugin-auth-ldap
4755 description: job type
4759 - activitypub-follow
4760 - activitypub-http-broadcast
4761 - activitypub-http-fetcher
4762 - activitypub-http-unicast
4768 - activitypub-refresher
4793 Authenticating via OAuth requires the following steps:
4794 - Have an activated account
4795 - [Generate] an access token for that account at `/api/v1/users/token`.
4796 - Make requests with the *Authorization: Bearer <token\>* header
4797 - Profit, depending on the role assigned to the account
4799 Note that the __access token is valid for 1 day__ and is given
4800 along with a __refresh token valid for 2 weeks__.
4802 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4806 tokenUrl: /api/v1/users/token
4809 moderator: Moderator scope
4812 # Resuable core properties
4820 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4821 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4826 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4827 example: 2y84q2MQUMWPbiEcxNXMgC
4830 description: immutable name of the user, used to find or mention its actor
4832 pattern: '/^[a-z0-9._]+$/'
4837 description: immutable name of the channel, used to interact with its actor
4838 example: framasoft_videos
4839 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4850 description: category id of the video (see [/videos/categories](#operation/getCategories))
4852 VideoConstantNumber-Category:
4855 $ref: '#/components/schemas/VideoCategorySet'
4858 example: Science & Technology
4862 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4864 VideoConstantNumber-Licence:
4867 $ref: '#/components/schemas/VideoLicenceSet'
4870 example: Attribution - Share Alike
4874 description: language id of the video (see [/videos/languages](#operation/getLanguages))
4876 VideoConstantString-Language:
4879 $ref: '#/components/schemas/VideoLanguageSet'
4884 VideoPlaylistPrivacySet:
4890 description: Video playlist privacy policy (see [/video-playlists/privacies])
4891 VideoPlaylistPrivacyConstant:
4894 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4898 VideoPlaylistTypeSet:
4903 description: The video playlist type (Regular = `1`, Watch Later = `2`)
4904 VideoPlaylistTypeConstant:
4907 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4918 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4919 VideoPrivacyConstant:
4922 $ref: '#/components/schemas/VideoPrivacySet'
4939 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4946 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
4957 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4967 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4971 $ref: '#/components/schemas/AbuseStateSet'
4974 AbusePredefinedReasons:
4987 example: [spamOrMisleading]
4992 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4994 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4996 VideoResolutionConstant:
4997 description: resolutions and their labels for the video
5000 $ref: '#/components/schemas/VideoResolutionSet'
5004 VideoScheduledUpdate:
5007 $ref: '#/components/schemas/VideoPrivacySet'
5011 description: When to update the video
5031 - $ref: '#/components/schemas/ActorImage'
5032 VideoChannelSummary:
5035 $ref: '#/components/schemas/id'
5049 - $ref: '#/components/schemas/ActorImage'
5063 - $ref: '#/components/schemas/Video'
5070 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5071 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
5072 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5074 $ref: '#/components/schemas/VideoResolutionConstant'
5077 description: Video file size in bytes
5080 description: Direct URL of the torrent file
5084 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5088 description: Direct URL of the video
5092 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5096 description: Frames per second of the video file
5100 description: URL dereferencing the output of ffprobe on the file
5101 VideoStreamingPlaylists:
5106 $ref: '#/components/schemas/id'
5114 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5115 VideoStreamingPlaylists-HLS:
5126 Video files associated to this playlist.
5128 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5130 $ref: '#/components/schemas/VideoFile'
5142 $ref: '#/components/schemas/Video/properties/id'
5144 $ref: '#/components/schemas/Video/properties/uuid'
5146 $ref: '#/components/schemas/Video/properties/name'
5150 description: object id for the video
5152 - $ref: '#/components/schemas/id'
5154 description: universal identifier for the video, that can be used across instances
5156 - $ref: '#/components/schemas/UUIDv4'
5159 - $ref: '#/components/schemas/shortUUID'
5165 example: 2017-10-01T10:52:46.396Z
5166 description: time at which the video object was first drafted
5170 example: 2018-10-01T10:52:46.396Z
5171 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5175 example: 2021-05-04T08:01:01.502Z
5176 description: last time the video's metadata was modified
5177 originallyPublishedAt:
5180 example: 2010-10-01T10:52:46.396Z
5181 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5184 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5185 description: category in which the video is classified
5188 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5189 description: licence under which the video is distributed
5192 - $ref: '#/components/schemas/VideoConstantString-Language'
5193 description: main language used in the video
5196 - $ref: '#/components/schemas/VideoPrivacyConstant'
5197 description: privacy policy used to distribute the video
5201 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5202 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5206 truncated description of the video, written in Markdown.
5207 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5212 description: duration of the video in seconds
5217 description: title of the video
5218 example: What is PeerTube?
5223 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5226 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5229 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5246 - $ref: '#/components/schemas/VideoStateConstant'
5247 description: represents the internal state of the video processing within the PeerTube instance
5251 - $ref: '#/components/schemas/VideoScheduledUpdate'
5259 $ref: '#/components/schemas/AccountSummary'
5261 $ref: '#/components/schemas/VideoChannelSummary'
5270 - $ref: '#/components/schemas/Video'
5275 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5276 description: path at which to get the full description of maximum `10000` characters
5279 description: A text tell the audience how to support the video creator
5280 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5284 $ref: '#/components/schemas/VideoChannel'
5286 $ref: '#/components/schemas/Account'
5288 example: [flowers, gardening]
5306 - https://peertube2.cpy.re/tracker/announce
5307 - wss://peertube2.cpy.re/tracker/socket
5311 $ref: '#/components/schemas/VideoFile'
5313 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5315 - field will be empty
5316 - video files will be found in `streamingPlaylists[].files` field
5320 $ref: '#/components/schemas/VideoStreamingPlaylists'
5322 HLS playlists/manifest files. If HLS is disabled on the server:
5324 - field will be empty
5325 - video files will be found in `files` field
5326 FileRedundancyInformation:
5329 $ref: '#/components/schemas/id'
5354 $ref: '#/components/schemas/id'
5361 $ref: '#/components/schemas/UUIDv4'
5368 $ref: '#/components/schemas/FileRedundancyInformation'
5372 $ref: '#/components/schemas/FileRedundancyInformation'
5373 VideoImportStateConstant:
5381 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5388 additionalProperties: false
5392 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5393 required: [targetUrl]
5396 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5397 required: [magnetUri]
5400 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5401 required: [torrentfile]
5402 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5411 - $ref: '#/components/schemas/id'
5415 description: remote URL where to find the import's source video
5416 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5420 description: magnet URI allowing to resolve the import's source video
5421 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
5422 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5427 description: Torrent file containing only the video file
5434 - $ref: '#/components/schemas/VideoImportStateConstant'
5450 - $ref: '#/components/schemas/Video'
5460 $ref: '#/components/schemas/VideoImport'
5464 $ref: '#/components/schemas/id'
5467 example: The video is a spam
5471 $ref: '#/components/schemas/AbusePredefinedReasons'
5473 $ref: '#/components/schemas/Account'
5475 $ref: '#/components/schemas/AbuseStateConstant'
5478 example: Decided to ban the server since it spams us regularly
5482 $ref: '#/components/schemas/VideoInfo'
5489 $ref: '#/components/schemas/id'
5500 $ref: '#/components/schemas/AccountSummary'
5504 $ref: '#/components/schemas/id'
5506 $ref: '#/components/schemas/Video/properties/id'
5518 $ref: '#/components/schemas/UUIDv4'
5536 $ref: '#/components/schemas/id'
5538 $ref: '#/components/schemas/UUIDv4'
5541 - $ref: '#/components/schemas/shortUUID'
5564 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5566 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5568 $ref: '#/components/schemas/AccountSummary'
5570 $ref: '#/components/schemas/VideoChannelSummary'
5574 $ref: '#/components/schemas/id'
5581 description: Text of the comment
5583 example: This video is wonderful!
5585 $ref: '#/components/schemas/id'
5589 - $ref: '#/components/schemas/id'
5591 $ref: '#/components/schemas/Video/properties/id'
5606 totalRepliesFromVideoAuthor:
5613 $ref: '#/components/schemas/Account'
5614 VideoCommentThreadTree:
5617 $ref: '#/components/schemas/VideoComment'
5621 $ref: '#/components/schemas/VideoCommentThreadTree'
5625 $ref: '#/components/schemas/VideoConstantString-Language'
5641 $ref: '#/components/schemas/id'
5658 $ref: '#/components/schemas/id'
5663 description: immutable name of the actor, used to find or mention it
5665 - $ref: '#/components/schemas/username'
5669 description: server on which the actor is resident
5670 hostRedundancyAllowed:
5672 description: whether this actor's host allows redundancy of its videos
5676 description: number of actors subscribed to by this actor, as seen by this instance
5680 description: number of followers of this actor, as seen by this instance
5688 $ref: '#/components/schemas/ActorImage'
5691 - $ref: '#/components/schemas/Actor'
5694 description: object id for the user tied to this account
5696 - $ref: '#/components/schemas/User/properties/id'
5699 description: editable name of the account, displayed in its representations
5704 description: text or bio displayed on the account's profile
5710 description: timestamp within the video, in seconds
5777 allowedForCurrentIP:
5779 requiresEmailVerification:
5797 $ref: '#/components/schemas/VideoResolutionSet'
5882 example: 16810141515
5991 requiresEmailVerification:
6006 description: Settings that apply to new users, if registration is enabled
6010 example: 16810141515
6016 description: Settings pertaining to transcoding jobs
6020 allowAdditionalExtensions:
6022 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6025 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6028 description: Amount of threads used by ffmpeg for 1 transcoding job
6031 description: Amount of transcoding jobs to execute in parallel
6037 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6040 description: Resolutions to transcode _new videos_ to
6060 description: WebTorrent-specific settings
6066 description: HLS-specific settings
6116 $ref: '#/components/schemas/id'
6118 $ref: '#/components/schemas/Actor'
6120 $ref: '#/components/schemas/Actor'
6123 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6136 PredefinedAbuseReasons:
6137 description: Reason categories that help triage reports
6155 $ref: '#/components/schemas/id'
6167 - activitypub-http-unicast
6168 - activitypub-http-broadcast
6169 - activitypub-http-fetcher
6170 - activitypub-follow
6176 - activitypub-refresher
6180 additionalProperties: true
6183 additionalProperties: true
6199 $ref: '#/components/schemas/id'
6204 $ref: '#/components/schemas/id'
6205 VideoUploadRequestCommon:
6208 description: Video name
6210 example: What is PeerTube?
6214 description: Channel id that will contain this video
6219 $ref: '#/components/schemas/VideoPrivacySet'
6221 $ref: '#/components/schemas/VideoCategorySet'
6223 $ref: '#/components/schemas/VideoLicenceSet'
6225 $ref: '#/components/schemas/VideoLanguageSet'
6227 description: Video description
6230 **[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)**
6232 description: Whether or not we wait transcoding before publish the video
6235 description: A text tell the audience how to support the video creator
6236 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6239 description: Whether or not this video contains sensitive content
6242 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6255 description: Enable or disable comments for this video
6258 description: Enable or disable downloading for this video
6260 originallyPublishedAt:
6261 description: Date when the content was originally published
6265 $ref: '#/components/schemas/VideoScheduledUpdate'
6267 description: Video thumbnail file
6271 description: Video preview file
6277 VideoUploadRequestLegacy:
6279 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6285 description: Video file
6288 VideoUploadRequestResumable:
6290 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6296 description: Video filename including extension
6299 example: what_is_peertube.mp4
6301 description: Video thumbnail file
6305 description: Video preview file
6308 VideoUploadResponse:
6314 $ref: '#/components/schemas/Video/properties/id'
6316 $ref: '#/components/schemas/Video/properties/uuid'
6318 $ref: '#/components/schemas/Video/properties/shortUUID'
6319 CommentThreadResponse:
6328 $ref: '#/components/schemas/VideoComment'
6329 CommentThreadPostResponse:
6332 $ref: '#/components/schemas/VideoComment'
6342 $ref: '#/components/schemas/Video'
6346 $ref: '#/components/schemas/Account'
6349 description: Automatically start playing the upcoming video after the currently playing video
6350 autoPlayNextVideoPlaylist:
6352 description: Automatically start playing the video on the playlist after the currently playing video
6355 description: Automatically start playing the video on the watch page
6365 description: The user email
6368 description: Has the user confirmed their email address?
6371 - $ref: '#/components/schemas/id'
6375 description: Auth plugin to use to authenticate the user
6379 noInstanceConfigWarningModal:
6381 noAccountSetupWarningModal:
6386 $ref: '#/components/schemas/NSFWPolicy'
6388 $ref: '#/components/schemas/UserRole'
6397 description: Theme enabled by this user
6399 $ref: '#/components/schemas/username'
6403 $ref: '#/components/schemas/VideoChannel'
6406 description: The user video quota in bytes
6410 description: The user daily video quota in bytes
6414 description: Enable P2P in the player
6417 - $ref: '#/components/schemas/User'
6419 # optionally present fields: they require WITH_STATS scope
6422 description: Count of videos published
6425 description: Count of reports/abuses of which the user is a target
6426 abusesAcceptedCount:
6428 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6431 description: Count of reports/abuses created by the user
6434 description: Count of comments published
6438 $ref: '#/components/schemas/username'
6440 $ref: '#/components/schemas/password'
6444 description: The user email
6447 description: The user video quota in bytes
6451 description: The user daily video quota in bytes
6454 $ref: '#/components/schemas/usernameChannel'
6456 $ref: '#/components/schemas/UserRole'
6458 $ref: '#/components/schemas/UserAdminFlags'
6469 description: The updated email of the user
6471 - $ref: '#/components/schemas/User/properties/email'
6474 description: Set the email as verified
6477 description: The updated video quota of the user in bytes
6480 description: The updated daily video quota of the user in bytes
6484 description: The auth plugin to use to authenticate the user
6485 example: 'peertube-plugin-auth-saml2'
6487 $ref: '#/components/schemas/UserRole'
6489 $ref: '#/components/schemas/UserAdminFlags'
6491 # see shared/models/users/user-update-me.model.ts:
6494 $ref: '#/components/schemas/password'
6496 $ref: '#/components/schemas/password'
6498 description: new email used for login and service communications
6500 - $ref: '#/components/schemas/User/properties/email'
6503 description: new name of the user in its representations
6508 description: new NSFW display policy
6515 description: whether to enable P2P in the player or not
6518 description: new preference regarding playing videos automatically
6521 description: new preference regarding playing following videos automatically
6522 autoPlayNextVideoPlaylist:
6524 description: new preference regarding playing following playlist videos automatically
6525 videosHistoryEnabled:
6527 description: whether to keep track of watched history or not
6532 description: list of languages to filter videos down to
6535 noInstanceConfigWarningModal:
6537 noAccountSetupWarningModal:
6544 $ref: '#/components/schemas/id'
6551 description: Rating of the video
6558 $ref: '#/components/schemas/Video'
6565 description: Rating of the video
6572 description: immutable name of the user, used to find or mention its actor
6574 - $ref: '#/components/schemas/username'
6576 $ref: '#/components/schemas/password'
6580 description: email of the user, used for login or service communications
6583 description: editable name of the user, displayed in its representations
6588 description: channel base information used to create the first channel of the user
6591 $ref: '#/components/schemas/usernameChannel'
6593 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6603 pattern: /^[a-z0-9]$/
6606 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6609 pattern: /^[a-zA-Z0-9]$/
6612 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6613 OAuthToken-password:
6615 - $ref: '#/components/schemas/OAuthClient'
6625 $ref: '#/components/schemas/User/properties/username'
6627 $ref: '#/components/schemas/password'
6634 OAuthToken-refresh_token:
6636 - $ref: '#/components/schemas/OAuthClient'
6647 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6656 # GET/POST/PUT properties
6659 description: editable name of the channel, displayed in its representations
6660 example: Videos of Framasoft
6665 example: Videos made with <3 by Framasoft
6670 description: text shown by default on all videos of this channel, to tell the audience how to support it
6671 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6674 # GET-only properties
6678 - $ref: '#/components/schemas/id'
6694 $ref: '#/components/schemas/UUIDv4'
6697 - $ref: '#/components/schemas/VideoChannel'
6700 description: username of the channel to create
6702 - $ref: '#/components/schemas/usernameChannel'
6708 - $ref: '#/components/schemas/VideoChannel'
6710 bulkVideosSupportUpdate:
6712 description: Update the support field for all videos of this channel
6722 - $ref: '#/components/schemas/VideoChannel'
6723 - $ref: '#/components/schemas/Actor'
6728 name: 'media:peerLink'
6737 - application/x-bittorrent
6743 name: 'media:content'
6774 VideoCommentsForXML:
6809 description: video watch page URL
6812 description: video canonical URL
6816 description: video publication date
6819 description: video description
6822 description: video description
6825 description: publisher user name
6828 description: video category (MRSS)
6831 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6846 description: video embed path, relative to the canonical URL domain (MRSS)
6855 description: video watch path, relative to the canonical URL domain (MRSS)
6876 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6877 'media:description':
6884 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6887 description: main streamable file for the video
6897 - application/x-bittorrent
6906 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)
6909 - $ref: '#/components/schemas/MRSSPeerLink'
6910 - $ref: '#/components/schemas/MRSSGroupContent'
6911 NotificationSettingValue:
6928 $ref: '#/components/schemas/id'
6932 Notification type, following the `UserNotificationType` enum:
6934 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6936 - `2` NEW_COMMENT_ON_MY_VIDEO
6938 - `3` NEW_ABUSE_FOR_MODERATORS
6940 - `4` BLACKLIST_ON_MY_VIDEO
6942 - `5` UNBLACKLIST_ON_MY_VIDEO
6944 - `6` MY_VIDEO_PUBLISHED
6946 - `7` MY_VIDEO_IMPORT_SUCCESS
6948 - `8` MY_VIDEO_IMPORT_ERROR
6950 - `9` NEW_USER_REGISTRATION
6954 - `11` COMMENT_MENTION
6956 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6958 - `13` NEW_INSTANCE_FOLLOWER
6960 - `14` AUTO_INSTANCE_FOLLOWING
6966 - $ref: '#/components/schemas/VideoInfo'
6970 $ref: '#/components/schemas/ActorInfo'
6976 $ref: '#/components/schemas/id'
6979 $ref: '#/components/schemas/VideoInfo'
6984 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6994 $ref: '#/components/schemas/id'
6998 $ref: '#/components/schemas/VideoInfo'
7000 $ref: '#/components/schemas/ActorInfo'
7006 $ref: '#/components/schemas/id'
7009 - $ref: '#/components/schemas/VideoInfo'
7015 $ref: '#/components/schemas/id'
7018 - $ref: '#/components/schemas/VideoInfo'
7022 - $ref: '#/components/schemas/ActorInfo'
7028 $ref: '#/components/schemas/id'
7030 $ref: '#/components/schemas/ActorInfo'
7058 NotificationListResponse:
7067 $ref: '#/components/schemas/Notification'
7072 example: peertube-plugin-auth-ldap
7100 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7103 additionalProperties: true
7119 $ref: '#/components/schemas/Plugin'
7126 description: User can stream multiple times in a permanent live
7135 description: RTMP stream key to use to stream into this live video
7139 description: User can stream multiple times in a permanent live
7146 'https://search.example.org/api/v1/search/videos':
7148 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7151 description: successful operation
7155 $ref: '#/components/schemas/VideoListResponse'