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