support/doc/api/openapi.yaml

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