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   /videos/live/{id}/sessions:
2466     get:
2467       summary: List live sessions
2468       description: List all sessions created in a particular live
2469       security:
2470         - OAuth2: []
2471       tags:
2472         - Live Videos
2473       parameters:
2474         - $ref: '#/components/parameters/idOrUUID'
2475       responses:
2476         '200':
2477           description: successful operation
2478           content:
2479             application/json:
2480               schema:
2481                 type: object
2482                 properties:
2483                   total:
2484                     type: integer
2485                     example: 1
2486                   data:
2487                     type: array
2488                     items:
2489                       $ref: '#/components/schemas/LiveVideoSessionResponse'
2490   /videos/{id}/live-session:
2491     get:
2492       summary: Get live session of a replay
2493       description: If the video is a replay of a live, you can find the associated live session using this endpoint
2494       security:
2495         - OAuth2: []
2496       tags:
2497         - Live Videos
2498       parameters:
2499         - $ref: '#/components/parameters/idOrUUID'
2500       responses:
2501         '200':
2502           description: successful operation
2503           content:
2504             application/json:
2505               schema:
2506                 $ref: '#/components/schemas/LiveVideoSessionResponse'
2507
2508   /users/me/abuses:
2509     get:
2510       summary: List my abuses
2511       operationId: getMyAbuses
2512       security:
2513         - OAuth2: []
2514       tags:
2515         - Abuses
2516         - My User
2517       parameters:
2518         - name: id
2519           in: query
2520           description: only list the report with this id
2521           schema:
2522             type: integer
2523         - name: state
2524           in: query
2525           schema:
2526             $ref: '#/components/schemas/AbuseStateSet'
2527         - $ref: '#/components/parameters/abusesSort'
2528         - $ref: '#/components/parameters/start'
2529         - $ref: '#/components/parameters/count'
2530       responses:
2531         '200':
2532           description: successful operation
2533           content:
2534             application/json:
2535               schema:
2536                 type: object
2537                 properties:
2538                   total:
2539                     type: integer
2540                     example: 1
2541                   data:
2542                     type: array
2543                     items:
2544                       $ref: '#/components/schemas/Abuse'
2545
2546   /abuses:
2547     get:
2548       summary: List abuses
2549       operationId: getAbuses
2550       security:
2551         - OAuth2:
2552           - admin
2553           - moderator
2554       tags:
2555         - Abuses
2556       parameters:
2557         - name: id
2558           in: query
2559           description: only list the report with this id
2560           schema:
2561             type: integer
2562         - name: predefinedReason
2563           in: query
2564           description: predefined reason the listed reports should contain
2565           schema:
2566             $ref: '#/components/schemas/PredefinedAbuseReasons'
2567         - name: search
2568           in: query
2569           description: plain search that will match with video titles, reporter names and more
2570           schema:
2571             type: string
2572         - name: state
2573           in: query
2574           schema:
2575             $ref: '#/components/schemas/AbuseStateSet'
2576         - name: searchReporter
2577           in: query
2578           description: only list reports of a specific reporter
2579           schema:
2580             type: string
2581         - name: searchReportee
2582           description: only list reports of a specific reportee
2583           in: query
2584           schema:
2585             type: string
2586         - name: searchVideo
2587           in: query
2588           description: only list reports of a specific video
2589           schema:
2590             type: string
2591         - name: searchVideoChannel
2592           in: query
2593           description: only list reports of a specific video channel
2594           schema:
2595             type: string
2596         - name: videoIs
2597           in: query
2598           description: only list deleted or blocklisted videos
2599           schema:
2600             type: string
2601             enum:
2602             - 'deleted'
2603             - 'blacklisted'
2604         - name: filter
2605           in: query
2606           description: only list account, comment or video reports
2607           schema:
2608             type: string
2609             enum:
2610             - 'video'
2611             - 'comment'
2612             - 'account'
2613         - $ref: '#/components/parameters/start'
2614         - $ref: '#/components/parameters/count'
2615         - $ref: '#/components/parameters/abusesSort'
2616       responses:
2617         '200':
2618           description: successful operation
2619           content:
2620             application/json:
2621               schema:
2622                 type: object
2623                 properties:
2624                   total:
2625                     type: integer
2626                     example: 1
2627                   data:
2628                     type: array
2629                     items:
2630                       $ref: '#/components/schemas/Abuse'
2631     post:
2632       summary: Report an abuse
2633       security:
2634         - OAuth2: []
2635       tags:
2636         - Abuses
2637       requestBody:
2638         required: true
2639         content:
2640           application/json:
2641             schema:
2642               type: object
2643               properties:
2644                 reason:
2645                   description: Reason why the user reports this video
2646                   type: string
2647                   minLength: 2
2648                   maxLength: 3000
2649                 predefinedReasons:
2650                   $ref: '#/components/schemas/PredefinedAbuseReasons'
2651                 video:
2652                   type: object
2653                   properties:
2654                     id:
2655                       description: Video id to report
2656                       allOf:
2657                         - $ref: '#/components/schemas/Video/properties/id'
2658                     startAt:
2659                       type: integer
2660                       format: seconds
2661                       description: Timestamp in the video that marks the beginning of the report
2662                       minimum: 0
2663                     endAt:
2664                       type: integer
2665                       format: seconds
2666                       description: Timestamp in the video that marks the ending of the report
2667                       minimum: 0
2668                 comment:
2669                   type: object
2670                   properties:
2671                     id:
2672                       description: Comment id to report
2673                       allOf:
2674                         - $ref: '#/components/schemas/VideoComment/properties/id'
2675                 account:
2676                   type: object
2677                   properties:
2678                     id:
2679                       description: Account id to report
2680                       type: integer
2681               required:
2682                 - reason
2683       responses:
2684         '200':
2685           description: successful operation
2686           content:
2687             application/json:
2688               schema:
2689                 type: object
2690                 properties:
2691                   abuse:
2692                     type: object
2693                     properties:
2694                       id:
2695                         $ref: '#/components/schemas/id'
2696         '400':
2697           description: incorrect request parameters
2698
2699   '/abuses/{abuseId}':
2700     put:
2701       summary: Update an abuse
2702       security:
2703         - OAuth2:
2704           - admin
2705           - moderator
2706       tags:
2707         - Abuses
2708       parameters:
2709         - $ref: '#/components/parameters/abuseId'
2710       requestBody:
2711         content:
2712           application/json:
2713             schema:
2714               type: object
2715               properties:
2716                 state:
2717                   $ref: '#/components/schemas/AbuseStateSet'
2718                 moderationComment:
2719                   type: string
2720                   description: Update the report comment visible only to the moderation team
2721                   minLength: 2
2722                   maxLength: 3000
2723       responses:
2724         '204':
2725           description: successful operation
2726         '404':
2727           description: abuse not found
2728     delete:
2729       tags:
2730         - Abuses
2731       summary: Delete an abuse
2732       security:
2733         - OAuth2:
2734           - admin
2735           - moderator
2736       parameters:
2737         - $ref: '#/components/parameters/abuseId'
2738       responses:
2739         '204':
2740           description: successful operation
2741         '404':
2742           description: block not found
2743
2744   '/abuses/{abuseId}/messages':
2745     get:
2746       summary: List messages of an abuse
2747       security:
2748         - OAuth2: []
2749       tags:
2750         - Abuses
2751       parameters:
2752         - $ref: '#/components/parameters/abuseId'
2753       responses:
2754         '200':
2755           description: successful operation
2756           content:
2757             application/json:
2758               schema:
2759                 type: object
2760                 properties:
2761                   total:
2762                     type: integer
2763                     example: 1
2764                   data:
2765                     type: array
2766                     items:
2767                       $ref: '#/components/schemas/AbuseMessage'
2768     post:
2769       summary: Add message to an abuse
2770       security:
2771         - OAuth2: []
2772       tags:
2773         - Abuses
2774       parameters:
2775         - $ref: '#/components/parameters/abuseId'
2776       requestBody:
2777         required: true
2778         content:
2779           application/json:
2780             schema:
2781               type: object
2782               properties:
2783                 message:
2784                   description: Message to send
2785                   type: string
2786                   minLength: 2
2787                   maxLength: 3000
2788               required:
2789                 - message
2790       responses:
2791         '200':
2792           description: successful operation
2793         '400':
2794           description: incorrect request parameters
2795
2796   '/abuses/{abuseId}/messages/{abuseMessageId}':
2797     delete:
2798       summary: Delete an abuse message
2799       security:
2800         - OAuth2: []
2801       tags:
2802         - Abuses
2803       parameters:
2804         - $ref: '#/components/parameters/abuseId'
2805         - $ref: '#/components/parameters/abuseMessageId'
2806       responses:
2807         '204':
2808           description: successful operation
2809
2810   '/videos/{id}/blacklist':
2811     post:
2812       summary: Block a video
2813       operationId: addVideoBlock
2814       security:
2815         - OAuth2:
2816           - admin
2817           - moderator
2818       tags:
2819         - Video Blocks
2820       parameters:
2821         - $ref: '#/components/parameters/idOrUUID'
2822       responses:
2823         '204':
2824           description: successful operation
2825     delete:
2826       summary: Unblock a video by its id
2827       operationId: delVideoBlock
2828       security:
2829         - OAuth2:
2830           - admin
2831           - moderator
2832       tags:
2833         - Video Blocks
2834       parameters:
2835         - $ref: '#/components/parameters/idOrUUID'
2836       responses:
2837         '204':
2838           description: successful operation
2839         '404':
2840           description: block not found
2841
2842   /videos/blacklist:
2843     get:
2844       tags:
2845         - Video Blocks
2846       summary: List video blocks
2847       operationId: getVideoBlocks
2848       security:
2849         - OAuth2:
2850           - admin
2851           - moderator
2852       parameters:
2853         - name: type
2854           in: query
2855           description: >
2856             list only blocks that match this type:
2857
2858             - `1`: manual block
2859
2860             - `2`: automatic block that needs review
2861           schema:
2862             type: integer
2863             enum:
2864               - 1
2865               - 2
2866         - name: search
2867           in: query
2868           description: plain search that will match with video titles, and more
2869           schema:
2870             type: string
2871         - $ref: '#/components/parameters/start'
2872         - $ref: '#/components/parameters/count'
2873         - $ref: '#/components/parameters/blacklistsSort'
2874       responses:
2875         '200':
2876           description: successful operation
2877           content:
2878             application/json:
2879               schema:
2880                 type: object
2881                 properties:
2882                   total:
2883                     type: integer
2884                     example: 1
2885                   data:
2886                     type: array
2887                     items:
2888                       $ref: '#/components/schemas/VideoBlacklist'
2889
2890   /videos/{id}/captions:
2891     get:
2892       summary: List captions of a video
2893       operationId: getVideoCaptions
2894       tags:
2895         - Video Captions
2896       parameters:
2897         - $ref: '#/components/parameters/idOrUUID'
2898       responses:
2899         '200':
2900           description: successful operation
2901           content:
2902             application/json:
2903               schema:
2904                 type: object
2905                 properties:
2906                   total:
2907                     type: integer
2908                     example: 1
2909                   data:
2910                     type: array
2911                     items:
2912                       $ref: '#/components/schemas/VideoCaption'
2913
2914   /videos/{id}/captions/{captionLanguage}:
2915     put:
2916       summary: Add or replace a video caption
2917       operationId: addVideoCaption
2918       security:
2919         - OAuth2:
2920           - user
2921       tags:
2922         - Video Captions
2923       parameters:
2924         - $ref: '#/components/parameters/idOrUUID'
2925         - $ref: '#/components/parameters/captionLanguage'
2926       requestBody:
2927         content:
2928           multipart/form-data:
2929             schema:
2930               type: object
2931               properties:
2932                 captionfile:
2933                   description: The file to upload.
2934                   type: string
2935                   format: binary
2936             encoding:
2937               captionfile:
2938                 contentType: text/vtt, application/x-subrip, text/plain
2939       responses:
2940         '204':
2941           description: successful operation
2942         '404':
2943           description: video or language not found
2944     delete:
2945       summary: Delete a video caption
2946       operationId: delVideoCaption
2947       security:
2948         - OAuth2:
2949           - user
2950       tags:
2951         - Video Captions
2952       parameters:
2953         - $ref: '#/components/parameters/idOrUUID'
2954         - $ref: '#/components/parameters/captionLanguage'
2955       responses:
2956         '204':
2957           description: successful operation
2958         '404':
2959           description: video or language or caption for that language not found
2960
2961   /video-channels:
2962     get:
2963       summary: List video channels
2964       operationId: getVideoChannels
2965       tags:
2966         - Video Channels
2967       parameters:
2968         - $ref: '#/components/parameters/start'
2969         - $ref: '#/components/parameters/count'
2970         - $ref: '#/components/parameters/sort'
2971       responses:
2972         '200':
2973           description: successful operation
2974           content:
2975             application/json:
2976               schema:
2977                 $ref: '#/components/schemas/VideoChannelList'
2978     post:
2979       summary: Create a video channel
2980       operationId: addVideoChannel
2981       security:
2982         - OAuth2: []
2983       tags:
2984         - Video Channels
2985       responses:
2986         '204':
2987           description: successful operation
2988           content:
2989             application/json:
2990               schema:
2991                 type: object
2992                 properties:
2993                   videoChannel:
2994                     type: object
2995                     properties:
2996                       id:
2997                         $ref: '#/components/schemas/id'
2998       requestBody:
2999         content:
3000           application/json:
3001             schema:
3002               $ref: '#/components/schemas/VideoChannelCreate'
3003
3004   '/video-channels/{channelHandle}':
3005     get:
3006       summary: Get a video channel
3007       operationId: getVideoChannel
3008       tags:
3009         - Video Channels
3010       parameters:
3011         - $ref: '#/components/parameters/channelHandle'
3012       responses:
3013         '200':
3014           description: successful operation
3015           content:
3016             application/json:
3017               schema:
3018                 $ref: '#/components/schemas/VideoChannel'
3019     put:
3020       summary: Update a video channel
3021       operationId: putVideoChannel
3022       security:
3023         - OAuth2: []
3024       tags:
3025         - Video Channels
3026       parameters:
3027         - $ref: '#/components/parameters/channelHandle'
3028       responses:
3029         '204':
3030           description: successful operation
3031       requestBody:
3032         content:
3033           application/json:
3034             schema:
3035               $ref: '#/components/schemas/VideoChannelUpdate'
3036     delete:
3037       summary: Delete a video channel
3038       operationId: delVideoChannel
3039       security:
3040         - OAuth2: []
3041       tags:
3042         - Video Channels
3043       parameters:
3044         - $ref: '#/components/parameters/channelHandle'
3045       responses:
3046         '204':
3047           description: successful operation
3048
3049   '/video-channels/{channelHandle}/videos':
3050     get:
3051       summary: List videos of a video channel
3052       operationId: getVideoChannelVideos
3053       tags:
3054         - Video
3055         - Video Channels
3056       parameters:
3057         - $ref: '#/components/parameters/channelHandle'
3058         - $ref: '#/components/parameters/categoryOneOf'
3059         - $ref: '#/components/parameters/isLive'
3060         - $ref: '#/components/parameters/tagsOneOf'
3061         - $ref: '#/components/parameters/tagsAllOf'
3062         - $ref: '#/components/parameters/licenceOneOf'
3063         - $ref: '#/components/parameters/languageOneOf'
3064         - $ref: '#/components/parameters/nsfw'
3065         - $ref: '#/components/parameters/isLocal'
3066         - $ref: '#/components/parameters/include'
3067         - $ref: '#/components/parameters/privacyOneOf'
3068         - $ref: '#/components/parameters/hasHLSFiles'
3069         - $ref: '#/components/parameters/hasWebtorrentFiles'
3070         - $ref: '#/components/parameters/skipCount'
3071         - $ref: '#/components/parameters/start'
3072         - $ref: '#/components/parameters/count'
3073         - $ref: '#/components/parameters/videosSort'
3074       responses:
3075         '200':
3076           description: successful operation
3077           content:
3078             application/json:
3079               schema:
3080                 $ref: '#/components/schemas/VideoListResponse'
3081
3082   '/video-channels/{channelHandle}/followers':
3083     get:
3084       tags:
3085         - Video Channels
3086       summary: 'List followers of a video channel'
3087       security:
3088         - OAuth2: []
3089       operationId: getVideoChannelFollowers
3090       parameters:
3091         - $ref: '#/components/parameters/channelHandle'
3092         - $ref: '#/components/parameters/start'
3093         - $ref: '#/components/parameters/count'
3094         - $ref: '#/components/parameters/followersSort'
3095         - $ref: '#/components/parameters/search'
3096       responses:
3097         '200':
3098           description: successful operation
3099           content:
3100             application/json:
3101               schema:
3102                 type: object
3103                 properties:
3104                   total:
3105                     type: integer
3106                     example: 1
3107                   data:
3108                     type: array
3109                     items:
3110                       $ref: '#/components/schemas/Follow'
3111
3112   '/video-channels/{channelHandle}/avatar/pick':
3113     post:
3114       summary: Update channel avatar
3115       security:
3116         - OAuth2: []
3117       tags:
3118         - Video Channels
3119       parameters:
3120         - $ref: '#/components/parameters/channelHandle'
3121       responses:
3122         '200':
3123           description: successful operation
3124           content:
3125             application/json:
3126               schema:
3127                 type: object
3128                 properties:
3129                   avatars:
3130                     type: array
3131                     items:
3132                       $ref: '#/components/schemas/ActorImage'
3133         '413':
3134           description: image file too large
3135           headers:
3136             X-File-Maximum-Size:
3137               schema:
3138                 type: string
3139                 format: Nginx size
3140               description: Maximum file size for the avatar
3141       requestBody:
3142         content:
3143           multipart/form-data:
3144             schema:
3145               type: object
3146               properties:
3147                 avatarfile:
3148                   description: The file to upload.
3149                   type: string
3150                   format: binary
3151             encoding:
3152               avatarfile:
3153                 contentType: image/png, image/jpeg
3154
3155   '/video-channels/{channelHandle}/avatar':
3156     delete:
3157       summary: Delete channel avatar
3158       security:
3159         - OAuth2: []
3160       tags:
3161         - Video Channels
3162       parameters:
3163         - $ref: '#/components/parameters/channelHandle'
3164       responses:
3165         '204':
3166           description: successful operation
3167
3168   '/video-channels/{channelHandle}/banner/pick':
3169     post:
3170       summary: Update channel banner
3171       security:
3172         - OAuth2: []
3173       tags:
3174         - Video Channels
3175       parameters:
3176         - $ref: '#/components/parameters/channelHandle'
3177       responses:
3178         '200':
3179           description: successful operation
3180           content:
3181             application/json:
3182               schema:
3183                 type: object
3184                 properties:
3185                   banners:
3186                     type: array
3187                     items:
3188                       $ref: '#/components/schemas/ActorImage'
3189         '413':
3190           description: image file too large
3191           headers:
3192             X-File-Maximum-Size:
3193               schema:
3194                 type: string
3195                 format: Nginx size
3196               description: Maximum file size for the banner
3197       requestBody:
3198         content:
3199           multipart/form-data:
3200             schema:
3201               type: object
3202               properties:
3203                 bannerfile:
3204                   description: The file to upload.
3205                   type: string
3206                   format: binary
3207             encoding:
3208               bannerfile:
3209                 contentType: image/png, image/jpeg
3210
3211   '/video-channels/{channelHandle}/banner':
3212     delete:
3213       summary: Delete channel banner
3214       security:
3215         - OAuth2: []
3216       tags:
3217         - Video Channels
3218       parameters:
3219         - $ref: '#/components/parameters/channelHandle'
3220       responses:
3221         '204':
3222           description: successful operation
3223
3224   /video-playlists/privacies:
3225     get:
3226       summary: List available playlist privacy policies
3227       operationId: getPlaylistPrivacyPolicies
3228       tags:
3229         - Video Playlists
3230       responses:
3231         '200':
3232           description: successful operation
3233           content:
3234             application/json:
3235               schema:
3236                 type: array
3237                 items:
3238                   type: string
3239               examples:
3240                 nightly:
3241                   externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
3242
3243   /video-playlists:
3244     get:
3245       summary: List video playlists
3246       operationId: getPlaylists
3247       tags:
3248         - Video Playlists
3249       parameters:
3250         - $ref: '#/components/parameters/start'
3251         - $ref: '#/components/parameters/count'
3252         - $ref: '#/components/parameters/sort'
3253       responses:
3254         '200':
3255           description: successful operation
3256           content:
3257             application/json:
3258               schema:
3259                 type: object
3260                 properties:
3261                   total:
3262                     type: integer
3263                     example: 1
3264                   data:
3265                     type: array
3266                     items:
3267                       $ref: '#/components/schemas/VideoPlaylist'
3268     post:
3269       summary: Create a video playlist
3270       description: If the video playlist is set as public, `videoChannelId` is mandatory.
3271       operationId: addPlaylist
3272       security:
3273         - OAuth2: []
3274       tags:
3275         - Video Playlists
3276       responses:
3277         '200':
3278           description: successful operation
3279           content:
3280             application/json:
3281               schema:
3282                 type: object
3283                 properties:
3284                   videoPlaylist:
3285                     type: object
3286                     properties:
3287                       id:
3288                         $ref: '#/components/schemas/VideoPlaylist/properties/id'
3289                       uuid:
3290                         $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
3291                       shortUUID:
3292                         $ref: '#/components/schemas/VideoPlaylist/properties/shortUUID'
3293       requestBody:
3294         content:
3295           multipart/form-data:
3296             schema:
3297               type: object
3298               properties:
3299                 displayName:
3300                   description: Video playlist display name
3301                   type: string
3302                   minLength: 1
3303                   maxLength: 120
3304                 thumbnailfile:
3305                   description: Video playlist thumbnail file
3306                   type: string
3307                   format: binary
3308                 privacy:
3309                   $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3310                 description:
3311                   description: Video playlist description
3312                   type: string
3313                   minLength: 3
3314                   maxLength: 1000
3315                 videoChannelId:
3316                   allOf:
3317                     - $ref: '#/components/schemas/id'
3318                   description: Video channel in which the playlist will be published
3319               required:
3320                 - displayName
3321             encoding:
3322               thumbnailfile:
3323                 contentType: image/jpeg
3324
3325   /video-playlists/{playlistId}:
3326     get:
3327       summary: Get a video playlist
3328       tags:
3329         - Video Playlists
3330       parameters:
3331         - $ref: '#/components/parameters/playlistId'
3332       responses:
3333         '200':
3334           description: successful operation
3335           content:
3336             application/json:
3337               schema:
3338                 $ref: '#/components/schemas/VideoPlaylist'
3339     put:
3340       summary: Update a video playlist
3341       description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
3342       security:
3343         - OAuth2: []
3344       tags:
3345         - Video Playlists
3346       responses:
3347         '204':
3348           description: successful operation
3349       parameters:
3350         - $ref: '#/components/parameters/playlistId'
3351       requestBody:
3352         content:
3353           multipart/form-data:
3354             schema:
3355               type: object
3356               properties:
3357                 displayName:
3358                   description: Video playlist display name
3359                   type: string
3360                   minLength: 1
3361                   maxLength: 120
3362                 thumbnailfile:
3363                   description: Video playlist thumbnail file
3364                   type: string
3365                   format: binary
3366                 privacy:
3367                   $ref: '#/components/schemas/VideoPlaylistPrivacySet'
3368                 description:
3369                   description: Video playlist description
3370                   type: string
3371                 videoChannelId:
3372                   allOf:
3373                     - $ref: '#/components/schemas/id'
3374                   description: Video channel in which the playlist will be published
3375             encoding:
3376               thumbnailfile:
3377                 contentType: image/jpeg
3378     delete:
3379       summary: Delete a video playlist
3380       security:
3381         - OAuth2: []
3382       tags:
3383         - Video Playlists
3384       parameters:
3385         - $ref: '#/components/parameters/playlistId'
3386       responses:
3387         '204':
3388           description: successful operation
3389
3390   /video-playlists/{playlistId}/videos:
3391     get:
3392       summary: 'List videos of a playlist'
3393       operationId: getVideoPlaylistVideos
3394       tags:
3395         - Videos
3396         - Video Playlists
3397       parameters:
3398         - $ref: '#/components/parameters/playlistId'
3399         - $ref: '#/components/parameters/start'
3400         - $ref: '#/components/parameters/count'
3401       responses:
3402         '200':
3403           description: successful operation
3404           content:
3405             application/json:
3406               schema:
3407                 $ref: '#/components/schemas/VideoListResponse'
3408     post:
3409       summary: Add a video in a playlist
3410       operationId: addVideoPlaylistVideo
3411       security:
3412         - OAuth2: []
3413       tags:
3414         - Videos
3415         - Video Playlists
3416       parameters:
3417         - $ref: '#/components/parameters/playlistId'
3418       responses:
3419         '200':
3420           description: successful operation
3421           content:
3422             application/json:
3423               schema:
3424                 type: object
3425                 properties:
3426                   videoPlaylistElement:
3427                     type: object
3428                     properties:
3429                       id:
3430                         type: integer
3431                         example: 2
3432       requestBody:
3433         content:
3434           application/json:
3435             schema:
3436               type: object
3437               properties:
3438                 videoId:
3439                   oneOf:
3440                     - $ref: '#/components/schemas/Video/properties/uuid'
3441                     - $ref: '#/components/schemas/Video/properties/id'
3442                   description: Video to add in the playlist
3443                 startTimestamp:
3444                   type: integer
3445                   format: seconds
3446                   description: Start the video at this specific timestamp
3447                 stopTimestamp:
3448                   type: integer
3449                   format: seconds
3450                   description: Stop the video at this specific timestamp
3451               required:
3452                 - videoId
3453
3454   /video-playlists/{playlistId}/videos/reorder:
3455     post:
3456       summary: 'Reorder a playlist'
3457       operationId: reorderVideoPlaylist
3458       security:
3459         - OAuth2: []
3460       tags:
3461         - Video Playlists
3462       parameters:
3463         - $ref: '#/components/parameters/playlistId'
3464       responses:
3465         '204':
3466           description: successful operation
3467       requestBody:
3468         content:
3469           application/json:
3470             schema:
3471               type: object
3472               properties:
3473                 startPosition:
3474                   type: integer
3475                   description: 'Start position of the element to reorder'
3476                   minimum: 1
3477                 insertAfterPosition:
3478                   type: integer
3479                   description: 'New position for the block to reorder, to add the block before the first element'
3480                   minimum: 0
3481                 reorderLength:
3482                   type: integer
3483                   description: 'How many element from `startPosition` to reorder'
3484                   minimum: 1
3485               required:
3486                 - startPosition
3487                 - insertAfterPosition
3488
3489   /video-playlists/{playlistId}/videos/{playlistElementId}:
3490     put:
3491       summary: Update a playlist element
3492       operationId: putVideoPlaylistVideo
3493       security:
3494         - OAuth2: []
3495       tags:
3496         - Video Playlists
3497       parameters:
3498         - $ref: '#/components/parameters/playlistId'
3499         - $ref: '#/components/parameters/playlistElementId'
3500       responses:
3501         '204':
3502           description: successful operation
3503       requestBody:
3504         content:
3505           application/json:
3506             schema:
3507               type: object
3508               properties:
3509                 startTimestamp:
3510                   type: integer
3511                   format: seconds
3512                   description: Start the video at this specific timestamp
3513                 stopTimestamp:
3514                   type: integer
3515                   format: seconds
3516                   description: Stop the video at this specific timestamp
3517     delete:
3518       summary: Delete an element from a playlist
3519       operationId: delVideoPlaylistVideo
3520       security:
3521         - OAuth2: []
3522       tags:
3523         - Video Playlists
3524       parameters:
3525         - $ref: '#/components/parameters/playlistId'
3526         - $ref: '#/components/parameters/playlistElementId'
3527       responses:
3528         '204':
3529           description: successful operation
3530
3531   '/users/me/video-playlists/videos-exist':
3532     get:
3533       summary: Check video exists in my playlists
3534       security:
3535         - OAuth2: []
3536       tags:
3537         - Video Playlists
3538       parameters:
3539         - name: videoIds
3540           in: query
3541           required: true
3542           description: The video ids to check
3543           schema:
3544             type: array
3545             items:
3546               $ref: '#/components/schemas/Video/properties/id'
3547       responses:
3548         '200':
3549           description: successful operation
3550           content:
3551             application/json:
3552               schema:
3553                 type: object
3554                 properties:
3555                   videoId:
3556                     type: array
3557                     items:
3558                       type: object
3559                       properties:
3560                         playlistElementId:
3561                           type: integer
3562                         playlistId:
3563                           type: integer
3564                         startTimestamp:
3565                           type: integer
3566                           format: seconds
3567                         stopTimestamp:
3568                           type: integer
3569                           format: seconds
3570
3571   '/accounts/{name}/video-channels':
3572     get:
3573       summary: List video channels of an account
3574       tags:
3575         - Video Channels
3576         - Accounts
3577       parameters:
3578         - $ref: '#/components/parameters/name'
3579         - name: withStats
3580           in: query
3581           description: include view statistics for the last 30 days (only if authentified as the account user)
3582           schema:
3583             type: boolean
3584         - $ref: '#/components/parameters/start'
3585         - $ref: '#/components/parameters/count'
3586         - $ref: '#/components/parameters/sort'
3587       responses:
3588         '200':
3589           description: successful operation
3590           content:
3591             application/json:
3592               schema:
3593                 $ref: '#/components/schemas/VideoChannelList'
3594
3595   '/accounts/{name}/ratings':
3596     get:
3597       summary: List ratings of an account
3598       security:
3599         - OAuth2: []
3600       tags:
3601         - Accounts
3602       parameters:
3603         - $ref: '#/components/parameters/name'
3604         - $ref: '#/components/parameters/start'
3605         - $ref: '#/components/parameters/count'
3606         - $ref: '#/components/parameters/sort'
3607         - name: rating
3608           in: query
3609           required: false
3610           description: Optionally filter which ratings to retrieve
3611           schema:
3612             type: string
3613             enum:
3614               - like
3615               - dislike
3616       responses:
3617         '200':
3618           description: successful operation
3619           content:
3620             application/json:
3621               schema:
3622                 type: array
3623                 items:
3624                   $ref: '#/components/schemas/VideoRating'
3625
3626   '/videos/{id}/comment-threads':
3627     get:
3628       summary: List threads of a video
3629       tags:
3630         - Video Comments
3631       parameters:
3632         - $ref: '#/components/parameters/idOrUUID'
3633         - $ref: '#/components/parameters/start'
3634         - $ref: '#/components/parameters/count'
3635         - $ref: '#/components/parameters/commentsSort'
3636       responses:
3637         '200':
3638           description: successful operation
3639           content:
3640             application/json:
3641               schema:
3642                 $ref: '#/components/schemas/CommentThreadResponse'
3643     post:
3644       summary: Create a thread
3645       security:
3646         - OAuth2: []
3647       tags:
3648         - Video Comments
3649       parameters:
3650         - $ref: '#/components/parameters/idOrUUID'
3651       responses:
3652         '200':
3653           description: successful operation
3654           content:
3655             application/json:
3656               schema:
3657                 $ref: '#/components/schemas/CommentThreadPostResponse'
3658         '404':
3659           description: video does not exist
3660       requestBody:
3661         content:
3662           application/json:
3663             schema:
3664               type: object
3665               properties:
3666                 text:
3667                   allOf:
3668                     - $ref: '#/components/schemas/VideoComment/properties/text'
3669                   format: markdown
3670                   maxLength: 10000
3671               required:
3672                 - text
3673
3674   '/videos/{id}/comment-threads/{threadId}':
3675     get:
3676       summary: Get a thread
3677       tags:
3678         - Video Comments
3679       parameters:
3680         - $ref: '#/components/parameters/idOrUUID'
3681         - $ref: '#/components/parameters/threadId'
3682       responses:
3683         '200':
3684           description: successful operation
3685           content:
3686             application/json:
3687               schema:
3688                 $ref: '#/components/schemas/VideoCommentThreadTree'
3689
3690   '/videos/{id}/comments/{commentId}':
3691     post:
3692       summary: Reply to a thread of a video
3693       security:
3694         - OAuth2: []
3695       tags:
3696         - Video Comments
3697       parameters:
3698         - $ref: '#/components/parameters/idOrUUID'
3699         - $ref: '#/components/parameters/commentId'
3700       responses:
3701         '200':
3702           description: successful operation
3703           content:
3704             application/json:
3705               schema:
3706                 $ref: '#/components/schemas/CommentThreadPostResponse'
3707         '404':
3708           description: thread or video does not exist
3709       requestBody:
3710         content:
3711           application/json:
3712             schema:
3713               type: object
3714               properties:
3715                 text:
3716                   allOf:
3717                     - $ref: '#/components/schemas/VideoComment/properties/text'
3718                   format: markdown
3719                   maxLength: 10000
3720               required:
3721                 - text
3722     delete:
3723       summary: Delete a comment or a reply
3724       security:
3725         - OAuth2: []
3726       tags:
3727         - Video Comments
3728       parameters:
3729         - $ref: '#/components/parameters/idOrUUID'
3730         - $ref: '#/components/parameters/commentId'
3731       responses:
3732         '204':
3733           description: successful operation
3734         '403':
3735           description: cannot remove comment of another user
3736         '404':
3737           description: comment or video does not exist
3738         '409':
3739           description: comment is already deleted
3740
3741   '/videos/{id}/rate':
3742     put:
3743       summary: Like/dislike a video
3744       security:
3745         - OAuth2: []
3746       tags:
3747         - Video Rates
3748       parameters:
3749         - $ref: '#/components/parameters/idOrUUID'
3750       requestBody:
3751         content:
3752           application/json:
3753             schema:
3754               type: object
3755               properties:
3756                 rating:
3757                   type: string
3758                   enum:
3759                     - like
3760                     - dislike
3761               required:
3762                 - rating
3763       responses:
3764         '204':
3765           description: successful operation
3766         '404':
3767           description: video does not exist
3768
3769   '/videos/{id}/hls':
3770     delete:
3771       summary: Delete video HLS files
3772       security:
3773         - OAuth2:
3774           - admin
3775       tags:
3776         - Video Files
3777       operationId: delVideoHLS
3778       parameters:
3779         - $ref: '#/components/parameters/idOrUUID'
3780       responses:
3781         '204':
3782           description: successful operation
3783         '404':
3784           description: video does not exist
3785   '/videos/{id}/webtorrent':
3786     delete:
3787       summary: Delete video WebTorrent files
3788       security:
3789         - OAuth2:
3790           - admin
3791       tags:
3792         - Video Files
3793       operationId: delVideoWebTorrent
3794       parameters:
3795         - $ref: '#/components/parameters/idOrUUID'
3796       responses:
3797         '204':
3798           description: successful operation
3799         '404':
3800           description: video does not exist
3801
3802   '/videos/{id}/transcoding':
3803     post:
3804       summary: Create a transcoding job
3805       security:
3806         - OAuth2:
3807           - admin
3808       tags:
3809         - Video Transcoding
3810       operationId: createVideoTranscoding
3811       parameters:
3812         - $ref: '#/components/parameters/idOrUUID'
3813       requestBody:
3814           content:
3815             application/json:
3816               schema:
3817                 type: object
3818                 properties:
3819                   transcodingType:
3820                     type: string
3821                     enum:
3822                       - hls
3823                       - webtorrent
3824                 required:
3825                   - transcodingType
3826       responses:
3827         '204':
3828           description: successful operation
3829         '404':
3830           description: video does not exist
3831
3832   /search/videos:
3833     get:
3834       tags:
3835         - Search
3836       summary: Search videos
3837       operationId: searchVideos
3838       parameters:
3839         - name: search
3840           in: query
3841           required: true
3842           allowEmptyValue: false
3843           description: >
3844             String to search. If the user can make a remote URI search, and the string is an URI then the
3845             PeerTube instance will fetch the remote object and add it to its database. Then,
3846             you can use the REST API to fetch the complete video information and interact with it.
3847           schema:
3848             type: string
3849         - $ref: '#/components/parameters/categoryOneOf'
3850         - $ref: '#/components/parameters/isLive'
3851         - $ref: '#/components/parameters/tagsOneOf'
3852         - $ref: '#/components/parameters/tagsAllOf'
3853         - $ref: '#/components/parameters/licenceOneOf'
3854         - $ref: '#/components/parameters/languageOneOf'
3855         - $ref: '#/components/parameters/nsfw'
3856         - $ref: '#/components/parameters/isLocal'
3857         - $ref: '#/components/parameters/include'
3858         - $ref: '#/components/parameters/privacyOneOf'
3859         - $ref: '#/components/parameters/hasHLSFiles'
3860         - $ref: '#/components/parameters/hasWebtorrentFiles'
3861         - $ref: '#/components/parameters/skipCount'
3862         - $ref: '#/components/parameters/start'
3863         - $ref: '#/components/parameters/count'
3864         - $ref: '#/components/parameters/searchTarget'
3865         - $ref: '#/components/parameters/videosSearchSort'
3866         - name: startDate
3867           in: query
3868           description: Get videos that are published after this date
3869           schema:
3870             type: string
3871             format: date-time
3872         - name: endDate
3873           in: query
3874           description: Get videos that are published before this date
3875           schema:
3876             type: string
3877             format: date-time
3878         - name: originallyPublishedStartDate
3879           in: query
3880           description: Get videos that are originally published after this date
3881           schema:
3882             type: string
3883             format: date-time
3884         - name: originallyPublishedEndDate
3885           in: query
3886           description: Get videos that are originally published before this date
3887           schema:
3888             type: string
3889             format: date-time
3890         - name: durationMin
3891           in: query
3892           description: Get videos that have this minimum duration
3893           schema:
3894             type: integer
3895         - name: durationMax
3896           in: query
3897           description: Get videos that have this maximum duration
3898           schema:
3899             type: integer
3900       callbacks:
3901         'searchTarget === search-index':
3902           $ref: '#/components/callbacks/searchIndex'
3903       responses:
3904         '200':
3905           description: successful operation
3906           content:
3907             application/json:
3908               schema:
3909                 $ref: '#/components/schemas/VideoListResponse'
3910         '500':
3911           description: search index unavailable
3912
3913   /search/video-channels:
3914     get:
3915       tags:
3916         - Search
3917       summary: Search channels
3918       operationId: searchChannels
3919       parameters:
3920         - name: search
3921           in: query
3922           required: true
3923           description: >
3924             String to search. If the user can make a remote URI search, and the string is an URI then the
3925             PeerTube instance will fetch the remote object and add it to its database. Then,
3926             you can use the REST API to fetch the complete channel information and interact with it.
3927           schema:
3928             type: string
3929         - $ref: '#/components/parameters/start'
3930         - $ref: '#/components/parameters/count'
3931         - $ref: '#/components/parameters/searchTarget'
3932         - $ref: '#/components/parameters/sort'
3933       callbacks:
3934         'searchTarget === search-index':
3935           $ref: '#/components/callbacks/searchIndex'
3936       responses:
3937         '200':
3938           description: successful operation
3939           content:
3940             application/json:
3941               schema:
3942                 $ref: '#/components/schemas/VideoChannelList'
3943         '500':
3944           description: search index unavailable
3945
3946   /search/video-playlists:
3947     get:
3948       tags:
3949         - Search
3950       summary: Search playlists
3951       operationId: searchPlaylists
3952       parameters:
3953         - name: search
3954           in: query
3955           required: true
3956           description: >
3957             String to search. If the user can make a remote URI search, and the string is an URI then the
3958             PeerTube instance will fetch the remote object and add it to its database. Then,
3959             you can use the REST API to fetch the complete playlist information and interact with it.
3960           schema:
3961             type: string
3962         - $ref: '#/components/parameters/start'
3963         - $ref: '#/components/parameters/count'
3964         - $ref: '#/components/parameters/searchTarget'
3965         - $ref: '#/components/parameters/sort'
3966       callbacks:
3967         'searchTarget === search-index':
3968           $ref: '#/components/callbacks/searchIndex'
3969       responses:
3970         '200':
3971           description: successful operation
3972           content:
3973             application/json:
3974               schema:
3975                 type: object
3976                 properties:
3977                   total:
3978                     type: integer
3979                     example: 1
3980                   data:
3981                     type: array
3982                     items:
3983                       $ref: '#/components/schemas/VideoPlaylist'
3984         '500':
3985           description: search index unavailable
3986
3987   /blocklist/status:
3988     get:
3989       tags:
3990         - Account Blocks
3991         - Server Blocks
3992       summary: Get block status of accounts/hosts
3993       parameters:
3994         -
3995           name: 'accounts'
3996           in: query
3997           description: 'Check if these accounts are blocked'
3998           example: [ 'goofy@example.com', 'donald@example.com' ]
3999           schema:
4000             type: array
4001             items:
4002               type: string
4003         -
4004           name: 'hosts'
4005           in: query
4006           description: 'Check if these hosts are blocked'
4007           example: [ 'example.com' ]
4008           schema:
4009             type: array
4010             items:
4011               type: string
4012       responses:
4013         '200':
4014           description: successful operation
4015           content:
4016             'application/json':
4017               schema:
4018                 $ref: '#/components/schemas/BlockStatus'
4019
4020   /server/blocklist/accounts:
4021     get:
4022       tags:
4023         - Account Blocks
4024       summary: List account blocks
4025       security:
4026         - OAuth2:
4027           - admin
4028       parameters:
4029         - $ref: '#/components/parameters/start'
4030         - $ref: '#/components/parameters/count'
4031         - $ref: '#/components/parameters/sort'
4032       responses:
4033         '200':
4034           description: successful operation
4035     post:
4036       tags:
4037         - Account Blocks
4038       summary: Block an account
4039       security:
4040         - OAuth2:
4041           - admin
4042       requestBody:
4043         content:
4044           application/json:
4045             schema:
4046               type: object
4047               properties:
4048                 accountName:
4049                   type: string
4050                   example: chocobozzz@example.org
4051                   description: account to block, in the form `username@domain`
4052               required:
4053                 - accountName
4054       responses:
4055         '200':
4056           description: successful operation
4057         '409':
4058           description: self-blocking forbidden
4059
4060   '/server/blocklist/accounts/{accountName}':
4061     delete:
4062       tags:
4063         - Account Blocks
4064       summary: Unblock an account by its handle
4065       security:
4066         - OAuth2:
4067           - admin
4068       parameters:
4069         - name: accountName
4070           in: path
4071           required: true
4072           description: account to unblock, in the form `username@domain`
4073           schema:
4074             type: string
4075       responses:
4076         '201':
4077           description: successful operation
4078         '404':
4079           description: account or account block does not exist
4080
4081   /server/blocklist/servers:
4082     get:
4083       tags:
4084         - Server Blocks
4085       summary: List server blocks
4086       security:
4087         - OAuth2:
4088           - admin
4089       parameters:
4090         - $ref: '#/components/parameters/start'
4091         - $ref: '#/components/parameters/count'
4092         - $ref: '#/components/parameters/sort'
4093       responses:
4094         '200':
4095           description: successful operation
4096     post:
4097       tags:
4098         - Server Blocks
4099       summary: Block a server
4100       security:
4101         - OAuth2:
4102           - admin
4103       requestBody:
4104         content:
4105           application/json:
4106             schema:
4107               type: object
4108               properties:
4109                 host:
4110                   type: string
4111                   format: hostname
4112                   description: server domain to block
4113               required:
4114                 - host
4115       responses:
4116         '204':
4117           description: successful operation
4118         '409':
4119           description: self-blocking forbidden
4120
4121   '/server/blocklist/servers/{host}':
4122     delete:
4123       tags:
4124         - Server Blocks
4125       summary: Unblock a server by its domain
4126       security:
4127         - OAuth2:
4128           - admin
4129       parameters:
4130         - name: host
4131           in: path
4132           required: true
4133           description: server domain to unblock
4134           schema:
4135             type: string
4136             format: hostname
4137       responses:
4138         '204':
4139           description: successful operation
4140         '404':
4141           description: account block does not exist
4142
4143   /server/redundancy/{host}:
4144     put:
4145       tags:
4146         - Instance Redundancy
4147       summary: Update a server redundancy policy
4148       security:
4149         - OAuth2:
4150           - admin
4151       parameters:
4152         - name: host
4153           in: path
4154           required: true
4155           description: server domain to mirror
4156           schema:
4157             type: string
4158             format: hostname
4159       requestBody:
4160         content:
4161           application/json:
4162             schema:
4163               type: object
4164               properties:
4165                 redundancyAllowed:
4166                   type: boolean
4167                   description: allow mirroring of the host's local videos
4168               required:
4169                 - redundancyAllowed
4170       responses:
4171         '204':
4172           description: successful operation
4173         '404':
4174           description: server is not already known
4175
4176   /server/redundancy/videos:
4177     get:
4178       tags:
4179         - Video Mirroring
4180       summary: List videos being mirrored
4181       operationId: getMirroredVideos
4182       security:
4183         - OAuth2:
4184           - admin
4185       parameters:
4186         - name: target
4187           in: query
4188           required: true
4189           description: direction of the mirror
4190           schema:
4191             type: string
4192             enum:
4193               - my-videos
4194               - remote-videos
4195         - $ref: '#/components/parameters/start'
4196         - $ref: '#/components/parameters/count'
4197         - $ref: '#/components/parameters/videoRedundanciesSort'
4198       responses:
4199         '200':
4200           description: successful operation
4201           content:
4202             application/json:
4203               schema:
4204                 type: array
4205                 items:
4206                   $ref: '#/components/schemas/VideoRedundancy'
4207     post:
4208       tags:
4209         - Video Mirroring
4210       summary: Mirror a video
4211       operationId: putMirroredVideo
4212       security:
4213         - OAuth2:
4214           - admin
4215       requestBody:
4216         content:
4217           application/json:
4218             schema:
4219               type: object
4220               properties:
4221                 videoId:
4222                   $ref: '#/components/schemas/Video/properties/id'
4223               required:
4224                 - videoId
4225       responses:
4226         '204':
4227           description: successful operation
4228         '400':
4229           description: cannot mirror a local video
4230         '404':
4231           description: video does not exist
4232         '409':
4233           description: video is already mirrored
4234
4235   /server/redundancy/videos/{redundancyId}:
4236     delete:
4237       tags:
4238         - Video Mirroring
4239       summary: Delete a mirror done on a video
4240       operationId: delMirroredVideo
4241       security:
4242         - OAuth2:
4243           - admin
4244       parameters:
4245         - name: redundancyId
4246           in: path
4247           required: true
4248           description: id of an existing redundancy on a video
4249           schema:
4250             type: string
4251       responses:
4252         '204':
4253           description: successful operation
4254         '404':
4255           description: video redundancy not found
4256
4257   '/feeds/video-comments.{format}':
4258     get:
4259       tags:
4260         - Feeds
4261       summary: List comments on videos
4262       operationId: getSyndicatedComments
4263       parameters:
4264         - name: format
4265           in: path
4266           required: true
4267           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4268           schema:
4269             type: string
4270             enum:
4271               - xml
4272               - rss
4273               - rss2
4274               - atom
4275               - atom1
4276               - json
4277               - json1
4278         - name: videoId
4279           in: query
4280           description: 'limit listing to a specific video'
4281           schema:
4282             type: string
4283         - name: accountId
4284           in: query
4285           description: 'limit listing to a specific account'
4286           schema:
4287             type: string
4288         - name: accountName
4289           in: query
4290           description: 'limit listing to a specific account'
4291           schema:
4292             type: string
4293         - name: videoChannelId
4294           in: query
4295           description: 'limit listing to a specific video channel'
4296           schema:
4297             type: string
4298         - name: videoChannelName
4299           in: query
4300           description: 'limit listing to a specific video channel'
4301           schema:
4302             type: string
4303       responses:
4304         '204':
4305           description: successful operation
4306           headers:
4307             Cache-Control:
4308               schema:
4309                 type: string
4310                 default: 'max-age=900' # 15 min cache
4311           content:
4312             application/xml:
4313               schema:
4314                 $ref: '#/components/schemas/VideoCommentsForXML'
4315               examples:
4316                 nightly:
4317                   externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4318             application/rss+xml:
4319               schema:
4320                 $ref: '#/components/schemas/VideoCommentsForXML'
4321               examples:
4322                 nightly:
4323                   externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
4324             text/xml:
4325               schema:
4326                 $ref: '#/components/schemas/VideoCommentsForXML'
4327               examples:
4328                 nightly:
4329                   externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
4330             application/atom+xml:
4331               schema:
4332                 $ref: '#/components/schemas/VideoCommentsForXML'
4333               examples:
4334                 nightly:
4335                   externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
4336             application/json:
4337               schema:
4338                 type: object
4339               examples:
4340                 nightly:
4341                   externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
4342         '400':
4343           x-summary: field inconsistencies
4344           description: >
4345             Arises when:
4346               - videoId filter is mixed with a channel filter
4347         '404':
4348           description: video, video channel or account not found
4349         '406':
4350           description: accept header unsupported
4351
4352   '/feeds/videos.{format}':
4353     get:
4354       tags:
4355         - Feeds
4356       summary: List videos
4357       operationId: getSyndicatedVideos
4358       parameters:
4359         - name: format
4360           in: path
4361           required: true
4362           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4363           schema:
4364             type: string
4365             enum:
4366               - xml
4367               - rss
4368               - rss2
4369               - atom
4370               - atom1
4371               - json
4372               - json1
4373         - name: accountId
4374           in: query
4375           description: 'limit listing to a specific account'
4376           schema:
4377             type: string
4378         - name: accountName
4379           in: query
4380           description: 'limit listing to a specific account'
4381           schema:
4382             type: string
4383         - name: videoChannelId
4384           in: query
4385           description: 'limit listing to a specific video channel'
4386           schema:
4387             type: string
4388         - name: videoChannelName
4389           in: query
4390           description: 'limit listing to a specific video channel'
4391           schema:
4392             type: string
4393         - $ref: '#/components/parameters/sort'
4394         - $ref: '#/components/parameters/nsfw'
4395         - $ref: '#/components/parameters/isLocal'
4396         - $ref: '#/components/parameters/include'
4397         - $ref: '#/components/parameters/privacyOneOf'
4398         - $ref: '#/components/parameters/hasHLSFiles'
4399         - $ref: '#/components/parameters/hasWebtorrentFiles'
4400       responses:
4401         '204':
4402           description: successful operation
4403           headers:
4404             Cache-Control:
4405               schema:
4406                 type: string
4407                 default: 'max-age=900' # 15 min cache
4408           content:
4409             application/xml:
4410               schema:
4411                 $ref: '#/components/schemas/VideosForXML'
4412               examples:
4413                 nightly:
4414                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4415             application/rss+xml:
4416               schema:
4417                 $ref: '#/components/schemas/VideosForXML'
4418               examples:
4419                 nightly:
4420                   externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
4421             text/xml:
4422               schema:
4423                 $ref: '#/components/schemas/VideosForXML'
4424               examples:
4425                 nightly:
4426                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
4427             application/atom+xml:
4428               schema:
4429                 $ref: '#/components/schemas/VideosForXML'
4430               examples:
4431                 nightly:
4432                   externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
4433             application/json:
4434               schema:
4435                 type: object
4436               examples:
4437                 nightly:
4438                   externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
4439         '404':
4440           description: video channel or account not found
4441         '406':
4442           description: accept header unsupported
4443
4444   '/feeds/subscriptions.{format}':
4445     get:
4446       tags:
4447         - Feeds
4448         - Account
4449       summary: List videos of subscriptions tied to a token
4450       operationId: getSyndicatedSubscriptionVideos
4451       parameters:
4452         - name: format
4453           in: path
4454           required: true
4455           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
4456           schema:
4457             type: string
4458             enum:
4459               - xml
4460               - rss
4461               - rss2
4462               - atom
4463               - atom1
4464               - json
4465               - json1
4466         - name: accountId
4467           in: query
4468           description: limit listing to a specific account
4469           schema:
4470             type: string
4471           required: true
4472         - name: token
4473           in: query
4474           description: private token allowing access
4475           schema:
4476             type: string
4477           required: true
4478         - $ref: '#/components/parameters/sort'
4479         - $ref: '#/components/parameters/nsfw'
4480         - $ref: '#/components/parameters/isLocal'
4481         - $ref: '#/components/parameters/include'
4482         - $ref: '#/components/parameters/privacyOneOf'
4483         - $ref: '#/components/parameters/hasHLSFiles'
4484         - $ref: '#/components/parameters/hasWebtorrentFiles'
4485       responses:
4486         '204':
4487           description: successful operation
4488           headers:
4489             Cache-Control:
4490               schema:
4491                 type: string
4492                 default: 'max-age=900' # 15 min cache
4493           content:
4494             application/xml:
4495               schema:
4496                 $ref: '#/components/schemas/VideosForXML'
4497             application/rss+xml:
4498               schema:
4499                 $ref: '#/components/schemas/VideosForXML'
4500             text/xml:
4501               schema:
4502                 $ref: '#/components/schemas/VideosForXML'
4503             application/atom+xml:
4504               schema:
4505                 $ref: '#/components/schemas/VideosForXML'
4506             application/json:
4507               schema:
4508                 type: object
4509         '406':
4510           description: accept header unsupported
4511
4512   /plugins:
4513     get:
4514       tags:
4515         - Plugins
4516       summary: List plugins
4517       operationId: getPlugins
4518       security:
4519         - OAuth2:
4520           - admin
4521       parameters:
4522         - name: pluginType
4523           in: query
4524           schema:
4525             type: integer
4526         - name: uninstalled
4527           in: query
4528           schema:
4529             type: boolean
4530         - $ref: '#/components/parameters/start'
4531         - $ref: '#/components/parameters/count'
4532         - $ref: '#/components/parameters/sort'
4533       responses:
4534         '200':
4535           description: successful operation
4536           content:
4537             application/json:
4538               schema:
4539                 $ref: '#/components/schemas/PluginResponse'
4540
4541   /plugins/available:
4542     get:
4543       tags:
4544         - Plugins
4545       summary: List available plugins
4546       operationId: getAvailablePlugins
4547       security:
4548         - OAuth2:
4549           - admin
4550       parameters:
4551         - name: search
4552           in: query
4553           schema:
4554             type: string
4555         - name: pluginType
4556           in: query
4557           schema:
4558             type: integer
4559         - name: currentPeerTubeEngine
4560           in: query
4561           schema:
4562             type: string
4563         - $ref: '#/components/parameters/start'
4564         - $ref: '#/components/parameters/count'
4565         - $ref: '#/components/parameters/sort'
4566       responses:
4567         '200':
4568           description: successful operation
4569           content:
4570             application/json:
4571               schema:
4572                 $ref: '#/components/schemas/PluginResponse'
4573         '503':
4574           description: plugin index unavailable
4575
4576   /plugins/install:
4577     post:
4578       tags:
4579         - Plugins
4580       summary: Install a plugin
4581       operationId: addPlugin
4582       security:
4583         - OAuth2:
4584           - admin
4585       requestBody:
4586         content:
4587           application/json:
4588             schema:
4589               oneOf:
4590                 - type: object
4591                   properties:
4592                     npmName:
4593                       type: string
4594                       example: peertube-plugin-auth-ldap
4595                   required:
4596                     - npmName
4597                   additionalProperties: false
4598                 - type: object
4599                   properties:
4600                     path:
4601                       type: string
4602                   required:
4603                     - path
4604                   additionalProperties: false
4605       responses:
4606         '204':
4607           description: successful operation
4608         '400':
4609           description: should have either `npmName` or `path` set
4610
4611   /plugins/update:
4612     post:
4613       tags:
4614         - Plugins
4615       summary: Update a plugin
4616       operationId: updatePlugin
4617       security:
4618         - OAuth2:
4619           - admin
4620       requestBody:
4621         content:
4622           application/json:
4623             schema:
4624               oneOf:
4625                 - type: object
4626                   properties:
4627                     npmName:
4628                       type: string
4629                       example: peertube-plugin-auth-ldap
4630                   required:
4631                     - npmName
4632                   additionalProperties: false
4633                 - type: object
4634                   properties:
4635                     path:
4636                       type: string
4637                   required:
4638                     - path
4639                   additionalProperties: false
4640       responses:
4641         '204':
4642           description: successful operation
4643         '400':
4644           description: should have either `npmName` or `path` set
4645         '404':
4646           description: existing plugin not found
4647
4648   /plugins/uninstall:
4649     post:
4650       tags:
4651         - Plugins
4652       summary: Uninstall a plugin
4653       operationId: uninstallPlugin
4654       security:
4655         - OAuth2:
4656           - admin
4657       requestBody:
4658         content:
4659           application/json:
4660             schema:
4661               type: object
4662               properties:
4663                 npmName:
4664                   type: string
4665                   description: name of the plugin/theme in its package.json
4666                   example: peertube-plugin-auth-ldap
4667               required:
4668                 - npmName
4669       responses:
4670         '204':
4671           description: successful operation
4672         '404':
4673           description: existing plugin not found
4674
4675   /plugins/{npmName}:
4676     get:
4677       tags:
4678         - Plugins
4679       summary: Get a plugin
4680       operationId: getPlugin
4681       security:
4682         - OAuth2:
4683           - admin
4684       parameters:
4685         - $ref: '#/components/parameters/npmName'
4686       responses:
4687         '200':
4688           description: successful operation
4689           content:
4690             application/json:
4691               schema:
4692                 $ref: '#/components/schemas/Plugin'
4693         '404':
4694           description: plugin not found
4695
4696   /plugins/{npmName}/settings:
4697     put:
4698       tags:
4699         - Plugins
4700       summary: Set a plugin's settings
4701       security:
4702         - OAuth2:
4703           - admin
4704       parameters:
4705         - $ref: '#/components/parameters/npmName'
4706       requestBody:
4707         content:
4708           application/json:
4709             schema:
4710               type: object
4711               properties:
4712                 settings:
4713                   type: object
4714                   additionalProperties: true
4715       responses:
4716         '204':
4717           description: successful operation
4718         '404':
4719           description: plugin not found
4720
4721   /plugins/{npmName}/public-settings:
4722     get:
4723       tags:
4724         - Plugins
4725       summary: Get a plugin's public settings
4726       parameters:
4727         - $ref: '#/components/parameters/npmName'
4728       responses:
4729         '200':
4730           description: successful operation
4731           content:
4732             application/json:
4733               schema:
4734                 type: object
4735                 additionalProperties: true
4736         '404':
4737           description: plugin not found
4738
4739   /plugins/{npmName}/registered-settings:
4740     get:
4741       tags:
4742         - Plugins
4743       summary: Get a plugin's registered settings
4744       security:
4745         - OAuth2:
4746           - admin
4747       parameters:
4748         - $ref: '#/components/parameters/npmName'
4749       responses:
4750         '200':
4751           description: successful operation
4752           content:
4753             application/json:
4754               schema:
4755                 type: object
4756                 additionalProperties: true
4757         '404':
4758           description: plugin not found
4759
4760 servers:
4761   - url: 'https://peertube2.cpy.re/api/v1'
4762     description: Live Test Server (live data - latest nightly version)
4763   - url: 'https://peertube3.cpy.re/api/v1'
4764     description: Live Test Server (live data - latest RC version)
4765   - url: 'https://peertube.cpy.re/api/v1'
4766     description: Live Test Server (live data - stable version)
4767 components:
4768   parameters:
4769     start:
4770       name: start
4771       in: query
4772       required: false
4773       description: Offset used to paginate results
4774       schema:
4775         type: integer
4776         minimum: 0
4777     count:
4778       name: count
4779       in: query
4780       required: false
4781       description: "Number of items to return"
4782       schema:
4783         type: integer
4784         default: 15
4785         maximum: 100
4786         minimum: 1
4787     sort:
4788       name: sort
4789       in: query
4790       required: false
4791       description: Sort column
4792       schema:
4793         type: string
4794         example: -createdAt
4795     search:
4796       name: search
4797       in: query
4798       required: false
4799       description: Plain text search, applied to various parts of the model depending on endpoint
4800       schema:
4801         type: string
4802     searchTarget:
4803       name: searchTarget
4804       in: query
4805       required: false
4806       description: >
4807         If the administrator enabled search index support, you can override the default search target.
4808
4809
4810         **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4811         It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4812           * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4813           then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4814           After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4815           * 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
4816           the data from the origin instance API
4817       schema:
4818         type: string
4819         enum:
4820           - 'local'
4821           - 'search-index'
4822     videosSort:
4823       name: sort
4824       in: query
4825       required: false
4826       schema:
4827         type: string
4828         enum:
4829           - name
4830           - -duration
4831           - -createdAt
4832           - -publishedAt
4833           - -views
4834           - -likes
4835           - -trending
4836           - -hot
4837           - -best
4838         description: >
4839           Sort videos by criteria (prefixing with `-` means `DESC` order):
4840             * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
4841             * `best` - Same than `hot`, but also takes into account user video history
4842             * `trending` - Sort videos by recent views ("recent" is defined by the admin)
4843             * `views` - Sort videos using their `views` counter
4844             * `publishedAt` - Sort by video publication date (when it became publicly available)
4845     videosSearchSort:
4846       name: sort
4847       in: query
4848       required: false
4849       description: >
4850         Sort videos by criteria (prefixing with `-` means `DESC` order):
4851       schema:
4852         type: string
4853         enum:
4854         - name
4855         - -duration
4856         - -createdAt
4857         - -publishedAt
4858         - -views
4859         - -likes
4860         - -match
4861     commentsSort:
4862       name: sort
4863       in: query
4864       required: false
4865       description: Sort comments by criteria
4866       schema:
4867         type: string
4868         enum:
4869         - -createdAt
4870         - -totalReplies
4871     blacklistsSort:
4872       name: sort
4873       in: query
4874       required: false
4875       description: Sort blocklists by criteria
4876       schema:
4877         type: string
4878         enum:
4879         - -id
4880         - name
4881         - -duration
4882         - -views
4883         - -likes
4884         - -dislikes
4885         - -uuid
4886         - -createdAt
4887     usersSearch:
4888       name: search
4889       in: query
4890       required: false
4891       description: Plain text search that will match with user usernames or emails
4892       schema:
4893         type: string
4894     usersBlocked:
4895       name: blocked
4896       in: query
4897       required: false
4898       description: Filter results down to (un)banned users
4899       schema:
4900         type: boolean
4901     usersSort:
4902       name: sort
4903       in: query
4904       required: false
4905       description: Sort users by criteria
4906       schema:
4907         type: string
4908         enum:
4909         - -id
4910         - -username
4911         - -createdAt
4912     abusesSort:
4913       name: sort
4914       in: query
4915       required: false
4916       description: Sort abuses by criteria
4917       schema:
4918         type: string
4919         enum:
4920         - -id
4921         - -createdAt
4922         - -state
4923     videoRedundanciesSort:
4924       name: sort
4925       in: query
4926       required: false
4927       description: Sort abuses by criteria
4928       schema:
4929         type: string
4930         enum:
4931         - name
4932     followersSort:
4933       name: sort
4934       in: query
4935       required: false
4936       description: Sort followers by criteria
4937       schema:
4938         type: string
4939         enum:
4940         - createdAt
4941     name:
4942       name: name
4943       in: path
4944       required: true
4945       description: The username or handle of the account
4946       schema:
4947         type: string
4948         example: chocobozzz | chocobozzz@example.org
4949     id:
4950       name: id
4951       in: path
4952       required: true
4953       description: Entity id
4954       schema:
4955         $ref: '#/components/schemas/id'
4956     idOrUUID:
4957       name: id
4958       in: path
4959       required: true
4960       description: The object id, uuid or short uuid
4961       schema:
4962         oneOf:
4963           - $ref: '#/components/schemas/id'
4964           - $ref: '#/components/schemas/UUIDv4'
4965           - $ref: '#/components/schemas/shortUUID'
4966     playlistId:
4967       name: playlistId
4968       in: path
4969       required: true
4970       description: Playlist id
4971       schema:
4972         $ref: '#/components/schemas/VideoPlaylist/properties/id'
4973     playlistElementId:
4974       name: playlistElementId
4975       in: path
4976       required: true
4977       description: Playlist element id
4978       schema:
4979         $ref: '#/components/schemas/id'
4980     abuseId:
4981       name: abuseId
4982       in: path
4983       required: true
4984       description: Abuse id
4985       schema:
4986         $ref: '#/components/schemas/Abuse/properties/id'
4987     abuseMessageId:
4988       name: abuseMessageId
4989       in: path
4990       required: true
4991       description: Abuse message id
4992       schema:
4993         $ref: '#/components/schemas/AbuseMessage/properties/id'
4994     captionLanguage:
4995       name: captionLanguage
4996       in: path
4997       required: true
4998       description: The caption language
4999       schema:
5000         $ref: '#/components/schemas/VideoLanguageSet'
5001     channelHandle:
5002       name: channelHandle
5003       in: path
5004       required: true
5005       description: The video channel handle
5006       schema:
5007         type: string
5008         example: my_username | my_username@example.com
5009     subscriptionHandle:
5010       name: subscriptionHandle
5011       in: path
5012       required: true
5013       description: The subscription handle
5014       schema:
5015         type: string
5016         example: my_username | my_username@example.com
5017     threadId:
5018       name: threadId
5019       in: path
5020       required: true
5021       description: The thread id (root comment id)
5022       schema:
5023         type: integer
5024     commentId:
5025       name: commentId
5026       in: path
5027       required: true
5028       description: The comment id
5029       schema:
5030         $ref: '#/components/schemas/VideoComment/properties/id'
5031     isLive:
5032       name: isLive
5033       in: query
5034       required: false
5035       description: whether or not the video is a live
5036       schema:
5037         type: boolean
5038     categoryOneOf:
5039       name: categoryOneOf
5040       in: query
5041       required: false
5042       description: category id of the video (see [/videos/categories](#operation/getCategories))
5043       schema:
5044         oneOf:
5045         - $ref: '#/components/schemas/VideoCategorySet'
5046         - type: array
5047           items:
5048             $ref: '#/components/schemas/VideoCategorySet'
5049       style: form
5050       explode: false
5051     tagsOneOf:
5052       name: tagsOneOf
5053       in: query
5054       required: false
5055       description: tag(s) of the video
5056       schema:
5057         oneOf:
5058         - type: string
5059         - type: array
5060           maxItems: 5
5061           items:
5062             type: string
5063       style: form
5064       explode: false
5065     tagsAllOf:
5066       name: tagsAllOf
5067       in: query
5068       required: false
5069       description: tag(s) of the video, where all should be present in the video
5070       schema:
5071         oneOf:
5072         - type: string
5073         - type: array
5074           items:
5075             type: string
5076       style: form
5077       explode: false
5078     languageOneOf:
5079       name: languageOneOf
5080       in: query
5081       required: false
5082       description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
5083       schema:
5084         oneOf:
5085         - $ref: '#/components/schemas/VideoLanguageSet'
5086         - type: array
5087           items:
5088             $ref: '#/components/schemas/VideoLanguageSet'
5089       style: form
5090       explode: false
5091     licenceOneOf:
5092       name: licenceOneOf
5093       in: query
5094       required: false
5095       description: licence id of the video (see [/videos/licences](#operation/getLicences))
5096       schema:
5097         oneOf:
5098         - $ref: '#/components/schemas/VideoLicenceSet'
5099         - type: array
5100           items:
5101             $ref: '#/components/schemas/VideoLicenceSet'
5102       style: form
5103       explode: false
5104     skipCount:
5105       name: skipCount
5106       in: query
5107       required: false
5108       description: if you don't need the `total` in the response
5109       schema:
5110         type: string
5111         enum:
5112           - 'true'
5113           - 'false'
5114         default: 'false'
5115     nsfw:
5116       name: nsfw
5117       in: query
5118       required: false
5119       description: whether to include nsfw videos, if any
5120       schema:
5121         type: string
5122         enum:
5123         - 'true'
5124         - 'false'
5125     isLocal:
5126       name: isLocal
5127       in: query
5128       required: false
5129       schema:
5130         type: boolean
5131       description: '**PeerTube >= 4.0** Display only local or remote videos'
5132     hasHLSFiles:
5133       name: hasHLSFiles
5134       in: query
5135       required: false
5136       schema:
5137         type: boolean
5138       description: '**PeerTube >= 4.0** Display only videos that have HLS files'
5139     hasWebtorrentFiles:
5140       name: hasWebtorrentFiles
5141       in: query
5142       required: false
5143       schema:
5144         type: boolean
5145       description: '**PeerTube >= 4.0** Display only videos that have WebTorrent files'
5146     privacyOneOf:
5147       name: privacyOneOf
5148       in: query
5149       required: false
5150       schema:
5151         $ref: '#/components/schemas/VideoPrivacySet'
5152       description: '**PeerTube >= 4.0** Display only videos in this specific privacy/privacies'
5153     include:
5154       name: include
5155       in: query
5156       required: false
5157       schema:
5158         type: integer
5159         enum:
5160         - 0
5161         - 1
5162         - 2
5163         - 4
5164         - 8
5165       description: >
5166         **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
5167
5168         - `0` NONE
5169
5170         - `1` NOT_PUBLISHED_STATE
5171
5172         - `2` BLACKLISTED
5173
5174         - `4` BLOCKED_OWNER
5175
5176         - `8` FILES
5177     subscriptionsUris:
5178       name: uris
5179       in: query
5180       required: true
5181       description: list of uris to check if each is part of the user subscriptions
5182       schema:
5183         type: array
5184         items:
5185           type: string
5186           format: uri
5187     npmName:
5188       name: npmName
5189       in: path
5190       required: true
5191       description: name of the plugin/theme on npmjs.com or in its package.json
5192       schema:
5193         type: string
5194         example: peertube-plugin-auth-ldap
5195     jobType:
5196       name: jobType
5197       in: query
5198       required: false
5199       description: job type
5200       schema:
5201         type: string
5202         enum:
5203           - activitypub-follow
5204           - activitypub-http-broadcast
5205           - activitypub-http-fetcher
5206           - activitypub-http-unicast
5207           - email
5208           - video-transcoding
5209           - video-file-import
5210           - video-import
5211           - videos-views-stats
5212           - activitypub-refresher
5213           - video-redundancy
5214           - video-live-ending
5215     followState:
5216       name: state
5217       in: query
5218       schema:
5219         type: string
5220         enum:
5221           - pending
5222           - accepted
5223     actorType:
5224       name: actorType
5225       in: query
5226       schema:
5227         type: string
5228         enum:
5229           - Person
5230           - Application
5231           - Group
5232           - Service
5233           - Organization
5234   securitySchemes:
5235     OAuth2:
5236       description: |
5237         Authenticating via OAuth requires the following steps:
5238         - Have an activated account
5239         - [Generate] an access token for that account at `/api/v1/users/token`.
5240         - Make requests with the *Authorization: Bearer <token\>* header
5241         - Profit, depending on the role assigned to the account
5242
5243         Note that the __access token is valid for 1 day__ and is given
5244         along with a __refresh token valid for 2 weeks__.
5245
5246         [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
5247       type: oauth2
5248       flows:
5249         password:
5250           tokenUrl: /api/v1/users/token
5251           scopes:
5252             admin: Admin scope
5253             moderator: Moderator scope
5254             user: User scope
5255   schemas:
5256     # Resuable core properties
5257     id:
5258       type: integer
5259       minimum: 1
5260       example: 42
5261     UUIDv4:
5262       type: string
5263       format: uuid
5264       example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
5265       pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
5266       minLength: 36
5267       maxLength: 36
5268     shortUUID:
5269       type: string
5270       description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
5271       example: 2y84q2MQUMWPbiEcxNXMgC
5272     username:
5273       type: string
5274       description: immutable name of the user, used to find or mention its actor
5275       example: chocobozzz
5276       pattern: '/^[a-z0-9._]+$/'
5277       minLength: 1
5278       maxLength: 50
5279     usernameChannel:
5280       type: string
5281       description: immutable name of the channel, used to interact with its actor
5282       example: framasoft_videos
5283       pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
5284       minLength: 1
5285       maxLength: 50
5286     password:
5287       type: string
5288       format: password
5289       minLength: 6
5290       maxLength: 255
5291
5292     VideoCategorySet:
5293       type: integer
5294       description: category id of the video (see [/videos/categories](#operation/getCategories))
5295       example: 15
5296     VideoConstantNumber-Category:
5297       properties:
5298         id:
5299           $ref: '#/components/schemas/VideoCategorySet'
5300         label:
5301           type: string
5302           example: Science & Technology
5303
5304     VideoLicenceSet:
5305       type: integer
5306       description: licence id of the video (see [/videos/licences](#operation/getLicences))
5307       example: 2
5308     VideoConstantNumber-Licence:
5309       properties:
5310         id:
5311           $ref: '#/components/schemas/VideoLicenceSet'
5312         label:
5313           type: string
5314           example: Attribution - Share Alike
5315
5316     VideoLanguageSet:
5317       type: string
5318       description: language id of the video (see [/videos/languages](#operation/getLanguages))
5319       example: en
5320     VideoConstantString-Language:
5321       properties:
5322         id:
5323           $ref: '#/components/schemas/VideoLanguageSet'
5324         label:
5325           type: string
5326           example: English
5327
5328     VideoPlaylistPrivacySet:
5329       type: integer
5330       enum:
5331         - 1
5332         - 2
5333         - 3
5334       description: Video playlist privacy policy (see [/video-playlists/privacies])
5335     VideoPlaylistPrivacyConstant:
5336       properties:
5337         id:
5338           $ref: '#/components/schemas/VideoPlaylistPrivacySet'
5339         label:
5340           type: string
5341
5342     VideoPlaylistTypeSet:
5343       type: integer
5344       enum:
5345         - 1
5346         - 2
5347       description: The video playlist type (Regular = `1`, Watch Later = `2`)
5348     VideoPlaylistTypeConstant:
5349       properties:
5350         id:
5351           $ref: '#/components/schemas/VideoPlaylistTypeSet'
5352         label:
5353           type: string
5354
5355     VideoPrivacySet:
5356       type: integer
5357       enum:
5358         - 1
5359         - 2
5360         - 3
5361         - 4
5362       description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
5363     VideoPrivacyConstant:
5364       properties:
5365         id:
5366           $ref: '#/components/schemas/VideoPrivacySet'
5367         label:
5368           type: string
5369
5370     BlockStatus:
5371       properties:
5372         accounts:
5373           type: object
5374           additionalProperties:
5375             x-additionalPropertiesName: account
5376             type: object
5377             properties:
5378               blockedByServer:
5379                 type: boolean
5380               blockedByUser:
5381                 type: boolean
5382         hosts:
5383           type: object
5384           additionalProperties:
5385             x-additionalPropertiesName: host
5386             type: object
5387             properties:
5388               blockedByServer:
5389                 type: boolean
5390               blockedByUser:
5391                 type: boolean
5392
5393     NSFWPolicy:
5394       type: string
5395       enum:
5396         - display
5397         - blur
5398         - do_not_list
5399
5400     UserRole:
5401       type: integer
5402       enum:
5403         - 0
5404         - 1
5405         - 2
5406       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
5407       example: 2
5408     UserAdminFlags:
5409       type: integer
5410       enum:
5411         - 0
5412         - 1
5413       description: 'Admin flags for the user (None = `0`, Bypass video blocklist = `1`)'
5414       example: 1
5415
5416     LiveVideoLatencyMode:
5417       type: integer
5418       enum:
5419         - 1
5420         - 2
5421         - 3
5422       description: 'The live latency mode (Default = `1`, HIght latency = `2`, Small Latency = `3`)'
5423
5424     VideoStateConstant:
5425       properties:
5426         id:
5427           type: integer
5428           enum:
5429             - 1
5430             - 2
5431             - 3
5432             - 4
5433             - 5
5434             - 6
5435             - 7
5436             - 8
5437             - 9
5438           description: |
5439             The video state:
5440             - `1`: Published
5441             - `2`: To transcode
5442             - `3`: To import
5443             - `4`: Waiting for live stream
5444             - `5`: Live ended
5445             - `6`: To move to an external storage (object storage...)
5446             - `7`: Transcoding failed
5447             - `8`: Moving to an external storage failed
5448             - `9`: To edit using studio edition feature
5449         label:
5450           type: string
5451
5452     AbuseStateSet:
5453       type: integer
5454       enum:
5455         - 1
5456         - 2
5457         - 3
5458       description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
5459     AbuseStateConstant:
5460       properties:
5461         id:
5462           $ref: '#/components/schemas/AbuseStateSet'
5463         label:
5464           type: string
5465     AbusePredefinedReasons:
5466       type: array
5467       items:
5468         type: string
5469         enum:
5470         - violentOrAbusive
5471         - hatefulOrAbusive
5472         - spamOrMisleading
5473         - privacy
5474         - rights
5475         - serverRules
5476         - thumbnails
5477         - captions
5478       example: [spamOrMisleading]
5479
5480     VideoResolutionSet:
5481       type: integer
5482       description: |
5483         Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
5484
5485         `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
5486       example: 240
5487     VideoResolutionConstant:
5488       description: resolutions and their labels for the video
5489       properties:
5490         id:
5491           $ref: '#/components/schemas/VideoResolutionSet'
5492         label:
5493           type: string
5494           example: 240p
5495     VideoScheduledUpdate:
5496       properties:
5497         privacy:
5498           $ref: '#/components/schemas/VideoPrivacySet'
5499         updateAt:
5500           type: string
5501           format: date
5502           description: When to update the video
5503       required:
5504         - updateAt
5505     AccountSummary:
5506       properties:
5507         id:
5508           type: integer
5509         name:
5510           type: string
5511         displayName:
5512           type: string
5513         url:
5514           type: string
5515           format: url
5516         host:
5517           type: string
5518           format: hostname
5519         avatars:
5520           type: array
5521           items:
5522             $ref: '#/components/schemas/ActorImage'
5523     VideoChannelSummary:
5524       properties:
5525         id:
5526           $ref: '#/components/schemas/id'
5527         name:
5528           type: string
5529         displayName:
5530           type: string
5531         url:
5532           type: string
5533           format: url
5534         host:
5535           type: string
5536           format: hostname
5537         avatars:
5538           type: array
5539           items:
5540             $ref: '#/components/schemas/ActorImage'
5541     PlaylistElement:
5542       properties:
5543         position:
5544           type: integer
5545         startTimestamp:
5546           type: integer
5547           format: seconds
5548         stopTimestamp:
5549           type: integer
5550           format: seconds
5551         video:
5552           nullable: true
5553           allOf:
5554             - $ref: '#/components/schemas/Video'
5555     VideoFile:
5556       readOnly: true
5557       properties:
5558         magnetUri:
5559           type: string
5560           format: uri
5561           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
5562           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5563         resolution:
5564           $ref: '#/components/schemas/VideoResolutionConstant'
5565         size:
5566           type: integer
5567           description: Video file size in bytes
5568         torrentUrl:
5569           type: string
5570           description: Direct URL of the torrent file
5571           format: url
5572         torrentDownloadUrl:
5573           type: string
5574           description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
5575           format: url
5576         fileUrl:
5577           type: string
5578           description: Direct URL of the video
5579           format: url
5580         fileDownloadUrl:
5581           type: string
5582           description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
5583           format: url
5584         fps:
5585           type: number
5586           description: Frames per second of the video file
5587         metadataUrl:
5588           type: string
5589           format: url
5590           description: URL dereferencing the output of ffprobe on the file
5591     VideoStreamingPlaylists:
5592       allOf:
5593         - type: object
5594           properties:
5595             id:
5596               $ref: '#/components/schemas/id'
5597             type:
5598               type: integer
5599               enum:
5600                 - 1
5601               description: |
5602                 Playlist type:
5603                 - `1`: HLS
5604         - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
5605     VideoStreamingPlaylists-HLS:
5606       properties:
5607         playlistUrl:
5608           type: string
5609           format: url
5610         segmentsSha256Url:
5611           type: string
5612           format: url
5613         files:
5614           type: array
5615           description: |
5616             Video files associated to this playlist.
5617
5618             The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
5619           items:
5620             $ref: '#/components/schemas/VideoFile'
5621         redundancies:
5622           type: array
5623           items:
5624             type: object
5625             properties:
5626               baseUrl:
5627                 type: string
5628                 format: url
5629     VideoInfo:
5630       properties:
5631         id:
5632           $ref: '#/components/schemas/Video/properties/id'
5633         uuid:
5634           $ref: '#/components/schemas/Video/properties/uuid'
5635         name:
5636           $ref: '#/components/schemas/Video/properties/name'
5637     Video:
5638       properties:
5639         id:
5640           description: object id for the video
5641           allOf:
5642             - $ref: '#/components/schemas/id'
5643         uuid:
5644           description: universal identifier for the video, that can be used across instances
5645           allOf:
5646             - $ref: '#/components/schemas/UUIDv4'
5647         shortUUID:
5648           allOf:
5649             - $ref: '#/components/schemas/shortUUID'
5650         isLive:
5651           type: boolean
5652         createdAt:
5653           type: string
5654           format: date-time
5655           example: 2017-10-01T10:52:46.396Z
5656           description: time at which the video object was first drafted
5657         publishedAt:
5658           type: string
5659           format: date-time
5660           example: 2018-10-01T10:52:46.396Z
5661           description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
5662         updatedAt:
5663           type: string
5664           format: date-time
5665           example: 2021-05-04T08:01:01.502Z
5666           description: last time the video's metadata was modified
5667         originallyPublishedAt:
5668           type: string
5669           format: date-time
5670           example: 2010-10-01T10:52:46.396Z
5671           description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
5672         category:
5673           allOf:
5674             - $ref: '#/components/schemas/VideoConstantNumber-Category'
5675           description: category in which the video is classified
5676         licence:
5677           allOf:
5678             - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5679           description: licence under which the video is distributed
5680         language:
5681           allOf:
5682             - $ref: '#/components/schemas/VideoConstantString-Language'
5683           description: main language used in the video
5684         privacy:
5685           allOf:
5686             - $ref: '#/components/schemas/VideoPrivacyConstant'
5687           description: privacy policy used to distribute the video
5688         description:
5689           type: string
5690           example: |
5691             **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5692             **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5693           minLength: 3
5694           maxLength: 250
5695           description: |
5696             truncated description of the video, written in Markdown.
5697             Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5698         duration:
5699           type: integer
5700           example: 1419
5701           format: seconds
5702           description: duration of the video in seconds
5703         isLocal:
5704           type: boolean
5705         name:
5706           type: string
5707           description: title of the video
5708           example: What is PeerTube?
5709           minLength: 3
5710           maxLength: 120
5711         thumbnailPath:
5712           type: string
5713           example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5714         previewPath:
5715           type: string
5716           example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5717         embedPath:
5718           type: string
5719           example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5720         views:
5721           type: integer
5722           example: 1337
5723         likes:
5724           type: integer
5725           example: 42
5726         dislikes:
5727           type: integer
5728           example: 7
5729         nsfw:
5730           type: boolean
5731         waitTranscoding:
5732           type: boolean
5733           nullable: true
5734         state:
5735           allOf:
5736             - $ref: '#/components/schemas/VideoStateConstant'
5737           description: represents the internal state of the video processing within the PeerTube instance
5738         scheduledUpdate:
5739           nullable: true
5740           allOf:
5741             - $ref: '#/components/schemas/VideoScheduledUpdate'
5742         blacklisted:
5743           nullable: true
5744           type: boolean
5745         blacklistedReason:
5746           nullable: true
5747           type: string
5748         account:
5749           $ref: '#/components/schemas/AccountSummary'
5750         channel:
5751           $ref: '#/components/schemas/VideoChannelSummary'
5752         userHistory:
5753           nullable: true
5754           type: object
5755           properties:
5756             currentTime:
5757               type: integer
5758     VideoDetails:
5759       allOf:
5760         - $ref: '#/components/schemas/Video'
5761         - type: object
5762           properties:
5763             viewers:
5764               type: integer
5765               description: If the video is a live, you have the amount of current viewers
5766             descriptionPath:
5767               type: string
5768               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5769               description: path at which to get the full description of maximum `10000` characters
5770             support:
5771               type: string
5772               description: A text tell the audience how to support the video creator
5773               example: Please support our work on https://soutenir.framasoft.org/en/ <3
5774               minLength: 3
5775               maxLength: 1000
5776             channel:
5777               $ref: '#/components/schemas/VideoChannel'
5778             account:
5779               $ref: '#/components/schemas/Account'
5780             tags:
5781               example: [flowers, gardening]
5782               type: array
5783               minItems: 1
5784               maxItems: 5
5785               items:
5786                 type: string
5787                 minLength: 2
5788                 maxLength: 30
5789             commentsEnabled:
5790               type: boolean
5791             downloadEnabled:
5792               type: boolean
5793             trackerUrls:
5794               type: array
5795               items:
5796                 type: string
5797                 format: url
5798               example:
5799                 - https://peertube2.cpy.re/tracker/announce
5800                 - wss://peertube2.cpy.re/tracker/socket
5801             files:
5802               type: array
5803               items:
5804                 $ref: '#/components/schemas/VideoFile'
5805               description: |
5806                 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5807
5808                 - field will be empty
5809                 - video files will be found in `streamingPlaylists[].files` field
5810             streamingPlaylists:
5811               type: array
5812               items:
5813                 $ref: '#/components/schemas/VideoStreamingPlaylists'
5814               description: |
5815                 HLS playlists/manifest files. If HLS is disabled on the server:
5816
5817                 - field will be empty
5818                 - video files will be found in `files` field
5819     FileRedundancyInformation:
5820       properties:
5821         id:
5822           $ref: '#/components/schemas/id'
5823         fileUrl:
5824           type: string
5825           format: url
5826         strategy:
5827           type: string
5828           enum:
5829             - manual
5830             - most-views
5831             - trending
5832             - recently-added
5833         size:
5834           type: integer
5835         createdAt:
5836           type: string
5837           format: date-time
5838         updatedAt:
5839           type: string
5840           format: date-time
5841         expiresOn:
5842           type: string
5843           format: date-time
5844     VideoRedundancy:
5845       properties:
5846         id:
5847           $ref: '#/components/schemas/id'
5848         name:
5849           type: string
5850         url:
5851           type: string
5852           format: url
5853         uuid:
5854           $ref: '#/components/schemas/UUIDv4'
5855         redundancies:
5856           type: object
5857           properties:
5858             files:
5859               type: array
5860               items:
5861                 $ref: '#/components/schemas/FileRedundancyInformation'
5862             streamingPlaylists:
5863               type: array
5864               items:
5865                 $ref: '#/components/schemas/FileRedundancyInformation'
5866     VideoImportStateConstant:
5867       properties:
5868         id:
5869           type: integer
5870           enum:
5871             - 1
5872             - 2
5873             - 3
5874           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5875         label:
5876           type: string
5877           example: Pending
5878     VideoCreateImport:
5879       allOf:
5880         - type: object
5881           additionalProperties: false
5882           oneOf:
5883             - properties:
5884                 targetUrl:
5885                   $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5886               required: [targetUrl]
5887             - properties:
5888                 magnetUri:
5889                   $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5890               required: [magnetUri]
5891             - properties:
5892                 torrentfile:
5893                   $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5894               required: [torrentfile]
5895         - $ref: '#/components/schemas/VideoUploadRequestCommon'
5896       required:
5897         - channelId
5898         - name
5899     VideoImport:
5900       properties:
5901         id:
5902           readOnly: true
5903           allOf:
5904             - $ref: '#/components/schemas/id'
5905         targetUrl:
5906           type: string
5907           format: url
5908           description: remote URL where to find the import's source video
5909           example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5910         magnetUri:
5911           type: string
5912           format: uri
5913           description: magnet URI allowing to resolve the import's source video
5914           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5915         torrentfile:
5916           writeOnly: true
5917           type: string
5918           format: binary
5919           description: Torrent file containing only the video file
5920         torrentName:
5921           readOnly: true
5922           type: string
5923         state:
5924           readOnly: true
5925           allOf:
5926             - $ref: '#/components/schemas/VideoImportStateConstant'
5927         error:
5928           readOnly: true
5929           type: string
5930         createdAt:
5931           readOnly: true
5932           type: string
5933           format: date-time
5934         updatedAt:
5935           readOnly: true
5936           type: string
5937           format: date-time
5938         video:
5939           readOnly: true
5940           nullable: true
5941           allOf:
5942             - $ref: '#/components/schemas/Video'
5943     VideoImportsList:
5944       properties:
5945         total:
5946           type: integer
5947           example: 1
5948         data:
5949           type: array
5950           maxItems: 100
5951           items:
5952             $ref: '#/components/schemas/VideoImport'
5953     Abuse:
5954       properties:
5955         id:
5956           $ref: '#/components/schemas/id'
5957         reason:
5958           type: string
5959           example: The video is a spam
5960           minLength: 2
5961           maxLength: 3000
5962         predefinedReasons:
5963           $ref: '#/components/schemas/AbusePredefinedReasons'
5964         reporterAccount:
5965           $ref: '#/components/schemas/Account'
5966         state:
5967           $ref: '#/components/schemas/AbuseStateConstant'
5968         moderationComment:
5969           type: string
5970           example: Decided to ban the server since it spams us regularly
5971           minLength: 2
5972           maxLength: 3000
5973         video:
5974           $ref: '#/components/schemas/VideoInfo'
5975         createdAt:
5976           type: string
5977           format: date-time
5978     AbuseMessage:
5979       properties:
5980         id:
5981           $ref: '#/components/schemas/id'
5982         message:
5983           type: string
5984           minLength: 2
5985           maxLength: 3000
5986         byModerator:
5987           type: boolean
5988         createdAt:
5989           type: string
5990           format: date-time
5991         account:
5992           $ref: '#/components/schemas/AccountSummary'
5993     VideoBlacklist:
5994       properties:
5995         id:
5996           $ref: '#/components/schemas/id'
5997         videoId:
5998           $ref: '#/components/schemas/Video/properties/id'
5999         createdAt:
6000           type: string
6001           format: date-time
6002         updatedAt:
6003           type: string
6004           format: date-time
6005         name:
6006           type: string
6007           minLength: 3
6008           maxLength: 120
6009         uuid:
6010           $ref: '#/components/schemas/UUIDv4'
6011         description:
6012           type: string
6013           minLength: 3
6014           maxLength: 10000
6015         duration:
6016           type: integer
6017         views:
6018           type: integer
6019         likes:
6020           type: integer
6021         dislikes:
6022           type: integer
6023         nsfw:
6024           type: boolean
6025     VideoPlaylist:
6026       properties:
6027         id:
6028           $ref: '#/components/schemas/id'
6029         uuid:
6030           $ref: '#/components/schemas/UUIDv4'
6031         shortUUID:
6032           allOf:
6033             - $ref: '#/components/schemas/shortUUID'
6034         createdAt:
6035           type: string
6036           format: date-time
6037         updatedAt:
6038           type: string
6039           format: date-time
6040         description:
6041           type: string
6042           minLength: 3
6043           maxLength: 1000
6044         displayName:
6045           type: string
6046           minLength: 1
6047           maxLength: 120
6048         isLocal:
6049           type: boolean
6050         videoLength:
6051           type: integer
6052           minimum: 0
6053         thumbnailPath:
6054           type: string
6055         privacy:
6056           $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
6057         type:
6058           $ref: '#/components/schemas/VideoPlaylistTypeConstant'
6059         ownerAccount:
6060           $ref: '#/components/schemas/AccountSummary'
6061         videoChannel:
6062           $ref: '#/components/schemas/VideoChannelSummary'
6063     VideoComment:
6064       properties:
6065         id:
6066           $ref: '#/components/schemas/id'
6067         url:
6068           type: string
6069           format: url
6070         text:
6071           type: string
6072           format: html
6073           description: Text of the comment
6074           minLength: 1
6075           example: This video is wonderful!
6076         threadId:
6077           $ref: '#/components/schemas/id'
6078         inReplyToCommentId:
6079           nullable: true
6080           allOf:
6081             - $ref: '#/components/schemas/id'
6082         videoId:
6083           $ref: '#/components/schemas/Video/properties/id'
6084         createdAt:
6085           type: string
6086           format: date-time
6087         updatedAt:
6088           type: string
6089           format: date-time
6090         deletedAt:
6091           nullable: true
6092           type: string
6093           format: date-time
6094           default: null
6095         isDeleted:
6096           type: boolean
6097           default: false
6098         totalRepliesFromVideoAuthor:
6099           type: integer
6100           minimum: 0
6101         totalReplies:
6102           type: integer
6103           minimum: 0
6104         account:
6105           $ref: '#/components/schemas/Account'
6106     VideoCommentThreadTree:
6107       properties:
6108         comment:
6109           $ref: '#/components/schemas/VideoComment'
6110         children:
6111           type: array
6112           items:
6113             $ref: '#/components/schemas/VideoCommentThreadTree'
6114     VideoCaption:
6115       properties:
6116         language:
6117           $ref: '#/components/schemas/VideoConstantString-Language'
6118         captionPath:
6119           type: string
6120     ActorImage:
6121       properties:
6122         path:
6123           type: string
6124         width:
6125           type: integer
6126         createdAt:
6127           type: string
6128           format: date-time
6129         updatedAt:
6130           type: string
6131           format: date-time
6132     ActorInfo:
6133       properties:
6134         id:
6135           $ref: '#/components/schemas/id'
6136         name:
6137           type: string
6138         displayName:
6139           type: string
6140         host:
6141           type: string
6142           format: hostname
6143         avatars:
6144           type: array
6145           items:
6146             $ref: '#/components/schemas/ActorImage'
6147     Actor:
6148       properties:
6149         id:
6150           $ref: '#/components/schemas/id'
6151         url:
6152           type: string
6153           format: url
6154         name:
6155           description: immutable name of the actor, used to find or mention it
6156           allOf:
6157             - $ref: '#/components/schemas/username'
6158         host:
6159           type: string
6160           format: hostname
6161           description: server on which the actor is resident
6162         hostRedundancyAllowed:
6163           type: boolean
6164           description: whether this actor's host allows redundancy of its videos
6165         followingCount:
6166           type: integer
6167           minimum: 0
6168           description: number of actors subscribed to by this actor, as seen by this instance
6169         followersCount:
6170           type: integer
6171           minimum: 0
6172           description: number of followers of this actor, as seen by this instance
6173         createdAt:
6174           type: string
6175           format: date-time
6176         updatedAt:
6177           type: string
6178           format: date-time
6179     Account:
6180       allOf:
6181         - $ref: '#/components/schemas/Actor'
6182         - properties:
6183             userId:
6184               description: object id for the user tied to this account
6185               allOf:
6186                 - $ref: '#/components/schemas/User/properties/id'
6187             displayName:
6188               type: string
6189               description: editable name of the account, displayed in its representations
6190               minLength: 3
6191               maxLength: 120
6192             description:
6193               type: string
6194               description: text or bio displayed on the account's profile
6195     UserViewingVideo:
6196       required:
6197         - currentTime
6198       properties:
6199         currentTime:
6200           type: integer
6201           format: seconds
6202           description: timestamp within the video, in seconds
6203           example: 5
6204         viewEvent:
6205           type: string
6206           enum:
6207             - seek
6208           description: >
6209             Event since last viewing call:
6210              * `seek` - If the user seeked the video
6211
6212     VideoStatsOverall:
6213       properties:
6214         averageWatchTime:
6215           type: number
6216         totalWatchTime:
6217           type: number
6218         viewersPeak:
6219           type: number
6220         viewersPeakDate:
6221           type: string
6222           format: date-time
6223         views:
6224           type: number
6225         likes:
6226           type: number
6227         dislikes:
6228           type: number
6229         comments:
6230           type: number
6231         countries:
6232           type: array
6233           items:
6234             type: object
6235             properties:
6236               isoCode:
6237                 type: string
6238               viewers:
6239                 type: number
6240
6241     VideoStatsRetention:
6242       properties:
6243         data:
6244           type: array
6245           items:
6246             type: object
6247             properties:
6248               second:
6249                 type: number
6250               retentionPercent:
6251                 type: number
6252
6253     VideoStatsTimeserie:
6254       properties:
6255         data:
6256           type: array
6257           items:
6258             type: object
6259             properties:
6260               date:
6261                 type: string
6262               value:
6263                 type: number
6264
6265     ServerConfig:
6266       properties:
6267         instance:
6268           type: object
6269           properties:
6270             name:
6271               type: string
6272             shortDescription:
6273               type: string
6274             defaultClientRoute:
6275               type: string
6276             isNSFW:
6277               type: boolean
6278             defaultNSFWPolicy:
6279               type: string
6280             customizations:
6281               type: object
6282               properties:
6283                 javascript:
6284                   type: string
6285                 css:
6286                   type: string
6287         search:
6288           type: object
6289           properties:
6290             remoteUri:
6291               type: object
6292               properties:
6293                 users:
6294                   type: boolean
6295                 anonymous:
6296                   type: boolean
6297         plugin:
6298           type: object
6299           properties:
6300             registered:
6301               type: array
6302               items:
6303                 type: string
6304         theme:
6305           type: object
6306           properties:
6307             registered:
6308               type: array
6309               items:
6310                 type: string
6311         email:
6312           type: object
6313           properties:
6314             enabled:
6315               type: boolean
6316         contactForm:
6317           type: object
6318           properties:
6319             enabled:
6320               type: boolean
6321         serverVersion:
6322           type: string
6323         serverCommit:
6324           type: string
6325         signup:
6326           type: object
6327           properties:
6328             allowed:
6329               type: boolean
6330             allowedForCurrentIP:
6331               type: boolean
6332             requiresEmailVerification:
6333               type: boolean
6334         transcoding:
6335           type: object
6336           properties:
6337             hls:
6338               type: object
6339               properties:
6340                 enabled:
6341                   type: boolean
6342             webtorrent:
6343               type: object
6344               properties:
6345                 enabled:
6346                   type: boolean
6347             enabledResolutions:
6348               type: array
6349               items:
6350                 $ref: '#/components/schemas/VideoResolutionSet'
6351         import:
6352           type: object
6353           properties:
6354             videos:
6355               type: object
6356               properties:
6357                 http:
6358                   type: object
6359                   properties:
6360                     enabled:
6361                       type: boolean
6362                 torrent:
6363                   type: object
6364                   properties:
6365                     enabled:
6366                       type: boolean
6367         autoBlacklist:
6368           type: object
6369           properties:
6370             videos:
6371               type: object
6372               properties:
6373                 ofUsers:
6374                   type: object
6375                   properties:
6376                     enabled:
6377                       type: boolean
6378         avatar:
6379           type: object
6380           properties:
6381             file:
6382               type: object
6383               properties:
6384                 size:
6385                   type: object
6386                   properties:
6387                     max:
6388                       type: integer
6389             extensions:
6390               type: array
6391               items:
6392                 type: string
6393         video:
6394           type: object
6395           properties:
6396             image:
6397               type: object
6398               properties:
6399                 extensions:
6400                   type: array
6401                   items:
6402                     type: string
6403                 size:
6404                   type: object
6405                   properties:
6406                     max:
6407                       type: integer
6408             file:
6409               type: object
6410               properties:
6411                 extensions:
6412                   type: array
6413                   items:
6414                     type: string
6415         videoCaption:
6416           type: object
6417           properties:
6418             file:
6419               type: object
6420               properties:
6421                 size:
6422                   type: object
6423                   properties:
6424                     max:
6425                       type: integer
6426                 extensions:
6427                   type: array
6428                   items:
6429                     type: string
6430         user:
6431           type: object
6432           properties:
6433             videoQuota:
6434               type: integer
6435               example: 16810141515
6436             videoQuotaDaily:
6437               type: integer
6438               example: 1681014151
6439         trending:
6440           type: object
6441           properties:
6442             videos:
6443               type: object
6444               properties:
6445                 intervalDays:
6446                   type: integer
6447         tracker:
6448           type: object
6449           properties:
6450             enabled:
6451               type: boolean
6452         followings:
6453           type: object
6454           properties:
6455             instance:
6456               type: object
6457               properties:
6458                 autoFollowIndex:
6459                   type: object
6460                   properties:
6461                     indexUrl:
6462                       type: string
6463                       format: url
6464         homepage:
6465           type: object
6466           properties:
6467             enabled:
6468               type: boolean
6469
6470     ServerConfigAbout:
6471       properties:
6472         instance:
6473           type: object
6474           properties:
6475             name:
6476               type: string
6477             shortDescription:
6478               type: string
6479             description:
6480               type: string
6481             terms:
6482               type: string
6483     ServerConfigCustom:
6484       properties:
6485         instance:
6486           type: object
6487           properties:
6488             name:
6489               type: string
6490             shortDescription:
6491               type: string
6492             description:
6493               type: string
6494             terms:
6495               type: string
6496             defaultClientRoute:
6497               type: string
6498             isNSFW:
6499               type: boolean
6500             defaultNSFWPolicy:
6501               type: string
6502             customizations:
6503               type: object
6504               properties:
6505                 javascript:
6506                   type: string
6507                 css:
6508                   type: string
6509         theme:
6510           type: object
6511           properties:
6512             default:
6513               type: string
6514         services:
6515           type: object
6516           properties:
6517             twitter:
6518               type: object
6519               properties:
6520                 username:
6521                   type: string
6522                 whitelisted:
6523                   type: boolean
6524         cache:
6525           type: object
6526           properties:
6527             previews:
6528               type: object
6529               properties:
6530                 size:
6531                   type: integer
6532             captions:
6533               type: object
6534               properties:
6535                 size:
6536                   type: integer
6537         signup:
6538           type: object
6539           properties:
6540             enabled:
6541               type: boolean
6542             limit:
6543               type: integer
6544             requiresEmailVerification:
6545               type: boolean
6546         admin:
6547           type: object
6548           properties:
6549             email:
6550               type: string
6551               format: email
6552         contactForm:
6553           type: object
6554           properties:
6555             enabled:
6556               type: boolean
6557         user:
6558           type: object
6559           description: Settings that apply to new users, if registration is enabled
6560           properties:
6561             videoQuota:
6562               type: integer
6563               example: 16810141515
6564             videoQuotaDaily:
6565               type: integer
6566               example: 1681014151
6567         transcoding:
6568           type: object
6569           description: Settings pertaining to transcoding jobs
6570           properties:
6571             enabled:
6572               type: boolean
6573             allowAdditionalExtensions:
6574               type: boolean
6575               description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6576             allowAudioFiles:
6577               type: boolean
6578               description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6579             threads:
6580               type: integer
6581               description: Amount of threads used by ffmpeg for 1 transcoding job
6582             concurrency:
6583               type: number
6584               description: Amount of transcoding jobs to execute in parallel
6585             profile:
6586               type: string
6587               enum:
6588                 - default
6589               description: |
6590                 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6591             resolutions:
6592               type: object
6593               description: Resolutions to transcode _new videos_ to
6594               properties:
6595                 0p:
6596                   type: boolean
6597                 144p:
6598                   type: boolean
6599                 240p:
6600                   type: boolean
6601                 360p:
6602                   type: boolean
6603                 480p:
6604                   type: boolean
6605                 720p:
6606                   type: boolean
6607                 1080p:
6608                   type: boolean
6609                 1440p:
6610                   type: boolean
6611                 2160p:
6612                   type: boolean
6613             webtorrent:
6614               type: object
6615               description: WebTorrent-specific settings
6616               properties:
6617                 enabled:
6618                   type: boolean
6619             hls:
6620               type: object
6621               description: HLS-specific settings
6622               properties:
6623                 enabled:
6624                   type: boolean
6625         import:
6626           type: object
6627           properties:
6628             videos:
6629               type: object
6630               properties:
6631                 http:
6632                   type: object
6633                   properties:
6634                     enabled:
6635                       type: boolean
6636                 torrent:
6637                   type: object
6638                   properties:
6639                     enabled:
6640                       type: boolean
6641         autoBlacklist:
6642           type: object
6643           properties:
6644             videos:
6645               type: object
6646               properties:
6647                 ofUsers:
6648                   type: object
6649                   properties:
6650                     enabled:
6651                       type: boolean
6652         followers:
6653           type: object
6654           properties:
6655             instance:
6656               type: object
6657               properties:
6658                 enabled:
6659                   type: boolean
6660                 manualApproval:
6661                   type: boolean
6662
6663     CustomHomepage:
6664       properties:
6665         content:
6666           type: string
6667
6668     Follow:
6669       properties:
6670         id:
6671           $ref: '#/components/schemas/id'
6672         follower:
6673           $ref: '#/components/schemas/Actor'
6674         following:
6675           $ref: '#/components/schemas/Actor'
6676         score:
6677           type: number
6678           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6679         state:
6680           type: string
6681           enum:
6682             - pending
6683             - accepted
6684         createdAt:
6685           type: string
6686           format: date-time
6687         updatedAt:
6688           type: string
6689           format: date-time
6690
6691     PredefinedAbuseReasons:
6692       description: Reason categories that help triage reports
6693       type: array
6694       maxItems: 8
6695       items:
6696         type: string
6697         enum:
6698         - violentOrAbusive
6699         - hatefulOrAbusive
6700         - spamOrMisleading
6701         - privacy
6702         - rights
6703         - serverRules
6704         - thumbnails
6705         - captions
6706
6707     Job:
6708       properties:
6709         id:
6710           $ref: '#/components/schemas/id'
6711         state:
6712           type: string
6713           enum:
6714             - active
6715             - completed
6716             - failed
6717             - waiting
6718             - delayed
6719         type:
6720           type: string
6721           enum:
6722             - activitypub-http-unicast
6723             - activitypub-http-broadcast
6724             - activitypub-http-fetcher
6725             - activitypub-follow
6726             - video-file-import
6727             - video-transcoding
6728             - email
6729             - video-import
6730             - videos-views-stats
6731             - activitypub-refresher
6732             - video-redundancy
6733         data:
6734           type: object
6735           additionalProperties: true
6736         error:
6737           type: object
6738           additionalProperties: true
6739         createdAt:
6740           type: string
6741           format: date-time
6742         finishedOn:
6743           type: string
6744           format: date-time
6745         processedOn:
6746           type: string
6747           format: date-time
6748     AddUserResponse:
6749       properties:
6750         user:
6751           type: object
6752           properties:
6753             id:
6754               $ref: '#/components/schemas/id'
6755             account:
6756               type: object
6757               properties:
6758                 id:
6759                   $ref: '#/components/schemas/id'
6760     VideoUploadRequestCommon:
6761       properties:
6762         name:
6763           description: Video name
6764           type: string
6765           example: What is PeerTube?
6766           minLength: 3
6767           maxLength: 120
6768         channelId:
6769           description: Channel id that will contain this video
6770           type: integer
6771           example: 3
6772           minimum: 1
6773         privacy:
6774           $ref: '#/components/schemas/VideoPrivacySet'
6775         category:
6776           $ref: '#/components/schemas/VideoCategorySet'
6777         licence:
6778           $ref: '#/components/schemas/VideoLicenceSet'
6779         language:
6780           $ref: '#/components/schemas/VideoLanguageSet'
6781         description:
6782           description: Video description
6783           type: string
6784           example: |
6785             **[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)**
6786         waitTranscoding:
6787           description: Whether or not we wait transcoding before publish the video
6788           type: boolean
6789         support:
6790           description: A text tell the audience how to support the video creator
6791           example: Please support our work on https://soutenir.framasoft.org/en/ <3
6792           type: string
6793         nsfw:
6794           description: Whether or not this video contains sensitive content
6795           type: boolean
6796         tags:
6797           description: Video tags (maximum 5 tags each between 2 and 30 characters)
6798           type: array
6799           minItems: 1
6800           maxItems: 5
6801           uniqueItems: true
6802           example:
6803             - framasoft
6804             - peertube
6805           items:
6806             type: string
6807             minLength: 2
6808             maxLength: 30
6809         commentsEnabled:
6810           description: Enable or disable comments for this video
6811           type: boolean
6812         downloadEnabled:
6813           description: Enable or disable downloading for this video
6814           type: boolean
6815         originallyPublishedAt:
6816           description: Date when the content was originally published
6817           type: string
6818           format: date-time
6819         scheduleUpdate:
6820           $ref: '#/components/schemas/VideoScheduledUpdate'
6821         thumbnailfile:
6822           description: Video thumbnail file
6823           type: string
6824           format: binary
6825         previewfile:
6826           description: Video preview file
6827           type: string
6828           format: binary
6829       required:
6830         - channelId
6831         - name
6832     VideoUploadRequestLegacy:
6833       allOf:
6834         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6835         - type: object
6836           required:
6837             - videofile
6838           properties:
6839             videofile:
6840               description: Video file
6841               type: string
6842               format: binary
6843     VideoUploadRequestResumable:
6844       allOf:
6845         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6846         - type: object
6847           required:
6848             - filename
6849           properties:
6850             filename:
6851               description: Video filename including extension
6852               type: string
6853               format: filename
6854               example: what_is_peertube.mp4
6855             thumbnailfile:
6856               description: Video thumbnail file
6857               type: string
6858               format: binary
6859             previewfile:
6860               description: Video preview file
6861               type: string
6862               format: binary
6863     VideoUploadResponse:
6864       properties:
6865         video:
6866           type: object
6867           properties:
6868             id:
6869               $ref: '#/components/schemas/Video/properties/id'
6870             uuid:
6871               $ref: '#/components/schemas/Video/properties/uuid'
6872             shortUUID:
6873               $ref: '#/components/schemas/Video/properties/shortUUID'
6874     CommentThreadResponse:
6875       properties:
6876         total:
6877           type: integer
6878           example: 1
6879         data:
6880           type: array
6881           maxItems: 100
6882           items:
6883             $ref: '#/components/schemas/VideoComment'
6884     CommentThreadPostResponse:
6885       properties:
6886         comment:
6887           $ref: '#/components/schemas/VideoComment'
6888     VideoListResponse:
6889       properties:
6890         total:
6891           type: integer
6892           example: 1
6893         data:
6894           type: array
6895           maxItems: 100
6896           items:
6897             $ref: '#/components/schemas/Video'
6898     User:
6899       properties:
6900         account:
6901           $ref: '#/components/schemas/Account'
6902         autoPlayNextVideo:
6903           type: boolean
6904           description: Automatically start playing the upcoming video after the currently playing video
6905         autoPlayNextVideoPlaylist:
6906           type: boolean
6907           description: Automatically start playing the video on the playlist after the currently playing video
6908         autoPlayVideo:
6909           type: boolean
6910           description: Automatically start playing the video on the watch page
6911         blocked:
6912           type: boolean
6913         blockedReason:
6914           type: string
6915         createdAt:
6916           type: string
6917         email:
6918           type: string
6919           format: email
6920           description: The user email
6921         emailVerified:
6922           type: boolean
6923           description: Has the user confirmed their email address?
6924         id:
6925           allOf:
6926             - $ref: '#/components/schemas/id'
6927           readOnly: true
6928         pluginAuth:
6929           type: string
6930           description: Auth plugin to use to authenticate the user
6931         lastLoginDate:
6932           type: string
6933           format: date-time
6934         noInstanceConfigWarningModal:
6935           type: boolean
6936         noAccountSetupWarningModal:
6937           type: boolean
6938         noWelcomeModal:
6939           type: boolean
6940         nsfwPolicy:
6941           $ref: '#/components/schemas/NSFWPolicy'
6942         role:
6943           $ref: '#/components/schemas/UserRole'
6944         roleLabel:
6945           type: string
6946           enum:
6947             - User
6948             - Moderator
6949             - Administrator
6950         theme:
6951           type: string
6952           description: Theme enabled by this user
6953         username:
6954           $ref: '#/components/schemas/username'
6955         videoChannels:
6956           type: array
6957           items:
6958             $ref: '#/components/schemas/VideoChannel'
6959         videoQuota:
6960           type: integer
6961           description: The user video quota in bytes
6962           example: -1
6963         videoQuotaDaily:
6964           type: integer
6965           description: The user daily video quota in bytes
6966           example: -1
6967         p2pEnabled:
6968           type: boolean
6969           description: Enable P2P in the player
6970     UserWithStats:
6971       allOf:
6972         - $ref: '#/components/schemas/User'
6973         - properties:
6974             # optionally present fields: they require WITH_STATS scope
6975             videosCount:
6976               type: integer
6977               description: Count of videos published
6978             abusesCount:
6979               type: integer
6980               description: Count of reports/abuses of which the user is a target
6981             abusesAcceptedCount:
6982               type: integer
6983               description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6984             abusesCreatedCount:
6985               type: integer
6986               description: Count of reports/abuses created by the user
6987             videoCommentsCount:
6988               type: integer
6989               description: Count of comments published
6990     AddUser:
6991       properties:
6992         username:
6993           $ref: '#/components/schemas/username'
6994         password:
6995           $ref: '#/components/schemas/password'
6996         email:
6997           type: string
6998           format: email
6999           description: The user email
7000         videoQuota:
7001           type: integer
7002           description: The user video quota in bytes
7003           example: -1
7004         videoQuotaDaily:
7005           type: integer
7006           description: The user daily video quota in bytes
7007           example: -1
7008         channelName:
7009           $ref: '#/components/schemas/usernameChannel'
7010         role:
7011           $ref: '#/components/schemas/UserRole'
7012         adminFlags:
7013           $ref: '#/components/schemas/UserAdminFlags'
7014       required:
7015         - username
7016         - password
7017         - email
7018         - videoQuota
7019         - videoQuotaDaily
7020         - role
7021     UpdateUser:
7022       properties:
7023         email:
7024           description: The updated email of the user
7025           allOf:
7026             - $ref: '#/components/schemas/User/properties/email'
7027         emailVerified:
7028           type: boolean
7029           description: Set the email as verified
7030         videoQuota:
7031           type: integer
7032           description: The updated video quota of the user in bytes
7033         videoQuotaDaily:
7034           type: integer
7035           description: The updated daily video quota of the user in bytes
7036         pluginAuth:
7037           type: string
7038           nullable: true
7039           description: The auth plugin to use to authenticate the user
7040           example: 'peertube-plugin-auth-saml2'
7041         role:
7042           $ref: '#/components/schemas/UserRole'
7043         adminFlags:
7044           $ref: '#/components/schemas/UserAdminFlags'
7045         password:
7046           $ref: '#/components/schemas/password'
7047     UpdateMe:
7048       # see shared/models/users/user-update-me.model.ts:
7049       properties:
7050         password:
7051           $ref: '#/components/schemas/password'
7052         currentPassword:
7053           $ref: '#/components/schemas/password'
7054         email:
7055           description: new email used for login and service communications
7056           allOf:
7057             - $ref: '#/components/schemas/User/properties/email'
7058         displayName:
7059           type: string
7060           description: new name of the user in its representations
7061           minLength: 3
7062           maxLength: 120
7063         displayNSFW:
7064           type: string
7065           description: new NSFW display policy
7066           enum:
7067             - 'true'
7068             - 'false'
7069             - both
7070         p2pEnabled:
7071           type: boolean
7072           description: whether to enable P2P in the player or not
7073         autoPlayVideo:
7074           type: boolean
7075           description: new preference regarding playing videos automatically
7076         autoPlayNextVideo:
7077           type: boolean
7078           description: new preference regarding playing following videos automatically
7079         autoPlayNextVideoPlaylist:
7080           type: boolean
7081           description: new preference regarding playing following playlist videos automatically
7082         videosHistoryEnabled:
7083           type: boolean
7084           description: whether to keep track of watched history or not
7085         videoLanguages:
7086           type: array
7087           items:
7088             type: string
7089           description: list of languages to filter videos down to
7090         theme:
7091           type: string
7092         noInstanceConfigWarningModal:
7093           type: boolean
7094         noAccountSetupWarningModal:
7095           type: boolean
7096         noWelcomeModal:
7097           type: boolean
7098     GetMeVideoRating:
7099       properties:
7100         id:
7101           $ref: '#/components/schemas/id'
7102         rating:
7103           type: string
7104           enum:
7105             - like
7106             - dislike
7107             - none
7108           description: Rating of the video
7109       required:
7110         - id
7111         - rating
7112     VideoRating:
7113       properties:
7114         video:
7115           $ref: '#/components/schemas/Video'
7116         rating:
7117           type: string
7118           enum:
7119             - like
7120             - dislike
7121             - none
7122           description: Rating of the video
7123       required:
7124         - video
7125         - rating
7126     RegisterUser:
7127       properties:
7128         username:
7129           description: immutable name of the user, used to find or mention its actor
7130           allOf:
7131             - $ref: '#/components/schemas/username'
7132         password:
7133           $ref: '#/components/schemas/password'
7134         email:
7135           type: string
7136           format: email
7137           description: email of the user, used for login or service communications
7138         displayName:
7139           type: string
7140           description: editable name of the user, displayed in its representations
7141           minLength: 1
7142           maxLength: 120
7143         channel:
7144           type: object
7145           description: channel base information used to create the first channel of the user
7146           properties:
7147             name:
7148               $ref: '#/components/schemas/usernameChannel'
7149             displayName:
7150               type: string
7151       required:
7152         - username
7153         - password
7154         - email
7155
7156     OAuthClient:
7157       properties:
7158         client_id:
7159           type: string
7160           pattern: /^[a-z0-9]$/
7161           maxLength: 32
7162           minLength: 32
7163           example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7164         client_secret:
7165           type: string
7166           pattern: /^[a-zA-Z0-9]$/
7167           maxLength: 32
7168           minLength: 32
7169           example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7170     OAuthToken-password:
7171       allOf:
7172         - $ref: '#/components/schemas/OAuthClient'
7173         - type: object
7174           properties:
7175             grant_type:
7176               type: string
7177               enum:
7178                 - password
7179                 - refresh_token
7180               default: password
7181             username:
7182               $ref: '#/components/schemas/User/properties/username'
7183             password:
7184               $ref: '#/components/schemas/password'
7185       required:
7186         - client_id
7187         - client_secret
7188         - grant_type
7189         - username
7190         - password
7191     OAuthToken-refresh_token:
7192       allOf:
7193         - $ref: '#/components/schemas/OAuthClient'
7194         - type: object
7195           properties:
7196             grant_type:
7197               type: string
7198               enum:
7199                 - password
7200                 - refresh_token
7201               default: password
7202             refresh_token:
7203               type: string
7204               example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7205       required:
7206         - client_id
7207         - client_secret
7208         - grant_type
7209         - refresh_token
7210
7211     VideoChannel:
7212       allOf:
7213         - $ref: '#/components/schemas/Actor'
7214         - type: object
7215           properties:
7216             displayName:
7217               type: string
7218               description: editable name of the channel, displayed in its representations
7219               example: Videos of Framasoft
7220               minLength: 1
7221               maxLength: 120
7222             description:
7223               type: string
7224               example: Videos made with <3 by Framasoft
7225               minLength: 3
7226               maxLength: 1000
7227             support:
7228               type: string
7229               description: text shown by default on all videos of this channel, to tell the audience how to support it
7230               example: Please support our work on https://soutenir.framasoft.org/en/ <3
7231               minLength: 3
7232               maxLength: 1000
7233             isLocal:
7234               readOnly: true
7235               type: boolean
7236             updatedAt:
7237               readOnly: true
7238               type: string
7239               format: date-time
7240             banners:
7241               type: array
7242               items:
7243                 $ref: '#/components/schemas/ActorImage'
7244             ownerAccount:
7245               readOnly: true
7246               nullable: true
7247               type: object
7248               properties:
7249                 id:
7250                   type: integer
7251                 uuid:
7252                   $ref: '#/components/schemas/UUIDv4'
7253     VideoChannelCreate:
7254       allOf:
7255         - $ref: '#/components/schemas/VideoChannel'
7256         - properties:
7257             name:
7258               description: username of the channel to create
7259               allOf:
7260                 - $ref: '#/components/schemas/usernameChannel'
7261       required:
7262         - name
7263         - displayName
7264     VideoChannelUpdate:
7265       allOf:
7266         - $ref: '#/components/schemas/VideoChannel'
7267         - properties:
7268             bulkVideosSupportUpdate:
7269               type: boolean
7270               description: Update the support field for all videos of this channel
7271     VideoChannelList:
7272       properties:
7273         total:
7274           type: integer
7275           example: 1
7276         data:
7277           type: array
7278           items:
7279             allOf:
7280               - $ref: '#/components/schemas/VideoChannel'
7281               - $ref: '#/components/schemas/Actor'
7282
7283     MRSSPeerLink:
7284       type: object
7285       xml:
7286         name: 'media:peerLink'
7287       properties:
7288         href:
7289           type: string
7290           xml:
7291             attribute: true
7292         type:
7293           type: string
7294           enum:
7295             - application/x-bittorrent
7296           xml:
7297             attribute: true
7298     MRSSGroupContent:
7299       type: object
7300       xml:
7301         name: 'media:content'
7302       properties:
7303         url:
7304           type: string
7305           format: url
7306           xml:
7307             attribute: true
7308         fileSize:
7309           type: integer
7310           xml:
7311             attribute: true
7312         type:
7313           type: string
7314           xml:
7315             attribute: true
7316         framerate:
7317           type: integer
7318           xml:
7319             attribute: true
7320         duration:
7321           type: integer
7322           xml:
7323             attribute: true
7324         height:
7325           type: integer
7326           xml:
7327             attribute: true
7328         lang:
7329           type: string
7330           xml:
7331             attribute: true
7332     VideoCommentsForXML:
7333       type: array
7334       xml:
7335         wrapped: true
7336         name: 'channel'
7337       items:
7338         type: object
7339         xml:
7340           name: 'item'
7341         properties:
7342           link:
7343             type: string
7344             format: url
7345           guid:
7346             type: string
7347           pubDate:
7348             type: string
7349             format: date-time
7350           'content:encoded':
7351             type: string
7352           'dc:creator':
7353             type: string
7354     VideosForXML:
7355       type: array
7356       xml:
7357         wrapped: true
7358         name: 'channel'
7359       items:
7360         type: object
7361         xml:
7362           name: 'item'
7363         properties:
7364           link:
7365             type: string
7366             format: url
7367             description: video watch page URL
7368           guid:
7369             type: string
7370             description: video canonical URL
7371           pubDate:
7372             type: string
7373             format: date-time
7374             description: video publication date
7375           description:
7376             type: string
7377             description: video description
7378           'content:encoded':
7379             type: string
7380             description: video description
7381           'dc:creator':
7382             type: string
7383             description: publisher user name
7384           'media:category':
7385             type: integer
7386             description: video category (MRSS)
7387           'media:community':
7388             type: object
7389             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7390             properties:
7391               'media:statistics':
7392                 type: object
7393                 properties:
7394                   views:
7395                     type: integer
7396                     xml:
7397                       attribute: true
7398           'media:embed':
7399             type: object
7400             properties:
7401               url:
7402                 type: string
7403                 format: url
7404                 description: video embed path, relative to the canonical URL domain (MRSS)
7405                 xml:
7406                   attribute: true
7407           'media:player':
7408             type: object
7409             properties:
7410               url:
7411                 type: string
7412                 format: url
7413                 description: video watch path, relative to the canonical URL domain (MRSS)
7414                 xml:
7415                   attribute: true
7416           'media:thumbnail':
7417             type: object
7418             properties:
7419               url:
7420                 type: string
7421                 format: url
7422                 xml:
7423                   attribute: true
7424               height:
7425                 type: integer
7426                 xml:
7427                   attribute: true
7428               width:
7429                 type: integer
7430                 xml:
7431                   attribute: true
7432           'media:title':
7433             type: string
7434             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7435           'media:description':
7436             type: string
7437           'media:rating':
7438             type: string
7439             enum:
7440               - nonadult
7441               - adult
7442             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7443           'enclosure':
7444             type: object
7445             description: main streamable file for the video
7446             properties:
7447               url:
7448                 type: string
7449                 format: url
7450                 xml:
7451                   attribute: true
7452               type:
7453                 type: string
7454                 enum:
7455                   - application/x-bittorrent
7456                 xml:
7457                   attribute: true
7458               length:
7459                 type: integer
7460                 xml:
7461                   attribute: true
7462           'media:group':
7463             type: array
7464             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)
7465             items:
7466               anyOf:
7467                 - $ref: '#/components/schemas/MRSSPeerLink'
7468                 - $ref: '#/components/schemas/MRSSGroupContent'
7469     NotificationSettingValue:
7470       type: integer
7471       description: >
7472         Notification type
7473
7474         - `0` NONE
7475
7476         - `1` WEB
7477
7478         - `2` EMAIL
7479       enum:
7480         - 0
7481         - 1
7482         - 2
7483     Notification:
7484       properties:
7485         id:
7486           $ref: '#/components/schemas/id'
7487         type:
7488           type: integer
7489           description: >
7490             Notification type, following the `UserNotificationType` enum:
7491
7492             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7493
7494             - `2` NEW_COMMENT_ON_MY_VIDEO
7495
7496             - `3` NEW_ABUSE_FOR_MODERATORS
7497
7498             - `4` BLACKLIST_ON_MY_VIDEO
7499
7500             - `5` UNBLACKLIST_ON_MY_VIDEO
7501
7502             - `6` MY_VIDEO_PUBLISHED
7503
7504             - `7` MY_VIDEO_IMPORT_SUCCESS
7505
7506             - `8` MY_VIDEO_IMPORT_ERROR
7507
7508             - `9` NEW_USER_REGISTRATION
7509
7510             - `10` NEW_FOLLOW
7511
7512             - `11` COMMENT_MENTION
7513
7514             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7515
7516             - `13` NEW_INSTANCE_FOLLOWER
7517
7518             - `14` AUTO_INSTANCE_FOLLOWING
7519
7520             - `15` ABUSE_STATE_CHANGE
7521
7522             - `16` ABUSE_NEW_MESSAGE
7523
7524             - `17` NEW_PLUGIN_VERSION
7525
7526             - `18` NEW_PEERTUBE_VERSION
7527         read:
7528           type: boolean
7529         video:
7530           nullable: true
7531           allOf:
7532             - $ref: '#/components/schemas/VideoInfo'
7533             - type: object
7534               properties:
7535                 channel:
7536                   $ref: '#/components/schemas/ActorInfo'
7537         videoImport:
7538           nullable: true
7539           type: object
7540           properties:
7541             id:
7542               $ref: '#/components/schemas/id'
7543             video:
7544               nullable: true
7545               $ref: '#/components/schemas/VideoInfo'
7546             torrentName:
7547               type: string
7548               nullable: true
7549             magnetUri:
7550               $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7551             targetUri:
7552               type: string
7553               format: uri
7554               nullable: true
7555         comment:
7556           nullable: true
7557           type: object
7558           properties:
7559             id:
7560               $ref: '#/components/schemas/id'
7561             threadId:
7562               type: integer
7563             video:
7564               $ref: '#/components/schemas/VideoInfo'
7565             account:
7566               $ref: '#/components/schemas/ActorInfo'
7567         videoAbuse:
7568           nullable: true
7569           type: object
7570           properties:
7571             id:
7572               $ref: '#/components/schemas/id'
7573             video:
7574               allOf:
7575                 - $ref: '#/components/schemas/VideoInfo'
7576         videoBlacklist:
7577           nullable: true
7578           type: object
7579           properties:
7580             id:
7581               $ref: '#/components/schemas/id'
7582             video:
7583               allOf:
7584                 - $ref: '#/components/schemas/VideoInfo'
7585         account:
7586           nullable: true
7587           allOf:
7588             - $ref: '#/components/schemas/ActorInfo'
7589         actorFollow:
7590           type: object
7591           nullable: true
7592           properties:
7593             id:
7594               $ref: '#/components/schemas/id'
7595             follower:
7596               $ref: '#/components/schemas/ActorInfo'
7597             state:
7598               type: string
7599               enum:
7600                 - pending
7601                 - accepted
7602             following:
7603               type: object
7604               properties:
7605                 type:
7606                   type: string
7607                   enum:
7608                     - account
7609                     - channel
7610                     - instance
7611                 name:
7612                   type: string
7613                 displayName:
7614                   type: string
7615                 host:
7616                   type: string
7617                   format: hostname
7618         createdAt:
7619           type: string
7620           format: date-time
7621         updatedAt:
7622           type: string
7623           format: date-time
7624     NotificationListResponse:
7625       properties:
7626         total:
7627           type: integer
7628           example: 1
7629         data:
7630           type: array
7631           maxItems: 100
7632           items:
7633             $ref: '#/components/schemas/Notification'
7634     Plugin:
7635       properties:
7636         name:
7637           type: string
7638           example: peertube-plugin-auth-ldap
7639         type:
7640           type: integer
7641           description: >
7642             - `1`: PLUGIN
7643
7644             - `2`: THEME
7645           enum:
7646             - 1
7647             - 2
7648         latestVersion:
7649           type: string
7650           example: 0.0.3
7651         version:
7652           type: string
7653           example: 0.0.1
7654         enabled:
7655           type: boolean
7656         uninstalled:
7657           type: boolean
7658         peertubeEngine:
7659           type: string
7660           example: 2.2.0
7661         description:
7662           type: string
7663         homepage:
7664           type: string
7665           format: url
7666           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7667         settings:
7668           type: object
7669           additionalProperties: true
7670         createdAt:
7671           type: string
7672           format: date-time
7673         updatedAt:
7674           type: string
7675           format: date-time
7676     PluginResponse:
7677       properties:
7678         total:
7679           type: integer
7680           example: 1
7681         data:
7682           type: array
7683           maxItems: 100
7684           items:
7685             $ref: '#/components/schemas/Plugin'
7686
7687     LiveVideoUpdate:
7688       properties:
7689         saveReplay:
7690           type: boolean
7691         permanentLive:
7692           description: User can stream multiple times in a permanent live
7693           type: boolean
7694         latencyMode:
7695           description: User can select live latency mode if enabled by the instance
7696           $ref: '#/components/schemas/LiveVideoLatencyMode'
7697
7698     LiveVideoResponse:
7699       properties:
7700         rtmpUrl:
7701           type: string
7702           description: Included in the response if an appropriate token is provided
7703         rtmpsUrl:
7704           type: string
7705           description: Included in the response if an appropriate token is provided
7706         streamKey:
7707           type: string
7708           description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
7709         saveReplay:
7710           type: boolean
7711         permanentLive:
7712           description: User can stream multiple times in a permanent live
7713           type: boolean
7714         latencyMode:
7715           description: User can select live latency mode if enabled by the instance
7716           $ref: '#/components/schemas/LiveVideoLatencyMode'
7717
7718     LiveVideoSessionResponse:
7719         properties:
7720           id:
7721             type: integer
7722           startDate:
7723             type: string
7724             format: date-time
7725             description: Start date of the live session
7726           endDate:
7727             type: string
7728             format: date-time
7729             nullable: true
7730             description: End date of the live session
7731           error:
7732             type: integer
7733             enum:
7734               - 1
7735               - 2
7736               - 3
7737               - 4
7738               - 5
7739             nullable: true
7740             description: >
7741               Error type if an error occured during the live session:
7742                 - `1`: Bad socket health (transcoding is too slow)
7743                 - `2`: Max duration exceeded
7744                 - `3`: Quota exceeded
7745                 - `4`: Quota FFmpeg error
7746                 - `5`: Video has been blacklisted during the live
7747           replayVideo:
7748             type: object
7749             description: Video replay information
7750             properties:
7751               id:
7752                 type: number
7753               uuid:
7754                 $ref: '#/components/schemas/UUIDv4'
7755               shortUUID:
7756                 $ref: '#/components/schemas/shortUUID'
7757
7758   callbacks:
7759     searchIndex:
7760       'https://search.example.org/api/v1/search/videos':
7761         post:
7762           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7763           responses:
7764             '200':
7765               description: successful operation
7766               content:
7767                 application/json:
7768                   schema:
7769                     $ref: '#/components/schemas/VideoListResponse'