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