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