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<sup>*</sup>    | 5 minutes                 |
  73     | `POST /users/ask-send-verify-email` | 3    | 5 minutes                 |
  74
  75     Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
  76     limit is announced by a `429 Too Many Requests` status code.
  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                   allOf:
2879                     - $ref: '#/components/schemas/VideoComment/properties/text'
2880                   format: markdown
2881                   maxLength: 10000
2882               required:
2883                 - text
2884
2885   '/videos/{id}/comment-threads/{threadId}':
2886     get:
2887       summary: Get a thread
2888       tags:
2889         - Video Comments
2890       parameters:
2891         - $ref: '#/components/parameters/idOrUUID'
2892         - $ref: '#/components/parameters/threadId'
2893       responses:
2894         '200':
2895           description: successful operation
2896           content:
2897             application/json:
2898               schema:
2899                 $ref: '#/components/schemas/VideoCommentThreadTree'
2900   '/videos/{id}/comments/{commentId}':
2901     post:
2902       summary: Reply to a thread of a video
2903       security:
2904         - OAuth2: []
2905       tags:
2906         - Video Comments
2907       parameters:
2908         - $ref: '#/components/parameters/idOrUUID'
2909         - $ref: '#/components/parameters/commentId'
2910       responses:
2911         '200':
2912           description: successful operation
2913           content:
2914             application/json:
2915               schema:
2916                 $ref: '#/components/schemas/CommentThreadPostResponse'
2917         '404':
2918           description: thread or video does not exist
2919       requestBody:
2920         content:
2921           application/json:
2922             schema:
2923               type: object
2924               properties:
2925                 text:
2926                   allOf:
2927                     - $ref: '#/components/schemas/VideoComment/properties/text'
2928                   format: markdown
2929                   maxLength: 10000
2930               required:
2931                 - text
2932
2933     delete:
2934       summary: Delete a comment or a reply
2935       security:
2936         - OAuth2: []
2937       tags:
2938         - Video Comments
2939       parameters:
2940         - $ref: '#/components/parameters/idOrUUID'
2941         - $ref: '#/components/parameters/commentId'
2942       responses:
2943         '204':
2944           description: successful operation
2945         '403':
2946           description: cannot remove comment of another user
2947         '404':
2948           description: comment or video does not exist
2949         '409':
2950           description: comment is already deleted
2951   '/videos/{id}/rate':
2952     put:
2953       summary: Like/dislike a video
2954       security:
2955         - OAuth2: []
2956       tags:
2957         - Video Rates
2958       parameters:
2959         - $ref: '#/components/parameters/idOrUUID'
2960       responses:
2961         '204':
2962           description: successful operation
2963         '404':
2964           description: video does not exist
2965   /search/videos:
2966     get:
2967       tags:
2968         - Search
2969       summary: Search videos
2970       parameters:
2971         - name: search
2972           in: query
2973           required: true
2974           allowEmptyValue: false
2975           description: >
2976             String to search. If the user can make a remote URI search, and the string is an URI then the
2977             PeerTube instance will fetch the remote object and add it to its database. Then,
2978             you can use the REST API to fetch the complete video information and interact with it.
2979           schema:
2980             type: string
2981         - $ref: '#/components/parameters/categoryOneOf'
2982         - $ref: '#/components/parameters/isLive'
2983         - $ref: '#/components/parameters/tagsOneOf'
2984         - $ref: '#/components/parameters/tagsAllOf'
2985         - $ref: '#/components/parameters/licenceOneOf'
2986         - $ref: '#/components/parameters/languageOneOf'
2987         - $ref: '#/components/parameters/nsfw'
2988         - $ref: '#/components/parameters/filter'
2989         - $ref: '#/components/parameters/skipCount'
2990         - $ref: '#/components/parameters/start'
2991         - $ref: '#/components/parameters/count'
2992         - $ref: '#/components/parameters/searchTarget'
2993         - $ref: '#/components/parameters/videosSearchSort'
2994         - name: startDate
2995           in: query
2996           description: Get videos that are published after this date
2997           schema:
2998             type: string
2999             format: date-time
3000         - name: endDate
3001           in: query
3002           description: Get videos that are published before this date
3003           schema:
3004             type: string
3005             format: date-time
3006         - name: originallyPublishedStartDate
3007           in: query
3008           description: Get videos that are originally published after this date
3009           schema:
3010             type: string
3011             format: date-time
3012         - name: originallyPublishedEndDate
3013           in: query
3014           description: Get videos that are originally published before this date
3015           schema:
3016             type: string
3017             format: date-time
3018         - name: durationMin
3019           in: query
3020           description: Get videos that have this minimum duration
3021           schema:
3022             type: integer
3023         - name: durationMax
3024           in: query
3025           description: Get videos that have this maximum duration
3026           schema:
3027             type: integer
3028       callbacks:
3029         'searchTarget === search-index':
3030           $ref: '#/components/callbacks/searchIndex'
3031       responses:
3032         '200':
3033           description: successful operation
3034           content:
3035             application/json:
3036               schema:
3037                 $ref: '#/components/schemas/VideoListResponse'
3038         '500':
3039           description: search index unavailable
3040   /search/video-channels:
3041     get:
3042       tags:
3043         - Search
3044       summary: Search channels
3045       parameters:
3046         - name: search
3047           in: query
3048           required: true
3049           description: >
3050             String to search. If the user can make a remote URI search, and the string is an URI then the
3051             PeerTube instance will fetch the remote object and add it to its database. Then,
3052             you can use the REST API to fetch the complete channel information and interact with it.
3053           schema:
3054             type: string
3055         - $ref: '#/components/parameters/start'
3056         - $ref: '#/components/parameters/count'
3057         - $ref: '#/components/parameters/searchTarget'
3058         - $ref: '#/components/parameters/sort'
3059       callbacks:
3060         'searchTarget === search-index':
3061           $ref: '#/components/callbacks/searchIndex'
3062       responses:
3063         '200':
3064           description: successful operation
3065           content:
3066             application/json:
3067               schema:
3068                 $ref: '#/components/schemas/VideoChannelList'
3069         '500':
3070           description: search index unavailable
3071   /blocklist/accounts:
3072     get:
3073       tags:
3074         - Account Blocks
3075       summary: List account blocks
3076       security:
3077         - OAuth2:
3078           - admin
3079       parameters:
3080         - $ref: '#/components/parameters/start'
3081         - $ref: '#/components/parameters/count'
3082         - $ref: '#/components/parameters/sort'
3083       responses:
3084         '200':
3085           description: successful operation
3086     post:
3087       tags:
3088         - Account Blocks
3089       summary: Block an account
3090       security:
3091         - OAuth2:
3092           - admin
3093       requestBody:
3094         content:
3095           application/json:
3096             schema:
3097               type: object
3098               properties:
3099                 accountName:
3100                   type: string
3101                   example: chocobozzz@example.org
3102                   description: account to block, in the form `username@domain`
3103               required:
3104                 - accountName
3105       responses:
3106         '200':
3107           description: successful operation
3108         '409':
3109           description: self-blocking forbidden
3110   '/blocklist/accounts/{accountName}':
3111     delete:
3112       tags:
3113         - Account Blocks
3114       summary: Unblock an account by its handle
3115       security:
3116         - OAuth2:
3117           - admin
3118       parameters:
3119         - name: accountName
3120           in: path
3121           required: true
3122           description: account to unblock, in the form `username@domain`
3123           schema:
3124             type: string
3125       responses:
3126         '201':
3127           description: successful operation
3128         '404':
3129           description: account or account block does not exist
3130   /blocklist/servers:
3131     get:
3132       tags:
3133         - Server Blocks
3134       summary: List server blocks
3135       security:
3136         - OAuth2:
3137           - admin
3138       parameters:
3139         - $ref: '#/components/parameters/start'
3140         - $ref: '#/components/parameters/count'
3141         - $ref: '#/components/parameters/sort'
3142       responses:
3143         '200':
3144           description: successful operation
3145     post:
3146       tags:
3147         - Server Blocks
3148       summary: Block a server
3149       security:
3150         - OAuth2:
3151           - admin
3152       requestBody:
3153         content:
3154           application/json:
3155             schema:
3156               type: object
3157               properties:
3158                 host:
3159                   type: string
3160                   format: hostname
3161                   description: server domain to block
3162               required:
3163                 - host
3164       responses:
3165         '200':
3166           description: successful operation
3167         '409':
3168           description: self-blocking forbidden
3169   '/blocklist/servers/{host}':
3170     delete:
3171       tags:
3172         - Server Blocks
3173       summary: Unblock a server by its domain
3174       security:
3175         - OAuth2:
3176           - admin
3177       parameters:
3178         - name: host
3179           in: path
3180           required: true
3181           description: server domain to unblock
3182           schema:
3183             type: string
3184             format: hostname
3185       responses:
3186         '201':
3187           description: successful operation
3188         '404':
3189           description: account block does not exist
3190   /redundancy/{host}:
3191     put:
3192       tags:
3193         - Instance Redundancy
3194       summary: Update a server redundancy policy
3195       security:
3196         - OAuth2:
3197           - admin
3198       parameters:
3199         - name: host
3200           in: path
3201           required: true
3202           description: server domain to mirror
3203           schema:
3204             type: string
3205             format: hostname
3206       requestBody:
3207         content:
3208           application/json:
3209             schema:
3210               type: object
3211               properties:
3212                 redundancyAllowed:
3213                   type: boolean
3214                   description: allow mirroring of the host's local videos
3215               required:
3216                 - redundancyAllowed
3217       responses:
3218         '204':
3219           description: successful operation
3220         '404':
3221           description: server is not already known
3222   /redundancy/videos:
3223     get:
3224       tags:
3225         - Video Mirroring
3226       summary: List videos being mirrored
3227       security:
3228         - OAuth2:
3229           - admin
3230       parameters:
3231         - name: target
3232           in: query
3233           required: true
3234           description: direction of the mirror
3235           schema:
3236             type: string
3237             enum:
3238               - my-videos
3239               - remote-videos
3240         - $ref: '#/components/parameters/start'
3241         - $ref: '#/components/parameters/count'
3242         - $ref: '#/components/parameters/videoRedundanciesSort'
3243       responses:
3244         '200':
3245           description: successful operation
3246           content:
3247             application/json:
3248               schema:
3249                 type: array
3250                 items:
3251                   $ref: '#/components/schemas/VideoRedundancy'
3252     post:
3253       tags:
3254         - Video Mirroring
3255       summary: Mirror a video
3256       security:
3257         - OAuth2:
3258           - admin
3259       requestBody:
3260         content:
3261           application/json:
3262             schema:
3263               type: object
3264               properties:
3265                 videoId:
3266                   $ref: '#/components/schemas/Video/properties/id'
3267               required:
3268                 - videoId
3269       responses:
3270         '204':
3271           description: successful operation
3272         '400':
3273           description: cannot mirror a local video
3274         '404':
3275           description: video does not exist
3276         '409':
3277           description: video is already mirrored
3278   /redundancy/videos/{redundancyId}:
3279     delete:
3280       tags:
3281         - Video Mirroring
3282       summary: Delete a mirror done on a video
3283       security:
3284         - OAuth2:
3285           - admin
3286       parameters:
3287         - name: redundancyId
3288           in: path
3289           required: true
3290           description: id of an existing redundancy on a video
3291           schema:
3292             type: string
3293       responses:
3294         '204':
3295           description: successful operation
3296         '404':
3297           description: video redundancy not found
3298   '/feeds/video-comments.{format}':
3299     get:
3300       tags:
3301         - Feeds
3302       summary: List comments on videos
3303       parameters:
3304         - name: format
3305           in: path
3306           required: true
3307           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3308           schema:
3309             type: string
3310             enum:
3311               - xml
3312               - rss
3313               - rss2
3314               - atom
3315               - atom1
3316               - json
3317               - json1
3318         - name: videoId
3319           in: query
3320           description: 'limit listing to a specific video'
3321           schema:
3322             type: string
3323         - name: accountId
3324           in: query
3325           description: 'limit listing to a specific account'
3326           schema:
3327             type: string
3328         - name: accountName
3329           in: query
3330           description: 'limit listing to a specific account'
3331           schema:
3332             type: string
3333         - name: videoChannelId
3334           in: query
3335           description: 'limit listing to a specific video channel'
3336           schema:
3337             type: string
3338         - name: videoChannelName
3339           in: query
3340           description: 'limit listing to a specific video channel'
3341           schema:
3342             type: string
3343       responses:
3344         '204':
3345           description: successful operation
3346           headers:
3347             Cache-Control:
3348               schema:
3349                 type: string
3350                 default: 'max-age=900' # 15 min cache
3351           content:
3352             application/xml:
3353               schema:
3354                 $ref: '#/components/schemas/VideoCommentsForXML'
3355               examples:
3356                 nightly:
3357                   externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3358             application/rss+xml:
3359               schema:
3360                 $ref: '#/components/schemas/VideoCommentsForXML'
3361               examples:
3362                 nightly:
3363                   externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3364             text/xml:
3365               schema:
3366                 $ref: '#/components/schemas/VideoCommentsForXML'
3367               examples:
3368                 nightly:
3369                   externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3370             application/atom+xml:
3371               schema:
3372                 $ref: '#/components/schemas/VideoCommentsForXML'
3373               examples:
3374                 nightly:
3375                   externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3376             application/json:
3377               schema:
3378                 type: object
3379               examples:
3380                 nightly:
3381                   externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3382         '400':
3383           x-summary: field inconsistencies
3384           description: >
3385             Arises when:
3386               - videoId filter is mixed with a channel filter
3387         '404':
3388           description: video, video channel or account not found
3389         '406':
3390           description: accept header unsupported
3391   '/feeds/videos.{format}':
3392     get:
3393       tags:
3394         - Feeds
3395       summary: List videos
3396       parameters:
3397         - name: format
3398           in: path
3399           required: true
3400           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3401           schema:
3402             type: string
3403             enum:
3404               - xml
3405               - rss
3406               - rss2
3407               - atom
3408               - atom1
3409               - json
3410               - json1
3411         - name: accountId
3412           in: query
3413           description: 'limit listing to a specific account'
3414           schema:
3415             type: string
3416         - name: accountName
3417           in: query
3418           description: 'limit listing to a specific account'
3419           schema:
3420             type: string
3421         - name: videoChannelId
3422           in: query
3423           description: 'limit listing to a specific video channel'
3424           schema:
3425             type: string
3426         - name: videoChannelName
3427           in: query
3428           description: 'limit listing to a specific video channel'
3429           schema:
3430             type: string
3431         - $ref: '#/components/parameters/sort'
3432         - $ref: '#/components/parameters/nsfw'
3433         - $ref: '#/components/parameters/filter'
3434       responses:
3435         '204':
3436           description: successful operation
3437           headers:
3438             Cache-Control:
3439               schema:
3440                 type: string
3441                 default: 'max-age=900' # 15 min cache
3442           content:
3443             application/xml:
3444               schema:
3445                 $ref: '#/components/schemas/VideosForXML'
3446               examples:
3447                 nightly:
3448                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3449             application/rss+xml:
3450               schema:
3451                 $ref: '#/components/schemas/VideosForXML'
3452               examples:
3453                 nightly:
3454                   externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3455             text/xml:
3456               schema:
3457                 $ref: '#/components/schemas/VideosForXML'
3458               examples:
3459                 nightly:
3460                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3461             application/atom+xml:
3462               schema:
3463                 $ref: '#/components/schemas/VideosForXML'
3464               examples:
3465                 nightly:
3466                   externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3467             application/json:
3468               schema:
3469                 type: object
3470               examples:
3471                 nightly:
3472                   externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3473         '404':
3474           description: video channel or account not found
3475         '406':
3476           description: accept header unsupported
3477   '/feeds/subscriptions.{format}':
3478     get:
3479       tags:
3480         - Feeds
3481         - Account
3482       summary: List videos of subscriptions tied to a token
3483       parameters:
3484         - name: format
3485           in: path
3486           required: true
3487           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3488           schema:
3489             type: string
3490             enum:
3491               - xml
3492               - rss
3493               - rss2
3494               - atom
3495               - atom1
3496               - json
3497               - json1
3498         - name: accountId
3499           in: query
3500           description: limit listing to a specific account
3501           schema:
3502             type: string
3503           required: true
3504         - name: token
3505           in: query
3506           description: private token allowing access
3507           schema:
3508             type: string
3509           required: true
3510         - $ref: '#/components/parameters/sort'
3511         - $ref: '#/components/parameters/nsfw'
3512         - $ref: '#/components/parameters/filter'
3513       responses:
3514         '204':
3515           description: successful operation
3516           headers:
3517             Cache-Control:
3518               schema:
3519                 type: string
3520                 default: 'max-age=900' # 15 min cache
3521           content:
3522             application/xml:
3523               schema:
3524                 $ref: '#/components/schemas/VideosForXML'
3525             application/rss+xml:
3526               schema:
3527                 $ref: '#/components/schemas/VideosForXML'
3528             text/xml:
3529               schema:
3530                 $ref: '#/components/schemas/VideosForXML'
3531             application/atom+xml:
3532               schema:
3533                 $ref: '#/components/schemas/VideosForXML'
3534             application/json:
3535               schema:
3536                 type: object
3537         '406':
3538           description: accept header unsupported
3539   /plugins:
3540     get:
3541       tags:
3542         - Plugins
3543       summary: List plugins
3544       security:
3545         - OAuth2:
3546           - admin
3547       parameters:
3548         - name: pluginType
3549           in: query
3550           schema:
3551             type: integer
3552         - name: uninstalled
3553           in: query
3554           schema:
3555             type: boolean
3556         - $ref: '#/components/parameters/start'
3557         - $ref: '#/components/parameters/count'
3558         - $ref: '#/components/parameters/sort'
3559       responses:
3560         '200':
3561           description: successful operation
3562           content:
3563             application/json:
3564               schema:
3565                 $ref: '#/components/schemas/PluginResponse'
3566   /plugins/available:
3567     get:
3568       tags:
3569         - Plugins
3570       summary: List available plugins
3571       security:
3572         - OAuth2:
3573           - admin
3574       parameters:
3575         - name: search
3576           in: query
3577           schema:
3578             type: string
3579         - name: pluginType
3580           in: query
3581           schema:
3582             type: integer
3583         - name: currentPeerTubeEngine
3584           in: query
3585           schema:
3586             type: string
3587         - $ref: '#/components/parameters/start'
3588         - $ref: '#/components/parameters/count'
3589         - $ref: '#/components/parameters/sort'
3590       responses:
3591         '200':
3592           description: successful operation
3593           content:
3594             application/json:
3595               schema:
3596                 $ref: '#/components/schemas/PluginResponse'
3597         '503':
3598           description: plugin index unavailable
3599   /plugins/install:
3600     post:
3601       tags:
3602         - Plugins
3603       summary: Install a plugin
3604       security:
3605         - OAuth2:
3606           - admin
3607       requestBody:
3608         content:
3609           application/json:
3610             schema:
3611               oneOf:
3612                 - type: object
3613                   properties:
3614                     npmName:
3615                       type: string
3616                       example: peertube-plugin-auth-ldap
3617                   required:
3618                     - npmName
3619                   additionalProperties: false
3620                 - type: object
3621                   properties:
3622                     path:
3623                       type: string
3624                   required:
3625                     - path
3626                   additionalProperties: false
3627       responses:
3628         '204':
3629           description: successful operation
3630         '400':
3631           description: should have either `npmName` or `path` set
3632   /plugins/update:
3633     post:
3634       tags:
3635         - Plugins
3636       summary: Update a plugin
3637       security:
3638         - OAuth2:
3639           - admin
3640       requestBody:
3641         content:
3642           application/json:
3643             schema:
3644               oneOf:
3645                 - type: object
3646                   properties:
3647                     npmName:
3648                       type: string
3649                       example: peertube-plugin-auth-ldap
3650                   required:
3651                     - npmName
3652                   additionalProperties: false
3653                 - type: object
3654                   properties:
3655                     path:
3656                       type: string
3657                   required:
3658                     - path
3659                   additionalProperties: false
3660       responses:
3661         '204':
3662           description: successful operation
3663         '400':
3664           description: should have either `npmName` or `path` set
3665         '404':
3666           description: existing plugin not found
3667   /plugins/uninstall:
3668     post:
3669       tags:
3670         - Plugins
3671       summary: Uninstall a plugin
3672       security:
3673         - OAuth2:
3674           - admin
3675       requestBody:
3676         content:
3677           application/json:
3678             schema:
3679               type: object
3680               properties:
3681                 npmName:
3682                   type: string
3683                   description: name of the plugin/theme in its package.json
3684                   example: peertube-plugin-auth-ldap
3685               required:
3686                 - npmName
3687       responses:
3688         '204':
3689           description: successful operation
3690         '404':
3691           description: existing plugin not found
3692   /plugins/{npmName}:
3693     get:
3694       tags:
3695         - Plugins
3696       summary: Get a plugin
3697       security:
3698         - OAuth2:
3699           - admin
3700       parameters:
3701         - $ref: '#/components/parameters/npmName'
3702       responses:
3703         '200':
3704           description: successful operation
3705           content:
3706             application/json:
3707               schema:
3708                 $ref: '#/components/schemas/Plugin'
3709         '404':
3710           description: plugin not found
3711   /plugins/{npmName}/settings:
3712     put:
3713       tags:
3714         - Plugins
3715       summary: Set a plugin's settings
3716       security:
3717         - OAuth2:
3718           - admin
3719       parameters:
3720         - $ref: '#/components/parameters/npmName'
3721       requestBody:
3722         content:
3723           application/json:
3724             schema:
3725               type: object
3726               properties:
3727                 settings:
3728                   type: object
3729                   additionalProperties: true
3730       responses:
3731         '204':
3732           description: successful operation
3733         '404':
3734           description: plugin not found
3735   /plugins/{npmName}/public-settings:
3736     get:
3737       tags:
3738         - Plugins
3739       summary: Get a plugin's public settings
3740       parameters:
3741         - $ref: '#/components/parameters/npmName'
3742       responses:
3743         '200':
3744           description: successful operation
3745           content:
3746             application/json:
3747               schema:
3748                 type: object
3749                 additionalProperties: true
3750         '404':
3751           description: plugin not found
3752   /plugins/{npmName}/registered-settings:
3753     get:
3754       tags:
3755         - Plugins
3756       summary: Get a plugin's registered settings
3757       security:
3758         - OAuth2:
3759           - admin
3760       parameters:
3761         - $ref: '#/components/parameters/npmName'
3762       responses:
3763         '200':
3764           description: successful operation
3765           content:
3766             application/json:
3767               schema:
3768                 type: object
3769                 additionalProperties: true
3770         '404':
3771           description: plugin not found
3772 servers:
3773   - url: 'https://peertube2.cpy.re/api/v1'
3774     description: Live Test Server (live data - latest nightly version)
3775   - url: 'https://peertube3.cpy.re/api/v1'
3776     description: Live Test Server (live data - latest RC version)
3777   - url: 'https://peertube.cpy.re/api/v1'
3778     description: Live Test Server (live data - stable version)
3779 components:
3780   parameters:
3781     start:
3782       name: start
3783       in: query
3784       required: false
3785       description: Offset used to paginate results
3786       schema:
3787         type: integer
3788         minimum: 0
3789     count:
3790       name: count
3791       in: query
3792       required: false
3793       description: "Number of items to return"
3794       schema:
3795         type: integer
3796         default: 15
3797         maximum: 100
3798         minimum: 1
3799     sort:
3800       name: sort
3801       in: query
3802       required: false
3803       description: Sort column
3804       schema:
3805         type: string
3806         example: -createdAt
3807     search:
3808       name: search
3809       in: query
3810       required: false
3811       description: Plain text search, applied to various parts of the model depending on endpoint
3812       schema:
3813         type: string
3814     searchTarget:
3815       name: searchTarget
3816       in: query
3817       required: false
3818       description: >
3819         If the administrator enabled search index support, you can override the default search target.
3820
3821
3822         **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
3823         It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
3824           * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
3825           then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
3826           After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
3827           * 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
3828           the data from the origin instance API
3829       schema:
3830         type: string
3831         enum:
3832           - 'local'
3833           - 'search-index'
3834     videosSort:
3835       name: sort
3836       in: query
3837       required: false
3838       description: Sort videos by criteria
3839       schema:
3840         type: string
3841         enum:
3842         - name
3843         - -duration
3844         - -createdAt
3845         - -publishedAt
3846         - -views
3847         - -likes
3848         - -trending
3849         - -hot
3850     videosSearchSort:
3851       name: sort
3852       in: query
3853       required: false
3854       description: Sort videos by criteria
3855       schema:
3856         type: string
3857         enum:
3858         - name
3859         - -duration
3860         - -createdAt
3861         - -publishedAt
3862         - -views
3863         - -likes
3864         - -match
3865     commentsSort:
3866       name: sort
3867       in: query
3868       required: false
3869       description: Sort comments by criteria
3870       schema:
3871         type: string
3872         enum:
3873         - -createdAt
3874         - -totalReplies
3875     blacklistsSort:
3876       name: sort
3877       in: query
3878       required: false
3879       description: Sort blacklists by criteria
3880       schema:
3881         type: string
3882         enum:
3883         - -id
3884         - name
3885         - -duration
3886         - -views
3887         - -likes
3888         - -dislikes
3889         - -uuid
3890         - -createdAt
3891     usersSearch:
3892       name: search
3893       in: query
3894       required: false
3895       description: Plain text search that will match with user usernames or emails
3896       schema:
3897         type: string
3898     usersBlocked:
3899       name: blocked
3900       in: query
3901       required: false
3902       description: Filter results down to (un)banned users
3903       schema:
3904         type: boolean
3905     usersSort:
3906       name: sort
3907       in: query
3908       required: false
3909       description: Sort users by criteria
3910       schema:
3911         type: string
3912         enum:
3913         - -id
3914         - -username
3915         - -createdAt
3916     abusesSort:
3917       name: sort
3918       in: query
3919       required: false
3920       description: Sort abuses by criteria
3921       schema:
3922         type: string
3923         enum:
3924         - -id
3925         - -createdAt
3926         - -state
3927     videoRedundanciesSort:
3928       name: sort
3929       in: query
3930       required: false
3931       description: Sort abuses by criteria
3932       schema:
3933         type: string
3934         enum:
3935         - name
3936     name:
3937       name: name
3938       in: path
3939       required: true
3940       description: The username or handle of the account
3941       schema:
3942         type: string
3943         example: chocobozzz | chocobozzz@example.org
3944     id:
3945       name: id
3946       in: path
3947       required: true
3948       description: The user id
3949       schema:
3950         $ref: '#/components/schemas/id'
3951     idOrUUID:
3952       name: id
3953       in: path
3954       required: true
3955       description: The object id or uuid
3956       schema:
3957         oneOf:
3958           - $ref: '#/components/schemas/id'
3959           - $ref: '#/components/schemas/UUIDv4'
3960     playlistElementId:
3961       name: playlistElementId
3962       in: path
3963       required: true
3964       description: Playlist element id
3965       schema:
3966         $ref: '#/components/schemas/id'
3967     abuseId:
3968       name: abuseId
3969       in: path
3970       required: true
3971       description: Abuse id
3972       schema:
3973         $ref: '#/components/schemas/Abuse/properties/id'
3974     abuseMessageId:
3975       name: abuseMessageId
3976       in: path
3977       required: true
3978       description: Abuse message id
3979       schema:
3980         $ref: '#/components/schemas/AbuseMessage/properties/id'
3981     captionLanguage:
3982       name: captionLanguage
3983       in: path
3984       required: true
3985       description: The caption language
3986       schema:
3987         $ref: '#/components/schemas/VideoLanguageSet'
3988     channelHandle:
3989       name: channelHandle
3990       in: path
3991       required: true
3992       description: The video channel handle
3993       schema:
3994         type: string
3995         example: my_username | my_username@example.com
3996     subscriptionHandle:
3997       name: subscriptionHandle
3998       in: path
3999       required: true
4000       description: The subscription handle
4001       schema:
4002         type: string
4003         example: my_username | my_username@example.com
4004     threadId:
4005       name: threadId
4006       in: path
4007       required: true
4008       description: The thread id (root comment id)
4009       schema:
4010         $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
4011     commentId:
4012       name: commentId
4013       in: path
4014       required: true
4015       description: The comment id
4016       schema:
4017         $ref: '#/components/schemas/VideoComment/properties/id'
4018     isLive:
4019       name: isLive
4020       in: query
4021       required: false
4022       description: whether or not the video is a live
4023       schema:
4024         type: boolean
4025     categoryOneOf:
4026       name: categoryOneOf
4027       in: query
4028       required: false
4029       description: category id of the video (see [/videos/categories](#operation/getCategories))
4030       schema:
4031         oneOf:
4032         - $ref: '#/components/schemas/VideoCategorySet'
4033         - type: array
4034           items:
4035             $ref: '#/components/schemas/VideoCategorySet'
4036       style: form
4037       explode: false
4038     tagsOneOf:
4039       name: tagsOneOf
4040       in: query
4041       required: false
4042       description: tag(s) of the video
4043       schema:
4044         oneOf:
4045         - type: string
4046         - type: array
4047           maxItems: 5
4048           items:
4049             type: string
4050       style: form
4051       explode: false
4052     tagsAllOf:
4053       name: tagsAllOf
4054       in: query
4055       required: false
4056       description: tag(s) of the video, where all should be present in the video
4057       schema:
4058         oneOf:
4059         - type: string
4060         - type: array
4061           items:
4062             type: string
4063       style: form
4064       explode: false
4065     languageOneOf:
4066       name: languageOneOf
4067       in: query
4068       required: false
4069       description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4070       schema:
4071         oneOf:
4072         - $ref: '#/components/schemas/VideoLanguageSet'
4073         - type: array
4074           items:
4075             $ref: '#/components/schemas/VideoLanguageSet'
4076       style: form
4077       explode: false
4078     licenceOneOf:
4079       name: licenceOneOf
4080       in: query
4081       required: false
4082       description: licence id of the video (see [/videos/licences](#operation/getLicences))
4083       schema:
4084         oneOf:
4085         - $ref: '#/components/schemas/VideoLicenceSet'
4086         - type: array
4087           items:
4088             $ref: '#/components/schemas/VideoLicenceSet'
4089       style: form
4090       explode: false
4091     skipCount:
4092       name: skipCount
4093       in: query
4094       required: false
4095       description: if you don't need the `total` in the response
4096       schema:
4097         type: string
4098         enum:
4099           - 'true'
4100           - 'false'
4101         default: 'false'
4102     nsfw:
4103       name: nsfw
4104       in: query
4105       required: false
4106       description: whether to include nsfw videos, if any
4107       schema:
4108         type: string
4109         enum:
4110         - 'true'
4111         - 'false'
4112     filter:
4113       name: filter
4114       in: query
4115       required: false
4116       description: >
4117         Special filters which might require special rights:
4118          * `local` - only videos local to the instance
4119          * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4120          * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4121       schema:
4122         type: string
4123         enum:
4124         - local
4125         - all-local
4126     subscriptionsUris:
4127       name: uris
4128       in: query
4129       required: true
4130       description: list of uris to check if each is part of the user subscriptions
4131       schema:
4132         type: array
4133         items:
4134           type: string
4135           format: uri
4136     npmName:
4137       name: npmName
4138       in: path
4139       required: true
4140       description: name of the plugin/theme on npmjs.com or in its package.json
4141       schema:
4142         type: string
4143         example: peertube-plugin-auth-ldap
4144     jobType:
4145       name: jobType
4146       in: query
4147       required: false
4148       description: job type
4149       schema:
4150         type: string
4151         enum:
4152           - activitypub-follow
4153           - activitypub-http-broadcast
4154           - activitypub-http-fetcher
4155           - activitypub-http-unicast
4156           - email
4157           - video-transcoding
4158           - video-file-import
4159           - video-import
4160           - videos-views
4161           - activitypub-refresher
4162           - video-redundancy
4163           - video-live-ending
4164   securitySchemes:
4165     OAuth2:
4166       description: |
4167         Authenticating via OAuth requires the following steps:
4168         - Have an activated account
4169         - [Generate](https://docs.joinpeertube.org/api-rest-getting-started) a
4170         Bearer Token for that account at `/api/v1/users/token`
4171         - Make authenticated requests, putting *Authorization: Bearer <token\>*
4172         - Profit, depending on the role assigned to the account
4173
4174         Note that the __access token is valid for 1 day__ and, and is given
4175         along with a __refresh token valid for 2 weeks__.
4176       type: oauth2
4177       flows:
4178         password:
4179           tokenUrl: 'https://peertube.example.com/api/v1/users/token'
4180           scopes:
4181             admin: Admin scope
4182             moderator: Moderator scope
4183             user: User scope
4184   schemas:
4185     # Resuable core properties
4186     id:
4187       type: integer
4188       minimum: 1
4189       example: 42
4190     UUIDv4:
4191       type: string
4192       format: uuid
4193       example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4194       pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4195       minLength: 36
4196       maxLength: 36
4197     username:
4198       type: string
4199       description: The username of the user
4200       example: chocobozzz
4201       pattern: '/^[a-z0-9._]{1,50}$/'
4202       minLength: 1
4203       maxLength: 50
4204     usernameChannel:
4205       type: string
4206       description: The username for the default channel
4207       example: The Capybara Channel
4208       pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
4209     password:
4210       type: string
4211       format: password
4212       description: The password of the user
4213       minLength: 6
4214       maxLength: 255
4215
4216     VideoCategorySet:
4217       type: integer
4218       description: category id of the video (see [/videos/categories](#operation/getCategories))
4219       example: 15
4220     VideoConstantNumber-Category:
4221       properties:
4222         id:
4223           $ref: '#/components/schemas/VideoCategorySet'
4224         label:
4225           type: string
4226           example: Science & Technology
4227
4228     VideoLicenceSet:
4229       type: integer
4230       description: licence id of the video (see [/videos/licences](#operation/getLicences))
4231       example: 2
4232     VideoConstantNumber-Licence:
4233       properties:
4234         id:
4235           $ref: '#/components/schemas/VideoLicenceSet'
4236         label:
4237           type: string
4238           example: Attribution - Share Alike
4239
4240     VideoLanguageSet:
4241       type: string
4242       description: language id of the video (see [/videos/languages](#operation/getLanguages))
4243       example: en
4244     VideoConstantString-Language:
4245       properties:
4246         id:
4247           $ref: '#/components/schemas/VideoLanguageSet'
4248         label:
4249           type: string
4250           example: English
4251
4252     VideoPlaylistPrivacySet:
4253       type: integer
4254       enum:
4255         - 1
4256         - 2
4257         - 3
4258       description: Video playlist privacy policy (see [/video-playlists/privacies])
4259     VideoPlaylistPrivacyConstant:
4260       properties:
4261         id:
4262           $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4263         label:
4264           type: string
4265
4266     VideoPlaylistTypeSet:
4267       type: integer
4268       enum:
4269         - 1
4270         - 2
4271       description: The video playlist type (Regular = `1`, Watch Later = `2`)
4272     VideoPlaylistTypeConstant:
4273       properties:
4274         id:
4275           $ref: '#/components/schemas/VideoPlaylistTypeSet'
4276         label:
4277           type: string
4278
4279     VideoPrivacySet:
4280       type: integer
4281       enum:
4282         - 1
4283         - 2
4284         - 3
4285         - 4
4286       description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4287     VideoPrivacyConstant:
4288       properties:
4289         id:
4290           $ref: '#/components/schemas/VideoPrivacySet'
4291         label:
4292           type: string
4293
4294     NSFWPolicy:
4295       type: string
4296       enum:
4297         - display
4298         - blur
4299         - do_not_list
4300
4301     UserRole:
4302       type: integer
4303       enum:
4304         - 0
4305         - 1
4306         - 2
4307       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4308       example: 2
4309     UserAdminFlags:
4310       type: integer
4311       enum:
4312         - 0
4313         - 1
4314       description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4315       example: 1
4316
4317     VideoStateConstant:
4318       properties:
4319         id:
4320           type: integer
4321           enum:
4322             - 1
4323             - 2
4324             - 3
4325           description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4326         label:
4327           type: string
4328
4329     AbuseStateSet:
4330       type: integer
4331       enum:
4332         - 1
4333         - 2
4334         - 3
4335       description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4336     AbuseStateConstant:
4337       properties:
4338         id:
4339           $ref: '#/components/schemas/AbuseStateSet'
4340         label:
4341           type: string
4342     AbusePredefinedReasons:
4343       type: array
4344       items:
4345         type: string
4346         enum:
4347         - violentOrAbusive
4348         - hatefulOrAbusive
4349         - spamOrMisleading
4350         - privacy
4351         - rights
4352         - serverRules
4353         - thumbnails
4354         - captions
4355       example: [spamOrMisleading]
4356
4357     VideoResolutionSet:
4358       type: integer
4359       description: |
4360         Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4361
4362         `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4363       example: 240
4364     VideoResolutionConstant:
4365       description: resolutions and their labels for the video
4366       properties:
4367         id:
4368           $ref: '#/components/schemas/VideoResolutionSet'
4369         label:
4370           type: string
4371           example: 240p
4372     VideoScheduledUpdate:
4373       properties:
4374         privacy:
4375           $ref: '#/components/schemas/VideoPrivacySet'
4376         updateAt:
4377           type: string
4378           format: date
4379           description: When to update the video
4380       required:
4381         - updateAt
4382     AccountSummary:
4383       properties:
4384         id:
4385           type: integer
4386         name:
4387           type: string
4388         displayName:
4389           type: string
4390         url:
4391           type: string
4392           format: url
4393         host:
4394           type: string
4395           format: hostname
4396         avatar:
4397           nullable: true
4398           allOf:
4399             - $ref: '#/components/schemas/ActorImage'
4400     VideoChannelSummary:
4401       properties:
4402         id:
4403           $ref: '#/components/schemas/id'
4404         name:
4405           type: string
4406         displayName:
4407           type: string
4408         url:
4409           type: string
4410           format: url
4411         host:
4412           type: string
4413           format: hostname
4414         avatar:
4415           nullable: true
4416           allOf:
4417             - $ref: '#/components/schemas/ActorImage'
4418     PlaylistElement:
4419       properties:
4420         position:
4421           type: integer
4422         startTimestamp:
4423           type: integer
4424         stopTimestamp:
4425           type: integer
4426         video:
4427           nullable: true
4428           allOf:
4429             - $ref: '#/components/schemas/Video'
4430     VideoFile:
4431       readOnly: true
4432       properties:
4433         magnetUri:
4434           type: string
4435           format: uri
4436           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4437           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
4438           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4439         resolution:
4440           $ref: '#/components/schemas/VideoResolutionConstant'
4441         size:
4442           type: integer
4443           description: Video file size in bytes
4444         torrentUrl:
4445           type: string
4446           description: Direct URL of the torrent file
4447           format: url
4448         torrentDownloadUrl:
4449           type: string
4450           description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4451           format: url
4452         fileUrl:
4453           type: string
4454           description: Direct URL of the video
4455           format: url
4456         fileDownloadUrl:
4457           type: string
4458           description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4459           format: url
4460         fps:
4461           type: number
4462           description: Frames per second of the video file
4463         metadataUrl:
4464           type: string
4465           format: url
4466           description: URL dereferencing the output of ffprobe on the file
4467     VideoStreamingPlaylists:
4468       allOf:
4469         - type: object
4470           properties:
4471             id:
4472               $ref: '#/components/schemas/id'
4473             type:
4474               type: integer
4475               enum:
4476                 - 1
4477               description: |
4478                 Playlist type:
4479                 - `1`: HLS
4480         - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4481     VideoStreamingPlaylists-HLS:
4482       properties:
4483         playlistUrl:
4484           type: string
4485           format: url
4486         segmentsSha256Url:
4487           type: string
4488           format: url
4489         files:
4490           type: array
4491           description: |
4492             Video files associated to this playlist.
4493
4494             The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4495           items:
4496             $ref: '#/components/schemas/VideoFile'
4497         redundancies:
4498           type: array
4499           items:
4500             type: object
4501             properties:
4502               baseUrl:
4503                 type: string
4504                 format: url
4505     VideoInfo:
4506       properties:
4507         id:
4508           $ref: '#/components/schemas/Video/properties/id'
4509         uuid:
4510           $ref: '#/components/schemas/Video/properties/uuid'
4511         name:
4512           $ref: '#/components/schemas/Video/properties/name'
4513     Video:
4514       properties:
4515         id:
4516           description: object id for the video
4517           allOf:
4518             - $ref: '#/components/schemas/id'
4519         uuid:
4520           description: universal identifier for the video, that can be used across instances
4521           allOf:
4522             - $ref: '#/components/schemas/UUIDv4'
4523         isLive:
4524           type: boolean
4525         createdAt:
4526           type: string
4527           format: date-time
4528           example: 2017-10-01T10:52:46.396Z
4529           description: time at which the video object was first drafted
4530         publishedAt:
4531           type: string
4532           format: date-time
4533           example: 2018-10-01T10:52:46.396Z
4534           description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4535         updatedAt:
4536           type: string
4537           format: date-time
4538           example: 2021-05-04T08:01:01.502Z
4539           description: last time the video's metadata was modified
4540         originallyPublishedAt:
4541           type: string
4542           format: date-time
4543           example: 2010-10-01T10:52:46.396Z
4544           description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4545         category:
4546           allOf:
4547             - $ref: '#/components/schemas/VideoConstantNumber-Category'
4548           description: category in which the video is classified
4549         licence:
4550           allOf:
4551             - $ref: '#/components/schemas/VideoConstantNumber-Licence'
4552           description: licence under which the video is distributed
4553         language:
4554           allOf:
4555             - $ref: '#/components/schemas/VideoConstantString-Language'
4556           description: main language used in the video
4557         privacy:
4558           allOf:
4559             - $ref: '#/components/schemas/VideoPrivacyConstant'
4560           description: privacy policy used to distribute the video
4561         description:
4562           type: string
4563           example: |
4564             **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
4565             **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
4566           minLength: 3
4567           maxLength: 250
4568           description: |
4569             truncated description of the video, written in Markdown.
4570             Resolve `descriptionPath` to get the full description of maximum `10000` characters.
4571         duration:
4572           type: integer
4573           example: 1419
4574           description: duration of the video in seconds
4575         isLocal:
4576           type: boolean
4577         name:
4578           type: string
4579           description: title of the video
4580           example: What is PeerTube?
4581           minLength: 3
4582           maxLength: 120
4583         thumbnailPath:
4584           type: string
4585           example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4586         previewPath:
4587           type: string
4588           example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4589         embedPath:
4590           type: string
4591           example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4592         views:
4593           type: integer
4594           example: 1337
4595         likes:
4596           type: integer
4597           example: 42
4598         dislikes:
4599           type: integer
4600           example: 7
4601         nsfw:
4602           type: boolean
4603         waitTranscoding:
4604           type: boolean
4605           nullable: true
4606         state:
4607           allOf:
4608             - $ref: '#/components/schemas/VideoStateConstant'
4609           description: represents the internal state of the video processing within the PeerTube instance
4610         scheduledUpdate:
4611           nullable: true
4612           allOf:
4613             - $ref: '#/components/schemas/VideoScheduledUpdate'
4614         blacklisted:
4615           nullable: true
4616           type: boolean
4617         blacklistedReason:
4618           nullable: true
4619           type: string
4620         account:
4621           $ref: '#/components/schemas/AccountSummary'
4622         channel:
4623           $ref: '#/components/schemas/VideoChannelSummary'
4624         userHistory:
4625           nullable: true
4626           type: object
4627           properties:
4628             currentTime:
4629               type: integer
4630     VideoDetails:
4631       allOf:
4632         - $ref: '#/components/schemas/Video'
4633         - type: object
4634           properties:
4635             descriptionPath:
4636               type: string
4637               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
4638               description: path at which to get the full description of maximum `10000` characters
4639             support:
4640               type: string
4641               description: A text tell the audience how to support the video creator
4642               example: Please support my work on <insert crowdfunding plateform>! <3
4643               minLength: 3
4644               maxLength: 1000
4645             channel:
4646               $ref: '#/components/schemas/VideoChannel'
4647             account:
4648               $ref: '#/components/schemas/Account'
4649             tags:
4650               example: [flowers, gardening]
4651               type: array
4652               minItems: 1
4653               maxItems: 5
4654               items:
4655                 type: string
4656                 minLength: 2
4657                 maxLength: 30
4658             commentsEnabled:
4659               type: boolean
4660             downloadEnabled:
4661               type: boolean
4662             trackerUrls:
4663               type: array
4664               items:
4665                 type: string
4666                 format: url
4667               example:
4668                 - https://peertube2.cpy.re/tracker/announce
4669                 - wss://peertube2.cpy.re/tracker/socket
4670             files:
4671               type: array
4672               items:
4673                 $ref: '#/components/schemas/VideoFile'
4674               description: |
4675                 WebTorrent/raw video files. If WebTorrent is disabled on the server:
4676
4677                 - field will be empty
4678                 - video files will be found in `streamingPlaylists[].files` field
4679             streamingPlaylists:
4680               type: array
4681               items:
4682                 $ref: '#/components/schemas/VideoStreamingPlaylists'
4683               description: |
4684                 HLS playlists/manifest files. If HLS is disabled on the server:
4685
4686                 - field will be empty
4687                 - video files will be found in `files` field
4688     FileRedundancyInformation:
4689       properties:
4690         id:
4691           $ref: '#/components/schemas/id'
4692         fileUrl:
4693           type: string
4694           format: url
4695         strategy:
4696           type: string
4697           enum:
4698             - manual
4699             - most-views
4700             - trending
4701             - recently-added
4702         size:
4703           type: integer
4704         createdAt:
4705           type: string
4706           format: date-time
4707         updatedAt:
4708           type: string
4709           format: date-time
4710         expiresOn:
4711           type: string
4712           format: date-time
4713     VideoRedundancy:
4714       properties:
4715         id:
4716           $ref: '#/components/schemas/id'
4717         name:
4718           type: string
4719         url:
4720           type: string
4721           format: url
4722         uuid:
4723           $ref: '#/components/schemas/UUIDv4'
4724         redundancies:
4725           type: object
4726           properties:
4727             files:
4728               type: array
4729               items:
4730                 $ref: '#/components/schemas/FileRedundancyInformation'
4731             streamingPlaylists:
4732               type: array
4733               items:
4734                 $ref: '#/components/schemas/FileRedundancyInformation'
4735     VideoImportStateConstant:
4736       properties:
4737         id:
4738           type: integer
4739           enum:
4740             - 1
4741             - 2
4742             - 3
4743           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4744         label:
4745           type: string
4746           example: Pending
4747     VideoCreateImport:
4748       allOf:
4749         - type: object
4750           additionalProperties: false
4751           oneOf:
4752             - properties:
4753                 targetUrl:
4754                   $ref: '#/components/schemas/VideoImport/properties/targetUrl'
4755               required: [targetUrl]
4756             - properties:
4757                 magnetUri:
4758                   $ref: '#/components/schemas/VideoImport/properties/magnetUri'
4759               required: [magnetUri]
4760             - properties:
4761                 torrentfile:
4762                   $ref: '#/components/schemas/VideoImport/properties/torrentfile'
4763               required: [torrentfile]
4764         - $ref: '#/components/schemas/VideoUploadRequestCommon'
4765       required:
4766         - channelId
4767         - name
4768     VideoImport:
4769       properties:
4770         id:
4771           readOnly: true
4772           allOf:
4773             - $ref: '#/components/schemas/id'
4774         targetUrl:
4775           type: string
4776           format: url
4777           description: remote URL where to find the import's source video
4778           example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4779         magnetUri:
4780           type: string
4781           format: uri
4782           description: magnet URI allowing to resolve the import's source video
4783           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
4784           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4785         torrentfile:
4786           writeOnly: true
4787           type: string
4788           format: binary
4789           description: Torrent file containing only the video file
4790         torrentName:
4791           readOnly: true
4792           type: string
4793         state:
4794           readOnly: true
4795           allOf:
4796             - $ref: '#/components/schemas/VideoImportStateConstant'
4797         error:
4798           readOnly: true
4799           type: string
4800         createdAt:
4801           readOnly: true
4802           type: string
4803           format: date-time
4804         updatedAt:
4805           readOnly: true
4806           type: string
4807           format: date-time
4808         video:
4809           readOnly: true
4810           nullable: true
4811           allOf:
4812             - $ref: '#/components/schemas/Video'
4813     VideoImportsList:
4814       properties:
4815         total:
4816           type: integer
4817           example: 1
4818         data:
4819           type: array
4820           maxItems: 100
4821           items:
4822             $ref: '#/components/schemas/VideoImport'
4823     Abuse:
4824       properties:
4825         id:
4826           $ref: '#/components/schemas/id'
4827         reason:
4828           type: string
4829           example: The video is a spam
4830           minLength: 2
4831           maxLength: 3000
4832         predefinedReasons:
4833           $ref: '#/components/schemas/AbusePredefinedReasons'
4834         reporterAccount:
4835           $ref: '#/components/schemas/Account'
4836         state:
4837           $ref: '#/components/schemas/AbuseStateConstant'
4838         moderationComment:
4839           type: string
4840           example: Decided to ban the server since it spams us regularly
4841           minLength: 2
4842           maxLength: 3000
4843         video:
4844           $ref: '#/components/schemas/VideoInfo'
4845         createdAt:
4846           type: string
4847           format: date-time
4848     AbuseMessage:
4849       properties:
4850         id:
4851           $ref: '#/components/schemas/id'
4852         message:
4853           type: string
4854           minLength: 2
4855           maxLength: 3000
4856         byModerator:
4857           type: boolean
4858         createdAt:
4859           type: string
4860           format: date-time
4861         account:
4862           $ref: '#/components/schemas/AccountSummary'
4863     VideoBlacklist:
4864       properties:
4865         id:
4866           $ref: '#/components/schemas/id'
4867         videoId:
4868           $ref: '#/components/schemas/Video/properties/id'
4869         createdAt:
4870           type: string
4871           format: date-time
4872         updatedAt:
4873           type: string
4874           format: date-time
4875         name:
4876           type: string
4877           minLength: 3
4878           maxLength: 120
4879         uuid:
4880           $ref: '#/components/schemas/UUIDv4'
4881         description:
4882           type: string
4883           minLength: 3
4884           maxLength: 10000
4885         duration:
4886           type: integer
4887         views:
4888           type: integer
4889         likes:
4890           type: integer
4891         dislikes:
4892           type: integer
4893         nsfw:
4894           type: boolean
4895     VideoPlaylist:
4896       properties:
4897         id:
4898           $ref: '#/components/schemas/id'
4899         uuid:
4900           $ref: '#/components/schemas/UUIDv4'
4901         createdAt:
4902           type: string
4903           format: date-time
4904         updatedAt:
4905           type: string
4906           format: date-time
4907         description:
4908           type: string
4909           minLength: 3
4910           maxLength: 1000
4911         displayName:
4912           type: string
4913           minLength: 1
4914           maxLength: 120
4915         isLocal:
4916           type: boolean
4917         videoLength:
4918           type: integer
4919           minimum: 0
4920         thumbnailPath:
4921           type: string
4922         privacy:
4923           $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
4924         type:
4925           $ref: '#/components/schemas/VideoPlaylistTypeConstant'
4926         ownerAccount:
4927           $ref: '#/components/schemas/AccountSummary'
4928         videoChannel:
4929           $ref: '#/components/schemas/VideoChannelSummary'
4930     VideoComment:
4931       properties:
4932         id:
4933           $ref: '#/components/schemas/id'
4934         url:
4935           type: string
4936           format: url
4937         text:
4938           type: string
4939           format: html
4940           description: Text of the comment
4941           minLength: 1
4942           example: This video is wonderful!
4943         threadId:
4944           $ref: '#/components/schemas/id'
4945         inReplyToCommentId:
4946           nullable: true
4947           allOf:
4948             - $ref: '#/components/schemas/id'
4949         videoId:
4950           $ref: '#/components/schemas/Video/properties/id'
4951         createdAt:
4952           type: string
4953           format: date-time
4954         updatedAt:
4955           type: string
4956           format: date-time
4957         deletedAt:
4958           nullable: true
4959           type: string
4960           format: date-time
4961           default: null
4962         isDeleted:
4963           type: boolean
4964           default: false
4965         totalRepliesFromVideoAuthor:
4966           type: integer
4967           minimum: 0
4968         totalReplies:
4969           type: integer
4970           minimum: 0
4971         account:
4972           $ref: '#/components/schemas/Account'
4973     VideoCommentThreadTree:
4974       properties:
4975         comment:
4976           $ref: '#/components/schemas/VideoComment'
4977         children:
4978           type: array
4979           items:
4980             $ref: '#/components/schemas/VideoCommentThreadTree'
4981     VideoCaption:
4982       properties:
4983         language:
4984           $ref: '#/components/schemas/VideoConstantString-Language'
4985         captionPath:
4986           type: string
4987     ActorImage:
4988       properties:
4989         path:
4990           type: string
4991         createdAt:
4992           type: string
4993           format: date-time
4994         updatedAt:
4995           type: string
4996           format: date-time
4997     ActorInfo:
4998       properties:
4999         id:
5000           $ref: '#/components/schemas/id'
5001         name:
5002           type: string
5003         displayName:
5004           type: string
5005         host:
5006           type: string
5007           format: hostname
5008         avatar:
5009           nullable: true
5010           type: object
5011           properties:
5012             path:
5013               type: string
5014     Actor:
5015       properties:
5016         id:
5017           $ref: '#/components/schemas/id'
5018         url:
5019           type: string
5020           format: url
5021         name:
5022           description: immutable name of the actor
5023           allOf:
5024             - $ref: '#/components/schemas/username'
5025         host:
5026           type: string
5027           format: hostname
5028           description: server on which the actor is resident
5029         hostRedundancyAllowed:
5030           type: boolean
5031           description: whether this actor's host allows redundancy of its videos
5032         followingCount:
5033           type: integer
5034           minimum: 0
5035           description: number of actors subscribed to by this actor, as seen by this instance
5036         followersCount:
5037           type: integer
5038           minimum: 0
5039           description: number of followers of this actor, as seen by this instance
5040         createdAt:
5041           type: string
5042           format: date-time
5043         updatedAt:
5044           type: string
5045           format: date-time
5046         avatar:
5047           $ref: '#/components/schemas/ActorImage'
5048     Account:
5049       allOf:
5050         - $ref: '#/components/schemas/Actor'
5051         - properties:
5052             userId:
5053               description: object id for the user tied to this account
5054               allOf:
5055                 - $ref: '#/components/schemas/User/properties/id'
5056             displayName:
5057               type: string
5058               description: name displayed on the account's profile
5059             description:
5060               type: string
5061               description: text or bio displayed on the account's profile
5062     UserWatchingVideo:
5063       properties:
5064         currentTime:
5065           type: integer
5066           description: timestamp within the video, in seconds
5067           example: 5
5068     ServerConfig:
5069       properties:
5070         instance:
5071           type: object
5072           properties:
5073             name:
5074               type: string
5075             shortDescription:
5076               type: string
5077             defaultClientRoute:
5078               type: string
5079             isNSFW:
5080               type: boolean
5081             defaultNSFWPolicy:
5082               type: string
5083             customizations:
5084               type: object
5085               properties:
5086                 javascript:
5087                   type: string
5088                 css:
5089                   type: string
5090         search:
5091           type: object
5092           properties:
5093             remoteUri:
5094               type: object
5095               properties:
5096                 users:
5097                   type: boolean
5098                 anonymous:
5099                   type: boolean
5100         plugin:
5101           type: object
5102           properties:
5103             registered:
5104               type: array
5105               items:
5106                 type: string
5107         theme:
5108           type: object
5109           properties:
5110             registered:
5111               type: array
5112               items:
5113                 type: string
5114         email:
5115           type: object
5116           properties:
5117             enabled:
5118               type: boolean
5119         contactForm:
5120           type: object
5121           properties:
5122             enabled:
5123               type: boolean
5124         serverVersion:
5125           type: string
5126         serverCommit:
5127           type: string
5128         signup:
5129           type: object
5130           properties:
5131             allowed:
5132               type: boolean
5133             allowedForCurrentIP:
5134               type: boolean
5135             requiresEmailVerification:
5136               type: boolean
5137         transcoding:
5138           type: object
5139           properties:
5140             hls:
5141               type: object
5142               properties:
5143                 enabled:
5144                   type: boolean
5145             webtorrent:
5146               type: object
5147               properties:
5148                 enabled:
5149                   type: boolean
5150             enabledResolutions:
5151               type: array
5152               items:
5153                 $ref: '#/components/schemas/VideoResolutionSet'
5154         import:
5155           type: object
5156           properties:
5157             videos:
5158               type: object
5159               properties:
5160                 http:
5161                   type: object
5162                   properties:
5163                     enabled:
5164                       type: boolean
5165                 torrent:
5166                   type: object
5167                   properties:
5168                     enabled:
5169                       type: boolean
5170         autoBlacklist:
5171           type: object
5172           properties:
5173             videos:
5174               type: object
5175               properties:
5176                 ofUsers:
5177                   type: object
5178                   properties:
5179                     enabled:
5180                       type: boolean
5181         avatar:
5182           type: object
5183           properties:
5184             file:
5185               type: object
5186               properties:
5187                 size:
5188                   type: object
5189                   properties:
5190                     max:
5191                       type: integer
5192             extensions:
5193               type: array
5194               items:
5195                 type: string
5196         video:
5197           type: object
5198           properties:
5199             image:
5200               type: object
5201               properties:
5202                 extensions:
5203                   type: array
5204                   items:
5205                     type: string
5206                 size:
5207                   type: object
5208                   properties:
5209                     max:
5210                       type: integer
5211             file:
5212               type: object
5213               properties:
5214                 extensions:
5215                   type: array
5216                   items:
5217                     type: string
5218         videoCaption:
5219           type: object
5220           properties:
5221             file:
5222               type: object
5223               properties:
5224                 size:
5225                   type: object
5226                   properties:
5227                     max:
5228                       type: integer
5229                 extensions:
5230                   type: array
5231                   items:
5232                     type: string
5233         user:
5234           type: object
5235           properties:
5236             videoQuota:
5237               type: integer
5238               example: 16810141515
5239             videoQuotaDaily:
5240               type: integer
5241               example: 1681014151
5242         trending:
5243           type: object
5244           properties:
5245             videos:
5246               type: object
5247               properties:
5248                 intervalDays:
5249                   type: integer
5250         tracker:
5251           type: object
5252           properties:
5253             enabled:
5254               type: boolean
5255         followings:
5256           type: object
5257           properties:
5258             instance:
5259               type: object
5260               properties:
5261                 autoFollowIndex:
5262                   type: object
5263                   properties:
5264                     indexUrl:
5265                       type: string
5266                       format: url
5267     ServerConfigAbout:
5268       properties:
5269         instance:
5270           type: object
5271           properties:
5272             name:
5273               type: string
5274             shortDescription:
5275               type: string
5276             description:
5277               type: string
5278             terms:
5279               type: string
5280     ServerConfigCustom:
5281       properties:
5282         instance:
5283           type: object
5284           properties:
5285             name:
5286               type: string
5287             shortDescription:
5288               type: string
5289             description:
5290               type: string
5291             terms:
5292               type: string
5293             defaultClientRoute:
5294               type: string
5295             isNSFW:
5296               type: boolean
5297             defaultNSFWPolicy:
5298               type: string
5299             customizations:
5300               type: object
5301               properties:
5302                 javascript:
5303                   type: string
5304                 css:
5305                   type: string
5306         theme:
5307           type: object
5308           properties:
5309             default:
5310               type: string
5311         services:
5312           type: object
5313           properties:
5314             twitter:
5315               type: object
5316               properties:
5317                 username:
5318                   type: string
5319                 whitelisted:
5320                   type: boolean
5321         cache:
5322           type: object
5323           properties:
5324             previews:
5325               type: object
5326               properties:
5327                 size:
5328                   type: integer
5329             captions:
5330               type: object
5331               properties:
5332                 size:
5333                   type: integer
5334         signup:
5335           type: object
5336           properties:
5337             enabled:
5338               type: boolean
5339             limit:
5340               type: integer
5341             requiresEmailVerification:
5342               type: boolean
5343         admin:
5344           type: object
5345           properties:
5346             email:
5347               type: string
5348               format: email
5349         contactForm:
5350           type: object
5351           properties:
5352             enabled:
5353               type: boolean
5354         user:
5355           type: object
5356           description: Settings that apply to new users, if registration is enabled
5357           properties:
5358             videoQuota:
5359               type: integer
5360               example: 16810141515
5361             videoQuotaDaily:
5362               type: integer
5363               example: 1681014151
5364         transcoding:
5365           type: object
5366           description: Settings pertaining to transcoding jobs
5367           properties:
5368             enabled:
5369               type: boolean
5370             allowAdditionalExtensions:
5371               type: boolean
5372               description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5373             allowAudioFiles:
5374               type: boolean
5375               description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5376             threads:
5377               type: integer
5378               description: Amount of threads used by ffmpeg for 1 transcoding job
5379             concurrency:
5380               type: number
5381               description: Amount of transcoding jobs to execute in parallel
5382             profile:
5383               type: string
5384               enum:
5385                 - default
5386               description: |
5387                 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5388             resolutions:
5389               type: object
5390               description: Resolutions to transcode _new videos_ to
5391               properties:
5392                 0p:
5393                   type: boolean
5394                 240p:
5395                   type: boolean
5396                 360p:
5397                   type: boolean
5398                 480p:
5399                   type: boolean
5400                 720p:
5401                   type: boolean
5402                 1080p:
5403                   type: boolean
5404                 1440p:
5405                   type: boolean
5406                 2160p:
5407                   type: boolean
5408             webtorrent:
5409               type: object
5410               description: WebTorrent-specific settings
5411               properties:
5412                 enabled:
5413                   type: boolean
5414             hls:
5415               type: object
5416               description: HLS-specific settings
5417               properties:
5418                 enabled:
5419                   type: boolean
5420         import:
5421           type: object
5422           properties:
5423             videos:
5424               type: object
5425               properties:
5426                 http:
5427                   type: object
5428                   properties:
5429                     enabled:
5430                       type: boolean
5431                 torrent:
5432                   type: object
5433                   properties:
5434                     enabled:
5435                       type: boolean
5436         autoBlacklist:
5437           type: object
5438           properties:
5439             videos:
5440               type: object
5441               properties:
5442                 ofUsers:
5443                   type: object
5444                   properties:
5445                     enabled:
5446                       type: boolean
5447         followers:
5448           type: object
5449           properties:
5450             instance:
5451               type: object
5452               properties:
5453                 enabled:
5454                   type: boolean
5455                 manualApproval:
5456                   type: boolean
5457     Follow:
5458       properties:
5459         id:
5460           $ref: '#/components/schemas/id'
5461         follower:
5462           $ref: '#/components/schemas/Actor'
5463         following:
5464           $ref: '#/components/schemas/Actor'
5465         score:
5466           type: number
5467           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5468         state:
5469           type: string
5470           enum:
5471             - pending
5472             - accepted
5473         createdAt:
5474           type: string
5475           format: date-time
5476         updatedAt:
5477           type: string
5478           format: date-time
5479
5480     PredefinedAbuseReasons:
5481       description: Reason categories that help triage reports
5482       type: array
5483       maxItems: 8
5484       items:
5485         type: string
5486         enum:
5487         - violentOrAbusive
5488         - hatefulOrAbusive
5489         - spamOrMisleading
5490         - privacy
5491         - rights
5492         - serverRules
5493         - thumbnails
5494         - captions
5495
5496     Job:
5497       properties:
5498         id:
5499           $ref: '#/components/schemas/id'
5500         state:
5501           type: string
5502           enum:
5503             - active
5504             - completed
5505             - failed
5506             - waiting
5507             - delayed
5508         type:
5509           type: string
5510           enum:
5511             - activitypub-http-unicast
5512             - activitypub-http-broadcast
5513             - activitypub-http-fetcher
5514             - activitypub-follow
5515             - video-file-import
5516             - video-transcoding
5517             - email
5518             - video-import
5519             - videos-views
5520             - activitypub-refresher
5521             - video-redundancy
5522         data:
5523           type: object
5524           additionalProperties: true
5525         error:
5526           type: object
5527           additionalProperties: true
5528         createdAt:
5529           type: string
5530           format: date-time
5531         finishedOn:
5532           type: string
5533           format: date-time
5534         processedOn:
5535           type: string
5536           format: date-time
5537     AddUserResponse:
5538       properties:
5539         user:
5540           type: object
5541           properties:
5542             id:
5543               $ref: '#/components/schemas/id'
5544             account:
5545               type: object
5546               properties:
5547                 id:
5548                   $ref: '#/components/schemas/id'
5549     VideoUploadRequestCommon:
5550       properties:
5551         name:
5552           description: Video name
5553           type: string
5554           example: What is PeerTube?
5555           minLength: 3
5556           maxLength: 120
5557         channelId:
5558           description: Channel id that will contain this video
5559           type: integer
5560           example: 3
5561           minimum: 1
5562         privacy:
5563           $ref: '#/components/schemas/VideoPrivacySet'
5564         category:
5565           $ref: '#/components/schemas/VideoCategorySet'
5566         licence:
5567           $ref: '#/components/schemas/VideoLicenceSet'
5568         language:
5569           $ref: '#/components/schemas/VideoLanguageSet'
5570         description:
5571           description: Video description
5572           type: string
5573           example: |
5574             **[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)**
5575         waitTranscoding:
5576           description: Whether or not we wait transcoding before publish the video
5577           type: boolean
5578         support:
5579           description: A text tell the audience how to support the video creator
5580           example: Please support my work on <insert crowdfunding plateform>! <3
5581           type: string
5582         nsfw:
5583           description: Whether or not this video contains sensitive content
5584           type: boolean
5585         tags:
5586           description: Video tags (maximum 5 tags each between 2 and 30 characters)
5587           type: array
5588           minItems: 1
5589           maxItems: 5
5590           uniqueItems: true
5591           example:
5592             - framasoft
5593             - peertube
5594           items:
5595             type: string
5596             minLength: 2
5597             maxLength: 30
5598         commentsEnabled:
5599           description: Enable or disable comments for this video
5600           type: boolean
5601         downloadEnabled:
5602           description: Enable or disable downloading for this video
5603           type: boolean
5604         originallyPublishedAt:
5605           description: Date when the content was originally published
5606           type: string
5607           format: date-time
5608         scheduleUpdate:
5609           $ref: '#/components/schemas/VideoScheduledUpdate'
5610         thumbnailfile:
5611           description: Video thumbnail file
5612           type: string
5613           format: binary
5614         previewfile:
5615           description: Video preview file
5616           type: string
5617           format: binary
5618       required:
5619         - channelId
5620         - name
5621     VideoUploadRequestLegacy:
5622       allOf:
5623         - $ref: '#/components/schemas/VideoUploadRequestCommon'
5624         - type: object
5625           required:
5626             - videofile
5627           properties:
5628             videofile:
5629               description: Video file
5630               type: string
5631               format: binary
5632     VideoUploadRequestResumable:
5633       allOf:
5634         - $ref: '#/components/schemas/VideoUploadRequestCommon'
5635         - type: object
5636           required:
5637             - filename
5638           properties:
5639             filename:
5640               description: Video filename including extension
5641               type: string
5642               format: filename
5643               example: what_is_peertube.mp4
5644             thumbnailfile:
5645               description: Video thumbnail file
5646               type: string
5647               format: binary
5648             previewfile:
5649               description: Video preview file
5650               type: string
5651               format: binary
5652     VideoUploadResponse:
5653       properties:
5654         video:
5655           type: object
5656           properties:
5657             id:
5658               $ref: '#/components/schemas/Video/properties/id'
5659             uuid:
5660               $ref: '#/components/schemas/Video/properties/uuid'
5661     CommentThreadResponse:
5662       properties:
5663         total:
5664           type: integer
5665           example: 1
5666         data:
5667           type: array
5668           maxItems: 100
5669           items:
5670             $ref: '#/components/schemas/VideoComment'
5671     CommentThreadPostResponse:
5672       properties:
5673         comment:
5674           $ref: '#/components/schemas/VideoComment'
5675     VideoListResponse:
5676       properties:
5677         total:
5678           type: integer
5679           example: 1
5680         data:
5681           type: array
5682           maxItems: 100
5683           items:
5684             $ref: '#/components/schemas/Video'
5685     User:
5686       properties:
5687         account:
5688           $ref: '#/components/schemas/Account'
5689         autoPlayNextVideo:
5690           type: boolean
5691           description: Automatically start playing the upcoming video after the currently playing video
5692         autoPlayNextVideoPlaylist:
5693           type: boolean
5694           description: Automatically start playing the video on the playlist after the currently playing video
5695         autoPlayVideo:
5696           type: boolean
5697           description: Automatically start playing the video on the watch page
5698         blocked:
5699           type: boolean
5700         blockedReason:
5701           type: string
5702         createdAt:
5703           type: string
5704         email:
5705           type: string
5706           format: email
5707           description: The user email
5708         emailVerified:
5709           type: boolean
5710           description: Has the user confirmed their email address?
5711         id:
5712           allOf:
5713             - $ref: '#/components/schemas/id'
5714           readOnly: true
5715         pluginAuth:
5716           type: string
5717           description: Auth plugin to use to authenticate the user
5718         lastLoginDate:
5719           type: string
5720           format: date-time
5721         noInstanceConfigWarningModal:
5722           type: boolean
5723         noWelcomeModal:
5724           type: boolean
5725         nsfwPolicy:
5726           $ref: '#/components/schemas/NSFWPolicy'
5727         role:
5728           $ref: '#/components/schemas/UserRole'
5729         roleLabel:
5730           type: string
5731           enum:
5732             - User
5733             - Moderator
5734             - Administrator
5735         theme:
5736           type: string
5737           description: Theme enabled by this user
5738         username:
5739           $ref: '#/components/schemas/username'
5740         videoChannels:
5741           type: array
5742           items:
5743             $ref: '#/components/schemas/VideoChannel'
5744         videoQuota:
5745           type: integer
5746           description: The user video quota in bytes
5747           example: -1
5748         videoQuotaDaily:
5749           type: integer
5750           description: The user daily video quota in bytes
5751           example: -1
5752         webtorrentEnabled:
5753           type: boolean
5754           description: Enable P2P in the player
5755     UserWithStats:
5756       allOf:
5757         - $ref: '#/components/schemas/User'
5758         - properties:
5759             # optionally present fields: they require WITH_STATS scope
5760             videosCount:
5761               type: integer
5762               description: Count of videos published
5763             abusesCount:
5764               type: integer
5765               description: Count of reports/abuses of which the user is a target
5766             abusesAcceptedCount:
5767               type: integer
5768               description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
5769             abusesCreatedCount:
5770               type: integer
5771               description: Count of reports/abuses created by the user
5772             videoCommentsCount:
5773               type: integer
5774               description: Count of comments published
5775     AddUser:
5776       properties:
5777         username:
5778           $ref: '#/components/schemas/username'
5779         password:
5780           $ref: '#/components/schemas/password'
5781         email:
5782           type: string
5783           format: email
5784           description: The user email
5785         videoQuota:
5786           type: integer
5787           description: The user video quota in bytes
5788           example: -1
5789         videoQuotaDaily:
5790           type: integer
5791           description: The user daily video quota in bytes
5792           example: -1
5793         channelName:
5794           $ref: '#/components/schemas/usernameChannel'
5795         role:
5796           $ref: '#/components/schemas/UserRole'
5797         adminFlags:
5798           $ref: '#/components/schemas/UserAdminFlags'
5799       required:
5800         - username
5801         - password
5802         - email
5803         - videoQuota
5804         - videoQuotaDaily
5805         - role
5806     UpdateUser:
5807       properties:
5808         email:
5809           type: string
5810           format: email
5811           description: The updated email of the user
5812         emailVerified:
5813           type: boolean
5814           description: Set the email as verified
5815         videoQuota:
5816           type: integer
5817           description: The updated video quota of the user in bytes
5818         videoQuotaDaily:
5819           type: integer
5820           description: The updated daily video quota of the user in bytes
5821         pluginAuth:
5822           type: string
5823           nullable: true
5824           description: The auth plugin to use to authenticate the user
5825           example: 'peertube-plugin-auth-saml2'
5826         role:
5827           $ref: '#/components/schemas/UserRole'
5828         adminFlags:
5829           $ref: '#/components/schemas/UserAdminFlags'
5830     UpdateMe:
5831       properties:
5832         password:
5833           $ref: '#/components/schemas/password'
5834         email:
5835           type: string
5836           format: email
5837           description: Your new email
5838         displayNSFW:
5839           type: string
5840           description: Your new displayNSFW
5841           enum:
5842             - 'true'
5843             - 'false'
5844             - both
5845         autoPlayVideo:
5846           type: boolean
5847           description: Your new autoPlayVideo
5848       required:
5849         - password
5850         - email
5851         - displayNSFW
5852         - autoPlayVideo
5853     GetMeVideoRating:
5854       properties:
5855         id:
5856           $ref: '#/components/schemas/id'
5857         rating:
5858           type: string
5859           enum:
5860             - like
5861             - dislike
5862             - none
5863           description: Rating of the video
5864       required:
5865         - id
5866         - rating
5867     VideoRating:
5868       properties:
5869         video:
5870           $ref: '#/components/schemas/Video'
5871         rating:
5872           type: string
5873           enum:
5874             - like
5875             - dislike
5876             - none
5877           description: Rating of the video
5878       required:
5879         - video
5880         - rating
5881     RegisterUser:
5882       properties:
5883         username:
5884           $ref: '#/components/schemas/username'
5885         password:
5886           $ref: '#/components/schemas/password'
5887         email:
5888           type: string
5889           format: email
5890           description: The email of the user
5891         displayName:
5892           type: string
5893           description: The user display name
5894           minLength: 1
5895           maxLength: 120
5896         channel:
5897           type: object
5898           properties:
5899             name:
5900               $ref: '#/components/schemas/usernameChannel'
5901             displayName:
5902               type: string
5903               description: The display name for the default channel
5904               minLength: 1
5905               maxLength: 120
5906       required:
5907         - username
5908         - password
5909         - email
5910
5911     VideoChannel:
5912       properties:
5913         # GET/POST/PUT properties
5914         displayName:
5915           type: string
5916           example: Videos of Framasoft
5917           minLength: 1
5918           maxLength: 120
5919         description:
5920           type: string
5921           example: Videos made with <3 by Framasoft
5922           minLength: 3
5923           maxLength: 1000
5924         support:
5925           type: string
5926           description: text shown by default on all videos of this channel, to tell the audience how to support it
5927           example: Please support my work on <insert crowdfunding plateform>! <3
5928           minLength: 3
5929           maxLength: 1000
5930         # GET-only properties
5931         id:
5932           readOnly: true
5933           allOf:
5934             - $ref: '#/components/schemas/id'
5935         isLocal:
5936           readOnly: true
5937           type: boolean
5938         updatedAt:
5939           readOnly: true
5940           type: string
5941           format: date-time
5942         ownerAccount:
5943           readOnly: true
5944           nullable: true
5945           type: object
5946           properties:
5947             id:
5948               type: integer
5949             uuid:
5950               $ref: '#/components/schemas/UUIDv4'
5951     VideoChannelCreate:
5952       allOf:
5953         - $ref: '#/components/schemas/VideoChannel'
5954         - properties:
5955             name:
5956               description: username of the channel to create
5957               allOf:
5958                 - $ref: '#/components/schemas/usernameChannel'
5959       required:
5960         - name
5961         - displayName
5962     VideoChannelUpdate:
5963       allOf:
5964         - $ref: '#/components/schemas/VideoChannel'
5965         - properties:
5966             bulkVideosSupportUpdate:
5967               type: boolean
5968               description: Update the support field for all videos of this channel
5969     VideoChannelList:
5970       properties:
5971         total:
5972           type: integer
5973           example: 1
5974         data:
5975           type: array
5976           items:
5977             allOf:
5978               - $ref: '#/components/schemas/VideoChannel'
5979               - $ref: '#/components/schemas/Actor'
5980
5981     MRSSPeerLink:
5982       type: object
5983       xml:
5984         name: 'media:peerLink'
5985       properties:
5986         href:
5987           type: string
5988           xml:
5989             attribute: true
5990         type:
5991           type: string
5992           enum:
5993             - application/x-bittorrent
5994           xml:
5995             attribute: true
5996     MRSSGroupContent:
5997       type: object
5998       xml:
5999         name: 'media:content'
6000       properties:
6001         url:
6002           type: string
6003           format: url
6004           xml:
6005             attribute: true
6006         fileSize:
6007           type: integer
6008           xml:
6009             attribute: true
6010         type:
6011           type: string
6012           xml:
6013             attribute: true
6014         framerate:
6015           type: integer
6016           xml:
6017             attribute: true
6018         duration:
6019           type: integer
6020           xml:
6021             attribute: true
6022         height:
6023           type: integer
6024           xml:
6025             attribute: true
6026         lang:
6027           type: string
6028           xml:
6029             attribute: true
6030     VideoCommentsForXML:
6031       type: array
6032       xml:
6033         wrapped: true
6034         name: 'channel'
6035       items:
6036         type: object
6037         xml:
6038           name: 'item'
6039         properties:
6040           link:
6041             type: string
6042             format: url
6043           guid:
6044             type: string
6045           pubDate:
6046             type: string
6047             format: date-time
6048           'content:encoded':
6049             type: string
6050           'dc:creator':
6051             type: string
6052     VideosForXML:
6053       type: array
6054       xml:
6055         wrapped: true
6056         name: 'channel'
6057       items:
6058         type: object
6059         xml:
6060           name: 'item'
6061         properties:
6062           link:
6063             type: string
6064             format: url
6065             description: video watch page URL
6066           guid:
6067             type: string
6068             description: video canonical URL
6069           pubDate:
6070             type: string
6071             format: date-time
6072             description: video publication date
6073           description:
6074             type: string
6075             description: video description
6076           'content:encoded':
6077             type: string
6078             description: video description
6079           'dc:creator':
6080             type: string
6081             description: publisher user name
6082           'media:category':
6083             type: integer
6084             description: video category (MRSS)
6085           'media:community':
6086             type: object
6087             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6088             properties:
6089               'media:statistics':
6090                 type: object
6091                 properties:
6092                   views:
6093                     type: integer
6094                     xml:
6095                       attribute: true
6096           'media:embed':
6097             type: object
6098             properties:
6099               url:
6100                 type: string
6101                 format: url
6102                 description: video embed path, relative to the canonical URL domain (MRSS)
6103                 xml:
6104                   attribute: true
6105           'media:player':
6106             type: object
6107             properties:
6108               url:
6109                 type: string
6110                 format: url
6111                 description: video watch path, relative to the canonical URL domain (MRSS)
6112                 xml:
6113                   attribute: true
6114           'media:thumbnail':
6115             type: object
6116             properties:
6117               url:
6118                 type: string
6119                 format: url
6120                 xml:
6121                   attribute: true
6122               height:
6123                 type: integer
6124                 xml:
6125                   attribute: true
6126               width:
6127                 type: integer
6128                 xml:
6129                   attribute: true
6130           'media:title':
6131             type: string
6132             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6133           'media:description':
6134             type: string
6135           'media:rating':
6136             type: string
6137             enum:
6138               - nonadult
6139               - adult
6140             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6141           'enclosure':
6142             type: object
6143             description: main streamable file for the video
6144             properties:
6145               url:
6146                 type: string
6147                 format: url
6148                 xml:
6149                   attribute: true
6150               type:
6151                 type: string
6152                 enum:
6153                   - application/x-bittorrent
6154                 xml:
6155                   attribute: true
6156               length:
6157                 type: integer
6158                 xml:
6159                   attribute: true
6160           'media:group':
6161             type: array
6162             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)
6163             items:
6164               anyOf:
6165                 - $ref: '#/components/schemas/MRSSPeerLink'
6166                 - $ref: '#/components/schemas/MRSSGroupContent'
6167     NotificationSettingValue:
6168       type: integer
6169       description: >
6170         Notification type
6171
6172         - `0` NONE
6173
6174         - `1` WEB
6175
6176         - `2` EMAIL
6177       enum:
6178         - 0
6179         - 1
6180         - 3
6181     Notification:
6182       properties:
6183         id:
6184           $ref: '#/components/schemas/id'
6185         type:
6186           type: integer
6187           description: >
6188             Notification type, following the `UserNotificationType` enum:
6189
6190             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6191
6192             - `2` NEW_COMMENT_ON_MY_VIDEO
6193
6194             - `3` NEW_ABUSE_FOR_MODERATORS
6195
6196             - `4` BLACKLIST_ON_MY_VIDEO
6197
6198             - `5` UNBLACKLIST_ON_MY_VIDEO
6199
6200             - `6` MY_VIDEO_PUBLISHED
6201
6202             - `7` MY_VIDEO_IMPORT_SUCCESS
6203
6204             - `8` MY_VIDEO_IMPORT_ERROR
6205
6206             - `9` NEW_USER_REGISTRATION
6207
6208             - `10` NEW_FOLLOW
6209
6210             - `11` COMMENT_MENTION
6211
6212             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6213
6214             - `13` NEW_INSTANCE_FOLLOWER
6215
6216             - `14` AUTO_INSTANCE_FOLLOWING
6217         read:
6218           type: boolean
6219         video:
6220           nullable: true
6221           allOf:
6222             - $ref: '#/components/schemas/VideoInfo'
6223             - type: object
6224               properties:
6225                 channel:
6226                   $ref: '#/components/schemas/ActorInfo'
6227         videoImport:
6228           nullable: true
6229           type: object
6230           properties:
6231             id:
6232               $ref: '#/components/schemas/id'
6233             video:
6234               nullable: true
6235               $ref: '#/components/schemas/VideoInfo'
6236             torrentName:
6237               type: string
6238               nullable: true
6239             magnetUri:
6240               $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6241             targetUri:
6242               type: string
6243               format: uri
6244               nullable: true
6245         comment:
6246           nullable: true
6247           type: object
6248           properties:
6249             id:
6250               $ref: '#/components/schemas/id'
6251             threadId:
6252               type: integer
6253             video:
6254               $ref: '#/components/schemas/VideoInfo'
6255             account:
6256               $ref: '#/components/schemas/ActorInfo'
6257         videoAbuse:
6258           nullable: true
6259           type: object
6260           properties:
6261             id:
6262               $ref: '#/components/schemas/id'
6263             video:
6264               allOf:
6265                 - $ref: '#/components/schemas/VideoInfo'
6266         videoBlacklist:
6267           nullable: true
6268           type: object
6269           properties:
6270             id:
6271               $ref: '#/components/schemas/id'
6272             video:
6273               allOf:
6274                 - $ref: '#/components/schemas/VideoInfo'
6275         account:
6276           nullable: true
6277           allOf:
6278             - $ref: '#/components/schemas/ActorInfo'
6279         actorFollow:
6280           type: object
6281           nullable: true
6282           properties:
6283             id:
6284               $ref: '#/components/schemas/id'
6285             follower:
6286               $ref: '#/components/schemas/ActorInfo'
6287             state:
6288               type: string
6289               enum:
6290                 - pending
6291                 - accepted
6292             following:
6293               type: object
6294               properties:
6295                 type:
6296                   type: string
6297                   enum:
6298                     - account
6299                     - channel
6300                     - instance
6301                 name:
6302                   type: string
6303                 displayName:
6304                   type: string
6305                 host:
6306                   type: string
6307                   format: hostname
6308         createdAt:
6309           type: string
6310           format: date-time
6311         updatedAt:
6312           type: string
6313           format: date-time
6314     NotificationListResponse:
6315       properties:
6316         total:
6317           type: integer
6318           example: 1
6319         data:
6320           type: array
6321           maxItems: 100
6322           items:
6323             $ref: '#/components/schemas/Notification'
6324     Plugin:
6325       properties:
6326         name:
6327           type: string
6328           example: peertube-plugin-auth-ldap
6329         type:
6330           type: integer
6331           description: >
6332             - `1`: PLUGIN
6333
6334             - `2`: THEME
6335           enum:
6336             - 1
6337             - 2
6338         latestVersion:
6339           type: string
6340           example: 0.0.3
6341         version:
6342           type: string
6343           example: 0.0.1
6344         enabled:
6345           type: boolean
6346         uninstalled:
6347           type: boolean
6348         peertubeEngine:
6349           type: string
6350           example: 2.2.0
6351         description:
6352           type: string
6353         homepage:
6354           type: string
6355           format: url
6356           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6357         settings:
6358           type: object
6359           additionalProperties: true
6360         createdAt:
6361           type: string
6362           format: date-time
6363         updatedAt:
6364           type: string
6365           format: date-time
6366     PluginResponse:
6367       properties:
6368         total:
6369           type: integer
6370           example: 1
6371         data:
6372           type: array
6373           maxItems: 100
6374           items:
6375             $ref: '#/components/schemas/Plugin'
6376
6377     LiveVideoUpdate:
6378       properties:
6379         saveReplay:
6380           type: boolean
6381         permanentLive:
6382           description: User can stream multiple times in a permanent live
6383           type: boolean
6384
6385     LiveVideoResponse:
6386       properties:
6387         rtmpUrl:
6388           type: string
6389         streamKey:
6390           type: string
6391           description: RTMP stream key to use to stream into this live video
6392         saveReplay:
6393           type: boolean
6394         permanentLive:
6395           description: User can stream multiple times in a permanent live
6396           type: boolean
6397
6398
6399
6400   callbacks:
6401     searchIndex:
6402       'https://search.example.org/api/v1/search/videos':
6403         post:
6404           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6405           responses:
6406             '200':
6407               description: successful operation
6408               content:
6409                 application/json:
6410                   schema:
6411                     $ref: '#/components/schemas/VideoListResponse'