support/doc/api/openapi.yaml

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