support/doc/api/openapi.yaml

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