support/doc/api/openapi.yaml

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