support/doc/api/openapi.yaml

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