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 configured
56 | Endpoint | Calls | Time frame |
57 |-------------------------|------------------|---------------------------|
58 | `/*` | 50 | 10 seconds |
59 | `POST /users/token` | 15 | 5 minutes |
60 | `POST /users/register` | 2¹ | 5 minutes |
61 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
63 Depending on the endpoint, ¹failed requests are not taken into account. A service
64 limit is announced by a `429 Too Many Requests` status code.
66 You can get details about the current state of your rate limit by reading the
69 | Header | Description |
70 |-------------------------|------------------------------------------------------------|
71 | X-RateLimit-Limit | Number of max requests allowed in the current time period |
72 | X-RateLimit-Remaining | Number of remaining requests in the current time period |
73 | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp |
74 | Retry-After | Seconds to delay after the first `429` is received |
76 url: https://docs.joinpeertube.org/api-rest-reference.html
80 Accounts encompass remote accounts discovered across the federation,
81 and correspond to the main Actor, along with video channels a user can create, which
84 When a comment is posted, it is done with your Account's Actor.
87 Using some features of PeerTube require authentication, for which User
88 provide different levels of permission as well as associated user
89 information. Each user has a corresponding local Account for federation.
92 Operations related to your own User, when logged-in.
93 - name: My Subscriptions
95 Operations related to your subscriptions to video channels, their
96 new videos, and how to keep up to date with their latest publications!
99 Operations related to your watch history.
100 - name: My Notifications
102 Notifications following new videos, follows or reports. They allow you
103 to keep track of the interactions and overall important information that
104 concerns you. You MAY set per-notification type delivery preference, to
105 receive the info either by mail, by in-browser notification or both.
108 Each server exposes public information regarding supported videos and
112 Jobs are long-running tasks enqueued and processed by the instance
113 itself. No additional worker registration is currently available.
114 - name: Instance Follows
116 Managing servers which the instance interacts with is crucial to the
117 concept of federation in PeerTube and external video indexation. The PeerTube
118 server then deals with inter-server ActivityPub operations and propagates
119 information across its social graph by posting activities to actors' inbox
122 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
123 - name: Instance Redundancy
125 Redundancy is part of the inter-server solidarity that PeerTube fosters.
126 Manage the list of instances you wish to help by seeding their videos according
127 to the policy of video selection of your choice. Note that you have a similar functionality
128 to mirror individual videos, see `Video Mirroring`.
130 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
133 Managing plugins installed from a local path or from NPM, or search for new ones.
135 url: https://docs.joinpeertube.org/api-plugins
138 Abuses deal with reports of local or remote videos/comments/accounts alike.
141 Operations dealing with listing, uploading, fetching or modifying videos.
144 The search helps to find _videos_ or _channels_ from within the instance and beyond.
145 Videos from other instances federated by the instance (that is, instances
146 followed by the instance) can be found via keywords and other criteria of
149 Administrators can also enable the use of a remote search system, indexing
150 videos and channels not could be not federated by the instance.
151 - name: Video Comments
153 Operations dealing with comments to a video. Comments are organized in
155 - name: Video Playlists
157 Operations dealing with playlists of videos. Playlists are bound to users
159 - name: Video Channels
161 Operations dealing with the creation, modification and listing of videos within a channel.
164 Operations dealing with blocking videos (removing them from view and
165 preventing interactions).
168 Like/dislike a video.
171 Server syndication feeds
189 - Video Ownership Change
202 - name: Instance Configuration
206 - Instance Redundancy
216 summary: Get an account
218 - $ref: '#/components/parameters/name'
221 description: successful operation
225 $ref: '#/components/schemas/Account'
227 description: account not found
228 '/accounts/{name}/videos':
233 summary: 'List videos of an account'
235 - $ref: '#/components/parameters/name'
236 - $ref: '#/components/parameters/categoryOneOf'
237 - $ref: '#/components/parameters/isLive'
238 - $ref: '#/components/parameters/tagsOneOf'
239 - $ref: '#/components/parameters/tagsAllOf'
240 - $ref: '#/components/parameters/licenceOneOf'
241 - $ref: '#/components/parameters/languageOneOf'
242 - $ref: '#/components/parameters/nsfw'
243 - $ref: '#/components/parameters/filter'
244 - $ref: '#/components/parameters/skipCount'
245 - $ref: '#/components/parameters/start'
246 - $ref: '#/components/parameters/count'
247 - $ref: '#/components/parameters/videosSort'
250 description: successful operation
254 $ref: '#/components/schemas/VideoListResponse'
258 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
259 .then(function(response) {
260 return response.json()
261 }).then(function(data) {
267 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
273 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
275 http = Net::HTTP.new(uri.host, uri.port)
278 response = http.get(uri.request_uri)
280 puts JSON.parse(response.read_body)
285 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
293 summary: List accounts
295 - $ref: '#/components/parameters/start'
296 - $ref: '#/components/parameters/count'
297 - $ref: '#/components/parameters/sort'
300 description: successful operation
306 $ref: '#/components/schemas/Account'
311 summary: Get instance public configuration
314 description: successful operation
318 $ref: '#/components/schemas/ServerConfig'
321 summary: Get instance "About" information
326 description: successful operation
330 $ref: '#/components/schemas/ServerConfigAbout'
333 summary: Get instance runtime configuration
341 description: successful operation
345 $ref: '#/components/schemas/ServerConfigCustom'
347 summary: Set instance runtime configuration
355 description: successful operation
357 x-summary: field inconsistencies
360 - the emailer is disabled and the instance is open to registrations
361 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
363 summary: Delete instance runtime configuration
371 description: successful operation
374 summary: List instance jobs
384 description: The state of the job ('' for for no filter)
394 - $ref: '#/components/parameters/jobType'
395 - $ref: '#/components/parameters/start'
396 - $ref: '#/components/parameters/count'
397 - $ref: '#/components/parameters/sort'
400 description: successful operation
413 $ref: '#/components/schemas/Job'
414 '/server/following/{host}':
421 summary: Unfollow a server
426 description: 'The host to unfollow '
432 description: successful operation
437 summary: List instance followers
439 - $ref: '#/components/parameters/start'
440 - $ref: '#/components/parameters/count'
441 - $ref: '#/components/parameters/sort'
444 description: successful operation
450 $ref: '#/components/schemas/Follow'
455 summary: List instances followed by the server
474 - $ref: '#/components/parameters/start'
475 - $ref: '#/components/parameters/count'
476 - $ref: '#/components/parameters/sort'
479 description: successful operation
485 $ref: '#/components/schemas/Follow'
492 summary: Follow a server
495 description: successful operation
497 description: cannot follow a non-HTTPS server
512 summary: Create a user
520 description: user created
524 $ref: '#/components/schemas/AddUserResponse'
528 operationId: getUserId
530 id: '$response.body#/user/id'
533 operationId: putUserId
535 id: '$response.body#/user/id'
538 operationId: delUserId
540 id: '$response.body#/user/id'
542 description: insufficient authority to create an admin or moderator
547 $ref: '#/components/schemas/AddUser'
548 description: User to create
558 - $ref: '#/components/parameters/usersSearch'
559 - $ref: '#/components/parameters/usersBlocked'
560 - $ref: '#/components/parameters/start'
561 - $ref: '#/components/parameters/count'
562 - $ref: '#/components/parameters/usersSort'
565 description: successful operation
571 $ref: '#/components/schemas/User'
574 - $ref: '#/components/parameters/id'
576 summary: Delete a user
582 operationId: delUserId
585 description: successful operation
592 operationId: getUserId
595 description: successful operation
599 $ref: '#/components/schemas/User'
601 summary: Update a user
606 operationId: putUserId
609 description: successful operation
614 $ref: '#/components/schemas/UpdateUser'
618 summary: Register a user
623 description: successful operation
628 $ref: '#/components/schemas/RegisterUser'
632 summary: Get my user information
640 description: successful operation
646 $ref: '#/components/schemas/User'
648 summary: Update my user information
656 description: successful operation
661 $ref: '#/components/schemas/UpdateMe'
663 /users/me/videos/imports:
665 summary: Get video imports of my user
673 - $ref: '#/components/parameters/start'
674 - $ref: '#/components/parameters/count'
675 - $ref: '#/components/parameters/sort'
678 description: successful operation
682 $ref: '#/components/schemas/VideoImport'
683 /users/me/video-quota-used:
685 summary: Get my user used quota
693 description: successful operation
698 '/users/me/videos/{videoId}/rating':
700 summary: Get rate of my user for a video
710 description: 'The video id '
715 description: successful operation
719 $ref: '#/components/schemas/GetMeVideoRating'
722 summary: Get videos of my user
730 - $ref: '#/components/parameters/start'
731 - $ref: '#/components/parameters/count'
732 - $ref: '#/components/parameters/sort'
735 description: successful operation
739 $ref: '#/components/schemas/VideoListResponse'
740 /users/me/subscriptions:
742 summary: Get my user subscriptions
749 - $ref: '#/components/parameters/start'
750 - $ref: '#/components/parameters/count'
751 - $ref: '#/components/parameters/sort'
754 description: successful operation
758 summary: Add subscription to my user
771 description: uri of the video channels to subscribe to
777 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
780 description: successful operation
781 /users/me/subscriptions/exist:
783 summary: Get if subscriptions exist for my user
790 - $ref: '#/components/parameters/subscriptionsUris'
793 description: successful operation
798 /users/me/subscriptions/videos:
800 summary: List videos of subscriptions of my user
808 - $ref: '#/components/parameters/categoryOneOf'
809 - $ref: '#/components/parameters/isLive'
810 - $ref: '#/components/parameters/tagsOneOf'
811 - $ref: '#/components/parameters/tagsAllOf'
812 - $ref: '#/components/parameters/licenceOneOf'
813 - $ref: '#/components/parameters/languageOneOf'
814 - $ref: '#/components/parameters/nsfw'
815 - $ref: '#/components/parameters/filter'
816 - $ref: '#/components/parameters/skipCount'
817 - $ref: '#/components/parameters/start'
818 - $ref: '#/components/parameters/count'
819 - $ref: '#/components/parameters/videosSort'
822 description: successful operation
826 $ref: '#/components/schemas/VideoListResponse'
827 '/users/me/subscriptions/{subscriptionHandle}':
829 summary: Get subscription of my user
836 - $ref: '#/components/parameters/subscriptionHandle'
839 description: successful operation
843 $ref: '#/components/schemas/VideoChannel'
845 summary: Delete subscription of my user
852 - $ref: '#/components/parameters/subscriptionHandle'
855 description: successful operation
856 /users/me/notifications:
858 summary: List my notifications
866 description: only list unread notifications
869 - $ref: '#/components/parameters/start'
870 - $ref: '#/components/parameters/count'
871 - $ref: '#/components/parameters/sort'
874 description: successful operation
878 $ref: '#/components/schemas/NotificationListResponse'
879 /users/me/notifications/read:
881 summary: Mark notifications as read by their id
894 description: ids of the notifications to mark as read
901 description: successful operation
902 /users/me/notifications/read-all:
904 summary: Mark all my notification as read
911 description: successful operation
912 /users/me/notification-settings:
914 summary: Update my notification settings
925 newVideoFromSubscription:
926 $ref: '#/components/schemas/NotificationSettingValue'
928 $ref: '#/components/schemas/NotificationSettingValue'
930 $ref: '#/components/schemas/NotificationSettingValue'
931 videoAutoBlacklistAsModerator:
932 $ref: '#/components/schemas/NotificationSettingValue'
934 $ref: '#/components/schemas/NotificationSettingValue'
936 $ref: '#/components/schemas/NotificationSettingValue'
937 myVideoImportFinished:
938 $ref: '#/components/schemas/NotificationSettingValue'
940 $ref: '#/components/schemas/NotificationSettingValue'
942 $ref: '#/components/schemas/NotificationSettingValue'
944 $ref: '#/components/schemas/NotificationSettingValue'
946 $ref: '#/components/schemas/NotificationSettingValue'
947 autoInstanceFollowing:
948 $ref: '#/components/schemas/NotificationSettingValue'
951 description: successful operation
952 /users/me/history/videos:
954 summary: List watched videos history
960 - $ref: '#/components/parameters/start'
961 - $ref: '#/components/parameters/count'
962 - $ref: '#/components/parameters/search'
965 description: successful operation
969 $ref: '#/components/schemas/VideoListResponse'
970 /users/me/history/videos/remove:
972 summary: Clear video history
984 description: history before this date will be deleted
989 description: successful operation
990 /users/me/avatar/pick:
992 summary: Update my user avatar
999 description: successful operation
1006 $ref: '#/components/schemas/ActorImage'
1008 description: image file too large
1010 X-File-Maximum-Size:
1014 description: Maximum file size for the avatar
1017 multipart/form-data:
1022 description: The file to upload.
1027 contentType: image/png, image/jpeg
1030 summary: Delete my avatar
1037 description: successful operation
1041 summary: List video ownership changes
1043 - Video Ownership Change
1048 description: successful operation
1049 '/videos/ownership/{id}/accept':
1051 summary: Accept ownership change request
1053 - Video Ownership Change
1057 - $ref: '#/components/parameters/idOrUUID'
1060 description: successful operation
1062 description: cannot terminate an ownership change of another user
1064 description: video owneship change not found
1065 '/videos/ownership/{id}/refuse':
1067 summary: Refuse ownership change request
1069 - Video Ownership Change
1073 - $ref: '#/components/parameters/idOrUUID'
1076 description: successful operation
1078 description: cannot terminate an ownership change of another user
1080 description: video owneship change not found
1081 '/videos/{id}/give-ownership':
1083 summary: Request ownership change
1085 - Video Ownership Change
1089 - $ref: '#/components/parameters/idOrUUID'
1093 application/x-www-form-urlencoded:
1103 description: successful operation
1105 description: changing video ownership to a remote account is not supported yet
1107 description: video not found
1110 summary: List videos
1114 - $ref: '#/components/parameters/categoryOneOf'
1115 - $ref: '#/components/parameters/isLive'
1116 - $ref: '#/components/parameters/tagsOneOf'
1117 - $ref: '#/components/parameters/tagsAllOf'
1118 - $ref: '#/components/parameters/licenceOneOf'
1119 - $ref: '#/components/parameters/languageOneOf'
1120 - $ref: '#/components/parameters/nsfw'
1121 - $ref: '#/components/parameters/filter'
1122 - $ref: '#/components/parameters/skipCount'
1123 - $ref: '#/components/parameters/start'
1124 - $ref: '#/components/parameters/count'
1125 - $ref: '#/components/parameters/videosSort'
1128 description: successful operation
1132 $ref: '#/components/schemas/VideoListResponse'
1135 summary: List available video categories
1140 description: successful operation
1149 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1152 summary: List available video licences
1157 description: successful operation
1166 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1169 summary: List available video languages
1174 description: successful operation
1183 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1186 summary: List available video privacies
1191 description: successful operation
1200 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1203 summary: Update a video
1209 - $ref: '#/components/parameters/idOrUUID'
1212 description: successful operation
1215 multipart/form-data:
1220 description: Video thumbnail file
1224 description: Video preview file
1228 description: Video category
1232 description: Video licence
1236 description: Video language
1239 $ref: '#/components/schemas/VideoPrivacySet'
1241 description: Video description
1244 description: Whether or not we wait transcoding before publish the video
1247 description: A text tell the audience how to support the video creator
1248 example: Please support my work on <insert crowdfunding plateform>! <3
1251 description: Whether or not this video contains sensitive content
1254 description: Video name
1259 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1268 description: Enable or disable comments for this video
1270 originallyPublishedAt:
1271 description: Date when the content was originally published
1275 $ref: '#/components/schemas/VideoScheduledUpdate'
1278 contentType: image/jpeg
1280 contentType: image/jpeg
1282 summary: Get a video
1286 - $ref: '#/components/parameters/idOrUUID'
1289 description: successful operation
1293 $ref: '#/components/schemas/VideoDetails'
1295 summary: Delete a video
1301 - $ref: '#/components/parameters/idOrUUID'
1304 description: successful operation
1305 '/videos/{id}/description':
1307 summary: Get complete video description
1311 - $ref: '#/components/parameters/idOrUUID'
1314 description: successful operation
1319 '/videos/{id}/views':
1321 summary: Add a view to a video
1325 - $ref: '#/components/parameters/idOrUUID'
1328 description: successful operation
1329 '/videos/{id}/watching':
1331 summary: Set watching progress of a video
1337 - $ref: '#/components/parameters/idOrUUID'
1342 $ref: '#/components/schemas/UserWatchingVideo'
1346 description: successful operation
1349 summary: Upload a video
1356 description: successful operation
1360 $ref: '#/components/schemas/VideoUploadResponse'
1362 description: invalid file field, schedule date or parameter
1364 description: video didn't pass upload filter
1366 description: upload has timed out
1368 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1370 X-File-Maximum-Size:
1374 description: Maximum file size for the video
1376 description: video type unsupported
1378 description: video unreadable
1381 multipart/form-data:
1386 description: Video file
1390 description: Channel id that will contain this video
1393 description: Video thumbnail file
1397 description: Video preview file
1401 $ref: '#/components/schemas/VideoPrivacySet'
1403 description: Video category
1407 description: Video licence
1411 description: Video language
1414 description: Video description
1417 description: Whether or not we wait transcoding before publish the video
1420 description: A text tell the audience how to support the video creator
1421 example: Please support my work on <insert crowdfunding plateform>! <3
1424 description: Whether or not this video contains sensitive content
1427 description: Video name
1432 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1442 description: Enable or disable comments for this video
1445 description: Enable or disable downloading for this video
1447 originallyPublishedAt:
1448 description: Date when the content was originally published
1452 $ref: '#/components/schemas/VideoScheduledUpdate'
1459 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1461 contentType: image/jpeg
1463 contentType: image/jpeg
1468 USERNAME="<your_username>"
1469 PASSWORD="<your_password>"
1470 FILE_PATH="<your_file_path>"
1471 CHANNEL_ID="<your_channel_id>"
1474 API_PATH="https://peertube2.cpy.re/api/v1"
1476 client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1477 client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1478 token=$(curl -s "$API_PATH/users/token" \
1479 --data client_id="$client_id" \
1480 --data client_secret="$client_secret" \
1481 --data grant_type=password \
1482 --data response_type=code \
1483 --data username="$USERNAME" \
1484 --data password="$PASSWORD" \
1485 | jq -r ".access_token")
1487 curl -s "$API_PATH/videos/upload" \
1488 -H "Authorization: Bearer $token" \
1490 --form videofile=@"$FILE_PATH" \
1491 --form channelId=$CHANNEL_ID \
1495 summary: Import a video
1496 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1503 multipart/form-data:
1508 description: Torrent File
1512 description: HTTP target URL
1515 description: Magnet URI
1518 description: Channel id that will contain this video
1521 description: Video thumbnail file
1525 description: Video preview file
1529 $ref: '#/components/schemas/VideoPrivacySet'
1531 description: Video category
1535 description: Video licence
1539 description: Video language
1542 description: Video description
1545 description: Whether or not we wait transcoding before publish the video
1548 description: A text tell the audience how to support the video creator
1549 example: Please support my work on <insert crowdfunding plateform>! <3
1552 description: Whether or not this video contains sensitive content
1555 description: Video name
1560 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1569 description: Enable or disable comments for this video
1572 description: Enable or disable downloading for this video
1575 $ref: '#/components/schemas/VideoScheduledUpdate'
1581 contentType: application/x-bittorrent
1583 contentType: image/jpeg
1585 contentType: image/jpeg
1588 description: successful operation
1592 $ref: '#/components/schemas/VideoUploadResponse'
1594 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1596 description: video didn't pass pre-import filter
1598 description: HTTP or Torrent/magnetURI import not enabled
1602 summary: Create a live
1610 description: successful operation
1614 $ref: '#/components/schemas/VideoUploadResponse'
1616 description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
1619 multipart/form-data:
1624 description: Channel id that will contain this live video
1629 description: User can stream multiple times in a permanent live
1632 description: Live video/replay thumbnail file
1636 description: Live video/replay preview file
1640 $ref: '#/components/schemas/VideoPrivacySet'
1642 description: Live video/replay category
1645 description: Live video/replay licence
1648 description: Live video/replay language
1651 description: Live video/replay description
1654 description: A text tell the audience how to support the creator
1655 example: Please support my work on <insert crowdfunding plateform>! <3
1658 description: Whether or not this live video/replay contains sensitive content
1661 description: Live video/replay name
1666 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
1675 description: Enable or disable comments for this live video/replay
1678 description: Enable or disable downloading for the replay of this live
1685 contentType: image/jpeg
1687 contentType: image/jpeg
1691 summary: Get a live information
1698 - $ref: '#/components/parameters/idOrUUID'
1701 description: successful operation
1705 $ref: '#/components/schemas/LiveVideoResponse'
1707 summary: Update a live information
1714 - $ref: '#/components/parameters/idOrUUID'
1719 $ref: '#/components/schemas/LiveVideoUpdate'
1722 description: Successful operation
1724 description: Bad parameters or trying to update a live that has already started
1726 description: Trying to save replay of the live but saving replay is not enabled on the instance
1730 summary: List my abuses
1739 description: only list the report with this id
1745 $ref: '#/components/schemas/AbuseStateSet'
1746 - $ref: '#/components/parameters/start'
1747 - $ref: '#/components/parameters/count'
1748 - $ref: '#/components/parameters/abusesSort'
1751 description: successful operation
1757 $ref: '#/components/schemas/Abuse'
1761 summary: List abuses
1771 description: only list the report with this id
1774 - name: predefinedReason
1776 description: predefined reason the listed reports should contain
1778 $ref: '#/components/schemas/PredefinedAbuseReasons'
1781 description: plain search that will match with video titles, reporter names and more
1787 $ref: '#/components/schemas/AbuseStateSet'
1788 - name: searchReporter
1790 description: only list reports of a specific reporter
1793 - name: searchReportee
1794 description: only list reports of a specific reportee
1800 description: only list reports of a specific video
1803 - name: searchVideoChannel
1805 description: only list reports of a specific video channel
1810 description: only list blacklisted or deleted videos
1818 description: only list account, comment or video reports
1825 - $ref: '#/components/parameters/start'
1826 - $ref: '#/components/parameters/count'
1827 - $ref: '#/components/parameters/abusesSort'
1830 description: successful operation
1836 $ref: '#/components/schemas/Abuse'
1839 summary: Report an abuse
1852 description: Reason why the user reports this video
1857 $ref: '#/components/schemas/PredefinedAbuseReasons'
1862 description: Video id to report
1866 description: Timestamp in the video that marks the beginning of the report
1870 description: Timestamp in the video that marks the ending of the report
1876 description: Comment id to report
1882 description: Account id to report
1888 description: successful operation
1890 description: incorrect request parameters
1891 '/abuses/{abuseId}':
1893 summary: Update an abuse
1901 - $ref: '#/components/parameters/abuseId'
1909 $ref: '#/components/schemas/AbuseStateSet'
1912 description: Update the report comment visible only to the moderation team
1917 description: successful operation
1919 description: abuse not found
1923 summary: Delete an abuse
1929 - $ref: '#/components/parameters/abuseId'
1932 description: successful operation
1934 description: block not found
1935 '/abuses/{abuseId}/messages':
1937 summary: List messages of an abuse
1943 - $ref: '#/components/parameters/abuseId'
1946 description: successful operation
1952 $ref: '#/components/schemas/AbuseMessage'
1955 summary: Add message to an abuse
1961 - $ref: '#/components/parameters/abuseId'
1970 description: Message to send
1978 description: successful operation
1980 description: incorrect request parameters
1981 '/abuses/{abuseId}/messages/{abuseMessageId}':
1983 summary: Delete an abuse message
1989 - $ref: '#/components/parameters/abuseId'
1990 - $ref: '#/components/parameters/abuseMessageId'
1993 description: successful operation
1995 '/videos/{id}/blacklist':
1997 summary: Block a video
2005 - $ref: '#/components/parameters/idOrUUID'
2008 description: successful operation
2010 summary: Unblock a video by its id
2018 - $ref: '#/components/parameters/idOrUUID'
2021 description: successful operation
2023 description: block not found
2028 summary: List video blocks
2037 list only blocks that match this type:
2041 - `2`: automatic block that needs review
2049 description: plain search that will match with video titles, and more
2052 - $ref: '#/components/parameters/start'
2053 - $ref: '#/components/parameters/count'
2054 - $ref: '#/components/parameters/blacklistsSort'
2057 description: successful operation
2069 $ref: '#/components/schemas/VideoBlacklist'
2070 /videos/{id}/captions:
2072 summary: List captions of a video
2076 - $ref: '#/components/parameters/idOrUUID'
2079 description: successful operation
2091 $ref: '#/components/schemas/VideoCaption'
2092 /videos/{id}/captions/{captionLanguage}:
2094 summary: Add or replace a video caption
2101 - $ref: '#/components/parameters/idOrUUID'
2102 - $ref: '#/components/parameters/captionLanguage'
2105 multipart/form-data:
2110 description: The file to upload.
2115 contentType: text/vtt, application/x-subrip, text/plain
2118 description: successful operation
2120 description: video or language not found
2122 summary: Delete a video caption
2129 - $ref: '#/components/parameters/idOrUUID'
2130 - $ref: '#/components/parameters/captionLanguage'
2133 description: successful operation
2135 description: video or language or caption for that language not found
2138 summary: List video channels
2142 - $ref: '#/components/parameters/start'
2143 - $ref: '#/components/parameters/count'
2144 - $ref: '#/components/parameters/sort'
2147 description: successful operation
2159 $ref: '#/components/schemas/VideoChannel'
2161 summary: Create a video channel
2168 description: successful operation
2173 $ref: '#/components/schemas/VideoChannelCreate'
2174 '/video-channels/{channelHandle}':
2176 summary: Get a video channel
2180 - $ref: '#/components/parameters/channelHandle'
2183 description: successful operation
2187 $ref: '#/components/schemas/VideoChannel'
2189 summary: Update a video channel
2195 - $ref: '#/components/parameters/channelHandle'
2198 description: successful operation
2203 $ref: '#/components/schemas/VideoChannelUpdate'
2205 summary: Delete a video channel
2211 - $ref: '#/components/parameters/channelHandle'
2214 description: successful operation
2215 '/video-channels/{channelHandle}/videos':
2217 summary: List videos of a video channel
2222 - $ref: '#/components/parameters/channelHandle'
2223 - $ref: '#/components/parameters/categoryOneOf'
2224 - $ref: '#/components/parameters/isLive'
2225 - $ref: '#/components/parameters/tagsOneOf'
2226 - $ref: '#/components/parameters/tagsAllOf'
2227 - $ref: '#/components/parameters/licenceOneOf'
2228 - $ref: '#/components/parameters/languageOneOf'
2229 - $ref: '#/components/parameters/nsfw'
2230 - $ref: '#/components/parameters/filter'
2231 - $ref: '#/components/parameters/skipCount'
2232 - $ref: '#/components/parameters/start'
2233 - $ref: '#/components/parameters/count'
2234 - $ref: '#/components/parameters/videosSort'
2237 description: successful operation
2241 $ref: '#/components/schemas/VideoListResponse'
2242 '/video-channels/{channelHandle}/avatar/pick':
2244 summary: Update channel avatar
2250 - $ref: '#/components/parameters/channelHandle'
2253 description: successful operation
2260 $ref: '#/components/schemas/ActorImage'
2262 description: image file too large
2264 X-File-Maximum-Size:
2268 description: Maximum file size for the avatar
2271 multipart/form-data:
2276 description: The file to upload.
2281 contentType: image/png, image/jpeg
2282 '/video-channels/{channelHandle}/avatar':
2284 summary: Delete channel avatar
2290 - $ref: '#/components/parameters/channelHandle'
2293 description: successful operation
2296 '/video-channels/{channelHandle}/banner/pick':
2298 summary: Update channel banner
2304 - $ref: '#/components/parameters/channelHandle'
2307 description: successful operation
2314 $ref: '#/components/schemas/ActorImage'
2316 description: image file too large
2318 X-File-Maximum-Size:
2322 description: Maximum file size for the banner
2325 multipart/form-data:
2330 description: The file to upload.
2335 contentType: image/png, image/jpeg
2336 '/video-channels/{channelHandle}/banner':
2338 summary: Delete channel banner
2344 - $ref: '#/components/parameters/channelHandle'
2347 description: successful operation
2349 /video-playlists/privacies:
2351 summary: List available playlist privacies
2356 description: successful operation
2365 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2369 summary: List video playlists
2373 - $ref: '#/components/parameters/start'
2374 - $ref: '#/components/parameters/count'
2375 - $ref: '#/components/parameters/sort'
2378 description: successful operation
2390 $ref: '#/components/schemas/VideoPlaylist'
2392 summary: Create a video playlist
2393 description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
2400 description: successful operation
2412 $ref: '#/components/schemas/UUIDv4'
2415 multipart/form-data:
2420 description: Video playlist display name
2425 description: Video playlist thumbnail file
2429 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2431 description: Video playlist description
2434 description: Video channel in which the playlist will be published
2440 contentType: image/jpeg
2442 /video-playlists/{id}:
2444 summary: Get a video playlist
2448 - $ref: '#/components/parameters/idOrUUID'
2451 description: successful operation
2455 $ref: '#/components/schemas/VideoPlaylist'
2457 summary: Update a video playlist
2458 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2465 description: successful operation
2467 - $ref: '#/components/parameters/idOrUUID'
2470 multipart/form-data:
2475 description: Video playlist display name
2480 description: Video playlist thumbnail file
2484 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2486 description: Video playlist description
2489 description: Video channel in which the playlist will be published
2493 contentType: image/jpeg
2495 summary: Delete a video playlist
2501 - $ref: '#/components/parameters/idOrUUID'
2504 description: successful operation
2506 /video-playlists/{id}/videos:
2508 summary: 'List videos of a playlist'
2513 - $ref: '#/components/parameters/idOrUUID'
2516 description: successful operation
2520 $ref: '#/components/schemas/VideoListResponse'
2522 summary: 'Add a video in a playlist'
2529 - $ref: '#/components/parameters/idOrUUID'
2532 description: successful operation
2538 videoPlaylistElement:
2551 description: 'Video to add in the playlist'
2554 description: 'Start the video at this specific timestamp (in seconds)'
2557 description: 'Stop the video at this specific timestamp (in seconds)'
2561 /video-playlists/{id}/videos/reorder:
2563 summary: 'Reorder a playlist'
2569 - $ref: '#/components/parameters/idOrUUID'
2572 description: successful operation
2581 description: 'Start position of the element to reorder'
2583 insertAfterPosition:
2585 description: 'New position for the block to reorder, to add the block before the first element'
2589 description: 'How many element from `startPosition` to reorder'
2593 - insertAfterPosition
2595 /video-playlists/{id}/videos/{playlistElementId}:
2597 summary: 'Update a playlist element'
2603 - $ref: '#/components/parameters/idOrUUID'
2604 - $ref: '#/components/parameters/playlistElementId'
2607 description: successful operation
2616 description: 'Start the video at this specific timestamp (in seconds)'
2619 description: 'Stop the video at this specific timestamp (in seconds)'
2621 summary: 'Delete an element from a playlist'
2627 - $ref: '#/components/parameters/idOrUUID'
2628 - $ref: '#/components/parameters/playlistElementId'
2631 description: successful operation
2633 '/users/me/video-playlists/videos-exist':
2635 summary: 'Check video exists in my playlists'
2644 description: The video ids to check
2651 description: successful operation
2671 '/accounts/{name}/video-channels':
2673 summary: List video channels of an account
2678 - $ref: '#/components/parameters/name'
2681 description: include view statistics for the last 30 days (only if authentified as the account user)
2684 - $ref: '#/components/parameters/start'
2685 - $ref: '#/components/parameters/count'
2686 - $ref: '#/components/parameters/sort'
2689 description: successful operation
2700 $ref: '#/components/schemas/VideoChannel'
2701 '/accounts/{name}/ratings':
2703 summary: List ratings of an account
2709 - $ref: '#/components/parameters/name'
2710 - $ref: '#/components/parameters/start'
2711 - $ref: '#/components/parameters/count'
2712 - $ref: '#/components/parameters/sort'
2716 description: Optionally filter which ratings to retrieve
2724 description: successful operation
2730 $ref: '#/components/schemas/VideoRating'
2731 '/videos/{id}/comment-threads':
2733 summary: List threads of a video
2737 - $ref: '#/components/parameters/idOrUUID'
2738 - $ref: '#/components/parameters/start'
2739 - $ref: '#/components/parameters/count'
2740 - $ref: '#/components/parameters/commentsSort'
2743 description: successful operation
2747 $ref: '#/components/schemas/CommentThreadResponse'
2749 summary: Create a thread
2755 - $ref: '#/components/parameters/idOrUUID'
2758 description: successful operation
2762 $ref: '#/components/schemas/CommentThreadPostResponse'
2764 description: video does not exist
2773 description: 'Text comment'
2777 '/videos/{id}/comment-threads/{threadId}':
2779 summary: Get a thread
2783 - $ref: '#/components/parameters/idOrUUID'
2784 - $ref: '#/components/parameters/threadId'
2787 description: successful operation
2791 $ref: '#/components/schemas/VideoCommentThreadTree'
2792 '/videos/{id}/comments/{commentId}':
2794 summary: Reply to a thread of a video
2800 - $ref: '#/components/parameters/idOrUUID'
2801 - $ref: '#/components/parameters/commentId'
2804 description: successful operation
2808 $ref: '#/components/schemas/CommentThreadPostResponse'
2810 description: thread or video does not exist
2819 description: 'Text comment'
2824 summary: Delete a comment or a reply
2830 - $ref: '#/components/parameters/idOrUUID'
2831 - $ref: '#/components/parameters/commentId'
2834 description: successful operation
2836 description: cannot remove comment of another user
2838 description: comment or video does not exist
2840 description: comment is already deleted
2841 '/videos/{id}/rate':
2843 summary: Like/dislike a video
2849 - $ref: '#/components/parameters/idOrUUID'
2852 description: successful operation
2854 description: video does not exist
2859 summary: Search videos
2864 allowEmptyValue: false
2866 String to search. If the user can make a remote URI search, and the string is an URI then the
2867 PeerTube instance will fetch the remote object and add it to its database. Then,
2868 you can use the REST API to fetch the complete video information and interact with it.
2871 - $ref: '#/components/parameters/categoryOneOf'
2872 - $ref: '#/components/parameters/isLive'
2873 - $ref: '#/components/parameters/tagsOneOf'
2874 - $ref: '#/components/parameters/tagsAllOf'
2875 - $ref: '#/components/parameters/licenceOneOf'
2876 - $ref: '#/components/parameters/languageOneOf'
2877 - $ref: '#/components/parameters/nsfw'
2878 - $ref: '#/components/parameters/filter'
2879 - $ref: '#/components/parameters/skipCount'
2880 - $ref: '#/components/parameters/start'
2881 - $ref: '#/components/parameters/count'
2882 - $ref: '#/components/parameters/searchTarget'
2883 - $ref: '#/components/parameters/videosSearchSort'
2886 description: Get videos that are published after this date
2892 description: Get videos that are published before this date
2896 - name: originallyPublishedStartDate
2898 description: Get videos that are originally published after this date
2902 - name: originallyPublishedEndDate
2904 description: Get videos that are originally published before this date
2910 description: Get videos that have this minimum duration
2915 description: Get videos that have this maximum duration
2919 'searchTarget === search-index':
2920 $ref: '#/components/callbacks/searchIndex'
2923 description: successful operation
2927 $ref: '#/components/schemas/VideoListResponse'
2929 description: search index unavailable
2930 /search/video-channels:
2934 summary: Search channels
2940 String to search. If the user can make a remote URI search, and the string is an URI then the
2941 PeerTube instance will fetch the remote object and add it to its database. Then,
2942 you can use the REST API to fetch the complete channel information and interact with it.
2945 - $ref: '#/components/parameters/start'
2946 - $ref: '#/components/parameters/count'
2947 - $ref: '#/components/parameters/searchTarget'
2948 - $ref: '#/components/parameters/sort'
2950 'searchTarget === search-index':
2951 $ref: '#/components/callbacks/searchIndex'
2954 description: successful operation
2960 $ref: '#/components/schemas/VideoChannel'
2962 description: search index unavailable
2963 /blocklist/accounts:
2967 summary: List account blocks
2972 - $ref: '#/components/parameters/start'
2973 - $ref: '#/components/parameters/count'
2974 - $ref: '#/components/parameters/sort'
2977 description: successful operation
2981 summary: Block an account
2993 example: chocobozzz@example.org
2994 description: account to block, in the form `username@domain`
2999 description: successful operation
3001 description: self-blocking forbidden
3002 '/blocklist/accounts/{accountName}':
3006 summary: Unblock an account by its handle
3014 description: account to unblock, in the form `username@domain`
3019 description: successful operation
3021 description: account or account block does not exist
3026 summary: List server blocks
3031 - $ref: '#/components/parameters/start'
3032 - $ref: '#/components/parameters/count'
3033 - $ref: '#/components/parameters/sort'
3036 description: successful operation
3040 summary: Block a server
3053 description: server domain to block
3058 description: successful operation
3060 description: self-blocking forbidden
3061 '/blocklist/servers/{host}':
3065 summary: Unblock a server by its domain
3073 description: server domain to unblock
3079 description: successful operation
3081 description: account block does not exist
3085 - Instance Redundancy
3086 summary: Update a server redundancy policy
3094 description: server domain to mirror
3106 description: allow mirroring of the host's local videos
3111 description: successful operation
3113 description: server is not already known
3118 summary: List videos being mirrored
3126 description: direction of the mirror
3132 - $ref: '#/components/parameters/start'
3133 - $ref: '#/components/parameters/count'
3134 - $ref: '#/components/parameters/videoRedundanciesSort'
3137 description: successful operation
3143 $ref: '#/components/schemas/VideoRedundancy'
3147 summary: Mirror a video
3163 description: successful operation
3165 description: cannot mirror a local video
3167 description: video does not exist
3169 description: video is already mirrored
3170 /redundancy/videos/{redundancyId}:
3174 summary: Delete a mirror done on a video
3179 - name: redundancyId
3182 description: id of an existing redundancy on a video
3187 description: successful operation
3189 description: video redundancy not found
3190 '/feeds/video-comments.{format}':
3194 summary: List comments on videos
3199 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3212 description: 'limit listing to a specific video'
3217 description: 'limit listing to a specific account'
3222 description: 'limit listing to a specific account'
3225 - name: videoChannelId
3227 description: 'limit listing to a specific video channel'
3230 - name: videoChannelName
3232 description: 'limit listing to a specific video channel'
3237 description: successful operation
3242 default: 'max-age=900' # 15 min cache
3246 $ref: '#/components/schemas/VideoCommentsForXML'
3249 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3250 application/rss+xml:
3252 $ref: '#/components/schemas/VideoCommentsForXML'
3255 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3258 $ref: '#/components/schemas/VideoCommentsForXML'
3261 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3262 application/atom+xml:
3264 $ref: '#/components/schemas/VideoCommentsForXML'
3267 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3273 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3275 x-summary: field inconsistencies
3278 - videoId filter is mixed with a channel filter
3280 description: video, video channel or account not found
3282 description: accept header unsupported
3283 '/feeds/videos.{format}':
3287 summary: List videos
3292 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3305 description: 'limit listing to a specific account'
3310 description: 'limit listing to a specific account'
3313 - name: videoChannelId
3315 description: 'limit listing to a specific video channel'
3318 - name: videoChannelName
3320 description: 'limit listing to a specific video channel'
3323 - $ref: '#/components/parameters/sort'
3324 - $ref: '#/components/parameters/nsfw'
3325 - $ref: '#/components/parameters/filter'
3328 description: successful operation
3333 default: 'max-age=900' # 15 min cache
3337 $ref: '#/components/schemas/VideosForXML'
3340 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3341 application/rss+xml:
3343 $ref: '#/components/schemas/VideosForXML'
3346 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3349 $ref: '#/components/schemas/VideosForXML'
3352 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3353 application/atom+xml:
3355 $ref: '#/components/schemas/VideosForXML'
3358 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3364 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3366 description: video channel or account not found
3368 description: accept header unsupported
3369 '/feeds/subscriptions.{format}':
3374 summary: List videos of subscriptions tied to a token
3379 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3392 description: limit listing to a specific account
3398 description: private token allowing access
3402 - $ref: '#/components/parameters/sort'
3403 - $ref: '#/components/parameters/nsfw'
3404 - $ref: '#/components/parameters/filter'
3407 description: successful operation
3412 default: 'max-age=900' # 15 min cache
3416 $ref: '#/components/schemas/VideosForXML'
3417 application/rss+xml:
3419 $ref: '#/components/schemas/VideosForXML'
3422 $ref: '#/components/schemas/VideosForXML'
3423 application/atom+xml:
3425 $ref: '#/components/schemas/VideosForXML'
3430 description: accept header unsupported
3435 summary: List plugins
3448 - $ref: '#/components/parameters/start'
3449 - $ref: '#/components/parameters/count'
3450 - $ref: '#/components/parameters/sort'
3453 description: successful operation
3457 $ref: '#/components/schemas/PluginResponse'
3462 summary: List available plugins
3475 - name: currentPeerTubeEngine
3479 - $ref: '#/components/parameters/start'
3480 - $ref: '#/components/parameters/count'
3481 - $ref: '#/components/parameters/sort'
3484 description: successful operation
3488 $ref: '#/components/schemas/PluginResponse'
3490 description: plugin index unavailable
3495 summary: Install a plugin
3508 example: peertube-plugin-auth-ldap
3511 additionalProperties: false
3518 additionalProperties: false
3521 description: successful operation
3523 description: should have either `npmName` or `path` set
3528 summary: Update a plugin
3541 example: peertube-plugin-auth-ldap
3544 additionalProperties: false
3551 additionalProperties: false
3554 description: successful operation
3556 description: should have either `npmName` or `path` set
3558 description: existing plugin not found
3563 summary: Uninstall a plugin
3575 description: name of the plugin/theme in its package.json
3576 example: peertube-plugin-auth-ldap
3581 description: successful operation
3583 description: existing plugin not found
3588 summary: Get a plugin
3593 - $ref: '#/components/parameters/npmName'
3596 description: successful operation
3600 $ref: '#/components/schemas/Plugin'
3602 description: plugin not found
3603 /plugins/{npmName}/settings:
3607 summary: Set a plugin's settings
3612 - $ref: '#/components/parameters/npmName'
3621 additionalProperties: true
3624 description: successful operation
3626 description: plugin not found
3627 /plugins/{npmName}/public-settings:
3631 summary: Get a plugin's public settings
3633 - $ref: '#/components/parameters/npmName'
3636 description: successful operation
3641 additionalProperties: true
3643 description: plugin not found
3644 /plugins/{npmName}/registered-settings:
3648 summary: Get a plugin's registered settings
3653 - $ref: '#/components/parameters/npmName'
3656 description: successful operation
3661 additionalProperties: true
3663 description: plugin not found
3665 - url: 'https://peertube2.cpy.re/api/v1'
3666 description: Live Test Server (live data - latest nightly version)
3667 - url: 'https://peertube3.cpy.re/api/v1'
3668 description: Live Test Server (live data - latest RC version)
3669 - url: 'https://peertube.cpy.re/api/v1'
3670 description: Live Test Server (live data - stable version)
3677 description: Offset used to paginate results
3685 description: "Number of items to return"
3695 description: Sort column
3703 description: Plain text search, applied to various parts of the model depending on endpoint
3711 If the administrator enabled search index support, you can override the default search target.
3714 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
3715 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
3716 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
3717 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
3718 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
3719 * 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
3720 the data from the origin instance API
3730 description: Sort videos by criteria
3746 description: Sort videos by criteria
3761 description: Sort comments by criteria
3771 description: Sort blacklists by criteria
3787 description: Plain text search that will match with user usernames or emails
3794 description: Filter results down to (un)banned users
3801 description: Sort users by criteria
3812 description: Sort abuses by criteria
3819 videoRedundanciesSort:
3823 description: Sort abuses by criteria
3832 description: The username or handle of the account
3835 example: chocobozzz | chocobozzz@example.org
3840 description: The user id
3849 description: The object id or uuid
3855 - $ref: '#/components/schemas/UUIDv4'
3857 name: playlistElementId
3860 description: Playlist element id
3867 description: Abuse id
3871 name: abuseMessageId
3874 description: Abuse message id
3878 name: captionLanguage
3881 description: The caption language
3888 description: The video channel handle
3891 example: my_username | my_username@example.com
3893 name: subscriptionHandle
3896 description: The subscription handle
3899 example: my_username | my_username@example.com
3904 description: The thread id (root comment id)
3911 description: The comment id
3918 description: whether or not the video is a live
3925 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
3938 description: tag(s) of the video
3951 description: tag(s) of the video, where all should be present in the video
3964 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
3977 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
3990 description: if you don't need the `total` in the response
4001 description: whether to include nsfw videos, if any
4012 Special filters which might require special rights:
4013 * `local` - only videos local to the instance
4014 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4015 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4025 description: list of uris to check if each is part of the user subscriptions
4035 description: name of the plugin/theme on npmjs.com or in its package.json
4038 example: peertube-plugin-auth-ldap
4043 description: job type
4047 - activitypub-follow
4048 - activitypub-http-broadcast
4049 - activitypub-http-fetcher
4050 - activitypub-http-unicast
4056 - activitypub-refresher
4062 Authenticating via OAuth requires the following steps:
4063 - Have an activated account
4064 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
4065 Bearer Token for that account at `/api/v1/users/token`
4066 - Make authenticated requests, putting *Authorization: Bearer <token\>*
4067 - Profit, depending on the role assigned to the account
4069 Note that the __access token is valid for 1 day__ and, and is given
4070 along with a __refresh token valid for 2 weeks__.
4074 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
4077 moderator: Moderator scope
4083 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4084 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4085 # the regex above limits the length;
4086 # however, some tools might require explicit settings:
4090 VideoConstantNumber-Category:
4094 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
4097 VideoConstantNumber-Licence:
4101 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
4104 VideoConstantString-Language:
4108 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
4112 VideoPlaylistPrivacySet:
4118 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
4119 VideoPlaylistPrivacyConstant:
4122 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4126 VideoPlaylistTypeSet:
4131 description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
4132 VideoPlaylistTypeConstant:
4135 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4146 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
4147 VideoPrivacyConstant:
4150 $ref: '#/components/schemas/VideoPrivacySet'
4167 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4174 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4185 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4195 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4199 $ref: '#/components/schemas/AbuseStateSet'
4202 AbusePredefinedReasons:
4215 example: [spamOrMisleading]
4217 VideoResolutionConstant:
4221 description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
4226 VideoScheduledUpdate:
4229 $ref: '#/components/schemas/VideoPrivacySet'
4233 description: When to update the video
4253 - $ref: '#/components/schemas/ActorImage'
4254 VideoChannelSummary:
4271 - $ref: '#/components/schemas/ActorImage'
4283 - $ref: '#/components/schemas/Video'
4289 $ref: '#/components/schemas/VideoResolutionConstant'
4292 description: 'Video file size in bytes'
4295 description: Direct URL of the torrent file
4299 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4303 description: Direct URL of the video
4307 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4314 VideoStreamingPlaylists:
4327 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4328 VideoStreamingPlaylists-HLS:
4339 Video files associated to this playlist.
4341 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4343 $ref: '#/components/schemas/VideoFile'
4357 $ref: '#/components/schemas/UUIDv4'
4368 $ref: '#/components/schemas/UUIDv4'
4374 example: 2017-10-01T10:52:46.396Z
4375 description: time at which the video object was first drafted
4379 example: 2018-10-01T10:52:46.396Z
4380 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4384 example: 2021-05-04T08:01:01.502Z
4385 description: last time the video's metadata was modified
4386 originallyPublishedAt:
4389 example: 2010-10-01T10:52:46.396Z
4390 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4392 $ref: '#/components/schemas/VideoConstantNumber-Category'
4394 $ref: '#/components/schemas/VideoConstantNumber-Licence'
4396 $ref: '#/components/schemas/VideoConstantString-Language'
4398 $ref: '#/components/schemas/VideoPrivacyConstant'
4402 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4403 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4407 truncated description of the video, written in Markdown.
4408 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4412 description: duration of the video in seconds
4417 example: What is PeerTube?
4422 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4425 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4428 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4444 $ref: '#/components/schemas/VideoStateConstant'
4448 - $ref: '#/components/schemas/VideoScheduledUpdate'
4456 $ref: '#/components/schemas/AccountSummary'
4458 $ref: '#/components/schemas/VideoChannelSummary'
4467 - $ref: '#/components/schemas/Video'
4472 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4473 description: path at which to get the full description of maximum `10000` characters
4476 description: A text tell the audience how to support the video creator
4477 example: Please support my work on <insert crowdfunding plateform>! <3
4481 $ref: '#/components/schemas/VideoChannel'
4483 $ref: '#/components/schemas/Account'
4485 example: [flowers, gardening]
4505 $ref: '#/components/schemas/VideoFile'
4507 WebTorrent/raw video files. If WebTorrent is disabled on the server:
4509 - field will be empty
4510 - video files will be found in `streamingPlaylists[].files` field
4514 $ref: '#/components/schemas/VideoStreamingPlaylists'
4516 HLS playlists/manifest files. If HLS is disabled on the server:
4518 - field will be empty
4519 - video files will be found in `files` field
4520 FileRedundancyInformation:
4555 $ref: '#/components/schemas/UUIDv4'
4562 $ref: '#/components/schemas/FileRedundancyInformation'
4566 $ref: '#/components/schemas/FileRedundancyInformation'
4567 VideoImportStateConstant:
4575 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4587 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4591 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
4595 $ref: '#/components/schemas/VideoImportStateConstant'
4605 $ref: '#/components/schemas/Video'
4613 example: The video is a spam
4617 $ref: '#/components/schemas/AbusePredefinedReasons'
4619 $ref: '#/components/schemas/Account'
4621 $ref: '#/components/schemas/AbuseStateConstant'
4624 example: Decided to ban the server since it spams us regularly
4628 $ref: '#/components/schemas/VideoInfo'
4646 $ref: '#/components/schemas/AccountSummary'
4664 $ref: '#/components/schemas/UUIDv4'
4697 $ref: '#/components/schemas/UUIDv4'
4713 $ref: '#/components/schemas/UUIDv4'
4725 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
4727 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
4729 $ref: '#/components/schemas/AccountSummary'
4731 $ref: '#/components/schemas/VideoChannelSummary'
4755 totalRepliesFromVideoAuthor:
4760 $ref: '#/components/schemas/Account'
4761 VideoCommentThreadTree:
4764 $ref: '#/components/schemas/VideoComment'
4768 $ref: '#/components/schemas/VideoCommentThreadTree'
4772 $ref: '#/components/schemas/VideoConstantString-Language'
4827 $ref: '#/components/schemas/ActorImage'
4830 - $ref: '#/components/schemas/Actor'
4843 description: timestamp within the video, in seconds
4910 allowedForCurrentIP:
4912 requiresEmailVerification:
5116 requiresEmailVerification:
5141 allowAdditionalExtensions:
5211 $ref: '#/components/schemas/Actor'
5213 $ref: '#/components/schemas/Actor'
5216 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5229 PredefinedAbuseReasons:
5230 description: Reason categories that help triage reports
5261 - activitypub-http-unicast
5262 - activitypub-http-broadcast
5263 - activitypub-http-fetcher
5264 - activitypub-follow
5270 - activitypub-refresher
5274 additionalProperties: true
5277 additionalProperties: true
5301 VideoUploadResponse:
5310 $ref: '#/components/schemas/UUIDv4'
5311 CommentThreadResponse:
5320 $ref: '#/components/schemas/VideoComment'
5321 CommentThreadPostResponse:
5324 $ref: '#/components/schemas/VideoComment'
5334 $ref: '#/components/schemas/Video'
5342 description: The user username
5348 description: The user email
5351 description: Auth plugin to use to authenticate the user
5354 description: Theme enabled by this user
5357 description: Has the user confirmed their email address?
5359 $ref: '#/components/schemas/NSFWPolicy'
5362 description: Enable P2P in the player
5365 description: Automatically start playing the video on the watch page
5367 $ref: '#/components/schemas/UserRole'
5376 description: The user video quota
5379 description: The user daily video quota
5384 abusesAcceptedCount:
5390 noInstanceConfigWarningModal:
5401 $ref: '#/components/schemas/Account'
5405 $ref: '#/components/schemas/VideoChannel'
5410 description: The user username
5416 description: The user password. If the smtp server is configured, you can leave empty and an email will be sent
5422 description: The user email
5425 description: The user video quota
5428 description: The user daily video quota
5431 description: The user default channel username
5433 $ref: '#/components/schemas/UserRole'
5435 $ref: '#/components/schemas/UserAdminFlags'
5447 description: The user id
5451 description: The updated email of the user
5454 description: Set the email as verified
5457 description: The updated video quota of the user
5460 description: The updated daily video quota of the user
5464 description: The auth plugin to use to authenticate the user
5465 example: 'peertube-plugin-auth-saml2'
5467 $ref: '#/components/schemas/UserRole'
5469 $ref: '#/components/schemas/UserAdminFlags'
5477 description: Your new password
5483 description: Your new email
5486 description: Your new displayNSFW
5493 description: Your new autoPlayVideo
5503 description: Id of the video
5506 description: Rating of the video
5513 $ref: '#/components/schemas/Video'
5516 description: 'Rating of the video'
5524 description: The username of the user
5527 pattern: '/^[a-z0-9._]{1,50}$/'
5531 description: The password of the user
5537 description: The email of the user
5540 description: The user display name
5548 description: The username for the default channel
5549 pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
5552 description: The display name for the default channel
5572 description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
5573 example: Please support my work on <insert crowdfunding plateform>! <3
5578 - $ref: '#/components/schemas/VideoChannelCommon'
5589 - $ref: '#/components/schemas/VideoChannelCommon'
5591 bulkVideosSupportUpdate:
5593 description: 'Update the support field for all videos of this channel'
5598 name: 'media:peerLink'
5607 - application/x-bittorrent
5613 name: 'media:content'
5644 VideoCommentsForXML:
5679 description: video watch page URL
5682 description: video canonical URL
5686 description: video publication date
5689 description: video description
5692 description: video description
5695 description: publisher user name
5698 description: video category (MRSS)
5701 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
5716 description: video embed path, relative to the canonical URL domain (MRSS)
5725 description: video watch path, relative to the canonical URL domain (MRSS)
5746 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
5747 'media:description':
5754 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
5757 description: main streamable file for the video
5767 - application/x-bittorrent
5776 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)
5779 - $ref: '#/components/schemas/MRSSPeerLink'
5780 - $ref: '#/components/schemas/MRSSGroupContent'
5781 NotificationSettingValue:
5802 Notification type, following the `UserNotificationType` enum:
5804 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
5806 - `2` NEW_COMMENT_ON_MY_VIDEO
5808 - `3` NEW_ABUSE_FOR_MODERATORS
5810 - `4` BLACKLIST_ON_MY_VIDEO
5812 - `5` UNBLACKLIST_ON_MY_VIDEO
5814 - `6` MY_VIDEO_PUBLISHED
5816 - `7` MY_VIDEO_IMPORT_SUCCESS
5818 - `8` MY_VIDEO_IMPORT_ERROR
5820 - `9` NEW_USER_REGISTRATION
5824 - `11` COMMENT_MENTION
5826 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
5828 - `13` NEW_INSTANCE_FOLLOWER
5830 - `14` AUTO_INSTANCE_FOLLOWING
5836 - $ref: '#/components/schemas/VideoInfo'
5840 $ref: '#/components/schemas/ActorInfo'
5849 $ref: '#/components/schemas/VideoInfo'
5870 $ref: '#/components/schemas/VideoInfo'
5872 $ref: '#/components/schemas/ActorInfo'
5881 - $ref: '#/components/schemas/VideoInfo'
5890 - $ref: '#/components/schemas/VideoInfo'
5894 - $ref: '#/components/schemas/ActorInfo'
5902 $ref: '#/components/schemas/ActorInfo'
5930 NotificationListResponse:
5939 $ref: '#/components/schemas/Notification'
5944 example: peertube-plugin-auth-ldap
5972 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
5975 additionalProperties: true
5991 $ref: '#/components/schemas/Plugin'
5998 description: User can stream multiple times in a permanent live
6007 description: RTMP stream key to use to stream into this live video
6011 description: User can stream multiple times in a permanent live
6018 'https://search.example.org/api/v1/search/videos':
6020 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6023 description: successful operation
6027 $ref: '#/components/schemas/VideoListResponse'