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