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