support/doc/api/openapi.yaml

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