support/doc/api/openapi.yaml

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