support/doc/api/openapi.yaml

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