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