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