support/doc/api/openapi.yaml

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