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
17 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
18 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
19 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
20 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
22 - [Python](https://framagit.org/framasoft/peertube/clients/python)
23 - [Go](https://framagit.org/framasoft/peertube/clients/go)
24 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
26 See the [Quick Start guide](https://docs.joinpeertube.org/#/api-rest-getting-started) so you can play with the PeerTube API.
30 When you sign up for an account, you are given the possibility to generate
31 sessions, and authenticate using this session token. One session token can
32 currently be used at a time.
36 The API uses standard HTTP status codes to indicate the success or failure
37 of the API call. The body of the response will be JSON in the following
42 "code": "unauthorized_request", // example inner error code
43 "error": "Token is invalid." // example exposed error message
47 url: https://docs.joinpeertube.org/api-rest-reference.html
51 Using some features of PeerTube require authentication, for which Accounts
52 provide different levels of permission as well as associated user
53 information. Accounts also encompass remote accounts discovered across the federation.
56 Each server exposes public information regarding supported videos and
60 Jobs are long-running tasks enqueued and processed by the instance
61 itself. No additional worker registration is currently available.
62 - name: Instance Follows
64 Managing servers which the instance interacts with is crucial to the
65 concept of federation in PeerTube and external video indexation. The PeerTube
66 server then deals with inter-server ActivityPub operations and propagates
67 information across its social graph by posting activities to actors' inbox
71 Video abuses deal with reports of local or remote videos alike.
74 Operations dealing with listing, uploading, fetching or modifying videos.
77 The search helps to find _videos_ or _channels_ from within the instance and beyond.
78 Videos from other instances federated by the instance (that is, instances
79 followed by the instance) can be found via keywords and other criteria of
82 Administrators can also enable the use of a remote search system, indexing
83 videos and channels not could be not federated by the instance.
84 - name: Video Comments
86 Operations dealing with comments to a video. Comments are organized in
88 - name: Video Playlists
90 Operations dealing with playlists of videos. Playlists are bound to users
92 - name: Video Channels
94 Operations dealing with the creation, modification and listing of videos within a channel.
97 Operations dealing with blocking videos (removing them from view and
98 preventing interactions).
101 Like/dislike a video.
104 Server syndication feeds
121 - Video Ownership Change
132 - name: Instance Configuration
144 summary: Get an account
146 - $ref: '#/components/parameters/name'
149 description: successful operation
153 $ref: '#/components/schemas/Account'
155 description: account not found
156 '/accounts/{name}/videos':
161 summary: 'List videos of an account'
163 - $ref: '#/components/parameters/name'
164 - $ref: '#/components/parameters/categoryOneOf'
165 - $ref: '#/components/parameters/tagsOneOf'
166 - $ref: '#/components/parameters/tagsAllOf'
167 - $ref: '#/components/parameters/licenceOneOf'
168 - $ref: '#/components/parameters/languageOneOf'
169 - $ref: '#/components/parameters/nsfw'
170 - $ref: '#/components/parameters/filter'
171 - $ref: '#/components/parameters/skipCount'
172 - $ref: '#/components/parameters/start'
173 - $ref: '#/components/parameters/count'
174 - $ref: '#/components/parameters/videosSort'
177 description: successful operation
181 $ref: '#/components/schemas/VideoListResponse'
185 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
186 .then(function(response) {
187 return response.json()
188 }).then(function(data) {
194 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
200 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
202 http = Net::HTTP.new(uri.host, uri.port)
205 response = http.get(uri.request_uri)
207 puts JSON.parse(response.read_body)
212 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
220 summary: List accounts
222 - $ref: '#/components/parameters/start'
223 - $ref: '#/components/parameters/count'
224 - $ref: '#/components/parameters/sort'
227 description: successful operation
233 $ref: '#/components/schemas/Account'
238 summary: Get instance public configuration
241 description: successful operation
245 $ref: '#/components/schemas/ServerConfig'
248 summary: Get instance "About" information
253 description: successful operation
257 $ref: '#/components/schemas/ServerConfigAbout'
260 summary: Get instance runtime configuration
268 description: successful operation
272 $ref: '#/components/schemas/ServerConfigCustom'
274 summary: Set instance runtime configuration
282 description: successful operation
284 summary: Delete instance runtime configuration
292 description: successful operation
295 summary: List instance jobs
305 description: The state of the job
314 - $ref: '#/components/parameters/start'
315 - $ref: '#/components/parameters/count'
316 - $ref: '#/components/parameters/sort'
319 description: successful operation
325 $ref: '#/components/schemas/Job'
326 '/server/following/{host}':
333 summary: Unfollow a server
338 description: 'The host to unfollow '
343 description: successful operation
348 summary: List instance followers
350 - $ref: '#/components/parameters/start'
351 - $ref: '#/components/parameters/count'
352 - $ref: '#/components/parameters/sort'
355 description: successful operation
361 $ref: '#/components/schemas/Follow'
366 summary: List instances followed by the server
385 - $ref: '#/components/parameters/start'
386 - $ref: '#/components/parameters/count'
387 - $ref: '#/components/parameters/sort'
390 description: successful operation
396 $ref: '#/components/schemas/Follow'
403 summary: Follow a server
406 description: successful operation
408 description: cannot follow a non-HTTPS server
422 summary: Create a user
430 description: successful operation
434 $ref: '#/components/schemas/AddUserResponse'
439 $ref: '#/components/schemas/AddUser'
440 description: User to create
449 - $ref: '#/components/parameters/start'
450 - $ref: '#/components/parameters/count'
451 - $ref: '#/components/parameters/usersSort'
454 description: successful operation
460 $ref: '#/components/schemas/User'
463 summary: Delete a user
470 - $ref: '#/components/parameters/id'
473 description: successful operation
481 - $ref: '#/components/parameters/id'
484 description: successful operation
488 $ref: '#/components/schemas/User'
490 summary: Update a user
496 - $ref: '#/components/parameters/id'
499 description: successful operation
504 $ref: '#/components/schemas/UpdateUser'
508 summary: Register a user
513 description: successful operation
518 $ref: '#/components/schemas/RegisterUser'
522 summary: Get my user information
530 description: successful operation
536 $ref: '#/components/schemas/User'
538 summary: Update my user information
546 description: successful operation
551 $ref: '#/components/schemas/UpdateMe'
553 /users/me/videos/imports:
555 summary: Get video imports of my user
563 - $ref: '#/components/parameters/start'
564 - $ref: '#/components/parameters/count'
565 - $ref: '#/components/parameters/sort'
568 description: successful operation
572 $ref: '#/components/schemas/VideoImport'
573 /users/me/video-quota-used:
575 summary: Get my user used quota
583 description: successful operation
588 '/users/me/videos/{videoId}/rating':
590 summary: Get rate of my user for a video
600 description: 'The video id '
605 description: successful operation
609 $ref: '#/components/schemas/GetMeVideoRating'
612 summary: Get videos of my user
620 - $ref: '#/components/parameters/start'
621 - $ref: '#/components/parameters/count'
622 - $ref: '#/components/parameters/sort'
625 description: successful operation
629 $ref: '#/components/schemas/VideoListResponse'
630 /users/me/subscriptions:
632 summary: Get my user subscriptions
639 - $ref: '#/components/parameters/start'
640 - $ref: '#/components/parameters/count'
641 - $ref: '#/components/parameters/sort'
644 description: successful operation
646 summary: Add subscription to my user
654 description: successful operation
655 /users/me/subscriptions/exist:
657 summary: Get if subscriptions exist for my user
664 - $ref: '#/components/parameters/subscriptionsUris'
667 description: successful operation
672 /users/me/subscriptions/videos:
674 summary: List videos of subscriptions of my user
682 - $ref: '#/components/parameters/categoryOneOf'
683 - $ref: '#/components/parameters/tagsOneOf'
684 - $ref: '#/components/parameters/tagsAllOf'
685 - $ref: '#/components/parameters/licenceOneOf'
686 - $ref: '#/components/parameters/languageOneOf'
687 - $ref: '#/components/parameters/nsfw'
688 - $ref: '#/components/parameters/filter'
689 - $ref: '#/components/parameters/skipCount'
690 - $ref: '#/components/parameters/start'
691 - $ref: '#/components/parameters/count'
692 - $ref: '#/components/parameters/videosSort'
695 description: successful operation
699 $ref: '#/components/schemas/VideoListResponse'
700 '/users/me/subscriptions/{subscriptionHandle}':
702 summary: Get subscription of my user
709 - $ref: '#/components/parameters/subscriptionHandle'
712 description: successful operation
716 $ref: '#/components/schemas/VideoChannel'
718 summary: Delete subscription of my user
725 - $ref: '#/components/parameters/subscriptionHandle'
728 description: successful operation
729 /users/me/notifications:
731 summary: List my notifications
739 description: only list unread notifications
742 - $ref: '#/components/parameters/start'
743 - $ref: '#/components/parameters/count'
744 - $ref: '#/components/parameters/sort'
747 description: successful operation
751 $ref: '#/components/schemas/NotificationListResponse'
752 /users/me/notifications/read:
754 summary: Mark notifications as read by their id
767 description: ids of the notifications to mark as read
774 description: successful operation
775 /users/me/notifications/read-all:
777 summary: Mark all my notification as read
784 description: successful operation
785 /users/me/notification-settings:
787 summary: Update my notification settings
798 newVideoFromSubscription:
799 $ref: '#/components/schemas/NotificationSettingValue'
801 $ref: '#/components/schemas/NotificationSettingValue'
802 videoAbuseAsModerator:
803 $ref: '#/components/schemas/NotificationSettingValue'
804 videoAutoBlacklistAsModerator:
805 $ref: '#/components/schemas/NotificationSettingValue'
807 $ref: '#/components/schemas/NotificationSettingValue'
809 $ref: '#/components/schemas/NotificationSettingValue'
810 myVideoImportFinished:
811 $ref: '#/components/schemas/NotificationSettingValue'
813 $ref: '#/components/schemas/NotificationSettingValue'
815 $ref: '#/components/schemas/NotificationSettingValue'
817 $ref: '#/components/schemas/NotificationSettingValue'
819 $ref: '#/components/schemas/NotificationSettingValue'
820 autoInstanceFollowing:
821 $ref: '#/components/schemas/NotificationSettingValue'
824 description: successful operation
825 /users/me/avatar/pick:
827 summary: Update my user avatar
834 description: successful operation
838 $ref: '#/components/schemas/Avatar'
846 description: The file to upload.
851 contentType: image/png, image/jpeg
854 summary: List video ownership changes
856 - Video Ownership Change
861 description: successful operation
862 '/videos/ownership/{id}/accept':
864 summary: Accept ownership change request
866 - Video Ownership Change
870 - $ref: '#/components/parameters/idOrUUID'
873 description: successful operation
875 description: cannot terminate an ownership change of another user
877 description: video owneship change not found
878 '/videos/ownership/{id}/refuse':
880 summary: Refuse ownership change request
882 - Video Ownership Change
886 - $ref: '#/components/parameters/idOrUUID'
889 description: successful operation
891 description: cannot terminate an ownership change of another user
893 description: video owneship change not found
894 '/videos/{id}/give-ownership':
896 summary: Request ownership change
898 - Video Ownership Change
902 - $ref: '#/components/parameters/idOrUUID'
906 application/x-www-form-urlencoded:
916 description: successful operation
918 description: changing video ownership to a remote account is not supported yet
920 description: video not found
927 - $ref: '#/components/parameters/categoryOneOf'
928 - $ref: '#/components/parameters/tagsOneOf'
929 - $ref: '#/components/parameters/tagsAllOf'
930 - $ref: '#/components/parameters/licenceOneOf'
931 - $ref: '#/components/parameters/languageOneOf'
932 - $ref: '#/components/parameters/nsfw'
933 - $ref: '#/components/parameters/filter'
934 - $ref: '#/components/parameters/skipCount'
935 - $ref: '#/components/parameters/start'
936 - $ref: '#/components/parameters/count'
937 - $ref: '#/components/parameters/videosSort'
940 description: successful operation
944 $ref: '#/components/schemas/VideoListResponse'
947 summary: List available video categories
952 description: successful operation
961 summary: List available video licences
966 description: successful operation
975 summary: List available video languages
980 description: successful operation
989 summary: List available video privacies
994 description: successful operation
1003 summary: Update a video
1009 - $ref: '#/components/parameters/idOrUUID'
1012 description: successful operation
1015 multipart/form-data:
1020 description: Video thumbnail file
1024 description: Video preview file
1028 description: Video category
1031 description: Video licence
1034 description: Video language
1037 $ref: '#/components/schemas/VideoPrivacySet'
1039 description: Video description
1042 description: Whether or not we wait transcoding before publish the video
1045 description: Text describing how to support the video uploader
1048 description: Whether or not this video contains sensitive content
1051 description: Video name
1054 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1063 description: Enable or disable comments for this video
1065 originallyPublishedAt:
1066 description: Date when the content was originally published
1070 $ref: '#/components/schemas/VideoScheduledUpdate'
1073 contentType: image/jpeg
1075 contentType: image/jpeg
1077 summary: Get a video
1081 - $ref: '#/components/parameters/idOrUUID'
1084 description: successful operation
1088 $ref: '#/components/schemas/VideoDetails'
1090 summary: Delete a video
1096 - $ref: '#/components/parameters/idOrUUID'
1099 description: successful operation
1100 '/videos/{id}/description':
1102 summary: Get complete video description
1106 - $ref: '#/components/parameters/idOrUUID'
1109 description: successful operation
1114 '/videos/{id}/views':
1116 summary: Add a view to a video
1120 - $ref: '#/components/parameters/idOrUUID'
1123 description: successful operation
1124 '/videos/{id}/watching':
1126 summary: Set watching progress of a video
1132 - $ref: '#/components/parameters/idOrUUID'
1137 $ref: '#/components/schemas/UserWatchingVideo'
1141 description: successful operation
1144 summary: Upload a video
1151 description: successful operation
1155 $ref: '#/components/schemas/VideoUploadResponse'
1157 description: 'The user video quota is exceeded with this video.'
1159 description: 'Upload has timed out'
1161 description: 'Invalid input file.'
1164 multipart/form-data:
1169 description: Video file
1173 description: Channel id that will contain this video
1176 description: Video thumbnail file
1180 description: Video preview file
1184 $ref: '#/components/schemas/VideoPrivacySet'
1186 description: Video category
1189 description: Video licence
1192 description: Video language
1195 description: Video description
1198 description: Whether or not we wait transcoding before publish the video
1201 description: Text describing how to support the video uploader
1204 description: Whether or not this video contains sensitive content
1207 description: Video name
1210 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1220 description: Enable or disable comments for this video
1222 originallyPublishedAt:
1223 description: Date when the content was originally published
1227 $ref: '#/components/schemas/VideoScheduledUpdate'
1234 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1236 contentType: image/jpeg
1238 contentType: image/jpeg
1242 ## DEPENDENCIES: httpie, jq
1243 # pip install httpie
1244 USERNAME="<your_username>"
1245 PASSWORD="<your_password>"
1246 FILE_PATH="<your_file_path>"
1247 CHANNEL_ID="<your_channel_id>"
1250 API_PATH="https://peertube2.cpy.re/api/v1"
1252 client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1253 client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1254 token=$(http -b --form POST "$API_PATH/users/token" \
1255 client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
1256 username=$USERNAME \
1257 password=$PASSWORD \
1258 | jq -r ".access_token")
1260 http -b --form POST "$API_PATH/videos/upload" \
1261 videofile@$FILE_PATH \
1262 channelId=$CHANNEL_ID \
1264 "Authorization:Bearer $token"
1267 summary: Import a video
1268 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1275 multipart/form-data:
1280 description: Torrent File
1284 description: HTTP target URL
1287 description: Magnet URI
1290 description: Channel id that will contain this video
1293 description: Video thumbnail file
1297 description: Video preview file
1301 $ref: '#/components/schemas/VideoPrivacySet'
1303 description: Video category
1306 description: Video licence
1309 description: Video language
1312 description: Video description
1315 description: Whether or not we wait transcoding before publish the video
1318 description: Text describing how to support the video uploader
1321 description: Whether or not this video contains sensitive content
1324 description: Video name
1327 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1336 description: Enable or disable comments for this video
1339 $ref: '#/components/schemas/VideoScheduledUpdate'
1345 contentType: application/x-bittorrent
1347 contentType: image/jpeg
1349 contentType: image/jpeg
1352 description: successful operation
1356 $ref: '#/components/schemas/VideoUploadResponse'
1358 description: HTTP or Torrent/magnetURI import not enabled
1360 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1363 summary: List video abuses
1371 - $ref: '#/components/parameters/start'
1372 - $ref: '#/components/parameters/count'
1373 - $ref: '#/components/parameters/abusesSort'
1376 description: successful operation
1382 $ref: '#/components/schemas/VideoAbuse'
1383 '/videos/{id}/abuse':
1385 summary: Report an abuse
1392 - $ref: '#/components/parameters/idOrUUID'
1401 description: Reason why the user reports this video
1404 description: Reason categories that help triage reports
1419 description: Timestamp in the video that marks the beginning of the report
1422 description: Timestamp in the video that marks the ending of the report
1427 description: successful operation
1428 '/videos/{id}/abuse/{abuseId}':
1430 summary: Update an abuse
1439 description: successful operation
1441 description: video abuse not found
1443 - $ref: '#/components/parameters/idOrUUID'
1444 - $ref: '#/components/parameters/abuseId'
1452 $ref: '#/components/schemas/VideoAbuseStateSet'
1455 description: 'Update the comment of the video abuse for other admin/moderators'
1457 summary: Delete an abuse
1466 description: successful operation
1468 description: block not found
1470 - $ref: '#/components/parameters/idOrUUID'
1471 - $ref: '#/components/parameters/abuseId'
1473 '/videos/{id}/blacklist':
1475 summary: Block a video
1483 - $ref: '#/components/parameters/idOrUUID'
1486 description: successful operation
1488 summary: Unblock a video by its id
1496 - $ref: '#/components/parameters/idOrUUID'
1499 description: successful operation
1501 description: block not found
1506 summary: List video blocks
1512 - $ref: '#/components/parameters/start'
1513 - $ref: '#/components/parameters/count'
1514 - $ref: '#/components/parameters/blacklistsSort'
1517 description: successful operation
1523 $ref: '#/components/schemas/VideoBlacklist'
1524 /videos/{id}/captions:
1526 summary: List captions of a video
1530 - $ref: '#/components/parameters/idOrUUID'
1533 description: successful operation
1544 $ref: '#/components/schemas/VideoCaption'
1545 /videos/{id}/captions/{captionLanguage}:
1547 summary: Add or replace a video caption
1551 - $ref: '#/components/parameters/idOrUUID'
1552 - $ref: '#/components/parameters/captionLanguage'
1555 multipart/form-data:
1560 description: The file to upload.
1565 contentType: text/vtt, application/x-subrip, text/plain
1568 description: successful operation
1570 description: video or language not found
1572 summary: Delete a video caption
1576 - $ref: '#/components/parameters/idOrUUID'
1577 - $ref: '#/components/parameters/captionLanguage'
1580 description: successful operation
1582 description: video or language or caption for that language not found
1585 summary: List video channels
1589 - $ref: '#/components/parameters/start'
1590 - $ref: '#/components/parameters/count'
1591 - $ref: '#/components/parameters/sort'
1594 description: successful operation
1600 $ref: '#/components/schemas/VideoChannel'
1602 summary: Create a video channel
1609 description: successful operation
1614 $ref: '#/components/schemas/VideoChannelCreate'
1615 '/video-channels/{channelHandle}':
1617 summary: Get a video channel
1621 - $ref: '#/components/parameters/channelHandle'
1624 description: successful operation
1628 $ref: '#/components/schemas/VideoChannel'
1630 summary: Update a video channel
1636 - $ref: '#/components/parameters/channelHandle'
1639 description: successful operation
1644 $ref: '#/components/schemas/VideoChannelUpdate'
1646 summary: Delete a video channel
1652 - $ref: '#/components/parameters/channelHandle'
1655 description: successful operation
1656 '/video-channels/{channelHandle}/videos':
1658 summary: List videos of a video channel
1663 - $ref: '#/components/parameters/channelHandle'
1664 - $ref: '#/components/parameters/categoryOneOf'
1665 - $ref: '#/components/parameters/tagsOneOf'
1666 - $ref: '#/components/parameters/tagsAllOf'
1667 - $ref: '#/components/parameters/licenceOneOf'
1668 - $ref: '#/components/parameters/languageOneOf'
1669 - $ref: '#/components/parameters/nsfw'
1670 - $ref: '#/components/parameters/filter'
1671 - $ref: '#/components/parameters/skipCount'
1672 - $ref: '#/components/parameters/start'
1673 - $ref: '#/components/parameters/count'
1674 - $ref: '#/components/parameters/videosSort'
1677 description: successful operation
1681 $ref: '#/components/schemas/VideoListResponse'
1683 /video-playlists/privacies:
1685 summary: List available playlist privacies
1690 description: successful operation
1700 summary: List video playlists
1704 - $ref: '#/components/parameters/start'
1705 - $ref: '#/components/parameters/count'
1706 - $ref: '#/components/parameters/sort'
1709 description: successful operation
1715 $ref: '#/components/schemas/VideoPlaylist'
1717 summary: Create a video playlist
1718 description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
1725 description: successful operation
1740 multipart/form-data:
1745 description: Video playlist display name
1748 description: Video playlist thumbnail file
1752 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
1754 description: Video playlist description
1757 description: Video channel in which the playlist will be published
1762 /video-playlists/{id}:
1764 summary: Get a video playlist
1768 - $ref: '#/components/parameters/idOrUUID'
1771 description: successful operation
1775 $ref: '#/components/schemas/VideoPlaylist'
1777 summary: Update a video playlist
1778 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
1785 description: successful operation
1787 - $ref: '#/components/parameters/idOrUUID'
1790 multipart/form-data:
1795 description: Video playlist display name
1798 description: Video playlist thumbnail file
1802 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
1804 description: Video playlist description
1807 description: Video channel in which the playlist will be published
1810 summary: Delete a video playlist
1816 - $ref: '#/components/parameters/idOrUUID'
1819 description: successful operation
1821 /video-playlists/{id}/videos:
1823 summary: 'List videos of a playlist'
1828 - $ref: '#/components/parameters/idOrUUID'
1831 description: successful operation
1835 $ref: '#/components/schemas/VideoListResponse'
1837 summary: 'Add a video in a playlist'
1844 - $ref: '#/components/parameters/idOrUUID'
1847 description: successful operation
1853 videoPlaylistElement:
1866 description: 'Video to add in the playlist'
1869 description: 'Start the video at this specific timestamp (in seconds)'
1872 description: 'Stop the video at this specific timestamp (in seconds)'
1876 /video-playlists/{id}/videos/reorder:
1878 summary: 'Reorder a playlist'
1884 - $ref: '#/components/parameters/idOrUUID'
1887 description: successful operation
1896 description: 'Start position of the element to reorder'
1898 insertAfterPosition:
1900 description: 'New position for the block to reorder, to add the block before the first element'
1904 description: 'How many element from `startPosition` to reorder'
1908 - insertAfterPosition
1910 /video-playlists/{id}/videos/{playlistElementId}:
1912 summary: 'Update a playlist element'
1918 - $ref: '#/components/parameters/idOrUUID'
1919 - $ref: '#/components/parameters/playlistElementId'
1922 description: successful operation
1931 description: 'Start the video at this specific timestamp (in seconds)'
1934 description: 'Stop the video at this specific timestamp (in seconds)'
1936 summary: 'Delete an element from a playlist'
1942 - $ref: '#/components/parameters/idOrUUID'
1943 - $ref: '#/components/parameters/playlistElementId'
1946 description: successful operation
1948 '/users/me/video-playlists/videos-exist':
1950 summary: 'Check video exists in my playlists'
1959 description: The video ids to check
1966 description: successful operation
1986 '/accounts/{name}/video-channels':
1988 summary: List video channels of an account
1993 - $ref: '#/components/parameters/name'
1996 description: successful operation
2002 $ref: '#/components/schemas/VideoChannel'
2003 '/accounts/{name}/ratings':
2005 summary: List ratings of an account
2011 - $ref: '#/components/parameters/name'
2012 - $ref: '#/components/parameters/start'
2013 - $ref: '#/components/parameters/count'
2014 - $ref: '#/components/parameters/sort'
2018 description: Optionally filter which ratings to retrieve
2026 description: successful operation
2032 $ref: '#/components/schemas/VideoRating'
2033 '/videos/{id}/comment-threads':
2035 summary: List threads of a video
2039 - $ref: '#/components/parameters/idOrUUID'
2040 - $ref: '#/components/parameters/start'
2041 - $ref: '#/components/parameters/count'
2042 - $ref: '#/components/parameters/commentsSort'
2045 description: successful operation
2049 $ref: '#/components/schemas/CommentThreadResponse'
2051 summary: Create a thread
2057 - $ref: '#/components/parameters/idOrUUID'
2060 description: successful operation
2064 $ref: '#/components/schemas/CommentThreadPostResponse'
2073 description: 'Text comment'
2077 '/videos/{id}/comment-threads/{threadId}':
2079 summary: Get a thread
2083 - $ref: '#/components/parameters/idOrUUID'
2084 - $ref: '#/components/parameters/threadId'
2087 description: successful operation
2091 $ref: '#/components/schemas/VideoCommentThreadTree'
2092 '/videos/{id}/comments/{commentId}':
2094 summary: Reply to a thread of a video
2100 - $ref: '#/components/parameters/idOrUUID'
2101 - $ref: '#/components/parameters/commentId'
2104 description: successful operation
2108 $ref: '#/components/schemas/CommentThreadPostResponse'
2117 description: 'Text comment'
2122 summary: Delete a comment or a reply
2128 - $ref: '#/components/parameters/idOrUUID'
2129 - $ref: '#/components/parameters/commentId'
2132 description: successful operation
2133 '/videos/{id}/rate':
2135 summary: Like/dislike a video
2141 - $ref: '#/components/parameters/idOrUUID'
2144 description: successful operation
2149 summary: Search videos
2151 - $ref: '#/components/parameters/categoryOneOf'
2152 - $ref: '#/components/parameters/tagsOneOf'
2153 - $ref: '#/components/parameters/tagsAllOf'
2154 - $ref: '#/components/parameters/licenceOneOf'
2155 - $ref: '#/components/parameters/languageOneOf'
2156 - $ref: '#/components/parameters/nsfw'
2157 - $ref: '#/components/parameters/filter'
2158 - $ref: '#/components/parameters/skipCount'
2159 - $ref: '#/components/parameters/start'
2160 - $ref: '#/components/parameters/count'
2161 - $ref: '#/components/parameters/searchTarget'
2162 - $ref: '#/components/parameters/videosSearchSort'
2167 String to search. If the user can make a remote URI search, and the string is an URI then the
2168 PeerTube instance will fetch the remote object and add it to its database. Then,
2169 you can use the REST API to fetch the complete video information and interact with it.
2175 description: Get videos that are published after this date
2182 description: Get videos that are published before this date
2186 - name: originallyPublishedStartDate
2189 description: Get videos that are originally published after this date
2193 - name: originallyPublishedEndDate
2196 description: Get videos that are originally published before this date
2203 description: Get videos that have this minimum duration
2209 description: Get videos that have this maximum duration
2214 description: successful operation
2218 $ref: '#/components/schemas/VideoListResponse'
2219 /search/video-channels:
2223 summary: Search channels
2225 - $ref: '#/components/parameters/start'
2226 - $ref: '#/components/parameters/count'
2227 - $ref: '#/components/parameters/searchTarget'
2228 - $ref: '#/components/parameters/sort'
2233 String to search. If the user can make a remote URI search, and the string is an URI then the
2234 PeerTube instance will fetch the remote object and add it to its database. Then,
2235 you can use the REST API to fetch the complete channel information and interact with it.
2240 description: successful operation
2246 $ref: '#/components/schemas/VideoChannel'
2247 /blocklist/accounts:
2251 summary: List account blocks
2256 - $ref: '#/components/parameters/start'
2257 - $ref: '#/components/parameters/count'
2258 - $ref: '#/components/parameters/sort'
2261 description: successful operation
2265 summary: Block an account
2277 description: account to block, in the form `username@domain`
2282 description: successful operation
2284 description: self-blocking forbidden
2285 '/blocklist/accounts/{accountName}':
2289 summary: Unblock an account by its handle
2297 description: account to unblock, in the form `username@domain`
2302 description: successful operation
2304 description: account or account block does not exist
2309 summary: List server blocks
2314 - $ref: '#/components/parameters/start'
2315 - $ref: '#/components/parameters/count'
2316 - $ref: '#/components/parameters/sort'
2319 description: successful operation
2323 summary: Block a server
2335 description: server domain to block
2340 description: successful operation
2342 description: self-blocking forbidden
2343 '/blocklist/servers/{host}':
2347 summary: Unblock a server by its domain
2355 description: server domain to unblock
2360 description: successful operation
2362 description: account block does not exist
2363 '/feeds/video-comments.{format}':
2367 summary: List comments on videos
2369 - url: 'https://peertube2.cpy.re'
2370 description: Live Test Server (live data - latest nightly version)
2371 - url: 'https://peertube3.cpy.re'
2372 description: Live Test Server (live data - latest RC version)
2373 - url: 'https://peertube.cpy.re'
2374 description: Live Test Server (live data - stable version)
2379 description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
2392 description: 'limit listing to a specific video'
2397 description: successful operation
2402 default: 'max-age=900' # 15 min cache
2406 $ref: '#/components/schemas/VideoCommentsForXML'
2407 application/rss+xml:
2409 $ref: '#/components/schemas/VideoCommentsForXML'
2412 $ref: '#/components/schemas/VideoCommentsForXML'
2413 application/atom+xml:
2415 $ref: '#/components/schemas/VideoCommentsForXML'
2420 description: accept header unsupported
2421 '/feeds/videos.{format}':
2425 summary: List videos
2427 - url: 'https://peertube2.cpy.re'
2428 description: Live Test Server (live data - latest nightly version)
2429 - url: 'https://peertube3.cpy.re'
2430 description: Live Test Server (live data - latest RC version)
2431 - url: 'https://peertube.cpy.re'
2432 description: Live Test Server (live data - stable version)
2437 description: 'format expected (we focus on making `rss` the most featureful ; it serves Media RSS)'
2450 description: 'limit listing to a specific account'
2455 description: 'limit listing to a specific account'
2458 - name: videoChannelId
2460 description: 'limit listing to a specific video channel'
2463 - name: videoChannelName
2465 description: 'limit listing to a specific video channel'
2470 description: successful operation
2475 default: 'max-age=900' # 15 min cache
2479 $ref: '#/components/schemas/VideosForXML'
2480 application/rss+xml:
2482 $ref: '#/components/schemas/VideosForXML'
2485 $ref: '#/components/schemas/VideosForXML'
2486 application/atom+xml:
2488 $ref: '#/components/schemas/VideosForXML'
2493 description: accept header unsupported
2495 - url: 'https://peertube2.cpy.re/api/v1'
2496 description: Live Test Server (live data - latest nightly version)
2497 - url: 'https://peertube3.cpy.re/api/v1'
2498 description: Live Test Server (live data - latest RC version)
2499 - url: 'https://peertube.cpy.re/api/v1'
2500 description: Live Test Server (live data - stable version)
2507 description: Offset used to paginate results
2514 description: "Number of items to return"
2523 description: Sort column (`-createdAt` for example)
2531 If the administrator enabled search index support, you can override the default search target.
2534 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
2535 It means the instance may not know the objects you fetched. If you want to load video/channel information:
2536 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
2537 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
2538 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
2539 * If the current user has not the ability to make a remote URI search, then redirect the user on the origin instance or fetch
2540 the data from the origin instance API
2550 description: Sort videos by criteria
2565 description: Sort videos by criteria
2580 description: Sort comments by criteria
2590 description: Sort blacklists by criteria
2606 description: Sort users by criteria
2617 description: Sort abuses by criteria
2629 The name of the account (`chocobozzz` or `chocobozzz@example.org` for
2637 description: The user id
2644 description: The object id or uuid
2648 name: playlistElementId
2651 description: Playlist element id
2658 description: Video abuse id
2662 name: captionLanguage
2665 description: The caption language
2672 description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
2676 name: subscriptionHandle
2679 description: "The subscription handle (example: 'my_username@example.com' or 'my_username')"
2686 description: The thread id (root comment id)
2693 description: The comment id
2700 description: category id of the video (see /videos/categories)
2713 description: tag(s) of the video
2726 description: tag(s) of the video, where all should be present in the video
2739 description: language id of the video (see /videos/languages). Use `_unknown` to filter on videos that don't have a video language
2752 description: licence id of the video (see /videos/licences)
2765 description: if you don't need the `total` in the response
2776 description: whether to include nsfw videos, if any
2787 Special filters (local for instance) which might require special rights:
2788 * `local` - only videos local to the instance
2789 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
2799 description: list of uris to check if each is part of the user subscriptions
2807 In the header: *Authorization: Bearer <token\>*
2810 Authenticating via OAuth requires the following steps:
2813 - Have an account with sufficient authorization levels
2815 - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
2818 - Make Authenticated Requests
2822 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
2825 moderator: Moderator scope
2828 VideoConstantNumber:
2834 VideoConstantString:
2841 VideoPlaylistPrivacySet:
2847 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
2848 VideoPlaylistPrivacyConstant:
2851 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2855 VideoPlaylistTypeSet:
2860 description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
2861 VideoPlaylistTypeConstant:
2864 $ref: '#/components/schemas/VideoPlaylistTypeSet'
2875 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
2876 VideoPrivacyConstant:
2879 $ref: '#/components/schemas/VideoPrivacySet'
2896 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
2906 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
2916 description: 'The video playlist privacy (Pending = `1`, Rejected = `2`, Accepted = `3`)'
2917 VideoAbuseStateConstant:
2920 $ref: '#/components/schemas/VideoAbuseStateSet'
2923 VideoAbusePredefinedReasons:
2937 VideoResolutionConstant:
2941 description: 'Video resolution (240, 360, 720 ...)'
2944 VideoScheduledUpdate:
2947 $ref: '#/components/schemas/VideoPrivacySet'
2951 description: When to update the video
2969 - $ref: '#/components/schemas/Avatar'
2970 VideoChannelSummary:
2985 - $ref: '#/components/schemas/Avatar'
2997 - $ref: '#/components/schemas/Video'
3003 $ref: '#/components/schemas/VideoResolutionConstant'
3006 description: 'Video file size in bytes'
3019 VideoStreamingPlaylists:
3027 description: 'Playlist type (HLS = `1`)'
3035 $ref: '#/components/schemas/VideoFile'
3063 originallyPublishedAt:
3066 $ref: '#/components/schemas/VideoConstantNumber'
3068 $ref: '#/components/schemas/VideoConstantNumber'
3070 $ref: '#/components/schemas/VideoConstantString'
3072 $ref: '#/components/schemas/VideoPrivacyConstant'
3099 $ref: '#/components/schemas/VideoStateConstant'
3103 - $ref: '#/components/schemas/VideoScheduledUpdate'
3111 $ref: '#/components/schemas/AccountSummary'
3113 $ref: '#/components/schemas/VideoChannelSummary'
3122 - $ref: '#/components/schemas/Video'
3130 $ref: '#/components/schemas/VideoChannel'
3132 $ref: '#/components/schemas/Account'
3140 $ref: '#/components/schemas/VideoFile'
3152 $ref: '#/components/schemas/VideoStreamingPlaylists'
3153 VideoImportStateConstant:
3161 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
3178 $ref: '#/components/schemas/VideoImportStateConstant'
3188 $ref: '#/components/schemas/Video'
3196 $ref: '#/components/schemas/VideoAbusePredefinedReasons'
3198 $ref: '#/components/schemas/Account'
3200 $ref: '#/components/schemas/VideoAbuseStateConstant'
3276 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
3278 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
3280 $ref: '#/components/schemas/AccountSummary'
3282 $ref: '#/components/schemas/VideoChannelSummary'
3301 totalRepliesFromVideoAuthor:
3306 $ref: '#/components/schemas/Account'
3307 VideoCommentThreadTree:
3310 $ref: '#/components/schemas/VideoComment'
3314 $ref: '#/components/schemas/VideoCommentThreadTree'
3318 $ref: '#/components/schemas/VideoConstantString'
3364 $ref: '#/components/schemas/Avatar'
3367 - $ref: '#/components/schemas/Actor'
3385 description: 'Theme enabled by this user'
3388 description: 'Has the user confirmed their email address?'
3390 $ref: '#/components/schemas/NSFWPolicy'
3395 description: 'Automatically start playing the video on the watch page'
3397 $ref: '#/components/schemas/UserRole'
3412 videoAbusesAcceptedCount:
3414 videoAbusesCreatedCount:
3418 noInstanceConfigWarningModal:
3429 $ref: '#/components/schemas/Account'
3433 $ref: '#/components/schemas/VideoChannel'
3503 allowedForCurrentIP:
3505 requiresEmailVerification:
3708 requiresEmailVerification:
3732 allowAdditionalExtensions:
3800 $ref: '#/components/schemas/Actor'
3802 $ref: '#/components/schemas/Actor'
3844 VideoUploadResponse:
3853 CommentThreadResponse:
3860 $ref: '#/components/schemas/VideoComment'
3861 CommentThreadPostResponse:
3864 $ref: '#/components/schemas/VideoComment'
3872 $ref: '#/components/schemas/Video'
3877 description: 'The user username'
3882 description: 'The user password. If the smtp server is configured, you can leave empty and an email will be sent'
3887 description: 'The user email. MUST be in the format of an email address.'
3890 description: 'The user video quota'
3893 description: 'The user daily video quota'
3895 $ref: '#/components/schemas/UserRole'
3907 description: 'The user id'
3910 description: 'The updated email of the user'
3913 description: 'The updated video quota of the user'
3916 description: 'The updated daily video quota of the user'
3918 $ref: '#/components/schemas/UserRole'
3929 description: 'Your new password'
3932 description: 'Your new email'
3935 description: 'Your new displayNSFW'
3938 description: 'Your new autoPlayVideo'
3948 description: 'Id of the video'
3951 description: 'Rating of the video'
3958 $ref: '#/components/schemas/Video'
3961 description: 'Rating of the video'
3969 description: 'The username of the user'
3972 description: 'The password of the user'
3975 description: 'The email of the user'
3978 description: 'The user display name'
3984 description: 'The name for the default channel'
3987 description: 'The display name for the default channel'
4003 description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
4015 description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
4016 bulkVideosSupportUpdate:
4018 description: 'Update the support field for all videos of this channel'
4023 name: 'media:peerLink'
4032 - application/x-bittorrent
4038 name: 'media:content'
4068 VideoCommentsForXML:
4101 description: video watch page URL
4104 description: video canonical URL
4108 description: video publication date
4111 description: video description
4114 description: video description
4117 description: publisher user name
4120 description: video category (MRSS)
4123 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
4137 description: video embed path, relative to the canonical URL domain (MRSS)
4145 description: video watch path, relative to the canonical URL domain (MRSS)
4165 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
4166 'media:description':
4173 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
4176 description: main streamable file for the video
4185 - application/x-bittorrent
4194 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)
4197 - $ref: '#/components/schemas/MRSSPeerLink'
4198 - $ref: '#/components/schemas/MRSSGroupContent'
4199 NotificationSettingValue:
4217 Notification type, following the `UserNotificationType` enum:
4218 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
4219 - `2` NEW_COMMENT_ON_MY_VIDEO
4220 - `3` NEW_VIDEO_ABUSE_FOR_MODERATORS
4221 - `4` BLACKLIST_ON_MY_VIDEO
4222 - `5` UNBLACKLIST_ON_MY_VIDEO
4223 - `6` MY_VIDEO_PUBLISHED
4224 - `7` MY_VIDEO_IMPORT_SUCCESS
4225 - `8` MY_VIDEO_IMPORT_ERROR
4226 - `9` NEW_USER_REGISTRATION
4228 - `11` COMMENT_MENTION
4229 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
4230 - `13` NEW_INSTANCE_FOLLOWER
4231 - `14` AUTO_INSTANCE_FOLLOWING
4237 - $ref: '#/components/schemas/VideoInfo'
4241 $ref: '#/components/schemas/ActorInfo'
4250 $ref: '#/components/schemas/VideoInfo'
4269 $ref: '#/components/schemas/VideoInfo'
4271 $ref: '#/components/schemas/ActorInfo'
4280 - $ref: '#/components/schemas/VideoInfo'
4289 - $ref: '#/components/schemas/VideoInfo'
4293 - $ref: '#/components/schemas/ActorInfo'
4301 $ref: '#/components/schemas/ActorInfo'
4328 NotificationListResponse:
4335 $ref: '#/components/schemas/Notification'