support/doc/api/openapi.yaml

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