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