support/doc/api/openapi.yaml

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