support/doc/api/openapi.yaml

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