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