]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blame_incremental - support/doc/api/openapi.yaml
projects / github / Chocobozzz / PeerTube.git / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
Bumped to version v1.1.0
[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml
... / ...
CommitLineData
1openapi: 3.0.0
2info:
3 title: PeerTube
4 version: 1.1.0
5 contact:
6 name: PeerTube Community
7 url: 'https://joinpeertube.org'
8 license:
9 name: AGPLv3.0
10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
11 x-logo:
12 url: 'https://joinpeertube.org/img/brand.png'
13 altText: PeerTube Project Homepage
14 description: |
15 # Introduction
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.
23
24 # Authentication
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.
28
29 # Errors
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
32 format.
33
34 ```
35 {
36 "code": "unauthorized_request", // example inner error code
37 "error": "Token is invalid." // example exposed error message
38 }
39 ```
40externalDocs:
41 url: https://docs.joinpeertube.org/api.html
42tags:
43 - name: Accounts
44 description: >
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.
48 - name: Config
49 description: >
50 Each server exposes public information regarding supported videos and
51 options.
52 - name: Feeds
53 description: |
54 Feeds of videos and feeds of comments allow to see updates and get them in
55 an aggregator or script of your choice.
56 - name: Job
57 description: >
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
61 description: >
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
66 endpoints.
67 - name: Video Abuse
68 description: |
69 Video abuses deal with reports of local or remote videos alike.
70 - name: Video
71 description: |
72 Operations dealing with listing, uploading, fetching or modifying videos.
73 - name: Search
74 description: |
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
78 the advanced search.
79 - name: Video Comment
80 description: >
81 Operations dealing with comments to a video. Comments are organized in
82 threads.
83 - name: Video Channel
84 description: >
85 Operations dealing with creation, modification and video listing of a
86 user's channels.
87 - name: Video Blacklist
88 description: >
89 Operations dealing with blacklisting videos (removing them from view and
90 preventing interactions).
91 - name: Video Rate
92 description: >
93 Voting for a video.
94x-tagGroups:
95 - name: Accounts
96 tags:
97 - Accounts
98 - User
99 - name: Videos
100 tags:
101 - Video
102 - Video Channel
103 - Video Comment
104 - Video Following
105 - Video Rate
106 - name: Moderation
107 tags:
108 - Video Abuse
109 - Video Blacklist
110 - name: Instance Configuration
111 tags:
112 - Config
113 - Server Following
114 - name: Notifications
115 tags:
116 - Feeds
117 - name: Jobs
118 tags:
119 - Job
120 - name: Search
121 tags:
122 - Search
123paths:
124 '/accounts/{name}':
125 get:
126 tags:
127 - Accounts
128 summary: Get the account by name
129 parameters:
130 - $ref: '#/components/parameters/name'
131 - $ref: '#/components/parameters/start'
132 - $ref: '#/components/parameters/count'
133 - $ref: '#/components/parameters/sort'
134 responses:
135 '200':
136 description: successful operation
137 content:
138 application/json:
139 schema:
140 $ref: '#/components/schemas/Account'
141 '/accounts/{name}/videos':
142 get:
143 tags:
144 - Accounts
145 - Video
146 summary: 'Get videos for an account, provided the name of that account'
147 parameters:
148 - $ref: '#/components/parameters/name'
149 responses:
150 '200':
151 description: successful operation
152 content:
153 application/json:
154 schema:
155 $ref: '#/components/schemas/Video'
156 x-code-samples:
157 - lang: JavaScript
158 source: |
159 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
160 .then(function(response) {
161 return response.json()
162 }).then(function(data) {
163 console.log(data)
164 })
165 - lang: Shell
166 source: |
167 # pip install httpie
168 http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
169 - lang: Ruby
170 source: |
171 require 'uri'
172 require 'net/http'
173
174 url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
175
176 http = Net::HTTP.new(url.host, url.port)
177 http.use_ssl = true
178 http.verify_mode = OpenSSL::SSL::VERIFY_NONE
179
180 request = Net::HTTP::Post.new(url)
181 request["content-type"] = 'application/json'
182 response = http.request(request)
183 puts response.read_body
184 - lang: Python
185 source: |
186 import http.client
187
188 conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
189
190 headers = {
191 'content-type': "application/json"
192 }
193
194 conn.request("POST", "/accounts/{name}/videos", None, headers)
195
196 res = conn.getresponse()
197 data = res.read()
198
199 print(data.decode("utf-8"))
200 /accounts:
201 get:
202 tags:
203 - Accounts
204 summary: Get all accounts
205 responses:
206 '200':
207 description: successful operation
208 content:
209 'application/json':
210 schema:
211 type: array
212 items:
213 $ref: '#/components/schemas/Account'
214 /config:
215 get:
216 tags:
217 - Config
218 summary: Get the public configuration of the server
219 responses:
220 '200':
221 description: successful operation
222 content:
223 application/json:
224 schema:
225 $ref: '#/components/schemas/ServerConfig'
226 /config/about:
227 get:
228 summary: Get the instance about page content
229 tags:
230 - Config
231 responses:
232 '200':
233 description: successful operation
234 /config/custom:
235 get:
236 summary: Get the runtime configuration of the server
237 tags:
238 - Config
239 security:
240 - OAuth2:
241 - admin
242 responses:
243 '200':
244 description: successful operation
245 put:
246 summary: Set the runtime configuration of the server
247 tags:
248 - Config
249 security:
250 - OAuth2:
251 - admin
252 responses:
253 '200':
254 description: successful operation
255 delete:
256 summary: Delete the runtime configuration of the server
257 tags:
258 - Config
259 security:
260 - OAuth2:
261 - admin
262 responses:
263 '200':
264 description: successful operation
265 '/feeds/videos.{format}':
266 get:
267 summary: >-
268 Get the feed of videos for the server, with optional filter by account
269 name or id
270 tags:
271 - Feeds
272 parameters:
273 - name: format
274 in: path
275 required: true
276 description: >-
277 The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
278 json to JSON FEED 1.0
279 schema:
280 type: string
281 enum:
282 - xml
283 - atom
284 - json
285 default: xml
286 - name: accountId
287 in: query
288 required: false
289 description: >-
290 The id of the local account to filter to (beware, users IDs and not
291 actors IDs which will return empty feeds
292 schema:
293 type: number
294 - name: accountName
295 in: query
296 required: false
297 description: The name of the local account to filter to
298 schema:
299 type: string
300 responses:
301 '200':
302 description: successful operation
303 /jobs/{state}:
304 get:
305 summary: Get list of jobs
306 security:
307 - OAuth2:
308 - admin
309 tags:
310 - Job
311 parameters:
312 - name: state
313 in: path
314 required: true
315 description: The state of the job
316 schema:
317 type: string
318 enum:
319 - active
320 - completed
321 - failed
322 - waiting
323 - delayed
324 - $ref: '#/components/parameters/start'
325 - $ref: '#/components/parameters/count'
326 - $ref: '#/components/parameters/sort'
327 responses:
328 '200':
329 description: successful operation
330 content:
331 application/json:
332 schema:
333 type: array
334 items:
335 $ref: '#/components/schemas/Job'
336 '/server/following/{host}':
337 delete:
338 security:
339 - OAuth2:
340 - admin
341 tags:
342 - Server Following
343 summary: Unfollow a server by hostname
344 parameters:
345 - name: host
346 in: path
347 required: true
348 description: 'The host to unfollow '
349 schema:
350 type: string
351 responses:
352 '201':
353 description: successful operation
354 /server/followers:
355 get:
356 tags:
357 - Server Following
358 summary: Get followers of the server
359 parameters:
360 - $ref: '#/components/parameters/start'
361 - $ref: '#/components/parameters/count'
362 - $ref: '#/components/parameters/sort'
363 responses:
364 '200':
365 description: successful operation
366 content:
367 application/json:
368 schema:
369 type: array
370 items:
371 $ref: '#/components/schemas/Follow'
372 /server/following:
373 get:
374 tags:
375 - Server Following
376 summary: Get servers followed by the server
377 parameters:
378 - $ref: '#/components/parameters/start'
379 - $ref: '#/components/parameters/count'
380 - $ref: '#/components/parameters/sort'
381 responses:
382 '200':
383 description: successful operation
384 content:
385 application/json:
386 schema:
387 type: array
388 items:
389 $ref: '#/components/schemas/Follow'
390 post:
391 security:
392 - OAuth2:
393 - admin
394 tags:
395 - Server Following
396 summary: Follow a server
397 responses:
398 '204':
399 $ref: '#/paths/~1users~1me/put/responses/204'
400 requestBody:
401 content:
402 application/json:
403 schema:
404 $ref: '#/components/schemas/Follow'
405 /users:
406 post:
407 summary: Creates user
408 security:
409 - OAuth2:
410 - admin
411 tags:
412 - User
413 responses:
414 '200':
415 description: successful operation
416 content:
417 application/json:
418 schema:
419 $ref: '#/components/schemas/AddUserResponse'
420 requestBody:
421 content:
422 application/json:
423 schema:
424 $ref: '#/components/schemas/AddUser'
425 description: User to create
426 required: true
427 get:
428 summary: Get a list of users
429 security:
430 - OAuth2: []
431 tags:
432 - User
433 parameters:
434 - $ref: '#/components/parameters/start'
435 - $ref: '#/components/parameters/count'
436 - $ref: '#/components/parameters/usersSort'
437 responses:
438 '200':
439 description: successful operation
440 content:
441 application/json:
442 schema:
443 type: array
444 items:
445 $ref: '#/components/schemas/User'
446 '/users/{id}':
447 delete:
448 summary: Delete a user by its id
449 security:
450 - OAuth2:
451 - admin
452 tags:
453 - User
454 parameters:
455 - $ref: '#/components/parameters/id'
456 responses:
457 '204':
458 $ref: '#/paths/~1users~1me/put/responses/204'
459 get:
460 summary: Get user by its id
461 security:
462 - OAuth2: []
463 tags:
464 - User
465 parameters:
466 - $ref: '#/components/parameters/id'
467 responses:
468 '200':
469 description: successful operation
470 content:
471 application/json:
472 schema:
473 $ref: '#/components/schemas/User'
474 put:
475 summary: Update user profile by its id
476 security:
477 - OAuth2: []
478 tags:
479 - User
480 parameters:
481 - $ref: '#/components/parameters/id'
482 responses:
483 '204':
484 $ref: '#/paths/~1users~1me/put/responses/204'
485 requestBody:
486 content:
487 application/json:
488 schema:
489 $ref: '#/components/schemas/UpdateUser'
490 required: true
491 /users/me:
492 get:
493 summary: Get current user information
494 security:
495 - OAuth2: []
496 tags:
497 - User
498 responses:
499 '200':
500 description: successful operation
501 content:
502 application/json:
503 schema:
504 type: array
505 items:
506 $ref: '#/components/schemas/User'
507 put:
508 summary: Update current user information
509 security:
510 - OAuth2: []
511 tags:
512 - User
513 responses:
514 '204':
515 description: Successful operation
516 requestBody:
517 content:
518 application/json:
519 schema:
520 $ref: '#/components/schemas/UpdateMe'
521 required: true
522 /users/me/video-quota-used:
523 get:
524 summary: Get current user used quota
525 security:
526 - OAuth2: []
527 tags:
528 - User
529 responses:
530 '200':
531 description: successful operation
532 content:
533 application/json:
534 schema:
535 type: number
536 '/users/me/videos/{videoId}/rating':
537 get:
538 summary: 'Get rating of video by its id, among those of the current user'
539 security:
540 - OAuth2: []
541 tags:
542 - User
543 parameters:
544 - name: videoId
545 in: path
546 required: true
547 description: 'The video id '
548 schema:
549 type: string
550 responses:
551 '200':
552 description: successful operation
553 content:
554 application/json:
555 schema:
556 $ref: '#/components/schemas/GetMeVideoRating'
557 /users/me/videos:
558 get:
559 summary: Get videos of the current user
560 security:
561 - OAuth2: []
562 tags:
563 - User
564 parameters:
565 - $ref: '#/components/parameters/start'
566 - $ref: '#/components/parameters/count'
567 - $ref: '#/components/parameters/sort'
568 responses:
569 '200':
570 description: successful operation
571 content:
572 application/json:
573 schema:
574 type: array
575 items:
576 $ref: '#/components/schemas/Video'
577 /users/register:
578 post:
579 summary: Register a user
580 tags:
581 - User
582 responses:
583 '204':
584 $ref: '#/paths/~1users~1me/put/responses/204'
585 requestBody:
586 content:
587 application/json:
588 schema:
589 $ref: '#/components/schemas/RegisterUser'
590 required: true
591 /users/me/avatar/pick:
592 post:
593 summary: Update current user avatar
594 security:
595 - OAuth2: []
596 tags:
597 - User
598 responses:
599 '200':
600 description: successful operation
601 content:
602 application/json:
603 schema:
604 $ref: '#/components/schemas/Avatar'
605 requestBody:
606 content:
607 multipart/form-data:
608 schema:
609 type: object
610 properties:
611 avatarfile:
612 description: The file to upload.
613 type: string
614 format: binary
615 encoding:
616 profileImage:
617 # only accept png/jpeg
618 contentType: image/png, image/jpeg
619 /videos:
620 get:
621 summary: Get list of videos
622 tags:
623 - Video
624 parameters:
625 - $ref: '#/components/parameters/categoryOneOf'
626 - $ref: '#/components/parameters/tagsOneOf'
627 - $ref: '#/components/parameters/tagsAllOf'
628 - $ref: '#/components/parameters/licenceOneOf'
629 - $ref: '#/components/parameters/languageOneOf'
630 - $ref: '#/components/parameters/nsfw'
631 - $ref: '#/components/parameters/filter'
632 - $ref: '#/components/parameters/start'
633 - $ref: '#/components/parameters/count'
634 - $ref: '#/components/parameters/videosSort'
635 responses:
636 '200':
637 description: successful operation
638 content:
639 application/json:
640 schema:
641 type: array
642 items:
643 $ref: '#/components/schemas/Video'
644 /videos/categories:
645 get:
646 summary: Get list of video licences known by the server
647 tags:
648 - Video
649 responses:
650 '200':
651 description: successful operation
652 content:
653 application/json:
654 schema:
655 type: array
656 items:
657 type: string
658 /videos/licences:
659 get:
660 summary: Get list of video licences known by the server
661 tags:
662 - Video
663 responses:
664 '200':
665 description: successful operation
666 content:
667 application/json:
668 schema:
669 type: array
670 items:
671 type: string
672 /videos/languages:
673 get:
674 summary: Get list of languages known by the server
675 tags:
676 - Video
677 responses:
678 '200':
679 description: successful operation
680 content:
681 application/json:
682 schema:
683 type: array
684 items:
685 type: string
686 /videos/privacies:
687 get:
688 summary: Get list of privacy policies supported by the server
689 tags:
690 - Video
691 responses:
692 '200':
693 description: successful operation
694 content:
695 application/json:
696 schema:
697 type: array
698 items:
699 type: string
700 '/videos/{id}':
701 put:
702 summary: Update metadata for a video by its id
703 security:
704 - OAuth2: []
705 tags:
706 - Video
707 parameters:
708 - $ref: '#/components/parameters/id2'
709 responses:
710 '200':
711 description: successful operation
712 content:
713 application/json:
714 schema:
715 $ref: '#/components/schemas/Video'
716 requestBody:
717 content:
718 multipart/form-data:
719 schema:
720 type: object
721 properties:
722 thumbnailfile:
723 description: Video thumbnail file
724 type: string
725 previewfile:
726 description: Video preview file
727 type: string
728 category:
729 description: Video category
730 type: string
731 licence:
732 description: Video licence
733 type: string
734 language:
735 description: Video language
736 type: string
737 description:
738 description: Video description
739 type: string
740 waitTranscoding:
741 description: Whether or not we wait transcoding before publish the video
742 type: string
743 support:
744 description: Text describing how to support the video uploader
745 type: string
746 nsfw:
747 description: Whether or not this video contains sensitive content
748 type: string
749 name:
750 description: Video name
751 type: string
752 tags:
753 description: Video tags
754 type: string
755 commentsEnabled:
756 description: Enable or disable comments for this video
757 type: string
758 scheduleUpdate: &ref_0
759 type: object
760 properties:
761 privacy:
762 type: string
763 enum:
764 - Public
765 - Unlisted
766 description: Video privacy target
767 updateAt:
768 type: string
769 format: date
770 description: When to update the video
771 required:
772 - updateAt
773 get:
774 summary: Get a video by its id
775 tags:
776 - Video
777 parameters:
778 - $ref: '#/components/parameters/id2'
779 responses:
780 '200':
781 description: successful operation
782 content:
783 application/json:
784 schema:
785 $ref: '#/components/schemas/Video'
786 delete:
787 summary: Delete a video by its id
788 security:
789 - OAuth2: []
790 tags:
791 - Video
792 parameters:
793 - $ref: '#/components/parameters/id2'
794 responses:
795 '204':
796 $ref: '#/paths/~1users~1me/put/responses/204'
797 '/videos/{id}/description':
798 get:
799 summary: Get a video description by its id
800 tags:
801 - Video
802 parameters:
803 - $ref: '#/components/parameters/id2'
804 responses:
805 '200':
806 description: successful operation
807 content:
808 application/json:
809 schema:
810 type: string
811 '/videos/{id}/views':
812 post:
813 summary: Add a view to the video by its id
814 tags:
815 - Video
816 parameters:
817 - $ref: '#/components/parameters/id2'
818 responses:
819 '204':
820 $ref: '#/paths/~1users~1me/put/responses/204'
821 '/videos/{id}/watching':
822 put:
823 summary: Indicate progress of in watching the video by its id for a user
824 tags:
825 - Video
826 security:
827 - OAuth2: []
828 parameters:
829 - $ref: '#/components/parameters/id2'
830 requestBody:
831 content:
832 application/json:
833 schema:
834 $ref: '#/components/schemas/UserWatchingVideo'
835 required: true
836 responses:
837 '204':
838 $ref: '#/paths/~1users~1me/put/responses/204'
839 /videos/ownership:
840 get:
841 summary: Get list of video ownership changes requests
842 tags:
843 - Video
844 security:
845 - OAuth2: []
846 parameters:
847 - $ref: '#/components/parameters/id2'
848 responses:
849 '200':
850 description: successful operation
851 '/videos/ownership/{id}/accept':
852 post:
853 summary: Refuse ownership change request for video by its id
854 tags:
855 - Video
856 security:
857 - OAuth2: []
858 parameters:
859 - $ref: '#/components/parameters/id2'
860 responses:
861 '204':
862 $ref: '#/paths/~1users~1me/put/responses/204'
863 '/videos/ownership/{id}/refuse':
864 post:
865 summary: Accept ownership change request for video by its id
866 tags:
867 - Video
868 security:
869 - OAuth2: []
870 parameters:
871 - $ref: '#/components/parameters/id2'
872 responses:
873 '204':
874 $ref: '#/paths/~1users~1me/put/responses/204'
875 '/videos/{id}/give-ownership':
876 post:
877 summary: Request change of ownership for a video you own, by its id
878 tags:
879 - Video
880 security:
881 - OAuth2: []
882 parameters:
883 - $ref: '#/components/parameters/id2'
884 requestBody:
885 required: true
886 content:
887 application/x-www-form-urlencoded:
888 schema:
889 type: object
890 properties:
891 username:
892 type: string
893 required:
894 - username
895 responses:
896 '204':
897 $ref: '#/paths/~1users~1me/put/responses/204'
898 '400':
899 description: 'Changing video ownership to a remote account is not supported yet'
900 /videos/upload:
901 post:
902 summary: Upload a video file with its metadata
903 security:
904 - OAuth2: []
905 tags:
906 - Video
907 responses:
908 '200':
909 description: successful operation
910 content:
911 application/json:
912 schema:
913 $ref: '#/components/schemas/VideoUploadResponse'
914 requestBody:
915 content:
916 multipart/form-data:
917 schema:
918 type: object
919 properties:
920 videofile:
921 description: Video file
922 type: string
923 format: binary
924 channelId:
925 description: Channel id that will contain this video
926 type: number
927 thumbnailfile:
928 description: Video thumbnail file
929 type: string
930 previewfile:
931 description: Video preview file
932 type: string
933 privacy:
934 $ref: '#/components/schemas/VideoPrivacy'
935 category:
936 description: Video category
937 type: string
938 licence:
939 description: Video licence
940 type: string
941 language:
942 description: Video language
943 type: string
944 description:
945 description: Video description
946 type: string
947 waitTranscoding:
948 description: Whether or not we wait transcoding before publish the video
949 type: string
950 support:
951 description: Text describing how to support the video uploader
952 type: string
953 nsfw:
954 description: Whether or not this video contains sensitive content
955 type: string
956 name:
957 description: Video name
958 type: string
959 tags:
960 description: Video tags
961 type: string
962 commentsEnabled:
963 description: Enable or disable comments for this video
964 type: string
965 scheduleUpdate: *ref_0
966 required:
967 - videofile
968 - channelId
969 - name
970 x-code-samples:
971 - lang: Shell
972 source: |
973 ## DEPENDENCIES: httpie, jq
974 # pip install httpie
975 USERNAME="<your_username>"
976 PASSWORD="<your_password>"
977 FILE_PATH="<your_file_path>"
978 CHANNEL_ID="<your_channel_id>"
979 NAME="<video_name>"
980
981 API_PATH="https://peertube2.cpy.re/api/v1"
982 ## AUTH
983 client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
984 client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
985 token=$(http -b --form POST "$API_PATH/users/token" \
986 client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
987 username=$USERNAME \
988 password=$PASSWORD \
989 | jq -r ".access_token")
990 ## VIDEO UPLOAD
991 http -b --form POST "$API_PATH/videos/upload" \
992 videofile@$FILE_PATH \
993 channelId=$CHANNEL_ID \
994 name=$NAME \
995 "Authorization:Bearer $token"
996 /videos/abuse:
997 get:
998 summary: Get list of reported video abuses
999 security:
1000 - OAuth2: []
1001 tags:
1002 - Video Abuse
1003 parameters:
1004 - $ref: '#/components/parameters/start'
1005 - $ref: '#/components/parameters/count'
1006 - $ref: '#/components/parameters/abusesSort'
1007 responses:
1008 '200':
1009 description: successful operation
1010 content:
1011 application/json:
1012 schema:
1013 type: array
1014 items:
1015 $ref: '#/components/schemas/VideoAbuse'
1016 '/videos/{id}/abuse':
1017 post:
1018 summary: 'Report an abuse, on a video by its id'
1019 security:
1020 - OAuth2: []
1021 tags:
1022 - Video Abuse
1023 parameters:
1024 - $ref: '#/components/parameters/id2'
1025 responses:
1026 '204':
1027 $ref: '#/paths/~1users~1me/put/responses/204'
1028 '/videos/{id}/blacklist':
1029 post:
1030 summary: Put on blacklist a video by its id
1031 security:
1032 - OAuth2:
1033 - admin
1034 - moderator
1035 tags:
1036 - Video Blacklist
1037 parameters:
1038 - $ref: '#/components/parameters/id2'
1039 responses:
1040 '204':
1041 $ref: '#/paths/~1users~1me/put/responses/204'
1042 delete:
1043 summary: Delete an entry of the blacklist of a video by its id
1044 security:
1045 - OAuth2:
1046 - admin
1047 - moderator
1048 tags:
1049 - Video Blacklist
1050 parameters:
1051 - $ref: '#/components/parameters/id2'
1052 responses:
1053 '204':
1054 $ref: '#/paths/~1users~1me/put/responses/204'
1055 /videos/blacklist:
1056 get:
1057 summary: Get list of videos on blacklist
1058 security:
1059 - OAuth2:
1060 - admin
1061 - moderator
1062 tags:
1063 - Video Blacklist
1064 parameters:
1065 - $ref: '#/components/parameters/start'
1066 - $ref: '#/components/parameters/count'
1067 - $ref: '#/components/parameters/blacklistsSort'
1068 responses:
1069 '200':
1070 description: successful operation
1071 content:
1072 application/json:
1073 schema:
1074 type: array
1075 items:
1076 $ref: '#/components/schemas/VideoBlacklist'
1077 /video-channels:
1078 get:
1079 summary: Get list of video channels
1080 tags:
1081 - Video Channel
1082 parameters:
1083 - $ref: '#/components/parameters/start'
1084 - $ref: '#/components/parameters/count'
1085 - $ref: '#/components/parameters/sort'
1086 responses:
1087 '200':
1088 description: successful operation
1089 content:
1090 application/json:
1091 schema:
1092 type: array
1093 items:
1094 $ref: '#/components/schemas/VideoChannel'
1095 post:
1096 summary: Creates a video channel for the current user
1097 security:
1098 - OAuth2: []
1099 tags:
1100 - Video Channel
1101 responses:
1102 '204':
1103 $ref: '#/paths/~1users~1me/put/responses/204'
1104 requestBody:
1105 $ref: '#/components/requestBodies/VideoChannelInput'
1106 '/video-channels/{id}':
1107 get:
1108 summary: Get a video channel by its id
1109 tags:
1110 - Video Channel
1111 parameters:
1112 - $ref: '#/components/parameters/id3'
1113 responses:
1114 '200':
1115 description: successful operation
1116 content:
1117 application/json:
1118 schema:
1119 $ref: '#/components/schemas/VideoChannel'
1120 put:
1121 summary: Update a video channel by its id
1122 security:
1123 - OAuth2: []
1124 tags:
1125 - Video Channel
1126 parameters:
1127 - $ref: '#/components/parameters/id3'
1128 responses:
1129 '204':
1130 $ref: '#/paths/~1users~1me/put/responses/204'
1131 requestBody:
1132 $ref: '#/components/requestBodies/VideoChannelInput'
1133 delete:
1134 summary: Delete a video channel by its id
1135 security:
1136 - OAuth2: []
1137 tags:
1138 - Video Channel
1139 parameters:
1140 - $ref: '#/components/parameters/id3'
1141 responses:
1142 '204':
1143 $ref: '#/paths/~1users~1me/put/responses/204'
1144 '/video-channels/{id}/videos':
1145 get:
1146 summary: Get videos of a video channel by its id
1147 tags:
1148 - Video Channel
1149 parameters:
1150 - $ref: '#/components/parameters/id3'
1151 responses:
1152 '200':
1153 description: successful operation
1154 content:
1155 application/json:
1156 schema:
1157 $ref: '#/components/schemas/Video'
1158 '/accounts/{name}/video-channels':
1159 get:
1160 summary: Get video channels of an account by its name
1161 tags:
1162 - Video Channel
1163 parameters:
1164 - $ref: '#/components/parameters/name'
1165 responses:
1166 '200':
1167 description: successful operation
1168 content:
1169 application/json:
1170 schema:
1171 type: array
1172 items:
1173 $ref: '#/components/schemas/VideoChannel'
1174 '/videos/{id}/comment-threads':
1175 get:
1176 summary: Get the comment threads of a video by its id
1177 tags:
1178 - Video Comment
1179 parameters:
1180 - $ref: '#/components/parameters/id2'
1181 - $ref: '#/components/parameters/start'
1182 - $ref: '#/components/parameters/count'
1183 - $ref: '#/components/parameters/sort'
1184 responses:
1185 '200':
1186 description: successful operation
1187 content:
1188 application/json:
1189 schema:
1190 $ref: '#/components/schemas/CommentThreadResponse'
1191 post:
1192 summary: 'Creates a comment thread, on a video by its id'
1193 security:
1194 - OAuth2: []
1195 tags:
1196 - Video Comment
1197 parameters:
1198 - $ref: '#/components/parameters/id2'
1199 responses:
1200 '200':
1201 description: successful operation
1202 content:
1203 application/json:
1204 schema:
1205 $ref: '#/components/schemas/CommentThreadPostResponse'
1206 '/videos/{id}/comment-threads/{threadId}':
1207 get:
1208 summary: 'Get the comment thread by its id, of a video by its id'
1209 tags:
1210 - Video Comment
1211 parameters:
1212 - $ref: '#/components/parameters/id2'
1213 - name: threadId
1214 in: path
1215 required: true
1216 description: The thread id (root comment id)
1217 schema:
1218 type: number
1219 responses:
1220 '200':
1221 description: successful operation
1222 content:
1223 application/json:
1224 schema:
1225 $ref: '#/components/schemas/VideoCommentThreadTree'
1226 '/videos/{id}/comments/{commentId}':
1227 post:
1228 summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1229 security:
1230 - OAuth2: []
1231 tags:
1232 - Video Comment
1233 parameters:
1234 - $ref: '#/components/parameters/id2'
1235 - $ref: '#/components/parameters/commentId'
1236 responses:
1237 '200':
1238 description: successful operation
1239 content:
1240 application/json:
1241 schema:
1242 $ref: '#/components/schemas/CommentThreadPostResponse'
1243 delete:
1244 summary: 'Delete a comment in a comment therad by its id, of a video by its id'
1245 security:
1246 - OAuth2: []
1247 tags:
1248 - Video Comment
1249 parameters:
1250 - $ref: '#/components/parameters/id2'
1251 - $ref: '#/components/parameters/commentId'
1252 responses:
1253 '204':
1254 $ref: '#/paths/~1users~1me/put/responses/204'
1255 '/videos/{id}/rate':
1256 put:
1257 summary: Vote for a video by its id
1258 security:
1259 - OAuth2: []
1260 tags:
1261 - Video Rate
1262 parameters:
1263 - $ref: '#/components/parameters/id2'
1264 responses:
1265 '204':
1266 $ref: '#/paths/~1users~1me/put/responses/204'
1267 /search/videos:
1268 get:
1269 tags:
1270 - Search
1271 summary: Get the videos corresponding to a given query
1272 parameters:
1273 - $ref: '#/components/parameters/start'
1274 - $ref: '#/components/parameters/count'
1275 - $ref: '#/components/parameters/videosSearchSort'
1276 - name: search
1277 in: query
1278 required: true
1279 description: String to search
1280 schema:
1281 type: string
1282 responses:
1283 '200':
1284 description: successful operation
1285 content:
1286 application/json:
1287 schema:
1288 type: array
1289 items:
1290 $ref: '#/components/schemas/Video'
1291servers:
1292 - url: 'https://peertube.cpy.re/api/v1'
1293 description: Live Test Server (live data - stable version)
1294 - url: 'https://peertube2.cpy.re/api/v1'
1295 description: Live Test Server (live data - bleeding edge version)
1296 - url: 'https://peertube3.cpy.re/api/v1'
1297 description: Live Test Server (live data - bleeding edge version)
1298components:
1299 parameters:
1300 start:
1301 name: start
1302 in: query
1303 required: false
1304 description: Offset
1305 schema:
1306 type: number
1307 count:
1308 name: count
1309 in: query
1310 required: false
1311 description: Number of items
1312 schema:
1313 type: number
1314 sort:
1315 name: sort
1316 in: query
1317 required: false
1318 description: Sort column (-createdAt for example)
1319 schema:
1320 type: string
1321 videosSort:
1322 name: sort
1323 in: query
1324 required: false
1325 description: Sort videos by criteria
1326 schema:
1327 type: string
1328 enum:
1329 - -name
1330 - -duration
1331 - -createdAt
1332 - -publishedAt
1333 - -views
1334 - -likes
1335 - -trending
1336 videosSearchSort:
1337 name: sort
1338 in: query
1339 required: false
1340 description: Sort videos by criteria
1341 schema:
1342 type: string
1343 enum:
1344 - -name
1345 - -duration
1346 - -createdAt
1347 - -publishedAt
1348 - -views
1349 - -likes
1350 - -match
1351 blacklistsSort:
1352 name: sort
1353 in: query
1354 required: false
1355 description: Sort blacklists by criteria
1356 schema:
1357 type: string
1358 enum:
1359 - -id
1360 - -name
1361 - -duration
1362 - -views
1363 - -likes
1364 - -dislikes
1365 - -uuid
1366 - -createdAt
1367 usersSort:
1368 name: sort
1369 in: query
1370 required: false
1371 description: Sort users by criteria
1372 schema:
1373 type: string
1374 enum:
1375 - -id
1376 - -username
1377 - -createdAt
1378 abusesSort:
1379 name: sort
1380 in: query
1381 required: false
1382 description: Sort abuses by criteria
1383 schema:
1384 type: string
1385 enum:
1386 - -id
1387 - -createdAt
1388 - -state
1389 name:
1390 name: name
1391 in: path
1392 required: true
1393 description: >-
1394 The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1395 example)
1396 schema:
1397 type: string
1398 id:
1399 name: id
1400 in: path
1401 required: true
1402 description: The user id
1403 schema:
1404 type: number
1405 id2:
1406 name: id
1407 in: path
1408 required: true
1409 description: The video id or uuid
1410 schema:
1411 type: string
1412 id3:
1413 name: id
1414 in: path
1415 required: true
1416 description: The video channel id or uuid
1417 schema:
1418 type: string
1419 commentId:
1420 name: threadId
1421 in: path
1422 required: true
1423 description: The comment id
1424 schema:
1425 type: number
1426 categoryOneOf:
1427 name: categoryOneOf
1428 in: query
1429 required: false
1430 description: category id of the video
1431 schema:
1432 oneOf:
1433 - type: number
1434 - type: array
1435 items:
1436 type: number
1437 tagsOneOf:
1438 name: tagsOneOf
1439 in: query
1440 required: false
1441 description: tag(s) of the video
1442 schema:
1443 oneOf:
1444 - type: string
1445 - type: array
1446 items:
1447 type: string
1448 tagsAllOf:
1449 name: tagsAllOf
1450 in: query
1451 required: false
1452 description: tag(s) of the video, where all should be present in the video
1453 schema:
1454 oneOf:
1455 - type: string
1456 - type: array
1457 items:
1458 type: string
1459 languageOneOf:
1460 name: languageOneOf
1461 in: query
1462 required: false
1463 description: language id of the video
1464 schema:
1465 oneOf:
1466 - type: number
1467 - type: array
1468 items:
1469 type: number
1470 licenceOneOf:
1471 name: licenceOneOf
1472 in: query
1473 required: false
1474 description: licence id of the video
1475 schema:
1476 oneOf:
1477 - type: number
1478 - type: array
1479 items:
1480 type: number
1481 nsfw:
1482 name: nsfw
1483 in: query
1484 required: false
1485 description: whether to include nsfw videos, if any
1486 schema:
1487 type: string
1488 enum:
1489 - 'true'
1490 - 'false'
1491 filter:
1492 name: filter
1493 in: query
1494 required: false
1495 description: >
1496 Special filters (local for instance) which might require special rights:
1497 * `local` - only videos local to the instance
1498 * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
1499 schema:
1500 type: string
1501 enum:
1502 - local
1503 - all-local
1504 requestBodies:
1505 VideoChannelInput:
1506 content:
1507 application/json:
1508 schema:
1509 $ref: '#/components/schemas/VideoChannelInput'
1510 securitySchemes:
1511 OAuth2:
1512 description: >
1513 In the header: *Authorization: Bearer <token\>*
1514
1515
1516 Authenticating via OAuth requires the following steps:
1517
1518
1519 - Have an account with sufficient authorization levels
1520
1521 - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
1522 Bearer Token
1523
1524 - Make Authenticated Requests
1525 type: oauth2
1526 flows:
1527 password:
1528 tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1529 scopes:
1530 admin: Admin scope
1531 moderator: Moderator scope
1532 user: User scope
1533 schemas:
1534 VideoConstantNumber:
1535 properties:
1536 id:
1537 type: number
1538 label:
1539 type: string
1540 VideoConstantString:
1541 properties:
1542 id:
1543 type: string
1544 label:
1545 type: string
1546 VideoPrivacy:
1547 type: string
1548 enum:
1549 - Public
1550 - Unlisted
1551 - Private
1552 Video:
1553 properties:
1554 id:
1555 type: number
1556 uuid:
1557 type: string
1558 createdAt:
1559 type: string
1560 publishedAt:
1561 type: string
1562 updatedAt:
1563 type: string
1564 category:
1565 $ref: '#/components/schemas/VideoConstantNumber'
1566 licence:
1567 $ref: '#/components/schemas/VideoConstantNumber'
1568 language:
1569 $ref: '#/components/schemas/VideoConstantString'
1570 privacy:
1571 $ref: '#/components/schemas/VideoPrivacy'
1572 description:
1573 type: string
1574 duration:
1575 type: number
1576 isLocal:
1577 type: boolean
1578 name:
1579 type: string
1580 thumbnailPath:
1581 type: string
1582 previewPath:
1583 type: string
1584 embedPath:
1585 type: string
1586 views:
1587 type: number
1588 likes:
1589 type: number
1590 dislikes:
1591 type: number
1592 nsfw:
1593 type: boolean
1594 account:
1595 type: object
1596 properties:
1597 name:
1598 type: string
1599 displayName:
1600 type: string
1601 url:
1602 type: string
1603 host:
1604 type: string
1605 avatar:
1606 $ref: '#/components/schemas/Avatar'
1607 VideoAbuse:
1608 properties:
1609 id:
1610 type: number
1611 reason:
1612 type: string
1613 reporterAccount:
1614 $ref: '#/components/schemas/Account'
1615 video:
1616 type: object
1617 properties:
1618 id:
1619 type: number
1620 name:
1621 type: string
1622 uuid:
1623 type: string
1624 url:
1625 type: string
1626 createdAt:
1627 type: string
1628 VideoBlacklist:
1629 properties:
1630 id:
1631 type: number
1632 videoId:
1633 type: number
1634 createdAt:
1635 type: string
1636 updatedAt:
1637 type: string
1638 name:
1639 type: string
1640 uuid:
1641 type: string
1642 description:
1643 type: string
1644 duration:
1645 type: number
1646 views:
1647 type: number
1648 likes:
1649 type: number
1650 dislikes:
1651 type: number
1652 nsfw:
1653 type: boolean
1654 VideoChannel:
1655 properties:
1656 displayName:
1657 type: string
1658 description:
1659 type: string
1660 isLocal:
1661 type: boolean
1662 ownerAccount:
1663 type: object
1664 properties:
1665 id:
1666 type: number
1667 uuid:
1668 type: string
1669 VideoComment:
1670 properties:
1671 id:
1672 type: number
1673 url:
1674 type: string
1675 text:
1676 type: string
1677 threadId:
1678 type: number
1679 inReplyToCommentId:
1680 type: number
1681 videoId:
1682 type: number
1683 createdAt:
1684 type: string
1685 updatedAt:
1686 type: string
1687 totalReplies:
1688 type: number
1689 account:
1690 $ref: '#/components/schemas/Account'
1691 VideoCommentThreadTree:
1692 properties:
1693 comment:
1694 $ref: '#/components/schemas/VideoComment'
1695 children:
1696 type: array
1697 items:
1698 $ref: '#/components/schemas/VideoCommentThreadTree'
1699 Avatar:
1700 properties:
1701 path:
1702 type: string
1703 createdAt:
1704 type: string
1705 updatedAt:
1706 type: string
1707 Actor:
1708 properties:
1709 id:
1710 type: number
1711 uuid:
1712 type: string
1713 url:
1714 type: string
1715 name:
1716 type: string
1717 host:
1718 type: string
1719 followingCount:
1720 type: number
1721 followersCount:
1722 type: number
1723 createdAt:
1724 type: string
1725 updatedAt:
1726 type: string
1727 avatar:
1728 $ref: '#/components/schemas/Avatar'
1729 Account:
1730 allOf:
1731 - $ref: '#/components/schemas/Actor'
1732 - properties:
1733 displayName:
1734 type: string
1735 User:
1736 properties:
1737 id:
1738 type: number
1739 username:
1740 type: string
1741 email:
1742 type: string
1743 displayNSFW:
1744 type: boolean
1745 autoPlayVideo:
1746 type: boolean
1747 role:
1748 type: string
1749 enum:
1750 - User
1751 - Moderator
1752 - Administrator
1753 videoQuota:
1754 type: number
1755 createdAt:
1756 type: string
1757 account:
1758 $ref: '#/components/schemas/Account'
1759 videoChannels:
1760 type: array
1761 items:
1762 $ref: '#/components/schemas/VideoChannel'
1763 UserWatchingVideo:
1764 properties:
1765 currentTime:
1766 type: number
1767 ServerConfig:
1768 properties:
1769 signup:
1770 type: object
1771 properties:
1772 allowed:
1773 type: boolean
1774 transcoding:
1775 type: object
1776 properties:
1777 enabledResolutions:
1778 type: array
1779 items:
1780 type: number
1781 avatar:
1782 type: object
1783 properties:
1784 file:
1785 type: object
1786 properties:
1787 size:
1788 type: object
1789 properties:
1790 max:
1791 type: number
1792 extensions:
1793 type: array
1794 items:
1795 type: string
1796 video:
1797 type: object
1798 properties:
1799 file:
1800 type: object
1801 properties:
1802 extensions:
1803 type: array
1804 items:
1805 type: string
1806 Follow:
1807 properties:
1808 id:
1809 type: number
1810 follower:
1811 $ref: '#/components/schemas/Actor'
1812 following:
1813 $ref: '#/components/schemas/Actor'
1814 score:
1815 type: number
1816 state:
1817 type: string
1818 enum:
1819 - pending
1820 - accepted
1821 createdAt:
1822 type: string
1823 updatedAt:
1824 type: string
1825 Job:
1826 properties:
1827 id:
1828 type: number
1829 state:
1830 type: string
1831 enum:
1832 - pending
1833 - processing
1834 - error
1835 - success
1836 category:
1837 type: string
1838 enum:
1839 - transcoding
1840 - activitypub-http
1841 handlerName:
1842 type: string
1843 handlerInputData:
1844 type: string
1845 createdAt:
1846 type: string
1847 updatedAt:
1848 type: string
1849 AddUserResponse:
1850 properties:
1851 id:
1852 type: number
1853 uuid:
1854 type: string
1855 VideoUploadResponse:
1856 properties:
1857 video:
1858 type: object
1859 properties:
1860 id:
1861 type: number
1862 uuid:
1863 type: string
1864 CommentThreadResponse:
1865 properties:
1866 total:
1867 type: number
1868 data:
1869 type: array
1870 items:
1871 $ref: '#/components/schemas/VideoComment'
1872 CommentThreadPostResponse:
1873 properties:
1874 comment:
1875 $ref: '#/components/schemas/VideoComment'
1876 AddUser:
1877 properties:
1878 username:
1879 type: string
1880 description: 'The user username '
1881 password:
1882 type: string
1883 description: 'The user password '
1884 email:
1885 type: string
1886 description: 'The user email '
1887 videoQuota:
1888 type: string
1889 description: 'The user videoQuota '
1890 role:
1891 type: integer
1892 format: int32
1893 enum:
1894 - 0
1895 - 1
1896 - 2
1897 description: 'The user role '
1898 required:
1899 - username
1900 - password
1901 - email
1902 - videoQuota
1903 - role
1904 UpdateUser:
1905 properties:
1906 id:
1907 type: string
1908 description: 'The user id '
1909 email:
1910 type: string
1911 description: 'The updated email of the user '
1912 videoQuota:
1913 type: string
1914 description: 'The updated videoQuota of the user '
1915 role:
1916 type: string
1917 description: 'The updated role of the user '
1918 required:
1919 - id
1920 - email
1921 - videoQuota
1922 - role
1923 UpdateMe:
1924 properties:
1925 password:
1926 type: string
1927 description: 'Your new password '
1928 email:
1929 type: string
1930 description: 'Your new email '
1931 displayNSFW:
1932 type: string
1933 description: 'Your new displayNSFW '
1934 autoPlayVideo:
1935 type: string
1936 description: 'Your new autoPlayVideo '
1937 required:
1938 - password
1939 - email
1940 - displayNSFW
1941 - autoPlayVideo
1942 GetMeVideoRating:
1943 properties:
1944 id:
1945 type: string
1946 description: 'Id of the video '
1947 rating:
1948 type: number
1949 description: 'Rating of the video '
1950 required:
1951 - id
1952 - rating
1953 RegisterUser:
1954 properties:
1955 username:
1956 type: string
1957 description: 'The username of the user '
1958 password:
1959 type: string
1960 description: 'The password of the user '
1961 email:
1962 type: string
1963 description: 'The email of the user '
1964 required:
1965 - username
1966 - password
1967 - email
1968 VideoChannelInput:
1969 properties:
1970 name:
1971 type: string
1972 description:
1973 type: string
1974
ActivityPub-federated video streaming platform using P2P directly in your web browser