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       properties:
6131         currentTime:
6132           type: integer
6133           format: seconds
6134           description: timestamp within the video, in seconds
6135           example: 5
6136
6137     VideoStatsOverall:
6138       properties:
6139         averageWatchTime:
6140           type: number
6141         totalWatchTime:
6142           type: number
6143         viewersPeak:
6144           type: number
6145         viewersPeakDate:
6146           type: string
6147           format: date-time
6148         views:
6149           type: number
6150         likes:
6151           type: number
6152         dislikes:
6153           type: number
6154         comments:
6155           type: number
6156         countries:
6157           type: array
6158           items:
6159             type: object
6160             properties:
6161               isoCode:
6162                 type: string
6163               viewers:
6164                 type: number
6165
6166     VideoStatsRetention:
6167       properties:
6168         data:
6169           type: array
6170           items:
6171             type: object
6172             properties:
6173               second:
6174                 type: number
6175               retentionPercent:
6176                 type: number
6177
6178     VideoStatsTimeserie:
6179       properties:
6180         data:
6181           type: array
6182           items:
6183             type: object
6184             properties:
6185               date:
6186                 type: string
6187               value:
6188                 type: number
6189
6190     ServerConfig:
6191       properties:
6192         instance:
6193           type: object
6194           properties:
6195             name:
6196               type: string
6197             shortDescription:
6198               type: string
6199             defaultClientRoute:
6200               type: string
6201             isNSFW:
6202               type: boolean
6203             defaultNSFWPolicy:
6204               type: string
6205             customizations:
6206               type: object
6207               properties:
6208                 javascript:
6209                   type: string
6210                 css:
6211                   type: string
6212         search:
6213           type: object
6214           properties:
6215             remoteUri:
6216               type: object
6217               properties:
6218                 users:
6219                   type: boolean
6220                 anonymous:
6221                   type: boolean
6222         plugin:
6223           type: object
6224           properties:
6225             registered:
6226               type: array
6227               items:
6228                 type: string
6229         theme:
6230           type: object
6231           properties:
6232             registered:
6233               type: array
6234               items:
6235                 type: string
6236         email:
6237           type: object
6238           properties:
6239             enabled:
6240               type: boolean
6241         contactForm:
6242           type: object
6243           properties:
6244             enabled:
6245               type: boolean
6246         serverVersion:
6247           type: string
6248         serverCommit:
6249           type: string
6250         signup:
6251           type: object
6252           properties:
6253             allowed:
6254               type: boolean
6255             allowedForCurrentIP:
6256               type: boolean
6257             requiresEmailVerification:
6258               type: boolean
6259         transcoding:
6260           type: object
6261           properties:
6262             hls:
6263               type: object
6264               properties:
6265                 enabled:
6266                   type: boolean
6267             webtorrent:
6268               type: object
6269               properties:
6270                 enabled:
6271                   type: boolean
6272             enabledResolutions:
6273               type: array
6274               items:
6275                 $ref: '#/components/schemas/VideoResolutionSet'
6276         import:
6277           type: object
6278           properties:
6279             videos:
6280               type: object
6281               properties:
6282                 http:
6283                   type: object
6284                   properties:
6285                     enabled:
6286                       type: boolean
6287                 torrent:
6288                   type: object
6289                   properties:
6290                     enabled:
6291                       type: boolean
6292         autoBlacklist:
6293           type: object
6294           properties:
6295             videos:
6296               type: object
6297               properties:
6298                 ofUsers:
6299                   type: object
6300                   properties:
6301                     enabled:
6302                       type: boolean
6303         avatar:
6304           type: object
6305           properties:
6306             file:
6307               type: object
6308               properties:
6309                 size:
6310                   type: object
6311                   properties:
6312                     max:
6313                       type: integer
6314             extensions:
6315               type: array
6316               items:
6317                 type: string
6318         video:
6319           type: object
6320           properties:
6321             image:
6322               type: object
6323               properties:
6324                 extensions:
6325                   type: array
6326                   items:
6327                     type: string
6328                 size:
6329                   type: object
6330                   properties:
6331                     max:
6332                       type: integer
6333             file:
6334               type: object
6335               properties:
6336                 extensions:
6337                   type: array
6338                   items:
6339                     type: string
6340         videoCaption:
6341           type: object
6342           properties:
6343             file:
6344               type: object
6345               properties:
6346                 size:
6347                   type: object
6348                   properties:
6349                     max:
6350                       type: integer
6351                 extensions:
6352                   type: array
6353                   items:
6354                     type: string
6355         user:
6356           type: object
6357           properties:
6358             videoQuota:
6359               type: integer
6360               example: 16810141515
6361             videoQuotaDaily:
6362               type: integer
6363               example: 1681014151
6364         trending:
6365           type: object
6366           properties:
6367             videos:
6368               type: object
6369               properties:
6370                 intervalDays:
6371                   type: integer
6372         tracker:
6373           type: object
6374           properties:
6375             enabled:
6376               type: boolean
6377         followings:
6378           type: object
6379           properties:
6380             instance:
6381               type: object
6382               properties:
6383                 autoFollowIndex:
6384                   type: object
6385                   properties:
6386                     indexUrl:
6387                       type: string
6388                       format: url
6389         homepage:
6390           type: object
6391           properties:
6392             enabled:
6393               type: boolean
6394
6395     ServerConfigAbout:
6396       properties:
6397         instance:
6398           type: object
6399           properties:
6400             name:
6401               type: string
6402             shortDescription:
6403               type: string
6404             description:
6405               type: string
6406             terms:
6407               type: string
6408     ServerConfigCustom:
6409       properties:
6410         instance:
6411           type: object
6412           properties:
6413             name:
6414               type: string
6415             shortDescription:
6416               type: string
6417             description:
6418               type: string
6419             terms:
6420               type: string
6421             defaultClientRoute:
6422               type: string
6423             isNSFW:
6424               type: boolean
6425             defaultNSFWPolicy:
6426               type: string
6427             customizations:
6428               type: object
6429               properties:
6430                 javascript:
6431                   type: string
6432                 css:
6433                   type: string
6434         theme:
6435           type: object
6436           properties:
6437             default:
6438               type: string
6439         services:
6440           type: object
6441           properties:
6442             twitter:
6443               type: object
6444               properties:
6445                 username:
6446                   type: string
6447                 whitelisted:
6448                   type: boolean
6449         cache:
6450           type: object
6451           properties:
6452             previews:
6453               type: object
6454               properties:
6455                 size:
6456                   type: integer
6457             captions:
6458               type: object
6459               properties:
6460                 size:
6461                   type: integer
6462         signup:
6463           type: object
6464           properties:
6465             enabled:
6466               type: boolean
6467             limit:
6468               type: integer
6469             requiresEmailVerification:
6470               type: boolean
6471         admin:
6472           type: object
6473           properties:
6474             email:
6475               type: string
6476               format: email
6477         contactForm:
6478           type: object
6479           properties:
6480             enabled:
6481               type: boolean
6482         user:
6483           type: object
6484           description: Settings that apply to new users, if registration is enabled
6485           properties:
6486             videoQuota:
6487               type: integer
6488               example: 16810141515
6489             videoQuotaDaily:
6490               type: integer
6491               example: 1681014151
6492         transcoding:
6493           type: object
6494           description: Settings pertaining to transcoding jobs
6495           properties:
6496             enabled:
6497               type: boolean
6498             allowAdditionalExtensions:
6499               type: boolean
6500               description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
6501             allowAudioFiles:
6502               type: boolean
6503               description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
6504             threads:
6505               type: integer
6506               description: Amount of threads used by ffmpeg for 1 transcoding job
6507             concurrency:
6508               type: number
6509               description: Amount of transcoding jobs to execute in parallel
6510             profile:
6511               type: string
6512               enum:
6513                 - default
6514               description: |
6515                 New profiles can be added by plugins ; available in core PeerTube: 'default'.
6516             resolutions:
6517               type: object
6518               description: Resolutions to transcode _new videos_ to
6519               properties:
6520                 0p:
6521                   type: boolean
6522                 144p:
6523                   type: boolean
6524                 240p:
6525                   type: boolean
6526                 360p:
6527                   type: boolean
6528                 480p:
6529                   type: boolean
6530                 720p:
6531                   type: boolean
6532                 1080p:
6533                   type: boolean
6534                 1440p:
6535                   type: boolean
6536                 2160p:
6537                   type: boolean
6538             webtorrent:
6539               type: object
6540               description: WebTorrent-specific settings
6541               properties:
6542                 enabled:
6543                   type: boolean
6544             hls:
6545               type: object
6546               description: HLS-specific settings
6547               properties:
6548                 enabled:
6549                   type: boolean
6550         import:
6551           type: object
6552           properties:
6553             videos:
6554               type: object
6555               properties:
6556                 http:
6557                   type: object
6558                   properties:
6559                     enabled:
6560                       type: boolean
6561                 torrent:
6562                   type: object
6563                   properties:
6564                     enabled:
6565                       type: boolean
6566         autoBlacklist:
6567           type: object
6568           properties:
6569             videos:
6570               type: object
6571               properties:
6572                 ofUsers:
6573                   type: object
6574                   properties:
6575                     enabled:
6576                       type: boolean
6577         followers:
6578           type: object
6579           properties:
6580             instance:
6581               type: object
6582               properties:
6583                 enabled:
6584                   type: boolean
6585                 manualApproval:
6586                   type: boolean
6587
6588     CustomHomepage:
6589       properties:
6590         content:
6591           type: string
6592
6593     Follow:
6594       properties:
6595         id:
6596           $ref: '#/components/schemas/id'
6597         follower:
6598           $ref: '#/components/schemas/Actor'
6599         following:
6600           $ref: '#/components/schemas/Actor'
6601         score:
6602           type: number
6603           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
6604         state:
6605           type: string
6606           enum:
6607             - pending
6608             - accepted
6609         createdAt:
6610           type: string
6611           format: date-time
6612         updatedAt:
6613           type: string
6614           format: date-time
6615
6616     PredefinedAbuseReasons:
6617       description: Reason categories that help triage reports
6618       type: array
6619       maxItems: 8
6620       items:
6621         type: string
6622         enum:
6623         - violentOrAbusive
6624         - hatefulOrAbusive
6625         - spamOrMisleading
6626         - privacy
6627         - rights
6628         - serverRules
6629         - thumbnails
6630         - captions
6631
6632     Job:
6633       properties:
6634         id:
6635           $ref: '#/components/schemas/id'
6636         state:
6637           type: string
6638           enum:
6639             - active
6640             - completed
6641             - failed
6642             - waiting
6643             - delayed
6644         type:
6645           type: string
6646           enum:
6647             - activitypub-http-unicast
6648             - activitypub-http-broadcast
6649             - activitypub-http-fetcher
6650             - activitypub-follow
6651             - video-file-import
6652             - video-transcoding
6653             - email
6654             - video-import
6655             - videos-views-stats
6656             - activitypub-refresher
6657             - video-redundancy
6658         data:
6659           type: object
6660           additionalProperties: true
6661         error:
6662           type: object
6663           additionalProperties: true
6664         createdAt:
6665           type: string
6666           format: date-time
6667         finishedOn:
6668           type: string
6669           format: date-time
6670         processedOn:
6671           type: string
6672           format: date-time
6673     AddUserResponse:
6674       properties:
6675         user:
6676           type: object
6677           properties:
6678             id:
6679               $ref: '#/components/schemas/id'
6680             account:
6681               type: object
6682               properties:
6683                 id:
6684                   $ref: '#/components/schemas/id'
6685     VideoUploadRequestCommon:
6686       properties:
6687         name:
6688           description: Video name
6689           type: string
6690           example: What is PeerTube?
6691           minLength: 3
6692           maxLength: 120
6693         channelId:
6694           description: Channel id that will contain this video
6695           type: integer
6696           example: 3
6697           minimum: 1
6698         privacy:
6699           $ref: '#/components/schemas/VideoPrivacySet'
6700         category:
6701           $ref: '#/components/schemas/VideoCategorySet'
6702         licence:
6703           $ref: '#/components/schemas/VideoLicenceSet'
6704         language:
6705           $ref: '#/components/schemas/VideoLanguageSet'
6706         description:
6707           description: Video description
6708           type: string
6709           example: |
6710             **[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)**
6711         waitTranscoding:
6712           description: Whether or not we wait transcoding before publish the video
6713           type: boolean
6714         support:
6715           description: A text tell the audience how to support the video creator
6716           example: Please support our work on https://soutenir.framasoft.org/en/ <3
6717           type: string
6718         nsfw:
6719           description: Whether or not this video contains sensitive content
6720           type: boolean
6721         tags:
6722           description: Video tags (maximum 5 tags each between 2 and 30 characters)
6723           type: array
6724           minItems: 1
6725           maxItems: 5
6726           uniqueItems: true
6727           example:
6728             - framasoft
6729             - peertube
6730           items:
6731             type: string
6732             minLength: 2
6733             maxLength: 30
6734         commentsEnabled:
6735           description: Enable or disable comments for this video
6736           type: boolean
6737         downloadEnabled:
6738           description: Enable or disable downloading for this video
6739           type: boolean
6740         originallyPublishedAt:
6741           description: Date when the content was originally published
6742           type: string
6743           format: date-time
6744         scheduleUpdate:
6745           $ref: '#/components/schemas/VideoScheduledUpdate'
6746         thumbnailfile:
6747           description: Video thumbnail file
6748           type: string
6749           format: binary
6750         previewfile:
6751           description: Video preview file
6752           type: string
6753           format: binary
6754       required:
6755         - channelId
6756         - name
6757     VideoUploadRequestLegacy:
6758       allOf:
6759         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6760         - type: object
6761           required:
6762             - videofile
6763           properties:
6764             videofile:
6765               description: Video file
6766               type: string
6767               format: binary
6768     VideoUploadRequestResumable:
6769       allOf:
6770         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6771         - type: object
6772           required:
6773             - filename
6774           properties:
6775             filename:
6776               description: Video filename including extension
6777               type: string
6778               format: filename
6779               example: what_is_peertube.mp4
6780             thumbnailfile:
6781               description: Video thumbnail file
6782               type: string
6783               format: binary
6784             previewfile:
6785               description: Video preview file
6786               type: string
6787               format: binary
6788     VideoUploadResponse:
6789       properties:
6790         video:
6791           type: object
6792           properties:
6793             id:
6794               $ref: '#/components/schemas/Video/properties/id'
6795             uuid:
6796               $ref: '#/components/schemas/Video/properties/uuid'
6797             shortUUID:
6798               $ref: '#/components/schemas/Video/properties/shortUUID'
6799     CommentThreadResponse:
6800       properties:
6801         total:
6802           type: integer
6803           example: 1
6804         data:
6805           type: array
6806           maxItems: 100
6807           items:
6808             $ref: '#/components/schemas/VideoComment'
6809     CommentThreadPostResponse:
6810       properties:
6811         comment:
6812           $ref: '#/components/schemas/VideoComment'
6813     VideoListResponse:
6814       properties:
6815         total:
6816           type: integer
6817           example: 1
6818         data:
6819           type: array
6820           maxItems: 100
6821           items:
6822             $ref: '#/components/schemas/Video'
6823     User:
6824       properties:
6825         account:
6826           $ref: '#/components/schemas/Account'
6827         autoPlayNextVideo:
6828           type: boolean
6829           description: Automatically start playing the upcoming video after the currently playing video
6830         autoPlayNextVideoPlaylist:
6831           type: boolean
6832           description: Automatically start playing the video on the playlist after the currently playing video
6833         autoPlayVideo:
6834           type: boolean
6835           description: Automatically start playing the video on the watch page
6836         blocked:
6837           type: boolean
6838         blockedReason:
6839           type: string
6840         createdAt:
6841           type: string
6842         email:
6843           type: string
6844           format: email
6845           description: The user email
6846         emailVerified:
6847           type: boolean
6848           description: Has the user confirmed their email address?
6849         id:
6850           allOf:
6851             - $ref: '#/components/schemas/id'
6852           readOnly: true
6853         pluginAuth:
6854           type: string
6855           description: Auth plugin to use to authenticate the user
6856         lastLoginDate:
6857           type: string
6858           format: date-time
6859         noInstanceConfigWarningModal:
6860           type: boolean
6861         noAccountSetupWarningModal:
6862           type: boolean
6863         noWelcomeModal:
6864           type: boolean
6865         nsfwPolicy:
6866           $ref: '#/components/schemas/NSFWPolicy'
6867         role:
6868           $ref: '#/components/schemas/UserRole'
6869         roleLabel:
6870           type: string
6871           enum:
6872             - User
6873             - Moderator
6874             - Administrator
6875         theme:
6876           type: string
6877           description: Theme enabled by this user
6878         username:
6879           $ref: '#/components/schemas/username'
6880         videoChannels:
6881           type: array
6882           items:
6883             $ref: '#/components/schemas/VideoChannel'
6884         videoQuota:
6885           type: integer
6886           description: The user video quota in bytes
6887           example: -1
6888         videoQuotaDaily:
6889           type: integer
6890           description: The user daily video quota in bytes
6891           example: -1
6892         p2pEnabled:
6893           type: boolean
6894           description: Enable P2P in the player
6895     UserWithStats:
6896       allOf:
6897         - $ref: '#/components/schemas/User'
6898         - properties:
6899             # optionally present fields: they require WITH_STATS scope
6900             videosCount:
6901               type: integer
6902               description: Count of videos published
6903             abusesCount:
6904               type: integer
6905               description: Count of reports/abuses of which the user is a target
6906             abusesAcceptedCount:
6907               type: integer
6908               description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6909             abusesCreatedCount:
6910               type: integer
6911               description: Count of reports/abuses created by the user
6912             videoCommentsCount:
6913               type: integer
6914               description: Count of comments published
6915     AddUser:
6916       properties:
6917         username:
6918           $ref: '#/components/schemas/username'
6919         password:
6920           $ref: '#/components/schemas/password'
6921         email:
6922           type: string
6923           format: email
6924           description: The user email
6925         videoQuota:
6926           type: integer
6927           description: The user video quota in bytes
6928           example: -1
6929         videoQuotaDaily:
6930           type: integer
6931           description: The user daily video quota in bytes
6932           example: -1
6933         channelName:
6934           $ref: '#/components/schemas/usernameChannel'
6935         role:
6936           $ref: '#/components/schemas/UserRole'
6937         adminFlags:
6938           $ref: '#/components/schemas/UserAdminFlags'
6939       required:
6940         - username
6941         - password
6942         - email
6943         - videoQuota
6944         - videoQuotaDaily
6945         - role
6946     UpdateUser:
6947       properties:
6948         email:
6949           description: The updated email of the user
6950           allOf:
6951             - $ref: '#/components/schemas/User/properties/email'
6952         emailVerified:
6953           type: boolean
6954           description: Set the email as verified
6955         videoQuota:
6956           type: integer
6957           description: The updated video quota of the user in bytes
6958         videoQuotaDaily:
6959           type: integer
6960           description: The updated daily video quota of the user in bytes
6961         pluginAuth:
6962           type: string
6963           nullable: true
6964           description: The auth plugin to use to authenticate the user
6965           example: 'peertube-plugin-auth-saml2'
6966         role:
6967           $ref: '#/components/schemas/UserRole'
6968         adminFlags:
6969           $ref: '#/components/schemas/UserAdminFlags'
6970         password:
6971           $ref: '#/components/schemas/password'
6972     UpdateMe:
6973       # see shared/models/users/user-update-me.model.ts:
6974       properties:
6975         password:
6976           $ref: '#/components/schemas/password'
6977         currentPassword:
6978           $ref: '#/components/schemas/password'
6979         email:
6980           description: new email used for login and service communications
6981           allOf:
6982             - $ref: '#/components/schemas/User/properties/email'
6983         displayName:
6984           type: string
6985           description: new name of the user in its representations
6986           minLength: 3
6987           maxLength: 120
6988         displayNSFW:
6989           type: string
6990           description: new NSFW display policy
6991           enum:
6992             - 'true'
6993             - 'false'
6994             - both
6995         p2pEnabled:
6996           type: boolean
6997           description: whether to enable P2P in the player or not
6998         autoPlayVideo:
6999           type: boolean
7000           description: new preference regarding playing videos automatically
7001         autoPlayNextVideo:
7002           type: boolean
7003           description: new preference regarding playing following videos automatically
7004         autoPlayNextVideoPlaylist:
7005           type: boolean
7006           description: new preference regarding playing following playlist videos automatically
7007         videosHistoryEnabled:
7008           type: boolean
7009           description: whether to keep track of watched history or not
7010         videoLanguages:
7011           type: array
7012           items:
7013             type: string
7014           description: list of languages to filter videos down to
7015         theme:
7016           type: string
7017         noInstanceConfigWarningModal:
7018           type: boolean
7019         noAccountSetupWarningModal:
7020           type: boolean
7021         noWelcomeModal:
7022           type: boolean
7023     GetMeVideoRating:
7024       properties:
7025         id:
7026           $ref: '#/components/schemas/id'
7027         rating:
7028           type: string
7029           enum:
7030             - like
7031             - dislike
7032             - none
7033           description: Rating of the video
7034       required:
7035         - id
7036         - rating
7037     VideoRating:
7038       properties:
7039         video:
7040           $ref: '#/components/schemas/Video'
7041         rating:
7042           type: string
7043           enum:
7044             - like
7045             - dislike
7046             - none
7047           description: Rating of the video
7048       required:
7049         - video
7050         - rating
7051     RegisterUser:
7052       properties:
7053         username:
7054           description: immutable name of the user, used to find or mention its actor
7055           allOf:
7056             - $ref: '#/components/schemas/username'
7057         password:
7058           $ref: '#/components/schemas/password'
7059         email:
7060           type: string
7061           format: email
7062           description: email of the user, used for login or service communications
7063         displayName:
7064           type: string
7065           description: editable name of the user, displayed in its representations
7066           minLength: 1
7067           maxLength: 120
7068         channel:
7069           type: object
7070           description: channel base information used to create the first channel of the user
7071           properties:
7072             name:
7073               $ref: '#/components/schemas/usernameChannel'
7074             displayName:
7075               type: string
7076       required:
7077         - username
7078         - password
7079         - email
7080
7081     OAuthClient:
7082       properties:
7083         client_id:
7084           type: string
7085           pattern: /^[a-z0-9]$/
7086           maxLength: 32
7087           minLength: 32
7088           example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
7089         client_secret:
7090           type: string
7091           pattern: /^[a-zA-Z0-9]$/
7092           maxLength: 32
7093           minLength: 32
7094           example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
7095     OAuthToken-password:
7096       allOf:
7097         - $ref: '#/components/schemas/OAuthClient'
7098         - type: object
7099           properties:
7100             grant_type:
7101               type: string
7102               enum:
7103                 - password
7104                 - refresh_token
7105               default: password
7106             username:
7107               $ref: '#/components/schemas/User/properties/username'
7108             password:
7109               $ref: '#/components/schemas/password'
7110       required:
7111         - client_id
7112         - client_secret
7113         - grant_type
7114         - username
7115         - password
7116     OAuthToken-refresh_token:
7117       allOf:
7118         - $ref: '#/components/schemas/OAuthClient'
7119         - type: object
7120           properties:
7121             grant_type:
7122               type: string
7123               enum:
7124                 - password
7125                 - refresh_token
7126               default: password
7127             refresh_token:
7128               type: string
7129               example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
7130       required:
7131         - client_id
7132         - client_secret
7133         - grant_type
7134         - refresh_token
7135
7136     VideoChannel:
7137       allOf:
7138         - $ref: '#/components/schemas/Actor'
7139         - type: object
7140           properties:
7141             displayName:
7142               type: string
7143               description: editable name of the channel, displayed in its representations
7144               example: Videos of Framasoft
7145               minLength: 1
7146               maxLength: 120
7147             description:
7148               type: string
7149               example: Videos made with <3 by Framasoft
7150               minLength: 3
7151               maxLength: 1000
7152             support:
7153               type: string
7154               description: text shown by default on all videos of this channel, to tell the audience how to support it
7155               example: Please support our work on https://soutenir.framasoft.org/en/ <3
7156               minLength: 3
7157               maxLength: 1000
7158             isLocal:
7159               readOnly: true
7160               type: boolean
7161             updatedAt:
7162               readOnly: true
7163               type: string
7164               format: date-time
7165             banners:
7166               type: array
7167               items:
7168                 $ref: '#/components/schemas/ActorImage'
7169             ownerAccount:
7170               readOnly: true
7171               nullable: true
7172               type: object
7173               properties:
7174                 id:
7175                   type: integer
7176                 uuid:
7177                   $ref: '#/components/schemas/UUIDv4'
7178     VideoChannelCreate:
7179       allOf:
7180         - $ref: '#/components/schemas/VideoChannel'
7181         - properties:
7182             name:
7183               description: username of the channel to create
7184               allOf:
7185                 - $ref: '#/components/schemas/usernameChannel'
7186       required:
7187         - name
7188         - displayName
7189     VideoChannelUpdate:
7190       allOf:
7191         - $ref: '#/components/schemas/VideoChannel'
7192         - properties:
7193             bulkVideosSupportUpdate:
7194               type: boolean
7195               description: Update the support field for all videos of this channel
7196     VideoChannelList:
7197       properties:
7198         total:
7199           type: integer
7200           example: 1
7201         data:
7202           type: array
7203           items:
7204             allOf:
7205               - $ref: '#/components/schemas/VideoChannel'
7206               - $ref: '#/components/schemas/Actor'
7207
7208     MRSSPeerLink:
7209       type: object
7210       xml:
7211         name: 'media:peerLink'
7212       properties:
7213         href:
7214           type: string
7215           xml:
7216             attribute: true
7217         type:
7218           type: string
7219           enum:
7220             - application/x-bittorrent
7221           xml:
7222             attribute: true
7223     MRSSGroupContent:
7224       type: object
7225       xml:
7226         name: 'media:content'
7227       properties:
7228         url:
7229           type: string
7230           format: url
7231           xml:
7232             attribute: true
7233         fileSize:
7234           type: integer
7235           xml:
7236             attribute: true
7237         type:
7238           type: string
7239           xml:
7240             attribute: true
7241         framerate:
7242           type: integer
7243           xml:
7244             attribute: true
7245         duration:
7246           type: integer
7247           xml:
7248             attribute: true
7249         height:
7250           type: integer
7251           xml:
7252             attribute: true
7253         lang:
7254           type: string
7255           xml:
7256             attribute: true
7257     VideoCommentsForXML:
7258       type: array
7259       xml:
7260         wrapped: true
7261         name: 'channel'
7262       items:
7263         type: object
7264         xml:
7265           name: 'item'
7266         properties:
7267           link:
7268             type: string
7269             format: url
7270           guid:
7271             type: string
7272           pubDate:
7273             type: string
7274             format: date-time
7275           'content:encoded':
7276             type: string
7277           'dc:creator':
7278             type: string
7279     VideosForXML:
7280       type: array
7281       xml:
7282         wrapped: true
7283         name: 'channel'
7284       items:
7285         type: object
7286         xml:
7287           name: 'item'
7288         properties:
7289           link:
7290             type: string
7291             format: url
7292             description: video watch page URL
7293           guid:
7294             type: string
7295             description: video canonical URL
7296           pubDate:
7297             type: string
7298             format: date-time
7299             description: video publication date
7300           description:
7301             type: string
7302             description: video description
7303           'content:encoded':
7304             type: string
7305             description: video description
7306           'dc:creator':
7307             type: string
7308             description: publisher user name
7309           'media:category':
7310             type: integer
7311             description: video category (MRSS)
7312           'media:community':
7313             type: object
7314             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
7315             properties:
7316               'media:statistics':
7317                 type: object
7318                 properties:
7319                   views:
7320                     type: integer
7321                     xml:
7322                       attribute: true
7323           'media:embed':
7324             type: object
7325             properties:
7326               url:
7327                 type: string
7328                 format: url
7329                 description: video embed path, relative to the canonical URL domain (MRSS)
7330                 xml:
7331                   attribute: true
7332           'media:player':
7333             type: object
7334             properties:
7335               url:
7336                 type: string
7337                 format: url
7338                 description: video watch path, relative to the canonical URL domain (MRSS)
7339                 xml:
7340                   attribute: true
7341           'media:thumbnail':
7342             type: object
7343             properties:
7344               url:
7345                 type: string
7346                 format: url
7347                 xml:
7348                   attribute: true
7349               height:
7350                 type: integer
7351                 xml:
7352                   attribute: true
7353               width:
7354                 type: integer
7355                 xml:
7356                   attribute: true
7357           'media:title':
7358             type: string
7359             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
7360           'media:description':
7361             type: string
7362           'media:rating':
7363             type: string
7364             enum:
7365               - nonadult
7366               - adult
7367             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
7368           'enclosure':
7369             type: object
7370             description: main streamable file for the video
7371             properties:
7372               url:
7373                 type: string
7374                 format: url
7375                 xml:
7376                   attribute: true
7377               type:
7378                 type: string
7379                 enum:
7380                   - application/x-bittorrent
7381                 xml:
7382                   attribute: true
7383               length:
7384                 type: integer
7385                 xml:
7386                   attribute: true
7387           'media:group':
7388             type: array
7389             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)
7390             items:
7391               anyOf:
7392                 - $ref: '#/components/schemas/MRSSPeerLink'
7393                 - $ref: '#/components/schemas/MRSSGroupContent'
7394     NotificationSettingValue:
7395       type: integer
7396       description: >
7397         Notification type
7398
7399         - `0` NONE
7400
7401         - `1` WEB
7402
7403         - `2` EMAIL
7404       enum:
7405         - 0
7406         - 1
7407         - 2
7408     Notification:
7409       properties:
7410         id:
7411           $ref: '#/components/schemas/id'
7412         type:
7413           type: integer
7414           description: >
7415             Notification type, following the `UserNotificationType` enum:
7416
7417             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
7418
7419             - `2` NEW_COMMENT_ON_MY_VIDEO
7420
7421             - `3` NEW_ABUSE_FOR_MODERATORS
7422
7423             - `4` BLACKLIST_ON_MY_VIDEO
7424
7425             - `5` UNBLACKLIST_ON_MY_VIDEO
7426
7427             - `6` MY_VIDEO_PUBLISHED
7428
7429             - `7` MY_VIDEO_IMPORT_SUCCESS
7430
7431             - `8` MY_VIDEO_IMPORT_ERROR
7432
7433             - `9` NEW_USER_REGISTRATION
7434
7435             - `10` NEW_FOLLOW
7436
7437             - `11` COMMENT_MENTION
7438
7439             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
7440
7441             - `13` NEW_INSTANCE_FOLLOWER
7442
7443             - `14` AUTO_INSTANCE_FOLLOWING
7444
7445             - `15` ABUSE_STATE_CHANGE
7446
7447             - `16` ABUSE_NEW_MESSAGE
7448
7449             - `17` NEW_PLUGIN_VERSION
7450
7451             - `18` NEW_PEERTUBE_VERSION
7452         read:
7453           type: boolean
7454         video:
7455           nullable: true
7456           allOf:
7457             - $ref: '#/components/schemas/VideoInfo'
7458             - type: object
7459               properties:
7460                 channel:
7461                   $ref: '#/components/schemas/ActorInfo'
7462         videoImport:
7463           nullable: true
7464           type: object
7465           properties:
7466             id:
7467               $ref: '#/components/schemas/id'
7468             video:
7469               nullable: true
7470               $ref: '#/components/schemas/VideoInfo'
7471             torrentName:
7472               type: string
7473               nullable: true
7474             magnetUri:
7475               $ref: '#/components/schemas/VideoImport/properties/magnetUri'
7476             targetUri:
7477               type: string
7478               format: uri
7479               nullable: true
7480         comment:
7481           nullable: true
7482           type: object
7483           properties:
7484             id:
7485               $ref: '#/components/schemas/id'
7486             threadId:
7487               type: integer
7488             video:
7489               $ref: '#/components/schemas/VideoInfo'
7490             account:
7491               $ref: '#/components/schemas/ActorInfo'
7492         videoAbuse:
7493           nullable: true
7494           type: object
7495           properties:
7496             id:
7497               $ref: '#/components/schemas/id'
7498             video:
7499               allOf:
7500                 - $ref: '#/components/schemas/VideoInfo'
7501         videoBlacklist:
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         account:
7511           nullable: true
7512           allOf:
7513             - $ref: '#/components/schemas/ActorInfo'
7514         actorFollow:
7515           type: object
7516           nullable: true
7517           properties:
7518             id:
7519               $ref: '#/components/schemas/id'
7520             follower:
7521               $ref: '#/components/schemas/ActorInfo'
7522             state:
7523               type: string
7524               enum:
7525                 - pending
7526                 - accepted
7527             following:
7528               type: object
7529               properties:
7530                 type:
7531                   type: string
7532                   enum:
7533                     - account
7534                     - channel
7535                     - instance
7536                 name:
7537                   type: string
7538                 displayName:
7539                   type: string
7540                 host:
7541                   type: string
7542                   format: hostname
7543         createdAt:
7544           type: string
7545           format: date-time
7546         updatedAt:
7547           type: string
7548           format: date-time
7549     NotificationListResponse:
7550       properties:
7551         total:
7552           type: integer
7553           example: 1
7554         data:
7555           type: array
7556           maxItems: 100
7557           items:
7558             $ref: '#/components/schemas/Notification'
7559     Plugin:
7560       properties:
7561         name:
7562           type: string
7563           example: peertube-plugin-auth-ldap
7564         type:
7565           type: integer
7566           description: >
7567             - `1`: PLUGIN
7568
7569             - `2`: THEME
7570           enum:
7571             - 1
7572             - 2
7573         latestVersion:
7574           type: string
7575           example: 0.0.3
7576         version:
7577           type: string
7578           example: 0.0.1
7579         enabled:
7580           type: boolean
7581         uninstalled:
7582           type: boolean
7583         peertubeEngine:
7584           type: string
7585           example: 2.2.0
7586         description:
7587           type: string
7588         homepage:
7589           type: string
7590           format: url
7591           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
7592         settings:
7593           type: object
7594           additionalProperties: true
7595         createdAt:
7596           type: string
7597           format: date-time
7598         updatedAt:
7599           type: string
7600           format: date-time
7601     PluginResponse:
7602       properties:
7603         total:
7604           type: integer
7605           example: 1
7606         data:
7607           type: array
7608           maxItems: 100
7609           items:
7610             $ref: '#/components/schemas/Plugin'
7611
7612     LiveVideoUpdate:
7613       properties:
7614         saveReplay:
7615           type: boolean
7616         permanentLive:
7617           description: User can stream multiple times in a permanent live
7618           type: boolean
7619         latencyMode:
7620           description: User can select live latency mode if enabled by the instance
7621           $ref: '#/components/schemas/LiveVideoLatencyMode'
7622
7623     LiveVideoResponse:
7624       properties:
7625         rtmpUrl:
7626           type: string
7627         rtmpsUrl:
7628           type: string
7629         streamKey:
7630           type: string
7631           description: RTMP stream key to use to stream into this live video
7632         saveReplay:
7633           type: boolean
7634         permanentLive:
7635           description: User can stream multiple times in a permanent live
7636           type: boolean
7637         latencyMode:
7638           description: User can select live latency mode if enabled by the instance
7639           $ref: '#/components/schemas/LiveVideoLatencyMode'
7640
7641   callbacks:
7642     searchIndex:
7643       'https://search.example.org/api/v1/search/videos':
7644         post:
7645           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
7646           responses:
7647             '200':
7648               description: successful operation
7649               content:
7650                 application/json:
7651                   schema:
7652                     $ref: '#/components/schemas/VideoListResponse'