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.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).
110 - name: Instance Configuration
114 - name: Notifications
128 summary: Get the account by name
130 - $ref: '#/components/parameters/name'
131 - $ref: '#/components/parameters/start'
132 - $ref: '#/components/parameters/count'
133 - $ref: '#/components/parameters/sort'
136 description: successful operation
140 $ref: '#/components/schemas/Account'
141 '/accounts/{name}/videos':
146 summary: 'Get videos for an account, provided the name of that account'
148 - $ref: '#/components/parameters/name'
151 description: successful operation
155 $ref: '#/components/schemas/Video'
159 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
160 .then(function(response) {
161 return response.json()
162 }).then(function(data) {
168 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
174 url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
176 http = Net::HTTP.new(url.host, url.port)
178 http.verify_mode = OpenSSL::SSL::VERIFY_NONE
180 request = Net::HTTP::Post.new(url)
181 request["content-type"] = 'application/json'
182 response = http.request(request)
183 puts response.read_body
188 conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
191 'content-type': "application/json"
194 conn.request("POST", "/accounts/{name}/videos", None, headers)
196 res = conn.getresponse()
199 print(data.decode("utf-8"))
204 summary: Get all accounts
207 description: successful operation
213 $ref: '#/components/schemas/Account'
218 summary: Get the public configuration of the server
221 description: successful operation
225 $ref: '#/components/schemas/ServerConfig'
228 summary: Get the instance about page content
233 description: successful operation
236 summary: Get the runtime configuration of the server
244 description: successful operation
246 summary: Set the runtime configuration of the server
254 description: successful operation
256 summary: Delete the runtime configuration of the server
264 description: successful operation
265 '/feeds/videos.{format}':
268 Get the feed of videos for the server, with optional filter by account
277 The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
278 json to JSON FEED 1.0
290 The id of the local account to filter to (beware, users IDs and not
291 actors IDs which will return empty feeds
297 description: The name of the local account to filter to
302 description: successful operation
305 summary: Get list of jobs
315 description: The state of the job
324 - $ref: '#/components/parameters/start'
325 - $ref: '#/components/parameters/count'
326 - $ref: '#/components/parameters/sort'
329 description: successful operation
335 $ref: '#/components/schemas/Job'
336 '/server/following/{host}':
343 summary: Unfollow a server by hostname
348 description: 'The host to unfollow '
353 description: successful operation
358 summary: Get followers of the server
360 - $ref: '#/components/parameters/start'
361 - $ref: '#/components/parameters/count'
362 - $ref: '#/components/parameters/sort'
365 description: successful operation
371 $ref: '#/components/schemas/Follow'
376 summary: Get servers followed by the server
378 - $ref: '#/components/parameters/start'
379 - $ref: '#/components/parameters/count'
380 - $ref: '#/components/parameters/sort'
383 description: successful operation
389 $ref: '#/components/schemas/Follow'
396 summary: Follow a server
399 $ref: '#/paths/~1users~1me/put/responses/204'
404 $ref: '#/components/schemas/Follow'
407 summary: Creates user
415 description: successful operation
419 $ref: '#/components/schemas/AddUserResponse'
424 $ref: '#/components/schemas/AddUser'
425 description: User to create
428 summary: Get a list of users
434 - $ref: '#/components/parameters/start'
435 - $ref: '#/components/parameters/count'
436 - $ref: '#/components/parameters/usersSort'
439 description: successful operation
445 $ref: '#/components/schemas/User'
448 summary: Delete a user by its id
455 - $ref: '#/components/parameters/id'
458 $ref: '#/paths/~1users~1me/put/responses/204'
460 summary: Get user by its id
466 - $ref: '#/components/parameters/id'
469 description: successful operation
473 $ref: '#/components/schemas/User'
475 summary: Update user profile by its id
481 - $ref: '#/components/parameters/id'
484 $ref: '#/paths/~1users~1me/put/responses/204'
489 $ref: '#/components/schemas/UpdateUser'
493 summary: Get current user information
501 description: successful operation
507 $ref: '#/components/schemas/User'
509 summary: Update current user information
517 description: Successful operation
522 $ref: '#/components/schemas/UpdateMe'
524 /users/me/video-quota-used:
526 summary: Get current user used quota
534 description: successful operation
539 '/users/me/videos/{videoId}/rating':
541 summary: 'Get rating of video by its id, among those of the current user'
550 description: 'The video id '
555 description: successful operation
559 $ref: '#/components/schemas/GetMeVideoRating'
562 summary: Get videos of the current user
569 - $ref: '#/components/parameters/start'
570 - $ref: '#/components/parameters/count'
571 - $ref: '#/components/parameters/sort'
574 description: successful operation
580 $ref: '#/components/schemas/Video'
581 /users/me/subscriptions:
583 summary: Get subscriptions of the current user
590 - $ref: '#/components/parameters/start'
591 - $ref: '#/components/parameters/count'
592 - $ref: '#/components/parameters/sort'
595 description: successful operation
597 summary: Add subscription to the current user
605 description: successful operation
606 /users/me/subscriptions/exist:
608 summary: Get if subscriptions exist for the current user
615 - $ref: '#/components/parameters/subscriptionsUris'
618 description: successful operation
623 /users/me/subscriptions/videos:
625 summary: Get videos of subscriptions of the current user
632 - $ref: '#/components/parameters/start'
633 - $ref: '#/components/parameters/count'
634 - $ref: '#/components/parameters/sort'
637 description: successful operation
643 $ref: '#/components/schemas/Video'
644 '/users/me/subscriptions/{uri}':
646 summary: Get subscription of the current user for a given uri
654 description: successful operation
658 $ref: '#/components/schemas/VideoChannel'
660 summary: Delete subscription of the current user for a given uri
668 description: successful operation
671 summary: Register a user
676 $ref: '#/paths/~1users~1me/put/responses/204'
681 $ref: '#/components/schemas/RegisterUser'
683 /users/me/avatar/pick:
685 summary: Update current user avatar
692 description: successful operation
696 $ref: '#/components/schemas/Avatar'
704 description: The file to upload.
709 # only accept png/jpeg
710 contentType: image/png, image/jpeg
713 summary: Get list of videos
717 - $ref: '#/components/parameters/categoryOneOf'
718 - $ref: '#/components/parameters/tagsOneOf'
719 - $ref: '#/components/parameters/tagsAllOf'
720 - $ref: '#/components/parameters/licenceOneOf'
721 - $ref: '#/components/parameters/languageOneOf'
722 - $ref: '#/components/parameters/nsfw'
723 - $ref: '#/components/parameters/filter'
724 - $ref: '#/components/parameters/start'
725 - $ref: '#/components/parameters/count'
726 - $ref: '#/components/parameters/videosSort'
729 description: successful operation
735 $ref: '#/components/schemas/Video'
738 summary: Get list of video licences known by the server
743 description: successful operation
752 summary: Get list of video licences known by the server
757 description: successful operation
766 summary: Get list of languages known by the server
771 description: successful operation
780 summary: Get list of privacy policies supported by the server
785 description: successful operation
794 summary: Update metadata for a video by its id
800 - $ref: '#/components/parameters/id2'
803 description: successful operation
807 $ref: '#/components/schemas/Video'
815 description: Video thumbnail file
818 description: Video preview file
821 description: Video category
824 description: Video licence
827 description: Video language
830 description: Video description
833 description: Whether or not we wait transcoding before publish the video
836 description: Text describing how to support the video uploader
839 description: Whether or not this video contains sensitive content
842 description: Video name
845 description: Video tags (maximum 5 tags each between 2 and 30 characters)
850 description: Enable or disable comments for this video
852 scheduleUpdate: &ref_0
860 description: Video privacy target
864 description: When to update the video
868 summary: Get a video by its id
872 - $ref: '#/components/parameters/id2'
875 description: successful operation
879 $ref: '#/components/schemas/Video'
881 summary: Delete a video by its id
887 - $ref: '#/components/parameters/id2'
890 $ref: '#/paths/~1users~1me/put/responses/204'
891 '/videos/{id}/description':
893 summary: Get a video description by its id
897 - $ref: '#/components/parameters/id2'
900 description: successful operation
905 '/videos/{id}/views':
907 summary: Add a view to the video by its id
911 - $ref: '#/components/parameters/id2'
914 $ref: '#/paths/~1users~1me/put/responses/204'
915 '/videos/{id}/watching':
917 summary: Set watching progress of a video by its id for a user
923 - $ref: '#/components/parameters/id2'
928 $ref: '#/components/schemas/UserWatchingVideo'
932 $ref: '#/paths/~1users~1me/put/responses/204'
935 summary: Get list of video ownership changes requests
941 - $ref: '#/components/parameters/id2'
944 description: successful operation
945 '/videos/ownership/{id}/accept':
947 summary: Refuse ownership change request for video by its id
953 - $ref: '#/components/parameters/id2'
956 $ref: '#/paths/~1users~1me/put/responses/204'
957 '/videos/ownership/{id}/refuse':
959 summary: Accept ownership change request for video by its id
965 - $ref: '#/components/parameters/id2'
968 $ref: '#/paths/~1users~1me/put/responses/204'
969 '/videos/{id}/give-ownership':
971 summary: Request change of ownership for a video you own, by its id
977 - $ref: '#/components/parameters/id2'
981 application/x-www-form-urlencoded:
991 $ref: '#/paths/~1users~1me/put/responses/204'
993 description: 'Changing video ownership to a remote account is not supported yet'
996 summary: Upload a video file with its metadata
1003 description: successful operation
1007 $ref: '#/components/schemas/VideoUploadResponse'
1010 multipart/form-data:
1015 description: Video file
1019 description: Channel id that will contain this video
1022 description: Video thumbnail file
1025 description: Video preview file
1028 $ref: '#/components/schemas/VideoPrivacy'
1030 description: Video category
1033 description: Video licence
1036 description: Video language
1039 description: Video description
1042 description: Whether or not we wait transcoding before publish the video
1045 description: Text describing how to support the video uploader
1048 description: Whether or not this video contains sensitive content
1051 description: Video name
1054 description: Video tags
1059 description: Enable or disable comments for this video
1061 scheduleUpdate: *ref_0
1069 ## DEPENDENCIES: httpie, jq
1070 # pip install httpie
1071 USERNAME="<your_username>"
1072 PASSWORD="<your_password>"
1073 FILE_PATH="<your_file_path>"
1074 CHANNEL_ID="<your_channel_id>"
1077 API_PATH="https://peertube2.cpy.re/api/v1"
1079 client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1080 client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1081 token=$(http -b --form POST "$API_PATH/users/token" \
1082 client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
1083 username=$USERNAME \
1084 password=$PASSWORD \
1085 | jq -r ".access_token")
1087 http -b --form POST "$API_PATH/videos/upload" \
1088 videofile@$FILE_PATH \
1089 channelId=$CHANNEL_ID \
1091 "Authorization:Bearer $token"
1094 summary: Import a torrent or magnetURI or HTTP ressource (if enabled by the instance administrator)
1101 description: successful operation
1105 $ref: '#/components/schemas/VideoUploadResponse'
1108 multipart/form-data:
1113 description: Torrent File
1117 description: HTTP target URL
1120 description: Magnet URI
1123 description: Channel id that will contain this video
1126 description: Video thumbnail file
1129 description: Video preview file
1132 $ref: '#/components/schemas/VideoPrivacy'
1134 description: Video category
1137 description: Video licence
1140 description: Video language
1143 description: Video description
1146 description: Whether or not we wait transcoding before publish the video
1149 description: Text describing how to support the video uploader
1152 description: Whether or not this video contains sensitive content
1155 description: Video name
1158 description: Video tags
1163 description: Enable or disable comments for this video
1165 scheduleUpdate: *ref_0
1171 summary: Get list of reported video abuses
1177 - $ref: '#/components/parameters/start'
1178 - $ref: '#/components/parameters/count'
1179 - $ref: '#/components/parameters/abusesSort'
1182 description: successful operation
1188 $ref: '#/components/schemas/VideoAbuse'
1189 '/videos/{id}/abuse':
1191 summary: 'Report an abuse, on a video by its id'
1197 - $ref: '#/components/parameters/id2'
1200 $ref: '#/paths/~1users~1me/put/responses/204'
1201 '/videos/{id}/blacklist':
1203 summary: Put on blacklist a video by its id
1211 - $ref: '#/components/parameters/id2'
1214 $ref: '#/paths/~1users~1me/put/responses/204'
1216 summary: Delete an entry of the blacklist of a video by its id
1224 - $ref: '#/components/parameters/id2'
1227 $ref: '#/paths/~1users~1me/put/responses/204'
1230 summary: Get list of videos on blacklist
1238 - $ref: '#/components/parameters/start'
1239 - $ref: '#/components/parameters/count'
1240 - $ref: '#/components/parameters/blacklistsSort'
1243 description: successful operation
1249 $ref: '#/components/schemas/VideoBlacklist'
1252 summary: Get list of video channels
1256 - $ref: '#/components/parameters/start'
1257 - $ref: '#/components/parameters/count'
1258 - $ref: '#/components/parameters/sort'
1261 description: successful operation
1267 $ref: '#/components/schemas/VideoChannel'
1269 summary: Creates a video channel for the current user
1276 $ref: '#/paths/~1users~1me/put/responses/204'
1278 $ref: '#/components/requestBodies/VideoChannelInput'
1279 '/video-channels/{id}':
1281 summary: Get a video channel by its id
1285 - $ref: '#/components/parameters/id3'
1288 description: successful operation
1292 $ref: '#/components/schemas/VideoChannel'
1294 summary: Update a video channel by its id
1300 - $ref: '#/components/parameters/id3'
1303 $ref: '#/paths/~1users~1me/put/responses/204'
1305 $ref: '#/components/requestBodies/VideoChannelInput'
1307 summary: Delete a video channel by its id
1313 - $ref: '#/components/parameters/id3'
1316 $ref: '#/paths/~1users~1me/put/responses/204'
1317 '/video-channels/{id}/videos':
1319 summary: Get videos of a video channel by its id
1323 - $ref: '#/components/parameters/id3'
1326 description: successful operation
1330 $ref: '#/components/schemas/Video'
1331 '/accounts/{name}/video-channels':
1333 summary: Get video channels of an account by its name
1337 - $ref: '#/components/parameters/name'
1340 description: successful operation
1346 $ref: '#/components/schemas/VideoChannel'
1347 '/accounts/{name}/ratings':
1349 summary: Get ratings of an account by its name
1355 - $ref: '#/components/parameters/start'
1356 - $ref: '#/components/parameters/count'
1357 - $ref: '#/components/parameters/sort'
1361 description: Optionaly filter which ratings to retrieve
1369 description: successful operation
1375 $ref: '#/components/schemas/VideoRating'
1376 '/videos/{id}/comment-threads':
1378 summary: Get the comment threads of a video by its id
1382 - $ref: '#/components/parameters/id2'
1383 - $ref: '#/components/parameters/start'
1384 - $ref: '#/components/parameters/count'
1385 - $ref: '#/components/parameters/sort'
1388 description: successful operation
1392 $ref: '#/components/schemas/CommentThreadResponse'
1394 summary: 'Creates a comment thread, on a video by its id'
1400 - $ref: '#/components/parameters/id2'
1403 description: successful operation
1407 $ref: '#/components/schemas/CommentThreadPostResponse'
1408 '/videos/{id}/comment-threads/{threadId}':
1410 summary: 'Get the comment thread by its id, of a video by its id'
1414 - $ref: '#/components/parameters/id2'
1418 description: The thread id (root comment id)
1423 description: successful operation
1427 $ref: '#/components/schemas/VideoCommentThreadTree'
1428 '/videos/{id}/comments/{commentId}':
1430 summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1436 - $ref: '#/components/parameters/id2'
1437 - $ref: '#/components/parameters/commentId'
1440 description: successful operation
1444 $ref: '#/components/schemas/CommentThreadPostResponse'
1446 summary: 'Delete a comment in a comment therad by its id, of a video by its id'
1452 - $ref: '#/components/parameters/id2'
1453 - $ref: '#/components/parameters/commentId'
1456 $ref: '#/paths/~1users~1me/put/responses/204'
1457 '/videos/{id}/rate':
1459 summary: Vote for a video by its id
1465 - $ref: '#/components/parameters/id2'
1468 $ref: '#/paths/~1users~1me/put/responses/204'
1473 summary: Get the videos corresponding to a given query
1475 - $ref: '#/components/parameters/start'
1476 - $ref: '#/components/parameters/count'
1477 - $ref: '#/components/parameters/videosSearchSort'
1481 description: String to search
1486 description: successful operation
1492 $ref: '#/components/schemas/Video'
1494 - url: 'https://peertube.cpy.re/api/v1'
1495 description: Live Test Server (live data - stable version)
1496 - url: 'https://peertube2.cpy.re/api/v1'
1497 description: Live Test Server (live data - bleeding edge version)
1498 - url: 'https://peertube3.cpy.re/api/v1'
1499 description: Live Test Server (live data - bleeding edge version)
1513 description: Number of items
1520 description: Sort column (-createdAt for example)
1527 description: Sort videos by criteria
1542 description: Sort videos by criteria
1557 description: Sort blacklists by criteria
1573 description: Sort users by criteria
1584 description: Sort abuses by criteria
1596 The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1604 description: The user id
1611 description: The video id or uuid
1618 description: The video channel id or uuid
1625 description: The comment id
1632 description: category id of the video
1645 description: tag(s) of the video
1658 description: tag(s) of the video, where all should be present in the video
1671 description: language id of the video
1684 description: licence id of the video
1697 description: whether to include nsfw videos, if any
1708 Special filters (local for instance) which might require special rights:
1709 * `local` - only videos local to the instance
1710 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
1720 description: list of uris to check if each is part of the user subscriptions
1730 $ref: '#/components/schemas/VideoChannelInput'
1734 In the header: *Authorization: Bearer <token\>*
1737 Authenticating via OAuth requires the following steps:
1740 - Have an account with sufficient authorization levels
1742 - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
1745 - Make Authenticated Requests
1749 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1752 moderator: Moderator scope
1755 VideoConstantNumber:
1761 VideoConstantString:
1786 $ref: '#/components/schemas/VideoConstantNumber'
1788 $ref: '#/components/schemas/VideoConstantNumber'
1790 $ref: '#/components/schemas/VideoConstantString'
1792 $ref: '#/components/schemas/VideoPrivacy'
1827 $ref: '#/components/schemas/Avatar'
1835 $ref: '#/components/schemas/Account'
1911 $ref: '#/components/schemas/Account'
1912 VideoCommentThreadTree:
1915 $ref: '#/components/schemas/VideoComment'
1919 $ref: '#/components/schemas/VideoCommentThreadTree'
1949 $ref: '#/components/schemas/Avatar'
1952 - $ref: '#/components/schemas/Actor'
1981 $ref: '#/components/schemas/Account'
1985 $ref: '#/components/schemas/VideoChannel'
2034 $ref: '#/components/schemas/Actor'
2036 $ref: '#/components/schemas/Actor'
2078 VideoUploadResponse:
2087 CommentThreadResponse:
2094 $ref: '#/components/schemas/VideoComment'
2095 CommentThreadPostResponse:
2098 $ref: '#/components/schemas/VideoComment'
2103 description: 'The user username '
2106 description: 'The user password '
2109 description: 'The user email '
2112 description: 'The user videoQuota '
2115 description: 'The user daily video quota '
2123 description: 'The user role '
2135 description: 'The user id '
2138 description: 'The updated email of the user '
2141 description: 'The updated videoQuota of the user '
2144 description: 'The updated daily video quota of the user '
2147 description: 'The updated role of the user '
2158 description: 'Your new password '
2161 description: 'Your new email '
2164 description: 'Your new displayNSFW '
2167 description: 'Your new autoPlayVideo '
2177 description: 'Id of the video '
2180 description: 'Rating of the video '
2187 $ref: '#/components/schemas/Video'
2190 description: 'Rating of the video'
2198 description: 'The username of the user '
2201 description: 'The password of the user '
2204 description: 'The email of the user '