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