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
16 The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
17 resource URLs. It returns HTTP response codes to indicate errors. It also
18 accepts and returns JSON in the HTTP body. You can use your favorite
19 HTTP/REST library for your programming language to use PeerTube. No official
20 SDK is currently provided, but the spec API is fully compatible with
21 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
22 which generates a client SDK in the language of your choice.
25 When you sign up for an account, you are given the possibility to generate
26 sessions, and authenticate using this session token. One session token can
27 currently be used at a time.
30 The API uses standard HTTP status codes to indicate the success or failure
31 of the API call. The body of the response will be JSON in the following
36 "code": "unauthorized_request", // example inner error code
37 "error": "Token is invalid." // example exposed error message
41 url: https://docs.joinpeertube.org/#/api-rest-reference.html
45 Using some features of PeerTube require authentication, for which Accounts
46 provide different levels of permission as well as associated user
47 information. Accounts also encompass remote accounts discovered across the federation.
50 Each server exposes public information regarding supported videos and
54 Feeds of videos and feeds of comments allow to see updates and get them in
55 an aggregator or script of your choice.
58 Jobs are long-running tasks enqueued and processed by the instance
59 itself. No additional worker registration is currently available.
60 - name: Server Following
62 Managing servers which the instance interacts with is crucial to the
63 concept of federation in PeerTube and external video indexation. The PeerTube
64 server then deals with inter-server ActivityPub operations and propagates
65 information across its social graph by posting activities to actors' inbox
69 Video abuses deal with reports of local or remote videos alike.
72 Operations dealing with listing, uploading, fetching or modifying videos.
75 The search helps to find _videos_ from within the instance and beyond.
76 Videos from other instances federated by the instance (that is, instances
77 followed by the instance) can be found via keywords and other criteria of
81 Operations dealing with comments to a video. Comments are organized in
85 Operations dealing with creation, modification and video listing of a
87 - name: Video Blacklist
89 Operations dealing with blacklisting videos (removing them from view and
90 preventing interactions).
111 - name: Instance Configuration
115 - name: Notifications
129 summary: Get the account by name
131 - $ref: '#/components/parameters/name'
132 - $ref: '#/components/parameters/start'
133 - $ref: '#/components/parameters/count'
134 - $ref: '#/components/parameters/sort'
137 description: successful operation
141 $ref: '#/components/schemas/Account'
142 '/accounts/{name}/videos':
147 summary: 'Get videos for an account, provided the name of that account'
149 - $ref: '#/components/parameters/name'
152 description: successful operation
156 $ref: '#/components/schemas/VideoListResponse'
160 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
161 .then(function(response) {
162 return response.json()
163 }).then(function(data) {
169 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
175 url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
177 http = Net::HTTP.new(url.host, url.port)
179 http.verify_mode = OpenSSL::SSL::VERIFY_NONE
181 request = Net::HTTP::Post.new(url)
182 request["content-type"] = 'application/json'
183 response = http.request(request)
184 puts response.read_body
189 conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
192 'content-type': "application/json"
195 conn.request("POST", "/accounts/{name}/videos", None, headers)
197 res = conn.getresponse()
200 print(data.decode("utf-8"))
205 summary: Get all accounts
208 description: successful operation
214 $ref: '#/components/schemas/Account'
219 summary: Get the public configuration of the server
222 description: successful operation
226 $ref: '#/components/schemas/ServerConfig'
229 summary: Get the instance about page content
234 description: successful operation
237 summary: Get the runtime configuration of the server
245 description: successful operation
247 summary: Set the runtime configuration of the server
255 description: successful operation
257 summary: Delete the runtime configuration of the server
265 description: successful operation
266 '/feeds/videos.{format}':
269 Get the feed of videos for the server, with optional filter by account
278 The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
279 json to JSON FEED 1.0
291 The id of the local account to filter to (beware, users IDs and not
292 actors IDs which will return empty feeds
298 description: The name of the local account to filter to
303 description: successful operation
306 summary: Get list of jobs
316 description: The state of the job
325 - $ref: '#/components/parameters/start'
326 - $ref: '#/components/parameters/count'
327 - $ref: '#/components/parameters/sort'
330 description: successful operation
336 $ref: '#/components/schemas/Job'
337 '/server/following/{host}':
344 summary: Unfollow a server by hostname
349 description: 'The host to unfollow '
354 description: successful operation
359 summary: Get followers of the server
361 - $ref: '#/components/parameters/start'
362 - $ref: '#/components/parameters/count'
363 - $ref: '#/components/parameters/sort'
366 description: successful operation
372 $ref: '#/components/schemas/Follow'
377 summary: Get servers followed by the server
379 - $ref: '#/components/parameters/start'
380 - $ref: '#/components/parameters/count'
381 - $ref: '#/components/parameters/sort'
384 description: successful operation
390 $ref: '#/components/schemas/Follow'
397 summary: Follow a server
400 $ref: '#/paths/~1users~1me/put/responses/204'
405 $ref: '#/components/schemas/Follow'
408 summary: Creates user
416 description: successful operation
420 $ref: '#/components/schemas/AddUserResponse'
425 $ref: '#/components/schemas/AddUser'
426 description: User to create
429 summary: Get a list of users
435 - $ref: '#/components/parameters/start'
436 - $ref: '#/components/parameters/count'
437 - $ref: '#/components/parameters/usersSort'
440 description: successful operation
446 $ref: '#/components/schemas/User'
449 summary: Delete a user by its id
456 - $ref: '#/components/parameters/id'
459 $ref: '#/paths/~1users~1me/put/responses/204'
461 summary: Get user by its id
467 - $ref: '#/components/parameters/id'
470 description: successful operation
474 $ref: '#/components/schemas/User'
476 summary: Update user profile by its id
482 - $ref: '#/components/parameters/id'
485 $ref: '#/paths/~1users~1me/put/responses/204'
490 $ref: '#/components/schemas/UpdateUser'
494 summary: Get current user information
502 description: successful operation
508 $ref: '#/components/schemas/User'
510 summary: Update current user information
518 description: Successful operation
523 $ref: '#/components/schemas/UpdateMe'
525 /users/me/video-quota-used:
527 summary: Get current user used quota
535 description: successful operation
540 '/users/me/videos/{videoId}/rating':
542 summary: 'Get rating of video by its id, among those of the current user'
551 description: 'The video id '
556 description: successful operation
560 $ref: '#/components/schemas/GetMeVideoRating'
563 summary: Get videos of the current user
570 - $ref: '#/components/parameters/start'
571 - $ref: '#/components/parameters/count'
572 - $ref: '#/components/parameters/sort'
575 description: successful operation
579 $ref: '#/components/schemas/VideoListResponse'
580 /users/me/subscriptions:
582 summary: Get subscriptions of the current user
589 - $ref: '#/components/parameters/start'
590 - $ref: '#/components/parameters/count'
591 - $ref: '#/components/parameters/sort'
594 description: successful operation
596 summary: Add subscription to the current user
604 description: successful operation
605 /users/me/subscriptions/exist:
607 summary: Get if subscriptions exist for the current user
614 - $ref: '#/components/parameters/subscriptionsUris'
617 description: successful operation
622 /users/me/subscriptions/videos:
624 summary: Get videos of subscriptions of the current user
631 - $ref: '#/components/parameters/start'
632 - $ref: '#/components/parameters/count'
633 - $ref: '#/components/parameters/sort'
636 description: successful operation
640 $ref: '#/components/schemas/VideoListResponse'
641 '/users/me/subscriptions/{uri}':
643 summary: Get subscription of the current user for a given uri
651 description: successful operation
655 $ref: '#/components/schemas/VideoChannel'
657 summary: Delete subscription of the current user for a given uri
665 description: successful operation
668 summary: Register a user
673 $ref: '#/paths/~1users~1me/put/responses/204'
678 $ref: '#/components/schemas/RegisterUser'
680 /users/me/avatar/pick:
682 summary: Update current user avatar
689 description: successful operation
693 $ref: '#/components/schemas/Avatar'
701 description: The file to upload.
706 # only accept png/jpeg
707 contentType: image/png, image/jpeg
710 summary: Get list of videos
714 - $ref: '#/components/parameters/categoryOneOf'
715 - $ref: '#/components/parameters/tagsOneOf'
716 - $ref: '#/components/parameters/tagsAllOf'
717 - $ref: '#/components/parameters/licenceOneOf'
718 - $ref: '#/components/parameters/languageOneOf'
719 - $ref: '#/components/parameters/nsfw'
720 - $ref: '#/components/parameters/filter'
721 - $ref: '#/components/parameters/start'
722 - $ref: '#/components/parameters/count'
723 - $ref: '#/components/parameters/videosSort'
726 description: successful operation
730 $ref: '#/components/schemas/VideoListResponse'
733 summary: Get list of video licences known by the server
738 description: successful operation
747 summary: Get list of video licences known by the server
752 description: successful operation
761 summary: Get list of languages known by the server
766 description: successful operation
775 summary: Get list of privacy policies supported by the server
780 description: successful operation
789 summary: Update metadata for a video by its id
795 - $ref: '#/components/parameters/id2'
798 description: successful operation
802 $ref: '#/components/schemas/Video'
810 description: Video thumbnail file
813 description: Video preview file
816 description: Video category
819 description: Video licence
822 description: Video language
825 description: Video description
828 description: Whether or not we wait transcoding before publish the video
831 description: Text describing how to support the video uploader
834 description: Whether or not this video contains sensitive content
837 description: Video name
840 description: Video tags (maximum 5 tags each between 2 and 30 characters)
845 description: Enable or disable comments for this video
847 scheduleUpdate: &ref_0
855 description: Video privacy target
859 description: When to update the video
863 summary: Get a video by its id
867 - $ref: '#/components/parameters/id2'
870 description: successful operation
874 $ref: '#/components/schemas/Video'
876 summary: Delete a video by its id
882 - $ref: '#/components/parameters/id2'
885 $ref: '#/paths/~1users~1me/put/responses/204'
886 '/videos/{id}/description':
888 summary: Get a video description by its id
892 - $ref: '#/components/parameters/id2'
895 description: successful operation
900 '/videos/{id}/views':
902 summary: Add a view to the video by its id
906 - $ref: '#/components/parameters/id2'
909 $ref: '#/paths/~1users~1me/put/responses/204'
910 '/videos/{id}/watching':
912 summary: Set watching progress of a video by its id for a user
918 - $ref: '#/components/parameters/id2'
923 $ref: '#/components/schemas/UserWatchingVideo'
927 $ref: '#/paths/~1users~1me/put/responses/204'
930 summary: Get list of video ownership changes requests
936 - $ref: '#/components/parameters/id2'
939 description: successful operation
940 '/videos/ownership/{id}/accept':
942 summary: Refuse ownership change request for video by its id
948 - $ref: '#/components/parameters/id2'
951 $ref: '#/paths/~1users~1me/put/responses/204'
952 '/videos/ownership/{id}/refuse':
954 summary: Accept ownership change request for video by its id
960 - $ref: '#/components/parameters/id2'
963 $ref: '#/paths/~1users~1me/put/responses/204'
964 '/videos/{id}/give-ownership':
966 summary: Request change of ownership for a video you own, by its id
972 - $ref: '#/components/parameters/id2'
976 application/x-www-form-urlencoded:
986 $ref: '#/paths/~1users~1me/put/responses/204'
988 description: 'Changing video ownership to a remote account is not supported yet'
991 summary: Upload a video file with its metadata
998 description: successful operation
1002 $ref: '#/components/schemas/VideoUploadResponse'
1005 multipart/form-data:
1010 description: Video file
1014 description: Channel id that will contain this video
1017 description: Video thumbnail file
1020 description: Video preview file
1023 $ref: '#/components/schemas/VideoPrivacySet'
1025 description: Video category
1028 description: Video licence
1031 description: Video language
1034 description: Video description
1037 description: Whether or not we wait transcoding before publish the video
1040 description: Text describing how to support the video uploader
1043 description: Whether or not this video contains sensitive content
1046 description: Video name
1049 description: Video tags
1054 description: Enable or disable comments for this video
1056 scheduleUpdate: *ref_0
1064 ## DEPENDENCIES: httpie, jq
1065 # pip install httpie
1066 USERNAME="<your_username>"
1067 PASSWORD="<your_password>"
1068 FILE_PATH="<your_file_path>"
1069 CHANNEL_ID="<your_channel_id>"
1072 API_PATH="https://peertube2.cpy.re/api/v1"
1074 client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1075 client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1076 token=$(http -b --form POST "$API_PATH/users/token" \
1077 client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
1078 username=$USERNAME \
1079 password=$PASSWORD \
1080 | jq -r ".access_token")
1082 http -b --form POST "$API_PATH/videos/upload" \
1083 videofile@$FILE_PATH \
1084 channelId=$CHANNEL_ID \
1086 "Authorization:Bearer $token"
1089 summary: Import a torrent or magnetURI or HTTP ressource (if enabled by the instance administrator)
1096 description: successful operation
1100 $ref: '#/components/schemas/VideoUploadResponse'
1103 multipart/form-data:
1108 description: Torrent File
1112 description: HTTP target URL
1115 description: Magnet URI
1118 description: Channel id that will contain this video
1121 description: Video thumbnail file
1124 description: Video preview file
1127 $ref: '#/components/schemas/VideoPrivacySet'
1129 description: Video category
1132 description: Video licence
1135 description: Video language
1138 description: Video description
1141 description: Whether or not we wait transcoding before publish the video
1144 description: Text describing how to support the video uploader
1147 description: Whether or not this video contains sensitive content
1150 description: Video name
1153 description: Video tags
1158 description: Enable or disable comments for this video
1160 scheduleUpdate: *ref_0
1166 summary: Get list of reported video abuses
1172 - $ref: '#/components/parameters/start'
1173 - $ref: '#/components/parameters/count'
1174 - $ref: '#/components/parameters/abusesSort'
1177 description: successful operation
1183 $ref: '#/components/schemas/VideoAbuse'
1184 '/videos/{id}/abuse':
1186 summary: 'Report an abuse, on a video by its id'
1192 - $ref: '#/components/parameters/id2'
1195 $ref: '#/paths/~1users~1me/put/responses/204'
1196 '/videos/{id}/blacklist':
1198 summary: Put on blacklist a video by its id
1206 - $ref: '#/components/parameters/id2'
1209 $ref: '#/paths/~1users~1me/put/responses/204'
1211 summary: Delete an entry of the blacklist of a video by its id
1219 - $ref: '#/components/parameters/id2'
1222 $ref: '#/paths/~1users~1me/put/responses/204'
1225 summary: Get list of videos on blacklist
1233 - $ref: '#/components/parameters/start'
1234 - $ref: '#/components/parameters/count'
1235 - $ref: '#/components/parameters/blacklistsSort'
1238 description: successful operation
1244 $ref: '#/components/schemas/VideoBlacklist'
1245 /videos/{id}/captions:
1247 summary: Get list of video's captions
1251 - $ref: '#/components/parameters/id2'
1254 description: successful operation
1265 $ref: '#/components/schemas/VideoCaption'
1266 /videos/{id}/captions/{captionLanguage}:
1268 summary: Add or replace a video caption
1272 - $ref: '#/components/parameters/id2'
1273 - $ref: '#/components/parameters/captionLanguage'
1276 multipart/form-data:
1281 description: The file to upload.
1286 $ref: '#/paths/~1users~1me/put/responses/204'
1288 summary: Delete a video caption
1292 - $ref: '#/components/parameters/id2'
1293 - $ref: '#/components/parameters/captionLanguage'
1296 $ref: '#/paths/~1users~1me/put/responses/204'
1299 summary: Get list of video channels
1303 - $ref: '#/components/parameters/start'
1304 - $ref: '#/components/parameters/count'
1305 - $ref: '#/components/parameters/sort'
1308 description: successful operation
1314 $ref: '#/components/schemas/VideoChannel'
1316 summary: Creates a video channel for the current user
1323 $ref: '#/paths/~1users~1me/put/responses/204'
1328 $ref: '#/components/schemas/VideoChannelCreate'
1329 '/video-channels/{channelHandle}':
1331 summary: Get a video channel by its id
1335 - $ref: '#/components/parameters/channelHandle'
1338 description: successful operation
1342 $ref: '#/components/schemas/VideoChannel'
1344 summary: Update a video channel by its id
1350 - $ref: '#/components/parameters/channelHandle'
1353 $ref: '#/paths/~1users~1me/put/responses/204'
1358 $ref: '#/components/schemas/VideoChannelUpdate'
1360 summary: Delete a video channel by its id
1366 - $ref: '#/components/parameters/channelHandle'
1369 $ref: '#/paths/~1users~1me/put/responses/204'
1370 '/video-channels/{channelHandle}/videos':
1372 summary: Get videos of a video channel by its id
1377 - $ref: '#/components/parameters/channelHandle'
1380 description: successful operation
1384 $ref: '#/components/schemas/VideoListResponse'
1385 '/accounts/{name}/video-channels':
1387 summary: Get video channels of an account by its name
1391 - $ref: '#/components/parameters/name'
1394 description: successful operation
1400 $ref: '#/components/schemas/VideoChannel'
1401 '/accounts/{name}/ratings':
1403 summary: Get ratings of an account by its name
1409 - $ref: '#/components/parameters/start'
1410 - $ref: '#/components/parameters/count'
1411 - $ref: '#/components/parameters/sort'
1415 description: Optionaly filter which ratings to retrieve
1423 description: successful operation
1429 $ref: '#/components/schemas/VideoRating'
1430 '/videos/{id}/comment-threads':
1432 summary: Get the comment threads of a video by its id
1436 - $ref: '#/components/parameters/id2'
1437 - $ref: '#/components/parameters/start'
1438 - $ref: '#/components/parameters/count'
1439 - $ref: '#/components/parameters/sort'
1442 description: successful operation
1446 $ref: '#/components/schemas/CommentThreadResponse'
1448 summary: 'Creates a comment thread, on a video by its id'
1454 - $ref: '#/components/parameters/id2'
1457 description: successful operation
1461 $ref: '#/components/schemas/CommentThreadPostResponse'
1462 '/videos/{id}/comment-threads/{threadId}':
1464 summary: 'Get the comment thread by its id, of a video by its id'
1468 - $ref: '#/components/parameters/id2'
1472 description: The thread id (root comment id)
1477 description: successful operation
1481 $ref: '#/components/schemas/VideoCommentThreadTree'
1482 '/videos/{id}/comments/{commentId}':
1484 summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1490 - $ref: '#/components/parameters/id2'
1491 - $ref: '#/components/parameters/commentId'
1494 description: successful operation
1498 $ref: '#/components/schemas/CommentThreadPostResponse'
1500 summary: 'Delete a comment in a comment thread by its id, of a video by its id'
1506 - $ref: '#/components/parameters/id2'
1507 - $ref: '#/components/parameters/commentId'
1510 $ref: '#/paths/~1users~1me/put/responses/204'
1511 '/videos/{id}/rate':
1513 summary: Vote for a video by its id
1519 - $ref: '#/components/parameters/id2'
1522 $ref: '#/paths/~1users~1me/put/responses/204'
1527 summary: Get the videos corresponding to a given query
1529 - $ref: '#/components/parameters/start'
1530 - $ref: '#/components/parameters/count'
1531 - $ref: '#/components/parameters/videosSearchSort'
1535 description: String to search
1540 description: successful operation
1544 $ref: '#/components/schemas/VideoListResponse'
1546 - url: 'https://peertube.cpy.re/api/v1'
1547 description: Live Test Server (live data - stable version)
1548 - url: 'https://peertube2.cpy.re/api/v1'
1549 description: Live Test Server (live data - bleeding edge version)
1550 - url: 'https://peertube3.cpy.re/api/v1'
1551 description: Live Test Server (live data - bleeding edge version)
1565 description: Number of items
1572 description: Sort column (-createdAt for example)
1579 description: Sort videos by criteria
1594 description: Sort videos by criteria
1609 description: Sort blacklists by criteria
1625 description: Sort users by criteria
1636 description: Sort abuses by criteria
1648 The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1656 description: The user id
1663 description: The video id or uuid
1667 name: captionLanguage
1670 description: The caption language
1677 description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
1684 description: The comment id
1691 description: category id of the video
1704 description: tag(s) of the video
1717 description: tag(s) of the video, where all should be present in the video
1730 description: language id of the video
1743 description: licence id of the video
1756 description: whether to include nsfw videos, if any
1767 Special filters (local for instance) which might require special rights:
1768 * `local` - only videos local to the instance
1769 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
1779 description: list of uris to check if each is part of the user subscriptions
1787 In the header: *Authorization: Bearer <token\>*
1790 Authenticating via OAuth requires the following steps:
1793 - Have an account with sufficient authorization levels
1795 - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
1798 - Make Authenticated Requests
1802 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1805 moderator: Moderator scope
1808 VideoConstantNumber:
1814 VideoConstantString:
1826 description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
1827 VideoPrivacyConstant:
1850 $ref: '#/components/schemas/VideoConstantNumber'
1852 $ref: '#/components/schemas/VideoConstantNumber'
1854 $ref: '#/components/schemas/VideoConstantString'
1856 $ref: '#/components/schemas/VideoPrivacyConstant'
1891 $ref: '#/components/schemas/Avatar'
1899 $ref: '#/components/schemas/Account'
1975 $ref: '#/components/schemas/Account'
1976 VideoCommentThreadTree:
1979 $ref: '#/components/schemas/VideoComment'
1983 $ref: '#/components/schemas/VideoCommentThreadTree'
1987 $ref: '#/components/schemas/VideoConstantString'
2019 $ref: '#/components/schemas/Avatar'
2022 - $ref: '#/components/schemas/Actor'
2044 description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2058 $ref: '#/components/schemas/Account'
2062 $ref: '#/components/schemas/VideoChannel'
2111 $ref: '#/components/schemas/Actor'
2113 $ref: '#/components/schemas/Actor'
2155 VideoUploadResponse:
2164 CommentThreadResponse:
2171 $ref: '#/components/schemas/VideoComment'
2172 CommentThreadPostResponse:
2175 $ref: '#/components/schemas/VideoComment'
2183 $ref: '#/components/schemas/Video'
2188 description: 'The user username '
2191 description: 'The user password '
2194 description: 'The user email '
2197 description: 'The user videoQuota '
2200 description: 'The user daily video quota '
2207 description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2219 description: 'The user id '
2222 description: 'The updated email of the user '
2225 description: 'The updated videoQuota of the user '
2228 description: 'The updated daily video quota of the user '
2235 description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2246 description: 'Your new password '
2249 description: 'Your new email '
2252 description: 'Your new displayNSFW '
2255 description: 'Your new autoPlayVideo '
2265 description: 'Id of the video '
2268 description: 'Rating of the video '
2275 $ref: '#/components/schemas/Video'
2278 description: 'Rating of the video'
2286 description: 'The username of the user '
2289 description: 'The password of the user '
2292 description: 'The email of the user '
2318 bulkVideosSupportUpdate:
2320 description: 'Update all videos support field of this channel'