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 with 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 a session token. Only __one
31 session 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. The body of the response will be JSON in the following
46 "code": "unauthorized_request", // example inner error code
47 "error": "Token is invalid." // example exposed error message
53 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
55 | Endpoint | Calls | Time frame |
56 |-------------------------|------------------|---------------------------|
57 | `/*` | 50 | 10 seconds |
58 | `POST /users/token` | 15 | 5 minutes |
59 | `POST /users/register` | 2¹ | 5 minutes |
60 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
62 Depending on the endpoint, ¹failed requests are not taken into account. A service
63 limit is announced by a `429 Too Many Requests` status code.
65 You can get details about the current state of your rate limit by reading the
68 | Header | Description |
69 |-------------------------|------------------------------------------------------------|
70 | X-RateLimit-Limit | Number of max requests allowed in the current time period |
71 | X-RateLimit-Remaining | Number of remaining requests in the current time period |
72 | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp |
73 | Retry-After | Seconds to delay after the first `429` is received |
75 url: https://docs.joinpeertube.org/api-rest-reference.html
79 Accounts encompass remote accounts discovered across the federation,
80 and correspond to the main Actor, along with video channels a user can create, which
83 When a comment is posted, it is done with your Account's Actor.
86 Using some features of PeerTube require authentication, for which User
87 provide different levels of permission as well as associated user
88 information. Each user has a corresponding local Account for federation.
91 Operations related to your own User, when logged-in.
92 - name: My Subscriptions
94 Operations related to your subscriptions to video channels, their
95 new videos, and how to keep up to date with their latest publications!
98 Operations related to your watch history.
99 - name: My Notifications
101 Notifications following new videos, follows or reports. They allow you
102 to keep track of the interactions and overall important information that
103 concerns you. You MAY set per-notification type delivery preference, to
104 receive the info either by mail, by in-browser notification or both.
107 Each server exposes public information regarding supported videos and
111 Jobs are long-running tasks enqueued and processed by the instance
112 itself. No additional worker registration is currently available.
113 - name: Instance Follows
115 Managing servers which the instance interacts with is crucial to the
116 concept of federation in PeerTube and external video indexation. The PeerTube
117 server then deals with inter-server ActivityPub operations and propagates
118 information across its social graph by posting activities to actors' inbox
121 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
122 - name: Instance Redundancy
124 Redundancy is part of the inter-server solidarity that PeerTube fosters.
125 Manage the list of instances you wish to help by seeding their videos according
126 to the policy of video selection of your choice. Note that you have a similar functionality
127 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
129 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
132 Managing plugins installed from a local path or from NPM, or search for new ones.
134 url: https://docs.joinpeertube.org/api-plugins
137 Abuses deal with reports of local or remote videos/comments/accounts alike.
140 Operations dealing with listing, uploading, fetching or modifying videos.
143 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
147 - [_legacy_](#tag/Video-Upload/paths/~1videos~1upload/post), where the video file is sent in a single request
148 - [_resumable_](#tag/Video-Upload/paths/~1videos~1upload-resumable/post), where the video file is sent in chunks
150 You can upload videos more reliably by using the resumable variant. Its protocol lets
151 you resume an upload operation after a network interruption or other transmission failure,
152 saving time and bandwidth in the event of network failures.
154 Favor using resumable uploads in any of the following cases:
155 - You are transferring large files
156 - The likelihood of a network interruption is high
157 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
158 such as a mobile device
162 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
163 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
164 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
166 The import function is practical when the desired video/audio is available online. It makes PeerTube
167 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
168 - name: Video Captions
169 description: Operations dealing with listing, adding and removing closed captions of a video.
170 - name: Video Channels
171 description: Operations dealing with the creation, modification and listing of videos within a channel.
172 - name: Video Comments
174 Operations dealing with comments to a video. Comments are organized in threads: adding a
175 comment in response to the video starts a thread, adding a reply to a comment adds it to
176 its root comment thread.
178 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
180 description: Like/dislike a video.
181 - name: Video Playlists
182 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
184 description: Server syndication feeds
187 The search helps to find _videos_ or _channels_ from within the instance and beyond.
188 Videos from other instances federated by the instance (that is, instances
189 followed by the instance) can be found via keywords and other criteria of
192 Administrators can also enable the use of a remote search system, indexing
193 videos and channels not could be not federated by the instance.
194 - name: Video Mirroring
196 PeerTube instances can mirror videos from one another, and help distribute some videos.
198 For importing videos as your own, refer to [video imports](#tag/Video-Upload/paths/~1videos~1imports/post).
217 - Video Ownership Change
230 - name: Instance Configuration
234 - Instance Redundancy
244 summary: Get an account
246 - $ref: '#/components/parameters/name'
249 description: successful operation
253 $ref: '#/components/schemas/Account'
255 description: account not found
256 '/accounts/{name}/videos':
261 summary: 'List videos of an account'
263 - $ref: '#/components/parameters/name'
264 - $ref: '#/components/parameters/categoryOneOf'
265 - $ref: '#/components/parameters/isLive'
266 - $ref: '#/components/parameters/tagsOneOf'
267 - $ref: '#/components/parameters/tagsAllOf'
268 - $ref: '#/components/parameters/licenceOneOf'
269 - $ref: '#/components/parameters/languageOneOf'
270 - $ref: '#/components/parameters/nsfw'
271 - $ref: '#/components/parameters/filter'
272 - $ref: '#/components/parameters/skipCount'
273 - $ref: '#/components/parameters/start'
274 - $ref: '#/components/parameters/count'
275 - $ref: '#/components/parameters/videosSort'
278 description: successful operation
282 $ref: '#/components/schemas/VideoListResponse'
286 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
287 .then(function(response) {
288 return response.json()
289 }).then(function(data) {
295 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
301 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
303 http = Net::HTTP.new(uri.host, uri.port)
306 response = http.get(uri.request_uri)
308 puts JSON.parse(response.read_body)
313 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
321 summary: List accounts
323 - $ref: '#/components/parameters/start'
324 - $ref: '#/components/parameters/count'
325 - $ref: '#/components/parameters/sort'
328 description: successful operation
334 $ref: '#/components/schemas/Account'
339 summary: Get instance public configuration
342 description: successful operation
346 $ref: '#/components/schemas/ServerConfig'
349 summary: Get instance "About" information
354 description: successful operation
358 $ref: '#/components/schemas/ServerConfigAbout'
361 summary: Get instance runtime configuration
369 description: successful operation
373 $ref: '#/components/schemas/ServerConfigCustom'
375 summary: Set instance runtime configuration
383 description: successful operation
385 x-summary: field inconsistencies
388 - the emailer is disabled and the instance is open to registrations
389 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
391 summary: Delete instance runtime configuration
399 description: successful operation
402 summary: List instance jobs
412 description: The state of the job ('' for for no filter)
422 - $ref: '#/components/parameters/jobType'
423 - $ref: '#/components/parameters/start'
424 - $ref: '#/components/parameters/count'
425 - $ref: '#/components/parameters/sort'
428 description: successful operation
441 $ref: '#/components/schemas/Job'
442 '/server/following/{host}':
449 summary: Unfollow a server
454 description: 'The host to unfollow '
460 description: successful operation
465 summary: List instance followers
467 - $ref: '#/components/parameters/start'
468 - $ref: '#/components/parameters/count'
469 - $ref: '#/components/parameters/sort'
472 description: successful operation
478 $ref: '#/components/schemas/Follow'
483 summary: List instances followed by the server
502 - $ref: '#/components/parameters/start'
503 - $ref: '#/components/parameters/count'
504 - $ref: '#/components/parameters/sort'
507 description: successful operation
513 $ref: '#/components/schemas/Follow'
520 summary: Follow a server
523 description: successful operation
525 description: cannot follow a non-HTTPS server
540 summary: Create a user
548 description: user created
552 $ref: '#/components/schemas/AddUserResponse'
556 operationId: getUserId
558 id: '$response.body#/user/id'
561 operationId: putUserId
563 id: '$response.body#/user/id'
566 operationId: delUserId
568 id: '$response.body#/user/id'
570 description: insufficient authority to create an admin or moderator
575 $ref: '#/components/schemas/AddUser'
576 description: User to create
586 - $ref: '#/components/parameters/usersSearch'
587 - $ref: '#/components/parameters/usersBlocked'
588 - $ref: '#/components/parameters/start'
589 - $ref: '#/components/parameters/count'
590 - $ref: '#/components/parameters/usersSort'
593 description: successful operation
599 $ref: '#/components/schemas/User'
602 - $ref: '#/components/parameters/id'
604 summary: Delete a user
610 operationId: delUserId
613 description: successful operation
620 operationId: getUserId
623 description: successful operation
627 $ref: '#/components/schemas/User'
629 summary: Update a user
634 operationId: putUserId
637 description: successful operation
642 $ref: '#/components/schemas/UpdateUser'
646 summary: Register a user
651 description: successful operation
656 $ref: '#/components/schemas/RegisterUser'
660 summary: Get my user information
668 description: successful operation
674 $ref: '#/components/schemas/User'
676 summary: Update my user information
684 description: successful operation
689 $ref: '#/components/schemas/UpdateMe'
691 /users/me/videos/imports:
693 summary: Get video imports of my user
701 - $ref: '#/components/parameters/start'
702 - $ref: '#/components/parameters/count'
703 - $ref: '#/components/parameters/sort'
706 description: successful operation
710 $ref: '#/components/schemas/VideoImport'
711 /users/me/video-quota-used:
713 summary: Get my user used quota
721 description: successful operation
733 '/users/me/videos/{videoId}/rating':
735 summary: Get rate of my user for a video
745 description: 'The video id '
750 description: successful operation
754 $ref: '#/components/schemas/GetMeVideoRating'
757 summary: Get videos of my user
765 - $ref: '#/components/parameters/start'
766 - $ref: '#/components/parameters/count'
767 - $ref: '#/components/parameters/sort'
770 description: successful operation
774 $ref: '#/components/schemas/VideoListResponse'
775 /users/me/subscriptions:
777 summary: Get my user subscriptions
784 - $ref: '#/components/parameters/start'
785 - $ref: '#/components/parameters/count'
786 - $ref: '#/components/parameters/sort'
789 description: successful operation
793 summary: Add subscription to my user
806 description: uri of the video channels to subscribe to
812 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
815 description: successful operation
816 /users/me/subscriptions/exist:
818 summary: Get if subscriptions exist for my user
825 - $ref: '#/components/parameters/subscriptionsUris'
828 description: successful operation
833 /users/me/subscriptions/videos:
835 summary: List videos of subscriptions of my user
843 - $ref: '#/components/parameters/categoryOneOf'
844 - $ref: '#/components/parameters/isLive'
845 - $ref: '#/components/parameters/tagsOneOf'
846 - $ref: '#/components/parameters/tagsAllOf'
847 - $ref: '#/components/parameters/licenceOneOf'
848 - $ref: '#/components/parameters/languageOneOf'
849 - $ref: '#/components/parameters/nsfw'
850 - $ref: '#/components/parameters/filter'
851 - $ref: '#/components/parameters/skipCount'
852 - $ref: '#/components/parameters/start'
853 - $ref: '#/components/parameters/count'
854 - $ref: '#/components/parameters/videosSort'
857 description: successful operation
861 $ref: '#/components/schemas/VideoListResponse'
862 '/users/me/subscriptions/{subscriptionHandle}':
864 summary: Get subscription of my user
871 - $ref: '#/components/parameters/subscriptionHandle'
874 description: successful operation
878 $ref: '#/components/schemas/VideoChannel'
880 summary: Delete subscription of my user
887 - $ref: '#/components/parameters/subscriptionHandle'
890 description: successful operation
891 /users/me/notifications:
893 summary: List my notifications
901 description: only list unread notifications
904 - $ref: '#/components/parameters/start'
905 - $ref: '#/components/parameters/count'
906 - $ref: '#/components/parameters/sort'
909 description: successful operation
913 $ref: '#/components/schemas/NotificationListResponse'
914 /users/me/notifications/read:
916 summary: Mark notifications as read by their id
929 description: ids of the notifications to mark as read
936 description: successful operation
937 /users/me/notifications/read-all:
939 summary: Mark all my notification as read
946 description: successful operation
947 /users/me/notification-settings:
949 summary: Update my notification settings
960 newVideoFromSubscription:
961 $ref: '#/components/schemas/NotificationSettingValue'
963 $ref: '#/components/schemas/NotificationSettingValue'
965 $ref: '#/components/schemas/NotificationSettingValue'
966 videoAutoBlacklistAsModerator:
967 $ref: '#/components/schemas/NotificationSettingValue'
969 $ref: '#/components/schemas/NotificationSettingValue'
971 $ref: '#/components/schemas/NotificationSettingValue'
972 myVideoImportFinished:
973 $ref: '#/components/schemas/NotificationSettingValue'
975 $ref: '#/components/schemas/NotificationSettingValue'
977 $ref: '#/components/schemas/NotificationSettingValue'
979 $ref: '#/components/schemas/NotificationSettingValue'
981 $ref: '#/components/schemas/NotificationSettingValue'
982 autoInstanceFollowing:
983 $ref: '#/components/schemas/NotificationSettingValue'
986 description: successful operation
987 /users/me/history/videos:
989 summary: List watched videos history
995 - $ref: '#/components/parameters/start'
996 - $ref: '#/components/parameters/count'
997 - $ref: '#/components/parameters/search'
1000 description: successful operation
1004 $ref: '#/components/schemas/VideoListResponse'
1005 /users/me/history/videos/remove:
1007 summary: Clear video history
1014 multipart/form-data:
1019 description: history before this date will be deleted
1024 description: successful operation
1025 /users/me/avatar/pick:
1027 summary: Update my user avatar
1034 description: successful operation
1041 $ref: '#/components/schemas/ActorImage'
1043 description: image file too large
1045 X-File-Maximum-Size:
1049 description: Maximum file size for the avatar
1052 multipart/form-data:
1057 description: The file to upload.
1062 contentType: image/png, image/jpeg
1065 summary: Delete my avatar
1072 description: successful operation
1076 summary: List video ownership changes
1078 - Video Ownership Change
1083 description: successful operation
1084 '/videos/ownership/{id}/accept':
1086 summary: Accept ownership change request
1088 - Video Ownership Change
1092 - $ref: '#/components/parameters/idOrUUID'
1095 description: successful operation
1097 description: cannot terminate an ownership change of another user
1099 description: video owneship change not found
1100 '/videos/ownership/{id}/refuse':
1102 summary: Refuse ownership change request
1104 - Video Ownership Change
1108 - $ref: '#/components/parameters/idOrUUID'
1111 description: successful operation
1113 description: cannot terminate an ownership change of another user
1115 description: video owneship change not found
1116 '/videos/{id}/give-ownership':
1118 summary: Request ownership change
1120 - Video Ownership Change
1124 - $ref: '#/components/parameters/idOrUUID'
1128 application/x-www-form-urlencoded:
1138 description: successful operation
1140 description: changing video ownership to a remote account is not supported yet
1142 description: video not found
1145 summary: List videos
1149 - $ref: '#/components/parameters/categoryOneOf'
1150 - $ref: '#/components/parameters/isLive'
1151 - $ref: '#/components/parameters/tagsOneOf'
1152 - $ref: '#/components/parameters/tagsAllOf'
1153 - $ref: '#/components/parameters/licenceOneOf'
1154 - $ref: '#/components/parameters/languageOneOf'
1155 - $ref: '#/components/parameters/nsfw'
1156 - $ref: '#/components/parameters/filter'
1157 - $ref: '#/components/parameters/skipCount'
1158 - $ref: '#/components/parameters/start'
1159 - $ref: '#/components/parameters/count'
1160 - $ref: '#/components/parameters/videosSort'
1163 description: successful operation
1167 $ref: '#/components/schemas/VideoListResponse'
1170 summary: List available video categories
1175 description: successful operation
1184 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1187 summary: List available video licences
1192 description: successful operation
1201 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1204 summary: List available video languages
1209 description: successful operation
1218 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1221 summary: List available video privacies
1226 description: successful operation
1235 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1238 summary: Update a video
1244 - $ref: '#/components/parameters/idOrUUID'
1247 description: successful operation
1250 multipart/form-data:
1255 description: Video thumbnail file
1259 description: Video preview file
1263 description: Video category
1267 description: Video licence
1271 description: Video language
1274 $ref: '#/components/schemas/VideoPrivacySet'
1276 description: Video description
1279 description: Whether or not we wait transcoding before publish the video
1282 description: A text tell the audience how to support the video creator
1283 example: Please support my work on <insert crowdfunding plateform>! <3
1286 description: Whether or not this video contains sensitive content
1289 description: Video name
1294 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1303 description: Enable or disable comments for this video
1305 originallyPublishedAt:
1306 description: Date when the content was originally published
1310 $ref: '#/components/schemas/VideoScheduledUpdate'
1313 contentType: image/jpeg
1315 contentType: image/jpeg
1317 summary: Get a video
1321 - $ref: '#/components/parameters/idOrUUID'
1324 description: successful operation
1328 $ref: '#/components/schemas/VideoDetails'
1330 summary: Delete a video
1336 - $ref: '#/components/parameters/idOrUUID'
1339 description: successful operation
1340 '/videos/{id}/description':
1342 summary: Get complete video description
1346 - $ref: '#/components/parameters/idOrUUID'
1349 description: successful operation
1354 '/videos/{id}/views':
1356 summary: Add a view to a video
1360 - $ref: '#/components/parameters/idOrUUID'
1363 description: successful operation
1364 '/videos/{id}/watching':
1366 summary: Set watching progress of a video
1372 - $ref: '#/components/parameters/idOrUUID'
1377 $ref: '#/components/schemas/UserWatchingVideo'
1381 description: successful operation
1384 summary: Upload a video
1385 description: Uses a single request to upload a video.
1393 description: successful operation
1397 $ref: '#/components/schemas/VideoUploadResponse'
1399 description: invalid file field, schedule date or parameter
1401 description: video didn't pass upload filter
1403 description: upload has timed out
1405 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1407 X-File-Maximum-Size:
1411 description: Maximum file size for the video
1413 description: video type unsupported
1415 description: video unreadable
1418 multipart/form-data:
1420 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1423 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1425 contentType: image/jpeg
1427 contentType: image/jpeg
1432 USERNAME="<your_username>"
1433 PASSWORD="<your_password>"
1434 FILE_PATH="<your_file_path>"
1435 CHANNEL_ID="<your_channel_id>"
1438 API_PATH="https://peertube2.cpy.re/api/v1"
1440 client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1441 client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1442 token=$(curl -s "$API_PATH/users/token" \
1443 --data client_id="$client_id" \
1444 --data client_secret="$client_secret" \
1445 --data grant_type=password \
1446 --data response_type=code \
1447 --data username="$USERNAME" \
1448 --data password="$PASSWORD" \
1449 | jq -r ".access_token")
1451 curl -s "$API_PATH/videos/upload" \
1452 -H "Authorization: Bearer $token" \
1454 --form videofile=@"$FILE_PATH" \
1455 --form channelId=$CHANNEL_ID \
1457 /videos/upload-resumable:
1459 summary: Initialize the resumable upload of a video
1460 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1467 - name: X-Upload-Content-Length
1473 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1474 - name: X-Upload-Content-Type
1481 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1486 $ref: '#/components/schemas/VideoUploadRequestResumable'
1489 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1491 description: created
1497 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1503 description: invalid file field, schedule date or parameter
1505 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1507 description: video type unsupported
1509 summary: Send chunk for the resumable upload of a video
1510 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
1521 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1522 not valid anymore and you need to initialize a new upload.
1525 - name: Content-Range
1529 example: bytes 0-262143/2469036
1532 Specifies the bytes in the file that the request is uploading.
1534 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1535 262144 bytes (256 x 1024) in a 2,469,036 byte file.
1536 - name: Content-Length
1543 Size of the chunk that the request is sending.
1545 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)
1546 doesn't mandate for chunks to have the same size throughout the upload sequence.
1548 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1549 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1552 application/octet-stream:
1558 description: last chunk received
1566 $ref: '#/components/schemas/VideoUploadResponse'
1568 description: resume incomplete
1573 example: bytes=0-262143
1579 description: video didn't pass upload filter
1581 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1583 description: video unreadable
1585 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1586 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1597 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1598 not valid anymore and the upload session has already been deleted with its data ;-)
1601 - name: Content-Length
1609 description: upload cancelled
1617 summary: Import a video
1618 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1626 multipart/form-data:
1631 description: Torrent File
1635 description: HTTP target URL
1638 description: Magnet URI
1641 description: Channel id that will contain this video
1644 description: Video thumbnail file
1648 description: Video preview file
1652 $ref: '#/components/schemas/VideoPrivacySet'
1654 description: Video category
1658 description: Video licence
1662 description: Video language
1665 description: Video description
1668 description: Whether or not we wait transcoding before publish the video
1671 description: A text tell the audience how to support the video creator
1672 example: Please support my work on <insert crowdfunding plateform>! <3
1675 description: Whether or not this video contains sensitive content
1678 description: Video name
1683 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1692 description: Enable or disable comments for this video
1695 description: Enable or disable downloading for this video
1698 $ref: '#/components/schemas/VideoScheduledUpdate'
1704 contentType: application/x-bittorrent
1706 contentType: image/jpeg
1708 contentType: image/jpeg
1711 description: successful operation
1715 $ref: '#/components/schemas/VideoUploadResponse'
1717 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1719 description: video didn't pass pre-import filter
1721 description: HTTP or Torrent/magnetURI import not enabled
1725 summary: Create a live
1733 description: successful operation
1737 $ref: '#/components/schemas/VideoUploadResponse'
1739 description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
1742 multipart/form-data:
1747 description: Channel id that will contain this live video
1752 description: User can stream multiple times in a permanent live
1755 description: Live video/replay thumbnail file
1759 description: Live video/replay preview file
1763 $ref: '#/components/schemas/VideoPrivacySet'
1765 description: Live video/replay category
1768 description: Live video/replay licence
1771 description: Live video/replay language
1774 description: Live video/replay description
1777 description: A text tell the audience how to support the creator
1778 example: Please support my work on <insert crowdfunding plateform>! <3
1781 description: Whether or not this live video/replay contains sensitive content
1784 description: Live video/replay name
1789 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
1798 description: Enable or disable comments for this live video/replay
1801 description: Enable or disable downloading for the replay of this live
1808 contentType: image/jpeg
1810 contentType: image/jpeg
1814 summary: Get information about a live
1821 - $ref: '#/components/parameters/idOrUUID'
1824 description: successful operation
1828 $ref: '#/components/schemas/LiveVideoResponse'
1830 summary: Update information about a live
1837 - $ref: '#/components/parameters/idOrUUID'
1842 $ref: '#/components/schemas/LiveVideoUpdate'
1845 description: Successful operation
1847 description: Bad parameters or trying to update a live that has already started
1849 description: Trying to save replay of the live but saving replay is not enabled on the instance
1853 summary: List my abuses
1862 description: only list the report with this id
1868 $ref: '#/components/schemas/AbuseStateSet'
1869 - $ref: '#/components/parameters/start'
1870 - $ref: '#/components/parameters/count'
1871 - $ref: '#/components/parameters/abusesSort'
1874 description: successful operation
1880 $ref: '#/components/schemas/Abuse'
1884 summary: List abuses
1894 description: only list the report with this id
1897 - name: predefinedReason
1899 description: predefined reason the listed reports should contain
1901 $ref: '#/components/schemas/PredefinedAbuseReasons'
1904 description: plain search that will match with video titles, reporter names and more
1910 $ref: '#/components/schemas/AbuseStateSet'
1911 - name: searchReporter
1913 description: only list reports of a specific reporter
1916 - name: searchReportee
1917 description: only list reports of a specific reportee
1923 description: only list reports of a specific video
1926 - name: searchVideoChannel
1928 description: only list reports of a specific video channel
1933 description: only list blacklisted or deleted videos
1941 description: only list account, comment or video reports
1948 - $ref: '#/components/parameters/start'
1949 - $ref: '#/components/parameters/count'
1950 - $ref: '#/components/parameters/abusesSort'
1953 description: successful operation
1959 $ref: '#/components/schemas/Abuse'
1962 summary: Report an abuse
1975 description: Reason why the user reports this video
1980 $ref: '#/components/schemas/PredefinedAbuseReasons'
1985 description: Video id to report
1989 description: Timestamp in the video that marks the beginning of the report
1993 description: Timestamp in the video that marks the ending of the report
1999 description: Comment id to report
2005 description: Account id to report
2011 description: successful operation
2013 description: incorrect request parameters
2014 '/abuses/{abuseId}':
2016 summary: Update an abuse
2024 - $ref: '#/components/parameters/abuseId'
2032 $ref: '#/components/schemas/AbuseStateSet'
2035 description: Update the report comment visible only to the moderation team
2040 description: successful operation
2042 description: abuse not found
2046 summary: Delete an abuse
2052 - $ref: '#/components/parameters/abuseId'
2055 description: successful operation
2057 description: block not found
2058 '/abuses/{abuseId}/messages':
2060 summary: List messages of an abuse
2066 - $ref: '#/components/parameters/abuseId'
2069 description: successful operation
2075 $ref: '#/components/schemas/AbuseMessage'
2078 summary: Add message to an abuse
2084 - $ref: '#/components/parameters/abuseId'
2093 description: Message to send
2101 description: successful operation
2103 description: incorrect request parameters
2104 '/abuses/{abuseId}/messages/{abuseMessageId}':
2106 summary: Delete an abuse message
2112 - $ref: '#/components/parameters/abuseId'
2113 - $ref: '#/components/parameters/abuseMessageId'
2116 description: successful operation
2118 '/videos/{id}/blacklist':
2120 summary: Block a video
2128 - $ref: '#/components/parameters/idOrUUID'
2131 description: successful operation
2133 summary: Unblock a video by its id
2141 - $ref: '#/components/parameters/idOrUUID'
2144 description: successful operation
2146 description: block not found
2151 summary: List video blocks
2160 list only blocks that match this type:
2164 - `2`: automatic block that needs review
2172 description: plain search that will match with video titles, and more
2175 - $ref: '#/components/parameters/start'
2176 - $ref: '#/components/parameters/count'
2177 - $ref: '#/components/parameters/blacklistsSort'
2180 description: successful operation
2192 $ref: '#/components/schemas/VideoBlacklist'
2193 /videos/{id}/captions:
2195 summary: List captions of a video
2199 - $ref: '#/components/parameters/idOrUUID'
2202 description: successful operation
2214 $ref: '#/components/schemas/VideoCaption'
2215 /videos/{id}/captions/{captionLanguage}:
2217 summary: Add or replace a video caption
2224 - $ref: '#/components/parameters/idOrUUID'
2225 - $ref: '#/components/parameters/captionLanguage'
2228 multipart/form-data:
2233 description: The file to upload.
2238 contentType: text/vtt, application/x-subrip, text/plain
2241 description: successful operation
2243 description: video or language not found
2245 summary: Delete a video caption
2252 - $ref: '#/components/parameters/idOrUUID'
2253 - $ref: '#/components/parameters/captionLanguage'
2256 description: successful operation
2258 description: video or language or caption for that language not found
2261 summary: List video channels
2265 - $ref: '#/components/parameters/start'
2266 - $ref: '#/components/parameters/count'
2267 - $ref: '#/components/parameters/sort'
2270 description: successful operation
2282 $ref: '#/components/schemas/VideoChannel'
2284 summary: Create a video channel
2291 description: successful operation
2296 $ref: '#/components/schemas/VideoChannelCreate'
2297 '/video-channels/{channelHandle}':
2299 summary: Get a video channel
2303 - $ref: '#/components/parameters/channelHandle'
2306 description: successful operation
2310 $ref: '#/components/schemas/VideoChannel'
2312 summary: Update a video channel
2318 - $ref: '#/components/parameters/channelHandle'
2321 description: successful operation
2326 $ref: '#/components/schemas/VideoChannelUpdate'
2328 summary: Delete a video channel
2334 - $ref: '#/components/parameters/channelHandle'
2337 description: successful operation
2338 '/video-channels/{channelHandle}/videos':
2340 summary: List videos of a video channel
2345 - $ref: '#/components/parameters/channelHandle'
2346 - $ref: '#/components/parameters/categoryOneOf'
2347 - $ref: '#/components/parameters/isLive'
2348 - $ref: '#/components/parameters/tagsOneOf'
2349 - $ref: '#/components/parameters/tagsAllOf'
2350 - $ref: '#/components/parameters/licenceOneOf'
2351 - $ref: '#/components/parameters/languageOneOf'
2352 - $ref: '#/components/parameters/nsfw'
2353 - $ref: '#/components/parameters/filter'
2354 - $ref: '#/components/parameters/skipCount'
2355 - $ref: '#/components/parameters/start'
2356 - $ref: '#/components/parameters/count'
2357 - $ref: '#/components/parameters/videosSort'
2360 description: successful operation
2364 $ref: '#/components/schemas/VideoListResponse'
2365 '/video-channels/{channelHandle}/avatar/pick':
2367 summary: Update channel avatar
2373 - $ref: '#/components/parameters/channelHandle'
2376 description: successful operation
2383 $ref: '#/components/schemas/ActorImage'
2385 description: image file too large
2387 X-File-Maximum-Size:
2391 description: Maximum file size for the avatar
2394 multipart/form-data:
2399 description: The file to upload.
2404 contentType: image/png, image/jpeg
2405 '/video-channels/{channelHandle}/avatar':
2407 summary: Delete channel avatar
2413 - $ref: '#/components/parameters/channelHandle'
2416 description: successful operation
2419 '/video-channels/{channelHandle}/banner/pick':
2421 summary: Update channel banner
2427 - $ref: '#/components/parameters/channelHandle'
2430 description: successful operation
2437 $ref: '#/components/schemas/ActorImage'
2439 description: image file too large
2441 X-File-Maximum-Size:
2445 description: Maximum file size for the banner
2448 multipart/form-data:
2453 description: The file to upload.
2458 contentType: image/png, image/jpeg
2459 '/video-channels/{channelHandle}/banner':
2461 summary: Delete channel banner
2467 - $ref: '#/components/parameters/channelHandle'
2470 description: successful operation
2472 /video-playlists/privacies:
2474 summary: List available playlist privacies
2479 description: successful operation
2488 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2492 summary: List video playlists
2496 - $ref: '#/components/parameters/start'
2497 - $ref: '#/components/parameters/count'
2498 - $ref: '#/components/parameters/sort'
2501 description: successful operation
2513 $ref: '#/components/schemas/VideoPlaylist'
2515 summary: Create a video playlist
2516 description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
2523 description: successful operation
2535 $ref: '#/components/schemas/UUIDv4'
2538 multipart/form-data:
2543 description: Video playlist display name
2548 description: Video playlist thumbnail file
2552 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2554 description: Video playlist description
2557 description: Video channel in which the playlist will be published
2563 contentType: image/jpeg
2565 /video-playlists/{id}:
2567 summary: Get a video playlist
2571 - $ref: '#/components/parameters/idOrUUID'
2574 description: successful operation
2578 $ref: '#/components/schemas/VideoPlaylist'
2580 summary: Update a video playlist
2581 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2588 description: successful operation
2590 - $ref: '#/components/parameters/idOrUUID'
2593 multipart/form-data:
2598 description: Video playlist display name
2603 description: Video playlist thumbnail file
2607 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2609 description: Video playlist description
2612 description: Video channel in which the playlist will be published
2616 contentType: image/jpeg
2618 summary: Delete a video playlist
2624 - $ref: '#/components/parameters/idOrUUID'
2627 description: successful operation
2629 /video-playlists/{id}/videos:
2631 summary: 'List videos of a playlist'
2636 - $ref: '#/components/parameters/idOrUUID'
2639 description: successful operation
2643 $ref: '#/components/schemas/VideoListResponse'
2645 summary: 'Add a video in a playlist'
2652 - $ref: '#/components/parameters/idOrUUID'
2655 description: successful operation
2661 videoPlaylistElement:
2674 description: 'Video to add in the playlist'
2677 description: 'Start the video at this specific timestamp (in seconds)'
2680 description: 'Stop the video at this specific timestamp (in seconds)'
2684 /video-playlists/{id}/videos/reorder:
2686 summary: 'Reorder a playlist'
2692 - $ref: '#/components/parameters/idOrUUID'
2695 description: successful operation
2704 description: 'Start position of the element to reorder'
2706 insertAfterPosition:
2708 description: 'New position for the block to reorder, to add the block before the first element'
2712 description: 'How many element from `startPosition` to reorder'
2716 - insertAfterPosition
2718 /video-playlists/{id}/videos/{playlistElementId}:
2720 summary: 'Update a playlist element'
2726 - $ref: '#/components/parameters/idOrUUID'
2727 - $ref: '#/components/parameters/playlistElementId'
2730 description: successful operation
2739 description: 'Start the video at this specific timestamp (in seconds)'
2742 description: 'Stop the video at this specific timestamp (in seconds)'
2744 summary: 'Delete an element from a playlist'
2750 - $ref: '#/components/parameters/idOrUUID'
2751 - $ref: '#/components/parameters/playlistElementId'
2754 description: successful operation
2756 '/users/me/video-playlists/videos-exist':
2758 summary: 'Check video exists in my playlists'
2767 description: The video ids to check
2774 description: successful operation
2794 '/accounts/{name}/video-channels':
2796 summary: List video channels of an account
2801 - $ref: '#/components/parameters/name'
2804 description: include view statistics for the last 30 days (only if authentified as the account user)
2807 - $ref: '#/components/parameters/start'
2808 - $ref: '#/components/parameters/count'
2809 - $ref: '#/components/parameters/sort'
2812 description: successful operation
2823 $ref: '#/components/schemas/VideoChannel'
2824 '/accounts/{name}/ratings':
2826 summary: List ratings of an account
2832 - $ref: '#/components/parameters/name'
2833 - $ref: '#/components/parameters/start'
2834 - $ref: '#/components/parameters/count'
2835 - $ref: '#/components/parameters/sort'
2839 description: Optionally filter which ratings to retrieve
2847 description: successful operation
2853 $ref: '#/components/schemas/VideoRating'
2854 '/videos/{id}/comment-threads':
2856 summary: List threads of a video
2860 - $ref: '#/components/parameters/idOrUUID'
2861 - $ref: '#/components/parameters/start'
2862 - $ref: '#/components/parameters/count'
2863 - $ref: '#/components/parameters/commentsSort'
2866 description: successful operation
2870 $ref: '#/components/schemas/CommentThreadResponse'
2872 summary: Create a thread
2878 - $ref: '#/components/parameters/idOrUUID'
2881 description: successful operation
2885 $ref: '#/components/schemas/CommentThreadPostResponse'
2887 description: video does not exist
2896 description: 'Text comment'
2900 '/videos/{id}/comment-threads/{threadId}':
2902 summary: Get a thread
2906 - $ref: '#/components/parameters/idOrUUID'
2907 - $ref: '#/components/parameters/threadId'
2910 description: successful operation
2914 $ref: '#/components/schemas/VideoCommentThreadTree'
2915 '/videos/{id}/comments/{commentId}':
2917 summary: Reply to a thread of a video
2923 - $ref: '#/components/parameters/idOrUUID'
2924 - $ref: '#/components/parameters/commentId'
2927 description: successful operation
2931 $ref: '#/components/schemas/CommentThreadPostResponse'
2933 description: thread or video does not exist
2942 description: 'Text comment'
2947 summary: Delete a comment or a reply
2953 - $ref: '#/components/parameters/idOrUUID'
2954 - $ref: '#/components/parameters/commentId'
2957 description: successful operation
2959 description: cannot remove comment of another user
2961 description: comment or video does not exist
2963 description: comment is already deleted
2964 '/videos/{id}/rate':
2966 summary: Like/dislike a video
2972 - $ref: '#/components/parameters/idOrUUID'
2975 description: successful operation
2977 description: video does not exist
2982 summary: Search videos
2987 allowEmptyValue: false
2989 String to search. If the user can make a remote URI search, and the string is an URI then the
2990 PeerTube instance will fetch the remote object and add it to its database. Then,
2991 you can use the REST API to fetch the complete video information and interact with it.
2994 - $ref: '#/components/parameters/categoryOneOf'
2995 - $ref: '#/components/parameters/isLive'
2996 - $ref: '#/components/parameters/tagsOneOf'
2997 - $ref: '#/components/parameters/tagsAllOf'
2998 - $ref: '#/components/parameters/licenceOneOf'
2999 - $ref: '#/components/parameters/languageOneOf'
3000 - $ref: '#/components/parameters/nsfw'
3001 - $ref: '#/components/parameters/filter'
3002 - $ref: '#/components/parameters/skipCount'
3003 - $ref: '#/components/parameters/start'
3004 - $ref: '#/components/parameters/count'
3005 - $ref: '#/components/parameters/searchTarget'
3006 - $ref: '#/components/parameters/videosSearchSort'
3009 description: Get videos that are published after this date
3015 description: Get videos that are published before this date
3019 - name: originallyPublishedStartDate
3021 description: Get videos that are originally published after this date
3025 - name: originallyPublishedEndDate
3027 description: Get videos that are originally published before this date
3033 description: Get videos that have this minimum duration
3038 description: Get videos that have this maximum duration
3042 'searchTarget === search-index':
3043 $ref: '#/components/callbacks/searchIndex'
3046 description: successful operation
3050 $ref: '#/components/schemas/VideoListResponse'
3052 description: search index unavailable
3053 /search/video-channels:
3057 summary: Search channels
3063 String to search. If the user can make a remote URI search, and the string is an URI then the
3064 PeerTube instance will fetch the remote object and add it to its database. Then,
3065 you can use the REST API to fetch the complete channel information and interact with it.
3068 - $ref: '#/components/parameters/start'
3069 - $ref: '#/components/parameters/count'
3070 - $ref: '#/components/parameters/searchTarget'
3071 - $ref: '#/components/parameters/sort'
3073 'searchTarget === search-index':
3074 $ref: '#/components/callbacks/searchIndex'
3077 description: successful operation
3083 $ref: '#/components/schemas/VideoChannel'
3085 description: search index unavailable
3086 /blocklist/accounts:
3090 summary: List account blocks
3095 - $ref: '#/components/parameters/start'
3096 - $ref: '#/components/parameters/count'
3097 - $ref: '#/components/parameters/sort'
3100 description: successful operation
3104 summary: Block an account
3116 example: chocobozzz@example.org
3117 description: account to block, in the form `username@domain`
3122 description: successful operation
3124 description: self-blocking forbidden
3125 '/blocklist/accounts/{accountName}':
3129 summary: Unblock an account by its handle
3137 description: account to unblock, in the form `username@domain`
3142 description: successful operation
3144 description: account or account block does not exist
3149 summary: List server blocks
3154 - $ref: '#/components/parameters/start'
3155 - $ref: '#/components/parameters/count'
3156 - $ref: '#/components/parameters/sort'
3159 description: successful operation
3163 summary: Block a server
3176 description: server domain to block
3181 description: successful operation
3183 description: self-blocking forbidden
3184 '/blocklist/servers/{host}':
3188 summary: Unblock a server by its domain
3196 description: server domain to unblock
3202 description: successful operation
3204 description: account block does not exist
3208 - Instance Redundancy
3209 summary: Update a server redundancy policy
3217 description: server domain to mirror
3229 description: allow mirroring of the host's local videos
3234 description: successful operation
3236 description: server is not already known
3241 summary: List videos being mirrored
3249 description: direction of the mirror
3255 - $ref: '#/components/parameters/start'
3256 - $ref: '#/components/parameters/count'
3257 - $ref: '#/components/parameters/videoRedundanciesSort'
3260 description: successful operation
3266 $ref: '#/components/schemas/VideoRedundancy'
3270 summary: Mirror a video
3286 description: successful operation
3288 description: cannot mirror a local video
3290 description: video does not exist
3292 description: video is already mirrored
3293 /redundancy/videos/{redundancyId}:
3297 summary: Delete a mirror done on a video
3302 - name: redundancyId
3305 description: id of an existing redundancy on a video
3310 description: successful operation
3312 description: video redundancy not found
3313 '/feeds/video-comments.{format}':
3317 summary: List comments on videos
3322 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3335 description: 'limit listing to a specific video'
3340 description: 'limit listing to a specific account'
3345 description: 'limit listing to a specific account'
3348 - name: videoChannelId
3350 description: 'limit listing to a specific video channel'
3353 - name: videoChannelName
3355 description: 'limit listing to a specific video channel'
3360 description: successful operation
3365 default: 'max-age=900' # 15 min cache
3369 $ref: '#/components/schemas/VideoCommentsForXML'
3372 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3373 application/rss+xml:
3375 $ref: '#/components/schemas/VideoCommentsForXML'
3378 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3381 $ref: '#/components/schemas/VideoCommentsForXML'
3384 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3385 application/atom+xml:
3387 $ref: '#/components/schemas/VideoCommentsForXML'
3390 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3396 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3398 x-summary: field inconsistencies
3401 - videoId filter is mixed with a channel filter
3403 description: video, video channel or account not found
3405 description: accept header unsupported
3406 '/feeds/videos.{format}':
3410 summary: List videos
3415 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3428 description: 'limit listing to a specific account'
3433 description: 'limit listing to a specific account'
3436 - name: videoChannelId
3438 description: 'limit listing to a specific video channel'
3441 - name: videoChannelName
3443 description: 'limit listing to a specific video channel'
3446 - $ref: '#/components/parameters/sort'
3447 - $ref: '#/components/parameters/nsfw'
3448 - $ref: '#/components/parameters/filter'
3451 description: successful operation
3456 default: 'max-age=900' # 15 min cache
3460 $ref: '#/components/schemas/VideosForXML'
3463 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3464 application/rss+xml:
3466 $ref: '#/components/schemas/VideosForXML'
3469 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3472 $ref: '#/components/schemas/VideosForXML'
3475 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3476 application/atom+xml:
3478 $ref: '#/components/schemas/VideosForXML'
3481 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3487 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3489 description: video channel or account not found
3491 description: accept header unsupported
3492 '/feeds/subscriptions.{format}':
3497 summary: List videos of subscriptions tied to a token
3502 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3515 description: limit listing to a specific account
3521 description: private token allowing access
3525 - $ref: '#/components/parameters/sort'
3526 - $ref: '#/components/parameters/nsfw'
3527 - $ref: '#/components/parameters/filter'
3530 description: successful operation
3535 default: 'max-age=900' # 15 min cache
3539 $ref: '#/components/schemas/VideosForXML'
3540 application/rss+xml:
3542 $ref: '#/components/schemas/VideosForXML'
3545 $ref: '#/components/schemas/VideosForXML'
3546 application/atom+xml:
3548 $ref: '#/components/schemas/VideosForXML'
3553 description: accept header unsupported
3558 summary: List plugins
3571 - $ref: '#/components/parameters/start'
3572 - $ref: '#/components/parameters/count'
3573 - $ref: '#/components/parameters/sort'
3576 description: successful operation
3580 $ref: '#/components/schemas/PluginResponse'
3585 summary: List available plugins
3598 - name: currentPeerTubeEngine
3602 - $ref: '#/components/parameters/start'
3603 - $ref: '#/components/parameters/count'
3604 - $ref: '#/components/parameters/sort'
3607 description: successful operation
3611 $ref: '#/components/schemas/PluginResponse'
3613 description: plugin index unavailable
3618 summary: Install a plugin
3631 example: peertube-plugin-auth-ldap
3634 additionalProperties: false
3641 additionalProperties: false
3644 description: successful operation
3646 description: should have either `npmName` or `path` set
3651 summary: Update a plugin
3664 example: peertube-plugin-auth-ldap
3667 additionalProperties: false
3674 additionalProperties: false
3677 description: successful operation
3679 description: should have either `npmName` or `path` set
3681 description: existing plugin not found
3686 summary: Uninstall a plugin
3698 description: name of the plugin/theme in its package.json
3699 example: peertube-plugin-auth-ldap
3704 description: successful operation
3706 description: existing plugin not found
3711 summary: Get a plugin
3716 - $ref: '#/components/parameters/npmName'
3719 description: successful operation
3723 $ref: '#/components/schemas/Plugin'
3725 description: plugin not found
3726 /plugins/{npmName}/settings:
3730 summary: Set a plugin's settings
3735 - $ref: '#/components/parameters/npmName'
3744 additionalProperties: true
3747 description: successful operation
3749 description: plugin not found
3750 /plugins/{npmName}/public-settings:
3754 summary: Get a plugin's public settings
3756 - $ref: '#/components/parameters/npmName'
3759 description: successful operation
3764 additionalProperties: true
3766 description: plugin not found
3767 /plugins/{npmName}/registered-settings:
3771 summary: Get a plugin's registered settings
3776 - $ref: '#/components/parameters/npmName'
3779 description: successful operation
3784 additionalProperties: true
3786 description: plugin not found
3788 - url: 'https://peertube2.cpy.re/api/v1'
3789 description: Live Test Server (live data - latest nightly version)
3790 - url: 'https://peertube3.cpy.re/api/v1'
3791 description: Live Test Server (live data - latest RC version)
3792 - url: 'https://peertube.cpy.re/api/v1'
3793 description: Live Test Server (live data - stable version)
3800 description: Offset used to paginate results
3808 description: "Number of items to return"
3818 description: Sort column
3826 description: Plain text search, applied to various parts of the model depending on endpoint
3834 If the administrator enabled search index support, you can override the default search target.
3837 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
3838 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
3839 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
3840 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
3841 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
3842 * 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
3843 the data from the origin instance API
3853 description: Sort videos by criteria
3869 description: Sort videos by criteria
3884 description: Sort comments by criteria
3894 description: Sort blacklists by criteria
3910 description: Plain text search that will match with user usernames or emails
3917 description: Filter results down to (un)banned users
3924 description: Sort users by criteria
3935 description: Sort abuses by criteria
3942 videoRedundanciesSort:
3946 description: Sort abuses by criteria
3955 description: The username or handle of the account
3958 example: chocobozzz | chocobozzz@example.org
3963 description: The user id
3972 description: The object id or uuid
3978 - $ref: '#/components/schemas/UUIDv4'
3980 name: playlistElementId
3983 description: Playlist element id
3990 description: Abuse id
3994 name: abuseMessageId
3997 description: Abuse message id
4001 name: captionLanguage
4004 description: The caption language
4011 description: The video channel handle
4014 example: my_username | my_username@example.com
4016 name: subscriptionHandle
4019 description: The subscription handle
4022 example: my_username | my_username@example.com
4027 description: The thread id (root comment id)
4034 description: The comment id
4041 description: whether or not the video is a live
4048 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
4061 description: tag(s) of the video
4075 description: tag(s) of the video, where all should be present in the video
4088 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get)). Use `_unknown` to filter on videos that don't have a video language
4101 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
4114 description: if you don't need the `total` in the response
4125 description: whether to include nsfw videos, if any
4136 Special filters which might require special rights:
4137 * `local` - only videos local to the instance
4138 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4139 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4149 description: list of uris to check if each is part of the user subscriptions
4159 description: name of the plugin/theme on npmjs.com or in its package.json
4162 example: peertube-plugin-auth-ldap
4167 description: job type
4171 - activitypub-follow
4172 - activitypub-http-broadcast
4173 - activitypub-http-fetcher
4174 - activitypub-http-unicast
4180 - activitypub-refresher
4186 Authenticating via OAuth requires the following steps:
4187 - Have an activated account
4188 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
4189 Bearer Token for that account at `/api/v1/users/token`
4190 - Make authenticated requests, putting *Authorization: Bearer <token\>*
4191 - Profit, depending on the role assigned to the account
4193 Note that the __access token is valid for 1 day__ and, and is given
4194 along with a __refresh token valid for 2 weeks__.
4198 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
4201 moderator: Moderator scope
4207 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4208 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4209 # the regex above limits the length;
4210 # however, some tools might require explicit settings:
4214 VideoConstantNumber-Category:
4218 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
4221 VideoConstantNumber-Licence:
4225 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
4228 VideoConstantString-Language:
4232 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
4236 VideoPlaylistPrivacySet:
4242 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
4243 VideoPlaylistPrivacyConstant:
4246 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4250 VideoPlaylistTypeSet:
4255 description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
4256 VideoPlaylistTypeConstant:
4259 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4270 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
4271 VideoPrivacyConstant:
4274 $ref: '#/components/schemas/VideoPrivacySet'
4291 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4298 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4309 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4319 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4323 $ref: '#/components/schemas/AbuseStateSet'
4326 AbusePredefinedReasons:
4339 example: [spamOrMisleading]
4341 VideoResolutionConstant:
4345 description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
4350 VideoScheduledUpdate:
4353 $ref: '#/components/schemas/VideoPrivacySet'
4357 description: When to update the video
4377 - $ref: '#/components/schemas/ActorImage'
4378 VideoChannelSummary:
4395 - $ref: '#/components/schemas/ActorImage'
4407 - $ref: '#/components/schemas/Video'
4413 $ref: '#/components/schemas/VideoResolutionConstant'
4416 description: 'Video file size in bytes'
4419 description: Direct URL of the torrent file
4423 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4427 description: Direct URL of the video
4431 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4438 VideoStreamingPlaylists:
4451 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4452 VideoStreamingPlaylists-HLS:
4463 Video files associated to this playlist.
4465 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4467 $ref: '#/components/schemas/VideoFile'
4481 $ref: '#/components/schemas/UUIDv4'
4492 $ref: '#/components/schemas/UUIDv4'
4498 example: 2017-10-01T10:52:46.396Z
4499 description: time at which the video object was first drafted
4503 example: 2018-10-01T10:52:46.396Z
4504 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4508 example: 2021-05-04T08:01:01.502Z
4509 description: last time the video's metadata was modified
4510 originallyPublishedAt:
4513 example: 2010-10-01T10:52:46.396Z
4514 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4516 $ref: '#/components/schemas/VideoConstantNumber-Category'
4518 $ref: '#/components/schemas/VideoConstantNumber-Licence'
4520 $ref: '#/components/schemas/VideoConstantString-Language'
4522 $ref: '#/components/schemas/VideoPrivacyConstant'
4526 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4527 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4531 truncated description of the video, written in Markdown.
4532 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4536 description: duration of the video in seconds
4541 example: What is PeerTube?
4546 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4549 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4552 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4568 $ref: '#/components/schemas/VideoStateConstant'
4572 - $ref: '#/components/schemas/VideoScheduledUpdate'
4580 $ref: '#/components/schemas/AccountSummary'
4582 $ref: '#/components/schemas/VideoChannelSummary'
4591 - $ref: '#/components/schemas/Video'
4596 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4597 description: path at which to get the full description of maximum `10000` characters
4600 description: A text tell the audience how to support the video creator
4601 example: Please support my work on <insert crowdfunding plateform>! <3
4605 $ref: '#/components/schemas/VideoChannel'
4607 $ref: '#/components/schemas/Account'
4609 example: [flowers, gardening]
4629 $ref: '#/components/schemas/VideoFile'
4631 WebTorrent/raw video files. If WebTorrent is disabled on the server:
4633 - field will be empty
4634 - video files will be found in `streamingPlaylists[].files` field
4638 $ref: '#/components/schemas/VideoStreamingPlaylists'
4640 HLS playlists/manifest files. If HLS is disabled on the server:
4642 - field will be empty
4643 - video files will be found in `files` field
4644 FileRedundancyInformation:
4679 $ref: '#/components/schemas/UUIDv4'
4686 $ref: '#/components/schemas/FileRedundancyInformation'
4690 $ref: '#/components/schemas/FileRedundancyInformation'
4691 VideoImportStateConstant:
4699 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4711 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4715 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
4719 $ref: '#/components/schemas/VideoImportStateConstant'
4729 $ref: '#/components/schemas/Video'
4737 example: The video is a spam
4741 $ref: '#/components/schemas/AbusePredefinedReasons'
4743 $ref: '#/components/schemas/Account'
4745 $ref: '#/components/schemas/AbuseStateConstant'
4748 example: Decided to ban the server since it spams us regularly
4752 $ref: '#/components/schemas/VideoInfo'
4770 $ref: '#/components/schemas/AccountSummary'
4788 $ref: '#/components/schemas/UUIDv4'
4821 $ref: '#/components/schemas/UUIDv4'
4837 $ref: '#/components/schemas/UUIDv4'
4849 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
4851 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
4853 $ref: '#/components/schemas/AccountSummary'
4855 $ref: '#/components/schemas/VideoChannelSummary'
4879 totalRepliesFromVideoAuthor:
4884 $ref: '#/components/schemas/Account'
4885 VideoCommentThreadTree:
4888 $ref: '#/components/schemas/VideoComment'
4892 $ref: '#/components/schemas/VideoCommentThreadTree'
4896 $ref: '#/components/schemas/VideoConstantString-Language'
4951 $ref: '#/components/schemas/ActorImage'
4954 - $ref: '#/components/schemas/Actor'
4967 description: timestamp within the video, in seconds
5034 allowedForCurrentIP:
5036 requiresEmailVerification:
5240 requiresEmailVerification:
5265 allowAdditionalExtensions:
5335 $ref: '#/components/schemas/Actor'
5337 $ref: '#/components/schemas/Actor'
5340 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5353 PredefinedAbuseReasons:
5354 description: Reason categories that help triage reports
5386 - activitypub-http-unicast
5387 - activitypub-http-broadcast
5388 - activitypub-http-fetcher
5389 - activitypub-follow
5395 - activitypub-refresher
5399 additionalProperties: true
5402 additionalProperties: true
5426 VideoUploadRequestCommon:
5429 description: Video name
5432 description: Channel id that will contain this video
5435 $ref: '#/components/schemas/VideoPrivacySet'
5437 description: Video category
5441 description: Video licence
5445 description: Video language
5448 description: Video description
5451 description: Whether or not we wait transcoding before publish the video
5454 description: A text tell the audience how to support the video creator
5455 example: Please support my work on <insert crowdfunding plateform>! <3
5458 description: Whether or not this video contains sensitive content
5461 description: Video tags (maximum 5 tags each between 2 and 30 characters)
5471 description: Enable or disable comments for this video
5474 description: Enable or disable downloading for this video
5476 originallyPublishedAt:
5477 description: Date when the content was originally published
5481 $ref: '#/components/schemas/VideoScheduledUpdate'
5483 description: Video thumbnail file
5487 description: Video preview file
5493 VideoUploadRequestLegacy:
5495 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5501 description: Video file
5504 VideoUploadRequestResumable:
5506 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5512 description: Video filename including extension
5516 description: Video thumbnail file
5520 description: Video preview file
5523 VideoUploadResponse:
5532 $ref: '#/components/schemas/UUIDv4'
5533 CommentThreadResponse:
5542 $ref: '#/components/schemas/VideoComment'
5543 CommentThreadPostResponse:
5546 $ref: '#/components/schemas/VideoComment'
5556 $ref: '#/components/schemas/Video'
5564 description: The user username
5570 description: The user email
5573 description: Auth plugin to use to authenticate the user
5576 description: Theme enabled by this user
5579 description: Has the user confirmed their email address?
5581 $ref: '#/components/schemas/NSFWPolicy'
5584 description: Enable P2P in the player
5587 description: Automatically start playing the video on the watch page
5589 $ref: '#/components/schemas/UserRole'
5598 description: The user video quota
5601 description: The user daily video quota
5606 abusesAcceptedCount:
5612 noInstanceConfigWarningModal:
5623 $ref: '#/components/schemas/Account'
5627 $ref: '#/components/schemas/VideoChannel'
5632 description: The user username
5638 description: The user password. If the smtp server is configured, you can leave empty and an email will be sent
5644 description: The user email
5647 description: The user video quota
5650 description: The user daily video quota
5653 description: The user default channel username
5655 $ref: '#/components/schemas/UserRole'
5657 $ref: '#/components/schemas/UserAdminFlags'
5669 description: The user id
5673 description: The updated email of the user
5676 description: Set the email as verified
5679 description: The updated video quota of the user
5682 description: The updated daily video quota of the user
5686 description: The auth plugin to use to authenticate the user
5687 example: 'peertube-plugin-auth-saml2'
5689 $ref: '#/components/schemas/UserRole'
5691 $ref: '#/components/schemas/UserAdminFlags'
5699 description: Your new password
5705 description: Your new email
5708 description: Your new displayNSFW
5715 description: Your new autoPlayVideo
5725 description: Id of the video
5732 description: Rating of the video
5739 $ref: '#/components/schemas/Video'
5746 description: Rating of the video
5754 description: The username of the user
5757 pattern: '/^[a-z0-9._]{1,50}$/'
5761 description: The password of the user
5767 description: The email of the user
5770 description: The user display name
5778 description: The username for the default channel
5779 pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
5782 description: The display name for the default channel
5802 description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
5803 example: Please support my work on <insert crowdfunding plateform>! <3
5808 - $ref: '#/components/schemas/VideoChannelCommon'
5819 - $ref: '#/components/schemas/VideoChannelCommon'
5821 bulkVideosSupportUpdate:
5823 description: 'Update the support field for all videos of this channel'
5828 name: 'media:peerLink'
5837 - application/x-bittorrent
5843 name: 'media:content'
5874 VideoCommentsForXML:
5909 description: video watch page URL
5912 description: video canonical URL
5916 description: video publication date
5919 description: video description
5922 description: video description
5925 description: publisher user name
5928 description: video category (MRSS)
5931 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
5946 description: video embed path, relative to the canonical URL domain (MRSS)
5955 description: video watch path, relative to the canonical URL domain (MRSS)
5976 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
5977 'media:description':
5984 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
5987 description: main streamable file for the video
5997 - application/x-bittorrent
6006 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)
6009 - $ref: '#/components/schemas/MRSSPeerLink'
6010 - $ref: '#/components/schemas/MRSSGroupContent'
6011 NotificationSettingValue:
6032 Notification type, following the `UserNotificationType` enum:
6034 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6036 - `2` NEW_COMMENT_ON_MY_VIDEO
6038 - `3` NEW_ABUSE_FOR_MODERATORS
6040 - `4` BLACKLIST_ON_MY_VIDEO
6042 - `5` UNBLACKLIST_ON_MY_VIDEO
6044 - `6` MY_VIDEO_PUBLISHED
6046 - `7` MY_VIDEO_IMPORT_SUCCESS
6048 - `8` MY_VIDEO_IMPORT_ERROR
6050 - `9` NEW_USER_REGISTRATION
6054 - `11` COMMENT_MENTION
6056 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6058 - `13` NEW_INSTANCE_FOLLOWER
6060 - `14` AUTO_INSTANCE_FOLLOWING
6066 - $ref: '#/components/schemas/VideoInfo'
6070 $ref: '#/components/schemas/ActorInfo'
6079 $ref: '#/components/schemas/VideoInfo'
6100 $ref: '#/components/schemas/VideoInfo'
6102 $ref: '#/components/schemas/ActorInfo'
6111 - $ref: '#/components/schemas/VideoInfo'
6120 - $ref: '#/components/schemas/VideoInfo'
6124 - $ref: '#/components/schemas/ActorInfo'
6132 $ref: '#/components/schemas/ActorInfo'
6160 NotificationListResponse:
6169 $ref: '#/components/schemas/Notification'
6174 example: peertube-plugin-auth-ldap
6202 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6205 additionalProperties: true
6221 $ref: '#/components/schemas/Plugin'
6228 description: User can stream multiple times in a permanent live
6237 description: RTMP stream key to use to stream into this live video
6241 description: User can stream multiple times in a permanent live
6248 'https://search.example.org/api/v1/search/videos':
6250 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6253 description: successful operation
6257 $ref: '#/components/schemas/VideoListResponse'