aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc')
-rw-r--r--support/doc/api/openapi.yaml1226
-rw-r--r--support/doc/dependencies.md28
-rw-r--r--support/doc/plugins/guide.md39
3 files changed, 1027 insertions, 266 deletions
diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 7b619b59c..99a725ead 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -1,15 +1,15 @@
1openapi: 3.0.0 1openapi: 3.0.0
2info: 2info:
3 title: PeerTube 3 title: PeerTube
4 version: 3.2.1 4 version: 3.3.0
5 contact: 5 contact:
6 name: PeerTube Community 6 name: PeerTube Community
7 url: 'https://joinpeertube.org' 7 url: https://joinpeertube.org
8 license: 8 license:
9 name: AGPLv3.0 9 name: AGPLv3.0
10 url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE' 10 url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
11 x-logo: 11 x-logo:
12 url: 'https://joinpeertube.org/img/brand.png' 12 url: https://joinpeertube.org/img/brand.png
13 altText: PeerTube Project Homepage 13 altText: PeerTube Project Homepage
14 description: | 14 description: |
15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite 15 The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
@@ -22,13 +22,13 @@ info:
22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) 22 - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)
23 23
24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few 24 See the [REST API quick start](https://docs.joinpeertube.org/api-rest-getting-started) for a few
25 examples of using with the PeerTube API. 25 examples of using the PeerTube API.
26 26
27 # Authentication 27 # Authentication
28 28
29 When you sign up for an account on a PeerTube instance, you are given the possibility 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 a session token. Only __one 30 to generate sessions on it, and authenticate there using an access token. Only __one
31 session token can currently be used at a time__. 31 access token can currently be used at a time__.
32 32
33 ## Roles 33 ## Roles
34 34
@@ -38,41 +38,91 @@ info:
38 # Errors 38 # Errors
39 39
40 The API uses standard HTTP status codes to indicate the success or failure 40 The API uses standard HTTP status codes to indicate the success or failure
41 of the API call. The body of the response will be JSON in the following 41 of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.
42 formats.
43 42
44 ``` 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
45 { 64 {
46 "error": "Account not found" // error debug message 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"
47 } 70 }
48 ``` 71 ```
49 72
50 Some errors benefit from a more detailed message: 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
51 ``` 81 ```
82 HTTP 1.1 400 Bad Request
83 Content-Type: application/problem+json; charset=utf-8
84
52 { 85 {
53 "errors": { 86 "detail": "Incorrect request parameters: id",
54 "id": { // where 'id' is the name of the parameter concerned by the error. 87 "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
55 "value": "a117eb-c6a9-4756-bb09-2a956239f", // value that triggered the error. 88 "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
56 "msg": "Should have an valid id", // error debug message 89 "invalid-params": {
90 "id": {
91 "location": "params",
92 "msg": "Invalid value",
57 "param": "id", 93 "param": "id",
58 "location": "params" // 'params', 'body', 'header', 'query' or 'cookies' 94 "value": "9c9de5e8-0a1e-484a-b099-e80766180"
59 } 95 }
60 } 96 },
97 "status": 400,
98 "title": "Bad Request",
99 "type": "about:blank"
61 } 100 }
62 ``` 101 ```
63 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
64 # Rate limits 114 # Rate limits
65 115
66 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: 116 We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
67 117
68 | Endpoint | Calls | Time frame | 118 | Endpoint (prefix: `/api/v1`) | Calls | Time frame |
69 |-------------------------|------------------|---------------------------| 119 |------------------------------|---------------|--------------|
70 | `/*` | 50 | 10 seconds | 120 | `/*` | 50 | 10 seconds |
71 | `POST /users/token` | 15 | 5 minutes | 121 | `POST /users/token` | 15 | 5 minutes |
72 | `POST /users/register` | 2¹ | 5 minutes | 122 | `POST /users/register` | 2<sup>*</sup> | 5 minutes |
73 | `POST /users/ask-send-verify-email` | 3 | 5 minutes | 123 | `POST /users/ask-send-verify-email` | 3 | 5 minutes |
74 124
75 Depending on the endpoint, ¹failed requests are not taken into account. A service 125 Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
76 limit is announced by a `429 Too Many Requests` status code. 126 limit is announced by a `429 Too Many Requests` status code.
77 127
78 You can get details about the current state of your rate limit by reading the 128 You can get details about the current state of your rate limit by reading the
@@ -80,13 +130,37 @@ info:
80 130
81 | Header | Description | 131 | Header | Description |
82 |-------------------------|------------------------------------------------------------| 132 |-------------------------|------------------------------------------------------------|
83 | X-RateLimit-Limit | Number of max requests allowed in the current time period | 133 | `X-RateLimit-Limit` | Number of max requests allowed in the current time period |
84 | X-RateLimit-Remaining | Number of remaining requests in the current time period | 134 | `X-RateLimit-Remaining` | Number of remaining requests in the current time period |
85 | X-RateLimit-Reset | Timestamp of end of current time period as UNIX timestamp | 135 | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp |
86 | Retry-After | Seconds to delay after the first `429` is received | 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.
87externalDocs: 152externalDocs:
88 url: https://docs.joinpeertube.org/api-rest-reference.html 153 url: https://docs.joinpeertube.org/api-rest-reference.html
89tags: 154tags:
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__.
90 - name: Accounts 164 - name: Accounts
91 description: > 165 description: >
92 Accounts encompass remote accounts discovered across the federation, 166 Accounts encompass remote accounts discovered across the federation,
@@ -204,12 +278,18 @@ tags:
204 278
205 Administrators can also enable the use of a remote search system, indexing 279 Administrators can also enable the use of a remote search system, indexing
206 videos and channels not could be not federated by the instance. 280 videos and channels not could be not federated by the instance.
281 - name: Homepage
282 description: Get and update the custom homepage
207 - name: Video Mirroring 283 - name: Video Mirroring
208 description: | 284 description: |
209 PeerTube instances can mirror videos from one another, and help distribute some videos. 285 PeerTube instances can mirror videos from one another, and help distribute some videos.
210 286
211 For importing videos as your own, refer to [video imports](#operation/importVideo). 287 For importing videos as your own, refer to [video imports](#operation/importVideo).
212x-tagGroups: 288x-tagGroups:
289 - name: Auth
290 tags:
291 - Register
292 - Session
213 - name: Accounts 293 - name: Accounts
214 tags: 294 tags:
215 - Accounts 295 - Accounts
@@ -234,6 +314,9 @@ x-tagGroups:
234 - name: Search 314 - name: Search
235 tags: 315 tags:
236 - Search 316 - Search
317 - name: Custom pages
318 tags:
319 - Homepage
237 - name: Moderation 320 - name: Moderation
238 tags: 321 tags:
239 - Abuses 322 - Abuses
@@ -255,6 +338,7 @@ paths:
255 tags: 338 tags:
256 - Accounts 339 - Accounts
257 summary: Get an account 340 summary: Get an account
341 operationId: getAccount
258 parameters: 342 parameters:
259 - $ref: '#/components/parameters/name' 343 - $ref: '#/components/parameters/name'
260 responses: 344 responses:
@@ -266,12 +350,14 @@ paths:
266 $ref: '#/components/schemas/Account' 350 $ref: '#/components/schemas/Account'
267 '404': 351 '404':
268 description: account not found 352 description: account not found
353
269 '/accounts/{name}/videos': 354 '/accounts/{name}/videos':
270 get: 355 get:
271 tags: 356 tags:
272 - Accounts 357 - Accounts
273 - Video 358 - Video
274 summary: 'List videos of an account' 359 summary: 'List videos of an account'
360 operationId: getAccountVideos
275 parameters: 361 parameters:
276 - $ref: '#/components/parameters/name' 362 - $ref: '#/components/parameters/name'
277 - $ref: '#/components/parameters/categoryOneOf' 363 - $ref: '#/components/parameters/categoryOneOf'
@@ -327,11 +413,13 @@ paths:
327 json = r.json() 413 json = r.json()
328 414
329 print(json) 415 print(json)
416
330 /accounts: 417 /accounts:
331 get: 418 get:
332 tags: 419 tags:
333 - Accounts 420 - Accounts
334 summary: List accounts 421 summary: List accounts
422 operationId: getAccounts
335 parameters: 423 parameters:
336 - $ref: '#/components/parameters/start' 424 - $ref: '#/components/parameters/start'
337 - $ref: '#/components/parameters/count' 425 - $ref: '#/components/parameters/count'
@@ -345,11 +433,13 @@ paths:
345 type: array 433 type: array
346 items: 434 items:
347 $ref: '#/components/schemas/Account' 435 $ref: '#/components/schemas/Account'
436
348 /config: 437 /config:
349 get: 438 get:
350 tags: 439 tags:
351 - Config 440 - Config
352 summary: Get instance public configuration 441 summary: Get instance public configuration
442 operationId: getConfig
353 responses: 443 responses:
354 '200': 444 '200':
355 description: successful operation 445 description: successful operation
@@ -360,9 +450,11 @@ paths:
360 examples: 450 examples:
361 nightly: 451 nightly:
362 externalValue: https://peertube2.cpy.re/api/v1/config 452 externalValue: https://peertube2.cpy.re/api/v1/config
453
363 /config/about: 454 /config/about:
364 get: 455 get:
365 summary: Get instance "About" information 456 summary: Get instance "About" information
457 operationId: getAbout
366 tags: 458 tags:
367 - Config 459 - Config
368 responses: 460 responses:
@@ -375,9 +467,11 @@ paths:
375 examples: 467 examples:
376 nightly: 468 nightly:
377 externalValue: https://peertube2.cpy.re/api/v1/config/about 469 externalValue: https://peertube2.cpy.re/api/v1/config/about
470
378 /config/custom: 471 /config/custom:
379 get: 472 get:
380 summary: Get instance runtime configuration 473 summary: Get instance runtime configuration
474 operationId: getCustomConfig
381 tags: 475 tags:
382 - Config 476 - Config
383 security: 477 security:
@@ -392,6 +486,7 @@ paths:
392 $ref: '#/components/schemas/ServerConfigCustom' 486 $ref: '#/components/schemas/ServerConfigCustom'
393 put: 487 put:
394 summary: Set instance runtime configuration 488 summary: Set instance runtime configuration
489 operationId: putCustomConfig
395 tags: 490 tags:
396 - Config 491 - Config
397 security: 492 security:
@@ -408,6 +503,7 @@ paths:
408 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled 503 - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
409 delete: 504 delete:
410 summary: Delete instance runtime configuration 505 summary: Delete instance runtime configuration
506 operationId: delCustomConfig
411 tags: 507 tags:
412 - Config 508 - Config
413 security: 509 security:
@@ -416,9 +512,45 @@ paths:
416 responses: 512 responses:
417 '200': 513 '200':
418 description: successful operation 514 description: successful operation
515
516 /custom-pages/homepage/instance:
517 get:
518 summary: Get instance custom homepage
519 tags:
520 - Homepage
521 responses:
522 '404':
523 description: No homepage set
524 '200':
525 description: successful operation
526 content:
527 application/json:
528 schema:
529 $ref: '#/components/schemas/CustomHomepage'
530 put:
531 summary: Set instance custom homepage
532 tags:
533 - Homepage
534 security:
535 - OAuth2:
536 - admin
537 requestBody:
538 content:
539 application/json:
540 schema:
541 type: object
542 properties:
543 content:
544 type: string
545 description: content of the homepage, that will be injected in the client
546 responses:
547 '204':
548 description: successful operation
549
419 /jobs/{state}: 550 /jobs/{state}:
420 get: 551 get:
421 summary: List instance jobs 552 summary: List instance jobs
553 operationId: getJobs
422 security: 554 security:
423 - OAuth2: 555 - OAuth2:
424 - admin 556 - admin
@@ -458,66 +590,108 @@ paths:
458 maxItems: 100 590 maxItems: 100
459 items: 591 items:
460 $ref: '#/components/schemas/Job' 592 $ref: '#/components/schemas/Job'
461 '/server/following/{host}': 593
594 /server/followers:
595 get:
596 tags:
597 - Instance Follows
598 summary: List instances following the server
599 parameters:
600 - $ref: '#/components/parameters/followState'
601 - $ref: '#/components/parameters/actorType'
602 - $ref: '#/components/parameters/start'
603 - $ref: '#/components/parameters/count'
604 - $ref: '#/components/parameters/sort'
605 responses:
606 '200':
607 description: successful operation
608 content:
609 application/json:
610 schema:
611 type: object
612 properties:
613 total:
614 type: integer
615 example: 1
616 data:
617 type: array
618 items:
619 $ref: '#/components/schemas/Follow'
620
621 '/server/followers/{nameWithHost}':
462 delete: 622 delete:
623 summary: Remove or reject a follower to your server
463 security: 624 security:
464 - OAuth2: 625 - OAuth2:
465 - admin 626 - admin
466 tags: 627 tags:
467 - Instance Follows 628 - Instance Follows
468 summary: Unfollow a server
469 parameters: 629 parameters:
470 - name: host 630 - name: nameWithHost
471 in: path 631 in: path
472 required: true 632 required: true
473 description: 'The host to unfollow ' 633 description: The remote actor handle to remove from your followers
474 schema: 634 schema:
475 type: string 635 type: string
476 format: hostname 636 format: email
477 responses: 637 responses:
478 '201': 638 '204':
479 description: successful operation 639 description: successful operation
480 /server/followers: 640 '404':
481 get: 641 description: follower not found
642
643 '/server/followers/{nameWithHost}/reject':
644 post:
645 summary: Reject a pending follower to your server
646 security:
647 - OAuth2:
648 - admin
482 tags: 649 tags:
483 - Instance Follows 650 - Instance Follows
484 summary: List instance followers
485 parameters: 651 parameters:
486 - $ref: '#/components/parameters/start' 652 - name: nameWithHost
487 - $ref: '#/components/parameters/count' 653 in: path
488 - $ref: '#/components/parameters/sort' 654 required: true
655 description: The remote actor handle to remove from your followers
656 schema:
657 type: string
658 format: email
489 responses: 659 responses:
490 '200': 660 '204':
491 description: successful operation 661 description: successful operation
492 content: 662 '404':
493 application/json: 663 description: follower not found
494 schema: 664
495 type: array 665 '/server/followers/{nameWithHost}/accept':
496 items: 666 post:
497 $ref: '#/components/schemas/Follow' 667 summary: Accept a pending follower to your server
668 security:
669 - OAuth2:
670 - admin
671 tags:
672 - Instance Follows
673 parameters:
674 - name: nameWithHost
675 in: path
676 required: true
677 description: The remote actor handle to remove from your followers
678 schema:
679 type: string
680 format: email
681 responses:
682 '204':
683 description: successful operation
684 '404':
685 description: follower not found
686
498 /server/following: 687 /server/following:
499 get: 688 get:
500 tags: 689 tags:
501 - Instance Follows 690 - Instance Follows
502 summary: List instances followed by the server 691 summary: List instances followed by the server
503 parameters: 692 parameters:
504 - name: state 693 - $ref: '#/components/parameters/followState'
505 in: query 694 - $ref: '#/components/parameters/actorType'
506 schema:
507 type: string
508 enum:
509 - pending
510 - accepted
511 - name: actorType
512 in: query
513 schema:
514 type: string
515 enum:
516 - Person
517 - Application
518 - Group
519 - Service
520 - Organization
521 - $ref: '#/components/parameters/start' 695 - $ref: '#/components/parameters/start'
522 - $ref: '#/components/parameters/count' 696 - $ref: '#/components/parameters/count'
523 - $ref: '#/components/parameters/sort' 697 - $ref: '#/components/parameters/sort'
@@ -527,16 +701,22 @@ paths:
527 content: 701 content:
528 application/json: 702 application/json:
529 schema: 703 schema:
530 type: array 704 type: object
531 items: 705 properties:
532 $ref: '#/components/schemas/Follow' 706 total:
707 type: integer
708 example: 1
709 data:
710 type: array
711 items:
712 $ref: '#/components/schemas/Follow'
533 post: 713 post:
534 security: 714 security:
535 - OAuth2: 715 - OAuth2:
536 - admin 716 - admin
537 tags: 717 tags:
538 - Instance Follows 718 - Instance Follows
539 summary: Follow a server 719 summary: Follow a list of servers
540 responses: 720 responses:
541 '204': 721 '204':
542 description: successful operation 722 description: successful operation
@@ -554,9 +734,33 @@ paths:
554 type: string 734 type: string
555 format: hostname 735 format: hostname
556 uniqueItems: true 736 uniqueItems: true
737
738 '/server/following/{host}':
739 delete:
740 summary: Unfollow a server
741 security:
742 - OAuth2:
743 - admin
744 tags:
745 - Instance Follows
746 parameters:
747 - name: host
748 in: path
749 required: true
750 description: The host to unfollow
751 schema:
752 type: string
753 format: hostname
754 responses:
755 '204':
756 description: successful operation
757 '404':
758 description: host not found
759
557 /users: 760 /users:
558 post: 761 post:
559 summary: Create a user 762 summary: Create a user
763 operationId: addUser
560 security: 764 security:
561 - OAuth2: 765 - OAuth2:
562 - admin 766 - admin
@@ -571,18 +775,18 @@ paths:
571 $ref: '#/components/schemas/AddUserResponse' 775 $ref: '#/components/schemas/AddUserResponse'
572 links: 776 links:
573 # GET /users/{id} 777 # GET /users/{id}
574 GetUserId: 778 GetUser:
575 operationId: getUserId 779 operationId: getUser
576 parameters: 780 parameters:
577 id: '$response.body#/user/id' 781 id: '$response.body#/user/id'
578 # PUT /users/{id} 782 # PUT /users/{id}
579 PutUserId: 783 PutUser:
580 operationId: putUserId 784 operationId: putUser
581 parameters: 785 parameters:
582 id: '$response.body#/user/id' 786 id: '$response.body#/user/id'
583 # DELETE /users/{id} 787 # DELETE /users/{id}
584 DelUserId: 788 DelUser:
585 operationId: delUserId 789 operationId: delUser
586 parameters: 790 parameters:
587 id: '$response.body#/user/id' 791 id: '$response.body#/user/id'
588 '403': 792 '403':
@@ -598,6 +802,7 @@ paths:
598 required: true 802 required: true
599 get: 803 get:
600 summary: List users 804 summary: List users
805 operationId: getUsers
601 security: 806 security:
602 - OAuth2: 807 - OAuth2:
603 - admin 808 - admin
@@ -618,6 +823,7 @@ paths:
618 type: array 823 type: array
619 items: 824 items:
620 $ref: '#/components/schemas/User' 825 $ref: '#/components/schemas/User'
826
621 '/users/{id}': 827 '/users/{id}':
622 parameters: 828 parameters:
623 - $ref: '#/components/parameters/id' 829 - $ref: '#/components/parameters/id'
@@ -628,7 +834,7 @@ paths:
628 - admin 834 - admin
629 tags: 835 tags:
630 - Users 836 - Users
631 operationId: delUserId 837 operationId: delUser
632 responses: 838 responses:
633 '204': 839 '204':
634 description: successful operation 840 description: successful operation
@@ -638,7 +844,7 @@ paths:
638 - OAuth2: [] 844 - OAuth2: []
639 tags: 845 tags:
640 - Users 846 - Users
641 operationId: getUserId 847 operationId: getUser
642 parameters: 848 parameters:
643 - name: withStats 849 - name: withStats
644 in: query 850 in: query
@@ -663,7 +869,7 @@ paths:
663 - OAuth2: [] 869 - OAuth2: []
664 tags: 870 tags:
665 - Users 871 - Users
666 operationId: putUserId 872 operationId: putUser
667 responses: 873 responses:
668 '204': 874 '204':
669 description: successful operation 875 description: successful operation
@@ -673,11 +879,132 @@ paths:
673 schema: 879 schema:
674 $ref: '#/components/schemas/UpdateUser' 880 $ref: '#/components/schemas/UpdateUser'
675 required: true 881 required: true
882
883 /oauth-clients/local:
884 get:
885 summary: Login prerequisite
886 description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
887 operationId: getOAuthClient
888 tags:
889 - Session
890 responses:
891 '200':
892 description: successful operation
893 content:
894 application/json:
895 schema:
896 $ref: '#/components/schemas/OAuthClient'
897 links:
898 UseOAuthClientToLogin:
899 operationId: getOAuthToken
900 parameters:
901 client_id: '$response.body#/client_id'
902 client_secret: '$response.body#/client_secret'
903 x-codeSamples:
904 - lang: Shell
905 source: |
906 API="https://peertube2.cpy.re/api/v1"
907
908 ## AUTH
909 curl -s "$API/oauth-clients/local"
910
911 /users/token:
912 post:
913 summary: Login
914 operationId: getOAuthToken
915 description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
916 tags:
917 - Session
918 requestBody:
919 content:
920 application/x-www-form-urlencoded:
921 schema:
922 oneOf:
923 - $ref: '#/components/schemas/OAuthToken-password'
924 - $ref: '#/components/schemas/OAuthToken-refresh_token'
925 discriminator:
926 propertyName: grant_type
927 mapping:
928 password: '#/components/schemas/OAuthToken-password'
929 refresh_token: '#/components/schemas/OAuthToken-refresh_token'
930 responses:
931 '200':
932 description: successful operation
933 content:
934 application/json:
935 schema:
936 type: object
937 properties:
938 token_type:
939 type: string
940 example: Bearer
941 access_token:
942 type: string
943 example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
944 description: valid for 1 day
945 refresh_token:
946 type: string
947 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
948 description: valid for 2 weeks
949 expires_in:
950 type: integer
951 minimum: 0
952 example: 14399
953 refresh_token_expires_in:
954 type: integer
955 minimum: 0
956 example: 1209600
957 '400':
958 x-summary: client or credentials are invalid
959 description: |
960 Disambiguate via `type`:
961 - `invalid_client` for an unmatched `client_id`
962 - `invalid_grant` for unmatched credentials
963 '401':
964 x-summary: token expired
965 description: |
966 Disambiguate via `type`:
967 - default value for a regular authentication failure
968 - `invalid_token` for an expired token
969 x-codeSamples:
970 - lang: Shell
971 source: |
972 ## DEPENDENCIES: jq
973 API="https://peertube2.cpy.re/api/v1"
974 USERNAME="<your_username>"
975 PASSWORD="<your_password>"
976
977 ## AUTH
978 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
979 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
980 curl -s "$API/users/token" \
981 --data client_id="$client_id" \
982 --data client_secret="$client_secret" \
983 --data grant_type=password \
984 --data username="$USERNAME" \
985 --data password="$PASSWORD" \
986 | jq -r ".access_token"
987
988 /users/revoke-token:
989 post:
990 summary: Logout
991 description: Revokes your access token and its associated refresh token, destroying your current session.
992 operationId: revokeOAuthToken
993 tags:
994 - Session
995 security:
996 - OAuth2: []
997 responses:
998 '200':
999 description: successful operation
1000
676 /users/register: 1001 /users/register:
677 post: 1002 post:
678 summary: Register a user 1003 summary: Register a user
1004 operationId: registerUser
679 tags: 1005 tags:
680 - Users 1006 - Users
1007 - Register
681 responses: 1008 responses:
682 '204': 1009 '204':
683 description: successful operation 1010 description: successful operation
@@ -687,9 +1014,55 @@ paths:
687 schema: 1014 schema:
688 $ref: '#/components/schemas/RegisterUser' 1015 $ref: '#/components/schemas/RegisterUser'
689 required: true 1016 required: true
1017
1018 /users/{id}/verify-email:
1019 post:
1020 summary: Verify a user
1021 operationId: verifyUser
1022 description: |
1023 Following a user registration, the new user will receive an email asking to click a link
1024 containing a secret.
1025 tags:
1026 - Users
1027 - Register
1028 parameters:
1029 - $ref: '#/components/parameters/id'
1030 requestBody:
1031 content:
1032 application/json:
1033 schema:
1034 type: object
1035 properties:
1036 verificationString:
1037 type: string
1038 format: url
1039 isPendingEmail:
1040 type: boolean
1041 required:
1042 - verificationString
1043 responses:
1044 '204':
1045 description: successful operation
1046 '403':
1047 description: invalid verification string
1048 '404':
1049 description: user not found
1050
1051 /users/ask-send-verify-email:
1052 post:
1053 summary: Resend user verification link
1054 operationId: resendEmailToVerifyUser
1055 tags:
1056 - Users
1057 - Register
1058 responses:
1059 '204':
1060 description: successful operation
1061
690 /users/me: 1062 /users/me:
691 get: 1063 get:
692 summary: Get my user information 1064 summary: Get my user information
1065 operationId: getUserInfo
693 security: 1066 security:
694 - OAuth2: 1067 - OAuth2:
695 - user 1068 - user
@@ -706,6 +1079,7 @@ paths:
706 $ref: '#/components/schemas/User' 1079 $ref: '#/components/schemas/User'
707 put: 1080 put:
708 summary: Update my user information 1081 summary: Update my user information
1082 operationId: putUserInfo
709 security: 1083 security:
710 - OAuth2: 1084 - OAuth2:
711 - user 1085 - user
@@ -720,6 +1094,7 @@ paths:
720 schema: 1094 schema:
721 $ref: '#/components/schemas/UpdateMe' 1095 $ref: '#/components/schemas/UpdateMe'
722 required: true 1096 required: true
1097
723 /users/me/videos/imports: 1098 /users/me/videos/imports:
724 get: 1099 get:
725 summary: Get video imports of my user 1100 summary: Get video imports of my user
@@ -740,6 +1115,7 @@ paths:
740 application/json: 1115 application/json:
741 schema: 1116 schema:
742 $ref: '#/components/schemas/VideoImportsList' 1117 $ref: '#/components/schemas/VideoImportsList'
1118
743 /users/me/video-quota-used: 1119 /users/me/video-quota-used:
744 get: 1120 get:
745 summary: Get my user used quota 1121 summary: Get my user used quota
@@ -764,6 +1140,7 @@ paths:
764 type: number 1140 type: number
765 description: The user video quota used today in bytes 1141 description: The user video quota used today in bytes
766 example: 1681014151 1142 example: 1681014151
1143
767 '/users/me/videos/{videoId}/rating': 1144 '/users/me/videos/{videoId}/rating':
768 get: 1145 get:
769 summary: Get rate of my user for a video 1146 summary: Get rate of my user for a video
@@ -786,6 +1163,7 @@ paths:
786 application/json: 1163 application/json:
787 schema: 1164 schema:
788 $ref: '#/components/schemas/GetMeVideoRating' 1165 $ref: '#/components/schemas/GetMeVideoRating'
1166
789 /users/me/videos: 1167 /users/me/videos:
790 get: 1168 get:
791 summary: Get videos of my user 1169 summary: Get videos of my user
@@ -806,6 +1184,7 @@ paths:
806 application/json: 1184 application/json:
807 schema: 1185 schema:
808 $ref: '#/components/schemas/VideoListResponse' 1186 $ref: '#/components/schemas/VideoListResponse'
1187
809 /users/me/subscriptions: 1188 /users/me/subscriptions:
810 get: 1189 get:
811 summary: Get my user subscriptions 1190 summary: Get my user subscriptions
@@ -851,6 +1230,7 @@ paths:
851 responses: 1230 responses:
852 '200': 1231 '200':
853 description: successful operation 1232 description: successful operation
1233
854 /users/me/subscriptions/exist: 1234 /users/me/subscriptions/exist:
855 get: 1235 get:
856 summary: Get if subscriptions exist for my user 1236 summary: Get if subscriptions exist for my user
@@ -868,6 +1248,7 @@ paths:
868 application/json: 1248 application/json:
869 schema: 1249 schema:
870 type: object 1250 type: object
1251
871 /users/me/subscriptions/videos: 1252 /users/me/subscriptions/videos:
872 get: 1253 get:
873 summary: List videos of subscriptions of my user 1254 summary: List videos of subscriptions of my user
@@ -897,6 +1278,7 @@ paths:
897 application/json: 1278 application/json:
898 schema: 1279 schema:
899 $ref: '#/components/schemas/VideoListResponse' 1280 $ref: '#/components/schemas/VideoListResponse'
1281
900 '/users/me/subscriptions/{subscriptionHandle}': 1282 '/users/me/subscriptions/{subscriptionHandle}':
901 get: 1283 get:
902 summary: Get subscription of my user 1284 summary: Get subscription of my user
@@ -926,6 +1308,7 @@ paths:
926 responses: 1308 responses:
927 '200': 1309 '200':
928 description: successful operation 1310 description: successful operation
1311
929 /users/me/notifications: 1312 /users/me/notifications:
930 get: 1313 get:
931 summary: List my notifications 1314 summary: List my notifications
@@ -949,6 +1332,7 @@ paths:
949 application/json: 1332 application/json:
950 schema: 1333 schema:
951 $ref: '#/components/schemas/NotificationListResponse' 1334 $ref: '#/components/schemas/NotificationListResponse'
1335
952 /users/me/notifications/read: 1336 /users/me/notifications/read:
953 post: 1337 post:
954 summary: Mark notifications as read by their id 1338 summary: Mark notifications as read by their id
@@ -972,6 +1356,7 @@ paths:
972 responses: 1356 responses:
973 '204': 1357 '204':
974 description: successful operation 1358 description: successful operation
1359
975 /users/me/notifications/read-all: 1360 /users/me/notifications/read-all:
976 post: 1361 post:
977 summary: Mark all my notification as read 1362 summary: Mark all my notification as read
@@ -982,6 +1367,7 @@ paths:
982 responses: 1367 responses:
983 '204': 1368 '204':
984 description: successful operation 1369 description: successful operation
1370
985 /users/me/notification-settings: 1371 /users/me/notification-settings:
986 put: 1372 put:
987 summary: Update my notification settings 1373 summary: Update my notification settings
@@ -1022,6 +1408,7 @@ paths:
1022 responses: 1408 responses:
1023 '204': 1409 '204':
1024 description: successful operation 1410 description: successful operation
1411
1025 /users/me/history/videos: 1412 /users/me/history/videos:
1026 get: 1413 get:
1027 summary: List watched videos history 1414 summary: List watched videos history
@@ -1040,6 +1427,7 @@ paths:
1040 application/json: 1427 application/json:
1041 schema: 1428 schema:
1042 $ref: '#/components/schemas/VideoListResponse' 1429 $ref: '#/components/schemas/VideoListResponse'
1430
1043 /users/me/history/videos/remove: 1431 /users/me/history/videos/remove:
1044 post: 1432 post:
1045 summary: Clear video history 1433 summary: Clear video history
@@ -1060,6 +1448,7 @@ paths:
1060 responses: 1448 responses:
1061 '204': 1449 '204':
1062 description: successful operation 1450 description: successful operation
1451
1063 /users/me/avatar/pick: 1452 /users/me/avatar/pick:
1064 post: 1453 post:
1065 summary: Update my user avatar 1454 summary: Update my user avatar
@@ -1098,6 +1487,7 @@ paths:
1098 encoding: 1487 encoding:
1099 avatarfile: 1488 avatarfile:
1100 contentType: image/png, image/jpeg 1489 contentType: image/png, image/jpeg
1490
1101 /users/me/avatar: 1491 /users/me/avatar:
1102 delete: 1492 delete:
1103 summary: Delete my avatar 1493 summary: Delete my avatar
@@ -1119,6 +1509,7 @@ paths:
1119 responses: 1509 responses:
1120 '200': 1510 '200':
1121 description: successful operation 1511 description: successful operation
1512
1122 '/videos/ownership/{id}/accept': 1513 '/videos/ownership/{id}/accept':
1123 post: 1514 post:
1124 summary: Accept ownership change request 1515 summary: Accept ownership change request
@@ -1135,6 +1526,7 @@ paths:
1135 description: cannot terminate an ownership change of another user 1526 description: cannot terminate an ownership change of another user
1136 '404': 1527 '404':
1137 description: video owneship change not found 1528 description: video owneship change not found
1529
1138 '/videos/ownership/{id}/refuse': 1530 '/videos/ownership/{id}/refuse':
1139 post: 1531 post:
1140 summary: Refuse ownership change request 1532 summary: Refuse ownership change request
@@ -1151,6 +1543,7 @@ paths:
1151 description: cannot terminate an ownership change of another user 1543 description: cannot terminate an ownership change of another user
1152 '404': 1544 '404':
1153 description: video owneship change not found 1545 description: video owneship change not found
1546
1154 '/videos/{id}/give-ownership': 1547 '/videos/{id}/give-ownership':
1155 post: 1548 post:
1156 summary: Request ownership change 1549 summary: Request ownership change
@@ -1178,9 +1571,11 @@ paths:
1178 description: changing video ownership to a remote account is not supported yet 1571 description: changing video ownership to a remote account is not supported yet
1179 '404': 1572 '404':
1180 description: video not found 1573 description: video not found
1574
1181 /videos: 1575 /videos:
1182 get: 1576 get:
1183 summary: List videos 1577 summary: List videos
1578 operationId: getVideos
1184 tags: 1579 tags:
1185 - Video 1580 - Video
1186 parameters: 1581 parameters:
@@ -1203,6 +1598,7 @@ paths:
1203 application/json: 1598 application/json:
1204 schema: 1599 schema:
1205 $ref: '#/components/schemas/VideoListResponse' 1600 $ref: '#/components/schemas/VideoListResponse'
1601
1206 /videos/categories: 1602 /videos/categories:
1207 get: 1603 get:
1208 summary: List available video categories 1604 summary: List available video categories
@@ -1221,6 +1617,7 @@ paths:
1221 examples: 1617 examples:
1222 nightly: 1618 nightly:
1223 externalValue: https://peertube2.cpy.re/api/v1/videos/categories 1619 externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1620
1224 /videos/licences: 1621 /videos/licences:
1225 get: 1622 get:
1226 summary: List available video licences 1623 summary: List available video licences
@@ -1239,6 +1636,7 @@ paths:
1239 examples: 1636 examples:
1240 nightly: 1637 nightly:
1241 externalValue: https://peertube2.cpy.re/api/v1/videos/licences 1638 externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1639
1242 /videos/languages: 1640 /videos/languages:
1243 get: 1641 get:
1244 summary: List available video languages 1642 summary: List available video languages
@@ -1257,6 +1655,7 @@ paths:
1257 examples: 1655 examples:
1258 nightly: 1656 nightly:
1259 externalValue: https://peertube2.cpy.re/api/v1/videos/languages 1657 externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1658
1260 /videos/privacies: 1659 /videos/privacies:
1261 get: 1660 get:
1262 summary: List available video privacy policies 1661 summary: List available video privacy policies
@@ -1275,9 +1674,11 @@ paths:
1275 examples: 1674 examples:
1276 nightly: 1675 nightly:
1277 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies 1676 externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1677
1278 '/videos/{id}': 1678 '/videos/{id}':
1279 put: 1679 put:
1280 summary: Update a video 1680 summary: Update a video
1681 operationId: putVideo
1281 security: 1682 security:
1282 - OAuth2: [] 1683 - OAuth2: []
1283 tags: 1684 tags:
@@ -1317,7 +1718,7 @@ paths:
1317 type: string 1718 type: string
1318 support: 1719 support:
1319 description: A text tell the audience how to support the video creator 1720 description: A text tell the audience how to support the video creator
1320 example: Please support my work on <insert crowdfunding plateform>! <3 1721 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1321 type: string 1722 type: string
1322 nsfw: 1723 nsfw:
1323 description: Whether or not this video contains sensitive content 1724 description: Whether or not this video contains sensitive content
@@ -1339,6 +1740,9 @@ paths:
1339 commentsEnabled: 1740 commentsEnabled:
1340 description: Enable or disable comments for this video 1741 description: Enable or disable comments for this video
1341 type: boolean 1742 type: boolean
1743 downloadEnabled:
1744 description: Enable or disable downloading for this video
1745 type: boolean
1342 originallyPublishedAt: 1746 originallyPublishedAt:
1343 description: Date when the content was originally published 1747 description: Date when the content was originally published
1344 type: string 1748 type: string
@@ -1352,6 +1756,7 @@ paths:
1352 contentType: image/jpeg 1756 contentType: image/jpeg
1353 get: 1757 get:
1354 summary: Get a video 1758 summary: Get a video
1759 operationId: getVideo
1355 tags: 1760 tags:
1356 - Video 1761 - Video
1357 parameters: 1762 parameters:
@@ -1365,6 +1770,7 @@ paths:
1365 $ref: '#/components/schemas/VideoDetails' 1770 $ref: '#/components/schemas/VideoDetails'
1366 delete: 1771 delete:
1367 summary: Delete a video 1772 summary: Delete a video
1773 operationId: delVideo
1368 security: 1774 security:
1369 - OAuth2: [] 1775 - OAuth2: []
1370 tags: 1776 tags:
@@ -1374,9 +1780,11 @@ paths:
1374 responses: 1780 responses:
1375 '204': 1781 '204':
1376 description: successful operation 1782 description: successful operation
1783
1377 '/videos/{id}/description': 1784 '/videos/{id}/description':
1378 get: 1785 get:
1379 summary: Get complete video description 1786 summary: Get complete video description
1787 operationId: getVideoDesc
1380 tags: 1788 tags:
1381 - Video 1789 - Video
1382 parameters: 1790 parameters:
@@ -1393,9 +1801,11 @@ paths:
1393 maxLength: 10000 1801 maxLength: 10000
1394 example: | 1802 example: |
1395 **[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)** 1803 **[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)**
1804
1396 '/videos/{id}/views': 1805 '/videos/{id}/views':
1397 post: 1806 post:
1398 summary: Add a view to a video 1807 summary: Add a view to a video
1808 operationId: addView
1399 tags: 1809 tags:
1400 - Video 1810 - Video
1401 parameters: 1811 parameters:
@@ -1403,9 +1813,11 @@ paths:
1403 responses: 1813 responses:
1404 '204': 1814 '204':
1405 description: successful operation 1815 description: successful operation
1816
1406 '/videos/{id}/watching': 1817 '/videos/{id}/watching':
1407 put: 1818 put:
1408 summary: Set watching progress of a video 1819 summary: Set watching progress of a video
1820 operationId: setProgress
1409 tags: 1821 tags:
1410 - Video 1822 - Video
1411 security: 1823 security:
@@ -1421,6 +1833,7 @@ paths:
1421 responses: 1833 responses:
1422 '204': 1834 '204':
1423 description: successful operation 1835 description: successful operation
1836
1424 /videos/upload: 1837 /videos/upload:
1425 post: 1838 post:
1426 summary: Upload a video 1839 summary: Upload a video
@@ -1438,14 +1851,15 @@ paths:
1438 application/json: 1851 application/json:
1439 schema: 1852 schema:
1440 $ref: '#/components/schemas/VideoUploadResponse' 1853 $ref: '#/components/schemas/VideoUploadResponse'
1441 '400':
1442 description: invalid file field, schedule date or parameter
1443 '403': 1854 '403':
1444 description: video didn't pass upload filter 1855 description: video didn't pass upload filter
1445 '408': 1856 '408':
1446 description: upload has timed out 1857 description: upload has timed out
1447 '413': 1858 '413':
1448 description: video file too large, due to quota or max body size limit set by the reverse-proxy 1859 x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
1860 description: |
1861 If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
1862 - `quota_reached` for quota limits wether daily or global
1449 headers: 1863 headers:
1450 X-File-Maximum-Size: 1864 X-File-Maximum-Size:
1451 schema: 1865 schema:
@@ -1477,26 +1891,27 @@ paths:
1477 FILE_PATH="<your_file_path>" 1891 FILE_PATH="<your_file_path>"
1478 CHANNEL_ID="<your_channel_id>" 1892 CHANNEL_ID="<your_channel_id>"
1479 NAME="<video_name>" 1893 NAME="<video_name>"
1894 API="https://peertube2.cpy.re/api/v1"
1480 1895
1481 API_PATH="https://peertube2.cpy.re/api/v1"
1482 ## AUTH 1896 ## AUTH
1483 client_id=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_id") 1897 client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1484 client_secret=$(curl -s "$API_PATH/oauth-clients/local" | jq -r ".client_secret") 1898 client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1485 token=$(curl -s "$API_PATH/users/token" \ 1899 token=$(curl -s "$API/users/token" \
1486 --data client_id="$client_id" \ 1900 --data client_id="$client_id" \
1487 --data client_secret="$client_secret" \ 1901 --data client_secret="$client_secret" \
1488 --data grant_type=password \ 1902 --data grant_type=password \
1489 --data response_type=code \
1490 --data username="$USERNAME" \ 1903 --data username="$USERNAME" \
1491 --data password="$PASSWORD" \ 1904 --data password="$PASSWORD" \
1492 | jq -r ".access_token") 1905 | jq -r ".access_token")
1906
1493 ## VIDEO UPLOAD 1907 ## VIDEO UPLOAD
1494 curl -s "$API_PATH/videos/upload" \ 1908 curl -s "$API/videos/upload" \
1495 -H "Authorization: Bearer $token" \ 1909 -H "Authorization: Bearer $token" \
1496 --max-time 600 \ 1910 --max-time 600 \
1497 --form videofile=@"$FILE_PATH" \ 1911 --form videofile=@"$FILE_PATH" \
1498 --form channelId=$CHANNEL_ID \ 1912 --form channelId=$CHANNEL_ID \
1499 --form name="$NAME" 1913 --form name="$NAME"
1914
1500 /videos/upload-resumable: 1915 /videos/upload-resumable:
1501 post: 1916 post:
1502 summary: Initialize the resumable upload of a video 1917 summary: Initialize the resumable upload of a video
@@ -1543,10 +1958,12 @@ paths:
1543 schema: 1958 schema:
1544 type: number 1959 type: number
1545 example: 0 1960 example: 0
1546 '400':
1547 description: invalid file field, schedule date or parameter
1548 '413': 1961 '413':
1549 description: video file too large, due to quota, absolute max file size or concurrent partial upload limit 1962 x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1963 description: |
1964 Disambiguate via `type`:
1965 - `max_file_size_reached` for the absolute file size limit
1966 - `quota_reached` for quota limits whether daily or global
1550 '415': 1967 '415':
1551 description: video type unsupported 1968 description: video type unsupported
1552 put: 1969 put:
@@ -1560,7 +1977,7 @@ paths:
1560 - Video Upload 1977 - Video Upload
1561 parameters: 1978 parameters:
1562 - name: upload_id 1979 - name: upload_id
1563 in: path 1980 in: query
1564 required: true 1981 required: true
1565 description: | 1982 description: |
1566 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is 1983 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
@@ -1622,10 +2039,14 @@ paths:
1622 example: 0 2039 example: 0
1623 '403': 2040 '403':
1624 description: video didn't pass upload filter 2041 description: video didn't pass upload filter
1625 '413': 2042 '404':
1626 description: video file too large, due to quota or max body size limit set by the reverse-proxy 2043 description: upload not found
2044 '409':
2045 description: chunk doesn't match range
1627 '422': 2046 '422':
1628 description: video unreadable 2047 description: video unreadable
2048 '429':
2049 description: too many concurrent requests
1629 delete: 2050 delete:
1630 summary: Cancel the resumable upload of a video, deleting any data uploaded so far 2051 summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1631 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video 2052 description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
@@ -1637,7 +2058,7 @@ paths:
1637 - Video Upload 2058 - Video Upload
1638 parameters: 2059 parameters:
1639 - name: upload_id 2060 - name: upload_id
1640 in: path 2061 in: query
1641 required: true 2062 required: true
1642 description: | 2063 description: |
1643 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is 2064 Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
@@ -1658,6 +2079,9 @@ paths:
1658 schema: 2079 schema:
1659 type: number 2080 type: number
1660 example: 0 2081 example: 0
2082 '404':
2083 description: upload not found
2084
1661 /videos/imports: 2085 /videos/imports:
1662 post: 2086 post:
1663 summary: Import a video 2087 summary: Import a video
@@ -1672,74 +2096,7 @@ paths:
1672 content: 2096 content:
1673 multipart/form-data: 2097 multipart/form-data:
1674 schema: 2098 schema:
1675 type: object 2099 $ref: '#/components/schemas/VideoCreateImport'
1676 properties:
1677 torrentfile:
1678 description: Torrent File
1679 type: string
1680 format: binary
1681 targetUrl:
1682 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
1683 magnetUri:
1684 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
1685 channelId:
1686 description: Channel id that will contain this video
1687 allOf:
1688 - $ref: '#/components/schemas/VideoChannel/properties/id'
1689 thumbnailfile:
1690 description: Video thumbnail file
1691 type: string
1692 format: binary
1693 previewfile:
1694 description: Video preview file
1695 type: string
1696 format: binary
1697 privacy:
1698 $ref: '#/components/schemas/VideoPrivacySet'
1699 category:
1700 $ref: '#/components/schemas/VideoCategorySet'
1701 licence:
1702 $ref: '#/components/schemas/VideoLicenceSet'
1703 language:
1704 $ref: '#/components/schemas/VideoLanguageSet'
1705 description:
1706 description: Video description
1707 type: string
1708 waitTranscoding:
1709 description: Whether or not we wait transcoding before publish the video
1710 type: boolean
1711 support:
1712 description: A text tell the audience how to support the video creator
1713 example: Please support my work on <insert crowdfunding plateform>! <3
1714 type: string
1715 nsfw:
1716 description: Whether or not this video contains sensitive content
1717 type: boolean
1718 name:
1719 description: Video name
1720 type: string
1721 minLength: 3
1722 maxLength: 120
1723 tags:
1724 description: Video tags (maximum 5 tags each between 2 and 30 characters)
1725 type: array
1726 minItems: 1
1727 maxItems: 5
1728 items:
1729 type: string
1730 minLength: 2
1731 maxLength: 30
1732 commentsEnabled:
1733 description: Enable or disable comments for this video
1734 type: boolean
1735 downloadEnabled:
1736 description: Enable or disable downloading for this video
1737 type: boolean
1738 scheduleUpdate:
1739 $ref: '#/components/schemas/VideoScheduledUpdate'
1740 required:
1741 - channelId
1742 - name
1743 encoding: 2100 encoding:
1744 torrentfile: 2101 torrentfile:
1745 contentType: application/x-bittorrent 2102 contentType: application/x-bittorrent
@@ -1764,7 +2121,7 @@ paths:
1764 /videos/live: 2121 /videos/live:
1765 post: 2122 post:
1766 summary: Create a live 2123 summary: Create a live
1767 operationId: createLive 2124 operationId: addLive
1768 security: 2125 security:
1769 - OAuth2: [] 2126 - OAuth2: []
1770 tags: 2127 tags:
@@ -1777,8 +2134,20 @@ paths:
1777 application/json: 2134 application/json:
1778 schema: 2135 schema:
1779 $ref: '#/components/schemas/VideoUploadResponse' 2136 $ref: '#/components/schemas/VideoUploadResponse'
2137 '400':
2138 x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
2139 description: |
2140 Disambiguate via `type`:
2141 - default type for a validation error
2142 - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
1780 '403': 2143 '403':
1781 description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded 2144 x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2145 description: |
2146 Disambiguate via `type`:
2147 - `live_not_enabled` for a disabled live feature
2148 - `live_not_allowing_replay` for a disabled replay feature
2149 - `max_instance_lives_limit_reached` for the absolute concurrent live limit
2150 - `max_user_lives_limit_reached` for the user concurrent live limit
1782 requestBody: 2151 requestBody:
1783 content: 2152 content:
1784 multipart/form-data: 2153 multipart/form-data:
@@ -1814,7 +2183,7 @@ paths:
1814 type: string 2183 type: string
1815 support: 2184 support:
1816 description: A text tell the audience how to support the creator 2185 description: A text tell the audience how to support the creator
1817 example: Please support my work on <insert crowdfunding plateform>! <3 2186 example: Please support our work on https://soutenir.framasoft.org/en/ <3
1818 type: string 2187 type: string
1819 nsfw: 2188 nsfw:
1820 description: Whether or not this live video/replay contains sensitive content 2189 description: Whether or not this live video/replay contains sensitive content
@@ -1837,7 +2206,7 @@ paths:
1837 description: Enable or disable comments for this live video/replay 2206 description: Enable or disable comments for this live video/replay
1838 type: boolean 2207 type: boolean
1839 downloadEnabled: 2208 downloadEnabled:
1840 description: Enable or disable downloading for the replay of this live 2209 description: Enable or disable downloading for the replay of this live video
1841 type: boolean 2210 type: boolean
1842 required: 2211 required:
1843 - channelId 2212 - channelId
@@ -1979,7 +2348,7 @@ paths:
1979 type: string 2348 type: string
1980 - name: videoIs 2349 - name: videoIs
1981 in: query 2350 in: query
1982 description: only list blacklisted or deleted videos 2351 description: only list deleted or blocklisted videos
1983 schema: 2352 schema:
1984 type: string 2353 type: string
1985 enum: 2354 enum:
@@ -2012,7 +2381,6 @@ paths:
2012 type: array 2381 type: array
2013 items: 2382 items:
2014 $ref: '#/components/schemas/Abuse' 2383 $ref: '#/components/schemas/Abuse'
2015
2016 post: 2384 post:
2017 summary: Report an abuse 2385 summary: Report an abuse
2018 security: 2386 security:
@@ -2042,10 +2410,12 @@ paths:
2042 - $ref: '#/components/schemas/Video/properties/id' 2410 - $ref: '#/components/schemas/Video/properties/id'
2043 startAt: 2411 startAt:
2044 type: integer 2412 type: integer
2413 format: seconds
2045 description: Timestamp in the video that marks the beginning of the report 2414 description: Timestamp in the video that marks the beginning of the report
2046 minimum: 0 2415 minimum: 0
2047 endAt: 2416 endAt:
2048 type: integer 2417 type: integer
2418 format: seconds
2049 description: Timestamp in the video that marks the ending of the report 2419 description: Timestamp in the video that marks the ending of the report
2050 minimum: 0 2420 minimum: 0
2051 comment: 2421 comment:
@@ -2064,10 +2434,21 @@ paths:
2064 required: 2434 required:
2065 - reason 2435 - reason
2066 responses: 2436 responses:
2067 '204': 2437 '200':
2068 description: successful operation 2438 description: successful operation
2439 content:
2440 application/json:
2441 schema:
2442 type: object
2443 properties:
2444 abuse:
2445 type: object
2446 properties:
2447 id:
2448 $ref: '#/components/schemas/id'
2069 '400': 2449 '400':
2070 description: incorrect request parameters 2450 description: incorrect request parameters
2451
2071 '/abuses/{abuseId}': 2452 '/abuses/{abuseId}':
2072 put: 2453 put:
2073 summary: Update an abuse 2454 summary: Update an abuse
@@ -2112,6 +2493,7 @@ paths:
2112 description: successful operation 2493 description: successful operation
2113 '404': 2494 '404':
2114 description: block not found 2495 description: block not found
2496
2115 '/abuses/{abuseId}/messages': 2497 '/abuses/{abuseId}/messages':
2116 get: 2498 get:
2117 summary: List messages of an abuse 2499 summary: List messages of an abuse
@@ -2127,10 +2509,15 @@ paths:
2127 content: 2509 content:
2128 application/json: 2510 application/json:
2129 schema: 2511 schema:
2130 type: array 2512 type: object
2131 items: 2513 properties:
2132 $ref: '#/components/schemas/AbuseMessage' 2514 total:
2133 2515 type: integer
2516 example: 1
2517 data:
2518 type: array
2519 items:
2520 $ref: '#/components/schemas/AbuseMessage'
2134 post: 2521 post:
2135 summary: Add message to an abuse 2522 summary: Add message to an abuse
2136 security: 2523 security:
@@ -2158,6 +2545,7 @@ paths:
2158 description: successful operation 2545 description: successful operation
2159 '400': 2546 '400':
2160 description: incorrect request parameters 2547 description: incorrect request parameters
2548
2161 '/abuses/{abuseId}/messages/{abuseMessageId}': 2549 '/abuses/{abuseId}/messages/{abuseMessageId}':
2162 delete: 2550 delete:
2163 summary: Delete an abuse message 2551 summary: Delete an abuse message
@@ -2175,6 +2563,7 @@ paths:
2175 '/videos/{id}/blacklist': 2563 '/videos/{id}/blacklist':
2176 post: 2564 post:
2177 summary: Block a video 2565 summary: Block a video
2566 operationId: addVideoBlock
2178 security: 2567 security:
2179 - OAuth2: 2568 - OAuth2:
2180 - admin 2569 - admin
@@ -2188,6 +2577,7 @@ paths:
2188 description: successful operation 2577 description: successful operation
2189 delete: 2578 delete:
2190 summary: Unblock a video by its id 2579 summary: Unblock a video by its id
2580 operationId: delVideoBlock
2191 security: 2581 security:
2192 - OAuth2: 2582 - OAuth2:
2193 - admin 2583 - admin
@@ -2201,11 +2591,13 @@ paths:
2201 description: successful operation 2591 description: successful operation
2202 '404': 2592 '404':
2203 description: block not found 2593 description: block not found
2594
2204 /videos/blacklist: 2595 /videos/blacklist:
2205 get: 2596 get:
2206 tags: 2597 tags:
2207 - Video Blocks 2598 - Video Blocks
2208 summary: List video blocks 2599 summary: List video blocks
2600 operationId: getVideoBlocks
2209 security: 2601 security:
2210 - OAuth2: 2602 - OAuth2:
2211 - admin 2603 - admin
@@ -2247,9 +2639,11 @@ paths:
2247 type: array 2639 type: array
2248 items: 2640 items:
2249 $ref: '#/components/schemas/VideoBlacklist' 2641 $ref: '#/components/schemas/VideoBlacklist'
2642
2250 /videos/{id}/captions: 2643 /videos/{id}/captions:
2251 get: 2644 get:
2252 summary: List captions of a video 2645 summary: List captions of a video
2646 operationId: getVideoCaptions
2253 tags: 2647 tags:
2254 - Video Captions 2648 - Video Captions
2255 parameters: 2649 parameters:
@@ -2269,9 +2663,11 @@ paths:
2269 type: array 2663 type: array
2270 items: 2664 items:
2271 $ref: '#/components/schemas/VideoCaption' 2665 $ref: '#/components/schemas/VideoCaption'
2666
2272 /videos/{id}/captions/{captionLanguage}: 2667 /videos/{id}/captions/{captionLanguage}:
2273 put: 2668 put:
2274 summary: Add or replace a video caption 2669 summary: Add or replace a video caption
2670 operationId: addVideoCaption
2275 security: 2671 security:
2276 - OAuth2: 2672 - OAuth2:
2277 - user 2673 - user
@@ -2300,6 +2696,7 @@ paths:
2300 description: video or language not found 2696 description: video or language not found
2301 delete: 2697 delete:
2302 summary: Delete a video caption 2698 summary: Delete a video caption
2699 operationId: delVideoCaption
2303 security: 2700 security:
2304 - OAuth2: 2701 - OAuth2:
2305 - user 2702 - user
@@ -2313,9 +2710,11 @@ paths:
2313 description: successful operation 2710 description: successful operation
2314 '404': 2711 '404':
2315 description: video or language or caption for that language not found 2712 description: video or language or caption for that language not found
2713
2316 /video-channels: 2714 /video-channels:
2317 get: 2715 get:
2318 summary: List video channels 2716 summary: List video channels
2717 operationId: getVideoChannels
2319 tags: 2718 tags:
2320 - Video Channels 2719 - Video Channels
2321 parameters: 2720 parameters:
@@ -2331,6 +2730,7 @@ paths:
2331 $ref: '#/components/schemas/VideoChannelList' 2730 $ref: '#/components/schemas/VideoChannelList'
2332 post: 2731 post:
2333 summary: Create a video channel 2732 summary: Create a video channel
2733 operationId: addVideoChannel
2334 security: 2734 security:
2335 - OAuth2: [] 2735 - OAuth2: []
2336 tags: 2736 tags:
@@ -2338,14 +2738,26 @@ paths:
2338 responses: 2738 responses:
2339 '204': 2739 '204':
2340 description: successful operation 2740 description: successful operation
2741 content:
2742 application/json:
2743 schema:
2744 type: object
2745 properties:
2746 videoChannel:
2747 type: object
2748 properties:
2749 id:
2750 $ref: '#/components/schemas/VideoChannel/properties/id'
2341 requestBody: 2751 requestBody:
2342 content: 2752 content:
2343 application/json: 2753 application/json:
2344 schema: 2754 schema:
2345 $ref: '#/components/schemas/VideoChannelCreate' 2755 $ref: '#/components/schemas/VideoChannelCreate'
2756
2346 '/video-channels/{channelHandle}': 2757 '/video-channels/{channelHandle}':
2347 get: 2758 get:
2348 summary: Get a video channel 2759 summary: Get a video channel
2760 operationId: getVideoChannel
2349 tags: 2761 tags:
2350 - Video Channels 2762 - Video Channels
2351 parameters: 2763 parameters:
@@ -2359,6 +2771,7 @@ paths:
2359 $ref: '#/components/schemas/VideoChannel' 2771 $ref: '#/components/schemas/VideoChannel'
2360 put: 2772 put:
2361 summary: Update a video channel 2773 summary: Update a video channel
2774 operationId: putVideoChannel
2362 security: 2775 security:
2363 - OAuth2: [] 2776 - OAuth2: []
2364 tags: 2777 tags:
@@ -2375,6 +2788,7 @@ paths:
2375 $ref: '#/components/schemas/VideoChannelUpdate' 2788 $ref: '#/components/schemas/VideoChannelUpdate'
2376 delete: 2789 delete:
2377 summary: Delete a video channel 2790 summary: Delete a video channel
2791 operationId: delVideoChannel
2378 security: 2792 security:
2379 - OAuth2: [] 2793 - OAuth2: []
2380 tags: 2794 tags:
@@ -2384,9 +2798,11 @@ paths:
2384 responses: 2798 responses:
2385 '204': 2799 '204':
2386 description: successful operation 2800 description: successful operation
2801
2387 '/video-channels/{channelHandle}/videos': 2802 '/video-channels/{channelHandle}/videos':
2388 get: 2803 get:
2389 summary: List videos of a video channel 2804 summary: List videos of a video channel
2805 operationId: getVideoChannelVideos
2390 tags: 2806 tags:
2391 - Video 2807 - Video
2392 - Video Channels 2808 - Video Channels
@@ -2411,6 +2827,7 @@ paths:
2411 application/json: 2827 application/json:
2412 schema: 2828 schema:
2413 $ref: '#/components/schemas/VideoListResponse' 2829 $ref: '#/components/schemas/VideoListResponse'
2830
2414 '/video-channels/{channelHandle}/avatar/pick': 2831 '/video-channels/{channelHandle}/avatar/pick':
2415 post: 2832 post:
2416 summary: Update channel avatar 2833 summary: Update channel avatar
@@ -2451,6 +2868,7 @@ paths:
2451 encoding: 2868 encoding:
2452 avatarfile: 2869 avatarfile:
2453 contentType: image/png, image/jpeg 2870 contentType: image/png, image/jpeg
2871
2454 '/video-channels/{channelHandle}/avatar': 2872 '/video-channels/{channelHandle}/avatar':
2455 delete: 2873 delete:
2456 summary: Delete channel avatar 2874 summary: Delete channel avatar
@@ -2464,7 +2882,6 @@ paths:
2464 '204': 2882 '204':
2465 description: successful operation 2883 description: successful operation
2466 2884
2467
2468 '/video-channels/{channelHandle}/banner/pick': 2885 '/video-channels/{channelHandle}/banner/pick':
2469 post: 2886 post:
2470 summary: Update channel banner 2887 summary: Update channel banner
@@ -2505,6 +2922,7 @@ paths:
2505 encoding: 2922 encoding:
2506 bannerfile: 2923 bannerfile:
2507 contentType: image/png, image/jpeg 2924 contentType: image/png, image/jpeg
2925
2508 '/video-channels/{channelHandle}/banner': 2926 '/video-channels/{channelHandle}/banner':
2509 delete: 2927 delete:
2510 summary: Delete channel banner 2928 summary: Delete channel banner
@@ -2565,7 +2983,7 @@ paths:
2565 post: 2983 post:
2566 summary: Create a video playlist 2984 summary: Create a video playlist
2567 description: If the video playlist is set as public, `videoChannelId` is mandatory. 2985 description: If the video playlist is set as public, `videoChannelId` is mandatory.
2568 operationId: createPlaylist 2986 operationId: addPlaylist
2569 security: 2987 security:
2570 - OAuth2: [] 2988 - OAuth2: []
2571 tags: 2989 tags:
@@ -2585,6 +3003,8 @@ paths:
2585 $ref: '#/components/schemas/VideoPlaylist/properties/id' 3003 $ref: '#/components/schemas/VideoPlaylist/properties/id'
2586 uuid: 3004 uuid:
2587 $ref: '#/components/schemas/VideoPlaylist/properties/uuid' 3005 $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3006 shortUUID:
3007 $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
2588 requestBody: 3008 requestBody:
2589 content: 3009 content:
2590 multipart/form-data: 3010 multipart/form-data:
@@ -2617,13 +3037,13 @@ paths:
2617 thumbnailfile: 3037 thumbnailfile:
2618 contentType: image/jpeg 3038 contentType: image/jpeg
2619 3039
2620 /video-playlists/{id}: 3040 /video-playlists/{playlistId}:
2621 get: 3041 get:
2622 summary: Get a video playlist 3042 summary: Get a video playlist
2623 tags: 3043 tags:
2624 - Video Playlists 3044 - Video Playlists
2625 parameters: 3045 parameters:
2626 - $ref: '#/components/parameters/idOrUUID' 3046 - $ref: '#/components/parameters/playlistId'
2627 responses: 3047 responses:
2628 '200': 3048 '200':
2629 description: successful operation 3049 description: successful operation
@@ -2642,7 +3062,7 @@ paths:
2642 '204': 3062 '204':
2643 description: successful operation 3063 description: successful operation
2644 parameters: 3064 parameters:
2645 - $ref: '#/components/parameters/idOrUUID' 3065 - $ref: '#/components/parameters/playlistId'
2646 requestBody: 3066 requestBody:
2647 content: 3067 content:
2648 multipart/form-data: 3068 multipart/form-data:
@@ -2677,19 +3097,20 @@ paths:
2677 tags: 3097 tags:
2678 - Video Playlists 3098 - Video Playlists
2679 parameters: 3099 parameters:
2680 - $ref: '#/components/parameters/idOrUUID' 3100 - $ref: '#/components/parameters/playlistId'
2681 responses: 3101 responses:
2682 '204': 3102 '204':
2683 description: successful operation 3103 description: successful operation
2684 3104
2685 /video-playlists/{id}/videos: 3105 /video-playlists/{playlistId}/videos:
2686 get: 3106 get:
2687 summary: 'List videos of a playlist' 3107 summary: 'List videos of a playlist'
3108 operationId: getVideoPlaylistVideos
2688 tags: 3109 tags:
2689 - Videos 3110 - Videos
2690 - Video Playlists 3111 - Video Playlists
2691 parameters: 3112 parameters:
2692 - $ref: '#/components/parameters/idOrUUID' 3113 - $ref: '#/components/parameters/playlistId'
2693 responses: 3114 responses:
2694 '200': 3115 '200':
2695 description: successful operation 3116 description: successful operation
@@ -2698,14 +3119,15 @@ paths:
2698 schema: 3119 schema:
2699 $ref: '#/components/schemas/VideoListResponse' 3120 $ref: '#/components/schemas/VideoListResponse'
2700 post: 3121 post:
2701 summary: 'Add a video in a playlist' 3122 summary: Add a video in a playlist
3123 operationId: addVideoPlaylistVideo
2702 security: 3124 security:
2703 - OAuth2: [] 3125 - OAuth2: []
2704 tags: 3126 tags:
2705 - Videos 3127 - Videos
2706 - Video Playlists 3128 - Video Playlists
2707 parameters: 3129 parameters:
2708 - $ref: '#/components/parameters/idOrUUID' 3130 - $ref: '#/components/parameters/playlistId'
2709 responses: 3131 responses:
2710 '200': 3132 '200':
2711 description: successful operation 3133 description: successful operation
@@ -2719,6 +3141,7 @@ paths:
2719 properties: 3141 properties:
2720 id: 3142 id:
2721 type: integer 3143 type: integer
3144 example: 2
2722 requestBody: 3145 requestBody:
2723 content: 3146 content:
2724 application/json: 3147 application/json:
@@ -2726,27 +3149,31 @@ paths:
2726 type: object 3149 type: object
2727 properties: 3150 properties:
2728 videoId: 3151 videoId:
2729 allOf: 3152 oneOf:
3153 - $ref: '#/components/schemas/Video/properties/uuid'
2730 - $ref: '#/components/schemas/Video/properties/id' 3154 - $ref: '#/components/schemas/Video/properties/id'
2731 description: Video to add in the playlist 3155 description: Video to add in the playlist
2732 startTimestamp: 3156 startTimestamp:
2733 type: integer 3157 type: integer
2734 description: Start the video at this specific timestamp (in seconds) 3158 format: seconds
3159 description: Start the video at this specific timestamp
2735 stopTimestamp: 3160 stopTimestamp:
2736 type: integer 3161 type: integer
2737 description: Stop the video at this specific timestamp (in seconds) 3162 format: seconds
3163 description: Stop the video at this specific timestamp
2738 required: 3164 required:
2739 - videoId 3165 - videoId
2740 3166
2741 /video-playlists/{id}/videos/reorder: 3167 /video-playlists/{playlistId}/videos/reorder:
2742 post: 3168 post:
2743 summary: 'Reorder a playlist' 3169 summary: 'Reorder a playlist'
3170 operationId: reorderVideoPlaylist
2744 security: 3171 security:
2745 - OAuth2: [] 3172 - OAuth2: []
2746 tags: 3173 tags:
2747 - Video Playlists 3174 - Video Playlists
2748 parameters: 3175 parameters:
2749 - $ref: '#/components/parameters/idOrUUID' 3176 - $ref: '#/components/parameters/playlistId'
2750 responses: 3177 responses:
2751 '204': 3178 '204':
2752 description: successful operation 3179 description: successful operation
@@ -2772,15 +3199,16 @@ paths:
2772 - startPosition 3199 - startPosition
2773 - insertAfterPosition 3200 - insertAfterPosition
2774 3201
2775 /video-playlists/{id}/videos/{playlistElementId}: 3202 /video-playlists/{playlistId}/videos/{playlistElementId}:
2776 put: 3203 put:
2777 summary: 'Update a playlist element' 3204 summary: Update a playlist element
3205 operationId: putVideoPlaylistVideo
2778 security: 3206 security:
2779 - OAuth2: [] 3207 - OAuth2: []
2780 tags: 3208 tags:
2781 - Video Playlists 3209 - Video Playlists
2782 parameters: 3210 parameters:
2783 - $ref: '#/components/parameters/idOrUUID' 3211 - $ref: '#/components/parameters/playlistId'
2784 - $ref: '#/components/parameters/playlistElementId' 3212 - $ref: '#/components/parameters/playlistElementId'
2785 responses: 3213 responses:
2786 '204': 3214 '204':
@@ -2793,18 +3221,21 @@ paths:
2793 properties: 3221 properties:
2794 startTimestamp: 3222 startTimestamp:
2795 type: integer 3223 type: integer
2796 description: 'Start the video at this specific timestamp (in seconds)' 3224 format: seconds
3225 description: Start the video at this specific timestamp
2797 stopTimestamp: 3226 stopTimestamp:
2798 type: integer 3227 type: integer
2799 description: 'Stop the video at this specific timestamp (in seconds)' 3228 format: seconds
3229 description: Stop the video at this specific timestamp
2800 delete: 3230 delete:
2801 summary: 'Delete an element from a playlist' 3231 summary: Delete an element from a playlist
3232 operationId: delVideoPlaylistVideo
2802 security: 3233 security:
2803 - OAuth2: [] 3234 - OAuth2: []
2804 tags: 3235 tags:
2805 - Video Playlists 3236 - Video Playlists
2806 parameters: 3237 parameters:
2807 - $ref: '#/components/parameters/idOrUUID' 3238 - $ref: '#/components/parameters/playlistId'
2808 - $ref: '#/components/parameters/playlistElementId' 3239 - $ref: '#/components/parameters/playlistElementId'
2809 responses: 3240 responses:
2810 '204': 3241 '204':
@@ -2812,7 +3243,7 @@ paths:
2812 3243
2813 '/users/me/video-playlists/videos-exist': 3244 '/users/me/video-playlists/videos-exist':
2814 get: 3245 get:
2815 summary: 'Check video exists in my playlists' 3246 summary: Check video exists in my playlists
2816 security: 3247 security:
2817 - OAuth2: [] 3248 - OAuth2: []
2818 tags: 3249 tags:
@@ -2845,8 +3276,10 @@ paths:
2845 type: integer 3276 type: integer
2846 startTimestamp: 3277 startTimestamp:
2847 type: integer 3278 type: integer
3279 format: seconds
2848 stopTimestamp: 3280 stopTimestamp:
2849 type: integer 3281 type: integer
3282 format: seconds
2850 3283
2851 '/accounts/{name}/video-channels': 3284 '/accounts/{name}/video-channels':
2852 get: 3285 get:
@@ -2871,6 +3304,7 @@ paths:
2871 application/json: 3304 application/json:
2872 schema: 3305 schema:
2873 $ref: '#/components/schemas/VideoChannelList' 3306 $ref: '#/components/schemas/VideoChannelList'
3307
2874 '/accounts/{name}/ratings': 3308 '/accounts/{name}/ratings':
2875 get: 3309 get:
2876 summary: List ratings of an account 3310 summary: List ratings of an account
@@ -2901,6 +3335,7 @@ paths:
2901 type: array 3335 type: array
2902 items: 3336 items:
2903 $ref: '#/components/schemas/VideoRating' 3337 $ref: '#/components/schemas/VideoRating'
3338
2904 '/videos/{id}/comment-threads': 3339 '/videos/{id}/comment-threads':
2905 get: 3340 get:
2906 summary: List threads of a video 3341 summary: List threads of a video
@@ -2942,8 +3377,10 @@ paths:
2942 type: object 3377 type: object
2943 properties: 3378 properties:
2944 text: 3379 text:
2945 type: string 3380 allOf:
2946 description: 'Text comment' 3381 - $ref: '#/components/schemas/VideoComment/properties/text'
3382 format: markdown
3383 maxLength: 10000
2947 required: 3384 required:
2948 - text 3385 - text
2949 3386
@@ -2962,6 +3399,7 @@ paths:
2962 application/json: 3399 application/json:
2963 schema: 3400 schema:
2964 $ref: '#/components/schemas/VideoCommentThreadTree' 3401 $ref: '#/components/schemas/VideoCommentThreadTree'
3402
2965 '/videos/{id}/comments/{commentId}': 3403 '/videos/{id}/comments/{commentId}':
2966 post: 3404 post:
2967 summary: Reply to a thread of a video 3405 summary: Reply to a thread of a video
@@ -2988,10 +3426,12 @@ paths:
2988 type: object 3426 type: object
2989 properties: 3427 properties:
2990 text: 3428 text:
2991 $ref: '#/components/schemas/VideoComment/properties/text' 3429 allOf:
3430 - $ref: '#/components/schemas/VideoComment/properties/text'
3431 format: markdown
3432 maxLength: 10000
2992 required: 3433 required:
2993 - text 3434 - text
2994
2995 delete: 3435 delete:
2996 summary: Delete a comment or a reply 3436 summary: Delete a comment or a reply
2997 security: 3437 security:
@@ -3010,6 +3450,7 @@ paths:
3010 description: comment or video does not exist 3450 description: comment or video does not exist
3011 '409': 3451 '409':
3012 description: comment is already deleted 3452 description: comment is already deleted
3453
3013 '/videos/{id}/rate': 3454 '/videos/{id}/rate':
3014 put: 3455 put:
3015 summary: Like/dislike a video 3456 summary: Like/dislike a video
@@ -3019,16 +3460,31 @@ paths:
3019 - Video Rates 3460 - Video Rates
3020 parameters: 3461 parameters:
3021 - $ref: '#/components/parameters/idOrUUID' 3462 - $ref: '#/components/parameters/idOrUUID'
3463 requestBody:
3464 content:
3465 application/json:
3466 schema:
3467 type: object
3468 properties:
3469 rating:
3470 type: string
3471 enum:
3472 - like
3473 - dislike
3474 required:
3475 - rating
3022 responses: 3476 responses:
3023 '204': 3477 '204':
3024 description: successful operation 3478 description: successful operation
3025 '404': 3479 '404':
3026 description: video does not exist 3480 description: video does not exist
3481
3027 /search/videos: 3482 /search/videos:
3028 get: 3483 get:
3029 tags: 3484 tags:
3030 - Search 3485 - Search
3031 summary: Search videos 3486 summary: Search videos
3487 operationId: searchVideos
3032 parameters: 3488 parameters:
3033 - name: search 3489 - name: search
3034 in: query 3490 in: query
@@ -3099,11 +3555,13 @@ paths:
3099 $ref: '#/components/schemas/VideoListResponse' 3555 $ref: '#/components/schemas/VideoListResponse'
3100 '500': 3556 '500':
3101 description: search index unavailable 3557 description: search index unavailable
3558
3102 /search/video-channels: 3559 /search/video-channels:
3103 get: 3560 get:
3104 tags: 3561 tags:
3105 - Search 3562 - Search
3106 summary: Search channels 3563 summary: Search channels
3564 operationId: searchChannels
3107 parameters: 3565 parameters:
3108 - name: search 3566 - name: search
3109 in: query 3567 in: query
@@ -3130,7 +3588,49 @@ paths:
3130 $ref: '#/components/schemas/VideoChannelList' 3588 $ref: '#/components/schemas/VideoChannelList'
3131 '500': 3589 '500':
3132 description: search index unavailable 3590 description: search index unavailable
3133 /blocklist/accounts: 3591
3592 /search/video-playlists:
3593 get:
3594 tags:
3595 - Search
3596 summary: Search playlists
3597 operationId: searchPlaylists
3598 parameters:
3599 - name: search
3600 in: query
3601 required: true
3602 description: >
3603 String to search. If the user can make a remote URI search, and the string is an URI then the
3604 PeerTube instance will fetch the remote object and add it to its database. Then,
3605 you can use the REST API to fetch the complete playlist information and interact with it.
3606 schema:
3607 type: string
3608 - $ref: '#/components/parameters/start'
3609 - $ref: '#/components/parameters/count'
3610 - $ref: '#/components/parameters/searchTarget'
3611 - $ref: '#/components/parameters/sort'
3612 callbacks:
3613 'searchTarget === search-index':
3614 $ref: '#/components/callbacks/searchIndex'
3615 responses:
3616 '200':
3617 description: successful operation
3618 content:
3619 application/json:
3620 schema:
3621 type: object
3622 properties:
3623 total:
3624 type: integer
3625 example: 1
3626 data:
3627 type: array
3628 items:
3629 $ref: '#/components/schemas/VideoPlaylist'
3630 '500':
3631 description: search index unavailable
3632
3633 /server/blocklist/accounts:
3134 get: 3634 get:
3135 tags: 3635 tags:
3136 - Account Blocks 3636 - Account Blocks
@@ -3169,7 +3669,8 @@ paths:
3169 description: successful operation 3669 description: successful operation
3170 '409': 3670 '409':
3171 description: self-blocking forbidden 3671 description: self-blocking forbidden
3172 '/blocklist/accounts/{accountName}': 3672
3673 '/server/blocklist/accounts/{accountName}':
3173 delete: 3674 delete:
3174 tags: 3675 tags:
3175 - Account Blocks 3676 - Account Blocks
@@ -3189,7 +3690,8 @@ paths:
3189 description: successful operation 3690 description: successful operation
3190 '404': 3691 '404':
3191 description: account or account block does not exist 3692 description: account or account block does not exist
3192 /blocklist/servers: 3693
3694 /server/blocklist/servers:
3193 get: 3695 get:
3194 tags: 3696 tags:
3195 - Server Blocks 3697 - Server Blocks
@@ -3224,11 +3726,12 @@ paths:
3224 required: 3726 required:
3225 - host 3727 - host
3226 responses: 3728 responses:
3227 '200': 3729 '204':
3228 description: successful operation 3730 description: successful operation
3229 '409': 3731 '409':
3230 description: self-blocking forbidden 3732 description: self-blocking forbidden
3231 '/blocklist/servers/{host}': 3733
3734 '/server/blocklist/servers/{host}':
3232 delete: 3735 delete:
3233 tags: 3736 tags:
3234 - Server Blocks 3737 - Server Blocks
@@ -3245,11 +3748,12 @@ paths:
3245 type: string 3748 type: string
3246 format: hostname 3749 format: hostname
3247 responses: 3750 responses:
3248 '201': 3751 '204':
3249 description: successful operation 3752 description: successful operation
3250 '404': 3753 '404':
3251 description: account block does not exist 3754 description: account block does not exist
3252 /redundancy/{host}: 3755
3756 /server/redundancy/{host}:
3253 put: 3757 put:
3254 tags: 3758 tags:
3255 - Instance Redundancy 3759 - Instance Redundancy
@@ -3281,11 +3785,13 @@ paths:
3281 description: successful operation 3785 description: successful operation
3282 '404': 3786 '404':
3283 description: server is not already known 3787 description: server is not already known
3284 /redundancy/videos: 3788
3789 /server/redundancy/videos:
3285 get: 3790 get:
3286 tags: 3791 tags:
3287 - Video Mirroring 3792 - Video Mirroring
3288 summary: List videos being mirrored 3793 summary: List videos being mirrored
3794 operationId: getMirroredVideos
3289 security: 3795 security:
3290 - OAuth2: 3796 - OAuth2:
3291 - admin 3797 - admin
@@ -3315,6 +3821,7 @@ paths:
3315 tags: 3821 tags:
3316 - Video Mirroring 3822 - Video Mirroring
3317 summary: Mirror a video 3823 summary: Mirror a video
3824 operationId: putMirroredVideo
3318 security: 3825 security:
3319 - OAuth2: 3826 - OAuth2:
3320 - admin 3827 - admin
@@ -3337,11 +3844,13 @@ paths:
3337 description: video does not exist 3844 description: video does not exist
3338 '409': 3845 '409':
3339 description: video is already mirrored 3846 description: video is already mirrored
3340 /redundancy/videos/{redundancyId}: 3847
3848 /server/redundancy/videos/{redundancyId}:
3341 delete: 3849 delete:
3342 tags: 3850 tags:
3343 - Video Mirroring 3851 - Video Mirroring
3344 summary: Delete a mirror done on a video 3852 summary: Delete a mirror done on a video
3853 operationId: delMirroredVideo
3345 security: 3854 security:
3346 - OAuth2: 3855 - OAuth2:
3347 - admin 3856 - admin
@@ -3357,11 +3866,13 @@ paths:
3357 description: successful operation 3866 description: successful operation
3358 '404': 3867 '404':
3359 description: video redundancy not found 3868 description: video redundancy not found
3869
3360 '/feeds/video-comments.{format}': 3870 '/feeds/video-comments.{format}':
3361 get: 3871 get:
3362 tags: 3872 tags:
3363 - Feeds 3873 - Feeds
3364 summary: List comments on videos 3874 summary: List comments on videos
3875 operationId: getSyndicatedComments
3365 parameters: 3876 parameters:
3366 - name: format 3877 - name: format
3367 in: path 3878 in: path
@@ -3450,11 +3961,13 @@ paths:
3450 description: video, video channel or account not found 3961 description: video, video channel or account not found
3451 '406': 3962 '406':
3452 description: accept header unsupported 3963 description: accept header unsupported
3964
3453 '/feeds/videos.{format}': 3965 '/feeds/videos.{format}':
3454 get: 3966 get:
3455 tags: 3967 tags:
3456 - Feeds 3968 - Feeds
3457 summary: List videos 3969 summary: List videos
3970 operationId: getSyndicatedVideos
3458 parameters: 3971 parameters:
3459 - name: format 3972 - name: format
3460 in: path 3973 in: path
@@ -3536,12 +4049,14 @@ paths:
3536 description: video channel or account not found 4049 description: video channel or account not found
3537 '406': 4050 '406':
3538 description: accept header unsupported 4051 description: accept header unsupported
4052
3539 '/feeds/subscriptions.{format}': 4053 '/feeds/subscriptions.{format}':
3540 get: 4054 get:
3541 tags: 4055 tags:
3542 - Feeds 4056 - Feeds
3543 - Account 4057 - Account
3544 summary: List videos of subscriptions tied to a token 4058 summary: List videos of subscriptions tied to a token
4059 operationId: getSyndicatedSubscriptionVideos
3545 parameters: 4060 parameters:
3546 - name: format 4061 - name: format
3547 in: path 4062 in: path
@@ -3598,11 +4113,13 @@ paths:
3598 type: object 4113 type: object
3599 '406': 4114 '406':
3600 description: accept header unsupported 4115 description: accept header unsupported
4116
3601 /plugins: 4117 /plugins:
3602 get: 4118 get:
3603 tags: 4119 tags:
3604 - Plugins 4120 - Plugins
3605 summary: List plugins 4121 summary: List plugins
4122 operationId: getPlugins
3606 security: 4123 security:
3607 - OAuth2: 4124 - OAuth2:
3608 - admin 4125 - admin
@@ -3625,11 +4142,13 @@ paths:
3625 application/json: 4142 application/json:
3626 schema: 4143 schema:
3627 $ref: '#/components/schemas/PluginResponse' 4144 $ref: '#/components/schemas/PluginResponse'
4145
3628 /plugins/available: 4146 /plugins/available:
3629 get: 4147 get:
3630 tags: 4148 tags:
3631 - Plugins 4149 - Plugins
3632 summary: List available plugins 4150 summary: List available plugins
4151 operationId: getAvailablePlugins
3633 security: 4152 security:
3634 - OAuth2: 4153 - OAuth2:
3635 - admin 4154 - admin
@@ -3658,11 +4177,13 @@ paths:
3658 $ref: '#/components/schemas/PluginResponse' 4177 $ref: '#/components/schemas/PluginResponse'
3659 '503': 4178 '503':
3660 description: plugin index unavailable 4179 description: plugin index unavailable
4180
3661 /plugins/install: 4181 /plugins/install:
3662 post: 4182 post:
3663 tags: 4183 tags:
3664 - Plugins 4184 - Plugins
3665 summary: Install a plugin 4185 summary: Install a plugin
4186 operationId: addPlugin
3666 security: 4187 security:
3667 - OAuth2: 4188 - OAuth2:
3668 - admin 4189 - admin
@@ -3691,11 +4212,13 @@ paths:
3691 description: successful operation 4212 description: successful operation
3692 '400': 4213 '400':
3693 description: should have either `npmName` or `path` set 4214 description: should have either `npmName` or `path` set
4215
3694 /plugins/update: 4216 /plugins/update:
3695 post: 4217 post:
3696 tags: 4218 tags:
3697 - Plugins 4219 - Plugins
3698 summary: Update a plugin 4220 summary: Update a plugin
4221 operationId: updatePlugin
3699 security: 4222 security:
3700 - OAuth2: 4223 - OAuth2:
3701 - admin 4224 - admin
@@ -3726,11 +4249,13 @@ paths:
3726 description: should have either `npmName` or `path` set 4249 description: should have either `npmName` or `path` set
3727 '404': 4250 '404':
3728 description: existing plugin not found 4251 description: existing plugin not found
4252
3729 /plugins/uninstall: 4253 /plugins/uninstall:
3730 post: 4254 post:
3731 tags: 4255 tags:
3732 - Plugins 4256 - Plugins
3733 summary: Uninstall a plugin 4257 summary: Uninstall a plugin
4258 operationId: uninstallPlugin
3734 security: 4259 security:
3735 - OAuth2: 4260 - OAuth2:
3736 - admin 4261 - admin
@@ -3751,11 +4276,13 @@ paths:
3751 description: successful operation 4276 description: successful operation
3752 '404': 4277 '404':
3753 description: existing plugin not found 4278 description: existing plugin not found
4279
3754 /plugins/{npmName}: 4280 /plugins/{npmName}:
3755 get: 4281 get:
3756 tags: 4282 tags:
3757 - Plugins 4283 - Plugins
3758 summary: Get a plugin 4284 summary: Get a plugin
4285 operationId: getPlugin
3759 security: 4286 security:
3760 - OAuth2: 4287 - OAuth2:
3761 - admin 4288 - admin
@@ -3770,6 +4297,7 @@ paths:
3770 $ref: '#/components/schemas/Plugin' 4297 $ref: '#/components/schemas/Plugin'
3771 '404': 4298 '404':
3772 description: plugin not found 4299 description: plugin not found
4300
3773 /plugins/{npmName}/settings: 4301 /plugins/{npmName}/settings:
3774 put: 4302 put:
3775 tags: 4303 tags:
@@ -3794,6 +4322,7 @@ paths:
3794 description: successful operation 4322 description: successful operation
3795 '404': 4323 '404':
3796 description: plugin not found 4324 description: plugin not found
4325
3797 /plugins/{npmName}/public-settings: 4326 /plugins/{npmName}/public-settings:
3798 get: 4327 get:
3799 tags: 4328 tags:
@@ -3811,6 +4340,7 @@ paths:
3811 additionalProperties: true 4340 additionalProperties: true
3812 '404': 4341 '404':
3813 description: plugin not found 4342 description: plugin not found
4343
3814 /plugins/{npmName}/registered-settings: 4344 /plugins/{npmName}/registered-settings:
3815 get: 4345 get:
3816 tags: 4346 tags:
@@ -3831,6 +4361,7 @@ paths:
3831 additionalProperties: true 4361 additionalProperties: true
3832 '404': 4362 '404':
3833 description: plugin not found 4363 description: plugin not found
4364
3834servers: 4365servers:
3835 - url: 'https://peertube2.cpy.re/api/v1' 4366 - url: 'https://peertube2.cpy.re/api/v1'
3836 description: Live Test Server (live data - latest nightly version) 4367 description: Live Test Server (live data - latest nightly version)
@@ -3938,7 +4469,7 @@ components:
3938 name: sort 4469 name: sort
3939 in: query 4470 in: query
3940 required: false 4471 required: false
3941 description: Sort blacklists by criteria 4472 description: Sort blocklists by criteria
3942 schema: 4473 schema:
3943 type: string 4474 type: string
3944 enum: 4475 enum:
@@ -4014,11 +4545,19 @@ components:
4014 name: id 4545 name: id
4015 in: path 4546 in: path
4016 required: true 4547 required: true
4017 description: The object id or uuid 4548 description: The object id, uuid or short uuid
4018 schema: 4549 schema:
4019 oneOf: 4550 oneOf:
4020 - $ref: '#/components/schemas/id' 4551 - $ref: '#/components/schemas/id'
4021 - $ref: '#/components/schemas/UUIDv4' 4552 - $ref: '#/components/schemas/UUIDv4'
4553 - $ref: '#/components/schemas/shortUUID'
4554 playlistId:
4555 name: playlistId
4556 in: path
4557 required: true
4558 description: Playlist id
4559 schema:
4560 $ref: '#/components/schemas/VideoPlaylist/properties/id'
4022 playlistElementId: 4561 playlistElementId:
4023 name: playlistElementId 4562 name: playlistElementId
4024 in: path 4563 in: path
@@ -4069,7 +4608,7 @@ components:
4069 required: true 4608 required: true
4070 description: The thread id (root comment id) 4609 description: The thread id (root comment id)
4071 schema: 4610 schema:
4072 $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id' 4611 type: integer
4073 commentId: 4612 commentId:
4074 name: commentId 4613 name: commentId
4075 in: path 4614 in: path
@@ -4223,22 +4762,42 @@ components:
4223 - activitypub-refresher 4762 - activitypub-refresher
4224 - video-redundancy 4763 - video-redundancy
4225 - video-live-ending 4764 - video-live-ending
4765 followState:
4766 name: state
4767 in: query
4768 schema:
4769 type: string
4770 enum:
4771 - pending
4772 - accepted
4773 actorType:
4774 name: actorType
4775 in: query
4776 schema:
4777 type: string
4778 enum:
4779 - Person
4780 - Application
4781 - Group
4782 - Service
4783 - Organization
4226 securitySchemes: 4784 securitySchemes:
4227 OAuth2: 4785 OAuth2:
4228 description: | 4786 description: |
4229 Authenticating via OAuth requires the following steps: 4787 Authenticating via OAuth requires the following steps:
4230 - Have an activated account 4788 - Have an activated account
4231 - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a 4789 - [Generate] an access token for that account at `/api/v1/users/token`.
4232 Bearer Token for that account at `/api/v1/users/token` 4790 - Make requests with the *Authorization: Bearer <token\>* header
4233 - Make authenticated requests, putting *Authorization: Bearer <token\>*
4234 - Profit, depending on the role assigned to the account 4791 - Profit, depending on the role assigned to the account
4235 4792
4236 Note that the __access token is valid for 1 day__ and, and is given 4793 Note that the __access token is valid for 1 day__ and is given
4237 along with a __refresh token valid for 2 weeks__. 4794 along with a __refresh token valid for 2 weeks__.
4795
4796 [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4238 type: oauth2 4797 type: oauth2
4239 flows: 4798 flows:
4240 password: 4799 password:
4241 tokenUrl: 'https://peertube.example.com/api/v1/users/token' 4800 tokenUrl: /api/v1/users/token
4242 scopes: 4801 scopes:
4243 admin: Admin scope 4802 admin: Admin scope
4244 moderator: Moderator scope 4803 moderator: Moderator scope
@@ -4256,22 +4815,27 @@ components:
4256 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' 4815 pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4257 minLength: 36 4816 minLength: 36
4258 maxLength: 36 4817 maxLength: 36
4818 shortUUID:
4819 type: string
4820 description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
4821 example: 2y84q2MQUMWPbiEcxNXMgC
4259 username: 4822 username:
4260 type: string 4823 type: string
4261 description: The username of the user 4824 description: immutable name of the user, used to find or mention its actor
4262 example: chocobozzz 4825 example: chocobozzz
4263 pattern: '/^[a-z0-9._]{1,50}$/' 4826 pattern: '/^[a-z0-9._]+$/'
4264 minLength: 1 4827 minLength: 1
4265 maxLength: 50 4828 maxLength: 50
4266 usernameChannel: 4829 usernameChannel:
4267 type: string 4830 type: string
4268 description: The username for the default channel 4831 description: immutable name of the channel, used to interact with its actor
4269 example: The Capybara Channel 4832 example: framasoft_videos
4270 pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/' 4833 pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4834 minLength: 1
4835 maxLength: 50
4271 password: 4836 password:
4272 type: string 4837 type: string
4273 format: password 4838 format: password
4274 description: The password of the user
4275 minLength: 6 4839 minLength: 6
4276 maxLength: 255 4840 maxLength: 255
4277 4841
@@ -4373,7 +4937,7 @@ components:
4373 enum: 4937 enum:
4374 - 0 4938 - 0
4375 - 1 4939 - 1
4376 description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)' 4940 description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
4377 example: 1 4941 example: 1
4378 4942
4379 VideoStateConstant: 4943 VideoStateConstant:
@@ -4483,8 +5047,10 @@ components:
4483 type: integer 5047 type: integer
4484 startTimestamp: 5048 startTimestamp:
4485 type: integer 5049 type: integer
5050 format: seconds
4486 stopTimestamp: 5051 stopTimestamp:
4487 type: integer 5052 type: integer
5053 format: seconds
4488 video: 5054 video:
4489 nullable: true 5055 nullable: true
4490 allOf: 5056 allOf:
@@ -4582,6 +5148,9 @@ components:
4582 description: universal identifier for the video, that can be used across instances 5148 description: universal identifier for the video, that can be used across instances
4583 allOf: 5149 allOf:
4584 - $ref: '#/components/schemas/UUIDv4' 5150 - $ref: '#/components/schemas/UUIDv4'
5151 shortUUID:
5152 allOf:
5153 - $ref: '#/components/schemas/shortUUID'
4585 isLive: 5154 isLive:
4586 type: boolean 5155 type: boolean
4587 createdAt: 5156 createdAt:
@@ -4633,6 +5202,7 @@ components:
4633 duration: 5202 duration:
4634 type: integer 5203 type: integer
4635 example: 1419 5204 example: 1419
5205 format: seconds
4636 description: duration of the video in seconds 5206 description: duration of the video in seconds
4637 isLocal: 5207 isLocal:
4638 type: boolean 5208 type: boolean
@@ -4701,7 +5271,7 @@ components:
4701 support: 5271 support:
4702 type: string 5272 type: string
4703 description: A text tell the audience how to support the video creator 5273 description: A text tell the audience how to support the video creator
4704 example: Please support my work on <insert crowdfunding plateform>! <3 5274 example: Please support our work on https://soutenir.framasoft.org/en/ <3
4705 minLength: 3 5275 minLength: 3
4706 maxLength: 1000 5276 maxLength: 1000
4707 channel: 5277 channel:
@@ -4806,10 +5376,33 @@ components:
4806 label: 5376 label:
4807 type: string 5377 type: string
4808 example: Pending 5378 example: Pending
5379 VideoCreateImport:
5380 allOf:
5381 - type: object
5382 additionalProperties: false
5383 oneOf:
5384 - properties:
5385 targetUrl:
5386 $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5387 required: [targetUrl]
5388 - properties:
5389 magnetUri:
5390 $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5391 required: [magnetUri]
5392 - properties:
5393 torrentfile:
5394 $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5395 required: [torrentfile]
5396 - $ref: '#/components/schemas/VideoUploadRequestCommon'
5397 required:
5398 - channelId
5399 - name
4809 VideoImport: 5400 VideoImport:
4810 properties: 5401 properties:
4811 id: 5402 id:
4812 $ref: '#/components/schemas/id' 5403 readOnly: true
5404 allOf:
5405 - $ref: '#/components/schemas/id'
4813 targetUrl: 5406 targetUrl:
4814 type: string 5407 type: string
4815 format: url 5408 format: url
@@ -4821,19 +5414,31 @@ components:
4821 description: magnet URI allowing to resolve the import's source video 5414 description: magnet URI allowing to resolve the import's source video
4822 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4 5415 example: magnet:?xs=https%3A%2F%2Fframatube.org%2Fstatic%2Ftorrents%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.torrent&xt=urn:btih:38b4747ff788b30bf61f59d1965cd38f9e48e01f&dn=What+is+PeerTube%3F&tr=wss%3A%2F%2Fframatube.org%2Ftracker%2Fsocket&tr=https%3A%2F%2Fframatube.org%2Ftracker%2Fannounce&ws=https%3A%2F%2Fframatube.org%2Fstatic%2Fwebseed%2F9c9de5e8-0a1e-484a-b099-e80766180a6d-240.mp4
4823 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i 5416 pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5417 torrentfile:
5418 writeOnly: true
5419 type: string
5420 format: binary
5421 description: Torrent file containing only the video file
4824 torrentName: 5422 torrentName:
5423 readOnly: true
4825 type: string 5424 type: string
4826 state: 5425 state:
4827 $ref: '#/components/schemas/VideoImportStateConstant' 5426 readOnly: true
5427 allOf:
5428 - $ref: '#/components/schemas/VideoImportStateConstant'
4828 error: 5429 error:
5430 readOnly: true
4829 type: string 5431 type: string
4830 createdAt: 5432 createdAt:
5433 readOnly: true
4831 type: string 5434 type: string
4832 format: date-time 5435 format: date-time
4833 updatedAt: 5436 updatedAt:
5437 readOnly: true
4834 type: string 5438 type: string
4835 format: date-time 5439 format: date-time
4836 video: 5440 video:
5441 readOnly: true
4837 nullable: true 5442 nullable: true
4838 allOf: 5443 allOf:
4839 - $ref: '#/components/schemas/Video' 5444 - $ref: '#/components/schemas/Video'
@@ -4925,6 +5530,9 @@ components:
4925 $ref: '#/components/schemas/id' 5530 $ref: '#/components/schemas/id'
4926 uuid: 5531 uuid:
4927 $ref: '#/components/schemas/UUIDv4' 5532 $ref: '#/components/schemas/UUIDv4'
5533 shortUUID:
5534 allOf:
5535 - $ref: '#/components/schemas/shortUUID'
4928 createdAt: 5536 createdAt:
4929 type: string 5537 type: string
4930 format: date-time 5538 format: date-time
@@ -4963,13 +5571,16 @@ components:
4963 format: url 5571 format: url
4964 text: 5572 text:
4965 type: string 5573 type: string
4966 description: Text of the comment in Markdown 5574 format: html
5575 description: Text of the comment
4967 minLength: 1 5576 minLength: 1
4968 maxLength: 10000 5577 example: This video is wonderful!
4969 threadId: 5578 threadId:
4970 type: integer
4971 inReplyToCommentId:
4972 $ref: '#/components/schemas/id' 5579 $ref: '#/components/schemas/id'
5580 inReplyToCommentId:
5581 nullable: true
5582 allOf:
5583 - $ref: '#/components/schemas/id'
4973 videoId: 5584 videoId:
4974 $ref: '#/components/schemas/Video/properties/id' 5585 $ref: '#/components/schemas/Video/properties/id'
4975 createdAt: 5586 createdAt:
@@ -4978,6 +5589,14 @@ components:
4978 updatedAt: 5589 updatedAt:
4979 type: string 5590 type: string
4980 format: date-time 5591 format: date-time
5592 deletedAt:
5593 nullable: true
5594 type: string
5595 format: date-time
5596 default: null
5597 isDeleted:
5598 type: boolean
5599 default: false
4981 totalRepliesFromVideoAuthor: 5600 totalRepliesFromVideoAuthor:
4982 type: integer 5601 type: integer
4983 minimum: 0 5602 minimum: 0
@@ -5035,7 +5654,7 @@ components:
5035 type: string 5654 type: string
5036 format: url 5655 format: url
5037 name: 5656 name:
5038 description: immutable name of the actor 5657 description: immutable name of the actor, used to find or mention it
5039 allOf: 5658 allOf:
5040 - $ref: '#/components/schemas/username' 5659 - $ref: '#/components/schemas/username'
5041 host: 5660 host:
@@ -5071,7 +5690,9 @@ components:
5071 - $ref: '#/components/schemas/User/properties/id' 5690 - $ref: '#/components/schemas/User/properties/id'
5072 displayName: 5691 displayName:
5073 type: string 5692 type: string
5074 description: name displayed on the account's profile 5693 description: editable name of the account, displayed in its representations
5694 minLength: 3
5695 maxLength: 120
5075 description: 5696 description:
5076 type: string 5697 type: string
5077 description: text or bio displayed on the account's profile 5698 description: text or bio displayed on the account's profile
@@ -5079,6 +5700,7 @@ components:
5079 properties: 5700 properties:
5080 currentTime: 5701 currentTime:
5081 type: integer 5702 type: integer
5703 format: seconds
5082 description: timestamp within the video, in seconds 5704 description: timestamp within the video, in seconds
5083 example: 5 5705 example: 5
5084 ServerConfig: 5706 ServerConfig:
@@ -5280,6 +5902,12 @@ components:
5280 indexUrl: 5902 indexUrl:
5281 type: string 5903 type: string
5282 format: url 5904 format: url
5905 homepage:
5906 type: object
5907 properties:
5908 enabled:
5909 type: boolean
5910
5283 ServerConfigAbout: 5911 ServerConfigAbout:
5284 properties: 5912 properties:
5285 instance: 5913 instance:
@@ -5470,6 +6098,12 @@ components:
5470 type: boolean 6098 type: boolean
5471 manualApproval: 6099 manualApproval:
5472 type: boolean 6100 type: boolean
6101
6102 CustomHomepage:
6103 properties:
6104 content:
6105 type: string
6106
5473 Follow: 6107 Follow:
5474 properties: 6108 properties:
5475 id: 6109 id:
@@ -5593,7 +6227,7 @@ components:
5593 type: boolean 6227 type: boolean
5594 support: 6228 support:
5595 description: A text tell the audience how to support the video creator 6229 description: A text tell the audience how to support the video creator
5596 example: Please support my work on <insert crowdfunding plateform>! <3 6230 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5597 type: string 6231 type: string
5598 nsfw: 6232 nsfw:
5599 description: Whether or not this video contains sensitive content 6233 description: Whether or not this video contains sensitive content
@@ -5674,6 +6308,8 @@ components:
5674 $ref: '#/components/schemas/Video/properties/id' 6308 $ref: '#/components/schemas/Video/properties/id'
5675 uuid: 6309 uuid:
5676 $ref: '#/components/schemas/Video/properties/uuid' 6310 $ref: '#/components/schemas/Video/properties/uuid'
6311 shortUUID:
6312 $ref: '#/components/schemas/Video/properties/shortUUID'
5677 CommentThreadResponse: 6313 CommentThreadResponse:
5678 properties: 6314 properties:
5679 total: 6315 total:
@@ -5775,7 +6411,7 @@ components:
5775 # optionally present fields: they require WITH_STATS scope 6411 # optionally present fields: they require WITH_STATS scope
5776 videosCount: 6412 videosCount:
5777 type: integer 6413 type: integer
5778 description: Count of videos published 6414 description: Count of videos published
5779 abusesCount: 6415 abusesCount:
5780 type: integer 6416 type: integer
5781 description: Count of reports/abuses of which the user is a target 6417 description: Count of reports/abuses of which the user is a target
@@ -5822,9 +6458,9 @@ components:
5822 UpdateUser: 6458 UpdateUser:
5823 properties: 6459 properties:
5824 email: 6460 email:
5825 type: string
5826 format: email
5827 description: The updated email of the user 6461 description: The updated email of the user
6462 allOf:
6463 - $ref: '#/components/schemas/User/properties/email'
5828 emailVerified: 6464 emailVerified:
5829 type: boolean 6465 type: boolean
5830 description: Set the email as verified 6466 description: Set the email as verified
@@ -5844,28 +6480,54 @@ components:
5844 adminFlags: 6480 adminFlags:
5845 $ref: '#/components/schemas/UserAdminFlags' 6481 $ref: '#/components/schemas/UserAdminFlags'
5846 UpdateMe: 6482 UpdateMe:
6483 # see shared/models/users/user-update-me.model.ts:
5847 properties: 6484 properties:
5848 password: 6485 password:
5849 $ref: '#/components/schemas/password' 6486 $ref: '#/components/schemas/password'
6487 currentPassword:
6488 $ref: '#/components/schemas/password'
5850 email: 6489 email:
6490 description: new email used for login and service communications
6491 allOf:
6492 - $ref: '#/components/schemas/User/properties/email'
6493 displayName:
5851 type: string 6494 type: string
5852 format: email 6495 description: new name of the user in its representations
5853 description: Your new email 6496 minLength: 3
6497 maxLength: 120
5854 displayNSFW: 6498 displayNSFW:
5855 type: string 6499 type: string
5856 description: Your new displayNSFW 6500 description: new NSFW display policy
5857 enum: 6501 enum:
5858 - 'true' 6502 - 'true'
5859 - 'false' 6503 - 'false'
5860 - both 6504 - both
6505 webTorrentEnabled:
6506 type: boolean
6507 description: whether to enable P2P in the player or not
5861 autoPlayVideo: 6508 autoPlayVideo:
5862 type: boolean 6509 type: boolean
5863 description: Your new autoPlayVideo 6510 description: new preference regarding playing videos automatically
5864 required: 6511 autoPlayNextVideo:
5865 - password 6512 type: boolean
5866 - email 6513 description: new preference regarding playing following videos automatically
5867 - displayNSFW 6514 autoPlayNextVideoPlaylist:
5868 - autoPlayVideo 6515 type: boolean
6516 description: new preference regarding playing following playlist videos automatically
6517 videosHistoryEnabled:
6518 type: boolean
6519 description: whether to keep track of watched history or not
6520 videoLanguages:
6521 type: array
6522 items:
6523 type: string
6524 description: list of languages to filter videos down to
6525 theme:
6526 type: string
6527 noInstanceConfigWarningModal:
6528 type: boolean
6529 noWelcomeModal:
6530 type: boolean
5869 GetMeVideoRating: 6531 GetMeVideoRating:
5870 properties: 6532 properties:
5871 id: 6533 id:
@@ -5897,38 +6559,94 @@ components:
5897 RegisterUser: 6559 RegisterUser:
5898 properties: 6560 properties:
5899 username: 6561 username:
5900 $ref: '#/components/schemas/username' 6562 description: immutable name of the user, used to find or mention its actor
6563 allOf:
6564 - $ref: '#/components/schemas/username'
5901 password: 6565 password:
5902 $ref: '#/components/schemas/password' 6566 $ref: '#/components/schemas/password'
5903 email: 6567 email:
5904 type: string 6568 type: string
5905 format: email 6569 format: email
5906 description: The email of the user 6570 description: email of the user, used for login or service communications
5907 displayName: 6571 displayName:
5908 type: string 6572 type: string
5909 description: The user display name 6573 description: editable name of the user, displayed in its representations
5910 minLength: 1 6574 minLength: 1
5911 maxLength: 120 6575 maxLength: 120
5912 channel: 6576 channel:
5913 type: object 6577 type: object
6578 description: channel base information used to create the first channel of the user
5914 properties: 6579 properties:
5915 name: 6580 name:
5916 $ref: '#/components/schemas/usernameChannel' 6581 $ref: '#/components/schemas/usernameChannel'
5917 displayName: 6582 displayName:
5918 type: string 6583 $ref: '#/components/schemas/VideoChannel/properties/displayName'
5919 description: The display name for the default channel
5920 minLength: 1
5921 maxLength: 120
5922 required: 6584 required:
5923 - username 6585 - username
5924 - password 6586 - password
5925 - email 6587 - email
5926 6588
6589 OAuthClient:
6590 properties:
6591 client_id:
6592 type: string
6593 pattern: /^[a-z0-9]$/
6594 maxLength: 32
6595 minLength: 32
6596 example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6597 client_secret:
6598 type: string
6599 pattern: /^[a-zA-Z0-9]$/
6600 maxLength: 32
6601 minLength: 32
6602 example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6603 OAuthToken-password:
6604 allOf:
6605 - $ref: '#/components/schemas/OAuthClient'
6606 - type: object
6607 properties:
6608 grant_type:
6609 type: string
6610 enum:
6611 - password
6612 - refresh_token
6613 default: password
6614 username:
6615 $ref: '#/components/schemas/User/properties/username'
6616 password:
6617 $ref: '#/components/schemas/password'
6618 required:
6619 - client_id
6620 - client_secret
6621 - grant_type
6622 - username
6623 - password
6624 OAuthToken-refresh_token:
6625 allOf:
6626 - $ref: '#/components/schemas/OAuthClient'
6627 - type: object
6628 properties:
6629 grant_type:
6630 type: string
6631 enum:
6632 - password
6633 - refresh_token
6634 default: password
6635 refresh_token:
6636 type: string
6637 example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6638 required:
6639 - client_id
6640 - client_secret
6641 - grant_type
6642 - refresh_token
6643
5927 VideoChannel: 6644 VideoChannel:
5928 properties: 6645 properties:
5929 # GET/POST/PUT properties 6646 # GET/POST/PUT properties
5930 displayName: 6647 displayName:
5931 type: string 6648 type: string
6649 description: editable name of the channel, displayed in its representations
5932 example: Videos of Framasoft 6650 example: Videos of Framasoft
5933 minLength: 1 6651 minLength: 1
5934 maxLength: 120 6652 maxLength: 120
@@ -5940,7 +6658,7 @@ components:
5940 support: 6658 support:
5941 type: string 6659 type: string
5942 description: text shown by default on all videos of this channel, to tell the audience how to support it 6660 description: text shown by default on all videos of this channel, to tell the audience how to support it
5943 example: Please support my work on <insert crowdfunding plateform>! <3 6661 example: Please support our work on https://soutenir.framasoft.org/en/ <3
5944 minLength: 3 6662 minLength: 3
5945 maxLength: 1000 6663 maxLength: 1000
5946 # GET-only properties 6664 # GET-only properties
diff --git a/support/doc/dependencies.md b/support/doc/dependencies.md
index 939772a9d..8ea0c047d 100644
--- a/support/doc/dependencies.md
+++ b/support/doc/dependencies.md
@@ -1,6 +1,6 @@
1# Dependencies 1# Dependencies
2 2
3Follow the below guides, and check their versions match [required external dependencies versions](https://github.com/Chocobozzz/PeerTube/blob/master/package.json#7). You can check them automatically via `sudo npx engineslist`. 3Follow the below guides, and check their versions match [required external dependencies versions](https://github.com/Chocobozzz/PeerTube/blob/master/engines.yaml). You can check them automatically via `sudo npx engineslist`.
4 4
5_note_: only **LTS** versions of external dependencies are supported. If no LTS version matching the version constraint is available, only **release** versions are supported. 5_note_: only **LTS** versions of external dependencies are supported. If no LTS version matching the version constraint is available, only **release** versions are supported.
6 6
@@ -30,7 +30,7 @@ _note_: only **LTS** versions of external dependencies are supported. If no LTS
30 30
312. It would be wise to disable root access and to continue this tutorial with a user with sudoers group access 312. It would be wise to disable root access and to continue this tutorial with a user with sudoers group access
32 32
333. Install NodeJS 12.x: 333. Install NodeJS 14.x:
34[https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions) 34[https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)
354. Install yarn, and be sure to have [a recent version](https://github.com/yarnpkg/yarn/releases/latest): 354. Install yarn, and be sure to have [a recent version](https://github.com/yarnpkg/yarn/releases/latest):
36[https://yarnpkg.com/en/docs/install#linux-tab](https://yarnpkg.com/en/docs/install#linux-tab) 36[https://yarnpkg.com/en/docs/install#linux-tab](https://yarnpkg.com/en/docs/install#linux-tab)
@@ -101,7 +101,7 @@ sudo -H -u peertube CC=/opt/rh/devtoolset-7/root/usr/bin/gcc CXX=/opt/rh/devtool
1016. Initialize the PostgreSQL database: 1016. Initialize the PostgreSQL database:
102 102
103``` 103```
104sudo postgresql-setup initdb 104sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
105``` 105```
106 106
107Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis: 107Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis:
@@ -141,7 +141,7 @@ sudo ln -s /usr/bin/python3 /usr/bin/python
1416. Initialize the PostgreSQL database: 1416. Initialize the PostgreSQL database:
142 142
143``` 143```
144sudo postgresql-setup initdb 144sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
145``` 145```
146 146
147Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis: 147Now that dependencies are installed, before running PeerTube you should enable and start PostgreSQL and Redis:
@@ -188,19 +188,27 @@ This is necessary because `ffmpeg` is not in the Fedora repos.
1887. Run: 1887. Run:
189 189
190``` 190```
191sudo dnf install nginx ffmpeg postgresql-server postgresql-contrib openssl gcc-c++ make redis git 191sudo dnf install nginx ffmpeg postgresql-server postgresql-contrib openssl gcc-c++ make redis git vim
192ffmpeg -version # Should be >= 4.1 192ffmpeg -version # Should be >= 4.1
193g++ -v # Should be >= 5.x 193g++ -v # Should be >= 5.x
194``` 194```
195 195
1968. Post-installation 1968. Configure nginx
197
198```
199sudo mkdir /etc/nginx/sites-available
200sudo mkdir /etc/nginx/sites-enabled
201sudo ln -s /etc/nginx/sites-enabled/peertube /etc/nginx/conf.d/peertube.conf
202```
203
2049. Post-installation
197 205
198_from [PostgreSQL documentation](https://www.postgresql.org/download/linux/redhat/):_ 206_from [PostgreSQL documentation](https://www.postgresql.org/download/linux/redhat/):_
199> Due to policies for Red Hat family distributions, the PostgreSQL installation will not be enabled for automatic start or have the database initialized automatically. 207> Due to policies for Red Hat family distributions, the PostgreSQL installation will not be enabled for automatic start or have the database initialized automatically.
200 208
201``` 209```
202# PostgreSQL 210# PostgreSQL
203sudo postgresql-setup initdb 211sudo PGSETUP_INITDB_OPTIONS='--auth-host=md5' postgresql-setup --initdb --unit postgresql
204sudo systemctl enable postgresql.service 212sudo systemctl enable postgresql.service
205sudo systemctl start postgresql.service 213sudo systemctl start postgresql.service
206# Nginx 214# Nginx
@@ -211,7 +219,7 @@ sudo systemctl enable redis.service
211sudo systemctl start redis.service 219sudo systemctl start redis.service
212``` 220```
213 221
2149. Firewall 22210. Firewall
215 223
216By default, you cannot access your server via public IP. To do so, you must configure firewall: 224By default, you cannot access your server via public IP. To do so, you must configure firewall:
217 225
@@ -226,7 +234,7 @@ sudo firewall-cmd --permanent --zone=public --add-service=https
226sudo firewall-cmd --reload 234sudo firewall-cmd --reload
227``` 235```
228 236
22910. Configure max ports 23711. Configure max ports
230 238
231This is necessary if you are running dev setup, otherwise you will have errors with `nodemon` 239This is necessary if you are running dev setup, otherwise you will have errors with `nodemon`
232 240
@@ -321,7 +329,7 @@ dev-db/postgresql
321dev-db/redis 329dev-db/redis
322dev-vcs/git 330dev-vcs/git
323app-arch/unzip 331app-arch/unzip
324dev-lang/python:2.7 332dev-lang/python
325www-servers/nginx 333www-servers/nginx
326 334
327# Optional, client for Let’s Encrypt: 335# Optional, client for Let’s Encrypt:
diff --git a/support/doc/plugins/guide.md b/support/doc/plugins/guide.md
index d3b9db0ed..568c0662f 100644
--- a/support/doc/plugins/guide.md
+++ b/support/doc/plugins/guide.md
@@ -21,6 +21,7 @@
21 - [Notifier](#notifier) 21 - [Notifier](#notifier)
22 - [Markdown Renderer](#markdown-renderer) 22 - [Markdown Renderer](#markdown-renderer)
23 - [Auth header](#auth-header) 23 - [Auth header](#auth-header)
24 - [Plugin router route](#plugin-router-route)
24 - [Custom Modal](#custom-modal) 25 - [Custom Modal](#custom-modal)
25 - [Translate](#translate) 26 - [Translate](#translate)
26 - [Get public settings](#get-public-settings) 27 - [Get public settings](#get-public-settings)
@@ -28,6 +29,7 @@
28 - [Add custom fields to video form](#add-custom-fields-to-video-form) 29 - [Add custom fields to video form](#add-custom-fields-to-video-form)
29 - [Register settings script](#register-settings-script) 30 - [Register settings script](#register-settings-script)
30 - [HTML placeholder elements](#html-placeholder-elements) 31 - [HTML placeholder elements](#html-placeholder-elements)
32 - [Add/remove left menu links](#addremove-left-menu-links)
31 - [Publishing](#publishing) 33 - [Publishing](#publishing)
32- [Write a plugin/theme](#write-a-plugintheme) 34- [Write a plugin/theme](#write-a-plugintheme)
33 - [Clone the quickstart repository](#clone-the-quickstart-repository) 35 - [Clone the quickstart repository](#clone-the-quickstart-repository)
@@ -561,6 +563,27 @@ function register (...) {
561} 563}
562``` 564```
563 565
566#### Plugin router route
567
568**PeerTube >= 3.3**
569
570To get your plugin router route, you can use `peertubeHelpers.getBaseRouterRoute()`:
571
572```js
573function register (...) {
574 registerHook({
575 target: 'action:video-watch.video.loaded',
576 handler: ({ video }) => {
577 fetch(peertubeHelpers.getBaseRouterRoute() + '/my/plugin/api', {
578 method: 'GET',
579 headers: peertubeHelpers.getAuthHeader()
580 }).then(res => res.json())
581 .then(data => console.log('Hi %s.', data))
582 }
583 })
584}
585```
586
564#### Custom Modal 587#### Custom Modal
565 588
566To show a custom modal: 589To show a custom modal:
@@ -722,10 +745,16 @@ async function register (...) {
722 745
723See the complete list on https://docs.joinpeertube.org/api-plugins 746See the complete list on https://docs.joinpeertube.org/api-plugins
724 747
748#### Add/remove left menu links
749
750Left menu links can be filtered (add/remove a section or add/remove links) using the `filter:left-menu.links.create.result` client hook.
751
752
725### Publishing 753### Publishing
726 754
727PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes 755PeerTube plugins and themes should be published on [NPM](https://www.npmjs.com/) so that PeerTube indexes take into account your plugin (after ~ 1 day). An official plugin index is available on [packages.joinpeertube.org](https://packages.joinpeertube.org/api/v1/plugins), with no interface to present packages.
728take into account your plugin (after ~ 1 day). An official PeerTube index is available on https://packages.joinpeertube.org/ (it's just a REST API, so don't expect a beautiful website). 756
757> The official plugin index source code is available at https://framagit.org/framasoft/peertube/plugin-index
729 758
730## Write a plugin/theme 759## Write a plugin/theme
731 760
@@ -910,6 +939,12 @@ $ npm publish
910Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json` 939Every time you want to publish another version of your plugin/theme, just update the `version` key from the `package.json`
911and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours. 940and republish it on NPM. Remember that the PeerTube index will take into account your new plugin/theme version after ~24 hours.
912 941
942> If you need to force your plugin update on a specific __PeerTube__ instance, you may update the latest available version manually:
943> ```sql
944> UPDATE "plugin" SET "latestVersion" = 'X.X.X' WHERE "plugin"."name" = 'plugin-shortname';
945> ```
946> You'll then be able to click the __Update plugin__ button on the plugin list.
947
913### Unpublish 948### Unpublish
914 949
915If for a particular reason you don't want to maintain your plugin/theme anymore 950If for a particular reason you don't want to maintain your plugin/theme anymore
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-01 06:04:33 +0000