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