support/doc/api/openapi.yaml

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