support/doc/api/openapi.yaml

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