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         - -hot
3495     videosSearchSort:
3496       name: sort
3497       in: query
3498       required: false
3499       description: Sort videos by criteria
3500       schema:
3501         type: string
3502         enum:
3503         - name
3504         - -duration
3505         - -createdAt
3506         - -publishedAt
3507         - -views
3508         - -likes
3509         - -match
3510     commentsSort:
3511       name: sort
3512       in: query
3513       required: false
3514       description: Sort comments by criteria
3515       schema:
3516         type: string
3517         enum:
3518         - -createdAt
3519         - -totalReplies
3520     blacklistsSort:
3521       name: sort
3522       in: query
3523       required: false
3524       description: Sort blacklists by criteria
3525       schema:
3526         type: string
3527         enum:
3528         - -id
3529         - name
3530         - -duration
3531         - -views
3532         - -likes
3533         - -dislikes
3534         - -uuid
3535         - -createdAt
3536     usersSearch:
3537       name: search
3538       in: query
3539       required: false
3540       description: Plain text search that will match with user usernames or emails
3541       schema:
3542         type: string
3543     usersBlocked:
3544       name: blocked
3545       in: query
3546       required: false
3547       description: Filter results down to (un)banned users
3548       schema:
3549         type: boolean
3550     usersSort:
3551       name: sort
3552       in: query
3553       required: false
3554       description: Sort users by criteria
3555       schema:
3556         type: string
3557         enum:
3558         - -id
3559         - -username
3560         - -createdAt
3561     abusesSort:
3562       name: sort
3563       in: query
3564       required: false
3565       description: Sort abuses by criteria
3566       schema:
3567         type: string
3568         enum:
3569         - -id
3570         - -createdAt
3571         - -state
3572     videoRedundanciesSort:
3573       name: sort
3574       in: query
3575       required: false
3576       description: Sort abuses by criteria
3577       schema:
3578         type: string
3579         enum:
3580         - name
3581     name:
3582       name: name
3583       in: path
3584       required: true
3585       description: The username or handle of the account
3586       schema:
3587         type: string
3588         example: chocobozzz | chocobozzz@example.org
3589     id:
3590       name: id
3591       in: path
3592       required: true
3593       description: The user id
3594       schema:
3595         type: integer
3596         minimum: 0
3597         example: 42
3598     idOrUUID:
3599       name: id
3600       in: path
3601       required: true
3602       description: The object id or uuid
3603       schema:
3604         oneOf:
3605           - type: integer
3606             minimum: 0
3607             example: 42
3608           - type: string
3609             format: uuid
3610             example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
3611     playlistElementId:
3612       name: playlistElementId
3613       in: path
3614       required: true
3615       description: Playlist element id
3616       schema:
3617         type: integer
3618     abuseId:
3619       name: abuseId
3620       in: path
3621       required: true
3622       description: Abuse id
3623       schema:
3624         type: integer
3625     abuseMessageId:
3626       name: abuseMessageId
3627       in: path
3628       required: true
3629       description: Abuse message id
3630       schema:
3631         type: integer
3632     captionLanguage:
3633       name: captionLanguage
3634       in: path
3635       required: true
3636       description: The caption language
3637       schema:
3638         type: string
3639     channelHandle:
3640       name: channelHandle
3641       in: path
3642       required: true
3643       description: The video channel handle
3644       schema:
3645         type: string
3646         example: my_username | my_username@example.com
3647     subscriptionHandle:
3648       name: subscriptionHandle
3649       in: path
3650       required: true
3651       description: The subscription handle
3652       schema:
3653         type: string
3654         example: my_username | my_username@example.com
3655     threadId:
3656       name: threadId
3657       in: path
3658       required: true
3659       description: The thread id (root comment id)
3660       schema:
3661         type: integer
3662     commentId:
3663       name: commentId
3664       in: path
3665       required: true
3666       description: The comment id
3667       schema:
3668         type: integer
3669     categoryOneOf:
3670       name: categoryOneOf
3671       in: query
3672       required: false
3673       description: category id of the video (see [/videos/categories](#tag/Video/paths/~1videos~1categories/get))
3674       schema:
3675         oneOf:
3676         - type: integer
3677         - type: array
3678           items:
3679             type: integer
3680       style: form
3681       explode: false
3682     tagsOneOf:
3683       name: tagsOneOf
3684       in: query
3685       required: false
3686       description: tag(s) of the video
3687       schema:
3688         oneOf:
3689         - type: string
3690         - type: array
3691           items:
3692             type: string
3693       style: form
3694       explode: false
3695     tagsAllOf:
3696       name: tagsAllOf
3697       in: query
3698       required: false
3699       description: tag(s) of the video, where all should be present in the video
3700       schema:
3701         oneOf:
3702         - type: string
3703         - type: array
3704           items:
3705             type: string
3706       style: form
3707       explode: false
3708     languageOneOf:
3709       name: languageOneOf
3710       in: query
3711       required: false
3712       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
3713       schema:
3714         oneOf:
3715         - type: string
3716         - type: array
3717           items:
3718             type: string
3719       style: form
3720       explode: false
3721     licenceOneOf:
3722       name: licenceOneOf
3723       in: query
3724       required: false
3725       description: licence id of the video (see [/videos/licences](#tag/Video/paths/~1videos~1licences/get))
3726       schema:
3727         oneOf:
3728         - type: integer
3729         - type: array
3730           items:
3731             type: integer
3732       style: form
3733       explode: false
3734     skipCount:
3735       name: skipCount
3736       in: query
3737       required: false
3738       description: if you don't need the `total` in the response
3739       schema:
3740         type: string
3741         enum:
3742           - 'true'
3743           - 'false'
3744         default: 'false'
3745     nsfw:
3746       name: nsfw
3747       in: query
3748       required: false
3749       description: whether to include nsfw videos, if any
3750       schema:
3751         type: string
3752         enum:
3753         - 'true'
3754         - 'false'
3755     filter:
3756       name: filter
3757       in: query
3758       required: false
3759       description: >
3760         Special filters which might require special rights:
3761          * `local` - only videos local to the instance
3762          * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
3763          * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
3764       schema:
3765         type: string
3766         enum:
3767         - local
3768         - all-local
3769     subscriptionsUris:
3770       name: uris
3771       in: query
3772       required: true
3773       description: list of uris to check if each is part of the user subscriptions
3774       schema:
3775         type: array
3776         items:
3777           type: string
3778           format: uri
3779     npmName:
3780       name: npmName
3781       in: path
3782       required: true
3783       description: name of the plugin/theme on npmjs.com or in its package.json
3784       schema:
3785         type: string
3786         example: peertube-plugin-auth-ldap
3787     jobType:
3788       name: jobType
3789       in: query
3790       required: false
3791       description: job type
3792       schema:
3793         type: string
3794         enum:
3795           - activitypub-follow
3796           - activitypub-http-broadcast
3797           - activitypub-http-fetcher
3798           - activitypub-http-unicast
3799           - email
3800           - video-transcoding
3801           - video-file-import
3802           - video-import
3803           - videos-views
3804           - activitypub-refresher
3805           - video-redundancy
3806           - video-live-ending
3807   securitySchemes:
3808     OAuth2:
3809       description: >
3810         In the header: *Authorization: Bearer <token\>*
3811
3812
3813         Authenticating via OAuth requires the following steps:
3814
3815
3816         - Have an account with sufficient authorization levels
3817
3818         - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
3819         Bearer Token
3820
3821         - Make Authenticated Requests
3822       type: oauth2
3823       flows:
3824         password:
3825           tokenUrl: 'https://peertube.example.com/api/v1/users/token'
3826           scopes:
3827             admin: Admin scope
3828             moderator: Moderator scope
3829             user: User scope
3830   schemas:
3831     VideoConstantNumber:
3832       properties:
3833         id:
3834           type: integer
3835         label:
3836           type: string
3837     VideoConstantString:
3838       properties:
3839         id:
3840           type: string
3841         label:
3842           type: string
3843
3844     VideoPlaylistPrivacySet:
3845       type: integer
3846       enum:
3847         - 1
3848         - 2
3849         - 3
3850       description: 'The video playlist privacy (Public = `1`, Unlisted = `2`, Private = `3`)'
3851     VideoPlaylistPrivacyConstant:
3852       properties:
3853         id:
3854           $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3855         label:
3856           type: string
3857
3858     VideoPlaylistTypeSet:
3859       type: integer
3860       enum:
3861         - 1
3862         - 2
3863       description: 'The video playlist type (Regular = `1`, Watch Later = `2`)'
3864     VideoPlaylistTypeConstant:
3865       properties:
3866         id:
3867           $ref: '#/components/schemas/VideoPlaylistTypeSet'
3868         label:
3869           type: string
3870
3871     VideoPrivacySet:
3872       type: integer
3873       enum:
3874         - 1
3875         - 2
3876         - 3
3877         - 4
3878       description: 'The video privacy (Public = `1`, Unlisted = `2`, Private = `3`, Internal = `4`)'
3879     VideoPrivacyConstant:
3880       properties:
3881         id:
3882           $ref: '#/components/schemas/VideoPrivacySet'
3883         label:
3884           type: string
3885
3886     NSFWPolicy:
3887       type: string
3888       enum:
3889         - display
3890         - blur
3891         - do_not_list
3892
3893     UserRole:
3894       type: integer
3895       enum:
3896         - 0
3897         - 1
3898         - 2
3899       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
3900       example: 2
3901
3902     VideoStateConstant:
3903       properties:
3904         id:
3905           type: integer
3906           enum:
3907             - 1
3908             - 2
3909             - 3
3910           description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
3911         label:
3912           type: string
3913
3914     AbuseStateSet:
3915       type: integer
3916       enum:
3917         - 1
3918         - 2
3919         - 3
3920       description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
3921     AbuseStateConstant:
3922       properties:
3923         id:
3924           $ref: '#/components/schemas/AbuseStateSet'
3925         label:
3926           type: string
3927     AbusePredefinedReasons:
3928       type: array
3929       items:
3930         type: string
3931         enum:
3932         - violentOrAbusive
3933         - hatefulOrAbusive
3934         - spamOrMisleading
3935         - privacy
3936         - rights
3937         - serverRules
3938         - thumbnails
3939         - captions
3940       example: [spamOrMisleading]
3941
3942     VideoResolutionConstant:
3943       properties:
3944         id:
3945           type: integer
3946           description: 'Video resolution (240, 360, 720, 1080, 1440 or 2160)'
3947           example: 240
3948         label:
3949           type: string
3950           example: 240p
3951     VideoScheduledUpdate:
3952       properties:
3953         privacy:
3954           $ref: '#/components/schemas/VideoPrivacySet'
3955         updateAt:
3956           type: string
3957           format: date
3958           description: When to update the video
3959       required:
3960         - updateAt
3961     AccountSummary:
3962       properties:
3963         id:
3964           type: integer
3965         name:
3966           type: string
3967         displayName:
3968           type: string
3969         url:
3970           type: string
3971           format: url
3972         host:
3973           type: string
3974           format: hostname
3975         avatar:
3976           nullable: true
3977           allOf:
3978             - $ref: '#/components/schemas/Avatar'
3979     VideoChannelSummary:
3980       properties:
3981         id:
3982           type: integer
3983         name:
3984           type: string
3985         displayName:
3986           type: string
3987         url:
3988           type: string
3989           format: url
3990         host:
3991           type: string
3992           format: hostname
3993         avatar:
3994           nullable: true
3995           allOf:
3996             - $ref: '#/components/schemas/Avatar'
3997     PlaylistElement:
3998       properties:
3999         position:
4000           type: integer
4001         startTimestamp:
4002           type: integer
4003         stopTimestamp:
4004           type: integer
4005         video:
4006           nullable: true
4007           allOf:
4008             - $ref: '#/components/schemas/Video'
4009     VideoFile:
4010       properties:
4011         magnetUri:
4012           type: string
4013         resolution:
4014           $ref: '#/components/schemas/VideoResolutionConstant'
4015         size:
4016           type: integer
4017           description: 'Video file size in bytes'
4018         torrentUrl:
4019           type: string
4020           format: url
4021         torrentDownloadUrl:
4022           type: string
4023           format: url
4024         fileUrl:
4025           type: string
4026           format: url
4027         fileDownloadUrl:
4028           type: string
4029           format: url
4030         fps:
4031           type: number
4032         metadataUrl:
4033           type: string
4034           format: url
4035     VideoStreamingPlaylists:
4036       properties:
4037         id:
4038           type: integer
4039         type:
4040           type: integer
4041           enum:
4042             - 1
4043           description: 'Playlist type (HLS = `1`)'
4044         playlistUrl:
4045           type: string
4046           format: url
4047         segmentsSha256Url:
4048           type: string
4049           format: url
4050         files:
4051           type: array
4052           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)'
4053           items:
4054             $ref: '#/components/schemas/VideoFile'
4055         redundancies:
4056           type: array
4057           items:
4058             type: object
4059             properties:
4060               baseUrl:
4061                 type: string
4062                 format: url
4063     VideoInfo:
4064       properties:
4065         id:
4066           type: integer
4067         uuid:
4068           type: string
4069           format: uuid
4070           example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4071         name:
4072           type: string
4073     Video:
4074       properties:
4075         id:
4076           type: integer
4077           example: 8
4078         uuid:
4079           type: string
4080           format: uuid
4081           example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4082         isLive:
4083           type: boolean
4084         createdAt:
4085           type: string
4086           format: date-time
4087         publishedAt:
4088           type: string
4089           format: date-time
4090         updatedAt:
4091           type: string
4092           format: date-time
4093         originallyPublishedAt:
4094           type: string
4095           format: date-time
4096         category:
4097           $ref: '#/components/schemas/VideoConstantNumber'
4098         licence:
4099           $ref: '#/components/schemas/VideoConstantNumber'
4100         language:
4101           $ref: '#/components/schemas/VideoConstantString'
4102         privacy:
4103           $ref: '#/components/schemas/VideoPrivacyConstant'
4104         description:
4105           type: string
4106         duration:
4107           type: integer
4108           example: 1419
4109         isLocal:
4110           type: boolean
4111         name:
4112           type: string
4113           example: What is PeerTube?
4114         thumbnailPath:
4115           type: string
4116           example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4117         previewPath:
4118           type: string
4119           example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
4120         embedPath:
4121           type: string
4122           example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
4123         views:
4124           type: integer
4125           example: 1337
4126         likes:
4127           type: integer
4128           example: 42
4129         dislikes:
4130           type: integer
4131           example: 7
4132         nsfw:
4133           type: boolean
4134         waitTranscoding:
4135           type: boolean
4136           nullable: true
4137         state:
4138           $ref: '#/components/schemas/VideoStateConstant'
4139         scheduledUpdate:
4140           nullable: true
4141           allOf:
4142             - $ref: '#/components/schemas/VideoScheduledUpdate'
4143         blacklisted:
4144           nullable: true
4145           type: boolean
4146         blacklistedReason:
4147           nullable: true
4148           type: string
4149         account:
4150           $ref: '#/components/schemas/AccountSummary'
4151         channel:
4152           $ref: '#/components/schemas/VideoChannelSummary'
4153         userHistory:
4154           nullable: true
4155           type: object
4156           properties:
4157             currentTime:
4158               type: integer
4159     VideoDetails:
4160       allOf:
4161         - $ref: '#/components/schemas/Video'
4162         - type: object
4163           properties:
4164             descriptionPath:
4165               type: string
4166             support:
4167               type: string
4168               description: A text tell the audience how to support the video creator
4169               example: Please support my work on <insert crowdfunding plateform>! <3
4170             channel:
4171               $ref: '#/components/schemas/VideoChannel'
4172             account:
4173               $ref: '#/components/schemas/Account'
4174             tags:
4175               type: array
4176               items:
4177                 type: string
4178               example: [flowers, gardening]
4179             files:
4180               type: array
4181               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'
4182               items:
4183                 $ref: '#/components/schemas/VideoFile'
4184             commentsEnabled:
4185               type: boolean
4186             downloadEnabled:
4187               type: boolean
4188             trackerUrls:
4189               type: array
4190               items:
4191                 type: string
4192                 format: url
4193             streamingPlaylists:
4194               type: array
4195               items:
4196                 $ref: '#/components/schemas/VideoStreamingPlaylists'
4197     FileRedundancyInformation:
4198       properties:
4199         id:
4200           type: integer
4201         fileUrl:
4202           type: string
4203           format: url
4204         strategy:
4205           type: string
4206           enum:
4207             - manual
4208             - most-views
4209             - trending
4210             - recently-added
4211         size:
4212           type: integer
4213         createdAt:
4214           type: string
4215           format: date-time
4216         updatedAt:
4217           type: string
4218           format: date-time
4219         expiresOn:
4220           type: string
4221           format: date-time
4222     VideoRedundancy:
4223       properties:
4224         id:
4225           type: integer
4226         name:
4227           type: string
4228         url:
4229           type: string
4230           format: url
4231         uuid:
4232           type: string
4233           format: uuid
4234           example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4235         redundancies:
4236           type: object
4237           properties:
4238             files:
4239               type: array
4240               items:
4241                 $ref: '#/components/schemas/FileRedundancyInformation'
4242             streamingPlaylists:
4243               type: array
4244               items:
4245                 $ref: '#/components/schemas/FileRedundancyInformation'
4246     VideoImportStateConstant:
4247       properties:
4248         id:
4249           type: integer
4250           enum:
4251             - 1
4252             - 2
4253             - 3
4254           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
4255         label:
4256           type: string
4257           example: Pending
4258     VideoImport:
4259       properties:
4260         id:
4261           type: integer
4262           example: 2
4263         targetUrl:
4264           type: string
4265           format: url
4266           example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
4267         magnetUri:
4268           type: string
4269           format: uri
4270           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
4271         torrentName:
4272           type: string
4273         state:
4274           $ref: '#/components/schemas/VideoImportStateConstant'
4275         error:
4276           type: string
4277         createdAt:
4278           type: string
4279           format: date-time
4280         updatedAt:
4281           type: string
4282           format: date-time
4283         video:
4284           $ref: '#/components/schemas/Video'
4285     Abuse:
4286       properties:
4287         id:
4288           type: integer
4289           example: 7
4290         reason:
4291           type: string
4292           example: The video is a spam
4293         predefinedReasons:
4294           $ref: '#/components/schemas/AbusePredefinedReasons'
4295         reporterAccount:
4296           $ref: '#/components/schemas/Account'
4297         state:
4298           $ref: '#/components/schemas/AbuseStateConstant'
4299         moderationComment:
4300           type: string
4301           example: Decided to ban the server since it spams us regularly
4302         video:
4303           type: object
4304           properties:
4305             id:
4306               type: integer
4307             name:
4308               type: string
4309             uuid:
4310               type: string
4311               format: uuid
4312               example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4313         createdAt:
4314           type: string
4315           format: date-time
4316     AbuseMessage:
4317       properties:
4318         id:
4319           type: integer
4320         message:
4321           type: string
4322         byModerator:
4323           type: boolean
4324         createdAt:
4325           type: string
4326           format: date-time
4327         account:
4328           $ref: '#/components/schemas/AccountSummary'
4329     VideoBlacklist:
4330       properties:
4331         id:
4332           type: integer
4333         videoId:
4334           type: integer
4335         createdAt:
4336           type: string
4337           format: date-time
4338         updatedAt:
4339           type: string
4340           format: date-time
4341         name:
4342           type: string
4343         uuid:
4344           type: string
4345           format: uuid
4346           example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4347         description:
4348           type: string
4349         duration:
4350           type: integer
4351         views:
4352           type: integer
4353         likes:
4354           type: integer
4355         dislikes:
4356           type: integer
4357         nsfw:
4358           type: boolean
4359     VideoChannel:
4360       properties:
4361         displayName:
4362           type: string
4363         description:
4364           type: string
4365         isLocal:
4366           type: boolean
4367         ownerAccount:
4368           type: object
4369           properties:
4370             id:
4371               type: integer
4372             uuid:
4373               type: string
4374               format: uuid
4375               example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4376     VideoPlaylist:
4377       properties:
4378         id:
4379           type: integer
4380         createdAt:
4381           type: string
4382           format: date-time
4383         updatedAt:
4384           type: string
4385           format: date-time
4386         description:
4387           type: string
4388         uuid:
4389           type: string
4390           format: uuid
4391           example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4392         displayName:
4393           type: string
4394         isLocal:
4395           type: boolean
4396         videoLength:
4397           type: integer
4398         thumbnailPath:
4399           type: string
4400         privacy:
4401           $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
4402         type:
4403           $ref: '#/components/schemas/VideoPlaylistTypeConstant'
4404         ownerAccount:
4405           $ref: '#/components/schemas/AccountSummary'
4406         videoChannel:
4407           $ref: '#/components/schemas/VideoChannelSummary'
4408     VideoComment:
4409       properties:
4410         id:
4411           type: integer
4412         url:
4413           type: string
4414           format: url
4415         text:
4416           type: string
4417         threadId:
4418           type: integer
4419         inReplyToCommentId:
4420           type: integer
4421         videoId:
4422           type: integer
4423         createdAt:
4424           type: string
4425           format: date-time
4426         updatedAt:
4427           type: string
4428           format: date-time
4429         totalRepliesFromVideoAuthor:
4430           type: integer
4431         totalReplies:
4432           type: integer
4433         account:
4434           $ref: '#/components/schemas/Account'
4435     VideoCommentThreadTree:
4436       properties:
4437         comment:
4438           $ref: '#/components/schemas/VideoComment'
4439         children:
4440           type: array
4441           items:
4442             $ref: '#/components/schemas/VideoCommentThreadTree'
4443     VideoCaption:
4444       properties:
4445         language:
4446           $ref: '#/components/schemas/VideoConstantString'
4447         captionPath:
4448           type: string
4449     Avatar:
4450       properties:
4451         path:
4452           type: string
4453         createdAt:
4454           type: string
4455           format: date-time
4456         updatedAt:
4457           type: string
4458           format: date-time
4459     ActorInfo:
4460       properties:
4461         id:
4462           type: integer
4463           example: 11
4464         name:
4465           type: string
4466         displayName:
4467           type: string
4468         host:
4469           type: string
4470           format: hostname
4471         avatar:
4472           nullable: true
4473           type: object
4474           properties:
4475             path:
4476               type: string
4477     Actor:
4478       properties:
4479         id:
4480           type: integer
4481           example: 11
4482         url:
4483           type: string
4484           format: url
4485         name:
4486           type: string
4487         host:
4488           type: string
4489           format: hostname
4490         followingCount:
4491           type: integer
4492         followersCount:
4493           type: integer
4494         createdAt:
4495           type: string
4496           format: date-time
4497         updatedAt:
4498           type: string
4499           format: date-time
4500         avatar:
4501           $ref: '#/components/schemas/Avatar'
4502     Account:
4503       allOf:
4504         - $ref: '#/components/schemas/Actor'
4505         - properties:
4506             userId:
4507               type: string
4508               example: 2
4509             displayName:
4510               type: string
4511             description:
4512               type: string
4513     UserWatchingVideo:
4514       properties:
4515         currentTime:
4516           type: integer
4517           description: timestamp within the video, in seconds
4518           example: 5
4519     ServerConfig:
4520       properties:
4521         instance:
4522           type: object
4523           properties:
4524             name:
4525               type: string
4526             shortDescription:
4527               type: string
4528             defaultClientRoute:
4529               type: string
4530             isNSFW:
4531               type: boolean
4532             defaultNSFWPolicy:
4533               type: string
4534             customizations:
4535               type: object
4536               properties:
4537                 javascript:
4538                   type: string
4539                 css:
4540                   type: string
4541         search:
4542           type: object
4543           properties:
4544             remoteUri:
4545               type: object
4546               properties:
4547                 users:
4548                   type: boolean
4549                 anonymous:
4550                   type: boolean
4551         plugin:
4552           type: object
4553           properties:
4554             registered:
4555               type: array
4556               items:
4557                 type: string
4558         theme:
4559           type: object
4560           properties:
4561             registered:
4562               type: array
4563               items:
4564                 type: string
4565         email:
4566           type: object
4567           properties:
4568             enabled:
4569               type: boolean
4570         contactForm:
4571           type: object
4572           properties:
4573             enabled:
4574               type: boolean
4575         serverVersion:
4576           type: string
4577         serverCommit:
4578           type: string
4579         signup:
4580           type: object
4581           properties:
4582             allowed:
4583               type: boolean
4584             allowedForCurrentIP:
4585               type: boolean
4586             requiresEmailVerification:
4587               type: boolean
4588         transcoding:
4589           type: object
4590           properties:
4591             hls:
4592               type: object
4593               properties:
4594                 enabled:
4595                   type: boolean
4596             webtorrent:
4597               type: object
4598               properties:
4599                 enabled:
4600                   type: boolean
4601             enabledResolutions:
4602               type: array
4603               items:
4604                 type: integer
4605         import:
4606           type: object
4607           properties:
4608             videos:
4609               type: object
4610               properties:
4611                 http:
4612                   type: object
4613                   properties:
4614                     enabled:
4615                       type: boolean
4616                 torrent:
4617                   type: object
4618                   properties:
4619                     enabled:
4620                       type: boolean
4621         autoBlacklist:
4622           type: object
4623           properties:
4624             videos:
4625               type: object
4626               properties:
4627                 ofUsers:
4628                   type: object
4629                   properties:
4630                     enabled:
4631                       type: boolean
4632         avatar:
4633           type: object
4634           properties:
4635             file:
4636               type: object
4637               properties:
4638                 size:
4639                   type: object
4640                   properties:
4641                     max:
4642                       type: integer
4643             extensions:
4644               type: array
4645               items:
4646                 type: string
4647         video:
4648           type: object
4649           properties:
4650             image:
4651               type: object
4652               properties:
4653                 extensions:
4654                   type: array
4655                   items:
4656                     type: string
4657                 size:
4658                   type: object
4659                   properties:
4660                     max:
4661                       type: integer
4662             file:
4663               type: object
4664               properties:
4665                 extensions:
4666                   type: array
4667                   items:
4668                     type: string
4669         videoCaption:
4670           type: object
4671           properties:
4672             file:
4673               type: object
4674               properties:
4675                 size:
4676                   type: object
4677                   properties:
4678                     max:
4679                       type: integer
4680                 extensions:
4681                   type: array
4682                   items:
4683                     type: string
4684         user:
4685           type: object
4686           properties:
4687             videoQuota:
4688               type: integer
4689             videoQuotaDaily:
4690               type: integer
4691         trending:
4692           type: object
4693           properties:
4694             videos:
4695               type: object
4696               properties:
4697                 intervalDays:
4698                   type: integer
4699         tracker:
4700           type: object
4701           properties:
4702             enabled:
4703               type: boolean
4704         followings:
4705           type: object
4706           properties:
4707             instance:
4708               type: object
4709               properties:
4710                 autoFollowIndex:
4711                   type: object
4712                   properties:
4713                     indexUrl:
4714                       type: string
4715                       format: url
4716     ServerConfigAbout:
4717       properties:
4718         instance:
4719           type: object
4720           properties:
4721             name:
4722               type: string
4723             shortDescription:
4724               type: string
4725             description:
4726               type: string
4727             terms:
4728               type: string
4729     ServerConfigCustom:
4730       properties:
4731         instance:
4732           type: object
4733           properties:
4734             name:
4735               type: string
4736             shortDescription:
4737               type: string
4738             description:
4739               type: string
4740             terms:
4741               type: string
4742             defaultClientRoute:
4743               type: string
4744             isNSFW:
4745               type: boolean
4746             defaultNSFWPolicy:
4747               type: string
4748             customizations:
4749               type: object
4750               properties:
4751                 javascript:
4752                   type: string
4753                 css:
4754                   type: string
4755         theme:
4756           type: object
4757           properties:
4758             default:
4759               type: string
4760         services:
4761           type: object
4762           properties:
4763             twitter:
4764               type: object
4765               properties:
4766                 username:
4767                   type: string
4768                 whitelisted:
4769                   type: boolean
4770         cache:
4771           type: object
4772           properties:
4773             previews:
4774               type: object
4775               properties:
4776                 size:
4777                   type: integer
4778             captions:
4779               type: object
4780               properties:
4781                 size:
4782                   type: integer
4783         signup:
4784           type: object
4785           properties:
4786             enabled:
4787               type: boolean
4788             limit:
4789               type: integer
4790             requiresEmailVerification:
4791               type: boolean
4792         admin:
4793           type: object
4794           properties:
4795             email:
4796               type: string
4797               format: email
4798         contactForm:
4799           type: object
4800           properties:
4801             enabled:
4802               type: boolean
4803         user:
4804           type: object
4805           properties:
4806             videoQuota:
4807               type: integer
4808             videoQuotaDaily:
4809               type: integer
4810         transcoding:
4811           type: object
4812           properties:
4813             enabled:
4814               type: boolean
4815             allowAdditionalExtensions:
4816               type: boolean
4817             allowAudioFiles:
4818               type: boolean
4819             threads:
4820               type: integer
4821             resolutions:
4822               type: object
4823               properties:
4824                 240p:
4825                   type: boolean
4826                 360p:
4827                   type: boolean
4828                 480p:
4829                   type: boolean
4830                 720p:
4831                   type: boolean
4832                 1080p:
4833                   type: boolean
4834                 1440p:
4835                   type: boolean
4836                 2160p:
4837                   type: boolean
4838             hls:
4839               type: object
4840               properties:
4841                 enabled:
4842                   type: boolean
4843         import:
4844           type: object
4845           properties:
4846             videos:
4847               type: object
4848               properties:
4849                 http:
4850                   type: object
4851                   properties:
4852                     enabled:
4853                       type: boolean
4854                 torrent:
4855                   type: object
4856                   properties:
4857                     enabled:
4858                       type: boolean
4859         autoBlacklist:
4860           type: object
4861           properties:
4862             videos:
4863               type: object
4864               properties:
4865                 ofUsers:
4866                   type: object
4867                   properties:
4868                     enabled:
4869                       type: boolean
4870         followers:
4871           type: object
4872           properties:
4873             instance:
4874               type: object
4875               properties:
4876                 enabled:
4877                   type: boolean
4878                 manualApproval:
4879                   type: boolean
4880     Follow:
4881       properties:
4882         id:
4883           type: integer
4884         follower:
4885           $ref: '#/components/schemas/Actor'
4886         following:
4887           $ref: '#/components/schemas/Actor'
4888         score:
4889           type: number
4890           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
4891         state:
4892           type: string
4893           enum:
4894             - pending
4895             - accepted
4896         createdAt:
4897           type: string
4898           format: date-time
4899         updatedAt:
4900           type: string
4901           format: date-time
4902
4903     PredefinedAbuseReasons:
4904       description: Reason categories that help triage reports
4905       type: array
4906       items:
4907         type: string
4908         enum:
4909         - violentOrAbusive
4910         - hatefulOrAbusive
4911         - spamOrMisleading
4912         - privacy
4913         - rights
4914         - serverRules
4915         - thumbnails
4916         - captions
4917
4918     Job:
4919       properties:
4920         id:
4921           type: integer
4922           minimum: 0
4923           example: 42
4924         state:
4925           type: string
4926           enum:
4927             - active
4928             - completed
4929             - failed
4930             - waiting
4931             - delayed
4932         type:
4933           type: string
4934           enum:
4935             - activitypub-http-unicast
4936             - activitypub-http-broadcast
4937             - activitypub-http-fetcher
4938             - activitypub-follow
4939             - video-file-import
4940             - video-transcoding
4941             - email
4942             - video-import
4943             - videos-views
4944             - activitypub-refresher
4945             - video-redundancy
4946         data:
4947           type: object
4948           additionalProperties: true
4949         error:
4950           type: object
4951           additionalProperties: true
4952         createdAt:
4953           type: string
4954           format: date-time
4955         finishedOn:
4956           type: string
4957           format: date-time
4958         processedOn:
4959           type: string
4960           format: date-time
4961     AddUserResponse:
4962       properties:
4963         user:
4964           type: object
4965           properties:
4966             id:
4967               type: integer
4968               example: 8
4969             account:
4970               type: object
4971               properties:
4972                 id:
4973                   type: integer
4974                   example: 37
4975     VideoUploadResponse:
4976       properties:
4977         video:
4978           type: object
4979           properties:
4980             id:
4981               type: integer
4982               example: 8
4983             uuid:
4984               type: string
4985               format: uuid
4986               example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4987     CommentThreadResponse:
4988       properties:
4989         total:
4990           type: integer
4991           example: 1
4992         data:
4993           type: array
4994           maxItems: 100
4995           items:
4996             $ref: '#/components/schemas/VideoComment'
4997     CommentThreadPostResponse:
4998       properties:
4999         comment:
5000           $ref: '#/components/schemas/VideoComment'
5001     VideoListResponse:
5002       properties:
5003         total:
5004           type: integer
5005           example: 1
5006         data:
5007           type: array
5008           maxItems: 100
5009           items:
5010             $ref: '#/components/schemas/Video'
5011     User:
5012       properties:
5013         id:
5014           type: integer
5015           readOnly: true
5016         username:
5017           type: string
5018           description: The user username
5019           minLength: 1
5020           maxLength: 50
5021         email:
5022           type: string
5023           format: email
5024           description: The user email
5025         theme:
5026           type: string
5027           description: Theme enabled by this user
5028         emailVerified:
5029           type: boolean
5030           description: Has the user confirmed their email address?
5031         nsfwPolicy:
5032           $ref: '#/components/schemas/NSFWPolicy'
5033         webtorrentEnabled:
5034           type: boolean
5035           description: Enable P2P in the player
5036         autoPlayVideo:
5037           type: boolean
5038           description: Automatically start playing the video on the watch page
5039         role:
5040           $ref: '#/components/schemas/UserRole'
5041         roleLabel:
5042           type: string
5043           enum:
5044             - User
5045             - Moderator
5046             - Administrator
5047         videoQuota:
5048           type: integer
5049           description: The user video quota
5050         videoQuotaDaily:
5051           type: integer
5052           description: The user daily video quota
5053         videosCount:
5054           type: integer
5055         abusesCount:
5056           type: integer
5057         abusesAcceptedCount:
5058           type: integer
5059         abusesCreatedCount:
5060           type: integer
5061         videoCommentsCount:
5062           type: integer
5063         noInstanceConfigWarningModal:
5064           type: boolean
5065         noWelcomeModal:
5066           type: boolean
5067         blocked:
5068           type: boolean
5069         blockedReason:
5070           type: string
5071         createdAt:
5072           type: string
5073         account:
5074           $ref: '#/components/schemas/Account'
5075         videoChannels:
5076           type: array
5077           items:
5078             $ref: '#/components/schemas/VideoChannel'
5079     AddUser:
5080       properties:
5081         username:
5082           type: string
5083           description: The user username
5084           minLength: 1
5085           maxLength: 50
5086         password:
5087           type: string
5088           format: password
5089           description: The user password. If the smtp server is configured, you can leave empty and an email will be sent
5090           minLength: 6
5091           maxLength: 255
5092         email:
5093           type: string
5094           format: email
5095           description: The user email
5096         videoQuota:
5097           type: integer
5098           description: The user video quota
5099         videoQuotaDaily:
5100           type: integer
5101           description: The user daily video quota
5102         role:
5103           $ref: '#/components/schemas/UserRole'
5104       required:
5105         - username
5106         - password
5107         - email
5108         - videoQuota
5109         - videoQuotaDaily
5110         - role
5111     UpdateUser:
5112       properties:
5113         id:
5114           type: string
5115           description: The user id
5116         email:
5117           type: string
5118           format: email
5119           description: The updated email of the user
5120         videoQuota:
5121           type: integer
5122           description: The updated video quota of the user
5123         videoQuotaDaily:
5124           type: integer
5125           description: The updated daily video quota of the user
5126         role:
5127           $ref: '#/components/schemas/UserRole'
5128       required:
5129         - id
5130         - email
5131         - videoQuota
5132         - videoQuotaDaily
5133         - role
5134     UpdateMe:
5135       properties:
5136         password:
5137           type: string
5138           format: password
5139           description: Your new password
5140           minLength: 6
5141           maxLength: 255
5142         email:
5143           type: string
5144           format: email
5145           description: Your new email
5146         displayNSFW:
5147           type: string
5148           description: Your new displayNSFW
5149           enum:
5150             - 'true'
5151             - 'false'
5152             - both
5153         autoPlayVideo:
5154           type: boolean
5155           description: Your new autoPlayVideo
5156       required:
5157         - password
5158         - email
5159         - displayNSFW
5160         - autoPlayVideo
5161     GetMeVideoRating:
5162       properties:
5163         id:
5164           type: string
5165           description: Id of the video
5166         rating:
5167           type: number
5168           description: Rating of the video
5169       required:
5170         - id
5171         - rating
5172     VideoRating:
5173       properties:
5174         video:
5175           $ref: '#/components/schemas/Video'
5176         rating:
5177           type: number
5178           description: 'Rating of the video'
5179       required:
5180         - video
5181         - rating
5182     RegisterUser:
5183       properties:
5184         username:
5185           type: string
5186           description: The username of the user
5187           minLength: 1
5188           maxLength: 50
5189           pattern: '/^[a-z0-9._]{1,50}$/'
5190         password:
5191           type: string
5192           format: password
5193           description: The password of the user
5194           minLength: 6
5195           maxLength: 255
5196         email:
5197           type: string
5198           format: email
5199           description: The email of the user
5200         displayName:
5201           type: string
5202           description: The user display name
5203           minLength: 1
5204           maxLength: 120
5205         channel:
5206           type: object
5207           properties:
5208             name:
5209               type: string
5210               description: The username for the default channel
5211               pattern: '/^[ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789\\-_.:]+$/'
5212             displayName:
5213               type: string
5214               description: The display name for the default channel
5215               minLength: 1
5216               maxLength: 120
5217       required:
5218         - username
5219         - password
5220         - email
5221     VideoChannelCreate:
5222       properties:
5223         name:
5224           type: string
5225         displayName:
5226           type: string
5227         description:
5228           type: string
5229         support:
5230           type: string
5231           description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
5232           example: Please support my work on <insert crowdfunding plateform>! <3
5233       required:
5234         - name
5235         - displayName
5236     VideoChannelUpdate:
5237       properties:
5238         displayName:
5239           type: string
5240         description:
5241           type: string
5242         support:
5243           type: string
5244           description: 'A text shown by default on all videos of this channel, to tell the audience how to support it'
5245           example: Please support my work on <insert crowdfunding plateform>! <3
5246         bulkVideosSupportUpdate:
5247           type: boolean
5248           description: 'Update the support field for all videos of this channel'
5249
5250     MRSSPeerLink:
5251       type: object
5252       xml:
5253         name: 'media:peerLink'
5254       properties:
5255         href:
5256           type: string
5257           xml:
5258             attribute: true
5259         type:
5260           type: string
5261           enum:
5262             - application/x-bittorrent
5263           xml:
5264             attribute: true
5265     MRSSGroupContent:
5266       type: object
5267       xml:
5268         name: 'media:content'
5269       properties:
5270         url:
5271           type: string
5272           format: url
5273           xml:
5274             attribute: true
5275         fileSize:
5276           type: integer
5277           xml:
5278             attribute: true
5279         type:
5280           type: string
5281           xml:
5282             attribute: true
5283         framerate:
5284           type: integer
5285           xml:
5286             attribute: true
5287         duration:
5288           type: integer
5289           xml:
5290             attribute: true
5291         height:
5292           type: integer
5293           xml:
5294             attribute: true
5295         lang:
5296           type: string
5297           xml:
5298             attribute: true
5299     VideoCommentsForXML:
5300       type: array
5301       xml:
5302         wrapped: true
5303         name: 'channel'
5304       items:
5305         type: object
5306         xml:
5307           name: 'item'
5308         properties:
5309           link:
5310             type: string
5311             format: url
5312           guid:
5313             type: string
5314           pubDate:
5315             type: string
5316             format: date-time
5317           'content:encoded':
5318             type: string
5319           'dc:creator':
5320             type: string
5321     VideosForXML:
5322       type: array
5323       xml:
5324         wrapped: true
5325         name: 'channel'
5326       items:
5327         type: object
5328         xml:
5329           name: 'item'
5330         properties:
5331           link:
5332             type: string
5333             format: url
5334             description: video watch page URL
5335           guid:
5336             type: string
5337             description: video canonical URL
5338           pubDate:
5339             type: string
5340             format: date-time
5341             description: video publication date
5342           description:
5343             type: string
5344             description: video description
5345           'content:encoded':
5346             type: string
5347             description: video description
5348           'dc:creator':
5349             type: string
5350             description: publisher user name
5351           'media:category':
5352             type: integer
5353             description: video category (MRSS)
5354           'media:community':
5355             type: object
5356             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
5357             properties:
5358               'media:statistics':
5359                 type: object
5360                 properties:
5361                   views:
5362                     type: integer
5363                     xml:
5364                       attribute: true
5365           'media:embed':
5366             type: object
5367             properties:
5368               url:
5369                 type: string
5370                 format: url
5371                 description: video embed path, relative to the canonical URL domain (MRSS)
5372                 xml:
5373                   attribute: true
5374           'media:player':
5375             type: object
5376             properties:
5377               url:
5378                 type: string
5379                 format: url
5380                 description: video watch path, relative to the canonical URL domain (MRSS)
5381                 xml:
5382                   attribute: true
5383           'media:thumbnail':
5384             type: object
5385             properties:
5386               url:
5387                 type: string
5388                 format: url
5389                 xml:
5390                   attribute: true
5391               height:
5392                 type: integer
5393                 xml:
5394                   attribute: true
5395               width:
5396                 type: integer
5397                 xml:
5398                   attribute: true
5399           'media:title':
5400             type: string
5401             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
5402           'media:description':
5403             type: string
5404           'media:rating':
5405             type: string
5406             enum:
5407               - nonadult
5408               - adult
5409             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
5410           'enclosure':
5411             type: object
5412             description: main streamable file for the video
5413             properties:
5414               url:
5415                 type: string
5416                 format: url
5417                 xml:
5418                   attribute: true
5419               type:
5420                 type: string
5421                 enum:
5422                   - application/x-bittorrent
5423                 xml:
5424                   attribute: true
5425               length:
5426                 type: integer
5427                 xml:
5428                   attribute: true
5429           'media:group':
5430             type: array
5431             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)
5432             items:
5433               anyOf:
5434                 - $ref: '#/components/schemas/MRSSPeerLink'
5435                 - $ref: '#/components/schemas/MRSSGroupContent'
5436     NotificationSettingValue:
5437       type: integer
5438       description: >
5439         Notification type
5440
5441         - `0` NONE
5442
5443         - `1` WEB
5444
5445         - `2` EMAIL
5446       enum:
5447         - 0
5448         - 1
5449         - 3
5450     Notification:
5451       properties:
5452         id:
5453           type: integer
5454         type:
5455           type: integer
5456           description: >
5457             Notification type, following the `UserNotificationType` enum:
5458
5459             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
5460
5461             - `2` NEW_COMMENT_ON_MY_VIDEO
5462
5463             - `3` NEW_ABUSE_FOR_MODERATORS
5464
5465             - `4` BLACKLIST_ON_MY_VIDEO
5466
5467             - `5` UNBLACKLIST_ON_MY_VIDEO
5468
5469             - `6` MY_VIDEO_PUBLISHED
5470
5471             - `7` MY_VIDEO_IMPORT_SUCCESS
5472
5473             - `8` MY_VIDEO_IMPORT_ERROR
5474
5475             - `9` NEW_USER_REGISTRATION
5476
5477             - `10` NEW_FOLLOW
5478
5479             - `11` COMMENT_MENTION
5480
5481             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
5482
5483             - `13` NEW_INSTANCE_FOLLOWER
5484
5485             - `14` AUTO_INSTANCE_FOLLOWING
5486         read:
5487           type: boolean
5488         video:
5489           nullable: true
5490           allOf:
5491             - $ref: '#/components/schemas/VideoInfo'
5492             - type: object
5493               properties:
5494                 channel:
5495                   $ref: '#/components/schemas/ActorInfo'
5496         videoImport:
5497           nullable: true
5498           type: object
5499           properties:
5500             id:
5501               type: integer
5502             video:
5503               nullable: true
5504               $ref: '#/components/schemas/VideoInfo'
5505             torrentName:
5506               type: string
5507               nullable: true
5508             magnetUri:
5509               type: string
5510               format: uri
5511               nullable: true
5512             targetUri:
5513               type: string
5514               format: uri
5515               nullable: true
5516         comment:
5517           nullable: true
5518           type: object
5519           properties:
5520             id:
5521               type: integer
5522             threadId:
5523               type: integer
5524             video:
5525               $ref: '#/components/schemas/VideoInfo'
5526             account:
5527               $ref: '#/components/schemas/ActorInfo'
5528         videoAbuse:
5529           nullable: true
5530           type: object
5531           properties:
5532             id:
5533               type: integer
5534             video:
5535               allOf:
5536                 - $ref: '#/components/schemas/VideoInfo'
5537         videoBlacklist:
5538           nullable: true
5539           type: object
5540           properties:
5541             id:
5542               type: integer
5543             video:
5544               allOf:
5545                 - $ref: '#/components/schemas/VideoInfo'
5546         account:
5547           nullable: true
5548           allOf:
5549             - $ref: '#/components/schemas/ActorInfo'
5550         actorFollow:
5551           type: object
5552           nullable: true
5553           properties:
5554             id:
5555               type: integer
5556             follower:
5557               $ref: '#/components/schemas/ActorInfo'
5558             state:
5559               type: string
5560               enum:
5561                 - pending
5562                 - accepted
5563             following:
5564               type: object
5565               properties:
5566                 type:
5567                   type: string
5568                   enum:
5569                     - account
5570                     - channel
5571                     - instance
5572                 name:
5573                   type: string
5574                 displayName:
5575                   type: string
5576                 host:
5577                   type: string
5578                   format: hostname
5579         createdAt:
5580           type: string
5581           format: date-time
5582         updatedAt:
5583           type: string
5584           format: date-time
5585     NotificationListResponse:
5586       properties:
5587         total:
5588           type: integer
5589           example: 1
5590         data:
5591           type: array
5592           maxItems: 100
5593           items:
5594             $ref: '#/components/schemas/Notification'
5595     Plugin:
5596       properties:
5597         name:
5598           type: string
5599           example: peertube-plugin-auth-ldap
5600         type:
5601           type: integer
5602           description: >
5603             - `1`: PLUGIN
5604
5605             - `2`: THEME
5606           enum:
5607             - 1
5608             - 2
5609         latestVersion:
5610           type: string
5611           example: 0.0.3
5612         version:
5613           type: string
5614           example: 0.0.1
5615         enabled:
5616           type: boolean
5617         uninstalled:
5618           type: boolean
5619         peertubeEngine:
5620           type: string
5621           example: 2.2.0
5622         description:
5623           type: string
5624         homepage:
5625           type: string
5626           format: url
5627           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
5628         settings:
5629           type: object
5630           additionalProperties: true
5631         createdAt:
5632           type: string
5633           format: date-time
5634         updatedAt:
5635           type: string
5636           format: date-time
5637     PluginResponse:
5638       properties:
5639         total:
5640           type: integer
5641           example: 1
5642         data:
5643           type: array
5644           maxItems: 100
5645           items:
5646             $ref: '#/components/schemas/Plugin'
5647
5648     LiveVideoUpdate:
5649       properties:
5650         saveReplay:
5651           type: boolean
5652         permanentLive:
5653           description: User can stream multiple times in a permanent live
5654           type: boolean
5655
5656     LiveVideoResponse:
5657       properties:
5658         rtmpUrl:
5659           type: string
5660         streamKey:
5661           type: string
5662           description: RTMP stream key to use to stream into this live video
5663         saveReplay:
5664           type: boolean
5665         permanentLive:
5666           description: User can stream multiple times in a permanent live
5667           type: boolean
5668
5669   callbacks:
5670     searchIndex:
5671       'https://search.example.org/api/v1/search/videos':
5672         post:
5673           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
5674           responses:
5675             '200':
5676               description: successful operation
5677               content:
5678                 application/json:
5679                   schema:
5680                     $ref: '#/components/schemas/VideoListResponse'