support/doc/api/openapi.yaml

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