support/doc/api/openapi.yaml

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