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