support/doc/api/openapi.yaml

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