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/sort'
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
500 description: successful operation
506 $ref: '#/components/schemas/User'
508 summary: Update current user information
515 description: Successful operation
520 $ref: '#/components/schemas/UpdateMe'
522 /users/me/video-quota-used:
524 summary: Get current user used quota
531 description: successful operation
536 '/users/me/videos/{videoId}/rating':
538 summary: 'Get rating of video by its id, among those of the current user'
547 description: 'The video id '
552 description: successful operation
556 $ref: '#/components/schemas/GetMeVideoRating'
559 summary: Get videos of the current user
565 - $ref: '#/components/parameters/start'
566 - $ref: '#/components/parameters/count'
567 - $ref: '#/components/parameters/sort'
570 description: successful operation
576 $ref: '#/components/schemas/Video'
579 summary: Register a user
584 $ref: '#/paths/~1users~1me/put/responses/204'
589 $ref: '#/components/schemas/RegisterUser'
591 /users/me/avatar/pick:
593 summary: Update current user avatar
600 description: successful operation
604 $ref: '#/components/schemas/Avatar'
612 description: The file to upload.
617 # only accept png/jpeg
618 contentType: image/png, image/jpeg
621 summary: Get list of videos
628 description: category id of the video
631 - $ref: '#/components/parameters/start'
632 - $ref: '#/components/parameters/count'
633 - $ref: '#/components/parameters/sort'
636 description: successful operation
642 $ref: '#/components/schemas/Video'
645 summary: Get list of video licences known by the server
650 description: successful operation
659 summary: Get list of video licences known by the server
664 description: successful operation
673 summary: Get list of languages known by the server
678 description: successful operation
687 summary: Get list of privacy policies supported by the server
692 description: successful operation
701 summary: Update metadata for a video by its id
707 - $ref: '#/components/parameters/id2'
710 description: successful operation
714 $ref: '#/components/schemas/Video'
722 description: Video thumbnail file
725 description: Video preview file
728 description: Video category
731 description: Video licence
734 description: Video language
737 description: Video description
740 description: Whether or not we wait transcoding before publish the video
743 description: Text describing how to support the video uploader
746 description: Whether or not this video contains sensitive content
749 description: Video name
752 description: Video tags
755 description: Enable or disable comments for this video
757 scheduleUpdate: &ref_0
765 description: Video privacy target
769 description: When to update the video
773 summary: Get a video by its id
777 - $ref: '#/components/parameters/id2'
780 description: successful operation
784 $ref: '#/components/schemas/Video'
786 summary: Delete a video by its id
792 - $ref: '#/components/parameters/id2'
795 $ref: '#/paths/~1users~1me/put/responses/204'
796 '/videos/{id}/description':
798 summary: Get a video description by its id
802 - $ref: '#/components/parameters/id2'
805 description: successful operation
810 '/videos/{id}/views':
812 summary: Add a view to the video by its id
816 - $ref: '#/components/parameters/id2'
819 $ref: '#/paths/~1users~1me/put/responses/204'
820 '/videos/{id}/watching':
822 summary: Indicate progress of in watching the video by its id for a user
828 - $ref: '#/components/parameters/id2'
833 $ref: '#/components/schemas/UserWatchingVideo'
837 $ref: '#/paths/~1users~1me/put/responses/204'
840 summary: Get list of video ownership changes requests
846 - $ref: '#/components/parameters/id2'
849 description: successful operation
850 '/videos/ownership/{id}/accept':
852 summary: Refuse ownership change request for video by its id
858 - $ref: '#/components/parameters/id2'
861 $ref: '#/paths/~1users~1me/put/responses/204'
862 '/videos/ownership/{id}/refuse':
864 summary: Accept ownership change request for video by its id
870 - $ref: '#/components/parameters/id2'
873 $ref: '#/paths/~1users~1me/put/responses/204'
874 '/videos/{id}/give-ownership':
876 summary: Request change of ownership for a video you own, by its id
882 - $ref: '#/components/parameters/id2'
886 application/x-www-form-urlencoded:
896 $ref: '#/paths/~1users~1me/put/responses/204'
898 description: 'Changing video ownership to a remote account is not supported yet'
901 summary: Upload a video file with its metadata
908 description: successful operation
912 $ref: '#/components/schemas/VideoUploadResponse'
920 description: Video file
924 description: Channel id that will contain this video
927 description: Video thumbnail file
930 description: Video preview file
933 $ref: '#/components/schemas/VideoPrivacy'
935 description: Video category
938 description: Video licence
941 description: Video language
944 description: Video description
947 description: Whether or not we wait transcoding before publish the video
950 description: Text describing how to support the video uploader
953 description: Whether or not this video contains sensitive content
956 description: Video name
959 description: Video tags
962 description: Enable or disable comments for this video
964 scheduleUpdate: *ref_0
972 ## DEPENDENCIES: httpie, jq
974 USERNAME="<your_username>"
975 PASSWORD="<your_password>"
976 FILE_PATH="<your_file_path>"
977 CHANNEL_ID="<your_channel_id>"
980 API_PATH="https://peertube2.cpy.re/api/v1"
982 client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
983 client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
984 token=$(http -b --form POST "$API_PATH/users/token" \
985 client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
988 | jq -r ".access_token")
990 http -b --form POST "$API_PATH/videos/upload" \
991 videofile@$FILE_PATH \
992 channelId=$CHANNEL_ID \
994 "Authorization:Bearer $token"
997 summary: Get list of reported video abuses
1003 - $ref: '#/components/parameters/start'
1004 - $ref: '#/components/parameters/count'
1005 - $ref: '#/components/parameters/sort'
1008 description: successful operation
1014 $ref: '#/components/schemas/VideoAbuse'
1015 '/videos/{id}/abuse':
1017 summary: 'Report an abuse, on a video by its id'
1023 - $ref: '#/components/parameters/id2'
1026 $ref: '#/paths/~1users~1me/put/responses/204'
1027 '/videos/{id}/blacklist':
1029 summary: Put on blacklist a video by its id
1037 - $ref: '#/components/parameters/id2'
1040 $ref: '#/paths/~1users~1me/put/responses/204'
1042 summary: Delete an entry of the blacklist of a video by its id
1050 - $ref: '#/components/parameters/id2'
1053 $ref: '#/paths/~1users~1me/put/responses/204'
1056 summary: Get list of videos on blacklist
1064 - $ref: '#/components/parameters/start'
1065 - $ref: '#/components/parameters/count'
1066 - $ref: '#/components/parameters/sort'
1069 description: successful operation
1075 $ref: '#/components/schemas/VideoBlacklist'
1078 summary: Get list of video channels
1082 - $ref: '#/components/parameters/start'
1083 - $ref: '#/components/parameters/count'
1084 - $ref: '#/components/parameters/sort'
1087 description: successful operation
1093 $ref: '#/components/schemas/VideoChannel'
1095 summary: Creates a video channel for the current user
1102 $ref: '#/paths/~1users~1me/put/responses/204'
1104 $ref: '#/components/requestBodies/VideoChannelInput'
1105 '/video-channels/{id}':
1107 summary: Get a video channel by its id
1111 - $ref: '#/components/parameters/id3'
1114 description: successful operation
1118 $ref: '#/components/schemas/VideoChannel'
1120 summary: Update a video channel by its id
1126 - $ref: '#/components/parameters/id3'
1129 $ref: '#/paths/~1users~1me/put/responses/204'
1131 $ref: '#/components/requestBodies/VideoChannelInput'
1133 summary: Delete a video channel by its id
1139 - $ref: '#/components/parameters/id3'
1142 $ref: '#/paths/~1users~1me/put/responses/204'
1143 '/video-channels/{id}/videos':
1145 summary: Get videos of a video channel by its id
1149 - $ref: '#/components/parameters/id3'
1152 description: successful operation
1156 $ref: '#/components/schemas/Video'
1157 '/accounts/{name}/video-channels':
1159 summary: Get video channels of an account by its name
1163 - $ref: '#/components/parameters/name'
1166 description: successful operation
1172 $ref: '#/components/schemas/VideoChannel'
1173 '/videos/{id}/comment-threads':
1175 summary: Get the comment threads of a video by its id
1179 - $ref: '#/components/parameters/id2'
1180 - $ref: '#/components/parameters/start'
1181 - $ref: '#/components/parameters/count'
1182 - $ref: '#/components/parameters/sort'
1185 description: successful operation
1189 $ref: '#/components/schemas/CommentThreadResponse'
1191 summary: 'Creates a comment thread, on a video by its id'
1197 - $ref: '#/components/parameters/id2'
1200 description: successful operation
1204 $ref: '#/components/schemas/CommentThreadPostResponse'
1205 '/videos/{id}/comment-threads/{threadId}':
1207 summary: 'Get the comment thread by its id, of a video by its id'
1211 - $ref: '#/components/parameters/id2'
1215 description: The thread id (root comment id)
1220 description: successful operation
1224 $ref: '#/components/schemas/VideoCommentThreadTree'
1225 '/videos/{id}/comments/{commentId}':
1227 summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1233 - $ref: '#/components/parameters/id2'
1234 - $ref: '#/components/parameters/commentId'
1237 description: successful operation
1241 $ref: '#/components/schemas/CommentThreadPostResponse'
1243 summary: 'Delete a comment in a comment therad by its id, of a video by its id'
1249 - $ref: '#/components/parameters/id2'
1250 - $ref: '#/components/parameters/commentId'
1253 $ref: '#/paths/~1users~1me/put/responses/204'
1254 '/videos/{id}/rate':
1256 summary: Vote for a video by its id
1262 - $ref: '#/components/parameters/id2'
1265 $ref: '#/paths/~1users~1me/put/responses/204'
1270 summary: Get the videos corresponding to a given query
1272 - $ref: '#/components/parameters/start'
1273 - $ref: '#/components/parameters/count'
1274 - $ref: '#/components/parameters/sort'
1278 description: String to search
1283 description: successful operation
1289 $ref: '#/components/schemas/Video'
1291 - url: 'https://peertube.cpy.re/api/v1'
1292 description: Live Test Server (live data - stable version)
1293 - url: 'https://peertube2.cpy.re/api/v1'
1294 description: Live Test Server (live data - bleeding edge version)
1295 - url: 'https://peertube3.cpy.re/api/v1'
1296 description: Live Test Server (live data - bleeding edge version)
1310 description: Number of items
1317 description: Sort column (-createdAt for example)
1325 The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1333 description: The user id
1340 description: The video id or uuid
1347 description: The video channel id or uuid
1354 description: The comment id
1362 $ref: '#/components/schemas/VideoChannelInput'
1366 In the header: *Authorization: Bearer <token\>*
1369 Authenticating via OAuth requires the following steps:
1372 - Have an account with sufficient authorization levels
1374 - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
1377 - Make Authenticated Requests
1381 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1384 moderator: Moderator scope
1387 VideoConstantNumber:
1393 VideoConstantString:
1418 $ref: '#/components/schemas/VideoConstantNumber'
1420 $ref: '#/components/schemas/VideoConstantNumber'
1422 $ref: '#/components/schemas/VideoConstantString'
1424 $ref: '#/components/schemas/VideoPrivacy'
1459 $ref: '#/components/schemas/Avatar'
1467 $ref: '#/components/schemas/Account'
1543 $ref: '#/components/schemas/Account'
1544 VideoCommentThreadTree:
1547 $ref: '#/components/schemas/VideoComment'
1551 $ref: '#/components/schemas/VideoCommentThreadTree'
1581 $ref: '#/components/schemas/Avatar'
1584 - $ref: '#/components/schemas/Actor'
1611 $ref: '#/components/schemas/Account'
1615 $ref: '#/components/schemas/VideoChannel'
1664 $ref: '#/components/schemas/Actor'
1666 $ref: '#/components/schemas/Actor'
1708 VideoUploadResponse:
1717 CommentThreadResponse:
1724 $ref: '#/components/schemas/VideoComment'
1725 CommentThreadPostResponse:
1728 $ref: '#/components/schemas/VideoComment'
1733 description: 'The user username '
1736 description: 'The user password '
1739 description: 'The user email '
1742 description: 'The user videoQuota '
1745 description: 'The user role '
1756 description: 'The user id '
1759 description: 'The updated email of the user '
1762 description: 'The updated videoQuota of the user '
1765 description: 'The updated role of the user '
1775 description: 'Your new password '
1778 description: 'Your new email '
1781 description: 'Your new displayNSFW '
1784 description: 'Your new autoPlayVideo '
1794 description: 'Id of the video '
1797 description: 'Rating of the video '
1805 description: 'The username of the user '
1808 description: 'The password of the user '
1811 description: 'The email of the user '