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           description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
5391         label:
5392           type: string
5393
5394     AbuseStateSet:
5395       type: integer
5396       enum:
5397         - 1
5398         - 2
5399         - 3
5400       description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5401     AbuseStateConstant:
5402       properties:
5403         id:
5404           $ref: '#/components/schemas/AbuseStateSet'
5405         label:
5406           type: string
5407     AbusePredefinedReasons:
5408       type: array
5409       items:
5410         type: string
5411         enum:
5412         - violentOrAbusive
5413         - hatefulOrAbusive
5414         - spamOrMisleading
5415         - privacy
5416         - rights
5417         - serverRules
5418         - thumbnails
5419         - captions
5420       example: [spamOrMisleading]
5421
5422     VideoResolutionSet:
5423       type: integer
5424       description: |
5425         Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5426
5427         `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5428       example: 240
5429     VideoResolutionConstant:
5430       description: resolutions and their labels for the video
5431       properties:
5432         id:
5433           $ref: '#/components/schemas/VideoResolutionSet'
5434         label:
5435           type: string
5436           example: 240p
5437     VideoScheduledUpdate:
5438       properties:
5439         privacy:
5440           $ref: '#/components/schemas/VideoPrivacySet'
5441         updateAt:
5442           type: string
5443           format: date
5444           description: When to update the video
5445       required:
5446         - updateAt
5447     AccountSummary:
5448       properties:
5449         id:
5450           type: integer
5451         name:
5452           type: string
5453         displayName:
5454           type: string
5455         url:
5456           type: string
5457           format: url
5458         host:
5459           type: string
5460           format: hostname
5461         avatars:
5462           type: array
5463           items:
5464             $ref: '#/components/schemas/ActorImage'
5465     VideoChannelSummary:
5466       properties:
5467         id:
5468           $ref: '#/components/schemas/id'
5469         name:
5470           type: string
5471         displayName:
5472           type: string
5473         url:
5474           type: string
5475           format: url
5476         host:
5477           type: string
5478           format: hostname
5479         avatars:
5480           type: array
5481           items:
5482             $ref: '#/components/schemas/ActorImage'
5483     PlaylistElement:
5484       properties:
5485         position:
5486           type: integer
5487         startTimestamp:
5488           type: integer
5489           format: seconds
5490         stopTimestamp:
5491           type: integer
5492           format: seconds
5493         video:
5494           nullable: true
5495           allOf:
5496             - $ref: '#/components/schemas/Video'
5497     VideoFile:
5498       readOnly: true
5499       properties:
5500         magnetUri:
5501           type: string
5502           format: uri
5503           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5504           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5505         resolution:
5506           $ref: '#/components/schemas/VideoResolutionConstant'
5507         size:
5508           type: integer
5509           description: Video file size in bytes
5510         torrentUrl:
5511           type: string
5512           description: Direct URL of the torrent file
5513           format: url
5514         torrentDownloadUrl:
5515           type: string
5516           description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5517           format: url
5518         fileUrl:
5519           type: string
5520           description: Direct URL of the video
5521           format: url
5522         fileDownloadUrl:
5523           type: string
5524           description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5525           format: url
5526         fps:
5527           type: number
5528           description: Frames per second of the video file
5529         metadataUrl:
5530           type: string
5531           format: url
5532           description: URL dereferencing the output of ffprobe on the file
5533     VideoStreamingPlaylists:
5534       allOf:
5535         - type: object
5536           properties:
5537             id:
5538               $ref: '#/components/schemas/id'
5539             type:
5540               type: integer
5541               enum:
5542                 - 1
5543               description: |
5544                 Playlist type:
5545                 - `1`: HLS
5546         - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5547     VideoStreamingPlaylists-HLS:
5548       properties:
5549         playlistUrl:
5550           type: string
5551           format: url
5552         segmentsSha256Url:
5553           type: string
5554           format: url
5555         files:
5556           type: array
5557           description: |
5558             Video files associated to this playlist.
5559
5560             The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5561           items:
5562             $ref: '#/components/schemas/VideoFile'
5563         redundancies:
5564           type: array
5565           items:
5566             type: object
5567             properties:
5568               baseUrl:
5569                 type: string
5570                 format: url
5571     VideoInfo:
5572       properties:
5573         id:
5574           $ref: '#/components/schemas/Video/properties/id'
5575         uuid:
5576           $ref: '#/components/schemas/Video/properties/uuid'
5577         name:
5578           $ref: '#/components/schemas/Video/properties/name'
5579     Video:
5580       properties:
5581         id:
5582           description: object id for the video
5583           allOf:
5584             - $ref: '#/components/schemas/id'
5585         uuid:
5586           description: universal identifier for the video, that can be used across instances
5587           allOf:
5588             - $ref: '#/components/schemas/UUIDv4'
5589         shortUUID:
5590           allOf:
5591             - $ref: '#/components/schemas/shortUUID'
5592         isLive:
5593           type: boolean
5594         createdAt:
5595           type: string
5596           format: date-time
5597           example: 2017-10-01T10:52:46.396Z
5598           description: time at which the video object was first drafted
5599         publishedAt:
5600           type: string
5601           format: date-time
5602           example: 2018-10-01T10:52:46.396Z
5603           description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5604         updatedAt:
5605           type: string
5606           format: date-time
5607           example: 2021-05-04T08:01:01.502Z
5608           description: last time the video's metadata was modified
5609         originallyPublishedAt:
5610           type: string
5611           format: date-time
5612           example: 2010-10-01T10:52:46.396Z
5613           description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5614         category:
5615           allOf:
5616             - $ref: '#/components/schemas/VideoConstantNumber-Category'
5617           description: category in which the video is classified
5618         licence:
5619           allOf:
5620             - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5621           description: licence under which the video is distributed
5622         language:
5623           allOf:
5624             - $ref: '#/components/schemas/VideoConstantString-Language'
5625           description: main language used in the video
5626         privacy:
5627           allOf:
5628             - $ref: '#/components/schemas/VideoPrivacyConstant'
5629           description: privacy policy used to distribute the video
5630         description:
5631           type: string
5632           example: |
5633             **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5634             **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5635           minLength: 3
5636           maxLength: 250
5637           description: |
5638             truncated description of the video, written in Markdown.
5639             Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5640         duration:
5641           type: integer
5642           example: 1419
5643           format: seconds
5644           description: duration of the video in seconds
5645         isLocal:
5646           type: boolean
5647         name:
5648           type: string
5649           description: title of the video
5650           example: What is PeerTube?
5651           minLength: 3
5652           maxLength: 120
5653         thumbnailPath:
5654           type: string
5655           example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5656         previewPath:
5657           type: string
5658           example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5659         embedPath:
5660           type: string
5661           example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5662         views:
5663           type: integer
5664           example: 1337
5665         likes:
5666           type: integer
5667           example: 42
5668         dislikes:
5669           type: integer
5670           example: 7
5671         nsfw:
5672           type: boolean
5673         waitTranscoding:
5674           type: boolean
5675           nullable: true
5676         state:
5677           allOf:
5678             - $ref: '#/components/schemas/VideoStateConstant'
5679           description: represents the internal state of the video processing within the PeerTube instance
5680         scheduledUpdate:
5681           nullable: true
5682           allOf:
5683             - $ref: '#/components/schemas/VideoScheduledUpdate'
5684         blacklisted:
5685           nullable: true
5686           type: boolean
5687         blacklistedReason:
5688           nullable: true
5689           type: string
5690         account:
5691           $ref: '#/components/schemas/AccountSummary'
5692         channel:
5693           $ref: '#/components/schemas/VideoChannelSummary'
5694         userHistory:
5695           nullable: true
5696           type: object
5697           properties:
5698             currentTime:
5699               type: integer
5700     VideoDetails:
5701       allOf:
5702         - $ref: '#/components/schemas/Video'
5703         - type: object
5704           properties:
5705             viewers:
5706               type: integer
5707               description: If the video is a live, you have the amount of current viewers
5708             descriptionPath:
5709               type: string
5710               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5711               description: path at which to get the full description of maximum `10000` characters
5712             support:
5713               type: string
5714               description: A text tell the audience how to support the video creator
5715               example: Please support our work on https://soutenir.framasoft.org/en/ <3
5716               minLength: 3
5717               maxLength: 1000
5718             channel:
5719               $ref: '#/components/schemas/VideoChannel'
5720             account:
5721               $ref: '#/components/schemas/Account'
5722             tags:
5723               example: [flowers, gardening]
5724               type: array
5725               minItems: 1
5726               maxItems: 5
5727               items:
5728                 type: string
5729                 minLength: 2
5730                 maxLength: 30
5731             commentsEnabled:
5732               type: boolean
5733             downloadEnabled:
5734               type: boolean
5735             trackerUrls:
5736               type: array
5737               items:
5738                 type: string
5739                 format: url
5740               example:
5741                 - https://peertube2.cpy.re/tracker/announce
5742                 - wss://peertube2.cpy.re/tracker/socket
5743             files:
5744               type: array
5745               items:
5746                 $ref: '#/components/schemas/VideoFile'
5747               description: |
5748                 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5749
5750                 - field will be empty
5751                 - video files will be found in `streamingPlaylists[].files` field
5752             streamingPlaylists:
5753               type: array
5754               items:
5755                 $ref: '#/components/schemas/VideoStreamingPlaylists'
5756               description: |
5757                 HLS playlists/manifest files. If HLS is disabled on the server:
5758
5759                 - field will be empty
5760                 - video files will be found in `files` field
5761     FileRedundancyInformation:
5762       properties:
5763         id:
5764           $ref: '#/components/schemas/id'
5765         fileUrl:
5766           type: string
5767           format: url
5768         strategy:
5769           type: string
5770           enum:
5771             - manual
5772             - most-views
5773             - trending
5774             - recently-added
5775         size:
5776           type: integer
5777         createdAt:
5778           type: string
5779           format: date-time
5780         updatedAt:
5781           type: string
5782           format: date-time
5783         expiresOn:
5784           type: string
5785           format: date-time
5786     VideoRedundancy:
5787       properties:
5788         id:
5789           $ref: '#/components/schemas/id'
5790         name:
5791           type: string
5792         url:
5793           type: string
5794           format: url
5795         uuid:
5796           $ref: '#/components/schemas/UUIDv4'
5797         redundancies:
5798           type: object
5799           properties:
5800             files:
5801               type: array
5802               items:
5803                 $ref: '#/components/schemas/FileRedundancyInformation'
5804             streamingPlaylists:
5805               type: array
5806               items:
5807                 $ref: '#/components/schemas/FileRedundancyInformation'
5808     VideoImportStateConstant:
5809       properties:
5810         id:
5811           type: integer
5812           enum:
5813             - 1
5814             - 2
5815             - 3
5816           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5817         label:
5818           type: string
5819           example: Pending
5820     VideoCreateImport:
5821       allOf:
5822         - type: object
5823           additionalProperties: false
5824           oneOf:
5825             - properties:
5826                 targetUrl:
5827                   $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5828               required: [targetUrl]
5829             - properties:
5830                 magnetUri:
5831                   $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5832               required: [magnetUri]
5833             - properties:
5834                 torrentfile:
5835                   $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5836               required: [torrentfile]
5837         - $ref: '#/components/schemas/VideoUploadRequestCommon'
5838       required:
5839         - channelId
5840         - name
5841     VideoImport:
5842       properties:
5843         id:
5844           readOnly: true
5845           allOf:
5846             - $ref: '#/components/schemas/id'
5847         targetUrl:
5848           type: string
5849           format: url
5850           description: remote URL where to find the import's source video
5851           example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5852         magnetUri:
5853           type: string
5854           format: uri
5855           description: magnet URI allowing to resolve the import's source video
5856           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5857         torrentfile:
5858           writeOnly: true
5859           type: string
5860           format: binary
5861           description: Torrent file containing only the video file
5862         torrentName:
5863           readOnly: true
5864           type: string
5865         state:
5866           readOnly: true
5867           allOf:
5868             - $ref: '#/components/schemas/VideoImportStateConstant'
5869         error:
5870           readOnly: true
5871           type: string
5872         createdAt:
5873           readOnly: true
5874           type: string
5875           format: date-time
5876         updatedAt:
5877           readOnly: true
5878           type: string
5879           format: date-time
5880         video:
5881           readOnly: true
5882           nullable: true
5883           allOf:
5884             - $ref: '#/components/schemas/Video'
5885     VideoImportsList:
5886       properties:
5887         total:
5888           type: integer
5889           example: 1
5890         data:
5891           type: array
5892           maxItems: 100
5893           items:
5894             $ref: '#/components/schemas/VideoImport'
5895     Abuse:
5896       properties:
5897         id:
5898           $ref: '#/components/schemas/id'
5899         reason:
5900           type: string
5901           example: The video is a spam
5902           minLength: 2
5903           maxLength: 3000
5904         predefinedReasons:
5905           $ref: '#/components/schemas/AbusePredefinedReasons'
5906         reporterAccount:
5907           $ref: '#/components/schemas/Account'
5908         state:
5909           $ref: '#/components/schemas/AbuseStateConstant'
5910         moderationComment:
5911           type: string
5912           example: Decided to ban the server since it spams us regularly
5913           minLength: 2
5914           maxLength: 3000
5915         video:
5916           $ref: '#/components/schemas/VideoInfo'
5917         createdAt:
5918           type: string
5919           format: date-time
5920     AbuseMessage:
5921       properties:
5922         id:
5923           $ref: '#/components/schemas/id'
5924         message:
5925           type: string
5926           minLength: 2
5927           maxLength: 3000
5928         byModerator:
5929           type: boolean
5930         createdAt:
5931           type: string
5932           format: date-time
5933         account:
5934           $ref: '#/components/schemas/AccountSummary'
5935     VideoBlacklist:
5936       properties:
5937         id:
5938           $ref: '#/components/schemas/id'
5939         videoId:
5940           $ref: '#/components/schemas/Video/properties/id'
5941         createdAt:
5942           type: string
5943           format: date-time
5944         updatedAt:
5945           type: string
5946           format: date-time
5947         name:
5948           type: string
5949           minLength: 3
5950           maxLength: 120
5951         uuid:
5952           $ref: '#/components/schemas/UUIDv4'
5953         description:
5954           type: string
5955           minLength: 3
5956           maxLength: 10000
5957         duration:
5958           type: integer
5959         views:
5960           type: integer
5961         likes:
5962           type: integer
5963         dislikes:
5964           type: integer
5965         nsfw:
5966           type: boolean
5967     VideoPlaylist:
5968       properties:
5969         id:
5970           $ref: '#/components/schemas/id'
5971         uuid:
5972           $ref: '#/components/schemas/UUIDv4'
5973         shortUUID:
5974           allOf:
5975             - $ref: '#/components/schemas/shortUUID'
5976         createdAt:
5977           type: string
5978           format: date-time
5979         updatedAt:
5980           type: string
5981           format: date-time
5982         description:
5983           type: string
5984           minLength: 3
5985           maxLength: 1000
5986         displayName:
5987           type: string
5988           minLength: 1
5989           maxLength: 120
5990         isLocal:
5991           type: boolean
5992         videoLength:
5993           type: integer
5994           minimum: 0
5995         thumbnailPath:
5996           type: string
5997         privacy:
5998           $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5999         type:
6000           $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6001         ownerAccount:
6002           $ref: '#/components/schemas/AccountSummary'
6003         videoChannel:
6004           $ref: '#/components/schemas/VideoChannelSummary'
6005     VideoComment:
6006       properties:
6007         id:
6008           $ref: '#/components/schemas/id'
6009         url:
6010           type: string
6011           format: url
6012         text:
6013           type: string
6014           format: html
6015           description: Text of the comment
6016           minLength: 1
6017           example: This video is wonderful!
6018         threadId:
6019           $ref: '#/components/schemas/id'
6020         inReplyToCommentId:
6021           nullable: true
6022           allOf:
6023             - $ref: '#/components/schemas/id'
6024         videoId:
6025           $ref: '#/components/schemas/Video/properties/id'
6026         createdAt:
6027           type: string
6028           format: date-time
6029         updatedAt:
6030           type: string
6031           format: date-time
6032         deletedAt:
6033           nullable: true
6034           type: string
6035           format: date-time
6036           default: null
6037         isDeleted:
6038           type: boolean
6039           default: false
6040         totalRepliesFromVideoAuthor:
6041           type: integer
6042           minimum: 0
6043         totalReplies:
6044           type: integer
6045           minimum: 0
6046         account:
6047           $ref: '#/components/schemas/Account'
6048     VideoCommentThreadTree:
6049       properties:
6050         comment:
6051           $ref: '#/components/schemas/VideoComment'
6052         children:
6053           type: array
6054           items:
6055             $ref: '#/components/schemas/VideoCommentThreadTree'
6056     VideoCaption:
6057       properties:
6058         language:
6059           $ref: '#/components/schemas/VideoConstantString-Language'
6060         captionPath:
6061           type: string
6062     ActorImage:
6063       properties:
6064         path:
6065           type: string
6066         width:
6067           type: integer
6068         createdAt:
6069           type: string
6070           format: date-time
6071         updatedAt:
6072           type: string
6073           format: date-time
6074     ActorInfo:
6075       properties:
6076         id:
6077           $ref: '#/components/schemas/id'
6078         name:
6079           type: string
6080         displayName:
6081           type: string
6082         host:
6083           type: string
6084           format: hostname
6085         avatars:
6086           type: array
6087           items:
6088             $ref: '#/components/schemas/ActorImage'
6089     Actor:
6090       properties:
6091         id:
6092           $ref: '#/components/schemas/id'
6093         url:
6094           type: string
6095           format: url
6096         name:
6097           description: immutable name of the actor, used to find or mention it
6098           allOf:
6099             - $ref: '#/components/schemas/username'
6100         host:
6101           type: string
6102           format: hostname
6103           description: server on which the actor is resident
6104         hostRedundancyAllowed:
6105           type: boolean
6106           description: whether this actor's host allows redundancy of its videos
6107         followingCount:
6108           type: integer
6109           minimum: 0
6110           description: number of actors subscribed to by this actor, as seen by this instance
6111         followersCount:
6112           type: integer
6113           minimum: 0
6114           description: number of followers of this actor, as seen by this instance
6115         createdAt:
6116           type: string
6117           format: date-time
6118         updatedAt:
6119           type: string
6120           format: date-time
6121     Account:
6122       allOf:
6123         - $ref: '#/components/schemas/Actor'
6124         - properties:
6125             userId:
6126               description: object id for the user tied to this account
6127               allOf:
6128                 - $ref: '#/components/schemas/User/properties/id'
6129             displayName:
6130               type: string
6131               description: editable name of the account, displayed in its representations
6132               minLength: 3
6133               maxLength: 120
6134             description:
6135               type: string
6136               description: text or bio displayed on the account's profile
6137     UserViewingVideo:
6138       required:
6139         - currentTime
6140       properties:
6141         currentTime:
6142           type: integer
6143           format: seconds
6144           description: timestamp within the video, in seconds
6145           example: 5
6146         viewEvent:
6147           type: string
6148           enum:
6149             - seek
6150           description: >
6151             Event since last viewing call:
6152              * `seek` - If the user seeked the video
6153
6154     VideoStatsOverall:
6155       properties:
6156         averageWatchTime:
6157           type: number
6158         totalWatchTime:
6159           type: number
6160         viewersPeak:
6161           type: number
6162         viewersPeakDate:
6163           type: string
6164           format: date-time
6165         views:
6166           type: number
6167         likes:
6168           type: number
6169         dislikes:
6170           type: number
6171         comments:
6172           type: number
6173         countries:
6174           type: array
6175           items:
6176             type: object
6177             properties:
6178               isoCode:
6179                 type: string
6180               viewers:
6181                 type: number
6182
6183     VideoStatsRetention:
6184       properties:
6185         data:
6186           type: array
6187           items:
6188             type: object
6189             properties:
6190               second:
6191                 type: number
6192               retentionPercent:
6193                 type: number
6194
6195     VideoStatsTimeserie:
6196       properties:
6197         data:
6198           type: array
6199           items:
6200             type: object
6201             properties:
6202               date:
6203                 type: string
6204               value:
6205                 type: number
6206
6207     ServerConfig:
6208       properties:
6209         instance:
6210           type: object
6211           properties:
6212             name:
6213               type: string
6214             shortDescription:
6215               type: string
6216             defaultClientRoute:
6217               type: string
6218             isNSFW:
6219               type: boolean
6220             defaultNSFWPolicy:
6221               type: string
6222             customizations:
6223               type: object
6224               properties:
6225                 javascript:
6226                   type: string
6227                 css:
6228                   type: string
6229         search:
6230           type: object
6231           properties:
6232             remoteUri:
6233               type: object
6234               properties:
6235                 users:
6236                   type: boolean
6237                 anonymous:
6238                   type: boolean
6239         plugin:
6240           type: object
6241           properties:
6242             registered:
6243               type: array
6244               items:
6245                 type: string
6246         theme:
6247           type: object
6248           properties:
6249             registered:
6250               type: array
6251               items:
6252                 type: string
6253         email:
6254           type: object
6255           properties:
6256             enabled:
6257               type: boolean
6258         contactForm:
6259           type: object
6260           properties:
6261             enabled:
6262               type: boolean
6263         serverVersion:
6264           type: string
6265         serverCommit:
6266           type: string
6267         signup:
6268           type: object
6269           properties:
6270             allowed:
6271               type: boolean
6272             allowedForCurrentIP:
6273               type: boolean
6274             requiresEmailVerification:
6275               type: boolean
6276         transcoding:
6277           type: object
6278           properties:
6279             hls:
6280               type: object
6281               properties:
6282                 enabled:
6283                   type: boolean
6284             webtorrent:
6285               type: object
6286               properties:
6287                 enabled:
6288                   type: boolean
6289             enabledResolutions:
6290               type: array
6291               items:
6292                 $ref: '#/components/schemas/VideoResolutionSet'
6293         import:
6294           type: object
6295           properties:
6296             videos:
6297               type: object
6298               properties:
6299                 http:
6300                   type: object
6301                   properties:
6302                     enabled:
6303                       type: boolean
6304                 torrent:
6305                   type: object
6306                   properties:
6307                     enabled:
6308                       type: boolean
6309         autoBlacklist:
6310           type: object
6311           properties:
6312             videos:
6313               type: object
6314               properties:
6315                 ofUsers:
6316                   type: object
6317                   properties:
6318                     enabled:
6319                       type: boolean
6320         avatar:
6321           type: object
6322           properties:
6323             file:
6324               type: object
6325               properties:
6326                 size:
6327                   type: object
6328                   properties:
6329                     max:
6330                       type: integer
6331             extensions:
6332               type: array
6333               items:
6334                 type: string
6335         video:
6336           type: object
6337           properties:
6338             image:
6339               type: object
6340               properties:
6341                 extensions:
6342                   type: array
6343                   items:
6344                     type: string
6345                 size:
6346                   type: object
6347                   properties:
6348                     max:
6349                       type: integer
6350             file:
6351               type: object
6352               properties:
6353                 extensions:
6354                   type: array
6355                   items:
6356                     type: string
6357         videoCaption:
6358           type: object
6359           properties:
6360             file:
6361               type: object
6362               properties:
6363                 size:
6364                   type: object
6365                   properties:
6366                     max:
6367                       type: integer
6368                 extensions:
6369                   type: array
6370                   items:
6371                     type: string
6372         user:
6373           type: object
6374           properties:
6375             videoQuota:
6376               type: integer
6377               example: 16810141515
6378             videoQuotaDaily:
6379               type: integer
6380               example: 1681014151
6381         trending:
6382           type: object
6383           properties:
6384             videos:
6385               type: object
6386               properties:
6387                 intervalDays:
6388                   type: integer
6389         tracker:
6390           type: object
6391           properties:
6392             enabled:
6393               type: boolean
6394         followings:
6395           type: object
6396           properties:
6397             instance:
6398               type: object
6399               properties:
6400                 autoFollowIndex:
6401                   type: object
6402                   properties:
6403                     indexUrl:
6404                       type: string
6405                       format: url
6406         homepage:
6407           type: object
6408           properties:
6409             enabled:
6410               type: boolean
6411
6412     ServerConfigAbout:
6413       properties:
6414         instance:
6415           type: object
6416           properties:
6417             name:
6418               type: string
6419             shortDescription:
6420               type: string
6421             description:
6422               type: string
6423             terms:
6424               type: string
6425     ServerConfigCustom:
6426       properties:
6427         instance:
6428           type: object
6429           properties:
6430             name:
6431               type: string
6432             shortDescription:
6433               type: string
6434             description:
6435               type: string
6436             terms:
6437               type: string
6438             defaultClientRoute:
6439               type: string
6440             isNSFW:
6441               type: boolean
6442             defaultNSFWPolicy:
6443               type: string
6444             customizations:
6445               type: object
6446               properties:
6447                 javascript:
6448                   type: string
6449                 css:
6450                   type: string
6451         theme:
6452           type: object
6453           properties:
6454             default:
6455               type: string
6456         services:
6457           type: object
6458           properties:
6459             twitter:
6460               type: object
6461               properties:
6462                 username:
6463                   type: string
6464                 whitelisted:
6465                   type: boolean
6466         cache:
6467           type: object
6468           properties:
6469             previews:
6470               type: object
6471               properties:
6472                 size:
6473                   type: integer
6474             captions:
6475               type: object
6476               properties:
6477                 size:
6478                   type: integer
6479         signup:
6480           type: object
6481           properties:
6482             enabled:
6483               type: boolean
6484             limit:
6485               type: integer
6486             requiresEmailVerification:
6487               type: boolean
6488         admin:
6489           type: object
6490           properties:
6491             email:
6492               type: string
6493               format: email
6494         contactForm:
6495           type: object
6496           properties:
6497             enabled:
6498               type: boolean
6499         user:
6500           type: object
6501           description: Settings that apply to new users, if registration is enabled
6502           properties:
6503             videoQuota:
6504               type: integer
6505               example: 16810141515
6506             videoQuotaDaily:
6507               type: integer
6508               example: 1681014151
6509         transcoding:
6510           type: object
6511           description: Settings pertaining to transcoding jobs
6512           properties:
6513             enabled:
6514               type: boolean
6515             allowAdditionalExtensions:
6516               type: boolean
6517               description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6518             allowAudioFiles:
6519               type: boolean
6520               description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6521             threads:
6522               type: integer
6523               description: Amount of threads used by ffmpeg for 1 transcoding job
6524             concurrency:
6525               type: number
6526               description: Amount of transcoding jobs to execute in parallel
6527             profile:
6528               type: string
6529               enum:
6530                 - default
6531               description: |
6532                 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6533             resolutions:
6534               type: object
6535               description: Resolutions to transcode _new videos_ to
6536               properties:
6537                 0p:
6538                   type: boolean
6539                 144p:
6540                   type: boolean
6541                 240p:
6542                   type: boolean
6543                 360p:
6544                   type: boolean
6545                 480p:
6546                   type: boolean
6547                 720p:
6548                   type: boolean
6549                 1080p:
6550                   type: boolean
6551                 1440p:
6552                   type: boolean
6553                 2160p:
6554                   type: boolean
6555             webtorrent:
6556               type: object
6557               description: WebTorrent-specific settings
6558               properties:
6559                 enabled:
6560                   type: boolean
6561             hls:
6562               type: object
6563               description: HLS-specific settings
6564               properties:
6565                 enabled:
6566                   type: boolean
6567         import:
6568           type: object
6569           properties:
6570             videos:
6571               type: object
6572               properties:
6573                 http:
6574                   type: object
6575                   properties:
6576                     enabled:
6577                       type: boolean
6578                 torrent:
6579                   type: object
6580                   properties:
6581                     enabled:
6582                       type: boolean
6583         autoBlacklist:
6584           type: object
6585           properties:
6586             videos:
6587               type: object
6588               properties:
6589                 ofUsers:
6590                   type: object
6591                   properties:
6592                     enabled:
6593                       type: boolean
6594         followers:
6595           type: object
6596           properties:
6597             instance:
6598               type: object
6599               properties:
6600                 enabled:
6601                   type: boolean
6602                 manualApproval:
6603                   type: boolean
6604
6605     CustomHomepage:
6606       properties:
6607         content:
6608           type: string
6609
6610     Follow:
6611       properties:
6612         id:
6613           $ref: '#/components/schemas/id'
6614         follower:
6615           $ref: '#/components/schemas/Actor'
6616         following:
6617           $ref: '#/components/schemas/Actor'
6618         score:
6619           type: number
6620           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6621         state:
6622           type: string
6623           enum:
6624             - pending
6625             - accepted
6626         createdAt:
6627           type: string
6628           format: date-time
6629         updatedAt:
6630           type: string
6631           format: date-time
6632
6633     PredefinedAbuseReasons:
6634       description: Reason categories that help triage reports
6635       type: array
6636       maxItems: 8
6637       items:
6638         type: string
6639         enum:
6640         - violentOrAbusive
6641         - hatefulOrAbusive
6642         - spamOrMisleading
6643         - privacy
6644         - rights
6645         - serverRules
6646         - thumbnails
6647         - captions
6648
6649     Job:
6650       properties:
6651         id:
6652           $ref: '#/components/schemas/id'
6653         state:
6654           type: string
6655           enum:
6656             - active
6657             - completed
6658             - failed
6659             - waiting
6660             - delayed
6661         type:
6662           type: string
6663           enum:
6664             - activitypub-http-unicast
6665             - activitypub-http-broadcast
6666             - activitypub-http-fetcher
6667             - activitypub-follow
6668             - video-file-import
6669             - video-transcoding
6670             - email
6671             - video-import
6672             - videos-views-stats
6673             - activitypub-refresher
6674             - video-redundancy
6675         data:
6676           type: object
6677           additionalProperties: true
6678         error:
6679           type: object
6680           additionalProperties: true
6681         createdAt:
6682           type: string
6683           format: date-time
6684         finishedOn:
6685           type: string
6686           format: date-time
6687         processedOn:
6688           type: string
6689           format: date-time
6690     AddUserResponse:
6691       properties:
6692         user:
6693           type: object
6694           properties:
6695             id:
6696               $ref: '#/components/schemas/id'
6697             account:
6698               type: object
6699               properties:
6700                 id:
6701                   $ref: '#/components/schemas/id'
6702     VideoUploadRequestCommon:
6703       properties:
6704         name:
6705           description: Video name
6706           type: string
6707           example: What is PeerTube?
6708           minLength: 3
6709           maxLength: 120
6710         channelId:
6711           description: Channel id that will contain this video
6712           type: integer
6713           example: 3
6714           minimum: 1
6715         privacy:
6716           $ref: '#/components/schemas/VideoPrivacySet'
6717         category:
6718           $ref: '#/components/schemas/VideoCategorySet'
6719         licence:
6720           $ref: '#/components/schemas/VideoLicenceSet'
6721         language:
6722           $ref: '#/components/schemas/VideoLanguageSet'
6723         description:
6724           description: Video description
6725           type: string
6726           example: |
6727             **[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)**
6728         waitTranscoding:
6729           description: Whether or not we wait transcoding before publish the video
6730           type: boolean
6731         support:
6732           description: A text tell the audience how to support the video creator
6733           example: Please support our work on https://soutenir.framasoft.org/en/ <3
6734           type: string
6735         nsfw:
6736           description: Whether or not this video contains sensitive content
6737           type: boolean
6738         tags:
6739           description: Video tags (maximum 5 tags each between 2 and 30 characters)
6740           type: array
6741           minItems: 1
6742           maxItems: 5
6743           uniqueItems: true
6744           example:
6745             - framasoft
6746             - peertube
6747           items:
6748             type: string
6749             minLength: 2
6750             maxLength: 30
6751         commentsEnabled:
6752           description: Enable or disable comments for this video
6753           type: boolean
6754         downloadEnabled:
6755           description: Enable or disable downloading for this video
6756           type: boolean
6757         originallyPublishedAt:
6758           description: Date when the content was originally published
6759           type: string
6760           format: date-time
6761         scheduleUpdate:
6762           $ref: '#/components/schemas/VideoScheduledUpdate'
6763         thumbnailfile:
6764           description: Video thumbnail file
6765           type: string
6766           format: binary
6767         previewfile:
6768           description: Video preview file
6769           type: string
6770           format: binary
6771       required:
6772         - channelId
6773         - name
6774     VideoUploadRequestLegacy:
6775       allOf:
6776         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6777         - type: object
6778           required:
6779             - videofile
6780           properties:
6781             videofile:
6782               description: Video file
6783               type: string
6784               format: binary
6785     VideoUploadRequestResumable:
6786       allOf:
6787         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6788         - type: object
6789           required:
6790             - filename
6791           properties:
6792             filename:
6793               description: Video filename including extension
6794               type: string
6795               format: filename
6796               example: what_is_peertube.mp4
6797             thumbnailfile:
6798               description: Video thumbnail file
6799               type: string
6800               format: binary
6801             previewfile:
6802               description: Video preview file
6803               type: string
6804               format: binary
6805     VideoUploadResponse:
6806       properties:
6807         video:
6808           type: object
6809           properties:
6810             id:
6811               $ref: '#/components/schemas/Video/properties/id'
6812             uuid:
6813               $ref: '#/components/schemas/Video/properties/uuid'
6814             shortUUID:
6815               $ref: '#/components/schemas/Video/properties/shortUUID'
6816     CommentThreadResponse:
6817       properties:
6818         total:
6819           type: integer
6820           example: 1
6821         data:
6822           type: array
6823           maxItems: 100
6824           items:
6825             $ref: '#/components/schemas/VideoComment'
6826     CommentThreadPostResponse:
6827       properties:
6828         comment:
6829           $ref: '#/components/schemas/VideoComment'
6830     VideoListResponse:
6831       properties:
6832         total:
6833           type: integer
6834           example: 1
6835         data:
6836           type: array
6837           maxItems: 100
6838           items:
6839             $ref: '#/components/schemas/Video'
6840     User:
6841       properties:
6842         account:
6843           $ref: '#/components/schemas/Account'
6844         autoPlayNextVideo:
6845           type: boolean
6846           description: Automatically start playing the upcoming video after the currently playing video
6847         autoPlayNextVideoPlaylist:
6848           type: boolean
6849           description: Automatically start playing the video on the playlist after the currently playing video
6850         autoPlayVideo:
6851           type: boolean
6852           description: Automatically start playing the video on the watch page
6853         blocked:
6854           type: boolean
6855         blockedReason:
6856           type: string
6857         createdAt:
6858           type: string
6859         email:
6860           type: string
6861           format: email
6862           description: The user email
6863         emailVerified:
6864           type: boolean
6865           description: Has the user confirmed their email address?
6866         id:
6867           allOf:
6868             - $ref: '#/components/schemas/id'
6869           readOnly: true
6870         pluginAuth:
6871           type: string
6872           description: Auth plugin to use to authenticate the user
6873         lastLoginDate:
6874           type: string
6875           format: date-time
6876         noInstanceConfigWarningModal:
6877           type: boolean
6878         noAccountSetupWarningModal:
6879           type: boolean
6880         noWelcomeModal:
6881           type: boolean
6882         nsfwPolicy:
6883           $ref: '#/components/schemas/NSFWPolicy'
6884         role:
6885           $ref: '#/components/schemas/UserRole'
6886         roleLabel:
6887           type: string
6888           enum:
6889             - User
6890             - Moderator
6891             - Administrator
6892         theme:
6893           type: string
6894           description: Theme enabled by this user
6895         username:
6896           $ref: '#/components/schemas/username'
6897         videoChannels:
6898           type: array
6899           items:
6900             $ref: '#/components/schemas/VideoChannel'
6901         videoQuota:
6902           type: integer
6903           description: The user video quota in bytes
6904           example: -1
6905         videoQuotaDaily:
6906           type: integer
6907           description: The user daily video quota in bytes
6908           example: -1
6909         p2pEnabled:
6910           type: boolean
6911           description: Enable P2P in the player
6912     UserWithStats:
6913       allOf:
6914         - $ref: '#/components/schemas/User'
6915         - properties:
6916             # optionally present fields: they require WITH_STATS scope
6917             videosCount:
6918               type: integer
6919               description: Count of videos published
6920             abusesCount:
6921               type: integer
6922               description: Count of reports/abuses of which the user is a target
6923             abusesAcceptedCount:
6924               type: integer
6925               description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6926             abusesCreatedCount:
6927               type: integer
6928               description: Count of reports/abuses created by the user
6929             videoCommentsCount:
6930               type: integer
6931               description: Count of comments published
6932     AddUser:
6933       properties:
6934         username:
6935           $ref: '#/components/schemas/username'
6936         password:
6937           $ref: '#/components/schemas/password'
6938         email:
6939           type: string
6940           format: email
6941           description: The user email
6942         videoQuota:
6943           type: integer
6944           description: The user video quota in bytes
6945           example: -1
6946         videoQuotaDaily:
6947           type: integer
6948           description: The user daily video quota in bytes
6949           example: -1
6950         channelName:
6951           $ref: '#/components/schemas/usernameChannel'
6952         role:
6953           $ref: '#/components/schemas/UserRole'
6954         adminFlags:
6955           $ref: '#/components/schemas/UserAdminFlags'
6956       required:
6957         - username
6958         - password
6959         - email
6960         - videoQuota
6961         - videoQuotaDaily
6962         - role
6963     UpdateUser:
6964       properties:
6965         email:
6966           description: The updated email of the user
6967           allOf:
6968             - $ref: '#/components/schemas/User/properties/email'
6969         emailVerified:
6970           type: boolean
6971           description: Set the email as verified
6972         videoQuota:
6973           type: integer
6974           description: The updated video quota of the user in bytes
6975         videoQuotaDaily:
6976           type: integer
6977           description: The updated daily video quota of the user in bytes
6978         pluginAuth:
6979           type: string
6980           nullable: true
6981           description: The auth plugin to use to authenticate the user
6982           example: 'peertube-plugin-auth-saml2'
6983         role:
6984           $ref: '#/components/schemas/UserRole'
6985         adminFlags:
6986           $ref: '#/components/schemas/UserAdminFlags'
6987         password:
6988           $ref: '#/components/schemas/password'
6989     UpdateMe:
6990       # see shared/models/users/user-update-me.model.ts:
6991       properties:
6992         password:
6993           $ref: '#/components/schemas/password'
6994         currentPassword:
6995           $ref: '#/components/schemas/password'
6996         email:
6997           description: new email used for login and service communications
6998           allOf:
6999             - $ref: '#/components/schemas/User/properties/email'
7000         displayName:
7001           type: string
7002           description: new name of the user in its representations
7003           minLength: 3
7004           maxLength: 120
7005         displayNSFW:
7006           type: string
7007           description: new NSFW display policy
7008           enum:
7009             - 'true'
7010             - 'false'
7011             - both
7012         p2pEnabled:
7013           type: boolean
7014           description: whether to enable P2P in the player or not
7015         autoPlayVideo:
7016           type: boolean
7017           description: new preference regarding playing videos automatically
7018         autoPlayNextVideo:
7019           type: boolean
7020           description: new preference regarding playing following videos automatically
7021         autoPlayNextVideoPlaylist:
7022           type: boolean
7023           description: new preference regarding playing following playlist videos automatically
7024         videosHistoryEnabled:
7025           type: boolean
7026           description: whether to keep track of watched history or not
7027         videoLanguages:
7028           type: array
7029           items:
7030             type: string
7031           description: list of languages to filter videos down to
7032         theme:
7033           type: string
7034         noInstanceConfigWarningModal:
7035           type: boolean
7036         noAccountSetupWarningModal:
7037           type: boolean
7038         noWelcomeModal:
7039           type: boolean
7040     GetMeVideoRating:
7041       properties:
7042         id:
7043           $ref: '#/components/schemas/id'
7044         rating:
7045           type: string
7046           enum:
7047             - like
7048             - dislike
7049             - none
7050           description: Rating of the video
7051       required:
7052         - id
7053         - rating
7054     VideoRating:
7055       properties:
7056         video:
7057           $ref: '#/components/schemas/Video'
7058         rating:
7059           type: string
7060           enum:
7061             - like
7062             - dislike
7063             - none
7064           description: Rating of the video
7065       required:
7066         - video
7067         - rating
7068     RegisterUser:
7069       properties:
7070         username:
7071           description: immutable name of the user, used to find or mention its actor
7072           allOf:
7073             - $ref: '#/components/schemas/username'
7074         password:
7075           $ref: '#/components/schemas/password'
7076         email:
7077           type: string
7078           format: email
7079           description: email of the user, used for login or service communications
7080         displayName:
7081           type: string
7082           description: editable name of the user, displayed in its representations
7083           minLength: 1
7084           maxLength: 120
7085         channel:
7086           type: object
7087           description: channel base information used to create the first channel of the user
7088           properties:
7089             name:
7090               $ref: '#/components/schemas/usernameChannel'
7091             displayName:
7092               type: string
7093       required:
7094         - username
7095         - password
7096         - email
7097
7098     OAuthClient:
7099       properties:
7100         client_id:
7101           type: string
7102           pattern: /^[a-z0-9]$/
7103           maxLength: 32
7104           minLength: 32
7105           example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7106         client_secret:
7107           type: string
7108           pattern: /^[a-zA-Z0-9]$/
7109           maxLength: 32
7110           minLength: 32
7111           example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7112     OAuthToken-password:
7113       allOf:
7114         - $ref: '#/components/schemas/OAuthClient'
7115         - type: object
7116           properties:
7117             grant_type:
7118               type: string
7119               enum:
7120                 - password
7121                 - refresh_token
7122               default: password
7123             username:
7124               $ref: '#/components/schemas/User/properties/username'
7125             password:
7126               $ref: '#/components/schemas/password'
7127       required:
7128         - client_id
7129         - client_secret
7130         - grant_type
7131         - username
7132         - password
7133     OAuthToken-refresh_token:
7134       allOf:
7135         - $ref: '#/components/schemas/OAuthClient'
7136         - type: object
7137           properties:
7138             grant_type:
7139               type: string
7140               enum:
7141                 - password
7142                 - refresh_token
7143               default: password
7144             refresh_token:
7145               type: string
7146               example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7147       required:
7148         - client_id
7149         - client_secret
7150         - grant_type
7151         - refresh_token
7152
7153     VideoChannel:
7154       allOf:
7155         - $ref: '#/components/schemas/Actor'
7156         - type: object
7157           properties:
7158             displayName:
7159               type: string
7160               description: editable name of the channel, displayed in its representations
7161               example: Videos of Framasoft
7162               minLength: 1
7163               maxLength: 120
7164             description:
7165               type: string
7166               example: Videos made with <3 by Framasoft
7167               minLength: 3
7168               maxLength: 1000
7169             support:
7170               type: string
7171               description: text shown by default on all videos of this channel, to tell the audience how to support it
7172               example: Please support our work on https://soutenir.framasoft.org/en/ <3
7173               minLength: 3
7174               maxLength: 1000
7175             isLocal:
7176               readOnly: true
7177               type: boolean
7178             updatedAt:
7179               readOnly: true
7180               type: string
7181               format: date-time
7182             banners:
7183               type: array
7184               items:
7185                 $ref: '#/components/schemas/ActorImage'
7186             ownerAccount:
7187               readOnly: true
7188               nullable: true
7189               type: object
7190               properties:
7191                 id:
7192                   type: integer
7193                 uuid:
7194                   $ref: '#/components/schemas/UUIDv4'
7195     VideoChannelCreate:
7196       allOf:
7197         - $ref: '#/components/schemas/VideoChannel'
7198         - properties:
7199             name:
7200               description: username of the channel to create
7201               allOf:
7202                 - $ref: '#/components/schemas/usernameChannel'
7203       required:
7204         - name
7205         - displayName
7206     VideoChannelUpdate:
7207       allOf:
7208         - $ref: '#/components/schemas/VideoChannel'
7209         - properties:
7210             bulkVideosSupportUpdate:
7211               type: boolean
7212               description: Update the support field for all videos of this channel
7213     VideoChannelList:
7214       properties:
7215         total:
7216           type: integer
7217           example: 1
7218         data:
7219           type: array
7220           items:
7221             allOf:
7222               - $ref: '#/components/schemas/VideoChannel'
7223               - $ref: '#/components/schemas/Actor'
7224
7225     MRSSPeerLink:
7226       type: object
7227       xml:
7228         name: 'media:peerLink'
7229       properties:
7230         href:
7231           type: string
7232           xml:
7233             attribute: true
7234         type:
7235           type: string
7236           enum:
7237             - application/x-bittorrent
7238           xml:
7239             attribute: true
7240     MRSSGroupContent:
7241       type: object
7242       xml:
7243         name: 'media:content'
7244       properties:
7245         url:
7246           type: string
7247           format: url
7248           xml:
7249             attribute: true
7250         fileSize:
7251           type: integer
7252           xml:
7253             attribute: true
7254         type:
7255           type: string
7256           xml:
7257             attribute: true
7258         framerate:
7259           type: integer
7260           xml:
7261             attribute: true
7262         duration:
7263           type: integer
7264           xml:
7265             attribute: true
7266         height:
7267           type: integer
7268           xml:
7269             attribute: true
7270         lang:
7271           type: string
7272           xml:
7273             attribute: true
7274     VideoCommentsForXML:
7275       type: array
7276       xml:
7277         wrapped: true
7278         name: 'channel'
7279       items:
7280         type: object
7281         xml:
7282           name: 'item'
7283         properties:
7284           link:
7285             type: string
7286             format: url
7287           guid:
7288             type: string
7289           pubDate:
7290             type: string
7291             format: date-time
7292           'content:encoded':
7293             type: string
7294           'dc:creator':
7295             type: string
7296     VideosForXML:
7297       type: array
7298       xml:
7299         wrapped: true
7300         name: 'channel'
7301       items:
7302         type: object
7303         xml:
7304           name: 'item'
7305         properties:
7306           link:
7307             type: string
7308             format: url
7309             description: video watch page URL
7310           guid:
7311             type: string
7312             description: video canonical URL
7313           pubDate:
7314             type: string
7315             format: date-time
7316             description: video publication date
7317           description:
7318             type: string
7319             description: video description
7320           'content:encoded':
7321             type: string
7322             description: video description
7323           'dc:creator':
7324             type: string
7325             description: publisher user name
7326           'media:category':
7327             type: integer
7328             description: video category (MRSS)
7329           'media:community':
7330             type: object
7331             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7332             properties:
7333               'media:statistics':
7334                 type: object
7335                 properties:
7336                   views:
7337                     type: integer
7338                     xml:
7339                       attribute: true
7340           'media:embed':
7341             type: object
7342             properties:
7343               url:
7344                 type: string
7345                 format: url
7346                 description: video embed path, relative to the canonical URL domain (MRSS)
7347                 xml:
7348                   attribute: true
7349           'media:player':
7350             type: object
7351             properties:
7352               url:
7353                 type: string
7354                 format: url
7355                 description: video watch path, relative to the canonical URL domain (MRSS)
7356                 xml:
7357                   attribute: true
7358           'media:thumbnail':
7359             type: object
7360             properties:
7361               url:
7362                 type: string
7363                 format: url
7364                 xml:
7365                   attribute: true
7366               height:
7367                 type: integer
7368                 xml:
7369                   attribute: true
7370               width:
7371                 type: integer
7372                 xml:
7373                   attribute: true
7374           'media:title':
7375             type: string
7376             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7377           'media:description':
7378             type: string
7379           'media:rating':
7380             type: string
7381             enum:
7382               - nonadult
7383               - adult
7384             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7385           'enclosure':
7386             type: object
7387             description: main streamable file for the video
7388             properties:
7389               url:
7390                 type: string
7391                 format: url
7392                 xml:
7393                   attribute: true
7394               type:
7395                 type: string
7396                 enum:
7397                   - application/x-bittorrent
7398                 xml:
7399                   attribute: true
7400               length:
7401                 type: integer
7402                 xml:
7403                   attribute: true
7404           'media:group':
7405             type: array
7406             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)
7407             items:
7408               anyOf:
7409                 - $ref: '#/components/schemas/MRSSPeerLink'
7410                 - $ref: '#/components/schemas/MRSSGroupContent'
7411     NotificationSettingValue:
7412       type: integer
7413       description: >
7414         Notification type
7415
7416         - `0` NONE
7417
7418         - `1` WEB
7419
7420         - `2` EMAIL
7421       enum:
7422         - 0
7423         - 1
7424         - 2
7425     Notification:
7426       properties:
7427         id:
7428           $ref: '#/components/schemas/id'
7429         type:
7430           type: integer
7431           description: >
7432             Notification type, following the `UserNotificationType` enum:
7433
7434             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7435
7436             - `2` NEW_COMMENT_ON_MY_VIDEO
7437
7438             - `3` NEW_ABUSE_FOR_MODERATORS
7439
7440             - `4` BLACKLIST_ON_MY_VIDEO
7441
7442             - `5` UNBLACKLIST_ON_MY_VIDEO
7443
7444             - `6` MY_VIDEO_PUBLISHED
7445
7446             - `7` MY_VIDEO_IMPORT_SUCCESS
7447
7448             - `8` MY_VIDEO_IMPORT_ERROR
7449
7450             - `9` NEW_USER_REGISTRATION
7451
7452             - `10` NEW_FOLLOW
7453
7454             - `11` COMMENT_MENTION
7455
7456             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7457
7458             - `13` NEW_INSTANCE_FOLLOWER
7459
7460             - `14` AUTO_INSTANCE_FOLLOWING
7461
7462             - `15` ABUSE_STATE_CHANGE
7463
7464             - `16` ABUSE_NEW_MESSAGE
7465
7466             - `17` NEW_PLUGIN_VERSION
7467
7468             - `18` NEW_PEERTUBE_VERSION
7469         read:
7470           type: boolean
7471         video:
7472           nullable: true
7473           allOf:
7474             - $ref: '#/components/schemas/VideoInfo'
7475             - type: object
7476               properties:
7477                 channel:
7478                   $ref: '#/components/schemas/ActorInfo'
7479         videoImport:
7480           nullable: true
7481           type: object
7482           properties:
7483             id:
7484               $ref: '#/components/schemas/id'
7485             video:
7486               nullable: true
7487               $ref: '#/components/schemas/VideoInfo'
7488             torrentName:
7489               type: string
7490               nullable: true
7491             magnetUri:
7492               $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7493             targetUri:
7494               type: string
7495               format: uri
7496               nullable: true
7497         comment:
7498           nullable: true
7499           type: object
7500           properties:
7501             id:
7502               $ref: '#/components/schemas/id'
7503             threadId:
7504               type: integer
7505             video:
7506               $ref: '#/components/schemas/VideoInfo'
7507             account:
7508               $ref: '#/components/schemas/ActorInfo'
7509         videoAbuse:
7510           nullable: true
7511           type: object
7512           properties:
7513             id:
7514               $ref: '#/components/schemas/id'
7515             video:
7516               allOf:
7517                 - $ref: '#/components/schemas/VideoInfo'
7518         videoBlacklist:
7519           nullable: true
7520           type: object
7521           properties:
7522             id:
7523               $ref: '#/components/schemas/id'
7524             video:
7525               allOf:
7526                 - $ref: '#/components/schemas/VideoInfo'
7527         account:
7528           nullable: true
7529           allOf:
7530             - $ref: '#/components/schemas/ActorInfo'
7531         actorFollow:
7532           type: object
7533           nullable: true
7534           properties:
7535             id:
7536               $ref: '#/components/schemas/id'
7537             follower:
7538               $ref: '#/components/schemas/ActorInfo'
7539             state:
7540               type: string
7541               enum:
7542                 - pending
7543                 - accepted
7544             following:
7545               type: object
7546               properties:
7547                 type:
7548                   type: string
7549                   enum:
7550                     - account
7551                     - channel
7552                     - instance
7553                 name:
7554                   type: string
7555                 displayName:
7556                   type: string
7557                 host:
7558                   type: string
7559                   format: hostname
7560         createdAt:
7561           type: string
7562           format: date-time
7563         updatedAt:
7564           type: string
7565           format: date-time
7566     NotificationListResponse:
7567       properties:
7568         total:
7569           type: integer
7570           example: 1
7571         data:
7572           type: array
7573           maxItems: 100
7574           items:
7575             $ref: '#/components/schemas/Notification'
7576     Plugin:
7577       properties:
7578         name:
7579           type: string
7580           example: peertube-plugin-auth-ldap
7581         type:
7582           type: integer
7583           description: >
7584             - `1`: PLUGIN
7585
7586             - `2`: THEME
7587           enum:
7588             - 1
7589             - 2
7590         latestVersion:
7591           type: string
7592           example: 0.0.3
7593         version:
7594           type: string
7595           example: 0.0.1
7596         enabled:
7597           type: boolean
7598         uninstalled:
7599           type: boolean
7600         peertubeEngine:
7601           type: string
7602           example: 2.2.0
7603         description:
7604           type: string
7605         homepage:
7606           type: string
7607           format: url
7608           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7609         settings:
7610           type: object
7611           additionalProperties: true
7612         createdAt:
7613           type: string
7614           format: date-time
7615         updatedAt:
7616           type: string
7617           format: date-time
7618     PluginResponse:
7619       properties:
7620         total:
7621           type: integer
7622           example: 1
7623         data:
7624           type: array
7625           maxItems: 100
7626           items:
7627             $ref: '#/components/schemas/Plugin'
7628
7629     LiveVideoUpdate:
7630       properties:
7631         saveReplay:
7632           type: boolean
7633         permanentLive:
7634           description: User can stream multiple times in a permanent live
7635           type: boolean
7636         latencyMode:
7637           description: User can select live latency mode if enabled by the instance
7638           $ref: '#/components/schemas/LiveVideoLatencyMode'
7639
7640     LiveVideoResponse:
7641       properties:
7642         rtmpUrl:
7643           type: string
7644         rtmpsUrl:
7645           type: string
7646         streamKey:
7647           type: string
7648           description: RTMP stream key to use to stream into this live video
7649         saveReplay:
7650           type: boolean
7651         permanentLive:
7652           description: User can stream multiple times in a permanent live
7653           type: boolean
7654         latencyMode:
7655           description: User can select live latency mode if enabled by the instance
7656           $ref: '#/components/schemas/LiveVideoLatencyMode'
7657
7658   callbacks:
7659     searchIndex:
7660       'https://search.example.org/api/v1/search/videos':
7661         post:
7662           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7663           responses:
7664             '200':
7665               description: successful operation
7666               content:
7667                 application/json:
7668                   schema:
7669                     $ref: '#/components/schemas/VideoListResponse'