]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blob - support/doc/api/openapi.yaml
Add video caption created and deleted hooks
[github/Chocobozzz/PeerTube.git] / support / doc / api / openapi.yaml
1 openapi: 3.0.0
2 info:
3 title: PeerTube
4 version: 3.3.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 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
16 HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
17 [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
18 which generates a client SDK in the language of your choice - we generate some client SDKs automatically:
19
20 - [Python](https://framagit.org/framasoft/peertube/clients/python)
21 - [Go](https://framagit.org/framasoft/peertube/clients/go)
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
23
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using the PeerTube API.
26
27 # Authentication
28
29 When you sign up for an account on a PeerTube instance, you are given the possibility
30 to generate sessions on it, and authenticate there using an access token. Only __one
31 access token can currently be used at a time__.
32
33 ## Roles
34
35 Accounts are given permissions based on their role. There are three roles on
36 PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin-managing-users?id=roles) for a detail of their permissions.
37
38 # Errors
39
40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
42
43 ```
44 HTTP 1.1 404 Not Found
45 Content-Type: application/problem+json; charset=utf-8
46
47 {
48 "detail": "Video not found",
49 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
50 "status": 404,
51 "title": "Not Found",
52 "type": "about:blank"
53 }
54 ```
55
56 We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
57 but it is still optional. Types are used to disambiguate errors that bear the same status code
58 and are non-obvious:
59
60 ```
61 HTTP 1.1 403 Forbidden
62 Content-Type: application/problem+json; charset=utf-8
63
64 {
65 "detail": "Cannot get this video regarding follow constraints",
66 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
67 "status": 403,
68 "title": "Forbidden",
69 "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
70 }
71 ```
72
73 Here a 403 error could otherwise mean that the video is private or blocklisted.
74
75 ### Validation errors
76
77 Each parameter is evaluated on its own against a set of rules before the route validator
78 proceeds with potential testing involving parameter combinations. Errors coming from validation
79 errors appear earlier and benefit from a more detailed error description:
80
81 ```
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
84
85 {
86 "detail": "Incorrect request parameters: id",
87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
89 "invalid-params": {
90 "id": {
91 "location": "params",
92 "msg": "Invalid value",
93 "param": "id",
94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
95 }
96 },
97 "status": 400,
98 "title": "Bad Request",
99 "type": "about:blank"
100 }
101 ```
102
103 Where `id` is the name of the field concerned by the error, within the route definition.
104 `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
105 `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
106 is about.
107
108 ### Deprecated error fields
109
110 Some fields could be included with previous versions. They are still included but their use is deprecated:
111 - `error`: superseded by `detail`
112 - `code`: superseded by `type` (which is now an URI)
113
114 # Rate limits
115
116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
117
118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
119 |------------------------------|---------------|--------------|
120 | `/*` | 50 | 10 seconds |
121 | `POST /users/token` | 15 | 5 minutes |
122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
124
125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
126 limit is announced by a `429 Too Many Requests` status code.
127
128 You can get details about the current state of your rate limit by reading the
129 following headers:
130
131 | Header | Description |
132 |-------------------------|------------------------------------------------------------|
133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
136 | `Retry-After` | Seconds to delay after the first `429` is received |
137
138 # CORS
139
140 This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
141 allowing cross-domain communication from the browser for some routes:
142
143 | Endpoint |
144 |------------------------- ---|
145 | `/api/*` |
146 | `/download/*` |
147 | `/lazy-static/*` |
148 | `/live/segments-sha256/*` |
149 | `/.well-known/webfinger` |
150
151 In addition, all routes serving ActivityPub are CORS-enabled for all origins.
152 externalDocs:
153 url: https://docs.joinpeertube.org/api-rest-reference.html
154 tags:
155 - name: Register
156 description: |
157 As a visitor, you can use this API to open an account (if registrations are open on
158 that PeerTube instance). As an admin, you should use the dedicated [User creation
159 API](#operation/addUser) instead.
160 - name: Session
161 x-displayName: Login/Logout
162 description: |
163 Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
164 - name: Accounts
165 description: >
166 Accounts encompass remote accounts discovered across the federation,
167 and correspond to the main Actor, along with video channels a user can create, which
168 are also Actors.
169
170 When a comment is posted, it is done with your Account's Actor.
171 - name: Users
172 description: >
173 Using some features of PeerTube require authentication, for which User
174 provide different levels of permission as well as associated user
175 information. Each user has a corresponding local Account for federation.
176 - name: My User
177 description: >
178 Operations related to your own User, when logged-in.
179 - name: My Subscriptions
180 description: >
181 Operations related to your subscriptions to video channels, their
182 new videos, and how to keep up to date with their latest publications!
183 - name: My History
184 description: >
185 Operations related to your watch history.
186 - name: My Notifications
187 description: >
188 Notifications following new videos, follows or reports. They allow you
189 to keep track of the interactions and overall important information that
190 concerns you. You MAY set per-notification type delivery preference, to
191 receive the info either by mail, by in-browser notification or both.
192 - name: Config
193 description: >
194 Each server exposes public information regarding supported videos and
195 options.
196 - name: Job
197 description: >
198 Jobs are long-running tasks enqueued and processed by the instance
199 itself. No additional worker registration is currently available.
200 - name: Instance Follows
201 description: >
202 Managing servers which the instance interacts with is crucial to the
203 concept of federation in PeerTube and external video indexation. The PeerTube
204 server then deals with inter-server ActivityPub operations and propagates
205 information across its social graph by posting activities to actors' inbox
206 endpoints.
207 externalDocs:
208 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-follows
209 - name: Instance Redundancy
210 description: >
211 Redundancy is part of the inter-server solidarity that PeerTube fosters.
212 Manage the list of instances you wish to help by seeding their videos according
213 to the policy of video selection of your choice. Note that you have a similar functionality
214 to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
215 externalDocs:
216 url: https://docs.joinpeertube.org/admin-following-instances?id=instances-redundancy
217 - name: Plugins
218 description: >
219 Managing plugins installed from a local path or from NPM, or search for new ones.
220 externalDocs:
221 url: https://docs.joinpeertube.org/api-plugins
222 - name: Abuses
223 description: |
224 Abuses deal with reports of local or remote videos/comments/accounts alike.
225 - name: Video
226 description: |
227 Operations dealing with listing, uploading, fetching or modifying videos.
228 - name: Video Upload
229 description: |
230 Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.
231
232 ### Upload
233
234 - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
235 - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks
236
237 You can upload videos more reliably by using the resumable variant. Its protocol lets
238 you resume an upload operation after a network interruption or other transmission failure,
239 saving time and bandwidth in the event of network failures.
240
241 Favor using resumable uploads in any of the following cases:
242 - You are transferring large files
243 - The likelihood of a network interruption is high
244 - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
245 such as a mobile device
246
247 ### Import
248
249 - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
250 - _magnet_-based: where the URI resolves to a BitTorrent ressource containing a single supported video file
251 - _torrent_-based: where the metainfo file resolves to a BitTorrent ressource containing a single supported video file
252
253 The import function is practical when the desired video/audio is available online. It makes PeerTube
254 download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
255 - name: Video Captions
256 description: Operations dealing with listing, adding and removing closed captions of a video.
257 - name: Video Channels
258 description: Operations dealing with the creation, modification and listing of videos within a channel.
259 - name: Video Comments
260 description: >
261 Operations dealing with comments to a video. Comments are organized in threads: adding a
262 comment in response to the video starts a thread, adding a reply to a comment adds it to
263 its root comment thread.
264 - name: Video Blocks
265 description: Operations dealing with blocking videos (removing them from view and preventing interactions).
266 - name: Video Rates
267 description: Like/dislike a video.
268 - name: Video Playlists
269 description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
270 - name: Video Files
271 description: Operations on video files
272 - name: Video Transcoding
273 description: Video transcoding related operations
274 - name: Feeds
275 description: Server syndication feeds
276 - name: Search
277 description: |
278 The search helps to find _videos_ or _channels_ from within the instance and beyond.
279 Videos from other instances federated by the instance (that is, instances
280 followed by the instance) can be found via keywords and other criteria of
281 the advanced search.
282
283 Administrators can also enable the use of a remote search system, indexing
284 videos and channels not could be not federated by the instance.
285 - name: Homepage
286 description: Get and update the custom homepage
287 - name: Video Mirroring
288 description: |
289 PeerTube instances can mirror videos from one another, and help distribute some videos.
290
291 For importing videos as your own, refer to [video imports](#operation/importVideo).
292 x-tagGroups:
293 - name: Auth
294 tags:
295 - Register
296 - Session
297 - name: Accounts
298 tags:
299 - Accounts
300 - Users
301 - My User
302 - My Subscriptions
303 - My Notifications
304 - My History
305 - name: Videos
306 tags:
307 - Video
308 - Video Upload
309 - Video Captions
310 - Video Channels
311 - Video Comments
312 - Video Rates
313 - Video Playlists
314 - Video Ownership Change
315 - Video Mirroring
316 - Video Files
317 - Video Transcoding
318 - Live Videos
319 - Feeds
320 - name: Search
321 tags:
322 - Search
323 - name: Custom pages
324 tags:
325 - Homepage
326 - name: Moderation
327 tags:
328 - Abuses
329 - Video Blocks
330 - Account Blocks
331 - Server Blocks
332 - name: Instance Configuration
333 tags:
334 - Config
335 - Instance Follows
336 - Instance Redundancy
337 - Plugins
338 - name: Jobs
339 tags:
340 - Job
341 paths:
342 '/accounts/{name}':
343 get:
344 tags:
345 - Accounts
346 summary: Get an account
347 operationId: getAccount
348 parameters:
349 - $ref: '#/components/parameters/name'
350 responses:
351 '200':
352 description: successful operation
353 content:
354 application/json:
355 schema:
356 $ref: '#/components/schemas/Account'
357 '404':
358 description: account not found
359
360 '/accounts/{name}/videos':
361 get:
362 tags:
363 - Accounts
364 - Video
365 summary: 'List videos of an account'
366 operationId: getAccountVideos
367 parameters:
368 - $ref: '#/components/parameters/name'
369 - $ref: '#/components/parameters/categoryOneOf'
370 - $ref: '#/components/parameters/isLive'
371 - $ref: '#/components/parameters/tagsOneOf'
372 - $ref: '#/components/parameters/tagsAllOf'
373 - $ref: '#/components/parameters/licenceOneOf'
374 - $ref: '#/components/parameters/languageOneOf'
375 - $ref: '#/components/parameters/nsfw'
376 - $ref: '#/components/parameters/isLocal'
377 - $ref: '#/components/parameters/include'
378 - $ref: '#/components/parameters/privacyOneOf'
379 - $ref: '#/components/parameters/hasHLSFiles'
380 - $ref: '#/components/parameters/hasWebtorrentFiles'
381 - $ref: '#/components/parameters/skipCount'
382 - $ref: '#/components/parameters/start'
383 - $ref: '#/components/parameters/count'
384 - $ref: '#/components/parameters/videosSort'
385 responses:
386 '200':
387 description: successful operation
388 content:
389 application/json:
390 schema:
391 $ref: '#/components/schemas/VideoListResponse'
392 x-codeSamples:
393 - lang: JavaScript
394 source: |
395 fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
396 .then(function(response) {
397 return response.json()
398 }).then(function(data) {
399 console.log(data)
400 })
401 - lang: Shell
402 source: |
403 ## DEPENDENCIES: jq
404 curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
405 - lang: Ruby
406 source: |
407 require 'net/http'
408 require 'json'
409
410 uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
411
412 http = Net::HTTP.new(uri.host, uri.port)
413 http.use_ssl = true
414
415 response = http.get(uri.request_uri)
416
417 puts JSON.parse(response.read_body)
418 - lang: Python
419 source: |
420 import requests
421
422 r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
423 json = r.json()
424
425 print(json)
426
427 '/accounts/{name}/followers':
428 get:
429 tags:
430 - Accounts
431 summary: 'List followers of an account'
432 security:
433 - OAuth2: []
434 operationId: getAccountFollowers
435 parameters:
436 - $ref: '#/components/parameters/name'
437 - $ref: '#/components/parameters/start'
438 - $ref: '#/components/parameters/count'
439 - $ref: '#/components/parameters/followersSort'
440 - $ref: '#/components/parameters/search'
441 responses:
442 '200':
443 description: successful operation
444 content:
445 application/json:
446 schema:
447 type: object
448 properties:
449 total:
450 type: integer
451 example: 1
452 data:
453 type: array
454 items:
455 $ref: '#/components/schemas/Follow'
456
457 /accounts:
458 get:
459 tags:
460 - Accounts
461 summary: List accounts
462 operationId: getAccounts
463 parameters:
464 - $ref: '#/components/parameters/start'
465 - $ref: '#/components/parameters/count'
466 - $ref: '#/components/parameters/sort'
467 responses:
468 '200':
469 description: successful operation
470 content:
471 'application/json':
472 schema:
473 type: array
474 items:
475 $ref: '#/components/schemas/Account'
476
477 /config:
478 get:
479 tags:
480 - Config
481 summary: Get instance public configuration
482 operationId: getConfig
483 responses:
484 '200':
485 description: successful operation
486 content:
487 application/json:
488 schema:
489 $ref: '#/components/schemas/ServerConfig'
490 examples:
491 nightly:
492 externalValue: https://peertube2.cpy.re/api/v1/config
493
494 /config/about:
495 get:
496 summary: Get instance "About" information
497 operationId: getAbout
498 tags:
499 - Config
500 responses:
501 '200':
502 description: successful operation
503 content:
504 application/json:
505 schema:
506 $ref: '#/components/schemas/ServerConfigAbout'
507 examples:
508 nightly:
509 externalValue: https://peertube2.cpy.re/api/v1/config/about
510
511 /config/custom:
512 get:
513 summary: Get instance runtime configuration
514 operationId: getCustomConfig
515 tags:
516 - Config
517 security:
518 - OAuth2:
519 - admin
520 responses:
521 '200':
522 description: successful operation
523 content:
524 application/json:
525 schema:
526 $ref: '#/components/schemas/ServerConfigCustom'
527 put:
528 summary: Set instance runtime configuration
529 operationId: putCustomConfig
530 tags:
531 - Config
532 security:
533 - OAuth2:
534 - admin
535 responses:
536 '200':
537 description: successful operation
538 '400':
539 x-summary: field inconsistencies
540 description: >
541 Arises when:
542 - the emailer is disabled and the instance is open to registrations
543 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
544 delete:
545 summary: Delete instance runtime configuration
546 operationId: delCustomConfig
547 tags:
548 - Config
549 security:
550 - OAuth2:
551 - admin
552 responses:
553 '200':
554 description: successful operation
555
556 /custom-pages/homepage/instance:
557 get:
558 summary: Get instance custom homepage
559 tags:
560 - Homepage
561 responses:
562 '404':
563 description: No homepage set
564 '200':
565 description: successful operation
566 content:
567 application/json:
568 schema:
569 $ref: '#/components/schemas/CustomHomepage'
570 put:
571 summary: Set instance custom homepage
572 tags:
573 - Homepage
574 security:
575 - OAuth2:
576 - admin
577 requestBody:
578 content:
579 application/json:
580 schema:
581 type: object
582 properties:
583 content:
584 type: string
585 description: content of the homepage, that will be injected in the client
586 responses:
587 '204':
588 description: successful operation
589
590 /jobs/{state}:
591 get:
592 summary: List instance jobs
593 operationId: getJobs
594 security:
595 - OAuth2:
596 - admin
597 tags:
598 - Job
599 parameters:
600 - name: state
601 in: path
602 required: true
603 description: The state of the job ('' for for no filter)
604 schema:
605 type: string
606 enum:
607 - ''
608 - active
609 - completed
610 - failed
611 - waiting
612 - delayed
613 - $ref: '#/components/parameters/jobType'
614 - $ref: '#/components/parameters/start'
615 - $ref: '#/components/parameters/count'
616 - $ref: '#/components/parameters/sort'
617 responses:
618 '200':
619 description: successful operation
620 content:
621 application/json:
622 schema:
623 type: object
624 properties:
625 total:
626 type: integer
627 example: 1
628 data:
629 type: array
630 maxItems: 100
631 items:
632 $ref: '#/components/schemas/Job'
633
634 /server/followers:
635 get:
636 tags:
637 - Instance Follows
638 summary: List instances following the server
639 parameters:
640 - $ref: '#/components/parameters/followState'
641 - $ref: '#/components/parameters/actorType'
642 - $ref: '#/components/parameters/start'
643 - $ref: '#/components/parameters/count'
644 - $ref: '#/components/parameters/sort'
645 responses:
646 '200':
647 description: successful operation
648 content:
649 application/json:
650 schema:
651 type: object
652 properties:
653 total:
654 type: integer
655 example: 1
656 data:
657 type: array
658 items:
659 $ref: '#/components/schemas/Follow'
660
661 '/server/followers/{nameWithHost}':
662 delete:
663 summary: Remove or reject a follower to your server
664 security:
665 - OAuth2:
666 - admin
667 tags:
668 - Instance Follows
669 parameters:
670 - name: nameWithHost
671 in: path
672 required: true
673 description: The remote actor handle to remove from your followers
674 schema:
675 type: string
676 format: email
677 responses:
678 '204':
679 description: successful operation
680 '404':
681 description: follower not found
682
683 '/server/followers/{nameWithHost}/reject':
684 post:
685 summary: Reject a pending follower to your server
686 security:
687 - OAuth2:
688 - admin
689 tags:
690 - Instance Follows
691 parameters:
692 - name: nameWithHost
693 in: path
694 required: true
695 description: The remote actor handle to remove from your followers
696 schema:
697 type: string
698 format: email
699 responses:
700 '204':
701 description: successful operation
702 '404':
703 description: follower not found
704
705 '/server/followers/{nameWithHost}/accept':
706 post:
707 summary: Accept a pending follower to your server
708 security:
709 - OAuth2:
710 - admin
711 tags:
712 - Instance Follows
713 parameters:
714 - name: nameWithHost
715 in: path
716 required: true
717 description: The remote actor handle to remove from your followers
718 schema:
719 type: string
720 format: email
721 responses:
722 '204':
723 description: successful operation
724 '404':
725 description: follower not found
726
727 /server/following:
728 get:
729 tags:
730 - Instance Follows
731 summary: List instances followed by the server
732 parameters:
733 - $ref: '#/components/parameters/followState'
734 - $ref: '#/components/parameters/actorType'
735 - $ref: '#/components/parameters/start'
736 - $ref: '#/components/parameters/count'
737 - $ref: '#/components/parameters/sort'
738 responses:
739 '200':
740 description: successful operation
741 content:
742 application/json:
743 schema:
744 type: object
745 properties:
746 total:
747 type: integer
748 example: 1
749 data:
750 type: array
751 items:
752 $ref: '#/components/schemas/Follow'
753 post:
754 security:
755 - OAuth2:
756 - admin
757 tags:
758 - Instance Follows
759 summary: Follow a list of actors (PeerTube instance, channel or account)
760 responses:
761 '204':
762 description: successful operation
763 '500':
764 description: cannot follow a non-HTTPS server
765 requestBody:
766 content:
767 application/json:
768 schema:
769 type: object
770 properties:
771 hosts:
772 type: array
773 items:
774 type: string
775 format: hostname
776 uniqueItems: true
777 handles:
778 type: array
779 items:
780 type: string
781 uniqueItems: true
782
783 '/server/following/{hostOrHandle}':
784 delete:
785 summary: Unfollow an actor (PeerTube instance, channel or account)
786 security:
787 - OAuth2:
788 - admin
789 tags:
790 - Instance Follows
791 parameters:
792 - name: hostOrHandle
793 in: path
794 required: true
795 description: The hostOrHandle to unfollow
796 schema:
797 type: string
798 responses:
799 '204':
800 description: successful operation
801 '404':
802 description: host or handle not found
803
804 /users:
805 post:
806 summary: Create a user
807 operationId: addUser
808 security:
809 - OAuth2:
810 - admin
811 tags:
812 - Users
813 responses:
814 '200':
815 description: user created
816 content:
817 application/json:
818 schema:
819 $ref: '#/components/schemas/AddUserResponse'
820 links:
821 # GET /users/{id}
822 GetUser:
823 operationId: getUser
824 parameters:
825 id: '$response.body#/user/id'
826 # PUT /users/{id}
827 PutUser:
828 operationId: putUser
829 parameters:
830 id: '$response.body#/user/id'
831 # DELETE /users/{id}
832 DelUser:
833 operationId: delUser
834 parameters:
835 id: '$response.body#/user/id'
836 '403':
837 description: insufficient authority to create an admin or moderator
838 requestBody:
839 content:
840 application/json:
841 schema:
842 $ref: '#/components/schemas/AddUser'
843 description: |
844 If the smtp server is configured, you can leave the password empty and an email will be sent
845 asking the user to set it first.
846 required: true
847 get:
848 summary: List users
849 operationId: getUsers
850 security:
851 - OAuth2:
852 - admin
853 tags:
854 - Users
855 parameters:
856 - $ref: '#/components/parameters/usersSearch'
857 - $ref: '#/components/parameters/usersBlocked'
858 - $ref: '#/components/parameters/start'
859 - $ref: '#/components/parameters/count'
860 - $ref: '#/components/parameters/usersSort'
861 responses:
862 '200':
863 description: successful operation
864 content:
865 application/json:
866 schema:
867 type: array
868 items:
869 $ref: '#/components/schemas/User'
870
871 '/users/{id}':
872 parameters:
873 - $ref: '#/components/parameters/id'
874 delete:
875 summary: Delete a user
876 security:
877 - OAuth2:
878 - admin
879 tags:
880 - Users
881 operationId: delUser
882 responses:
883 '204':
884 description: successful operation
885 get:
886 summary: Get a user
887 security:
888 - OAuth2: []
889 tags:
890 - Users
891 operationId: getUser
892 parameters:
893 - name: withStats
894 in: query
895 description: include statistics about the user (only available as a moderator/admin)
896 schema:
897 type: boolean
898 responses:
899 '200':
900 x-summary: successful operation
901 description: |
902 As an admin/moderator, you can request a response augmented with statistics about the user's
903 moderation relations and videos usage, by using the `withStats` parameter.
904 content:
905 application/json:
906 schema:
907 oneOf:
908 - $ref: '#/components/schemas/User'
909 - $ref: '#/components/schemas/UserWithStats'
910 put:
911 summary: Update a user
912 security:
913 - OAuth2: []
914 tags:
915 - Users
916 operationId: putUser
917 responses:
918 '204':
919 description: successful operation
920 requestBody:
921 content:
922 application/json:
923 schema:
924 $ref: '#/components/schemas/UpdateUser'
925 required: true
926
927 /oauth-clients/local:
928 get:
929 summary: Login prerequisite
930 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
931 operationId: getOAuthClient
932 tags:
933 - Session
934 responses:
935 '200':
936 description: successful operation
937 content:
938 application/json:
939 schema:
940 $ref: '#/components/schemas/OAuthClient'
941 links:
942 UseOAuthClientToLogin:
943 operationId: getOAuthToken
944 parameters:
945 client_id: '$response.body#/client_id'
946 client_secret: '$response.body#/client_secret'
947 x-codeSamples:
948 - lang: Shell
949 source: |
950 API="https://peertube2.cpy.re/api/v1"
951
952 ## AUTH
953 curl -s "$API/oauth-clients/local"
954
955 /users/token:
956 post:
957 summary: Login
958 operationId: getOAuthToken
959 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
960 tags:
961 - Session
962 requestBody:
963 content:
964 application/x-www-form-urlencoded:
965 schema:
966 oneOf:
967 - $ref: '#/components/schemas/OAuthToken-password'
968 - $ref: '#/components/schemas/OAuthToken-refresh_token'
969 discriminator:
970 propertyName: grant_type
971 mapping:
972 password: '#/components/schemas/OAuthToken-password'
973 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
974 responses:
975 '200':
976 description: successful operation
977 content:
978 application/json:
979 schema:
980 type: object
981 properties:
982 token_type:
983 type: string
984 example: Bearer
985 access_token:
986 type: string
987 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
988 description: valid for 1 day
989 refresh_token:
990 type: string
991 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
992 description: valid for 2 weeks
993 expires_in:
994 type: integer
995 minimum: 0
996 example: 14399
997 refresh_token_expires_in:
998 type: integer
999 minimum: 0
1000 example: 1209600
1001 '400':
1002 x-summary: client or credentials are invalid
1003 description: |
1004 Disambiguate via `type`:
1005 - `invalid_client` for an unmatched `client_id`
1006 - `invalid_grant` for unmatched credentials
1007 '401':
1008 x-summary: token expired
1009 description: |
1010 Disambiguate via `type`:
1011 - default value for a regular authentication failure
1012 - `invalid_token` for an expired token
1013 x-codeSamples:
1014 - lang: Shell
1015 source: |
1016 ## DEPENDENCIES: jq
1017 API="https://peertube2.cpy.re/api/v1"
1018 USERNAME="<your_username>"
1019 PASSWORD="<your_password>"
1020
1021 ## AUTH
1022 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1023 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1024 curl -s "$API/users/token" \
1025 --data client_id="$client_id" \
1026 --data client_secret="$client_secret" \
1027 --data grant_type=password \
1028 --data username="$USERNAME" \
1029 --data password="$PASSWORD" \
1030 | jq -r ".access_token"
1031
1032 /users/revoke-token:
1033 post:
1034 summary: Logout
1035 description: Revokes your access token and its associated refresh token, destroying your current session.
1036 operationId: revokeOAuthToken
1037 tags:
1038 - Session
1039 security:
1040 - OAuth2: []
1041 responses:
1042 '200':
1043 description: successful operation
1044
1045 /users/register:
1046 post:
1047 summary: Register a user
1048 operationId: registerUser
1049 tags:
1050 - Users
1051 - Register
1052 responses:
1053 '204':
1054 description: successful operation
1055 requestBody:
1056 content:
1057 application/json:
1058 schema:
1059 $ref: '#/components/schemas/RegisterUser'
1060 required: true
1061
1062 /users/{id}/verify-email:
1063 post:
1064 summary: Verify a user
1065 operationId: verifyUser
1066 description: |
1067 Following a user registration, the new user will receive an email asking to click a link
1068 containing a secret.
1069 tags:
1070 - Users
1071 - Register
1072 parameters:
1073 - $ref: '#/components/parameters/id'
1074 requestBody:
1075 content:
1076 application/json:
1077 schema:
1078 type: object
1079 properties:
1080 verificationString:
1081 type: string
1082 format: url
1083 isPendingEmail:
1084 type: boolean
1085 required:
1086 - verificationString
1087 responses:
1088 '204':
1089 description: successful operation
1090 '403':
1091 description: invalid verification string
1092 '404':
1093 description: user not found
1094
1095 /users/ask-send-verify-email:
1096 post:
1097 summary: Resend user verification link
1098 operationId: resendEmailToVerifyUser
1099 tags:
1100 - Users
1101 - Register
1102 responses:
1103 '204':
1104 description: successful operation
1105
1106 /users/me:
1107 get:
1108 summary: Get my user information
1109 operationId: getUserInfo
1110 security:
1111 - OAuth2:
1112 - user
1113 tags:
1114 - My User
1115 responses:
1116 '200':
1117 description: successful operation
1118 content:
1119 application/json:
1120 schema:
1121 type: array
1122 items:
1123 $ref: '#/components/schemas/User'
1124 put:
1125 summary: Update my user information
1126 operationId: putUserInfo
1127 security:
1128 - OAuth2:
1129 - user
1130 tags:
1131 - My User
1132 responses:
1133 '204':
1134 description: successful operation
1135 requestBody:
1136 content:
1137 application/json:
1138 schema:
1139 $ref: '#/components/schemas/UpdateMe'
1140 required: true
1141
1142 /users/me/videos/imports:
1143 get:
1144 summary: Get video imports of my user
1145 security:
1146 - OAuth2:
1147 - user
1148 tags:
1149 - Videos
1150 - My User
1151 parameters:
1152 - $ref: '#/components/parameters/start'
1153 - $ref: '#/components/parameters/count'
1154 - $ref: '#/components/parameters/sort'
1155 responses:
1156 '200':
1157 description: successful operation
1158 content:
1159 application/json:
1160 schema:
1161 $ref: '#/components/schemas/VideoImportsList'
1162
1163 /users/me/video-quota-used:
1164 get:
1165 summary: Get my user used quota
1166 security:
1167 - OAuth2:
1168 - user
1169 tags:
1170 - My User
1171 responses:
1172 '200':
1173 description: successful operation
1174 content:
1175 application/json:
1176 schema:
1177 type: object
1178 properties:
1179 videoQuotaUsed:
1180 type: number
1181 description: The user video quota used so far in bytes
1182 example: 16810141515
1183 videoQuotaUsedDaily:
1184 type: number
1185 description: The user video quota used today in bytes
1186 example: 1681014151
1187
1188 '/users/me/videos/{videoId}/rating':
1189 get:
1190 summary: Get rate of my user for a video
1191 security:
1192 - OAuth2: []
1193 tags:
1194 - My User
1195 - Video Rates
1196 parameters:
1197 - name: videoId
1198 in: path
1199 required: true
1200 description: The video id
1201 schema:
1202 $ref: '#/components/schemas/Video/properties/id'
1203 responses:
1204 '200':
1205 description: successful operation
1206 content:
1207 application/json:
1208 schema:
1209 $ref: '#/components/schemas/GetMeVideoRating'
1210
1211 /users/me/videos:
1212 get:
1213 summary: Get videos of my user
1214 security:
1215 - OAuth2:
1216 - user
1217 tags:
1218 - My User
1219 - Videos
1220 parameters:
1221 - $ref: '#/components/parameters/start'
1222 - $ref: '#/components/parameters/count'
1223 - $ref: '#/components/parameters/sort'
1224 responses:
1225 '200':
1226 description: successful operation
1227 content:
1228 application/json:
1229 schema:
1230 $ref: '#/components/schemas/VideoListResponse'
1231
1232 /users/me/subscriptions:
1233 get:
1234 summary: Get my user subscriptions
1235 security:
1236 - OAuth2:
1237 - user
1238 tags:
1239 - My Subscriptions
1240 parameters:
1241 - $ref: '#/components/parameters/start'
1242 - $ref: '#/components/parameters/count'
1243 - $ref: '#/components/parameters/sort'
1244 responses:
1245 '200':
1246 description: successful operation
1247 content:
1248 application/json:
1249 schema:
1250 $ref: '#/components/schemas/VideoChannelList'
1251 post:
1252 tags:
1253 - My Subscriptions
1254 summary: Add subscription to my user
1255 security:
1256 - OAuth2:
1257 - user
1258 requestBody:
1259 content:
1260 application/json:
1261 schema:
1262 type: object
1263 properties:
1264 uri:
1265 type: string
1266 format: uri
1267 description: uri of the video channels to subscribe to
1268 required:
1269 - uri
1270 examples:
1271 default:
1272 value:
1273 uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
1274 responses:
1275 '200':
1276 description: successful operation
1277
1278 /users/me/subscriptions/exist:
1279 get:
1280 summary: Get if subscriptions exist for my user
1281 security:
1282 - OAuth2:
1283 - user
1284 tags:
1285 - My Subscriptions
1286 parameters:
1287 - $ref: '#/components/parameters/subscriptionsUris'
1288 responses:
1289 '200':
1290 description: successful operation
1291 content:
1292 application/json:
1293 schema:
1294 type: object
1295
1296 /users/me/subscriptions/videos:
1297 get:
1298 summary: List videos of subscriptions of my user
1299 security:
1300 - OAuth2:
1301 - user
1302 tags:
1303 - My Subscriptions
1304 - Videos
1305 parameters:
1306 - $ref: '#/components/parameters/categoryOneOf'
1307 - $ref: '#/components/parameters/isLive'
1308 - $ref: '#/components/parameters/tagsOneOf'
1309 - $ref: '#/components/parameters/tagsAllOf'
1310 - $ref: '#/components/parameters/licenceOneOf'
1311 - $ref: '#/components/parameters/languageOneOf'
1312 - $ref: '#/components/parameters/nsfw'
1313 - $ref: '#/components/parameters/isLocal'
1314 - $ref: '#/components/parameters/include'
1315 - $ref: '#/components/parameters/privacyOneOf'
1316 - $ref: '#/components/parameters/hasHLSFiles'
1317 - $ref: '#/components/parameters/hasWebtorrentFiles'
1318 - $ref: '#/components/parameters/skipCount'
1319 - $ref: '#/components/parameters/start'
1320 - $ref: '#/components/parameters/count'
1321 - $ref: '#/components/parameters/videosSort'
1322 responses:
1323 '200':
1324 description: successful operation
1325 content:
1326 application/json:
1327 schema:
1328 $ref: '#/components/schemas/VideoListResponse'
1329
1330 '/users/me/subscriptions/{subscriptionHandle}':
1331 get:
1332 summary: Get subscription of my user
1333 security:
1334 - OAuth2:
1335 - user
1336 tags:
1337 - My Subscriptions
1338 parameters:
1339 - $ref: '#/components/parameters/subscriptionHandle'
1340 responses:
1341 '200':
1342 description: successful operation
1343 content:
1344 application/json:
1345 schema:
1346 $ref: '#/components/schemas/VideoChannel'
1347 delete:
1348 summary: Delete subscription of my user
1349 security:
1350 - OAuth2:
1351 - user
1352 tags:
1353 - My Subscriptions
1354 parameters:
1355 - $ref: '#/components/parameters/subscriptionHandle'
1356 responses:
1357 '200':
1358 description: successful operation
1359
1360 /users/me/notifications:
1361 get:
1362 summary: List my notifications
1363 security:
1364 - OAuth2: []
1365 tags:
1366 - My Notifications
1367 parameters:
1368 - name: unread
1369 in: query
1370 description: only list unread notifications
1371 schema:
1372 type: boolean
1373 - $ref: '#/components/parameters/start'
1374 - $ref: '#/components/parameters/count'
1375 - $ref: '#/components/parameters/sort'
1376 responses:
1377 '200':
1378 description: successful operation
1379 content:
1380 application/json:
1381 schema:
1382 $ref: '#/components/schemas/NotificationListResponse'
1383
1384 /users/me/notifications/read:
1385 post:
1386 summary: Mark notifications as read by their id
1387 security:
1388 - OAuth2: []
1389 tags:
1390 - My Notifications
1391 requestBody:
1392 content:
1393 application/json:
1394 schema:
1395 type: object
1396 properties:
1397 ids:
1398 type: array
1399 description: ids of the notifications to mark as read
1400 items:
1401 type: integer
1402 required:
1403 - ids
1404 responses:
1405 '204':
1406 description: successful operation
1407
1408 /users/me/notifications/read-all:
1409 post:
1410 summary: Mark all my notification as read
1411 security:
1412 - OAuth2: []
1413 tags:
1414 - My Notifications
1415 responses:
1416 '204':
1417 description: successful operation
1418
1419 /users/me/notification-settings:
1420 put:
1421 summary: Update my notification settings
1422 security:
1423 - OAuth2: []
1424 tags:
1425 - My Notifications
1426 requestBody:
1427 content:
1428 application/json:
1429 schema:
1430 type: object
1431 properties:
1432 newVideoFromSubscription:
1433 $ref: '#/components/schemas/NotificationSettingValue'
1434 newCommentOnMyVideo:
1435 $ref: '#/components/schemas/NotificationSettingValue'
1436 abuseAsModerator:
1437 $ref: '#/components/schemas/NotificationSettingValue'
1438 videoAutoBlacklistAsModerator:
1439 $ref: '#/components/schemas/NotificationSettingValue'
1440 blacklistOnMyVideo:
1441 $ref: '#/components/schemas/NotificationSettingValue'
1442 myVideoPublished:
1443 $ref: '#/components/schemas/NotificationSettingValue'
1444 myVideoImportFinished:
1445 $ref: '#/components/schemas/NotificationSettingValue'
1446 newFollow:
1447 $ref: '#/components/schemas/NotificationSettingValue'
1448 newUserRegistration:
1449 $ref: '#/components/schemas/NotificationSettingValue'
1450 commentMention:
1451 $ref: '#/components/schemas/NotificationSettingValue'
1452 newInstanceFollower:
1453 $ref: '#/components/schemas/NotificationSettingValue'
1454 autoInstanceFollowing:
1455 $ref: '#/components/schemas/NotificationSettingValue'
1456 responses:
1457 '204':
1458 description: successful operation
1459
1460 /users/me/history/videos:
1461 get:
1462 summary: List watched videos history
1463 security:
1464 - OAuth2: []
1465 tags:
1466 - My History
1467 parameters:
1468 - $ref: '#/components/parameters/start'
1469 - $ref: '#/components/parameters/count'
1470 - $ref: '#/components/parameters/search'
1471 responses:
1472 '200':
1473 description: successful operation
1474 content:
1475 application/json:
1476 schema:
1477 $ref: '#/components/schemas/VideoListResponse'
1478
1479 /users/me/history/videos/remove:
1480 post:
1481 summary: Clear video history
1482 security:
1483 - OAuth2: []
1484 tags:
1485 - My History
1486 requestBody:
1487 content:
1488 multipart/form-data:
1489 schema:
1490 type: object
1491 properties:
1492 beforeDate:
1493 description: history before this date will be deleted
1494 type: string
1495 format: date-time
1496 responses:
1497 '204':
1498 description: successful operation
1499
1500 /users/me/avatar/pick:
1501 post:
1502 summary: Update my user avatar
1503 security:
1504 - OAuth2: []
1505 tags:
1506 - My User
1507 responses:
1508 '200':
1509 description: successful operation
1510 content:
1511 application/json:
1512 schema:
1513 type: object
1514 properties:
1515 avatar:
1516 $ref: '#/components/schemas/ActorImage'
1517 '413':
1518 description: image file too large
1519 headers:
1520 X-File-Maximum-Size:
1521 schema:
1522 type: string
1523 format: Nginx size
1524 description: Maximum file size for the avatar
1525 requestBody:
1526 content:
1527 multipart/form-data:
1528 schema:
1529 type: object
1530 properties:
1531 avatarfile:
1532 description: The file to upload
1533 type: string
1534 format: binary
1535 encoding:
1536 avatarfile:
1537 contentType: image/png, image/jpeg
1538
1539 /users/me/avatar:
1540 delete:
1541 summary: Delete my avatar
1542 security:
1543 - OAuth2: []
1544 tags:
1545 - My User
1546 responses:
1547 '204':
1548 description: successful operation
1549
1550 /videos/ownership:
1551 get:
1552 summary: List video ownership changes
1553 tags:
1554 - Video Ownership Change
1555 security:
1556 - OAuth2: []
1557 responses:
1558 '200':
1559 description: successful operation
1560
1561 '/videos/ownership/{id}/accept':
1562 post:
1563 summary: Accept ownership change request
1564 tags:
1565 - Video Ownership Change
1566 security:
1567 - OAuth2: []
1568 parameters:
1569 - $ref: '#/components/parameters/idOrUUID'
1570 responses:
1571 '204':
1572 description: successful operation
1573 '403':
1574 description: cannot terminate an ownership change of another user
1575 '404':
1576 description: video owneship change not found
1577
1578 '/videos/ownership/{id}/refuse':
1579 post:
1580 summary: Refuse ownership change request
1581 tags:
1582 - Video Ownership Change
1583 security:
1584 - OAuth2: []
1585 parameters:
1586 - $ref: '#/components/parameters/idOrUUID'
1587 responses:
1588 '204':
1589 description: successful operation
1590 '403':
1591 description: cannot terminate an ownership change of another user
1592 '404':
1593 description: video owneship change not found
1594
1595 '/videos/{id}/give-ownership':
1596 post:
1597 summary: Request ownership change
1598 tags:
1599 - Video Ownership Change
1600 security:
1601 - OAuth2: []
1602 parameters:
1603 - $ref: '#/components/parameters/idOrUUID'
1604 requestBody:
1605 required: true
1606 content:
1607 application/x-www-form-urlencoded:
1608 schema:
1609 type: object
1610 properties:
1611 username:
1612 type: string
1613 required:
1614 - username
1615 responses:
1616 '204':
1617 description: successful operation
1618 '400':
1619 description: changing video ownership to a remote account is not supported yet
1620 '404':
1621 description: video not found
1622
1623 /videos:
1624 get:
1625 summary: List videos
1626 operationId: getVideos
1627 tags:
1628 - Video
1629 parameters:
1630 - $ref: '#/components/parameters/categoryOneOf'
1631 - $ref: '#/components/parameters/isLive'
1632 - $ref: '#/components/parameters/tagsOneOf'
1633 - $ref: '#/components/parameters/tagsAllOf'
1634 - $ref: '#/components/parameters/licenceOneOf'
1635 - $ref: '#/components/parameters/languageOneOf'
1636 - $ref: '#/components/parameters/nsfw'
1637 - $ref: '#/components/parameters/isLocal'
1638 - $ref: '#/components/parameters/include'
1639 - $ref: '#/components/parameters/privacyOneOf'
1640 - $ref: '#/components/parameters/hasHLSFiles'
1641 - $ref: '#/components/parameters/hasWebtorrentFiles'
1642 - $ref: '#/components/parameters/skipCount'
1643 - $ref: '#/components/parameters/start'
1644 - $ref: '#/components/parameters/count'
1645 - $ref: '#/components/parameters/videosSort'
1646 responses:
1647 '200':
1648 description: successful operation
1649 content:
1650 application/json:
1651 schema:
1652 $ref: '#/components/schemas/VideoListResponse'
1653
1654 /videos/categories:
1655 get:
1656 summary: List available video categories
1657 operationId: getCategories
1658 tags:
1659 - Video
1660 responses:
1661 '200':
1662 description: successful operation
1663 content:
1664 application/json:
1665 schema:
1666 type: array
1667 items:
1668 type: string
1669 examples:
1670 nightly:
1671 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1672
1673 /videos/licences:
1674 get:
1675 summary: List available video licences
1676 operationId: getLicences
1677 tags:
1678 - Video
1679 responses:
1680 '200':
1681 description: successful operation
1682 content:
1683 application/json:
1684 schema:
1685 type: array
1686 items:
1687 type: string
1688 examples:
1689 nightly:
1690 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1691
1692 /videos/languages:
1693 get:
1694 summary: List available video languages
1695 operationId: getLanguages
1696 tags:
1697 - Video
1698 responses:
1699 '200':
1700 description: successful operation
1701 content:
1702 application/json:
1703 schema:
1704 type: array
1705 items:
1706 type: string
1707 examples:
1708 nightly:
1709 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1710
1711 /videos/privacies:
1712 get:
1713 summary: List available video privacy policies
1714 operationId: getPrivacyPolicies
1715 tags:
1716 - Video
1717 responses:
1718 '200':
1719 description: successful operation
1720 content:
1721 application/json:
1722 schema:
1723 type: array
1724 items:
1725 type: string
1726 examples:
1727 nightly:
1728 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1729
1730 '/videos/{id}':
1731 put:
1732 summary: Update a video
1733 operationId: putVideo
1734 security:
1735 - OAuth2: []
1736 tags:
1737 - Video
1738 parameters:
1739 - $ref: '#/components/parameters/idOrUUID'
1740 responses:
1741 '204':
1742 description: successful operation
1743 requestBody:
1744 content:
1745 multipart/form-data:
1746 schema:
1747 type: object
1748 properties:
1749 thumbnailfile:
1750 description: Video thumbnail file
1751 type: string
1752 format: binary
1753 previewfile:
1754 description: Video preview file
1755 type: string
1756 format: binary
1757 category:
1758 $ref: '#/components/schemas/VideoCategorySet'
1759 licence:
1760 $ref: '#/components/schemas/VideoLicenceSet'
1761 language:
1762 $ref: '#/components/schemas/VideoLanguageSet'
1763 privacy:
1764 $ref: '#/components/schemas/VideoPrivacySet'
1765 description:
1766 description: Video description
1767 type: string
1768 waitTranscoding:
1769 description: Whether or not we wait transcoding before publish the video
1770 type: string
1771 support:
1772 description: A text tell the audience how to support the video creator
1773 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1774 type: string
1775 nsfw:
1776 description: Whether or not this video contains sensitive content
1777 type: boolean
1778 name:
1779 description: Video name
1780 type: string
1781 minLength: 3
1782 maxLength: 120
1783 tags:
1784 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1785 type: array
1786 minItems: 1
1787 maxItems: 5
1788 items:
1789 type: string
1790 minLength: 2
1791 maxLength: 30
1792 commentsEnabled:
1793 description: Enable or disable comments for this video
1794 type: boolean
1795 downloadEnabled:
1796 description: Enable or disable downloading for this video
1797 type: boolean
1798 originallyPublishedAt:
1799 description: Date when the content was originally published
1800 type: string
1801 format: date-time
1802 scheduleUpdate:
1803 $ref: '#/components/schemas/VideoScheduledUpdate'
1804 encoding:
1805 thumbnailfile:
1806 contentType: image/jpeg
1807 previewfile:
1808 contentType: image/jpeg
1809 get:
1810 summary: Get a video
1811 operationId: getVideo
1812 tags:
1813 - Video
1814 parameters:
1815 - $ref: '#/components/parameters/idOrUUID'
1816 responses:
1817 '200':
1818 description: successful operation
1819 content:
1820 application/json:
1821 schema:
1822 $ref: '#/components/schemas/VideoDetails'
1823 delete:
1824 summary: Delete a video
1825 operationId: delVideo
1826 security:
1827 - OAuth2: []
1828 tags:
1829 - Video
1830 parameters:
1831 - $ref: '#/components/parameters/idOrUUID'
1832 responses:
1833 '204':
1834 description: successful operation
1835
1836 '/videos/{id}/description':
1837 get:
1838 summary: Get complete video description
1839 operationId: getVideoDesc
1840 tags:
1841 - Video
1842 parameters:
1843 - $ref: '#/components/parameters/idOrUUID'
1844 responses:
1845 '200':
1846 description: successful operation
1847 content:
1848 application/json:
1849 schema:
1850 nullable: true
1851 type: string
1852 minLength: 3
1853 maxLength: 10000
1854 example: |
1855 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
1856
1857 '/videos/{id}/views':
1858 post:
1859 summary: Add a view to a video
1860 operationId: addView
1861 tags:
1862 - Video
1863 parameters:
1864 - $ref: '#/components/parameters/idOrUUID'
1865 responses:
1866 '204':
1867 description: successful operation
1868
1869 '/videos/{id}/watching':
1870 put:
1871 summary: Set watching progress of a video
1872 operationId: setProgress
1873 tags:
1874 - Video
1875 security:
1876 - OAuth2: []
1877 parameters:
1878 - $ref: '#/components/parameters/idOrUUID'
1879 requestBody:
1880 content:
1881 application/json:
1882 schema:
1883 $ref: '#/components/schemas/UserWatchingVideo'
1884 required: true
1885 responses:
1886 '204':
1887 description: successful operation
1888
1889 /videos/upload:
1890 post:
1891 summary: Upload a video
1892 description: Uses a single request to upload a video.
1893 operationId: uploadLegacy
1894 security:
1895 - OAuth2: []
1896 tags:
1897 - Video
1898 - Video Upload
1899 responses:
1900 '200':
1901 description: successful operation
1902 content:
1903 application/json:
1904 schema:
1905 $ref: '#/components/schemas/VideoUploadResponse'
1906 '403':
1907 description: video didn't pass upload filter
1908 '408':
1909 description: upload has timed out
1910 '413':
1911 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1912 description: |
1913 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1914 - `quota_reached` for quota limits wether daily or global
1915 headers:
1916 X-File-Maximum-Size:
1917 schema:
1918 type: string
1919 format: Nginx size
1920 description: Maximum file size for the video
1921 '415':
1922 description: video type unsupported
1923 '422':
1924 description: video unreadable
1925 requestBody:
1926 content:
1927 multipart/form-data:
1928 schema:
1929 $ref: '#/components/schemas/VideoUploadRequestLegacy'
1930 encoding:
1931 videofile:
1932 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1933 thumbnailfile:
1934 contentType: image/jpeg
1935 previewfile:
1936 contentType: image/jpeg
1937 x-codeSamples:
1938 - lang: Shell
1939 source: |
1940 ## DEPENDENCIES: jq
1941 USERNAME="<your_username>"
1942 PASSWORD="<your_password>"
1943 FILE_PATH="<your_file_path>"
1944 CHANNEL_ID="<your_channel_id>"
1945 NAME="<video_name>"
1946 API="https://peertube2.cpy.re/api/v1"
1947
1948 ## AUTH
1949 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1950 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1951 token=$(curl -s "$API/users/token" \
1952 --data client_id="$client_id" \
1953 --data client_secret="$client_secret" \
1954 --data grant_type=password \
1955 --data username="$USERNAME" \
1956 --data password="$PASSWORD" \
1957 | jq -r ".access_token")
1958
1959 ## VIDEO UPLOAD
1960 curl -s "$API/videos/upload" \
1961 -H "Authorization: Bearer $token" \
1962 --max-time 600 \
1963 --form videofile=@"$FILE_PATH" \
1964 --form channelId=$CHANNEL_ID \
1965 --form name="$NAME"
1966
1967 /videos/upload-resumable:
1968 post:
1969 summary: Initialize the resumable upload of a video
1970 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1971 operationId: uploadResumableInit
1972 security:
1973 - OAuth2: []
1974 tags:
1975 - Video
1976 - Video Upload
1977 parameters:
1978 - name: X-Upload-Content-Length
1979 in: header
1980 schema:
1981 type: number
1982 example: 2469036
1983 required: true
1984 description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1985 - name: X-Upload-Content-Type
1986 in: header
1987 schema:
1988 type: string
1989 format: mimetype
1990 example: video/mp4
1991 required: true
1992 description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1993 requestBody:
1994 content:
1995 application/json:
1996 schema:
1997 $ref: '#/components/schemas/VideoUploadRequestResumable'
1998 responses:
1999 '200':
2000 description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
2001 '201':
2002 description: created
2003 headers:
2004 Location:
2005 schema:
2006 type: string
2007 format: url
2008 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
2009 Content-Length:
2010 schema:
2011 type: number
2012 example: 0
2013 '413':
2014 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
2015 description: |
2016 Disambiguate via `type`:
2017 - `max_file_size_reached` for the absolute file size limit
2018 - `quota_reached` for quota limits whether daily or global
2019 '415':
2020 description: video type unsupported
2021 put:
2022 summary: Send chunk for the resumable upload of a video
2023 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
2024 operationId: uploadResumable
2025 security:
2026 - OAuth2: []
2027 tags:
2028 - Video
2029 - Video Upload
2030 parameters:
2031 - name: upload_id
2032 in: query
2033 required: true
2034 description: |
2035 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2036 not valid anymore and you need to initialize a new upload.
2037 schema:
2038 type: string
2039 - name: Content-Range
2040 in: header
2041 schema:
2042 type: string
2043 example: bytes 0-262143/2469036
2044 required: true
2045 description: |
2046 Specifies the bytes in the file that the request is uploading.
2047
2048 For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
2049 262144 bytes (256 x 1024) in a 2,469,036 byte file.
2050 - name: Content-Length
2051 in: header
2052 schema:
2053 type: number
2054 example: 262144
2055 required: true
2056 description: |
2057 Size of the chunk that the request is sending.
2058
2059 The chunk size __must be a multiple of 256 KB__, and unlike [Google Resumable](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
2060 doesn't mandate for chunks to have the same size throughout the upload sequence.
2061
2062 Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
2063 1048576 bytes (~1MB) and increases or reduces size depending on connection health.
2064 requestBody:
2065 content:
2066 application/octet-stream:
2067 schema:
2068 type: string
2069 format: binary
2070 responses:
2071 '200':
2072 description: last chunk received
2073 headers:
2074 Content-Length:
2075 schema:
2076 type: number
2077 content:
2078 application/json:
2079 schema:
2080 $ref: '#/components/schemas/VideoUploadResponse'
2081 '308':
2082 description: resume incomplete
2083 headers:
2084 Range:
2085 schema:
2086 type: string
2087 example: bytes=0-262143
2088 Content-Length:
2089 schema:
2090 type: number
2091 example: 0
2092 '403':
2093 description: video didn't pass upload filter
2094 '404':
2095 description: upload not found
2096 '409':
2097 description: chunk doesn't match range
2098 '422':
2099 description: video unreadable
2100 '429':
2101 description: too many concurrent requests
2102 '503':
2103 description: upload is already being processed
2104 headers:
2105 'Retry-After':
2106 schema:
2107 type: number
2108 example: 300
2109 delete:
2110 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
2111 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
2112 operationId: uploadResumableCancel
2113 security:
2114 - OAuth2: []
2115 tags:
2116 - Video
2117 - Video Upload
2118 parameters:
2119 - name: upload_id
2120 in: query
2121 required: true
2122 description: |
2123 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
2124 not valid anymore and the upload session has already been deleted with its data ;-)
2125 schema:
2126 type: string
2127 - name: Content-Length
2128 in: header
2129 required: true
2130 schema:
2131 type: number
2132 example: 0
2133 responses:
2134 '204':
2135 description: upload cancelled
2136 headers:
2137 Content-Length:
2138 schema:
2139 type: number
2140 example: 0
2141 '404':
2142 description: upload not found
2143
2144 /videos/imports:
2145 post:
2146 summary: Import a video
2147 description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
2148 operationId: importVideo
2149 security:
2150 - OAuth2: []
2151 tags:
2152 - Video
2153 - Video Upload
2154 requestBody:
2155 content:
2156 multipart/form-data:
2157 schema:
2158 $ref: '#/components/schemas/VideoCreateImport'
2159 encoding:
2160 torrentfile:
2161 contentType: application/x-bittorrent
2162 thumbnailfile:
2163 contentType: image/jpeg
2164 previewfile:
2165 contentType: image/jpeg
2166 responses:
2167 '200':
2168 description: successful operation
2169 content:
2170 application/json:
2171 schema:
2172 $ref: '#/components/schemas/VideoUploadResponse'
2173 '400':
2174 description: '`magnetUri` or `targetUrl` or a torrent file missing'
2175 '403':
2176 description: video didn't pass pre-import filter
2177 '409':
2178 description: HTTP or Torrent/magnetURI import not enabled
2179
2180 /videos/live:
2181 post:
2182 summary: Create a live
2183 operationId: addLive
2184 security:
2185 - OAuth2: []
2186 tags:
2187 - Live Videos
2188 - Video
2189 responses:
2190 '200':
2191 description: successful operation
2192 content:
2193 application/json:
2194 schema:
2195 $ref: '#/components/schemas/VideoUploadResponse'
2196 '400':
2197 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2198 description: |
2199 Disambiguate via `type`:
2200 - default type for a validation error
2201 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
2202 '403':
2203 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2204 description: |
2205 Disambiguate via `type`:
2206 - `live_not_enabled` for a disabled live feature
2207 - `live_not_allowing_replay` for a disabled replay feature
2208 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2209 - `max_user_lives_limit_reached` for the user concurrent live limit
2210 requestBody:
2211 content:
2212 multipart/form-data:
2213 schema:
2214 type: object
2215 properties:
2216 channelId:
2217 description: Channel id that will contain this live video
2218 type: integer
2219 saveReplay:
2220 type: boolean
2221 permanentLive:
2222 description: User can stream multiple times in a permanent live
2223 type: boolean
2224 thumbnailfile:
2225 description: Live video/replay thumbnail file
2226 type: string
2227 format: binary
2228 previewfile:
2229 description: Live video/replay preview file
2230 type: string
2231 format: binary
2232 privacy:
2233 $ref: '#/components/schemas/VideoPrivacySet'
2234 category:
2235 $ref: '#/components/schemas/VideoCategorySet'
2236 licence:
2237 $ref: '#/components/schemas/VideoLicenceSet'
2238 language:
2239 $ref: '#/components/schemas/VideoLanguageSet'
2240 description:
2241 description: Live video/replay description
2242 type: string
2243 support:
2244 description: A text tell the audience how to support the creator
2245 example: Please support our work on https://soutenir.framasoft.org/en/ <3
2246 type: string
2247 nsfw:
2248 description: Whether or not this live video/replay contains sensitive content
2249 type: boolean
2250 name:
2251 description: Live video/replay name
2252 type: string
2253 minLength: 3
2254 maxLength: 120
2255 tags:
2256 description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2257 type: array
2258 minItems: 1
2259 maxItems: 5
2260 items:
2261 type: string
2262 minLength: 2
2263 maxLength: 30
2264 commentsEnabled:
2265 description: Enable or disable comments for this live video/replay
2266 type: boolean
2267 downloadEnabled:
2268 description: Enable or disable downloading for the replay of this live video
2269 type: boolean
2270 required:
2271 - channelId
2272 - name
2273 encoding:
2274 thumbnailfile:
2275 contentType: image/jpeg
2276 previewfile:
2277 contentType: image/jpeg
2278
2279 /videos/live/{id}:
2280 get:
2281 summary: Get information about a live
2282 operationId: getLiveId
2283 security:
2284 - OAuth2: []
2285 tags:
2286 - Live Videos
2287 - Video
2288 parameters:
2289 - $ref: '#/components/parameters/idOrUUID'
2290 responses:
2291 '200':
2292 description: successful operation
2293 content:
2294 application/json:
2295 schema:
2296 $ref: '#/components/schemas/LiveVideoResponse'
2297 put:
2298 summary: Update information about a live
2299 operationId: updateLiveId
2300 security:
2301 - OAuth2: []
2302 tags:
2303 - Live Videos
2304 - Video
2305 parameters:
2306 - $ref: '#/components/parameters/idOrUUID'
2307 requestBody:
2308 content:
2309 application/json:
2310 schema:
2311 $ref: '#/components/schemas/LiveVideoUpdate'
2312 responses:
2313 '204':
2314 description: successful operation
2315 '400':
2316 description: bad parameters or trying to update a live that has already started
2317 '403':
2318 description: trying to save replay of the live but saving replay is not enabled on the instance
2319
2320 /users/me/abuses:
2321 get:
2322 summary: List my abuses
2323 operationId: getMyAbuses
2324 security:
2325 - OAuth2: []
2326 tags:
2327 - Abuses
2328 - My User
2329 parameters:
2330 - name: id
2331 in: query
2332 description: only list the report with this id
2333 schema:
2334 type: integer
2335 - name: state
2336 in: query
2337 schema:
2338 $ref: '#/components/schemas/AbuseStateSet'
2339 - $ref: '#/components/parameters/abusesSort'
2340 - $ref: '#/components/parameters/start'
2341 - $ref: '#/components/parameters/count'
2342 responses:
2343 '200':
2344 description: successful operation
2345 content:
2346 application/json:
2347 schema:
2348 type: object
2349 properties:
2350 total:
2351 type: integer
2352 example: 1
2353 data:
2354 type: array
2355 items:
2356 $ref: '#/components/schemas/Abuse'
2357
2358 /abuses:
2359 get:
2360 summary: List abuses
2361 operationId: getAbuses
2362 security:
2363 - OAuth2:
2364 - admin
2365 - moderator
2366 tags:
2367 - Abuses
2368 parameters:
2369 - name: id
2370 in: query
2371 description: only list the report with this id
2372 schema:
2373 type: integer
2374 - name: predefinedReason
2375 in: query
2376 description: predefined reason the listed reports should contain
2377 schema:
2378 $ref: '#/components/schemas/PredefinedAbuseReasons'
2379 - name: search
2380 in: query
2381 description: plain search that will match with video titles, reporter names and more
2382 schema:
2383 type: string
2384 - name: state
2385 in: query
2386 schema:
2387 $ref: '#/components/schemas/AbuseStateSet'
2388 - name: searchReporter
2389 in: query
2390 description: only list reports of a specific reporter
2391 schema:
2392 type: string
2393 - name: searchReportee
2394 description: only list reports of a specific reportee
2395 in: query
2396 schema:
2397 type: string
2398 - name: searchVideo
2399 in: query
2400 description: only list reports of a specific video
2401 schema:
2402 type: string
2403 - name: searchVideoChannel
2404 in: query
2405 description: only list reports of a specific video channel
2406 schema:
2407 type: string
2408 - name: videoIs
2409 in: query
2410 description: only list deleted or blocklisted videos
2411 schema:
2412 type: string
2413 enum:
2414 - 'deleted'
2415 - 'blacklisted'
2416 - name: filter
2417 in: query
2418 description: only list account, comment or video reports
2419 schema:
2420 type: string
2421 enum:
2422 - 'video'
2423 - 'comment'
2424 - 'account'
2425 - $ref: '#/components/parameters/start'
2426 - $ref: '#/components/parameters/count'
2427 - $ref: '#/components/parameters/abusesSort'
2428 responses:
2429 '200':
2430 description: successful operation
2431 content:
2432 application/json:
2433 schema:
2434 type: object
2435 properties:
2436 total:
2437 type: integer
2438 example: 1
2439 data:
2440 type: array
2441 items:
2442 $ref: '#/components/schemas/Abuse'
2443 post:
2444 summary: Report an abuse
2445 security:
2446 - OAuth2: []
2447 tags:
2448 - Abuses
2449 requestBody:
2450 required: true
2451 content:
2452 application/json:
2453 schema:
2454 type: object
2455 properties:
2456 reason:
2457 description: Reason why the user reports this video
2458 type: string
2459 minLength: 2
2460 maxLength: 3000
2461 predefinedReasons:
2462 $ref: '#/components/schemas/PredefinedAbuseReasons'
2463 video:
2464 type: object
2465 properties:
2466 id:
2467 description: Video id to report
2468 allOf:
2469 - $ref: '#/components/schemas/Video/properties/id'
2470 startAt:
2471 type: integer
2472 format: seconds
2473 description: Timestamp in the video that marks the beginning of the report
2474 minimum: 0
2475 endAt:
2476 type: integer
2477 format: seconds
2478 description: Timestamp in the video that marks the ending of the report
2479 minimum: 0
2480 comment:
2481 type: object
2482 properties:
2483 id:
2484 description: Comment id to report
2485 allOf:
2486 - $ref: '#/components/schemas/VideoComment/properties/id'
2487 account:
2488 type: object
2489 properties:
2490 id:
2491 description: Account id to report
2492 type: integer
2493 required:
2494 - reason
2495 responses:
2496 '200':
2497 description: successful operation
2498 content:
2499 application/json:
2500 schema:
2501 type: object
2502 properties:
2503 abuse:
2504 type: object
2505 properties:
2506 id:
2507 $ref: '#/components/schemas/id'
2508 '400':
2509 description: incorrect request parameters
2510
2511 '/abuses/{abuseId}':
2512 put:
2513 summary: Update an abuse
2514 security:
2515 - OAuth2:
2516 - admin
2517 - moderator
2518 tags:
2519 - Abuses
2520 parameters:
2521 - $ref: '#/components/parameters/abuseId'
2522 requestBody:
2523 content:
2524 application/json:
2525 schema:
2526 type: object
2527 properties:
2528 state:
2529 $ref: '#/components/schemas/AbuseStateSet'
2530 moderationComment:
2531 type: string
2532 description: Update the report comment visible only to the moderation team
2533 minLength: 2
2534 maxLength: 3000
2535 responses:
2536 '204':
2537 description: successful operation
2538 '404':
2539 description: abuse not found
2540 delete:
2541 tags:
2542 - Abuses
2543 summary: Delete an abuse
2544 security:
2545 - OAuth2:
2546 - admin
2547 - moderator
2548 parameters:
2549 - $ref: '#/components/parameters/abuseId'
2550 responses:
2551 '204':
2552 description: successful operation
2553 '404':
2554 description: block not found
2555
2556 '/abuses/{abuseId}/messages':
2557 get:
2558 summary: List messages of an abuse
2559 security:
2560 - OAuth2: []
2561 tags:
2562 - Abuses
2563 parameters:
2564 - $ref: '#/components/parameters/abuseId'
2565 responses:
2566 '200':
2567 description: successful operation
2568 content:
2569 application/json:
2570 schema:
2571 type: object
2572 properties:
2573 total:
2574 type: integer
2575 example: 1
2576 data:
2577 type: array
2578 items:
2579 $ref: '#/components/schemas/AbuseMessage'
2580 post:
2581 summary: Add message to an abuse
2582 security:
2583 - OAuth2: []
2584 tags:
2585 - Abuses
2586 parameters:
2587 - $ref: '#/components/parameters/abuseId'
2588 requestBody:
2589 required: true
2590 content:
2591 application/json:
2592 schema:
2593 type: object
2594 properties:
2595 message:
2596 description: Message to send
2597 type: string
2598 minLength: 2
2599 maxLength: 3000
2600 required:
2601 - message
2602 responses:
2603 '200':
2604 description: successful operation
2605 '400':
2606 description: incorrect request parameters
2607
2608 '/abuses/{abuseId}/messages/{abuseMessageId}':
2609 delete:
2610 summary: Delete an abuse message
2611 security:
2612 - OAuth2: []
2613 tags:
2614 - Abuses
2615 parameters:
2616 - $ref: '#/components/parameters/abuseId'
2617 - $ref: '#/components/parameters/abuseMessageId'
2618 responses:
2619 '204':
2620 description: successful operation
2621
2622 '/videos/{id}/blacklist':
2623 post:
2624 summary: Block a video
2625 operationId: addVideoBlock
2626 security:
2627 - OAuth2:
2628 - admin
2629 - moderator
2630 tags:
2631 - Video Blocks
2632 parameters:
2633 - $ref: '#/components/parameters/idOrUUID'
2634 responses:
2635 '204':
2636 description: successful operation
2637 delete:
2638 summary: Unblock a video by its id
2639 operationId: delVideoBlock
2640 security:
2641 - OAuth2:
2642 - admin
2643 - moderator
2644 tags:
2645 - Video Blocks
2646 parameters:
2647 - $ref: '#/components/parameters/idOrUUID'
2648 responses:
2649 '204':
2650 description: successful operation
2651 '404':
2652 description: block not found
2653
2654 /videos/blacklist:
2655 get:
2656 tags:
2657 - Video Blocks
2658 summary: List video blocks
2659 operationId: getVideoBlocks
2660 security:
2661 - OAuth2:
2662 - admin
2663 - moderator
2664 parameters:
2665 - name: type
2666 in: query
2667 description: >
2668 list only blocks that match this type:
2669
2670 - `1`: manual block
2671
2672 - `2`: automatic block that needs review
2673 schema:
2674 type: integer
2675 enum:
2676 - 1
2677 - 2
2678 - name: search
2679 in: query
2680 description: plain search that will match with video titles, and more
2681 schema:
2682 type: string
2683 - $ref: '#/components/parameters/start'
2684 - $ref: '#/components/parameters/count'
2685 - $ref: '#/components/parameters/blacklistsSort'
2686 responses:
2687 '200':
2688 description: successful operation
2689 content:
2690 application/json:
2691 schema:
2692 type: object
2693 properties:
2694 total:
2695 type: integer
2696 example: 1
2697 data:
2698 type: array
2699 items:
2700 $ref: '#/components/schemas/VideoBlacklist'
2701
2702 /videos/{id}/captions:
2703 get:
2704 summary: List captions of a video
2705 operationId: getVideoCaptions
2706 tags:
2707 - Video Captions
2708 parameters:
2709 - $ref: '#/components/parameters/idOrUUID'
2710 responses:
2711 '200':
2712 description: successful operation
2713 content:
2714 application/json:
2715 schema:
2716 type: object
2717 properties:
2718 total:
2719 type: integer
2720 example: 1
2721 data:
2722 type: array
2723 items:
2724 $ref: '#/components/schemas/VideoCaption'
2725
2726 /videos/{id}/captions/{captionLanguage}:
2727 put:
2728 summary: Add or replace a video caption
2729 operationId: addVideoCaption
2730 security:
2731 - OAuth2:
2732 - user
2733 tags:
2734 - Video Captions
2735 parameters:
2736 - $ref: '#/components/parameters/idOrUUID'
2737 - $ref: '#/components/parameters/captionLanguage'
2738 requestBody:
2739 content:
2740 multipart/form-data:
2741 schema:
2742 type: object
2743 properties:
2744 captionfile:
2745 description: The file to upload.
2746 type: string
2747 format: binary
2748 encoding:
2749 captionfile:
2750 contentType: text/vtt, application/x-subrip, text/plain
2751 responses:
2752 '204':
2753 description: successful operation
2754 '404':
2755 description: video or language not found
2756 delete:
2757 summary: Delete a video caption
2758 operationId: delVideoCaption
2759 security:
2760 - OAuth2:
2761 - user
2762 tags:
2763 - Video Captions
2764 parameters:
2765 - $ref: '#/components/parameters/idOrUUID'
2766 - $ref: '#/components/parameters/captionLanguage'
2767 responses:
2768 '204':
2769 description: successful operation
2770 '404':
2771 description: video or language or caption for that language not found
2772
2773 /video-channels:
2774 get:
2775 summary: List video channels
2776 operationId: getVideoChannels
2777 tags:
2778 - Video Channels
2779 parameters:
2780 - $ref: '#/components/parameters/start'
2781 - $ref: '#/components/parameters/count'
2782 - $ref: '#/components/parameters/sort'
2783 responses:
2784 '200':
2785 description: successful operation
2786 content:
2787 application/json:
2788 schema:
2789 $ref: '#/components/schemas/VideoChannelList'
2790 post:
2791 summary: Create a video channel
2792 operationId: addVideoChannel
2793 security:
2794 - OAuth2: []
2795 tags:
2796 - Video Channels
2797 responses:
2798 '204':
2799 description: successful operation
2800 content:
2801 application/json:
2802 schema:
2803 type: object
2804 properties:
2805 videoChannel:
2806 type: object
2807 properties:
2808 id:
2809 $ref: '#/components/schemas/VideoChannel/properties/id'
2810 requestBody:
2811 content:
2812 application/json:
2813 schema:
2814 $ref: '#/components/schemas/VideoChannelCreate'
2815
2816 '/video-channels/{channelHandle}':
2817 get:
2818 summary: Get a video channel
2819 operationId: getVideoChannel
2820 tags:
2821 - Video Channels
2822 parameters:
2823 - $ref: '#/components/parameters/channelHandle'
2824 responses:
2825 '200':
2826 description: successful operation
2827 content:
2828 application/json:
2829 schema:
2830 $ref: '#/components/schemas/VideoChannel'
2831 put:
2832 summary: Update a video channel
2833 operationId: putVideoChannel
2834 security:
2835 - OAuth2: []
2836 tags:
2837 - Video Channels
2838 parameters:
2839 - $ref: '#/components/parameters/channelHandle'
2840 responses:
2841 '204':
2842 description: successful operation
2843 requestBody:
2844 content:
2845 application/json:
2846 schema:
2847 $ref: '#/components/schemas/VideoChannelUpdate'
2848 delete:
2849 summary: Delete a video channel
2850 operationId: delVideoChannel
2851 security:
2852 - OAuth2: []
2853 tags:
2854 - Video Channels
2855 parameters:
2856 - $ref: '#/components/parameters/channelHandle'
2857 responses:
2858 '204':
2859 description: successful operation
2860
2861 '/video-channels/{channelHandle}/videos':
2862 get:
2863 summary: List videos of a video channel
2864 operationId: getVideoChannelVideos
2865 tags:
2866 - Video
2867 - Video Channels
2868 parameters:
2869 - $ref: '#/components/parameters/channelHandle'
2870 - $ref: '#/components/parameters/categoryOneOf'
2871 - $ref: '#/components/parameters/isLive'
2872 - $ref: '#/components/parameters/tagsOneOf'
2873 - $ref: '#/components/parameters/tagsAllOf'
2874 - $ref: '#/components/parameters/licenceOneOf'
2875 - $ref: '#/components/parameters/languageOneOf'
2876 - $ref: '#/components/parameters/nsfw'
2877 - $ref: '#/components/parameters/isLocal'
2878 - $ref: '#/components/parameters/include'
2879 - $ref: '#/components/parameters/privacyOneOf'
2880 - $ref: '#/components/parameters/hasHLSFiles'
2881 - $ref: '#/components/parameters/hasWebtorrentFiles'
2882 - $ref: '#/components/parameters/skipCount'
2883 - $ref: '#/components/parameters/start'
2884 - $ref: '#/components/parameters/count'
2885 - $ref: '#/components/parameters/videosSort'
2886 responses:
2887 '200':
2888 description: successful operation
2889 content:
2890 application/json:
2891 schema:
2892 $ref: '#/components/schemas/VideoListResponse'
2893
2894 '/video-channels/{channelHandle}/followers':
2895 get:
2896 tags:
2897 - Video Channels
2898 summary: 'List followers of a video channel'
2899 security:
2900 - OAuth2: []
2901 operationId: getVideoChannelFollowers
2902 parameters:
2903 - $ref: '#/components/parameters/channelHandle'
2904 - $ref: '#/components/parameters/start'
2905 - $ref: '#/components/parameters/count'
2906 - $ref: '#/components/parameters/followersSort'
2907 - $ref: '#/components/parameters/search'
2908 responses:
2909 '200':
2910 description: successful operation
2911 content:
2912 application/json:
2913 schema:
2914 type: object
2915 properties:
2916 total:
2917 type: integer
2918 example: 1
2919 data:
2920 type: array
2921 items:
2922 $ref: '#/components/schemas/Follow'
2923
2924 '/video-channels/{channelHandle}/avatar/pick':
2925 post:
2926 summary: Update channel avatar
2927 security:
2928 - OAuth2: []
2929 tags:
2930 - Video Channels
2931 parameters:
2932 - $ref: '#/components/parameters/channelHandle'
2933 responses:
2934 '200':
2935 description: successful operation
2936 content:
2937 application/json:
2938 schema:
2939 type: object
2940 properties:
2941 avatar:
2942 $ref: '#/components/schemas/ActorImage'
2943 '413':
2944 description: image file too large
2945 headers:
2946 X-File-Maximum-Size:
2947 schema:
2948 type: string
2949 format: Nginx size
2950 description: Maximum file size for the avatar
2951 requestBody:
2952 content:
2953 multipart/form-data:
2954 schema:
2955 type: object
2956 properties:
2957 avatarfile:
2958 description: The file to upload.
2959 type: string
2960 format: binary
2961 encoding:
2962 avatarfile:
2963 contentType: image/png, image/jpeg
2964
2965 '/video-channels/{channelHandle}/avatar':
2966 delete:
2967 summary: Delete channel avatar
2968 security:
2969 - OAuth2: []
2970 tags:
2971 - Video Channels
2972 parameters:
2973 - $ref: '#/components/parameters/channelHandle'
2974 responses:
2975 '204':
2976 description: successful operation
2977
2978 '/video-channels/{channelHandle}/banner/pick':
2979 post:
2980 summary: Update channel banner
2981 security:
2982 - OAuth2: []
2983 tags:
2984 - Video Channels
2985 parameters:
2986 - $ref: '#/components/parameters/channelHandle'
2987 responses:
2988 '200':
2989 description: successful operation
2990 content:
2991 application/json:
2992 schema:
2993 type: object
2994 properties:
2995 banner:
2996 $ref: '#/components/schemas/ActorImage'
2997 '413':
2998 description: image file too large
2999 headers:
3000 X-File-Maximum-Size:
3001 schema:
3002 type: string
3003 format: Nginx size
3004 description: Maximum file size for the banner
3005 requestBody:
3006 content:
3007 multipart/form-data:
3008 schema:
3009 type: object
3010 properties:
3011 bannerfile:
3012 description: The file to upload.
3013 type: string
3014 format: binary
3015 encoding:
3016 bannerfile:
3017 contentType: image/png, image/jpeg
3018
3019 '/video-channels/{channelHandle}/banner':
3020 delete:
3021 summary: Delete channel banner
3022 security:
3023 - OAuth2: []
3024 tags:
3025 - Video Channels
3026 parameters:
3027 - $ref: '#/components/parameters/channelHandle'
3028 responses:
3029 '204':
3030 description: successful operation
3031
3032 /video-playlists/privacies:
3033 get:
3034 summary: List available playlist privacy policies
3035 operationId: getPlaylistPrivacyPolicies
3036 tags:
3037 - Video Playlists
3038 responses:
3039 '200':
3040 description: successful operation
3041 content:
3042 application/json:
3043 schema:
3044 type: array
3045 items:
3046 type: string
3047 examples:
3048 nightly:
3049 externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3050
3051 /video-playlists:
3052 get:
3053 summary: List video playlists
3054 operationId: getPlaylists
3055 tags:
3056 - Video Playlists
3057 parameters:
3058 - $ref: '#/components/parameters/start'
3059 - $ref: '#/components/parameters/count'
3060 - $ref: '#/components/parameters/sort'
3061 responses:
3062 '200':
3063 description: successful operation
3064 content:
3065 application/json:
3066 schema:
3067 type: object
3068 properties:
3069 total:
3070 type: integer
3071 example: 1
3072 data:
3073 type: array
3074 items:
3075 $ref: '#/components/schemas/VideoPlaylist'
3076 post:
3077 summary: Create a video playlist
3078 description: If the video playlist is set as public, `videoChannelId` is mandatory.
3079 operationId: addPlaylist
3080 security:
3081 - OAuth2: []
3082 tags:
3083 - Video Playlists
3084 responses:
3085 '200':
3086 description: successful operation
3087 content:
3088 application/json:
3089 schema:
3090 type: object
3091 properties:
3092 videoPlaylist:
3093 type: object
3094 properties:
3095 id:
3096 $ref: '#/components/schemas/VideoPlaylist/properties/id'
3097 uuid:
3098 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3099 shortUUID:
3100 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3101 requestBody:
3102 content:
3103 multipart/form-data:
3104 schema:
3105 type: object
3106 properties:
3107 displayName:
3108 description: Video playlist display name
3109 type: string
3110 minLength: 1
3111 maxLength: 120
3112 thumbnailfile:
3113 description: Video playlist thumbnail file
3114 type: string
3115 format: binary
3116 privacy:
3117 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3118 description:
3119 description: Video playlist description
3120 type: string
3121 minLength: 3
3122 maxLength: 1000
3123 videoChannelId:
3124 allOf:
3125 - $ref: '#/components/schemas/id'
3126 description: Video channel in which the playlist will be published
3127 required:
3128 - displayName
3129 encoding:
3130 thumbnailfile:
3131 contentType: image/jpeg
3132
3133 /video-playlists/{playlistId}:
3134 get:
3135 summary: Get a video playlist
3136 tags:
3137 - Video Playlists
3138 parameters:
3139 - $ref: '#/components/parameters/playlistId'
3140 responses:
3141 '200':
3142 description: successful operation
3143 content:
3144 application/json:
3145 schema:
3146 $ref: '#/components/schemas/VideoPlaylist'
3147 put:
3148 summary: Update a video playlist
3149 description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3150 security:
3151 - OAuth2: []
3152 tags:
3153 - Video Playlists
3154 responses:
3155 '204':
3156 description: successful operation
3157 parameters:
3158 - $ref: '#/components/parameters/playlistId'
3159 requestBody:
3160 content:
3161 multipart/form-data:
3162 schema:
3163 type: object
3164 properties:
3165 displayName:
3166 description: Video playlist display name
3167 type: string
3168 minLength: 1
3169 maxLength: 120
3170 thumbnailfile:
3171 description: Video playlist thumbnail file
3172 type: string
3173 format: binary
3174 privacy:
3175 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3176 description:
3177 description: Video playlist description
3178 type: string
3179 videoChannelId:
3180 allOf:
3181 - $ref: '#/components/schemas/id'
3182 description: Video channel in which the playlist will be published
3183 encoding:
3184 thumbnailfile:
3185 contentType: image/jpeg
3186 delete:
3187 summary: Delete a video playlist
3188 security:
3189 - OAuth2: []
3190 tags:
3191 - Video Playlists
3192 parameters:
3193 - $ref: '#/components/parameters/playlistId'
3194 responses:
3195 '204':
3196 description: successful operation
3197
3198 /video-playlists/{playlistId}/videos:
3199 get:
3200 summary: 'List videos of a playlist'
3201 operationId: getVideoPlaylistVideos
3202 tags:
3203 - Videos
3204 - Video Playlists
3205 parameters:
3206 - $ref: '#/components/parameters/playlistId'
3207 - $ref: '#/components/parameters/start'
3208 - $ref: '#/components/parameters/count'
3209 responses:
3210 '200':
3211 description: successful operation
3212 content:
3213 application/json:
3214 schema:
3215 $ref: '#/components/schemas/VideoListResponse'
3216 post:
3217 summary: Add a video in a playlist
3218 operationId: addVideoPlaylistVideo
3219 security:
3220 - OAuth2: []
3221 tags:
3222 - Videos
3223 - Video Playlists
3224 parameters:
3225 - $ref: '#/components/parameters/playlistId'
3226 responses:
3227 '200':
3228 description: successful operation
3229 content:
3230 application/json:
3231 schema:
3232 type: object
3233 properties:
3234 videoPlaylistElement:
3235 type: object
3236 properties:
3237 id:
3238 type: integer
3239 example: 2
3240 requestBody:
3241 content:
3242 application/json:
3243 schema:
3244 type: object
3245 properties:
3246 videoId:
3247 oneOf:
3248 - $ref: '#/components/schemas/Video/properties/uuid'
3249 - $ref: '#/components/schemas/Video/properties/id'
3250 description: Video to add in the playlist
3251 startTimestamp:
3252 type: integer
3253 format: seconds
3254 description: Start the video at this specific timestamp
3255 stopTimestamp:
3256 type: integer
3257 format: seconds
3258 description: Stop the video at this specific timestamp
3259 required:
3260 - videoId
3261
3262 /video-playlists/{playlistId}/videos/reorder:
3263 post:
3264 summary: 'Reorder a playlist'
3265 operationId: reorderVideoPlaylist
3266 security:
3267 - OAuth2: []
3268 tags:
3269 - Video Playlists
3270 parameters:
3271 - $ref: '#/components/parameters/playlistId'
3272 responses:
3273 '204':
3274 description: successful operation
3275 requestBody:
3276 content:
3277 application/json:
3278 schema:
3279 type: object
3280 properties:
3281 startPosition:
3282 type: integer
3283 description: 'Start position of the element to reorder'
3284 minimum: 1
3285 insertAfterPosition:
3286 type: integer
3287 description: 'New position for the block to reorder, to add the block before the first element'
3288 minimum: 0
3289 reorderLength:
3290 type: integer
3291 description: 'How many element from `startPosition` to reorder'
3292 minimum: 1
3293 required:
3294 - startPosition
3295 - insertAfterPosition
3296
3297 /video-playlists/{playlistId}/videos/{playlistElementId}:
3298 put:
3299 summary: Update a playlist element
3300 operationId: putVideoPlaylistVideo
3301 security:
3302 - OAuth2: []
3303 tags:
3304 - Video Playlists
3305 parameters:
3306 - $ref: '#/components/parameters/playlistId'
3307 - $ref: '#/components/parameters/playlistElementId'
3308 responses:
3309 '204':
3310 description: successful operation
3311 requestBody:
3312 content:
3313 application/json:
3314 schema:
3315 type: object
3316 properties:
3317 startTimestamp:
3318 type: integer
3319 format: seconds
3320 description: Start the video at this specific timestamp
3321 stopTimestamp:
3322 type: integer
3323 format: seconds
3324 description: Stop the video at this specific timestamp
3325 delete:
3326 summary: Delete an element from a playlist
3327 operationId: delVideoPlaylistVideo
3328 security:
3329 - OAuth2: []
3330 tags:
3331 - Video Playlists
3332 parameters:
3333 - $ref: '#/components/parameters/playlistId'
3334 - $ref: '#/components/parameters/playlistElementId'
3335 responses:
3336 '204':
3337 description: successful operation
3338
3339 '/users/me/video-playlists/videos-exist':
3340 get:
3341 summary: Check video exists in my playlists
3342 security:
3343 - OAuth2: []
3344 tags:
3345 - Video Playlists
3346 parameters:
3347 - name: videoIds
3348 in: query
3349 required: true
3350 description: The video ids to check
3351 schema:
3352 type: array
3353 items:
3354 $ref: '#/components/schemas/Video/properties/id'
3355 responses:
3356 '200':
3357 description: successful operation
3358 content:
3359 application/json:
3360 schema:
3361 type: object
3362 properties:
3363 videoId:
3364 type: array
3365 items:
3366 type: object
3367 properties:
3368 playlistElementId:
3369 type: integer
3370 playlistId:
3371 type: integer
3372 startTimestamp:
3373 type: integer
3374 format: seconds
3375 stopTimestamp:
3376 type: integer
3377 format: seconds
3378
3379 '/accounts/{name}/video-channels':
3380 get:
3381 summary: List video channels of an account
3382 tags:
3383 - Video Channels
3384 - Accounts
3385 parameters:
3386 - $ref: '#/components/parameters/name'
3387 - name: withStats
3388 in: query
3389 description: include view statistics for the last 30 days (only if authentified as the account user)
3390 schema:
3391 type: boolean
3392 - $ref: '#/components/parameters/start'
3393 - $ref: '#/components/parameters/count'
3394 - $ref: '#/components/parameters/sort'
3395 responses:
3396 '200':
3397 description: successful operation
3398 content:
3399 application/json:
3400 schema:
3401 $ref: '#/components/schemas/VideoChannelList'
3402
3403 '/accounts/{name}/ratings':
3404 get:
3405 summary: List ratings of an account
3406 security:
3407 - OAuth2: []
3408 tags:
3409 - Accounts
3410 parameters:
3411 - $ref: '#/components/parameters/name'
3412 - $ref: '#/components/parameters/start'
3413 - $ref: '#/components/parameters/count'
3414 - $ref: '#/components/parameters/sort'
3415 - name: rating
3416 in: query
3417 required: false
3418 description: Optionally filter which ratings to retrieve
3419 schema:
3420 type: string
3421 enum:
3422 - like
3423 - dislike
3424 responses:
3425 '200':
3426 description: successful operation
3427 content:
3428 application/json:
3429 schema:
3430 type: array
3431 items:
3432 $ref: '#/components/schemas/VideoRating'
3433
3434 '/videos/{id}/comment-threads':
3435 get:
3436 summary: List threads of a video
3437 tags:
3438 - Video Comments
3439 parameters:
3440 - $ref: '#/components/parameters/idOrUUID'
3441 - $ref: '#/components/parameters/start'
3442 - $ref: '#/components/parameters/count'
3443 - $ref: '#/components/parameters/commentsSort'
3444 responses:
3445 '200':
3446 description: successful operation
3447 content:
3448 application/json:
3449 schema:
3450 $ref: '#/components/schemas/CommentThreadResponse'
3451 post:
3452 summary: Create a thread
3453 security:
3454 - OAuth2: []
3455 tags:
3456 - Video Comments
3457 parameters:
3458 - $ref: '#/components/parameters/idOrUUID'
3459 responses:
3460 '200':
3461 description: successful operation
3462 content:
3463 application/json:
3464 schema:
3465 $ref: '#/components/schemas/CommentThreadPostResponse'
3466 '404':
3467 description: video does not exist
3468 requestBody:
3469 content:
3470 application/json:
3471 schema:
3472 type: object
3473 properties:
3474 text:
3475 allOf:
3476 - $ref: '#/components/schemas/VideoComment/properties/text'
3477 format: markdown
3478 maxLength: 10000
3479 required:
3480 - text
3481
3482 '/videos/{id}/comment-threads/{threadId}':
3483 get:
3484 summary: Get a thread
3485 tags:
3486 - Video Comments
3487 parameters:
3488 - $ref: '#/components/parameters/idOrUUID'
3489 - $ref: '#/components/parameters/threadId'
3490 responses:
3491 '200':
3492 description: successful operation
3493 content:
3494 application/json:
3495 schema:
3496 $ref: '#/components/schemas/VideoCommentThreadTree'
3497
3498 '/videos/{id}/comments/{commentId}':
3499 post:
3500 summary: Reply to a thread of a video
3501 security:
3502 - OAuth2: []
3503 tags:
3504 - Video Comments
3505 parameters:
3506 - $ref: '#/components/parameters/idOrUUID'
3507 - $ref: '#/components/parameters/commentId'
3508 responses:
3509 '200':
3510 description: successful operation
3511 content:
3512 application/json:
3513 schema:
3514 $ref: '#/components/schemas/CommentThreadPostResponse'
3515 '404':
3516 description: thread or video does not exist
3517 requestBody:
3518 content:
3519 application/json:
3520 schema:
3521 type: object
3522 properties:
3523 text:
3524 allOf:
3525 - $ref: '#/components/schemas/VideoComment/properties/text'
3526 format: markdown
3527 maxLength: 10000
3528 required:
3529 - text
3530 delete:
3531 summary: Delete a comment or a reply
3532 security:
3533 - OAuth2: []
3534 tags:
3535 - Video Comments
3536 parameters:
3537 - $ref: '#/components/parameters/idOrUUID'
3538 - $ref: '#/components/parameters/commentId'
3539 responses:
3540 '204':
3541 description: successful operation
3542 '403':
3543 description: cannot remove comment of another user
3544 '404':
3545 description: comment or video does not exist
3546 '409':
3547 description: comment is already deleted
3548
3549 '/videos/{id}/rate':
3550 put:
3551 summary: Like/dislike a video
3552 security:
3553 - OAuth2: []
3554 tags:
3555 - Video Rates
3556 parameters:
3557 - $ref: '#/components/parameters/idOrUUID'
3558 requestBody:
3559 content:
3560 application/json:
3561 schema:
3562 type: object
3563 properties:
3564 rating:
3565 type: string
3566 enum:
3567 - like
3568 - dislike
3569 required:
3570 - rating
3571 responses:
3572 '204':
3573 description: successful operation
3574 '404':
3575 description: video does not exist
3576
3577 '/videos/{id}/hls':
3578 delete:
3579 summary: Delete video HLS files
3580 security:
3581 - OAuth2:
3582 - admin
3583 tags:
3584 - Video Files
3585 operationId: delVideoHLS
3586 parameters:
3587 - $ref: '#/components/parameters/idOrUUID'
3588 responses:
3589 '204':
3590 description: successful operation
3591 '404':
3592 description: video does not exist
3593 '/videos/{id}/webtorrent':
3594 delete:
3595 summary: Delete video WebTorrent files
3596 security:
3597 - OAuth2:
3598 - admin
3599 tags:
3600 - Video Files
3601 operationId: delVideoWebTorrent
3602 parameters:
3603 - $ref: '#/components/parameters/idOrUUID'
3604 responses:
3605 '204':
3606 description: successful operation
3607 '404':
3608 description: video does not exist
3609
3610 '/videos/{id}/transcoding':
3611 post:
3612 summary: Create a transcoding job
3613 security:
3614 - OAuth2:
3615 - admin
3616 tags:
3617 - Video Transcoding
3618 operationId: createVideoTranscoding
3619 parameters:
3620 - $ref: '#/components/parameters/idOrUUID'
3621 requestBody:
3622 content:
3623 application/json:
3624 schema:
3625 type: object
3626 properties:
3627 transcodingType:
3628 type: string
3629 enum:
3630 - hls
3631 - webtorrent
3632 required:
3633 - transcodingType
3634 responses:
3635 '204':
3636 description: successful operation
3637 '404':
3638 description: video does not exist
3639
3640 /search/videos:
3641 get:
3642 tags:
3643 - Search
3644 summary: Search videos
3645 operationId: searchVideos
3646 parameters:
3647 - name: search
3648 in: query
3649 required: true
3650 allowEmptyValue: false
3651 description: >
3652 String to search. If the user can make a remote URI search, and the string is an URI then the
3653 PeerTube instance will fetch the remote object and add it to its database. Then,
3654 you can use the REST API to fetch the complete video information and interact with it.
3655 schema:
3656 type: string
3657 - $ref: '#/components/parameters/categoryOneOf'
3658 - $ref: '#/components/parameters/isLive'
3659 - $ref: '#/components/parameters/tagsOneOf'
3660 - $ref: '#/components/parameters/tagsAllOf'
3661 - $ref: '#/components/parameters/licenceOneOf'
3662 - $ref: '#/components/parameters/languageOneOf'
3663 - $ref: '#/components/parameters/nsfw'
3664 - $ref: '#/components/parameters/isLocal'
3665 - $ref: '#/components/parameters/include'
3666 - $ref: '#/components/parameters/privacyOneOf'
3667 - $ref: '#/components/parameters/hasHLSFiles'
3668 - $ref: '#/components/parameters/hasWebtorrentFiles'
3669 - $ref: '#/components/parameters/skipCount'
3670 - $ref: '#/components/parameters/start'
3671 - $ref: '#/components/parameters/count'
3672 - $ref: '#/components/parameters/searchTarget'
3673 - $ref: '#/components/parameters/videosSearchSort'
3674 - name: startDate
3675 in: query
3676 description: Get videos that are published after this date
3677 schema:
3678 type: string
3679 format: date-time
3680 - name: endDate
3681 in: query
3682 description: Get videos that are published before this date
3683 schema:
3684 type: string
3685 format: date-time
3686 - name: originallyPublishedStartDate
3687 in: query
3688 description: Get videos that are originally published after this date
3689 schema:
3690 type: string
3691 format: date-time
3692 - name: originallyPublishedEndDate
3693 in: query
3694 description: Get videos that are originally published before this date
3695 schema:
3696 type: string
3697 format: date-time
3698 - name: durationMin
3699 in: query
3700 description: Get videos that have this minimum duration
3701 schema:
3702 type: integer
3703 - name: durationMax
3704 in: query
3705 description: Get videos that have this maximum duration
3706 schema:
3707 type: integer
3708 callbacks:
3709 'searchTarget === search-index':
3710 $ref: '#/components/callbacks/searchIndex'
3711 responses:
3712 '200':
3713 description: successful operation
3714 content:
3715 application/json:
3716 schema:
3717 $ref: '#/components/schemas/VideoListResponse'
3718 '500':
3719 description: search index unavailable
3720
3721 /search/video-channels:
3722 get:
3723 tags:
3724 - Search
3725 summary: Search channels
3726 operationId: searchChannels
3727 parameters:
3728 - name: search
3729 in: query
3730 required: true
3731 description: >
3732 String to search. If the user can make a remote URI search, and the string is an URI then the
3733 PeerTube instance will fetch the remote object and add it to its database. Then,
3734 you can use the REST API to fetch the complete channel information and interact with it.
3735 schema:
3736 type: string
3737 - $ref: '#/components/parameters/start'
3738 - $ref: '#/components/parameters/count'
3739 - $ref: '#/components/parameters/searchTarget'
3740 - $ref: '#/components/parameters/sort'
3741 callbacks:
3742 'searchTarget === search-index':
3743 $ref: '#/components/callbacks/searchIndex'
3744 responses:
3745 '200':
3746 description: successful operation
3747 content:
3748 application/json:
3749 schema:
3750 $ref: '#/components/schemas/VideoChannelList'
3751 '500':
3752 description: search index unavailable
3753
3754 /search/video-playlists:
3755 get:
3756 tags:
3757 - Search
3758 summary: Search playlists
3759 operationId: searchPlaylists
3760 parameters:
3761 - name: search
3762 in: query
3763 required: true
3764 description: >
3765 String to search. If the user can make a remote URI search, and the string is an URI then the
3766 PeerTube instance will fetch the remote object and add it to its database. Then,
3767 you can use the REST API to fetch the complete playlist information and interact with it.
3768 schema:
3769 type: string
3770 - $ref: '#/components/parameters/start'
3771 - $ref: '#/components/parameters/count'
3772 - $ref: '#/components/parameters/searchTarget'
3773 - $ref: '#/components/parameters/sort'
3774 callbacks:
3775 'searchTarget === search-index':
3776 $ref: '#/components/callbacks/searchIndex'
3777 responses:
3778 '200':
3779 description: successful operation
3780 content:
3781 application/json:
3782 schema:
3783 type: object
3784 properties:
3785 total:
3786 type: integer
3787 example: 1
3788 data:
3789 type: array
3790 items:
3791 $ref: '#/components/schemas/VideoPlaylist'
3792 '500':
3793 description: search index unavailable
3794
3795 /blocklist/status:
3796 get:
3797 tags:
3798 - Account Blocks
3799 - Server Blocks
3800 summary: Get block status of accounts/hosts
3801 parameters:
3802 -
3803 name: 'accounts'
3804 in: query
3805 description: 'Check if these accounts are blocked'
3806 example: [ 'goofy@example.com', 'donald@example.com' ]
3807 schema:
3808 type: array
3809 items:
3810 type: string
3811 -
3812 name: 'hosts'
3813 in: query
3814 description: 'Check if these hosts are blocked'
3815 example: [ 'example.com' ]
3816 schema:
3817 type: array
3818 items:
3819 type: string
3820 responses:
3821 '200':
3822 description: successful operation
3823 content:
3824 'application/json':
3825 schema:
3826 $ref: '#/components/schemas/BlockStatus'
3827
3828 /server/blocklist/accounts:
3829 get:
3830 tags:
3831 - Account Blocks
3832 summary: List account blocks
3833 security:
3834 - OAuth2:
3835 - admin
3836 parameters:
3837 - $ref: '#/components/parameters/start'
3838 - $ref: '#/components/parameters/count'
3839 - $ref: '#/components/parameters/sort'
3840 responses:
3841 '200':
3842 description: successful operation
3843 post:
3844 tags:
3845 - Account Blocks
3846 summary: Block an account
3847 security:
3848 - OAuth2:
3849 - admin
3850 requestBody:
3851 content:
3852 application/json:
3853 schema:
3854 type: object
3855 properties:
3856 accountName:
3857 type: string
3858 example: chocobozzz@example.org
3859 description: account to block, in the form `username@domain`
3860 required:
3861 - accountName
3862 responses:
3863 '200':
3864 description: successful operation
3865 '409':
3866 description: self-blocking forbidden
3867
3868 '/server/blocklist/accounts/{accountName}':
3869 delete:
3870 tags:
3871 - Account Blocks
3872 summary: Unblock an account by its handle
3873 security:
3874 - OAuth2:
3875 - admin
3876 parameters:
3877 - name: accountName
3878 in: path
3879 required: true
3880 description: account to unblock, in the form `username@domain`
3881 schema:
3882 type: string
3883 responses:
3884 '201':
3885 description: successful operation
3886 '404':
3887 description: account or account block does not exist
3888
3889 /server/blocklist/servers:
3890 get:
3891 tags:
3892 - Server Blocks
3893 summary: List server blocks
3894 security:
3895 - OAuth2:
3896 - admin
3897 parameters:
3898 - $ref: '#/components/parameters/start'
3899 - $ref: '#/components/parameters/count'
3900 - $ref: '#/components/parameters/sort'
3901 responses:
3902 '200':
3903 description: successful operation
3904 post:
3905 tags:
3906 - Server Blocks
3907 summary: Block a server
3908 security:
3909 - OAuth2:
3910 - admin
3911 requestBody:
3912 content:
3913 application/json:
3914 schema:
3915 type: object
3916 properties:
3917 host:
3918 type: string
3919 format: hostname
3920 description: server domain to block
3921 required:
3922 - host
3923 responses:
3924 '204':
3925 description: successful operation
3926 '409':
3927 description: self-blocking forbidden
3928
3929 '/server/blocklist/servers/{host}':
3930 delete:
3931 tags:
3932 - Server Blocks
3933 summary: Unblock a server by its domain
3934 security:
3935 - OAuth2:
3936 - admin
3937 parameters:
3938 - name: host
3939 in: path
3940 required: true
3941 description: server domain to unblock
3942 schema:
3943 type: string
3944 format: hostname
3945 responses:
3946 '204':
3947 description: successful operation
3948 '404':
3949 description: account block does not exist
3950
3951 /server/redundancy/{host}:
3952 put:
3953 tags:
3954 - Instance Redundancy
3955 summary: Update a server redundancy policy
3956 security:
3957 - OAuth2:
3958 - admin
3959 parameters:
3960 - name: host
3961 in: path
3962 required: true
3963 description: server domain to mirror
3964 schema:
3965 type: string
3966 format: hostname
3967 requestBody:
3968 content:
3969 application/json:
3970 schema:
3971 type: object
3972 properties:
3973 redundancyAllowed:
3974 type: boolean
3975 description: allow mirroring of the host's local videos
3976 required:
3977 - redundancyAllowed
3978 responses:
3979 '204':
3980 description: successful operation
3981 '404':
3982 description: server is not already known
3983
3984 /server/redundancy/videos:
3985 get:
3986 tags:
3987 - Video Mirroring
3988 summary: List videos being mirrored
3989 operationId: getMirroredVideos
3990 security:
3991 - OAuth2:
3992 - admin
3993 parameters:
3994 - name: target
3995 in: query
3996 required: true
3997 description: direction of the mirror
3998 schema:
3999 type: string
4000 enum:
4001 - my-videos
4002 - remote-videos
4003 - $ref: '#/components/parameters/start'
4004 - $ref: '#/components/parameters/count'
4005 - $ref: '#/components/parameters/videoRedundanciesSort'
4006 responses:
4007 '200':
4008 description: successful operation
4009 content:
4010 application/json:
4011 schema:
4012 type: array
4013 items:
4014 $ref: '#/components/schemas/VideoRedundancy'
4015 post:
4016 tags:
4017 - Video Mirroring
4018 summary: Mirror a video
4019 operationId: putMirroredVideo
4020 security:
4021 - OAuth2:
4022 - admin
4023 requestBody:
4024 content:
4025 application/json:
4026 schema:
4027 type: object
4028 properties:
4029 videoId:
4030 $ref: '#/components/schemas/Video/properties/id'
4031 required:
4032 - videoId
4033 responses:
4034 '204':
4035 description: successful operation
4036 '400':
4037 description: cannot mirror a local video
4038 '404':
4039 description: video does not exist
4040 '409':
4041 description: video is already mirrored
4042
4043 /server/redundancy/videos/{redundancyId}:
4044 delete:
4045 tags:
4046 - Video Mirroring
4047 summary: Delete a mirror done on a video
4048 operationId: delMirroredVideo
4049 security:
4050 - OAuth2:
4051 - admin
4052 parameters:
4053 - name: redundancyId
4054 in: path
4055 required: true
4056 description: id of an existing redundancy on a video
4057 schema:
4058 type: string
4059 responses:
4060 '204':
4061 description: successful operation
4062 '404':
4063 description: video redundancy not found
4064
4065 '/feeds/video-comments.{format}':
4066 get:
4067 tags:
4068 - Feeds
4069 summary: List comments on videos
4070 operationId: getSyndicatedComments
4071 parameters:
4072 - name: format
4073 in: path
4074 required: true
4075 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4076 schema:
4077 type: string
4078 enum:
4079 - xml
4080 - rss
4081 - rss2
4082 - atom
4083 - atom1
4084 - json
4085 - json1
4086 - name: videoId
4087 in: query
4088 description: 'limit listing to a specific video'
4089 schema:
4090 type: string
4091 - name: accountId
4092 in: query
4093 description: 'limit listing to a specific account'
4094 schema:
4095 type: string
4096 - name: accountName
4097 in: query
4098 description: 'limit listing to a specific account'
4099 schema:
4100 type: string
4101 - name: videoChannelId
4102 in: query
4103 description: 'limit listing to a specific video channel'
4104 schema:
4105 type: string
4106 - name: videoChannelName
4107 in: query
4108 description: 'limit listing to a specific video channel'
4109 schema:
4110 type: string
4111 responses:
4112 '204':
4113 description: successful operation
4114 headers:
4115 Cache-Control:
4116 schema:
4117 type: string
4118 default: 'max-age=900' # 15 min cache
4119 content:
4120 application/xml:
4121 schema:
4122 $ref: '#/components/schemas/VideoCommentsForXML'
4123 examples:
4124 nightly:
4125 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4126 application/rss+xml:
4127 schema:
4128 $ref: '#/components/schemas/VideoCommentsForXML'
4129 examples:
4130 nightly:
4131 externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4132 text/xml:
4133 schema:
4134 $ref: '#/components/schemas/VideoCommentsForXML'
4135 examples:
4136 nightly:
4137 externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4138 application/atom+xml:
4139 schema:
4140 $ref: '#/components/schemas/VideoCommentsForXML'
4141 examples:
4142 nightly:
4143 externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4144 application/json:
4145 schema:
4146 type: object
4147 examples:
4148 nightly:
4149 externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4150 '400':
4151 x-summary: field inconsistencies
4152 description: >
4153 Arises when:
4154 - videoId filter is mixed with a channel filter
4155 '404':
4156 description: video, video channel or account not found
4157 '406':
4158 description: accept header unsupported
4159
4160 '/feeds/videos.{format}':
4161 get:
4162 tags:
4163 - Feeds
4164 summary: List videos
4165 operationId: getSyndicatedVideos
4166 parameters:
4167 - name: format
4168 in: path
4169 required: true
4170 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4171 schema:
4172 type: string
4173 enum:
4174 - xml
4175 - rss
4176 - rss2
4177 - atom
4178 - atom1
4179 - json
4180 - json1
4181 - name: accountId
4182 in: query
4183 description: 'limit listing to a specific account'
4184 schema:
4185 type: string
4186 - name: accountName
4187 in: query
4188 description: 'limit listing to a specific account'
4189 schema:
4190 type: string
4191 - name: videoChannelId
4192 in: query
4193 description: 'limit listing to a specific video channel'
4194 schema:
4195 type: string
4196 - name: videoChannelName
4197 in: query
4198 description: 'limit listing to a specific video channel'
4199 schema:
4200 type: string
4201 - $ref: '#/components/parameters/sort'
4202 - $ref: '#/components/parameters/nsfw'
4203 - $ref: '#/components/parameters/isLocal'
4204 - $ref: '#/components/parameters/include'
4205 - $ref: '#/components/parameters/privacyOneOf'
4206 - $ref: '#/components/parameters/hasHLSFiles'
4207 - $ref: '#/components/parameters/hasWebtorrentFiles'
4208 responses:
4209 '204':
4210 description: successful operation
4211 headers:
4212 Cache-Control:
4213 schema:
4214 type: string
4215 default: 'max-age=900' # 15 min cache
4216 content:
4217 application/xml:
4218 schema:
4219 $ref: '#/components/schemas/VideosForXML'
4220 examples:
4221 nightly:
4222 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4223 application/rss+xml:
4224 schema:
4225 $ref: '#/components/schemas/VideosForXML'
4226 examples:
4227 nightly:
4228 externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4229 text/xml:
4230 schema:
4231 $ref: '#/components/schemas/VideosForXML'
4232 examples:
4233 nightly:
4234 externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4235 application/atom+xml:
4236 schema:
4237 $ref: '#/components/schemas/VideosForXML'
4238 examples:
4239 nightly:
4240 externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4241 application/json:
4242 schema:
4243 type: object
4244 examples:
4245 nightly:
4246 externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4247 '404':
4248 description: video channel or account not found
4249 '406':
4250 description: accept header unsupported
4251
4252 '/feeds/subscriptions.{format}':
4253 get:
4254 tags:
4255 - Feeds
4256 - Account
4257 summary: List videos of subscriptions tied to a token
4258 operationId: getSyndicatedSubscriptionVideos
4259 parameters:
4260 - name: format
4261 in: path
4262 required: true
4263 description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4264 schema:
4265 type: string
4266 enum:
4267 - xml
4268 - rss
4269 - rss2
4270 - atom
4271 - atom1
4272 - json
4273 - json1
4274 - name: accountId
4275 in: query
4276 description: limit listing to a specific account
4277 schema:
4278 type: string
4279 required: true
4280 - name: token
4281 in: query
4282 description: private token allowing access
4283 schema:
4284 type: string
4285 required: true
4286 - $ref: '#/components/parameters/sort'
4287 - $ref: '#/components/parameters/nsfw'
4288 - $ref: '#/components/parameters/isLocal'
4289 - $ref: '#/components/parameters/include'
4290 - $ref: '#/components/parameters/privacyOneOf'
4291 - $ref: '#/components/parameters/hasHLSFiles'
4292 - $ref: '#/components/parameters/hasWebtorrentFiles'
4293 responses:
4294 '204':
4295 description: successful operation
4296 headers:
4297 Cache-Control:
4298 schema:
4299 type: string
4300 default: 'max-age=900' # 15 min cache
4301 content:
4302 application/xml:
4303 schema:
4304 $ref: '#/components/schemas/VideosForXML'
4305 application/rss+xml:
4306 schema:
4307 $ref: '#/components/schemas/VideosForXML'
4308 text/xml:
4309 schema:
4310 $ref: '#/components/schemas/VideosForXML'
4311 application/atom+xml:
4312 schema:
4313 $ref: '#/components/schemas/VideosForXML'
4314 application/json:
4315 schema:
4316 type: object
4317 '406':
4318 description: accept header unsupported
4319
4320 /plugins:
4321 get:
4322 tags:
4323 - Plugins
4324 summary: List plugins
4325 operationId: getPlugins
4326 security:
4327 - OAuth2:
4328 - admin
4329 parameters:
4330 - name: pluginType
4331 in: query
4332 schema:
4333 type: integer
4334 - name: uninstalled
4335 in: query
4336 schema:
4337 type: boolean
4338 - $ref: '#/components/parameters/start'
4339 - $ref: '#/components/parameters/count'
4340 - $ref: '#/components/parameters/sort'
4341 responses:
4342 '200':
4343 description: successful operation
4344 content:
4345 application/json:
4346 schema:
4347 $ref: '#/components/schemas/PluginResponse'
4348
4349 /plugins/available:
4350 get:
4351 tags:
4352 - Plugins
4353 summary: List available plugins
4354 operationId: getAvailablePlugins
4355 security:
4356 - OAuth2:
4357 - admin
4358 parameters:
4359 - name: search
4360 in: query
4361 schema:
4362 type: string
4363 - name: pluginType
4364 in: query
4365 schema:
4366 type: integer
4367 - name: currentPeerTubeEngine
4368 in: query
4369 schema:
4370 type: string
4371 - $ref: '#/components/parameters/start'
4372 - $ref: '#/components/parameters/count'
4373 - $ref: '#/components/parameters/sort'
4374 responses:
4375 '200':
4376 description: successful operation
4377 content:
4378 application/json:
4379 schema:
4380 $ref: '#/components/schemas/PluginResponse'
4381 '503':
4382 description: plugin index unavailable
4383
4384 /plugins/install:
4385 post:
4386 tags:
4387 - Plugins
4388 summary: Install a plugin
4389 operationId: addPlugin
4390 security:
4391 - OAuth2:
4392 - admin
4393 requestBody:
4394 content:
4395 application/json:
4396 schema:
4397 oneOf:
4398 - type: object
4399 properties:
4400 npmName:
4401 type: string
4402 example: peertube-plugin-auth-ldap
4403 required:
4404 - npmName
4405 additionalProperties: false
4406 - type: object
4407 properties:
4408 path:
4409 type: string
4410 required:
4411 - path
4412 additionalProperties: false
4413 responses:
4414 '204':
4415 description: successful operation
4416 '400':
4417 description: should have either `npmName` or `path` set
4418
4419 /plugins/update:
4420 post:
4421 tags:
4422 - Plugins
4423 summary: Update a plugin
4424 operationId: updatePlugin
4425 security:
4426 - OAuth2:
4427 - admin
4428 requestBody:
4429 content:
4430 application/json:
4431 schema:
4432 oneOf:
4433 - type: object
4434 properties:
4435 npmName:
4436 type: string
4437 example: peertube-plugin-auth-ldap
4438 required:
4439 - npmName
4440 additionalProperties: false
4441 - type: object
4442 properties:
4443 path:
4444 type: string
4445 required:
4446 - path
4447 additionalProperties: false
4448 responses:
4449 '204':
4450 description: successful operation
4451 '400':
4452 description: should have either `npmName` or `path` set
4453 '404':
4454 description: existing plugin not found
4455
4456 /plugins/uninstall:
4457 post:
4458 tags:
4459 - Plugins
4460 summary: Uninstall a plugin
4461 operationId: uninstallPlugin
4462 security:
4463 - OAuth2:
4464 - admin
4465 requestBody:
4466 content:
4467 application/json:
4468 schema:
4469 type: object
4470 properties:
4471 npmName:
4472 type: string
4473 description: name of the plugin/theme in its package.json
4474 example: peertube-plugin-auth-ldap
4475 required:
4476 - npmName
4477 responses:
4478 '204':
4479 description: successful operation
4480 '404':
4481 description: existing plugin not found
4482
4483 /plugins/{npmName}:
4484 get:
4485 tags:
4486 - Plugins
4487 summary: Get a plugin
4488 operationId: getPlugin
4489 security:
4490 - OAuth2:
4491 - admin
4492 parameters:
4493 - $ref: '#/components/parameters/npmName'
4494 responses:
4495 '200':
4496 description: successful operation
4497 content:
4498 application/json:
4499 schema:
4500 $ref: '#/components/schemas/Plugin'
4501 '404':
4502 description: plugin not found
4503
4504 /plugins/{npmName}/settings:
4505 put:
4506 tags:
4507 - Plugins
4508 summary: Set a plugin's settings
4509 security:
4510 - OAuth2:
4511 - admin
4512 parameters:
4513 - $ref: '#/components/parameters/npmName'
4514 requestBody:
4515 content:
4516 application/json:
4517 schema:
4518 type: object
4519 properties:
4520 settings:
4521 type: object
4522 additionalProperties: true
4523 responses:
4524 '204':
4525 description: successful operation
4526 '404':
4527 description: plugin not found
4528
4529 /plugins/{npmName}/public-settings:
4530 get:
4531 tags:
4532 - Plugins
4533 summary: Get a plugin's public settings
4534 parameters:
4535 - $ref: '#/components/parameters/npmName'
4536 responses:
4537 '200':
4538 description: successful operation
4539 content:
4540 application/json:
4541 schema:
4542 type: object
4543 additionalProperties: true
4544 '404':
4545 description: plugin not found
4546
4547 /plugins/{npmName}/registered-settings:
4548 get:
4549 tags:
4550 - Plugins
4551 summary: Get a plugin's registered settings
4552 security:
4553 - OAuth2:
4554 - admin
4555 parameters:
4556 - $ref: '#/components/parameters/npmName'
4557 responses:
4558 '200':
4559 description: successful operation
4560 content:
4561 application/json:
4562 schema:
4563 type: object
4564 additionalProperties: true
4565 '404':
4566 description: plugin not found
4567
4568 servers:
4569 - url: 'https://peertube2.cpy.re/api/v1'
4570 description: Live Test Server (live data - latest nightly version)
4571 - url: 'https://peertube3.cpy.re/api/v1'
4572 description: Live Test Server (live data - latest RC version)
4573 - url: 'https://peertube.cpy.re/api/v1'
4574 description: Live Test Server (live data - stable version)
4575 components:
4576 parameters:
4577 start:
4578 name: start
4579 in: query
4580 required: false
4581 description: Offset used to paginate results
4582 schema:
4583 type: integer
4584 minimum: 0
4585 count:
4586 name: count
4587 in: query
4588 required: false
4589 description: "Number of items to return"
4590 schema:
4591 type: integer
4592 default: 15
4593 maximum: 100
4594 minimum: 1
4595 sort:
4596 name: sort
4597 in: query
4598 required: false
4599 description: Sort column
4600 schema:
4601 type: string
4602 example: -createdAt
4603 search:
4604 name: search
4605 in: query
4606 required: false
4607 description: Plain text search, applied to various parts of the model depending on endpoint
4608 schema:
4609 type: string
4610 searchTarget:
4611 name: searchTarget
4612 in: query
4613 required: false
4614 description: >
4615 If the administrator enabled search index support, you can override the default search target.
4616
4617
4618 **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4619 It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4620 * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4621 then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4622 After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4623 * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch
4624 the data from the origin instance API
4625 schema:
4626 type: string
4627 enum:
4628 - 'local'
4629 - 'search-index'
4630 videosSort:
4631 name: sort
4632 in: query
4633 required: false
4634 description: Sort videos by criteria
4635 schema:
4636 type: string
4637 enum:
4638 - name
4639 - -duration
4640 - -createdAt
4641 - -publishedAt
4642 - -views
4643 - -likes
4644 - -trending
4645 - -hot
4646 videosSearchSort:
4647 name: sort
4648 in: query
4649 required: false
4650 description: Sort videos by criteria
4651 schema:
4652 type: string
4653 enum:
4654 - name
4655 - -duration
4656 - -createdAt
4657 - -publishedAt
4658 - -views
4659 - -likes
4660 - -match
4661 commentsSort:
4662 name: sort
4663 in: query
4664 required: false
4665 description: Sort comments by criteria
4666 schema:
4667 type: string
4668 enum:
4669 - -createdAt
4670 - -totalReplies
4671 blacklistsSort:
4672 name: sort
4673 in: query
4674 required: false
4675 description: Sort blocklists by criteria
4676 schema:
4677 type: string
4678 enum:
4679 - -id
4680 - name
4681 - -duration
4682 - -views
4683 - -likes
4684 - -dislikes
4685 - -uuid
4686 - -createdAt
4687 usersSearch:
4688 name: search
4689 in: query
4690 required: false
4691 description: Plain text search that will match with user usernames or emails
4692 schema:
4693 type: string
4694 usersBlocked:
4695 name: blocked
4696 in: query
4697 required: false
4698 description: Filter results down to (un)banned users
4699 schema:
4700 type: boolean
4701 usersSort:
4702 name: sort
4703 in: query
4704 required: false
4705 description: Sort users by criteria
4706 schema:
4707 type: string
4708 enum:
4709 - -id
4710 - -username
4711 - -createdAt
4712 abusesSort:
4713 name: sort
4714 in: query
4715 required: false
4716 description: Sort abuses by criteria
4717 schema:
4718 type: string
4719 enum:
4720 - -id
4721 - -createdAt
4722 - -state
4723 videoRedundanciesSort:
4724 name: sort
4725 in: query
4726 required: false
4727 description: Sort abuses by criteria
4728 schema:
4729 type: string
4730 enum:
4731 - name
4732 followersSort:
4733 name: sort
4734 in: query
4735 required: false
4736 description: Sort followers by criteria
4737 schema:
4738 type: string
4739 enum:
4740 - createdAt
4741 name:
4742 name: name
4743 in: path
4744 required: true
4745 description: The username or handle of the account
4746 schema:
4747 type: string
4748 example: chocobozzz | chocobozzz@example.org
4749 id:
4750 name: id
4751 in: path
4752 required: true
4753 description: The user id
4754 schema:
4755 $ref: '#/components/schemas/id'
4756 idOrUUID:
4757 name: id
4758 in: path
4759 required: true
4760 description: The object id, uuid or short uuid
4761 schema:
4762 oneOf:
4763 - $ref: '#/components/schemas/id'
4764 - $ref: '#/components/schemas/UUIDv4'
4765 - $ref: '#/components/schemas/shortUUID'
4766 playlistId:
4767 name: playlistId
4768 in: path
4769 required: true
4770 description: Playlist id
4771 schema:
4772 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4773 playlistElementId:
4774 name: playlistElementId
4775 in: path
4776 required: true
4777 description: Playlist element id
4778 schema:
4779 $ref: '#/components/schemas/id'
4780 abuseId:
4781 name: abuseId
4782 in: path
4783 required: true
4784 description: Abuse id
4785 schema:
4786 $ref: '#/components/schemas/Abuse/properties/id'
4787 abuseMessageId:
4788 name: abuseMessageId
4789 in: path
4790 required: true
4791 description: Abuse message id
4792 schema:
4793 $ref: '#/components/schemas/AbuseMessage/properties/id'
4794 captionLanguage:
4795 name: captionLanguage
4796 in: path
4797 required: true
4798 description: The caption language
4799 schema:
4800 $ref: '#/components/schemas/VideoLanguageSet'
4801 channelHandle:
4802 name: channelHandle
4803 in: path
4804 required: true
4805 description: The video channel handle
4806 schema:
4807 type: string
4808 example: my_username | my_username@example.com
4809 subscriptionHandle:
4810 name: subscriptionHandle
4811 in: path
4812 required: true
4813 description: The subscription handle
4814 schema:
4815 type: string
4816 example: my_username | my_username@example.com
4817 threadId:
4818 name: threadId
4819 in: path
4820 required: true
4821 description: The thread id (root comment id)
4822 schema:
4823 type: integer
4824 commentId:
4825 name: commentId
4826 in: path
4827 required: true
4828 description: The comment id
4829 schema:
4830 $ref: '#/components/schemas/VideoComment/properties/id'
4831 isLive:
4832 name: isLive
4833 in: query
4834 required: false
4835 description: whether or not the video is a live
4836 schema:
4837 type: boolean
4838 categoryOneOf:
4839 name: categoryOneOf
4840 in: query
4841 required: false
4842 description: category id of the video (see [/videos/categories](#operation/getCategories))
4843 schema:
4844 oneOf:
4845 - $ref: '#/components/schemas/VideoCategorySet'
4846 - type: array
4847 items:
4848 $ref: '#/components/schemas/VideoCategorySet'
4849 style: form
4850 explode: false
4851 tagsOneOf:
4852 name: tagsOneOf
4853 in: query
4854 required: false
4855 description: tag(s) of the video
4856 schema:
4857 oneOf:
4858 - type: string
4859 - type: array
4860 maxItems: 5
4861 items:
4862 type: string
4863 style: form
4864 explode: false
4865 tagsAllOf:
4866 name: tagsAllOf
4867 in: query
4868 required: false
4869 description: tag(s) of the video, where all should be present in the video
4870 schema:
4871 oneOf:
4872 - type: string
4873 - type: array
4874 items:
4875 type: string
4876 style: form
4877 explode: false
4878 languageOneOf:
4879 name: languageOneOf
4880 in: query
4881 required: false
4882 description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4883 schema:
4884 oneOf:
4885 - $ref: '#/components/schemas/VideoLanguageSet'
4886 - type: array
4887 items:
4888 $ref: '#/components/schemas/VideoLanguageSet'
4889 style: form
4890 explode: false
4891 licenceOneOf:
4892 name: licenceOneOf
4893 in: query
4894 required: false
4895 description: licence id of the video (see [/videos/licences](#operation/getLicences))
4896 schema:
4897 oneOf:
4898 - $ref: '#/components/schemas/VideoLicenceSet'
4899 - type: array
4900 items:
4901 $ref: '#/components/schemas/VideoLicenceSet'
4902 style: form
4903 explode: false
4904 skipCount:
4905 name: skipCount
4906 in: query
4907 required: false
4908 description: if you don't need the `total` in the response
4909 schema:
4910 type: string
4911 enum:
4912 - 'true'
4913 - 'false'
4914 default: 'false'
4915 nsfw:
4916 name: nsfw
4917 in: query
4918 required: false
4919 description: whether to include nsfw videos, if any
4920 schema:
4921 type: string
4922 enum:
4923 - 'true'
4924 - 'false'
4925 isLocal:
4926 name: isLocal
4927 in: query
4928 required: false
4929 schema:
4930 type: boolean
4931 description: '**PeerTube >= 4.0** Display only local or remote videos'
4932 hasHLSFiles:
4933 name: hasHLSFiles
4934 in: query
4935 required: false
4936 schema:
4937 type: boolean
4938 description: '**PeerTube >= 4.0** Display only videos that have HLS files'
4939 hasWebtorrentFiles:
4940 name: hasWebtorrentFiles
4941 in: query
4942 required: false
4943 schema:
4944 type: boolean
4945 description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
4946 privacyOneOf:
4947 name: privacyOneOf
4948 in: query
4949 required: false
4950 schema:
4951 $ref: '#/components/schemas/VideoPrivacySet'
4952 description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
4953 include:
4954 name: include
4955 in: query
4956 required: false
4957 schema:
4958 type: integer
4959 enum:
4960 - 0
4961 - 1
4962 - 2
4963 - 4
4964 - 8
4965 description: >
4966 **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
4967
4968 - `0` NONE
4969
4970 - `1` NOT_PUBLISHED_STATE
4971
4972 - `2` BLACKLISTED
4973
4974 - `4` BLOCKED_OWNER
4975
4976 - `8` FILES
4977 subscriptionsUris:
4978 name: uris
4979 in: query
4980 required: true
4981 description: list of uris to check if each is part of the user subscriptions
4982 schema:
4983 type: array
4984 items:
4985 type: string
4986 format: uri
4987 npmName:
4988 name: npmName
4989 in: path
4990 required: true
4991 description: name of the plugin/theme on npmjs.com or in its package.json
4992 schema:
4993 type: string
4994 example: peertube-plugin-auth-ldap
4995 jobType:
4996 name: jobType
4997 in: query
4998 required: false
4999 description: job type
5000 schema:
5001 type: string
5002 enum:
5003 - activitypub-follow
5004 - activitypub-http-broadcast
5005 - activitypub-http-fetcher
5006 - activitypub-http-unicast
5007 - email
5008 - video-transcoding
5009 - video-file-import
5010 - video-import
5011 - videos-views-stats
5012 - activitypub-refresher
5013 - video-redundancy
5014 - video-live-ending
5015 followState:
5016 name: state
5017 in: query
5018 schema:
5019 type: string
5020 enum:
5021 - pending
5022 - accepted
5023 actorType:
5024 name: actorType
5025 in: query
5026 schema:
5027 type: string
5028 enum:
5029 - Person
5030 - Application
5031 - Group
5032 - Service
5033 - Organization
5034 securitySchemes:
5035 OAuth2:
5036 description: |
5037 Authenticating via OAuth requires the following steps:
5038 - Have an activated account
5039 - [Generate] an access token for that account at `/api/v1/users/token`.
5040 - Make requests with the *Authorization: Bearer <token\>* header
5041 - Profit, depending on the role assigned to the account
5042
5043 Note that the __access token is valid for 1 day__ and is given
5044 along with a __refresh token valid for 2 weeks__.
5045
5046 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5047 type: oauth2
5048 flows:
5049 password:
5050 tokenUrl: /api/v1/users/token
5051 scopes:
5052 admin: Admin scope
5053 moderator: Moderator scope
5054 user: User scope
5055 schemas:
5056 # Resuable core properties
5057 id:
5058 type: integer
5059 minimum: 1
5060 example: 42
5061 UUIDv4:
5062 type: string
5063 format: uuid
5064 example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5065 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5066 minLength: 36
5067 maxLength: 36
5068 shortUUID:
5069 type: string
5070 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5071 example: 2y84q2MQUMWPbiEcxNXMgC
5072 username:
5073 type: string
5074 description: immutable name of the user, used to find or mention its actor
5075 example: chocobozzz
5076 pattern: '/^[a-z0-9._]+$/'
5077 minLength: 1
5078 maxLength: 50
5079 usernameChannel:
5080 type: string
5081 description: immutable name of the channel, used to interact with its actor
5082 example: framasoft_videos
5083 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5084 minLength: 1
5085 maxLength: 50
5086 password:
5087 type: string
5088 format: password
5089 minLength: 6
5090 maxLength: 255
5091
5092 VideoCategorySet:
5093 type: integer
5094 description: category id of the video (see [/videos/categories](#operation/getCategories))
5095 example: 15
5096 VideoConstantNumber-Category:
5097 properties:
5098 id:
5099 $ref: '#/components/schemas/VideoCategorySet'
5100 label:
5101 type: string
5102 example: Science & Technology
5103
5104 VideoLicenceSet:
5105 type: integer
5106 description: licence id of the video (see [/videos/licences](#operation/getLicences))
5107 example: 2
5108 VideoConstantNumber-Licence:
5109 properties:
5110 id:
5111 $ref: '#/components/schemas/VideoLicenceSet'
5112 label:
5113 type: string
5114 example: Attribution - Share Alike
5115
5116 VideoLanguageSet:
5117 type: string
5118 description: language id of the video (see [/videos/languages](#operation/getLanguages))
5119 example: en
5120 VideoConstantString-Language:
5121 properties:
5122 id:
5123 $ref: '#/components/schemas/VideoLanguageSet'
5124 label:
5125 type: string
5126 example: English
5127
5128 VideoPlaylistPrivacySet:
5129 type: integer
5130 enum:
5131 - 1
5132 - 2
5133 - 3
5134 description: Video playlist privacy policy (see [/video-playlists/privacies])
5135 VideoPlaylistPrivacyConstant:
5136 properties:
5137 id:
5138 $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5139 label:
5140 type: string
5141
5142 VideoPlaylistTypeSet:
5143 type: integer
5144 enum:
5145 - 1
5146 - 2
5147 description: The video playlist type (Regular = `1`, Watch Later = `2`)
5148 VideoPlaylistTypeConstant:
5149 properties:
5150 id:
5151 $ref: '#/components/schemas/VideoPlaylistTypeSet'
5152 label:
5153 type: string
5154
5155 VideoPrivacySet:
5156 type: integer
5157 enum:
5158 - 1
5159 - 2
5160 - 3
5161 - 4
5162 description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5163 VideoPrivacyConstant:
5164 properties:
5165 id:
5166 $ref: '#/components/schemas/VideoPrivacySet'
5167 label:
5168 type: string
5169
5170 BlockStatus:
5171 properties:
5172 accounts:
5173 type: object
5174 additionalProperties:
5175 x-additionalPropertiesName: account
5176 type: object
5177 properties:
5178 blockedByServer:
5179 type: boolean
5180 blockedByUser:
5181 type: boolean
5182 hosts:
5183 type: object
5184 additionalProperties:
5185 x-additionalPropertiesName: host
5186 type: object
5187 properties:
5188 blockedByServer:
5189 type: boolean
5190 blockedByUser:
5191 type: boolean
5192
5193 NSFWPolicy:
5194 type: string
5195 enum:
5196 - display
5197 - blur
5198 - do_not_list
5199
5200 UserRole:
5201 type: integer
5202 enum:
5203 - 0
5204 - 1
5205 - 2
5206 description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5207 example: 2
5208 UserAdminFlags:
5209 type: integer
5210 enum:
5211 - 0
5212 - 1
5213 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5214 example: 1
5215
5216 VideoStateConstant:
5217 properties:
5218 id:
5219 type: integer
5220 enum:
5221 - 1
5222 - 2
5223 - 3
5224 description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5225 label:
5226 type: string
5227
5228 AbuseStateSet:
5229 type: integer
5230 enum:
5231 - 1
5232 - 2
5233 - 3
5234 description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5235 AbuseStateConstant:
5236 properties:
5237 id:
5238 $ref: '#/components/schemas/AbuseStateSet'
5239 label:
5240 type: string
5241 AbusePredefinedReasons:
5242 type: array
5243 items:
5244 type: string
5245 enum:
5246 - violentOrAbusive
5247 - hatefulOrAbusive
5248 - spamOrMisleading
5249 - privacy
5250 - rights
5251 - serverRules
5252 - thumbnails
5253 - captions
5254 example: [spamOrMisleading]
5255
5256 VideoResolutionSet:
5257 type: integer
5258 description: |
5259 Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5260
5261 `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5262 example: 240
5263 VideoResolutionConstant:
5264 description: resolutions and their labels for the video
5265 properties:
5266 id:
5267 $ref: '#/components/schemas/VideoResolutionSet'
5268 label:
5269 type: string
5270 example: 240p
5271 VideoScheduledUpdate:
5272 properties:
5273 privacy:
5274 $ref: '#/components/schemas/VideoPrivacySet'
5275 updateAt:
5276 type: string
5277 format: date
5278 description: When to update the video
5279 required:
5280 - updateAt
5281 AccountSummary:
5282 properties:
5283 id:
5284 type: integer
5285 name:
5286 type: string
5287 displayName:
5288 type: string
5289 url:
5290 type: string
5291 format: url
5292 host:
5293 type: string
5294 format: hostname
5295 avatar:
5296 nullable: true
5297 allOf:
5298 - $ref: '#/components/schemas/ActorImage'
5299 VideoChannelSummary:
5300 properties:
5301 id:
5302 $ref: '#/components/schemas/id'
5303 name:
5304 type: string
5305 displayName:
5306 type: string
5307 url:
5308 type: string
5309 format: url
5310 host:
5311 type: string
5312 format: hostname
5313 avatar:
5314 nullable: true
5315 allOf:
5316 - $ref: '#/components/schemas/ActorImage'
5317 PlaylistElement:
5318 properties:
5319 position:
5320 type: integer
5321 startTimestamp:
5322 type: integer
5323 format: seconds
5324 stopTimestamp:
5325 type: integer
5326 format: seconds
5327 video:
5328 nullable: true
5329 allOf:
5330 - $ref: '#/components/schemas/Video'
5331 VideoFile:
5332 readOnly: true
5333 properties:
5334 magnetUri:
5335 type: string
5336 format: uri
5337 description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5338 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5339 resolution:
5340 $ref: '#/components/schemas/VideoResolutionConstant'
5341 size:
5342 type: integer
5343 description: Video file size in bytes
5344 torrentUrl:
5345 type: string
5346 description: Direct URL of the torrent file
5347 format: url
5348 torrentDownloadUrl:
5349 type: string
5350 description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5351 format: url
5352 fileUrl:
5353 type: string
5354 description: Direct URL of the video
5355 format: url
5356 fileDownloadUrl:
5357 type: string
5358 description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5359 format: url
5360 fps:
5361 type: number
5362 description: Frames per second of the video file
5363 metadataUrl:
5364 type: string
5365 format: url
5366 description: URL dereferencing the output of ffprobe on the file
5367 VideoStreamingPlaylists:
5368 allOf:
5369 - type: object
5370 properties:
5371 id:
5372 $ref: '#/components/schemas/id'
5373 type:
5374 type: integer
5375 enum:
5376 - 1
5377 description: |
5378 Playlist type:
5379 - `1`: HLS
5380 - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5381 VideoStreamingPlaylists-HLS:
5382 properties:
5383 playlistUrl:
5384 type: string
5385 format: url
5386 segmentsSha256Url:
5387 type: string
5388 format: url
5389 files:
5390 type: array
5391 description: |
5392 Video files associated to this playlist.
5393
5394 The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5395 items:
5396 $ref: '#/components/schemas/VideoFile'
5397 redundancies:
5398 type: array
5399 items:
5400 type: object
5401 properties:
5402 baseUrl:
5403 type: string
5404 format: url
5405 VideoInfo:
5406 properties:
5407 id:
5408 $ref: '#/components/schemas/Video/properties/id'
5409 uuid:
5410 $ref: '#/components/schemas/Video/properties/uuid'
5411 name:
5412 $ref: '#/components/schemas/Video/properties/name'
5413 Video:
5414 properties:
5415 id:
5416 description: object id for the video
5417 allOf:
5418 - $ref: '#/components/schemas/id'
5419 uuid:
5420 description: universal identifier for the video, that can be used across instances
5421 allOf:
5422 - $ref: '#/components/schemas/UUIDv4'
5423 shortUUID:
5424 allOf:
5425 - $ref: '#/components/schemas/shortUUID'
5426 isLive:
5427 type: boolean
5428 createdAt:
5429 type: string
5430 format: date-time
5431 example: 2017-10-01T10:52:46.396Z
5432 description: time at which the video object was first drafted
5433 publishedAt:
5434 type: string
5435 format: date-time
5436 example: 2018-10-01T10:52:46.396Z
5437 description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5438 updatedAt:
5439 type: string
5440 format: date-time
5441 example: 2021-05-04T08:01:01.502Z
5442 description: last time the video's metadata was modified
5443 originallyPublishedAt:
5444 type: string
5445 format: date-time
5446 example: 2010-10-01T10:52:46.396Z
5447 description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5448 category:
5449 allOf:
5450 - $ref: '#/components/schemas/VideoConstantNumber-Category'
5451 description: category in which the video is classified
5452 licence:
5453 allOf:
5454 - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5455 description: licence under which the video is distributed
5456 language:
5457 allOf:
5458 - $ref: '#/components/schemas/VideoConstantString-Language'
5459 description: main language used in the video
5460 privacy:
5461 allOf:
5462 - $ref: '#/components/schemas/VideoPrivacyConstant'
5463 description: privacy policy used to distribute the video
5464 description:
5465 type: string
5466 example: |
5467 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5468 **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5469 minLength: 3
5470 maxLength: 250
5471 description: |
5472 truncated description of the video, written in Markdown.
5473 Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5474 duration:
5475 type: integer
5476 example: 1419
5477 format: seconds
5478 description: duration of the video in seconds
5479 isLocal:
5480 type: boolean
5481 name:
5482 type: string
5483 description: title of the video
5484 example: What is PeerTube?
5485 minLength: 3
5486 maxLength: 120
5487 thumbnailPath:
5488 type: string
5489 example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5490 previewPath:
5491 type: string
5492 example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5493 embedPath:
5494 type: string
5495 example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5496 views:
5497 type: integer
5498 example: 1337
5499 likes:
5500 type: integer
5501 example: 42
5502 dislikes:
5503 type: integer
5504 example: 7
5505 nsfw:
5506 type: boolean
5507 waitTranscoding:
5508 type: boolean
5509 nullable: true
5510 state:
5511 allOf:
5512 - $ref: '#/components/schemas/VideoStateConstant'
5513 description: represents the internal state of the video processing within the PeerTube instance
5514 scheduledUpdate:
5515 nullable: true
5516 allOf:
5517 - $ref: '#/components/schemas/VideoScheduledUpdate'
5518 blacklisted:
5519 nullable: true
5520 type: boolean
5521 blacklistedReason:
5522 nullable: true
5523 type: string
5524 account:
5525 $ref: '#/components/schemas/AccountSummary'
5526 channel:
5527 $ref: '#/components/schemas/VideoChannelSummary'
5528 userHistory:
5529 nullable: true
5530 type: object
5531 properties:
5532 currentTime:
5533 type: integer
5534 VideoDetails:
5535 allOf:
5536 - $ref: '#/components/schemas/Video'
5537 - type: object
5538 properties:
5539 viewers:
5540 type: integer
5541 description: If the video is a live, you have the amount of current viewers
5542 descriptionPath:
5543 type: string
5544 example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5545 description: path at which to get the full description of maximum `10000` characters
5546 support:
5547 type: string
5548 description: A text tell the audience how to support the video creator
5549 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5550 minLength: 3
5551 maxLength: 1000
5552 channel:
5553 $ref: '#/components/schemas/VideoChannel'
5554 account:
5555 $ref: '#/components/schemas/Account'
5556 tags:
5557 example: [flowers, gardening]
5558 type: array
5559 minItems: 1
5560 maxItems: 5
5561 items:
5562 type: string
5563 minLength: 2
5564 maxLength: 30
5565 commentsEnabled:
5566 type: boolean
5567 downloadEnabled:
5568 type: boolean
5569 trackerUrls:
5570 type: array
5571 items:
5572 type: string
5573 format: url
5574 example:
5575 - https://peertube2.cpy.re/tracker/announce
5576 - wss://peertube2.cpy.re/tracker/socket
5577 files:
5578 type: array
5579 items:
5580 $ref: '#/components/schemas/VideoFile'
5581 description: |
5582 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5583
5584 - field will be empty
5585 - video files will be found in `streamingPlaylists[].files` field
5586 streamingPlaylists:
5587 type: array
5588 items:
5589 $ref: '#/components/schemas/VideoStreamingPlaylists'
5590 description: |
5591 HLS playlists/manifest files. If HLS is disabled on the server:
5592
5593 - field will be empty
5594 - video files will be found in `files` field
5595 FileRedundancyInformation:
5596 properties:
5597 id:
5598 $ref: '#/components/schemas/id'
5599 fileUrl:
5600 type: string
5601 format: url
5602 strategy:
5603 type: string
5604 enum:
5605 - manual
5606 - most-views
5607 - trending
5608 - recently-added
5609 size:
5610 type: integer
5611 createdAt:
5612 type: string
5613 format: date-time
5614 updatedAt:
5615 type: string
5616 format: date-time
5617 expiresOn:
5618 type: string
5619 format: date-time
5620 VideoRedundancy:
5621 properties:
5622 id:
5623 $ref: '#/components/schemas/id'
5624 name:
5625 type: string
5626 url:
5627 type: string
5628 format: url
5629 uuid:
5630 $ref: '#/components/schemas/UUIDv4'
5631 redundancies:
5632 type: object
5633 properties:
5634 files:
5635 type: array
5636 items:
5637 $ref: '#/components/schemas/FileRedundancyInformation'
5638 streamingPlaylists:
5639 type: array
5640 items:
5641 $ref: '#/components/schemas/FileRedundancyInformation'
5642 VideoImportStateConstant:
5643 properties:
5644 id:
5645 type: integer
5646 enum:
5647 - 1
5648 - 2
5649 - 3
5650 description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5651 label:
5652 type: string
5653 example: Pending
5654 VideoCreateImport:
5655 allOf:
5656 - type: object
5657 additionalProperties: false
5658 oneOf:
5659 - properties:
5660 targetUrl:
5661 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5662 required: [targetUrl]
5663 - properties:
5664 magnetUri:
5665 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5666 required: [magnetUri]
5667 - properties:
5668 torrentfile:
5669 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5670 required: [torrentfile]
5671 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5672 required:
5673 - channelId
5674 - name
5675 VideoImport:
5676 properties:
5677 id:
5678 readOnly: true
5679 allOf:
5680 - $ref: '#/components/schemas/id'
5681 targetUrl:
5682 type: string
5683 format: url
5684 description: remote URL where to find the import's source video
5685 example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5686 magnetUri:
5687 type: string
5688 format: uri
5689 description: magnet URI allowing to resolve the import's source video
5690 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5691 torrentfile:
5692 writeOnly: true
5693 type: string
5694 format: binary
5695 description: Torrent file containing only the video file
5696 torrentName:
5697 readOnly: true
5698 type: string
5699 state:
5700 readOnly: true
5701 allOf:
5702 - $ref: '#/components/schemas/VideoImportStateConstant'
5703 error:
5704 readOnly: true
5705 type: string
5706 createdAt:
5707 readOnly: true
5708 type: string
5709 format: date-time
5710 updatedAt:
5711 readOnly: true
5712 type: string
5713 format: date-time
5714 video:
5715 readOnly: true
5716 nullable: true
5717 allOf:
5718 - $ref: '#/components/schemas/Video'
5719 VideoImportsList:
5720 properties:
5721 total:
5722 type: integer
5723 example: 1
5724 data:
5725 type: array
5726 maxItems: 100
5727 items:
5728 $ref: '#/components/schemas/VideoImport'
5729 Abuse:
5730 properties:
5731 id:
5732 $ref: '#/components/schemas/id'
5733 reason:
5734 type: string
5735 example: The video is a spam
5736 minLength: 2
5737 maxLength: 3000
5738 predefinedReasons:
5739 $ref: '#/components/schemas/AbusePredefinedReasons'
5740 reporterAccount:
5741 $ref: '#/components/schemas/Account'
5742 state:
5743 $ref: '#/components/schemas/AbuseStateConstant'
5744 moderationComment:
5745 type: string
5746 example: Decided to ban the server since it spams us regularly
5747 minLength: 2
5748 maxLength: 3000
5749 video:
5750 $ref: '#/components/schemas/VideoInfo'
5751 createdAt:
5752 type: string
5753 format: date-time
5754 AbuseMessage:
5755 properties:
5756 id:
5757 $ref: '#/components/schemas/id'
5758 message:
5759 type: string
5760 minLength: 2
5761 maxLength: 3000
5762 byModerator:
5763 type: boolean
5764 createdAt:
5765 type: string
5766 format: date-time
5767 account:
5768 $ref: '#/components/schemas/AccountSummary'
5769 VideoBlacklist:
5770 properties:
5771 id:
5772 $ref: '#/components/schemas/id'
5773 videoId:
5774 $ref: '#/components/schemas/Video/properties/id'
5775 createdAt:
5776 type: string
5777 format: date-time
5778 updatedAt:
5779 type: string
5780 format: date-time
5781 name:
5782 type: string
5783 minLength: 3
5784 maxLength: 120
5785 uuid:
5786 $ref: '#/components/schemas/UUIDv4'
5787 description:
5788 type: string
5789 minLength: 3
5790 maxLength: 10000
5791 duration:
5792 type: integer
5793 views:
5794 type: integer
5795 likes:
5796 type: integer
5797 dislikes:
5798 type: integer
5799 nsfw:
5800 type: boolean
5801 VideoPlaylist:
5802 properties:
5803 id:
5804 $ref: '#/components/schemas/id'
5805 uuid:
5806 $ref: '#/components/schemas/UUIDv4'
5807 shortUUID:
5808 allOf:
5809 - $ref: '#/components/schemas/shortUUID'
5810 createdAt:
5811 type: string
5812 format: date-time
5813 updatedAt:
5814 type: string
5815 format: date-time
5816 description:
5817 type: string
5818 minLength: 3
5819 maxLength: 1000
5820 displayName:
5821 type: string
5822 minLength: 1
5823 maxLength: 120
5824 isLocal:
5825 type: boolean
5826 videoLength:
5827 type: integer
5828 minimum: 0
5829 thumbnailPath:
5830 type: string
5831 privacy:
5832 $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5833 type:
5834 $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5835 ownerAccount:
5836 $ref: '#/components/schemas/AccountSummary'
5837 videoChannel:
5838 $ref: '#/components/schemas/VideoChannelSummary'
5839 VideoComment:
5840 properties:
5841 id:
5842 $ref: '#/components/schemas/id'
5843 url:
5844 type: string
5845 format: url
5846 text:
5847 type: string
5848 format: html
5849 description: Text of the comment
5850 minLength: 1
5851 example: This video is wonderful!
5852 threadId:
5853 $ref: '#/components/schemas/id'
5854 inReplyToCommentId:
5855 nullable: true
5856 allOf:
5857 - $ref: '#/components/schemas/id'
5858 videoId:
5859 $ref: '#/components/schemas/Video/properties/id'
5860 createdAt:
5861 type: string
5862 format: date-time
5863 updatedAt:
5864 type: string
5865 format: date-time
5866 deletedAt:
5867 nullable: true
5868 type: string
5869 format: date-time
5870 default: null
5871 isDeleted:
5872 type: boolean
5873 default: false
5874 totalRepliesFromVideoAuthor:
5875 type: integer
5876 minimum: 0
5877 totalReplies:
5878 type: integer
5879 minimum: 0
5880 account:
5881 $ref: '#/components/schemas/Account'
5882 VideoCommentThreadTree:
5883 properties:
5884 comment:
5885 $ref: '#/components/schemas/VideoComment'
5886 children:
5887 type: array
5888 items:
5889 $ref: '#/components/schemas/VideoCommentThreadTree'
5890 VideoCaption:
5891 properties:
5892 language:
5893 $ref: '#/components/schemas/VideoConstantString-Language'
5894 captionPath:
5895 type: string
5896 ActorImage:
5897 properties:
5898 path:
5899 type: string
5900 createdAt:
5901 type: string
5902 format: date-time
5903 updatedAt:
5904 type: string
5905 format: date-time
5906 ActorInfo:
5907 properties:
5908 id:
5909 $ref: '#/components/schemas/id'
5910 name:
5911 type: string
5912 displayName:
5913 type: string
5914 host:
5915 type: string
5916 format: hostname
5917 avatar:
5918 nullable: true
5919 type: object
5920 properties:
5921 path:
5922 type: string
5923 Actor:
5924 properties:
5925 id:
5926 $ref: '#/components/schemas/id'
5927 url:
5928 type: string
5929 format: url
5930 name:
5931 description: immutable name of the actor, used to find or mention it
5932 allOf:
5933 - $ref: '#/components/schemas/username'
5934 host:
5935 type: string
5936 format: hostname
5937 description: server on which the actor is resident
5938 hostRedundancyAllowed:
5939 type: boolean
5940 description: whether this actor's host allows redundancy of its videos
5941 followingCount:
5942 type: integer
5943 minimum: 0
5944 description: number of actors subscribed to by this actor, as seen by this instance
5945 followersCount:
5946 type: integer
5947 minimum: 0
5948 description: number of followers of this actor, as seen by this instance
5949 createdAt:
5950 type: string
5951 format: date-time
5952 updatedAt:
5953 type: string
5954 format: date-time
5955 avatar:
5956 $ref: '#/components/schemas/ActorImage'
5957 Account:
5958 allOf:
5959 - $ref: '#/components/schemas/Actor'
5960 - properties:
5961 userId:
5962 description: object id for the user tied to this account
5963 allOf:
5964 - $ref: '#/components/schemas/User/properties/id'
5965 displayName:
5966 type: string
5967 description: editable name of the account, displayed in its representations
5968 minLength: 3
5969 maxLength: 120
5970 description:
5971 type: string
5972 description: text or bio displayed on the account's profile
5973 UserWatchingVideo:
5974 properties:
5975 currentTime:
5976 type: integer
5977 format: seconds
5978 description: timestamp within the video, in seconds
5979 example: 5
5980 ServerConfig:
5981 properties:
5982 instance:
5983 type: object
5984 properties:
5985 name:
5986 type: string
5987 shortDescription:
5988 type: string
5989 defaultClientRoute:
5990 type: string
5991 isNSFW:
5992 type: boolean
5993 defaultNSFWPolicy:
5994 type: string
5995 customizations:
5996 type: object
5997 properties:
5998 javascript:
5999 type: string
6000 css:
6001 type: string
6002 search:
6003 type: object
6004 properties:
6005 remoteUri:
6006 type: object
6007 properties:
6008 users:
6009 type: boolean
6010 anonymous:
6011 type: boolean
6012 plugin:
6013 type: object
6014 properties:
6015 registered:
6016 type: array
6017 items:
6018 type: string
6019 theme:
6020 type: object
6021 properties:
6022 registered:
6023 type: array
6024 items:
6025 type: string
6026 email:
6027 type: object
6028 properties:
6029 enabled:
6030 type: boolean
6031 contactForm:
6032 type: object
6033 properties:
6034 enabled:
6035 type: boolean
6036 serverVersion:
6037 type: string
6038 serverCommit:
6039 type: string
6040 signup:
6041 type: object
6042 properties:
6043 allowed:
6044 type: boolean
6045 allowedForCurrentIP:
6046 type: boolean
6047 requiresEmailVerification:
6048 type: boolean
6049 transcoding:
6050 type: object
6051 properties:
6052 hls:
6053 type: object
6054 properties:
6055 enabled:
6056 type: boolean
6057 webtorrent:
6058 type: object
6059 properties:
6060 enabled:
6061 type: boolean
6062 enabledResolutions:
6063 type: array
6064 items:
6065 $ref: '#/components/schemas/VideoResolutionSet'
6066 import:
6067 type: object
6068 properties:
6069 videos:
6070 type: object
6071 properties:
6072 http:
6073 type: object
6074 properties:
6075 enabled:
6076 type: boolean
6077 torrent:
6078 type: object
6079 properties:
6080 enabled:
6081 type: boolean
6082 autoBlacklist:
6083 type: object
6084 properties:
6085 videos:
6086 type: object
6087 properties:
6088 ofUsers:
6089 type: object
6090 properties:
6091 enabled:
6092 type: boolean
6093 avatar:
6094 type: object
6095 properties:
6096 file:
6097 type: object
6098 properties:
6099 size:
6100 type: object
6101 properties:
6102 max:
6103 type: integer
6104 extensions:
6105 type: array
6106 items:
6107 type: string
6108 video:
6109 type: object
6110 properties:
6111 image:
6112 type: object
6113 properties:
6114 extensions:
6115 type: array
6116 items:
6117 type: string
6118 size:
6119 type: object
6120 properties:
6121 max:
6122 type: integer
6123 file:
6124 type: object
6125 properties:
6126 extensions:
6127 type: array
6128 items:
6129 type: string
6130 videoCaption:
6131 type: object
6132 properties:
6133 file:
6134 type: object
6135 properties:
6136 size:
6137 type: object
6138 properties:
6139 max:
6140 type: integer
6141 extensions:
6142 type: array
6143 items:
6144 type: string
6145 user:
6146 type: object
6147 properties:
6148 videoQuota:
6149 type: integer
6150 example: 16810141515
6151 videoQuotaDaily:
6152 type: integer
6153 example: 1681014151
6154 trending:
6155 type: object
6156 properties:
6157 videos:
6158 type: object
6159 properties:
6160 intervalDays:
6161 type: integer
6162 tracker:
6163 type: object
6164 properties:
6165 enabled:
6166 type: boolean
6167 followings:
6168 type: object
6169 properties:
6170 instance:
6171 type: object
6172 properties:
6173 autoFollowIndex:
6174 type: object
6175 properties:
6176 indexUrl:
6177 type: string
6178 format: url
6179 homepage:
6180 type: object
6181 properties:
6182 enabled:
6183 type: boolean
6184
6185 ServerConfigAbout:
6186 properties:
6187 instance:
6188 type: object
6189 properties:
6190 name:
6191 type: string
6192 shortDescription:
6193 type: string
6194 description:
6195 type: string
6196 terms:
6197 type: string
6198 ServerConfigCustom:
6199 properties:
6200 instance:
6201 type: object
6202 properties:
6203 name:
6204 type: string
6205 shortDescription:
6206 type: string
6207 description:
6208 type: string
6209 terms:
6210 type: string
6211 defaultClientRoute:
6212 type: string
6213 isNSFW:
6214 type: boolean
6215 defaultNSFWPolicy:
6216 type: string
6217 customizations:
6218 type: object
6219 properties:
6220 javascript:
6221 type: string
6222 css:
6223 type: string
6224 theme:
6225 type: object
6226 properties:
6227 default:
6228 type: string
6229 services:
6230 type: object
6231 properties:
6232 twitter:
6233 type: object
6234 properties:
6235 username:
6236 type: string
6237 whitelisted:
6238 type: boolean
6239 cache:
6240 type: object
6241 properties:
6242 previews:
6243 type: object
6244 properties:
6245 size:
6246 type: integer
6247 captions:
6248 type: object
6249 properties:
6250 size:
6251 type: integer
6252 signup:
6253 type: object
6254 properties:
6255 enabled:
6256 type: boolean
6257 limit:
6258 type: integer
6259 requiresEmailVerification:
6260 type: boolean
6261 admin:
6262 type: object
6263 properties:
6264 email:
6265 type: string
6266 format: email
6267 contactForm:
6268 type: object
6269 properties:
6270 enabled:
6271 type: boolean
6272 user:
6273 type: object
6274 description: Settings that apply to new users, if registration is enabled
6275 properties:
6276 videoQuota:
6277 type: integer
6278 example: 16810141515
6279 videoQuotaDaily:
6280 type: integer
6281 example: 1681014151
6282 transcoding:
6283 type: object
6284 description: Settings pertaining to transcoding jobs
6285 properties:
6286 enabled:
6287 type: boolean
6288 allowAdditionalExtensions:
6289 type: boolean
6290 description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6291 allowAudioFiles:
6292 type: boolean
6293 description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6294 threads:
6295 type: integer
6296 description: Amount of threads used by ffmpeg for 1 transcoding job
6297 concurrency:
6298 type: number
6299 description: Amount of transcoding jobs to execute in parallel
6300 profile:
6301 type: string
6302 enum:
6303 - default
6304 description: |
6305 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6306 resolutions:
6307 type: object
6308 description: Resolutions to transcode _new videos_ to
6309 properties:
6310 0p:
6311 type: boolean
6312 144p:
6313 type: boolean
6314 240p:
6315 type: boolean
6316 360p:
6317 type: boolean
6318 480p:
6319 type: boolean
6320 720p:
6321 type: boolean
6322 1080p:
6323 type: boolean
6324 1440p:
6325 type: boolean
6326 2160p:
6327 type: boolean
6328 webtorrent:
6329 type: object
6330 description: WebTorrent-specific settings
6331 properties:
6332 enabled:
6333 type: boolean
6334 hls:
6335 type: object
6336 description: HLS-specific settings
6337 properties:
6338 enabled:
6339 type: boolean
6340 import:
6341 type: object
6342 properties:
6343 videos:
6344 type: object
6345 properties:
6346 http:
6347 type: object
6348 properties:
6349 enabled:
6350 type: boolean
6351 torrent:
6352 type: object
6353 properties:
6354 enabled:
6355 type: boolean
6356 autoBlacklist:
6357 type: object
6358 properties:
6359 videos:
6360 type: object
6361 properties:
6362 ofUsers:
6363 type: object
6364 properties:
6365 enabled:
6366 type: boolean
6367 followers:
6368 type: object
6369 properties:
6370 instance:
6371 type: object
6372 properties:
6373 enabled:
6374 type: boolean
6375 manualApproval:
6376 type: boolean
6377
6378 CustomHomepage:
6379 properties:
6380 content:
6381 type: string
6382
6383 Follow:
6384 properties:
6385 id:
6386 $ref: '#/components/schemas/id'
6387 follower:
6388 $ref: '#/components/schemas/Actor'
6389 following:
6390 $ref: '#/components/schemas/Actor'
6391 score:
6392 type: number
6393 description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6394 state:
6395 type: string
6396 enum:
6397 - pending
6398 - accepted
6399 createdAt:
6400 type: string
6401 format: date-time
6402 updatedAt:
6403 type: string
6404 format: date-time
6405
6406 PredefinedAbuseReasons:
6407 description: Reason categories that help triage reports
6408 type: array
6409 maxItems: 8
6410 items:
6411 type: string
6412 enum:
6413 - violentOrAbusive
6414 - hatefulOrAbusive
6415 - spamOrMisleading
6416 - privacy
6417 - rights
6418 - serverRules
6419 - thumbnails
6420 - captions
6421
6422 Job:
6423 properties:
6424 id:
6425 $ref: '#/components/schemas/id'
6426 state:
6427 type: string
6428 enum:
6429 - active
6430 - completed
6431 - failed
6432 - waiting
6433 - delayed
6434 type:
6435 type: string
6436 enum:
6437 - activitypub-http-unicast
6438 - activitypub-http-broadcast
6439 - activitypub-http-fetcher
6440 - activitypub-follow
6441 - video-file-import
6442 - video-transcoding
6443 - email
6444 - video-import
6445 - videos-views-stats
6446 - activitypub-refresher
6447 - video-redundancy
6448 data:
6449 type: object
6450 additionalProperties: true
6451 error:
6452 type: object
6453 additionalProperties: true
6454 createdAt:
6455 type: string
6456 format: date-time
6457 finishedOn:
6458 type: string
6459 format: date-time
6460 processedOn:
6461 type: string
6462 format: date-time
6463 AddUserResponse:
6464 properties:
6465 user:
6466 type: object
6467 properties:
6468 id:
6469 $ref: '#/components/schemas/id'
6470 account:
6471 type: object
6472 properties:
6473 id:
6474 $ref: '#/components/schemas/id'
6475 VideoUploadRequestCommon:
6476 properties:
6477 name:
6478 description: Video name
6479 type: string
6480 example: What is PeerTube?
6481 minLength: 3
6482 maxLength: 120
6483 channelId:
6484 description: Channel id that will contain this video
6485 type: integer
6486 example: 3
6487 minimum: 1
6488 privacy:
6489 $ref: '#/components/schemas/VideoPrivacySet'
6490 category:
6491 $ref: '#/components/schemas/VideoCategorySet'
6492 licence:
6493 $ref: '#/components/schemas/VideoLicenceSet'
6494 language:
6495 $ref: '#/components/schemas/VideoLanguageSet'
6496 description:
6497 description: Video description
6498 type: string
6499 example: |
6500 **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
6501 waitTranscoding:
6502 description: Whether or not we wait transcoding before publish the video
6503 type: boolean
6504 support:
6505 description: A text tell the audience how to support the video creator
6506 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6507 type: string
6508 nsfw:
6509 description: Whether or not this video contains sensitive content
6510 type: boolean
6511 tags:
6512 description: Video tags (maximum 5 tags each between 2 and 30 characters)
6513 type: array
6514 minItems: 1
6515 maxItems: 5
6516 uniqueItems: true
6517 example:
6518 - framasoft
6519 - peertube
6520 items:
6521 type: string
6522 minLength: 2
6523 maxLength: 30
6524 commentsEnabled:
6525 description: Enable or disable comments for this video
6526 type: boolean
6527 downloadEnabled:
6528 description: Enable or disable downloading for this video
6529 type: boolean
6530 originallyPublishedAt:
6531 description: Date when the content was originally published
6532 type: string
6533 format: date-time
6534 scheduleUpdate:
6535 $ref: '#/components/schemas/VideoScheduledUpdate'
6536 thumbnailfile:
6537 description: Video thumbnail file
6538 type: string
6539 format: binary
6540 previewfile:
6541 description: Video preview file
6542 type: string
6543 format: binary
6544 required:
6545 - channelId
6546 - name
6547 VideoUploadRequestLegacy:
6548 allOf:
6549 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6550 - type: object
6551 required:
6552 - videofile
6553 properties:
6554 videofile:
6555 description: Video file
6556 type: string
6557 format: binary
6558 VideoUploadRequestResumable:
6559 allOf:
6560 - $ref: '#/components/schemas/VideoUploadRequestCommon'
6561 - type: object
6562 required:
6563 - filename
6564 properties:
6565 filename:
6566 description: Video filename including extension
6567 type: string
6568 format: filename
6569 example: what_is_peertube.mp4
6570 thumbnailfile:
6571 description: Video thumbnail file
6572 type: string
6573 format: binary
6574 previewfile:
6575 description: Video preview file
6576 type: string
6577 format: binary
6578 VideoUploadResponse:
6579 properties:
6580 video:
6581 type: object
6582 properties:
6583 id:
6584 $ref: '#/components/schemas/Video/properties/id'
6585 uuid:
6586 $ref: '#/components/schemas/Video/properties/uuid'
6587 shortUUID:
6588 $ref: '#/components/schemas/Video/properties/shortUUID'
6589 CommentThreadResponse:
6590 properties:
6591 total:
6592 type: integer
6593 example: 1
6594 data:
6595 type: array
6596 maxItems: 100
6597 items:
6598 $ref: '#/components/schemas/VideoComment'
6599 CommentThreadPostResponse:
6600 properties:
6601 comment:
6602 $ref: '#/components/schemas/VideoComment'
6603 VideoListResponse:
6604 properties:
6605 total:
6606 type: integer
6607 example: 1
6608 data:
6609 type: array
6610 maxItems: 100
6611 items:
6612 $ref: '#/components/schemas/Video'
6613 User:
6614 properties:
6615 account:
6616 $ref: '#/components/schemas/Account'
6617 autoPlayNextVideo:
6618 type: boolean
6619 description: Automatically start playing the upcoming video after the currently playing video
6620 autoPlayNextVideoPlaylist:
6621 type: boolean
6622 description: Automatically start playing the video on the playlist after the currently playing video
6623 autoPlayVideo:
6624 type: boolean
6625 description: Automatically start playing the video on the watch page
6626 blocked:
6627 type: boolean
6628 blockedReason:
6629 type: string
6630 createdAt:
6631 type: string
6632 email:
6633 type: string
6634 format: email
6635 description: The user email
6636 emailVerified:
6637 type: boolean
6638 description: Has the user confirmed their email address?
6639 id:
6640 allOf:
6641 - $ref: '#/components/schemas/id'
6642 readOnly: true
6643 pluginAuth:
6644 type: string
6645 description: Auth plugin to use to authenticate the user
6646 lastLoginDate:
6647 type: string
6648 format: date-time
6649 noInstanceConfigWarningModal:
6650 type: boolean
6651 noAccountSetupWarningModal:
6652 type: boolean
6653 noWelcomeModal:
6654 type: boolean
6655 nsfwPolicy:
6656 $ref: '#/components/schemas/NSFWPolicy'
6657 role:
6658 $ref: '#/components/schemas/UserRole'
6659 roleLabel:
6660 type: string
6661 enum:
6662 - User
6663 - Moderator
6664 - Administrator
6665 theme:
6666 type: string
6667 description: Theme enabled by this user
6668 username:
6669 $ref: '#/components/schemas/username'
6670 videoChannels:
6671 type: array
6672 items:
6673 $ref: '#/components/schemas/VideoChannel'
6674 videoQuota:
6675 type: integer
6676 description: The user video quota in bytes
6677 example: -1
6678 videoQuotaDaily:
6679 type: integer
6680 description: The user daily video quota in bytes
6681 example: -1
6682 p2pEnabled:
6683 type: boolean
6684 description: Enable P2P in the player
6685 UserWithStats:
6686 allOf:
6687 - $ref: '#/components/schemas/User'
6688 - properties:
6689 # optionally present fields: they require WITH_STATS scope
6690 videosCount:
6691 type: integer
6692 description: Count of videos published
6693 abusesCount:
6694 type: integer
6695 description: Count of reports/abuses of which the user is a target
6696 abusesAcceptedCount:
6697 type: integer
6698 description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6699 abusesCreatedCount:
6700 type: integer
6701 description: Count of reports/abuses created by the user
6702 videoCommentsCount:
6703 type: integer
6704 description: Count of comments published
6705 AddUser:
6706 properties:
6707 username:
6708 $ref: '#/components/schemas/username'
6709 password:
6710 $ref: '#/components/schemas/password'
6711 email:
6712 type: string
6713 format: email
6714 description: The user email
6715 videoQuota:
6716 type: integer
6717 description: The user video quota in bytes
6718 example: -1
6719 videoQuotaDaily:
6720 type: integer
6721 description: The user daily video quota in bytes
6722 example: -1
6723 channelName:
6724 $ref: '#/components/schemas/usernameChannel'
6725 role:
6726 $ref: '#/components/schemas/UserRole'
6727 adminFlags:
6728 $ref: '#/components/schemas/UserAdminFlags'
6729 required:
6730 - username
6731 - password
6732 - email
6733 - videoQuota
6734 - videoQuotaDaily
6735 - role
6736 UpdateUser:
6737 properties:
6738 email:
6739 description: The updated email of the user
6740 allOf:
6741 - $ref: '#/components/schemas/User/properties/email'
6742 emailVerified:
6743 type: boolean
6744 description: Set the email as verified
6745 videoQuota:
6746 type: integer
6747 description: The updated video quota of the user in bytes
6748 videoQuotaDaily:
6749 type: integer
6750 description: The updated daily video quota of the user in bytes
6751 pluginAuth:
6752 type: string
6753 nullable: true
6754 description: The auth plugin to use to authenticate the user
6755 example: 'peertube-plugin-auth-saml2'
6756 role:
6757 $ref: '#/components/schemas/UserRole'
6758 adminFlags:
6759 $ref: '#/components/schemas/UserAdminFlags'
6760 UpdateMe:
6761 # see shared/models/users/user-update-me.model.ts:
6762 properties:
6763 password:
6764 $ref: '#/components/schemas/password'
6765 currentPassword:
6766 $ref: '#/components/schemas/password'
6767 email:
6768 description: new email used for login and service communications
6769 allOf:
6770 - $ref: '#/components/schemas/User/properties/email'
6771 displayName:
6772 type: string
6773 description: new name of the user in its representations
6774 minLength: 3
6775 maxLength: 120
6776 displayNSFW:
6777 type: string
6778 description: new NSFW display policy
6779 enum:
6780 - 'true'
6781 - 'false'
6782 - both
6783 p2pEnabled:
6784 type: boolean
6785 description: whether to enable P2P in the player or not
6786 autoPlayVideo:
6787 type: boolean
6788 description: new preference regarding playing videos automatically
6789 autoPlayNextVideo:
6790 type: boolean
6791 description: new preference regarding playing following videos automatically
6792 autoPlayNextVideoPlaylist:
6793 type: boolean
6794 description: new preference regarding playing following playlist videos automatically
6795 videosHistoryEnabled:
6796 type: boolean
6797 description: whether to keep track of watched history or not
6798 videoLanguages:
6799 type: array
6800 items:
6801 type: string
6802 description: list of languages to filter videos down to
6803 theme:
6804 type: string
6805 noInstanceConfigWarningModal:
6806 type: boolean
6807 noAccountSetupWarningModal:
6808 type: boolean
6809 noWelcomeModal:
6810 type: boolean
6811 GetMeVideoRating:
6812 properties:
6813 id:
6814 $ref: '#/components/schemas/id'
6815 rating:
6816 type: string
6817 enum:
6818 - like
6819 - dislike
6820 - none
6821 description: Rating of the video
6822 required:
6823 - id
6824 - rating
6825 VideoRating:
6826 properties:
6827 video:
6828 $ref: '#/components/schemas/Video'
6829 rating:
6830 type: string
6831 enum:
6832 - like
6833 - dislike
6834 - none
6835 description: Rating of the video
6836 required:
6837 - video
6838 - rating
6839 RegisterUser:
6840 properties:
6841 username:
6842 description: immutable name of the user, used to find or mention its actor
6843 allOf:
6844 - $ref: '#/components/schemas/username'
6845 password:
6846 $ref: '#/components/schemas/password'
6847 email:
6848 type: string
6849 format: email
6850 description: email of the user, used for login or service communications
6851 displayName:
6852 type: string
6853 description: editable name of the user, displayed in its representations
6854 minLength: 1
6855 maxLength: 120
6856 channel:
6857 type: object
6858 description: channel base information used to create the first channel of the user
6859 properties:
6860 name:
6861 $ref: '#/components/schemas/usernameChannel'
6862 displayName:
6863 $ref: '#/components/schemas/VideoChannel/properties/displayName'
6864 required:
6865 - username
6866 - password
6867 - email
6868
6869 OAuthClient:
6870 properties:
6871 client_id:
6872 type: string
6873 pattern: /^[a-z0-9]$/
6874 maxLength: 32
6875 minLength: 32
6876 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6877 client_secret:
6878 type: string
6879 pattern: /^[a-zA-Z0-9]$/
6880 maxLength: 32
6881 minLength: 32
6882 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6883 OAuthToken-password:
6884 allOf:
6885 - $ref: '#/components/schemas/OAuthClient'
6886 - type: object
6887 properties:
6888 grant_type:
6889 type: string
6890 enum:
6891 - password
6892 - refresh_token
6893 default: password
6894 username:
6895 $ref: '#/components/schemas/User/properties/username'
6896 password:
6897 $ref: '#/components/schemas/password'
6898 required:
6899 - client_id
6900 - client_secret
6901 - grant_type
6902 - username
6903 - password
6904 OAuthToken-refresh_token:
6905 allOf:
6906 - $ref: '#/components/schemas/OAuthClient'
6907 - type: object
6908 properties:
6909 grant_type:
6910 type: string
6911 enum:
6912 - password
6913 - refresh_token
6914 default: password
6915 refresh_token:
6916 type: string
6917 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6918 required:
6919 - client_id
6920 - client_secret
6921 - grant_type
6922 - refresh_token
6923
6924 VideoChannel:
6925 properties:
6926 # GET/POST/PUT properties
6927 displayName:
6928 type: string
6929 description: editable name of the channel, displayed in its representations
6930 example: Videos of Framasoft
6931 minLength: 1
6932 maxLength: 120
6933 description:
6934 type: string
6935 example: Videos made with <3 by Framasoft
6936 minLength: 3
6937 maxLength: 1000
6938 support:
6939 type: string
6940 description: text shown by default on all videos of this channel, to tell the audience how to support it
6941 example: Please support our work on https://soutenir.framasoft.org/en/ <3
6942 minLength: 3
6943 maxLength: 1000
6944 # GET-only properties
6945 id:
6946 readOnly: true
6947 allOf:
6948 - $ref: '#/components/schemas/id'
6949 isLocal:
6950 readOnly: true
6951 type: boolean
6952 updatedAt:
6953 readOnly: true
6954 type: string
6955 format: date-time
6956 ownerAccount:
6957 readOnly: true
6958 nullable: true
6959 type: object
6960 properties:
6961 id:
6962 type: integer
6963 uuid:
6964 $ref: '#/components/schemas/UUIDv4'
6965 VideoChannelCreate:
6966 allOf:
6967 - $ref: '#/components/schemas/VideoChannel'
6968 - properties:
6969 name:
6970 description: username of the channel to create
6971 allOf:
6972 - $ref: '#/components/schemas/usernameChannel'
6973 required:
6974 - name
6975 - displayName
6976 VideoChannelUpdate:
6977 allOf:
6978 - $ref: '#/components/schemas/VideoChannel'
6979 - properties:
6980 bulkVideosSupportUpdate:
6981 type: boolean
6982 description: Update the support field for all videos of this channel
6983 VideoChannelList:
6984 properties:
6985 total:
6986 type: integer
6987 example: 1
6988 data:
6989 type: array
6990 items:
6991 allOf:
6992 - $ref: '#/components/schemas/VideoChannel'
6993 - $ref: '#/components/schemas/Actor'
6994
6995 MRSSPeerLink:
6996 type: object
6997 xml:
6998 name: 'media:peerLink'
6999 properties:
7000 href:
7001 type: string
7002 xml:
7003 attribute: true
7004 type:
7005 type: string
7006 enum:
7007 - application/x-bittorrent
7008 xml:
7009 attribute: true
7010 MRSSGroupContent:
7011 type: object
7012 xml:
7013 name: 'media:content'
7014 properties:
7015 url:
7016 type: string
7017 format: url
7018 xml:
7019 attribute: true
7020 fileSize:
7021 type: integer
7022 xml:
7023 attribute: true
7024 type:
7025 type: string
7026 xml:
7027 attribute: true
7028 framerate:
7029 type: integer
7030 xml:
7031 attribute: true
7032 duration:
7033 type: integer
7034 xml:
7035 attribute: true
7036 height:
7037 type: integer
7038 xml:
7039 attribute: true
7040 lang:
7041 type: string
7042 xml:
7043 attribute: true
7044 VideoCommentsForXML:
7045 type: array
7046 xml:
7047 wrapped: true
7048 name: 'channel'
7049 items:
7050 type: object
7051 xml:
7052 name: 'item'
7053 properties:
7054 link:
7055 type: string
7056 format: url
7057 guid:
7058 type: string
7059 pubDate:
7060 type: string
7061 format: date-time
7062 'content:encoded':
7063 type: string
7064 'dc:creator':
7065 type: string
7066 VideosForXML:
7067 type: array
7068 xml:
7069 wrapped: true
7070 name: 'channel'
7071 items:
7072 type: object
7073 xml:
7074 name: 'item'
7075 properties:
7076 link:
7077 type: string
7078 format: url
7079 description: video watch page URL
7080 guid:
7081 type: string
7082 description: video canonical URL
7083 pubDate:
7084 type: string
7085 format: date-time
7086 description: video publication date
7087 description:
7088 type: string
7089 description: video description
7090 'content:encoded':
7091 type: string
7092 description: video description
7093 'dc:creator':
7094 type: string
7095 description: publisher user name
7096 'media:category':
7097 type: integer
7098 description: video category (MRSS)
7099 'media:community':
7100 type: object
7101 description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7102 properties:
7103 'media:statistics':
7104 type: object
7105 properties:
7106 views:
7107 type: integer
7108 xml:
7109 attribute: true
7110 'media:embed':
7111 type: object
7112 properties:
7113 url:
7114 type: string
7115 format: url
7116 description: video embed path, relative to the canonical URL domain (MRSS)
7117 xml:
7118 attribute: true
7119 'media:player':
7120 type: object
7121 properties:
7122 url:
7123 type: string
7124 format: url
7125 description: video watch path, relative to the canonical URL domain (MRSS)
7126 xml:
7127 attribute: true
7128 'media:thumbnail':
7129 type: object
7130 properties:
7131 url:
7132 type: string
7133 format: url
7134 xml:
7135 attribute: true
7136 height:
7137 type: integer
7138 xml:
7139 attribute: true
7140 width:
7141 type: integer
7142 xml:
7143 attribute: true
7144 'media:title':
7145 type: string
7146 description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7147 'media:description':
7148 type: string
7149 'media:rating':
7150 type: string
7151 enum:
7152 - nonadult
7153 - adult
7154 description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7155 'enclosure':
7156 type: object
7157 description: main streamable file for the video
7158 properties:
7159 url:
7160 type: string
7161 format: url
7162 xml:
7163 attribute: true
7164 type:
7165 type: string
7166 enum:
7167 - application/x-bittorrent
7168 xml:
7169 attribute: true
7170 length:
7171 type: integer
7172 xml:
7173 attribute: true
7174 'media:group':
7175 type: array
7176 description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or (MRSS)
7177 items:
7178 anyOf:
7179 - $ref: '#/components/schemas/MRSSPeerLink'
7180 - $ref: '#/components/schemas/MRSSGroupContent'
7181 NotificationSettingValue:
7182 type: integer
7183 description: >
7184 Notification type
7185
7186 - `0` NONE
7187
7188 - `1` WEB
7189
7190 - `2` EMAIL
7191 enum:
7192 - 0
7193 - 1
7194 - 2
7195 Notification:
7196 properties:
7197 id:
7198 $ref: '#/components/schemas/id'
7199 type:
7200 type: integer
7201 description: >
7202 Notification type, following the `UserNotificationType` enum:
7203
7204 - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7205
7206 - `2` NEW_COMMENT_ON_MY_VIDEO
7207
7208 - `3` NEW_ABUSE_FOR_MODERATORS
7209
7210 - `4` BLACKLIST_ON_MY_VIDEO
7211
7212 - `5` UNBLACKLIST_ON_MY_VIDEO
7213
7214 - `6` MY_VIDEO_PUBLISHED
7215
7216 - `7` MY_VIDEO_IMPORT_SUCCESS
7217
7218 - `8` MY_VIDEO_IMPORT_ERROR
7219
7220 - `9` NEW_USER_REGISTRATION
7221
7222 - `10` NEW_FOLLOW
7223
7224 - `11` COMMENT_MENTION
7225
7226 - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7227
7228 - `13` NEW_INSTANCE_FOLLOWER
7229
7230 - `14` AUTO_INSTANCE_FOLLOWING
7231 read:
7232 type: boolean
7233 video:
7234 nullable: true
7235 allOf:
7236 - $ref: '#/components/schemas/VideoInfo'
7237 - type: object
7238 properties:
7239 channel:
7240 $ref: '#/components/schemas/ActorInfo'
7241 videoImport:
7242 nullable: true
7243 type: object
7244 properties:
7245 id:
7246 $ref: '#/components/schemas/id'
7247 video:
7248 nullable: true
7249 $ref: '#/components/schemas/VideoInfo'
7250 torrentName:
7251 type: string
7252 nullable: true
7253 magnetUri:
7254 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7255 targetUri:
7256 type: string
7257 format: uri
7258 nullable: true
7259 comment:
7260 nullable: true
7261 type: object
7262 properties:
7263 id:
7264 $ref: '#/components/schemas/id'
7265 threadId:
7266 type: integer
7267 video:
7268 $ref: '#/components/schemas/VideoInfo'
7269 account:
7270 $ref: '#/components/schemas/ActorInfo'
7271 videoAbuse:
7272 nullable: true
7273 type: object
7274 properties:
7275 id:
7276 $ref: '#/components/schemas/id'
7277 video:
7278 allOf:
7279 - $ref: '#/components/schemas/VideoInfo'
7280 videoBlacklist:
7281 nullable: true
7282 type: object
7283 properties:
7284 id:
7285 $ref: '#/components/schemas/id'
7286 video:
7287 allOf:
7288 - $ref: '#/components/schemas/VideoInfo'
7289 account:
7290 nullable: true
7291 allOf:
7292 - $ref: '#/components/schemas/ActorInfo'
7293 actorFollow:
7294 type: object
7295 nullable: true
7296 properties:
7297 id:
7298 $ref: '#/components/schemas/id'
7299 follower:
7300 $ref: '#/components/schemas/ActorInfo'
7301 state:
7302 type: string
7303 enum:
7304 - pending
7305 - accepted
7306 following:
7307 type: object
7308 properties:
7309 type:
7310 type: string
7311 enum:
7312 - account
7313 - channel
7314 - instance
7315 name:
7316 type: string
7317 displayName:
7318 type: string
7319 host:
7320 type: string
7321 format: hostname
7322 createdAt:
7323 type: string
7324 format: date-time
7325 updatedAt:
7326 type: string
7327 format: date-time
7328 NotificationListResponse:
7329 properties:
7330 total:
7331 type: integer
7332 example: 1
7333 data:
7334 type: array
7335 maxItems: 100
7336 items:
7337 $ref: '#/components/schemas/Notification'
7338 Plugin:
7339 properties:
7340 name:
7341 type: string
7342 example: peertube-plugin-auth-ldap
7343 type:
7344 type: integer
7345 description: >
7346 - `1`: PLUGIN
7347
7348 - `2`: THEME
7349 enum:
7350 - 1
7351 - 2
7352 latestVersion:
7353 type: string
7354 example: 0.0.3
7355 version:
7356 type: string
7357 example: 0.0.1
7358 enabled:
7359 type: boolean
7360 uninstalled:
7361 type: boolean
7362 peertubeEngine:
7363 type: string
7364 example: 2.2.0
7365 description:
7366 type: string
7367 homepage:
7368 type: string
7369 format: url
7370 example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7371 settings:
7372 type: object
7373 additionalProperties: true
7374 createdAt:
7375 type: string
7376 format: date-time
7377 updatedAt:
7378 type: string
7379 format: date-time
7380 PluginResponse:
7381 properties:
7382 total:
7383 type: integer
7384 example: 1
7385 data:
7386 type: array
7387 maxItems: 100
7388 items:
7389 $ref: '#/components/schemas/Plugin'
7390
7391 LiveVideoUpdate:
7392 properties:
7393 saveReplay:
7394 type: boolean
7395 permanentLive:
7396 description: User can stream multiple times in a permanent live
7397 type: boolean
7398
7399 LiveVideoResponse:
7400 properties:
7401 rtmpUrl:
7402 type: string
7403 rtmpsUrl:
7404 type: string
7405 streamKey:
7406 type: string
7407 description: RTMP stream key to use to stream into this live video
7408 saveReplay:
7409 type: boolean
7410 permanentLive:
7411 description: User can stream multiple times in a permanent live
7412 type: boolean
7413
7414
7415
7416 callbacks:
7417 searchIndex:
7418 'https://search.example.org/api/v1/search/videos':
7419 post:
7420 summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7421 responses:
7422 '200':
7423 description: successful operation
7424 content:
7425 application/json:
7426 schema:
7427 $ref: '#/components/schemas/VideoListResponse'