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. Here is how it is configured by default:
55 | Endpoint | Calls | Time frame |
56 |-------------------------|------------------|---------------------------|
57 | `/*` | 50 | 10 seconds |
58 | `POST /users/token` | 15 | 5 minutes |
59 | `POST /users/register` | 2¹ | 5 minutes |
60 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
62 Depending on the endpoint, ¹failed requests are not taken into account. A service
63 limit is announced by a `429 Too Many Requests` status code.
65 You can get details about how your rate limit is going by reading following headers:
67 | Header | Description |
68 |-------------------------|------------------------------------------------------------|
69 | X-RateLimit-Limit | Number of max requests allowed in the current time period |
70 | X-RateLimit-Remaining | Number of remaining requests in the current time period |
71 | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp |
72 | Retry-After | Seconds to delay after the first `429` is received |
74 url: https://docs.joinpeertube.org/api-rest-reference.html
78 Accounts encompass remote accounts discovered across the federation,
79 and correspond to the main Actor, along with video channels a user can create, which
82 When a comment is posted, it is done with your Account's Actor.
85 Using some features of PeerTube require authentication, for which User
86 provide different levels of permission as well as associated user
87 information. Each user has a corresponding local Account for federation.
90 Operations related to your own User, when logged-in.
91 - name: My Subscriptions
93 Operations related to your subscriptions to video channels, their
94 new videos, and how to keep up to date with their latest publications!
97 Operations related to your watch history.
98 - name: My Notifications
100 Notifications following new videos, follows or reports. They allow you
101 to keep track of the interactions and overall important information that
102 concerns you. You MAY set per-notification type delivery preference, to
103 receive the info either by mail, by in-browser notification or both.
106 Each server exposes public information regarding supported videos and
110 Jobs are long-running tasks enqueued and processed by the instance
111 itself. No additional worker registration is currently available.
112 - name: Instance Follows
114 Managing servers which the instance interacts with is crucial to the
115 concept of federation in PeerTube and external video indexation. The PeerTube
116 server then deals with inter-server ActivityPub operations and propagates
117 information across its social graph by posting activities to actors' inbox
120 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
121 - name: Instance Redundancy
123 Redundancy is part of the inter-server solidarity that PeerTube fosters.
124 Manage the list of instances you wish to help by seeding their videos according
125 to the policy of video selection of your choice. Note that you have a similar functionality
126 to mirror individual videos, see `Video Mirroring`.
128 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
131 Managing plugins installed from a local path or from NPM, or search for new ones.
133 url: https://docs.joinpeertube.org/api-plugins
136 Abuses deal with reports of local or remote videos/comments/accounts alike.
139 Operations dealing with listing, uploading, fetching or modifying videos.
142 The search helps to find _videos_ or _channels_ from within the instance and beyond.
143 Videos from other instances federated by the instance (that is, instances
144 followed by the instance) can be found via keywords and other criteria of
147 Administrators can also enable the use of a remote search system, indexing
148 videos and channels not could be not federated by the instance.
149 - name: Video Comments
151 Operations dealing with comments to a video. Comments are organized in
153 - name: Video Playlists
155 Operations dealing with playlists of videos. Playlists are bound to users
157 - name: Video Channels
159 Operations dealing with the creation, modification and listing of videos within a channel.
162 Operations dealing with blocking videos (removing them from view and
163 preventing interactions).
166 Like/dislike a video.
169 Server syndication feeds
187 - Video Ownership Change
200 - name: Instance Configuration
204 - Instance Redundancy
214 summary: Get an account
216 - $ref: '#/components/parameters/name'
219 description: successful operation
223 $ref: '#/components/schemas/Account'
225 description: account not found
226 '/accounts/{name}/videos':
231 summary: 'List videos of an account'
233 - $ref: '#/components/parameters/name'
234 - $ref: '#/components/parameters/categoryOneOf'
235 - $ref: '#/components/parameters/isLive'
236 - $ref: '#/components/parameters/tagsOneOf'
237 - $ref: '#/components/parameters/tagsAllOf'
238 - $ref: '#/components/parameters/licenceOneOf'
239 - $ref: '#/components/parameters/languageOneOf'
240 - $ref: '#/components/parameters/nsfw'
241 - $ref: '#/components/parameters/filter'
242 - $ref: '#/components/parameters/skipCount'
243 - $ref: '#/components/parameters/start'
244 - $ref: '#/components/parameters/count'
245 - $ref: '#/components/parameters/videosSort'
248 description: successful operation
252 $ref: '#/components/schemas/VideoListResponse'
256 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
257 .then(function(response) {
258 return response.json()
259 }).then(function(data) {
265 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
271 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
273 http = Net::HTTP.new(uri.host, uri.port)
276 response = http.get(uri.request_uri)
278 puts JSON.parse(response.read_body)
283 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
291 summary: List accounts
293 - $ref: '#/components/parameters/start'
294 - $ref: '#/components/parameters/count'
295 - $ref: '#/components/parameters/sort'
298 description: successful operation
304 $ref: '#/components/schemas/Account'
309 summary: Get instance public configuration
312 description: successful operation
316 $ref: '#/components/schemas/ServerConfig'
319 summary: Get instance "About" information
324 description: successful operation
328 $ref: '#/components/schemas/ServerConfigAbout'
331 summary: Get instance runtime configuration
339 description: successful operation
343 $ref: '#/components/schemas/ServerConfigCustom'
345 summary: Set instance runtime configuration
353 description: successful operation
355 x-summary: field inconsistencies
358 - the emailer is disabled and the instance is open to registrations
359 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
361 summary: Delete instance runtime configuration
369 description: successful operation
372 summary: List instance jobs
382 description: The state of the job ('' for for no filter)
392 - $ref: '#/components/parameters/jobType'
393 - $ref: '#/components/parameters/start'
394 - $ref: '#/components/parameters/count'
395 - $ref: '#/components/parameters/sort'
398 description: successful operation
411 $ref: '#/components/schemas/Job'
412 '/server/following/{host}':
419 summary: Unfollow a server
424 description: 'The host to unfollow '
430 description: successful operation
435 summary: List instance followers
437 - $ref: '#/components/parameters/start'
438 - $ref: '#/components/parameters/count'
439 - $ref: '#/components/parameters/sort'
442 description: successful operation
448 $ref: '#/components/schemas/Follow'
453 summary: List instances followed by the server
472 - $ref: '#/components/parameters/start'
473 - $ref: '#/components/parameters/count'
474 - $ref: '#/components/parameters/sort'
477 description: successful operation
483 $ref: '#/components/schemas/Follow'
490 summary: Follow a server
493 description: successful operation
495 description: cannot follow a non-HTTPS server
510 summary: Create a user
518 description: user created
522 $ref: '#/components/schemas/AddUserResponse'
526 operationId: getUserId
528 id: '$response.body#/user/id'
531 operationId: putUserId
533 id: '$response.body#/user/id'
536 operationId: delUserId
538 id: '$response.body#/user/id'
540 description: insufficient authority to create an admin or moderator
545 $ref: '#/components/schemas/AddUser'
546 description: User to create
556 - $ref: '#/components/parameters/usersSearch'
557 - $ref: '#/components/parameters/usersBlocked'
558 - $ref: '#/components/parameters/start'
559 - $ref: '#/components/parameters/count'
560 - $ref: '#/components/parameters/usersSort'
563 description: successful operation
569 $ref: '#/components/schemas/User'
572 - $ref: '#/components/parameters/id'
574 summary: Delete a user
580 operationId: delUserId
583 description: successful operation
590 operationId: getUserId
593 description: successful operation
597 $ref: '#/components/schemas/User'
599 summary: Update a user
604 operationId: putUserId
607 description: successful operation
612 $ref: '#/components/schemas/UpdateUser'
616 summary: Register a user
621 description: successful operation
626 $ref: '#/components/schemas/RegisterUser'
630 summary: Get my user information
638 description: successful operation
644 $ref: '#/components/schemas/User'
646 summary: Update my user information
654 description: successful operation
659 $ref: '#/components/schemas/UpdateMe'
661 /users/me/videos/imports:
663 summary: Get video imports of my user
671 - $ref: '#/components/parameters/start'
672 - $ref: '#/components/parameters/count'
673 - $ref: '#/components/parameters/sort'
676 description: successful operation
680 $ref: '#/components/schemas/VideoImport'
681 /users/me/video-quota-used:
683 summary: Get my user used quota
691 description: successful operation
696 '/users/me/videos/{videoId}/rating':
698 summary: Get rate of my user for a video
708 description: 'The video id '
713 description: successful operation
717 $ref: '#/components/schemas/GetMeVideoRating'
720 summary: Get videos of my user
728 - $ref: '#/components/parameters/start'
729 - $ref: '#/components/parameters/count'
730 - $ref: '#/components/parameters/sort'
733 description: successful operation
737 $ref: '#/components/schemas/VideoListResponse'
738 /users/me/subscriptions:
740 summary: Get my user subscriptions
747 - $ref: '#/components/parameters/start'
748 - $ref: '#/components/parameters/count'
749 - $ref: '#/components/parameters/sort'
752 description: successful operation
756 summary: Add subscription to my user
769 description: uri of the video channels to subscribe to
775 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
778 description: successful operation
779 /users/me/subscriptions/exist:
781 summary: Get if subscriptions exist for my user
788 - $ref: '#/components/parameters/subscriptionsUris'
791 description: successful operation
796 /users/me/subscriptions/videos:
798 summary: List videos of subscriptions of my user
806 - $ref: '#/components/parameters/categoryOneOf'
807 - $ref: '#/components/parameters/isLive'
808 - $ref: '#/components/parameters/tagsOneOf'
809 - $ref: '#/components/parameters/tagsAllOf'
810 - $ref: '#/components/parameters/licenceOneOf'
811 - $ref: '#/components/parameters/languageOneOf'
812 - $ref: '#/components/parameters/nsfw'
813 - $ref: '#/components/parameters/filter'
814 - $ref: '#/components/parameters/skipCount'
815 - $ref: '#/components/parameters/start'
816 - $ref: '#/components/parameters/count'
817 - $ref: '#/components/parameters/videosSort'
820 description: successful operation
824 $ref: '#/components/schemas/VideoListResponse'
825 '/users/me/subscriptions/{subscriptionHandle}':
827 summary: Get subscription of my user
834 - $ref: '#/components/parameters/subscriptionHandle'
837 description: successful operation
841 $ref: '#/components/schemas/VideoChannel'
843 summary: Delete subscription of my user
850 - $ref: '#/components/parameters/subscriptionHandle'
853 description: successful operation
854 /users/me/notifications:
856 summary: List my notifications
864 description: only list unread notifications
867 - $ref: '#/components/parameters/start'
868 - $ref: '#/components/parameters/count'
869 - $ref: '#/components/parameters/sort'
872 description: successful operation
876 $ref: '#/components/schemas/NotificationListResponse'
877 /users/me/notifications/read:
879 summary: Mark notifications as read by their id
892 description: ids of the notifications to mark as read
899 description: successful operation
900 /users/me/notifications/read-all:
902 summary: Mark all my notification as read
909 description: successful operation
910 /users/me/notification-settings:
912 summary: Update my notification settings
923 newVideoFromSubscription:
924 $ref: '#/components/schemas/NotificationSettingValue'
926 $ref: '#/components/schemas/NotificationSettingValue'
928 $ref: '#/components/schemas/NotificationSettingValue'
929 videoAutoBlacklistAsModerator:
930 $ref: '#/components/schemas/NotificationSettingValue'
932 $ref: '#/components/schemas/NotificationSettingValue'
934 $ref: '#/components/schemas/NotificationSettingValue'
935 myVideoImportFinished:
936 $ref: '#/components/schemas/NotificationSettingValue'
938 $ref: '#/components/schemas/NotificationSettingValue'
940 $ref: '#/components/schemas/NotificationSettingValue'
942 $ref: '#/components/schemas/NotificationSettingValue'
944 $ref: '#/components/schemas/NotificationSettingValue'
945 autoInstanceFollowing:
946 $ref: '#/components/schemas/NotificationSettingValue'
949 description: successful operation
950 /users/me/history/videos:
952 summary: List watched videos history
958 - $ref: '#/components/parameters/start'
959 - $ref: '#/components/parameters/count'
960 - $ref: '#/components/parameters/search'
963 description: successful operation
967 $ref: '#/components/schemas/VideoListResponse'
968 /users/me/history/videos/remove:
970 summary: Clear video history
982 description: history before this date will be deleted
987 description: successful operation
988 /users/me/avatar/pick:
990 summary: Update my user avatar
997 description: successful operation
1004 $ref: '#/components/schemas/ActorImage'
1006 description: image file too large
1008 X-File-Maximum-Size:
1012 description: Maximum file size for the avatar
1015 multipart/form-data:
1020 description: The file to upload.
1025 contentType: image/png, image/jpeg
1028 summary: Delete my avatar
1035 description: successful operation
1039 summary: List video ownership changes
1041 - Video Ownership Change
1046 description: successful operation
1047 '/videos/ownership/{id}/accept':
1049 summary: Accept ownership change request
1051 - Video Ownership Change
1055 - $ref: '#/components/parameters/idOrUUID'
1058 description: successful operation
1060 description: cannot terminate an ownership change of another user
1062 description: video owneship change not found
1063 '/videos/ownership/{id}/refuse':
1065 summary: Refuse ownership change request
1067 - Video Ownership Change
1071 - $ref: '#/components/parameters/idOrUUID'
1074 description: successful operation
1076 description: cannot terminate an ownership change of another user
1078 description: video owneship change not found
1079 '/videos/{id}/give-ownership':
1081 summary: Request ownership change
1083 - Video Ownership Change
1087 - $ref: '#/components/parameters/idOrUUID'
1091 application/x-www-form-urlencoded:
1101 description: successful operation
1103 description: changing video ownership to a remote account is not supported yet
1105 description: video not found
1108 summary: List videos
1112 - $ref: '#/components/parameters/categoryOneOf'
1113 - $ref: '#/components/parameters/isLive'
1114 - $ref: '#/components/parameters/tagsOneOf'
1115 - $ref: '#/components/parameters/tagsAllOf'
1116 - $ref: '#/components/parameters/licenceOneOf'
1117 - $ref: '#/components/parameters/languageOneOf'
1118 - $ref: '#/components/parameters/nsfw'
1119 - $ref: '#/components/parameters/filter'
1120 - $ref: '#/components/parameters/skipCount'
1121 - $ref: '#/components/parameters/start'
1122 - $ref: '#/components/parameters/count'
1123 - $ref: '#/components/parameters/videosSort'
1126 description: successful operation
1130 $ref: '#/components/schemas/VideoListResponse'
1133 summary: List available video categories
1138 description: successful operation
1147 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1150 summary: List available video licences
1155 description: successful operation
1164 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1167 summary: List available video languages
1172 description: successful operation
1181 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1184 summary: List available video privacies
1189 description: successful operation
1198 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1201 summary: Update a video
1207 - $ref: '#/components/parameters/idOrUUID'
1210 description: successful operation
1213 multipart/form-data:
1218 description: Video thumbnail file
1222 description: Video preview file
1226 description: Video category
1230 description: Video licence
1234 description: Video language
1237 $ref: '#/components/schemas/VideoPrivacySet'
1239 description: Video description
1242 description: Whether or not we wait transcoding before publish the video
1245 description: A text tell the audience how to support the video creator
1246 example: Please support my work on <insert crowdfunding plateform>! <3
1249 description: Whether or not this video contains sensitive content
1252 description: Video name
1257 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1266 description: Enable or disable comments for this video
1268 originallyPublishedAt:
1269 description: Date when the content was originally published
1273 $ref: '#/components/schemas/VideoScheduledUpdate'
1276 contentType: image/jpeg
1278 contentType: image/jpeg
1280 summary: Get a video
1284 - $ref: '#/components/parameters/idOrUUID'
1287 description: successful operation
1291 $ref: '#/components/schemas/VideoDetails'
1293 summary: Delete a video
1299 - $ref: '#/components/parameters/idOrUUID'
1302 description: successful operation
1303 '/videos/{id}/description':
1305 summary: Get complete video description
1309 - $ref: '#/components/parameters/idOrUUID'
1312 description: successful operation
1317 '/videos/{id}/views':
1319 summary: Add a view to a video
1323 - $ref: '#/components/parameters/idOrUUID'
1326 description: successful operation
1327 '/videos/{id}/watching':
1329 summary: Set watching progress of a video
1335 - $ref: '#/components/parameters/idOrUUID'
1340 $ref: '#/components/schemas/UserWatchingVideo'
1344 description: successful operation
1347 summary: Upload a video
1354 description: successful operation
1358 $ref: '#/components/schemas/VideoUploadResponse'
1360 description: invalid file field, schedule date or parameter
1362 description: video didn't pass upload filter
1364 description: upload has timed out
1366 description: video file too large, due to quota or max body size limit set by the reverse-proxy
1368 X-File-Maximum-Size:
1372 description: Maximum file size for the video
1374 description: video type unsupported
1376 description: video unreadable
1379 multipart/form-data:
1384 description: Video file
1388 description: Channel id that will contain this video
1391 description: Video thumbnail file
1395 description: Video preview file
1399 $ref: '#/components/schemas/VideoPrivacySet'
1401 description: Video category
1405 description: Video licence
1409 description: Video language
1412 description: Video description
1415 description: Whether or not we wait transcoding before publish the video
1418 description: A text tell the audience how to support the video creator
1419 example: Please support my work on <insert crowdfunding plateform>! <3
1422 description: Whether or not this video contains sensitive content
1425 description: Video name
1430 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1440 description: Enable or disable comments for this video
1443 description: Enable or disable downloading for this video
1445 originallyPublishedAt:
1446 description: Date when the content was originally published
1450 $ref: '#/components/schemas/VideoScheduledUpdate'
1457 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1459 contentType: image/jpeg
1461 contentType: image/jpeg
1466 USERNAME="<your_username>"
1467 PASSWORD="<your_password>"
1468 FILE_PATH="<your_file_path>"
1469 CHANNEL_ID="<your_channel_id>"
1472 API_PATH="https://peertube2.cpy.re/api/v1"
1474 client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1475 client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1476 token=$(curl -s "$API_PATH/users/token" \
1477 --data client_id="$client_id" \
1478 --data client_secret="$client_secret" \
1479 --data grant_type=password \
1480 --data response_type=code \
1481 --data username="$USERNAME" \
1482 --data password="$PASSWORD" \
1483 | jq -r ".access_token")
1485 curl -s "$API_PATH/videos/upload" \
1486 -H "Authorization: Bearer $token" \
1488 --form videofile=@"$FILE_PATH" \
1489 --form channelId=$CHANNEL_ID \
1493 summary: Import a video
1494 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1501 multipart/form-data:
1506 description: Torrent File
1510 description: HTTP target URL
1513 description: Magnet URI
1516 description: Channel id that will contain this video
1519 description: Video thumbnail file
1523 description: Video preview file
1527 $ref: '#/components/schemas/VideoPrivacySet'
1529 description: Video category
1533 description: Video licence
1537 description: Video language
1540 description: Video description
1543 description: Whether or not we wait transcoding before publish the video
1546 description: A text tell the audience how to support the video creator
1547 example: Please support my work on <insert crowdfunding plateform>! <3
1550 description: Whether or not this video contains sensitive content
1553 description: Video name
1558 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1567 description: Enable or disable comments for this video
1570 description: Enable or disable downloading for this video
1573 $ref: '#/components/schemas/VideoScheduledUpdate'
1579 contentType: application/x-bittorrent
1581 contentType: image/jpeg
1583 contentType: image/jpeg
1586 description: successful operation
1590 $ref: '#/components/schemas/VideoUploadResponse'
1592 description: '`magnetUri` or `targetUrl` or a torrent file missing'
1594 description: video didn't pass pre-import filter
1596 description: HTTP or Torrent/magnetURI import not enabled
1600 summary: Create a live
1608 description: successful operation
1612 $ref: '#/components/schemas/VideoUploadResponse'
1614 description: Live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
1617 multipart/form-data:
1622 description: Channel id that will contain this live video
1627 description: User can stream multiple times in a permanent live
1630 description: Live video/replay thumbnail file
1634 description: Live video/replay preview file
1638 $ref: '#/components/schemas/VideoPrivacySet'
1640 description: Live video/replay category
1643 description: Live video/replay licence
1646 description: Live video/replay language
1649 description: Live video/replay description
1652 description: A text tell the audience how to support the creator
1653 example: Please support my work on <insert crowdfunding plateform>! <3
1656 description: Whether or not this live video/replay contains sensitive content
1659 description: Live video/replay name
1664 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
1673 description: Enable or disable comments for this live video/replay
1676 description: Enable or disable downloading for the replay of this live
1683 contentType: image/jpeg
1685 contentType: image/jpeg
1689 summary: Get a live information
1696 - $ref: '#/components/parameters/idOrUUID'
1699 description: successful operation
1703 $ref: '#/components/schemas/LiveVideoResponse'
1705 summary: Update a live information
1712 - $ref: '#/components/parameters/idOrUUID'
1717 $ref: '#/components/schemas/LiveVideoUpdate'
1720 description: Successful operation
1722 description: Bad parameters or trying to update a live that has already started
1724 description: Trying to save replay of the live but saving replay is not enabled on the instance
1728 summary: List my abuses
1737 description: only list the report with this id
1743 $ref: '#/components/schemas/AbuseStateSet'
1744 - $ref: '#/components/parameters/start'
1745 - $ref: '#/components/parameters/count'
1746 - $ref: '#/components/parameters/abusesSort'
1749 description: successful operation
1755 $ref: '#/components/schemas/Abuse'
1759 summary: List abuses
1769 description: only list the report with this id
1772 - name: predefinedReason
1774 description: predefined reason the listed reports should contain
1776 $ref: '#/components/schemas/PredefinedAbuseReasons'
1779 description: plain search that will match with video titles, reporter names and more
1785 $ref: '#/components/schemas/AbuseStateSet'
1786 - name: searchReporter
1788 description: only list reports of a specific reporter
1791 - name: searchReportee
1792 description: only list reports of a specific reportee
1798 description: only list reports of a specific video
1801 - name: searchVideoChannel
1803 description: only list reports of a specific video channel
1808 description: only list blacklisted or deleted videos
1816 description: only list account, comment or video reports
1823 - $ref: '#/components/parameters/start'
1824 - $ref: '#/components/parameters/count'
1825 - $ref: '#/components/parameters/abusesSort'
1828 description: successful operation
1834 $ref: '#/components/schemas/Abuse'
1837 summary: Report an abuse
1850 description: Reason why the user reports this video
1855 $ref: '#/components/schemas/PredefinedAbuseReasons'
1860 description: Video id to report
1864 description: Timestamp in the video that marks the beginning of the report
1868 description: Timestamp in the video that marks the ending of the report
1874 description: Comment id to report
1880 description: Account id to report
1886 description: successful operation
1888 description: incorrect request parameters
1889 '/abuses/{abuseId}':
1891 summary: Update an abuse
1899 - $ref: '#/components/parameters/abuseId'
1907 $ref: '#/components/schemas/AbuseStateSet'
1910 description: Update the report comment visible only to the moderation team
1915 description: successful operation
1917 description: abuse not found
1921 summary: Delete an abuse
1927 - $ref: '#/components/parameters/abuseId'
1930 description: successful operation
1932 description: block not found
1933 '/abuses/{abuseId}/messages':
1935 summary: List messages of an abuse
1941 - $ref: '#/components/parameters/abuseId'
1944 description: successful operation
1950 $ref: '#/components/schemas/AbuseMessage'
1953 summary: Add message to an abuse
1959 - $ref: '#/components/parameters/abuseId'
1968 description: Message to send
1976 description: successful operation
1978 description: incorrect request parameters
1979 '/abuses/{abuseId}/messages/{abuseMessageId}':
1981 summary: Delete an abuse message
1987 - $ref: '#/components/parameters/abuseId'
1988 - $ref: '#/components/parameters/abuseMessageId'
1991 description: successful operation
1993 '/videos/{id}/blacklist':
1995 summary: Block a video
2003 - $ref: '#/components/parameters/idOrUUID'
2006 description: successful operation
2008 summary: Unblock a video by its id
2016 - $ref: '#/components/parameters/idOrUUID'
2019 description: successful operation
2021 description: block not found
2026 summary: List video blocks
2035 list only blocks that match this type:
2039 - `2`: automatic block that needs review
2047 description: plain search that will match with video titles, and more
2050 - $ref: '#/components/parameters/start'
2051 - $ref: '#/components/parameters/count'
2052 - $ref: '#/components/parameters/blacklistsSort'
2055 description: successful operation
2067 $ref: '#/components/schemas/VideoBlacklist'
2068 /videos/{id}/captions:
2070 summary: List captions of a video
2074 - $ref: '#/components/parameters/idOrUUID'
2077 description: successful operation
2089 $ref: '#/components/schemas/VideoCaption'
2090 /videos/{id}/captions/{captionLanguage}:
2092 summary: Add or replace a video caption
2099 - $ref: '#/components/parameters/idOrUUID'
2100 - $ref: '#/components/parameters/captionLanguage'
2103 multipart/form-data:
2108 description: The file to upload.
2113 contentType: text/vtt, application/x-subrip, text/plain
2116 description: successful operation
2118 description: video or language not found
2120 summary: Delete a video caption
2127 - $ref: '#/components/parameters/idOrUUID'
2128 - $ref: '#/components/parameters/captionLanguage'
2131 description: successful operation
2133 description: video or language or caption for that language not found
2136 summary: List video channels
2140 - $ref: '#/components/parameters/start'
2141 - $ref: '#/components/parameters/count'
2142 - $ref: '#/components/parameters/sort'
2145 description: successful operation
2157 $ref: '#/components/schemas/VideoChannel'
2159 summary: Create a video channel
2166 description: successful operation
2171 $ref: '#/components/schemas/VideoChannelCreate'
2172 '/video-channels/{channelHandle}':
2174 summary: Get a video channel
2178 - $ref: '#/components/parameters/channelHandle'
2181 description: successful operation
2185 $ref: '#/components/schemas/VideoChannel'
2187 summary: Update a video channel
2193 - $ref: '#/components/parameters/channelHandle'
2196 description: successful operation
2201 $ref: '#/components/schemas/VideoChannelUpdate'
2203 summary: Delete a video channel
2209 - $ref: '#/components/parameters/channelHandle'
2212 description: successful operation
2213 '/video-channels/{channelHandle}/videos':
2215 summary: List videos of a video channel
2220 - $ref: '#/components/parameters/channelHandle'
2221 - $ref: '#/components/parameters/categoryOneOf'
2222 - $ref: '#/components/parameters/isLive'
2223 - $ref: '#/components/parameters/tagsOneOf'
2224 - $ref: '#/components/parameters/tagsAllOf'
2225 - $ref: '#/components/parameters/licenceOneOf'
2226 - $ref: '#/components/parameters/languageOneOf'
2227 - $ref: '#/components/parameters/nsfw'
2228 - $ref: '#/components/parameters/filter'
2229 - $ref: '#/components/parameters/skipCount'
2230 - $ref: '#/components/parameters/start'
2231 - $ref: '#/components/parameters/count'
2232 - $ref: '#/components/parameters/videosSort'
2235 description: successful operation
2239 $ref: '#/components/schemas/VideoListResponse'
2240 '/video-channels/{channelHandle}/avatar/pick':
2242 summary: Update channel avatar
2248 - $ref: '#/components/parameters/channelHandle'
2251 description: successful operation
2258 $ref: '#/components/schemas/ActorImage'
2260 description: image file too large
2262 X-File-Maximum-Size:
2266 description: Maximum file size for the avatar
2269 multipart/form-data:
2274 description: The file to upload.
2279 contentType: image/png, image/jpeg
2280 '/video-channels/{channelHandle}/avatar':
2282 summary: Delete channel avatar
2288 - $ref: '#/components/parameters/channelHandle'
2291 description: successful operation
2294 '/video-channels/{channelHandle}/banner/pick':
2296 summary: Update channel banner
2302 - $ref: '#/components/parameters/channelHandle'
2305 description: successful operation
2312 $ref: '#/components/schemas/ActorImage'
2314 description: image file too large
2316 X-File-Maximum-Size:
2320 description: Maximum file size for the banner
2323 multipart/form-data:
2328 description: The file to upload.
2333 contentType: image/png, image/jpeg
2334 '/video-channels/{channelHandle}/banner':
2336 summary: Delete channel banner
2342 - $ref: '#/components/parameters/channelHandle'
2345 description: successful operation
2347 /video-playlists/privacies:
2349 summary: List available playlist privacies
2354 description: successful operation
2363 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2367 summary: List video playlists
2371 - $ref: '#/components/parameters/start'
2372 - $ref: '#/components/parameters/count'
2373 - $ref: '#/components/parameters/sort'
2376 description: successful operation
2388 $ref: '#/components/schemas/VideoPlaylist'
2390 summary: Create a video playlist
2391 description: 'If the video playlist is set as public, the videoChannelId is mandatory.'
2398 description: successful operation
2410 $ref: '#/components/schemas/UUIDv4'
2413 multipart/form-data:
2418 description: Video playlist display name
2423 description: Video playlist thumbnail file
2427 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2429 description: Video playlist description
2432 description: Video channel in which the playlist will be published
2438 contentType: image/jpeg
2440 /video-playlists/{id}:
2442 summary: Get a video playlist
2446 - $ref: '#/components/parameters/idOrUUID'
2449 description: successful operation
2453 $ref: '#/components/schemas/VideoPlaylist'
2455 summary: Update a video playlist
2456 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2463 description: successful operation
2465 - $ref: '#/components/parameters/idOrUUID'
2468 multipart/form-data:
2473 description: Video playlist display name
2478 description: Video playlist thumbnail file
2482 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2484 description: Video playlist description
2487 description: Video channel in which the playlist will be published
2491 contentType: image/jpeg
2493 summary: Delete a video playlist
2499 - $ref: '#/components/parameters/idOrUUID'
2502 description: successful operation
2504 /video-playlists/{id}/videos:
2506 summary: 'List videos of a playlist'
2511 - $ref: '#/components/parameters/idOrUUID'
2514 description: successful operation
2518 $ref: '#/components/schemas/VideoListResponse'
2520 summary: 'Add a video in a playlist'
2527 - $ref: '#/components/parameters/idOrUUID'
2530 description: successful operation
2536 videoPlaylistElement:
2549 description: 'Video to add in the playlist'
2552 description: 'Start the video at this specific timestamp (in seconds)'
2555 description: 'Stop the video at this specific timestamp (in seconds)'
2559 /video-playlists/{id}/videos/reorder:
2561 summary: 'Reorder a playlist'
2567 - $ref: '#/components/parameters/idOrUUID'
2570 description: successful operation
2579 description: 'Start position of the element to reorder'
2581 insertAfterPosition:
2583 description: 'New position for the block to reorder, to add the block before the first element'
2587 description: 'How many element from `startPosition` to reorder'
2591 - insertAfterPosition
2593 /video-playlists/{id}/videos/{playlistElementId}:
2595 summary: 'Update a playlist element'
2601 - $ref: '#/components/parameters/idOrUUID'
2602 - $ref: '#/components/parameters/playlistElementId'
2605 description: successful operation
2614 description: 'Start the video at this specific timestamp (in seconds)'
2617 description: 'Stop the video at this specific timestamp (in seconds)'
2619 summary: 'Delete an element from a playlist'
2625 - $ref: '#/components/parameters/idOrUUID'
2626 - $ref: '#/components/parameters/playlistElementId'
2629 description: successful operation
2631 '/users/me/video-playlists/videos-exist':
2633 summary: 'Check video exists in my playlists'
2642 description: The video ids to check
2649 description: successful operation
2669 '/accounts/{name}/video-channels':
2671 summary: List video channels of an account
2676 - $ref: '#/components/parameters/name'
2679 description: include view statistics for the last 30 days (only if authentified as the account user)
2682 - $ref: '#/components/parameters/start'
2683 - $ref: '#/components/parameters/count'
2684 - $ref: '#/components/parameters/sort'
2687 description: successful operation
2698 $ref: '#/components/schemas/VideoChannel'
2699 '/accounts/{name}/ratings':
2701 summary: List ratings of an account
2707 - $ref: '#/components/parameters/name'
2708 - $ref: '#/components/parameters/start'
2709 - $ref: '#/components/parameters/count'
2710 - $ref: '#/components/parameters/sort'
2714 description: Optionally filter which ratings to retrieve
2722 description: successful operation
2728 $ref: '#/components/schemas/VideoRating'
2729 '/videos/{id}/comment-threads':
2731 summary: List threads of a video
2735 - $ref: '#/components/parameters/idOrUUID'
2736 - $ref: '#/components/parameters/start'
2737 - $ref: '#/components/parameters/count'
2738 - $ref: '#/components/parameters/commentsSort'
2741 description: successful operation
2745 $ref: '#/components/schemas/CommentThreadResponse'
2747 summary: Create a thread
2753 - $ref: '#/components/parameters/idOrUUID'
2756 description: successful operation
2760 $ref: '#/components/schemas/CommentThreadPostResponse'
2762 description: video does not exist
2771 description: 'Text comment'
2775 '/videos/{id}/comment-threads/{threadId}':
2777 summary: Get a thread
2781 - $ref: '#/components/parameters/idOrUUID'
2782 - $ref: '#/components/parameters/threadId'
2785 description: successful operation
2789 $ref: '#/components/schemas/VideoCommentThreadTree'
2790 '/videos/{id}/comments/{commentId}':
2792 summary: Reply to a thread of a video
2798 - $ref: '#/components/parameters/idOrUUID'
2799 - $ref: '#/components/parameters/commentId'
2802 description: successful operation
2806 $ref: '#/components/schemas/CommentThreadPostResponse'
2808 description: thread or video does not exist
2817 description: 'Text comment'
2822 summary: Delete a comment or a reply
2828 - $ref: '#/components/parameters/idOrUUID'
2829 - $ref: '#/components/parameters/commentId'
2832 description: successful operation
2834 description: cannot remove comment of another user
2836 description: comment or video does not exist
2838 description: comment is already deleted
2839 '/videos/{id}/rate':
2841 summary: Like/dislike a video
2847 - $ref: '#/components/parameters/idOrUUID'
2850 description: successful operation
2852 description: video does not exist
2857 summary: Search videos
2862 allowEmptyValue: false
2864 String to search. If the user can make a remote URI search, and the string is an URI then the
2865 PeerTube instance will fetch the remote object and add it to its database. Then,
2866 you can use the REST API to fetch the complete video information and interact with it.
2869 - $ref: '#/components/parameters/categoryOneOf'
2870 - $ref: '#/components/parameters/isLive'
2871 - $ref: '#/components/parameters/tagsOneOf'
2872 - $ref: '#/components/parameters/tagsAllOf'
2873 - $ref: '#/components/parameters/licenceOneOf'
2874 - $ref: '#/components/parameters/languageOneOf'
2875 - $ref: '#/components/parameters/nsfw'
2876 - $ref: '#/components/parameters/filter'
2877 - $ref: '#/components/parameters/skipCount'
2878 - $ref: '#/components/parameters/start'
2879 - $ref: '#/components/parameters/count'
2880 - $ref: '#/components/parameters/searchTarget'
2881 - $ref: '#/components/parameters/videosSearchSort'
2884 description: Get videos that are published after this date
2890 description: Get videos that are published before this date
2894 - name: originallyPublishedStartDate
2896 description: Get videos that are originally published after this date
2900 - name: originallyPublishedEndDate
2902 description: Get videos that are originally published before this date
2908 description: Get videos that have this minimum duration
2913 description: Get videos that have this maximum duration
2917 'searchTarget === search-index':
2918 $ref: '#/components/callbacks/searchIndex'
2921 description: successful operation
2925 $ref: '#/components/schemas/VideoListResponse'
2927 description: search index unavailable
2928 /search/video-channels:
2932 summary: Search channels
2938 String to search. If the user can make a remote URI search, and the string is an URI then the
2939 PeerTube instance will fetch the remote object and add it to its database. Then,
2940 you can use the REST API to fetch the complete channel information and interact with it.
2943 - $ref: '#/components/parameters/start'
2944 - $ref: '#/components/parameters/count'
2945 - $ref: '#/components/parameters/searchTarget'
2946 - $ref: '#/components/parameters/sort'
2948 'searchTarget === search-index':
2949 $ref: '#/components/callbacks/searchIndex'
2952 description: successful operation
2958 $ref: '#/components/schemas/VideoChannel'
2960 description: search index unavailable
2961 /blocklist/accounts:
2965 summary: List account blocks
2970 - $ref: '#/components/parameters/start'
2971 - $ref: '#/components/parameters/count'
2972 - $ref: '#/components/parameters/sort'
2975 description: successful operation
2979 summary: Block an account
2991 example: chocobozzz@example.org
2992 description: account to block, in the form `username@domain`
2997 description: successful operation
2999 description: self-blocking forbidden
3000 '/blocklist/accounts/{accountName}':
3004 summary: Unblock an account by its handle
3012 description: account to unblock, in the form `username@domain`
3017 description: successful operation
3019 description: account or account block does not exist
3024 summary: List server blocks
3029 - $ref: '#/components/parameters/start'
3030 - $ref: '#/components/parameters/count'
3031 - $ref: '#/components/parameters/sort'
3034 description: successful operation
3038 summary: Block a server
3051 description: server domain to block
3056 description: successful operation
3058 description: self-blocking forbidden
3059 '/blocklist/servers/{host}':
3063 summary: Unblock a server by its domain
3071 description: server domain to unblock
3077 description: successful operation
3079 description: account block does not exist
3083 - Instance Redundancy
3084 summary: Update a server redundancy policy
3092 description: server domain to mirror
3104 description: allow mirroring of the host's local videos
3109 description: successful operation
3111 description: server is not already known
3116 summary: List videos being mirrored
3124 description: direction of the mirror
3130 - $ref: '#/components/parameters/start'
3131 - $ref: '#/components/parameters/count'
3132 - $ref: '#/components/parameters/videoRedundanciesSort'
3135 description: successful operation
3141 $ref: '#/components/schemas/VideoRedundancy'
3145 summary: Mirror a video
3161 description: successful operation
3163 description: cannot mirror a local video
3165 description: video does not exist
3167 description: video is already mirrored
3168 /redundancy/videos/{redundancyId}:
3172 summary: Delete a mirror done on a video
3177 - name: redundancyId
3180 description: id of an existing redundancy on a video
3185 description: successful operation
3187 description: video redundancy not found
3188 '/feeds/video-comments.{format}':
3192 summary: List comments on videos
3194 - url: 'https://peertube2.cpy.re'
3195 description: Live Test Server (live data - latest nightly version)
3196 - url: 'https://peertube3.cpy.re'
3197 description: Live Test Server (live data - latest RC version)
3198 - url: 'https://peertube.cpy.re'
3199 description: Live Test Server (live data - stable version)
3204 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3217 description: 'limit listing to a specific video'
3222 description: 'limit listing to a specific account'
3227 description: 'limit listing to a specific account'
3230 - name: videoChannelId
3232 description: 'limit listing to a specific video channel'
3235 - name: videoChannelName
3237 description: 'limit listing to a specific video channel'
3242 description: successful operation
3247 default: 'max-age=900' # 15 min cache
3251 $ref: '#/components/schemas/VideoCommentsForXML'
3252 application/rss+xml:
3254 $ref: '#/components/schemas/VideoCommentsForXML'
3257 $ref: '#/components/schemas/VideoCommentsForXML'
3258 application/atom+xml:
3260 $ref: '#/components/schemas/VideoCommentsForXML'
3265 x-summary: field inconsistencies
3268 - videoId filter is mixed with a channel filter
3270 description: video, video channel or account not found
3272 description: accept header unsupported
3273 '/feeds/videos.{format}':
3277 summary: List videos
3279 - url: 'https://peertube2.cpy.re'
3280 description: Live Test Server (live data - latest nightly version)
3281 - url: 'https://peertube3.cpy.re'
3282 description: Live Test Server (live data - latest RC version)
3283 - url: 'https://peertube.cpy.re'
3284 description: Live Test Server (live data - stable version)
3289 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3302 description: 'limit listing to a specific account'
3307 description: 'limit listing to a specific account'
3310 - name: videoChannelId
3312 description: 'limit listing to a specific video channel'
3315 - name: videoChannelName
3317 description: 'limit listing to a specific video channel'
3320 - $ref: '#/components/parameters/sort'
3321 - $ref: '#/components/parameters/nsfw'
3322 - $ref: '#/components/parameters/filter'
3325 description: successful operation
3330 default: 'max-age=900' # 15 min cache
3334 $ref: '#/components/schemas/VideosForXML'
3337 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3338 application/rss+xml:
3340 $ref: '#/components/schemas/VideosForXML'
3343 $ref: '#/components/schemas/VideosForXML'
3344 application/atom+xml:
3346 $ref: '#/components/schemas/VideosForXML'
3351 description: video channel or account not found
3353 description: accept header unsupported
3358 summary: List plugins
3371 - $ref: '#/components/parameters/start'
3372 - $ref: '#/components/parameters/count'
3373 - $ref: '#/components/parameters/sort'
3376 description: successful operation
3380 $ref: '#/components/schemas/PluginResponse'
3385 summary: List available plugins
3398 - name: currentPeerTubeEngine
3402 - $ref: '#/components/parameters/start'
3403 - $ref: '#/components/parameters/count'
3404 - $ref: '#/components/parameters/sort'
3407 description: successful operation
3411 $ref: '#/components/schemas/PluginResponse'
3413 description: plugin index unavailable
3418 summary: Install a plugin
3431 example: peertube-plugin-auth-ldap
3434 additionalProperties: false
3441 additionalProperties: false
3444 description: successful operation
3446 description: should have either `npmName` or `path` set
3451 summary: Update a plugin
3464 example: peertube-plugin-auth-ldap
3467 additionalProperties: false
3474 additionalProperties: false
3477 description: successful operation
3479 description: should have either `npmName` or `path` set
3481 description: existing plugin not found
3486 summary: Uninstall a plugin
3498 description: name of the plugin/theme in its package.json
3499 example: peertube-plugin-auth-ldap
3504 description: successful operation
3506 description: existing plugin not found
3511 summary: Get a plugin
3516 - $ref: '#/components/parameters/npmName'
3519 description: successful operation
3523 $ref: '#/components/schemas/Plugin'
3525 description: plugin not found
3526 /plugins/{npmName}/settings:
3530 summary: Set a plugin's settings
3535 - $ref: '#/components/parameters/npmName'
3544 additionalProperties: true
3547 description: successful operation
3549 description: plugin not found
3550 /plugins/{npmName}/public-settings:
3554 summary: Get a plugin's public settings
3556 - $ref: '#/components/parameters/npmName'
3559 description: successful operation
3564 additionalProperties: true
3566 description: plugin not found
3567 /plugins/{npmName}/registered-settings:
3571 summary: Get a plugin's registered settings
3576 - $ref: '#/components/parameters/npmName'
3579 description: successful operation
3584 additionalProperties: true
3586 description: plugin not found
3588 - url: 'https://peertube2.cpy.re/api/v1'
3589 description: Live Test Server (live data - latest nightly version)
3590 - url: 'https://peertube3.cpy.re/api/v1'
3591 description: Live Test Server (live data - latest RC version)
3592 - url: 'https://peertube.cpy.re/api/v1'
3593 description: Live Test Server (live data - stable version)
3600 description: Offset used to paginate results
3608 description: "Number of items to return"
3618 description: Sort column
3626 description: Plain text search, applied to various parts of the model depending on endpoint
3634 If the administrator enabled search index support, you can override the default search target.
3637 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
3638 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
3639 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
3640 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
3641 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
3642 * 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
3643 the data from the origin instance API
3653 description: Sort videos by criteria
3669 description: Sort videos by criteria
3684 description: Sort comments by criteria
3694 description: Sort blacklists by criteria
3710 description: Plain text search that will match with user usernames or emails
3717 description: Filter results down to (un)banned users
3724 description: Sort users by criteria
3735 description: Sort abuses by criteria
3742 videoRedundanciesSort:
3746 description: Sort abuses by criteria
3755 description: The username or handle of the account
3758 example: chocobozzz | chocobozzz@example.org
3763 description: The user id
3772 description: The object id or uuid
3778 - $ref: '#/components/schemas/UUIDv4'
3780 name: playlistElementId
3783 description: Playlist element id
3790 description: Abuse id
3794 name: abuseMessageId
3797 description: Abuse message id
3801 name: captionLanguage
3804 description: The caption language
3811 description: The video channel handle
3814 example: my_username | my_username@example.com
3816 name: subscriptionHandle
3819 description: The subscription handle
3822 example: my_username | my_username@example.com
3827 description: The thread id (root comment id)
3834 description: The comment id
3841 description: whether or not the video is a live
3848 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
3861 description: tag(s) of the video
3874 description: tag(s) of the video, where all should be present in the video
3887 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
3900 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
3913 description: if you don't need the `total` in the response
3924 description: whether to include nsfw videos, if any
3935 Special filters which might require special rights:
3936 * `local` - only videos local to the instance
3937 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
3938 * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
3948 description: list of uris to check if each is part of the user subscriptions
3958 description: name of the plugin/theme on npmjs.com or in its package.json
3961 example: peertube-plugin-auth-ldap
3966 description: job type
3970 - activitypub-follow
3971 - activitypub-http-broadcast
3972 - activitypub-http-fetcher
3973 - activitypub-http-unicast
3979 - activitypub-refresher
3985 Authenticating via OAuth requires the following steps:
3986 - Have an activated account
3987 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
3988 Bearer Token for that account at `/api/v1/users/token`
3989 - Make authenticated requests, putting *Authorization: Bearer <token\>*
3990 - Profit, depending on the role assigned to the account
3992 Note that the __access token is valid for 1 day__ and, and is given
3993 along with a __refresh token valid for 2 weeks__.
3997 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
4000 moderator: Moderator scope
4006 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4007 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4008 # the regex above limits the length;
4009 # however, some tools might require explicit settings:
4013 VideoConstantNumber-Category:
4017 description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
4020 VideoConstantNumber-Licence:
4024 description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
4027 VideoConstantString-Language:
4031 description: language id of the video (see [/videos/languages](#tag/Video/paths/~1videos~1languages/get))
4035 VideoPlaylistPrivacySet:
4041 description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
4042 VideoPlaylistPrivacyConstant:
4045 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4049 VideoPlaylistTypeSet:
4054 description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
4055 VideoPlaylistTypeConstant:
4058 $ref: '#/components/schemas/VideoPlaylistTypeSet'
4069 description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
4070 VideoPrivacyConstant:
4073 $ref: '#/components/schemas/VideoPrivacySet'
4090 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4097 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4108 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4118 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4122 $ref: '#/components/schemas/AbuseStateSet'
4125 AbusePredefinedReasons:
4138 example: [spamOrMisleading]
4140 VideoResolutionConstant:
4144 description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
4149 VideoScheduledUpdate:
4152 $ref: '#/components/schemas/VideoPrivacySet'
4156 description: When to update the video
4176 - $ref: '#/components/schemas/ActorImage'
4177 VideoChannelSummary:
4194 - $ref: '#/components/schemas/ActorImage'
4206 - $ref: '#/components/schemas/Video'
4212 $ref: '#/components/schemas/VideoResolutionConstant'
4215 description: 'Video file size in bytes'
4218 description: Direct URL of the torrent file
4222 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4226 description: Direct URL of the video
4230 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4237 VideoStreamingPlaylists:
4250 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4251 VideoStreamingPlaylists-HLS:
4262 Video files associated to this playlist.
4264 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4266 $ref: '#/components/schemas/VideoFile'
4280 $ref: '#/components/schemas/UUIDv4'
4291 $ref: '#/components/schemas/UUIDv4'
4297 example: 2017-10-01T10:52:46.396Z
4298 description: time at which the video object was first drafted
4302 example: 2018-10-01T10:52:46.396Z
4303 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4307 example: 2021-05-04T08:01:01.502Z
4308 description: last time the video's metadata was modified
4309 originallyPublishedAt:
4312 example: 2010-10-01T10:52:46.396Z
4313 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4315 $ref: '#/components/schemas/VideoConstantNumber-Category'
4317 $ref: '#/components/schemas/VideoConstantNumber-Licence'
4319 $ref: '#/components/schemas/VideoConstantString-Language'
4321 $ref: '#/components/schemas/VideoPrivacyConstant'
4325 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4326 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4330 truncated description of the video, written in Markdown.
4331 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4335 description: duration of the video in seconds
4340 example: What is PeerTube?
4345 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4348 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4351 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4367 $ref: '#/components/schemas/VideoStateConstant'
4371 - $ref: '#/components/schemas/VideoScheduledUpdate'
4379 $ref: '#/components/schemas/AccountSummary'
4381 $ref: '#/components/schemas/VideoChannelSummary'
4390 - $ref: '#/components/schemas/Video'
4395 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4396 description: path at which to get the full description of maximum `10000` characters
4399 description: A text tell the audience how to support the video creator
4400 example: Please support my work on <insert crowdfunding plateform>! <3
4404 $ref: '#/components/schemas/VideoChannel'
4406 $ref: '#/components/schemas/Account'
4408 example: [flowers, gardening]
4428 $ref: '#/components/schemas/VideoFile'
4430 WebTorrent/raw video files. If WebTorrent is disabled on the server:
4432 - field will be empty
4433 - video files will be found in `streamingPlaylists[].files` field
4437 $ref: '#/components/schemas/VideoStreamingPlaylists'
4439 HLS playlists/manifest files. If HLS is disabled on the server:
4441 - field will be empty
4442 - video files will be found in `files` field
4443 FileRedundancyInformation:
4478 $ref: '#/components/schemas/UUIDv4'
4485 $ref: '#/components/schemas/FileRedundancyInformation'
4489 $ref: '#/components/schemas/FileRedundancyInformation'
4490 VideoImportStateConstant:
4498 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4510 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4514 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
4518 $ref: '#/components/schemas/VideoImportStateConstant'
4528 $ref: '#/components/schemas/Video'
4536 example: The video is a spam
4540 $ref: '#/components/schemas/AbusePredefinedReasons'
4542 $ref: '#/components/schemas/Account'
4544 $ref: '#/components/schemas/AbuseStateConstant'
4547 example: Decided to ban the server since it spams us regularly
4551 $ref: '#/components/schemas/VideoInfo'
4569 $ref: '#/components/schemas/AccountSummary'
4587 $ref: '#/components/schemas/UUIDv4'
4620 $ref: '#/components/schemas/UUIDv4'
4636 $ref: '#/components/schemas/UUIDv4'
4648 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
4650 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
4652 $ref: '#/components/schemas/AccountSummary'
4654 $ref: '#/components/schemas/VideoChannelSummary'
4678 totalRepliesFromVideoAuthor:
4683 $ref: '#/components/schemas/Account'
4684 VideoCommentThreadTree:
4687 $ref: '#/components/schemas/VideoComment'
4691 $ref: '#/components/schemas/VideoCommentThreadTree'
4695 $ref: '#/components/schemas/VideoConstantString-Language'
4750 $ref: '#/components/schemas/ActorImage'
4753 - $ref: '#/components/schemas/Actor'
4766 description: timestamp within the video, in seconds
4833 allowedForCurrentIP:
4835 requiresEmailVerification:
5039 requiresEmailVerification:
5064 allowAdditionalExtensions:
5134 $ref: '#/components/schemas/Actor'
5136 $ref: '#/components/schemas/Actor'
5139 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5152 PredefinedAbuseReasons:
5153 description: Reason categories that help triage reports
5184 - activitypub-http-unicast
5185 - activitypub-http-broadcast
5186 - activitypub-http-fetcher
5187 - activitypub-follow
5193 - activitypub-refresher
5197 additionalProperties: true
5200 additionalProperties: true
5224 VideoUploadResponse:
5233 $ref: '#/components/schemas/UUIDv4'
5234 CommentThreadResponse:
5243 $ref: '#/components/schemas/VideoComment'
5244 CommentThreadPostResponse:
5247 $ref: '#/components/schemas/VideoComment'
5257 $ref: '#/components/schemas/Video'
5265 description: The user username
5271 description: The user email
5274 description: Auth plugin to use to authenticate the user
5277 description: Theme enabled by this user
5280 description: Has the user confirmed their email address?
5282 $ref: '#/components/schemas/NSFWPolicy'
5285 description: Enable P2P in the player
5288 description: Automatically start playing the video on the watch page
5290 $ref: '#/components/schemas/UserRole'
5299 description: The user video quota
5302 description: The user daily video quota
5307 abusesAcceptedCount:
5313 noInstanceConfigWarningModal:
5324 $ref: '#/components/schemas/Account'
5328 $ref: '#/components/schemas/VideoChannel'
5333 description: The user username
5339 description: The user password. If the smtp server is configured, you can leave empty and an email will be sent
5345 description: The user email
5348 description: The user video quota
5351 description: The user daily video quota
5354 description: The user default channel username
5356 $ref: '#/components/schemas/UserRole'
5358 $ref: '#/components/schemas/UserAdminFlags'
5370 description: The user id
5374 description: The updated email of the user
5377 description: Set the email as verified
5380 description: The updated video quota of the user
5383 description: The updated daily video quota of the user
5387 description: The auth plugin to use to authenticate the user
5388 example: 'peertube-plugin-auth-saml2'
5390 $ref: '#/components/schemas/UserRole'
5392 $ref: '#/components/schemas/UserAdminFlags'
5400 description: Your new password
5406 description: Your new email
5409 description: Your new displayNSFW
5416 description: Your new autoPlayVideo
5426 description: Id of the video
5429 description: Rating of the video
5436 $ref: '#/components/schemas/Video'
5439 description: 'Rating of the video'
5447 description: The username of the user
5450 pattern: '/^[a-z0-9._]{1,50}$/'
5454 description: The password of the user
5460 description: The email of the user
5463 description: The user display name
5471 description: The username for the default channel
5472 pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
5475 description: The display name for the default channel
5495 description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
5496 example: Please support my work on <insert crowdfunding plateform>! <3
5501 - $ref: '#/components/schemas/VideoChannelCommon'
5512 - $ref: '#/components/schemas/VideoChannelCommon'
5514 bulkVideosSupportUpdate:
5516 description: 'Update the support field for all videos of this channel'
5521 name: 'media:peerLink'
5530 - application/x-bittorrent
5536 name: 'media:content'
5567 VideoCommentsForXML:
5602 description: video watch page URL
5605 description: video canonical URL
5609 description: video publication date
5612 description: video description
5615 description: video description
5618 description: publisher user name
5621 description: video category (MRSS)
5624 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
5639 description: video embed path, relative to the canonical URL domain (MRSS)
5648 description: video watch path, relative to the canonical URL domain (MRSS)
5669 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
5670 'media:description':
5677 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
5680 description: main streamable file for the video
5690 - application/x-bittorrent
5699 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)
5702 - $ref: '#/components/schemas/MRSSPeerLink'
5703 - $ref: '#/components/schemas/MRSSGroupContent'
5704 NotificationSettingValue:
5725 Notification type, following the `UserNotificationType` enum:
5727 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
5729 - `2` NEW_COMMENT_ON_MY_VIDEO
5731 - `3` NEW_ABUSE_FOR_MODERATORS
5733 - `4` BLACKLIST_ON_MY_VIDEO
5735 - `5` UNBLACKLIST_ON_MY_VIDEO
5737 - `6` MY_VIDEO_PUBLISHED
5739 - `7` MY_VIDEO_IMPORT_SUCCESS
5741 - `8` MY_VIDEO_IMPORT_ERROR
5743 - `9` NEW_USER_REGISTRATION
5747 - `11` COMMENT_MENTION
5749 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
5751 - `13` NEW_INSTANCE_FOLLOWER
5753 - `14` AUTO_INSTANCE_FOLLOWING
5759 - $ref: '#/components/schemas/VideoInfo'
5763 $ref: '#/components/schemas/ActorInfo'
5772 $ref: '#/components/schemas/VideoInfo'
5793 $ref: '#/components/schemas/VideoInfo'
5795 $ref: '#/components/schemas/ActorInfo'
5804 - $ref: '#/components/schemas/VideoInfo'
5813 - $ref: '#/components/schemas/VideoInfo'
5817 - $ref: '#/components/schemas/ActorInfo'
5825 $ref: '#/components/schemas/ActorInfo'
5853 NotificationListResponse:
5862 $ref: '#/components/schemas/Notification'
5867 example: peertube-plugin-auth-ldap
5895 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
5898 additionalProperties: true
5914 $ref: '#/components/schemas/Plugin'
5921 description: User can stream multiple times in a permanent live
5930 description: RTMP stream key to use to stream into this live video
5934 description: User can stream multiple times in a permanent live
5941 'https://search.example.org/api/v1/search/videos':
5943 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
5946 description: successful operation
5950 $ref: '#/components/schemas/VideoListResponse'