support/doc/api/openapi.yaml

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