support/doc/api/openapi.yaml

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