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 with 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/createUser) 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: createUser
 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             GetUserId:
 709               operationId: getUserId
 710               parameters:
 711                 id: '$response.body#/user/id'
 712             # PUT /users/{id}
 713             PutUserId:
 714               operationId: putUserId
 715               parameters:
 716                 id: '$response.body#/user/id'
 717             # DELETE /users/{id}
 718             DelUserId:
 719               operationId: delUserId
 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: delUserId
 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: getUserId
 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: putUserId
 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       tags:
1497         - Video
1498       parameters:
1499         - $ref: '#/components/parameters/categoryOneOf'
1500         - $ref: '#/components/parameters/isLive'
1501         - $ref: '#/components/parameters/tagsOneOf'
1502         - $ref: '#/components/parameters/tagsAllOf'
1503         - $ref: '#/components/parameters/licenceOneOf'
1504         - $ref: '#/components/parameters/languageOneOf'
1505         - $ref: '#/components/parameters/nsfw'
1506         - $ref: '#/components/parameters/filter'
1507         - $ref: '#/components/parameters/skipCount'
1508         - $ref: '#/components/parameters/start'
1509         - $ref: '#/components/parameters/count'
1510         - $ref: '#/components/parameters/videosSort'
1511       responses:
1512         '200':
1513           description: successful operation
1514           content:
1515             application/json:
1516               schema:
1517                 $ref: '#/components/schemas/VideoListResponse'
1518
1519   /videos/categories:
1520     get:
1521       summary: List available video categories
1522       operationId: getCategories
1523       tags:
1524         - Video
1525       responses:
1526         '200':
1527           description: successful operation
1528           content:
1529             application/json:
1530               schema:
1531                 type: array
1532                 items:
1533                   type: string
1534               examples:
1535                 nightly:
1536                   externalValue: https://peertube2.cpy.re/api/v1/videos/categories
1537
1538   /videos/licences:
1539     get:
1540       summary: List available video licences
1541       operationId: getLicences
1542       tags:
1543         - Video
1544       responses:
1545         '200':
1546           description: successful operation
1547           content:
1548             application/json:
1549               schema:
1550                 type: array
1551                 items:
1552                   type: string
1553               examples:
1554                 nightly:
1555                   externalValue: https://peertube2.cpy.re/api/v1/videos/licences
1556
1557   /videos/languages:
1558     get:
1559       summary: List available video languages
1560       operationId: getLanguages
1561       tags:
1562         - Video
1563       responses:
1564         '200':
1565           description: successful operation
1566           content:
1567             application/json:
1568               schema:
1569                 type: array
1570                 items:
1571                   type: string
1572               examples:
1573                 nightly:
1574                   externalValue: https://peertube2.cpy.re/api/v1/videos/languages
1575
1576   /videos/privacies:
1577     get:
1578       summary: List available video privacy policies
1579       operationId: getPrivacyPolicies
1580       tags:
1581         - Video
1582       responses:
1583         '200':
1584           description: successful operation
1585           content:
1586             application/json:
1587               schema:
1588                 type: array
1589                 items:
1590                   type: string
1591               examples:
1592                 nightly:
1593                   externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
1594
1595   '/videos/{id}':
1596     put:
1597       summary: Update a video
1598       operationId: putVideo
1599       security:
1600         - OAuth2: []
1601       tags:
1602         - Video
1603       parameters:
1604         - $ref: '#/components/parameters/idOrUUID'
1605       responses:
1606         '204':
1607           description: successful operation
1608       requestBody:
1609         content:
1610           multipart/form-data:
1611             schema:
1612               type: object
1613               properties:
1614                 thumbnailfile:
1615                   description: Video thumbnail file
1616                   type: string
1617                   format: binary
1618                 previewfile:
1619                   description: Video preview file
1620                   type: string
1621                   format: binary
1622                 category:
1623                   $ref: '#/components/schemas/VideoCategorySet'
1624                 licence:
1625                   $ref: '#/components/schemas/VideoLicenceSet'
1626                 language:
1627                   $ref: '#/components/schemas/VideoLanguageSet'
1628                 privacy:
1629                   $ref: '#/components/schemas/VideoPrivacySet'
1630                 description:
1631                   description: Video description
1632                   type: string
1633                 waitTranscoding:
1634                   description: Whether or not we wait transcoding before publish the video
1635                   type: string
1636                 support:
1637                   description: A text tell the audience how to support the video creator
1638                   example: Please support our work on https://soutenir.framasoft.org/en/ <3
1639                   type: string
1640                 nsfw:
1641                   description: Whether or not this video contains sensitive content
1642                   type: boolean
1643                 name:
1644                   description: Video name
1645                   type: string
1646                   minLength: 3
1647                   maxLength: 120
1648                 tags:
1649                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
1650                   type: array
1651                   minItems: 1
1652                   maxItems: 5
1653                   items:
1654                     type: string
1655                     minLength: 2
1656                     maxLength: 30
1657                 commentsEnabled:
1658                   description: Enable or disable comments for this video
1659                   type: boolean
1660                 originallyPublishedAt:
1661                   description: Date when the content was originally published
1662                   type: string
1663                   format: date-time
1664                 scheduleUpdate:
1665                   $ref: '#/components/schemas/VideoScheduledUpdate'
1666             encoding:
1667               thumbnailfile:
1668                 contentType: image/jpeg
1669               previewfile:
1670                 contentType: image/jpeg
1671     get:
1672       summary: Get a video
1673       operationId: getVideo
1674       tags:
1675         - Video
1676       parameters:
1677         - $ref: '#/components/parameters/idOrUUID'
1678       responses:
1679         '200':
1680           description: successful operation
1681           content:
1682             application/json:
1683               schema:
1684                 $ref: '#/components/schemas/VideoDetails'
1685     delete:
1686       summary: Delete a video
1687       operationId: delVideo
1688       security:
1689         - OAuth2: []
1690       tags:
1691         - Video
1692       parameters:
1693         - $ref: '#/components/parameters/idOrUUID'
1694       responses:
1695         '204':
1696           description: successful operation
1697
1698   '/videos/{id}/description':
1699     get:
1700       summary: Get complete video description
1701       operationId: getVideoDesc
1702       tags:
1703         - Video
1704       parameters:
1705         - $ref: '#/components/parameters/idOrUUID'
1706       responses:
1707         '200':
1708           description: successful operation
1709           content:
1710             application/json:
1711               schema:
1712                 nullable: true
1713                 type: string
1714                 minLength: 3
1715                 maxLength: 10000
1716                 example: |
1717                   **[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)**
1718
1719   '/videos/{id}/views':
1720     post:
1721       summary: Add a view to a video
1722       tags:
1723         - Video
1724       parameters:
1725         - $ref: '#/components/parameters/idOrUUID'
1726       responses:
1727         '204':
1728           description: successful operation
1729
1730   '/videos/{id}/watching':
1731     put:
1732       summary: Set watching progress of a video
1733       tags:
1734         - Video
1735       security:
1736         - OAuth2: []
1737       parameters:
1738         - $ref: '#/components/parameters/idOrUUID'
1739       requestBody:
1740         content:
1741           application/json:
1742             schema:
1743               $ref: '#/components/schemas/UserWatchingVideo'
1744         required: true
1745       responses:
1746         '204':
1747           description: successful operation
1748
1749   /videos/upload:
1750     post:
1751       summary: Upload a video
1752       description: Uses a single request to upload a video.
1753       operationId: uploadLegacy
1754       security:
1755         - OAuth2: []
1756       tags:
1757         - Video
1758         - Video Upload
1759       responses:
1760         '200':
1761           description: successful operation
1762           content:
1763             application/json:
1764               schema:
1765                 $ref: '#/components/schemas/VideoUploadResponse'
1766         '400':
1767           description: invalid file field, schedule date or parameter
1768         '403':
1769           description: video didn't pass upload filter
1770         '408':
1771           description: upload has timed out
1772         '413':
1773           description: video file too large, due to quota or max body size limit set by the reverse-proxy
1774           headers:
1775             X-File-Maximum-Size:
1776               schema:
1777                 type: string
1778                 format: Nginx size
1779               description: Maximum file size for the video
1780         '415':
1781           description: video type unsupported
1782         '422':
1783           description: video unreadable
1784       requestBody:
1785         content:
1786           multipart/form-data:
1787             schema:
1788               $ref: '#/components/schemas/VideoUploadRequestLegacy'
1789             encoding:
1790               videofile:
1791                 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1792               thumbnailfile:
1793                 contentType: image/jpeg
1794               previewfile:
1795                 contentType: image/jpeg
1796       x-codeSamples:
1797         - lang: Shell
1798           source: |
1799             ## DEPENDENCIES: jq
1800             USERNAME="<your_username>"
1801             PASSWORD="<your_password>"
1802             FILE_PATH="<your_file_path>"
1803             CHANNEL_ID="<your_channel_id>"
1804             NAME="<video_name>"
1805             API="https://peertube2.cpy.re/api/v1"
1806
1807             ## AUTH
1808             client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
1809             client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
1810             token=$(curl -s "$API/users/token" \
1811               --data client_id="$client_id" \
1812               --data client_secret="$client_secret" \
1813               --data grant_type=password \
1814               --data username="$USERNAME" \
1815               --data password="$PASSWORD" \
1816               | jq -r ".access_token")
1817
1818             ## VIDEO UPLOAD
1819             curl -s "$API/videos/upload" \
1820               -H "Authorization: Bearer $token" \
1821               --max-time 600 \
1822               --form videofile=@"$FILE_PATH" \
1823               --form channelId=$CHANNEL_ID \
1824               --form name="$NAME"
1825
1826   /videos/upload-resumable:
1827     post:
1828       summary: Initialize the resumable upload of a video
1829       description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
1830       operationId: uploadResumableInit
1831       security:
1832         - OAuth2: []
1833       tags:
1834         - Video
1835         - Video Upload
1836       parameters:
1837         - name: X-Upload-Content-Length
1838           in: header
1839           schema:
1840             type: number
1841             example: 2469036
1842           required: true
1843           description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
1844         - name: X-Upload-Content-Type
1845           in: header
1846           schema:
1847             type: string
1848             format: mimetype
1849             example: video/mp4
1850           required: true
1851           description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
1852       requestBody:
1853         content:
1854           application/json:
1855             schema:
1856               $ref: '#/components/schemas/VideoUploadRequestResumable'
1857       responses:
1858         '200':
1859           description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
1860         '201':
1861           description: created
1862           headers:
1863             Location:
1864               schema:
1865                 type: string
1866                 format: url
1867                 example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
1868             Content-Length:
1869               schema:
1870                 type: number
1871                 example: 0
1872         '400':
1873           description: invalid file field, schedule date or parameter
1874         '413':
1875           description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
1876         '415':
1877           description: video type unsupported
1878     put:
1879       summary: Send chunk for the resumable upload of a video
1880       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
1881       operationId: uploadResumable
1882       security:
1883         - OAuth2: []
1884       tags:
1885         - Video
1886         - Video Upload
1887       parameters:
1888         - name: upload_id
1889           in: path
1890           required: true
1891           description: |
1892             Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1893             not valid anymore and you need to initialize a new upload.
1894           schema:
1895             type: string
1896         - name: Content-Range
1897           in: header
1898           schema:
1899             type: string
1900             example: bytes 0-262143/2469036
1901           required: true
1902           description: |
1903             Specifies the bytes in the file that the request is uploading.
1904
1905             For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
1906             262144 bytes (256 x 1024) in a 2,469,036 byte file.
1907         - name: Content-Length
1908           in: header
1909           schema:
1910             type: number
1911             example: 262144
1912           required: true
1913           description: |
1914             Size of the chunk that the request is sending.
1915
1916             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)
1917             doesn't mandate for chunks to have the same size throughout the upload sequence.
1918
1919             Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
1920             1048576 bytes (~1MB) and increases or reduces size depending on connection health.
1921       requestBody:
1922         content:
1923           application/octet-stream:
1924             schema:
1925               type: string
1926               format: binary
1927       responses:
1928         '200':
1929           description: last chunk received
1930           headers:
1931             Content-Length:
1932               schema:
1933                 type: number
1934           content:
1935             application/json:
1936               schema:
1937                 $ref: '#/components/schemas/VideoUploadResponse'
1938         '308':
1939           description: resume incomplete
1940           headers:
1941             Range:
1942               schema:
1943                 type: string
1944                 example: bytes=0-262143
1945             Content-Length:
1946               schema:
1947                 type: number
1948                 example: 0
1949         '403':
1950           description: video didn't pass upload filter
1951         '413':
1952           description: video file too large, due to quota or max body size limit set by the reverse-proxy
1953         '422':
1954           description: video unreadable
1955     delete:
1956       summary: Cancel the resumable upload of a video, deleting any data uploaded so far
1957       description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
1958       operationId: uploadResumableCancel
1959       security:
1960         - OAuth2: []
1961       tags:
1962         - Video
1963         - Video Upload
1964       parameters:
1965         - name: upload_id
1966           in: path
1967           required: true
1968           description: |
1969             Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
1970             not valid anymore and the upload session has already been deleted with its data ;-)
1971           schema:
1972             type: string
1973         - name: Content-Length
1974           in: header
1975           required: true
1976           schema:
1977             type: number
1978             example: 0
1979       responses:
1980         '204':
1981           description: upload cancelled
1982           headers:
1983             Content-Length:
1984               schema:
1985                 type: number
1986                 example: 0
1987
1988   /videos/imports:
1989     post:
1990       summary: Import a video
1991       description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1992       operationId: importVideo
1993       security:
1994         - OAuth2: []
1995       tags:
1996         - Video
1997         - Video Upload
1998       requestBody:
1999         content:
2000           multipart/form-data:
2001             schema:
2002               $ref: '#/components/schemas/VideoCreateImport'
2003             encoding:
2004               torrentfile:
2005                 contentType: application/x-bittorrent
2006               thumbnailfile:
2007                 contentType: image/jpeg
2008               previewfile:
2009                 contentType: image/jpeg
2010       responses:
2011         '200':
2012           description: successful operation
2013           content:
2014             application/json:
2015               schema:
2016                 $ref: '#/components/schemas/VideoUploadResponse'
2017         '400':
2018           description: '`magnetUri` or `targetUrl` or a torrent file missing'
2019         '403':
2020           description: video didn't pass pre-import filter
2021         '409':
2022           description: HTTP or Torrent/magnetURI import not enabled
2023
2024   /videos/live:
2025     post:
2026       summary: Create a live
2027       operationId: createLive
2028       security:
2029         - OAuth2: []
2030       tags:
2031         - Live Videos
2032         - Video
2033       responses:
2034         '200':
2035           description: successful operation
2036           content:
2037             application/json:
2038               schema:
2039                 $ref: '#/components/schemas/VideoUploadResponse'
2040         '403':
2041           description: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
2042       requestBody:
2043         content:
2044           multipart/form-data:
2045             schema:
2046               type: object
2047               properties:
2048                 channelId:
2049                   description: Channel id that will contain this live video
2050                   type: integer
2051                 saveReplay:
2052                   type: boolean
2053                 permanentLive:
2054                   description: User can stream multiple times in a permanent live
2055                   type: boolean
2056                 thumbnailfile:
2057                   description: Live video/replay thumbnail file
2058                   type: string
2059                   format: binary
2060                 previewfile:
2061                   description: Live video/replay preview file
2062                   type: string
2063                   format: binary
2064                 privacy:
2065                   $ref: '#/components/schemas/VideoPrivacySet'
2066                 category:
2067                   $ref: '#/components/schemas/VideoCategorySet'
2068                 licence:
2069                   $ref: '#/components/schemas/VideoLicenceSet'
2070                 language:
2071                   $ref: '#/components/schemas/VideoLanguageSet'
2072                 description:
2073                   description: Live video/replay description
2074                   type: string
2075                 support:
2076                   description: A text tell the audience how to support the creator
2077                   example: Please support our work on https://soutenir.framasoft.org/en/ <3
2078                   type: string
2079                 nsfw:
2080                   description: Whether or not this live video/replay contains sensitive content
2081                   type: boolean
2082                 name:
2083                   description: Live video/replay name
2084                   type: string
2085                   minLength: 3
2086                   maxLength: 120
2087                 tags:
2088                   description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
2089                   type: array
2090                   minItems: 1
2091                   maxItems: 5
2092                   items:
2093                     type: string
2094                     minLength: 2
2095                     maxLength: 30
2096                 commentsEnabled:
2097                   description: Enable or disable comments for this live video/replay
2098                   type: boolean
2099                 downloadEnabled:
2100                   description: Enable or disable downloading for the replay of this live
2101                   type: boolean
2102               required:
2103                 - channelId
2104                 - name
2105             encoding:
2106               thumbnailfile:
2107                 contentType: image/jpeg
2108               previewfile:
2109                 contentType: image/jpeg
2110
2111   /videos/live/{id}:
2112     get:
2113       summary: Get information about a live
2114       operationId: getLiveId
2115       security:
2116         - OAuth2: []
2117       tags:
2118         - Live Videos
2119         - Video
2120       parameters:
2121         - $ref: '#/components/parameters/idOrUUID'
2122       responses:
2123         '200':
2124           description: successful operation
2125           content:
2126             application/json:
2127               schema:
2128                 $ref: '#/components/schemas/LiveVideoResponse'
2129     put:
2130       summary: Update information about a live
2131       operationId: updateLiveId
2132       security:
2133         - OAuth2: []
2134       tags:
2135         - Live Videos
2136         - Video
2137       parameters:
2138         - $ref: '#/components/parameters/idOrUUID'
2139       requestBody:
2140         content:
2141           application/json:
2142             schema:
2143               $ref: '#/components/schemas/LiveVideoUpdate'
2144       responses:
2145         '204':
2146           description: successful operation
2147         '400':
2148           description: bad parameters or trying to update a live that has already started
2149         '403':
2150           description: trying to save replay of the live but saving replay is not enabled on the instance
2151
2152   /users/me/abuses:
2153     get:
2154       summary: List my abuses
2155       operationId: getMyAbuses
2156       security:
2157         - OAuth2: []
2158       tags:
2159         - Abuses
2160         - My User
2161       parameters:
2162         - name: id
2163           in: query
2164           description: only list the report with this id
2165           schema:
2166             type: integer
2167         - name: state
2168           in: query
2169           schema:
2170             $ref: '#/components/schemas/AbuseStateSet'
2171         - $ref: '#/components/parameters/abusesSort'
2172         - $ref: '#/components/parameters/start'
2173         - $ref: '#/components/parameters/count'
2174       responses:
2175         '200':
2176           description: successful operation
2177           content:
2178             application/json:
2179               schema:
2180                 type: object
2181                 properties:
2182                   total:
2183                     type: integer
2184                     example: 1
2185                   data:
2186                     type: array
2187                     items:
2188                       $ref: '#/components/schemas/Abuse'
2189
2190   /abuses:
2191     get:
2192       summary: List abuses
2193       operationId: getAbuses
2194       security:
2195         - OAuth2:
2196           - admin
2197           - moderator
2198       tags:
2199         - Abuses
2200       parameters:
2201         - name: id
2202           in: query
2203           description: only list the report with this id
2204           schema:
2205             type: integer
2206         - name: predefinedReason
2207           in: query
2208           description: predefined reason the listed reports should contain
2209           schema:
2210             $ref: '#/components/schemas/PredefinedAbuseReasons'
2211         - name: search
2212           in: query
2213           description: plain search that will match with video titles, reporter names and more
2214           schema:
2215             type: string
2216         - name: state
2217           in: query
2218           schema:
2219             $ref: '#/components/schemas/AbuseStateSet'
2220         - name: searchReporter
2221           in: query
2222           description: only list reports of a specific reporter
2223           schema:
2224             type: string
2225         - name: searchReportee
2226           description: only list reports of a specific reportee
2227           in: query
2228           schema:
2229             type: string
2230         - name: searchVideo
2231           in: query
2232           description: only list reports of a specific video
2233           schema:
2234             type: string
2235         - name: searchVideoChannel
2236           in: query
2237           description: only list reports of a specific video channel
2238           schema:
2239             type: string
2240         - name: videoIs
2241           in: query
2242           description: only list blacklisted or deleted videos
2243           schema:
2244             type: string
2245             enum:
2246             - 'deleted'
2247             - 'blacklisted'
2248         - name: filter
2249           in: query
2250           description: only list account, comment or video reports
2251           schema:
2252             type: string
2253             enum:
2254             - 'video'
2255             - 'comment'
2256             - 'account'
2257         - $ref: '#/components/parameters/start'
2258         - $ref: '#/components/parameters/count'
2259         - $ref: '#/components/parameters/abusesSort'
2260       responses:
2261         '200':
2262           description: successful operation
2263           content:
2264             application/json:
2265               schema:
2266                 type: object
2267                 properties:
2268                   total:
2269                     type: integer
2270                     example: 1
2271                   data:
2272                     type: array
2273                     items:
2274                       $ref: '#/components/schemas/Abuse'
2275     post:
2276       summary: Report an abuse
2277       security:
2278         - OAuth2: []
2279       tags:
2280         - Abuses
2281       requestBody:
2282         required: true
2283         content:
2284           application/json:
2285             schema:
2286               type: object
2287               properties:
2288                 reason:
2289                   description: Reason why the user reports this video
2290                   type: string
2291                   minLength: 2
2292                   maxLength: 3000
2293                 predefinedReasons:
2294                   $ref: '#/components/schemas/PredefinedAbuseReasons'
2295                 video:
2296                   type: object
2297                   properties:
2298                     id:
2299                       description: Video id to report
2300                       allOf:
2301                         - $ref: '#/components/schemas/Video/properties/id'
2302                     startAt:
2303                       type: integer
2304                       format: seconds
2305                       description: Timestamp in the video that marks the beginning of the report
2306                       minimum: 0
2307                     endAt:
2308                       type: integer
2309                       format: seconds
2310                       description: Timestamp in the video that marks the ending of the report
2311                       minimum: 0
2312                 comment:
2313                   type: object
2314                   properties:
2315                     id:
2316                       description: Comment id to report
2317                       allOf:
2318                         - $ref: '#/components/schemas/VideoComment/properties/id'
2319                 account:
2320                   type: object
2321                   properties:
2322                     id:
2323                       description: Account id to report
2324                       type: integer
2325               required:
2326                 - reason
2327       responses:
2328         '200':
2329           description: successful operation
2330           content:
2331             application/json:
2332               schema:
2333                 type: object
2334                 properties:
2335                   abuse:
2336                     type: object
2337                     properties:
2338                       id:
2339                         $ref: '#/components/schemas/id'
2340         '400':
2341           description: incorrect request parameters
2342
2343   '/abuses/{abuseId}':
2344     put:
2345       summary: Update an abuse
2346       security:
2347         - OAuth2:
2348           - admin
2349           - moderator
2350       tags:
2351         - Abuses
2352       parameters:
2353         - $ref: '#/components/parameters/abuseId'
2354       requestBody:
2355         content:
2356           application/json:
2357             schema:
2358               type: object
2359               properties:
2360                 state:
2361                   $ref: '#/components/schemas/AbuseStateSet'
2362                 moderationComment:
2363                   type: string
2364                   description: Update the report comment visible only to the moderation team
2365                   minLength: 2
2366                   maxLength: 3000
2367       responses:
2368         '204':
2369           description: successful operation
2370         '404':
2371           description: abuse not found
2372     delete:
2373       tags:
2374         - Abuses
2375       summary: Delete an abuse
2376       security:
2377         - OAuth2:
2378           - admin
2379           - moderator
2380       parameters:
2381         - $ref: '#/components/parameters/abuseId'
2382       responses:
2383         '204':
2384           description: successful operation
2385         '404':
2386           description: block not found
2387
2388   '/abuses/{abuseId}/messages':
2389     get:
2390       summary: List messages of an abuse
2391       security:
2392         - OAuth2: []
2393       tags:
2394         - Abuses
2395       parameters:
2396         - $ref: '#/components/parameters/abuseId'
2397       responses:
2398         '200':
2399           description: successful operation
2400           content:
2401             application/json:
2402               schema:
2403                 type: object
2404                 properties:
2405                   total:
2406                     type: integer
2407                     example: 1
2408                   data:
2409                     type: array
2410                     items:
2411                       $ref: '#/components/schemas/AbuseMessage'
2412     post:
2413       summary: Add message to an abuse
2414       security:
2415         - OAuth2: []
2416       tags:
2417         - Abuses
2418       parameters:
2419         - $ref: '#/components/parameters/abuseId'
2420       requestBody:
2421         required: true
2422         content:
2423           application/json:
2424             schema:
2425               type: object
2426               properties:
2427                 message:
2428                   description: Message to send
2429                   type: string
2430                   minLength: 2
2431                   maxLength: 3000
2432               required:
2433                 - message
2434       responses:
2435         '200':
2436           description: successful operation
2437         '400':
2438           description: incorrect request parameters
2439
2440   '/abuses/{abuseId}/messages/{abuseMessageId}':
2441     delete:
2442       summary: Delete an abuse message
2443       security:
2444         - OAuth2: []
2445       tags:
2446         - Abuses
2447       parameters:
2448         - $ref: '#/components/parameters/abuseId'
2449         - $ref: '#/components/parameters/abuseMessageId'
2450       responses:
2451         '204':
2452           description: successful operation
2453
2454   '/videos/{id}/blacklist':
2455     post:
2456       summary: Block a video
2457       operationId: addVideoBlock
2458       security:
2459         - OAuth2:
2460           - admin
2461           - moderator
2462       tags:
2463         - Video Blocks
2464       parameters:
2465         - $ref: '#/components/parameters/idOrUUID'
2466       responses:
2467         '204':
2468           description: successful operation
2469     delete:
2470       summary: Unblock a video by its id
2471       operationId: delVideoBlock
2472       security:
2473         - OAuth2:
2474           - admin
2475           - moderator
2476       tags:
2477         - Video Blocks
2478       parameters:
2479         - $ref: '#/components/parameters/idOrUUID'
2480       responses:
2481         '204':
2482           description: successful operation
2483         '404':
2484           description: block not found
2485
2486   /videos/blacklist:
2487     get:
2488       tags:
2489         - Video Blocks
2490       summary: List video blocks
2491       operationId: getVideoBlocks
2492       security:
2493         - OAuth2:
2494           - admin
2495           - moderator
2496       parameters:
2497         - name: type
2498           in: query
2499           description: >
2500             list only blocks that match this type:
2501
2502             - `1`: manual block
2503
2504             - `2`: automatic block that needs review
2505           schema:
2506             type: integer
2507             enum:
2508               - 1
2509               - 2
2510         - name: search
2511           in: query
2512           description: plain search that will match with video titles, and more
2513           schema:
2514             type: string
2515         - $ref: '#/components/parameters/start'
2516         - $ref: '#/components/parameters/count'
2517         - $ref: '#/components/parameters/blacklistsSort'
2518       responses:
2519         '200':
2520           description: successful operation
2521           content:
2522             application/json:
2523               schema:
2524                 type: object
2525                 properties:
2526                   total:
2527                     type: integer
2528                     example: 1
2529                   data:
2530                     type: array
2531                     items:
2532                       $ref: '#/components/schemas/VideoBlacklist'
2533
2534   /videos/{id}/captions:
2535     get:
2536       summary: List captions of a video
2537       operationId: getVideoCaptions
2538       tags:
2539         - Video Captions
2540       parameters:
2541         - $ref: '#/components/parameters/idOrUUID'
2542       responses:
2543         '200':
2544           description: successful operation
2545           content:
2546             application/json:
2547               schema:
2548                 type: object
2549                 properties:
2550                   total:
2551                     type: integer
2552                     example: 1
2553                   data:
2554                     type: array
2555                     items:
2556                       $ref: '#/components/schemas/VideoCaption'
2557
2558   /videos/{id}/captions/{captionLanguage}:
2559     put:
2560       summary: Add or replace a video caption
2561       operationId: addVideoCaption
2562       security:
2563         - OAuth2:
2564           - user
2565       tags:
2566         - Video Captions
2567       parameters:
2568         - $ref: '#/components/parameters/idOrUUID'
2569         - $ref: '#/components/parameters/captionLanguage'
2570       requestBody:
2571         content:
2572           multipart/form-data:
2573             schema:
2574               type: object
2575               properties:
2576                 captionfile:
2577                   description: The file to upload.
2578                   type: string
2579                   format: binary
2580             encoding:
2581               captionfile:
2582                 contentType: text/vtt, application/x-subrip, text/plain
2583       responses:
2584         '204':
2585           description: successful operation
2586         '404':
2587           description: video or language not found
2588     delete:
2589       summary: Delete a video caption
2590       operationId: delVideoCaption
2591       security:
2592         - OAuth2:
2593           - user
2594       tags:
2595         - Video Captions
2596       parameters:
2597         - $ref: '#/components/parameters/idOrUUID'
2598         - $ref: '#/components/parameters/captionLanguage'
2599       responses:
2600         '204':
2601           description: successful operation
2602         '404':
2603           description: video or language or caption for that language not found
2604
2605   /video-channels:
2606     get:
2607       summary: List video channels
2608       operationId: getVideoChannels
2609       tags:
2610         - Video Channels
2611       parameters:
2612         - $ref: '#/components/parameters/start'
2613         - $ref: '#/components/parameters/count'
2614         - $ref: '#/components/parameters/sort'
2615       responses:
2616         '200':
2617           description: successful operation
2618           content:
2619             application/json:
2620               schema:
2621                 $ref: '#/components/schemas/VideoChannelList'
2622     post:
2623       summary: Create a video channel
2624       operationId: addVideoChannel
2625       security:
2626         - OAuth2: []
2627       tags:
2628         - Video Channels
2629       responses:
2630         '204':
2631           description: successful operation
2632           content:
2633             application/json:
2634               schema:
2635                 type: object
2636                 properties:
2637                   videoChannel:
2638                     type: object
2639                     properties:
2640                       id:
2641                         $ref: '#/components/schemas/VideoChannel/properties/id'
2642       requestBody:
2643         content:
2644           application/json:
2645             schema:
2646               $ref: '#/components/schemas/VideoChannelCreate'
2647
2648   '/video-channels/{channelHandle}':
2649     get:
2650       summary: Get a video channel
2651       operationId: getVideoChannel
2652       tags:
2653         - Video Channels
2654       parameters:
2655         - $ref: '#/components/parameters/channelHandle'
2656       responses:
2657         '200':
2658           description: successful operation
2659           content:
2660             application/json:
2661               schema:
2662                 $ref: '#/components/schemas/VideoChannel'
2663     put:
2664       summary: Update a video channel
2665       operationId: putVideoChannel
2666       security:
2667         - OAuth2: []
2668       tags:
2669         - Video Channels
2670       parameters:
2671         - $ref: '#/components/parameters/channelHandle'
2672       responses:
2673         '204':
2674           description: successful operation
2675       requestBody:
2676         content:
2677           application/json:
2678             schema:
2679               $ref: '#/components/schemas/VideoChannelUpdate'
2680     delete:
2681       summary: Delete a video channel
2682       operationId: delVideoChannel
2683       security:
2684         - OAuth2: []
2685       tags:
2686         - Video Channels
2687       parameters:
2688         - $ref: '#/components/parameters/channelHandle'
2689       responses:
2690         '204':
2691           description: successful operation
2692
2693   '/video-channels/{channelHandle}/videos':
2694     get:
2695       summary: List videos of a video channel
2696       operationId: getVideoChannelVideos
2697       tags:
2698         - Video
2699         - Video Channels
2700       parameters:
2701         - $ref: '#/components/parameters/channelHandle'
2702         - $ref: '#/components/parameters/categoryOneOf'
2703         - $ref: '#/components/parameters/isLive'
2704         - $ref: '#/components/parameters/tagsOneOf'
2705         - $ref: '#/components/parameters/tagsAllOf'
2706         - $ref: '#/components/parameters/licenceOneOf'
2707         - $ref: '#/components/parameters/languageOneOf'
2708         - $ref: '#/components/parameters/nsfw'
2709         - $ref: '#/components/parameters/filter'
2710         - $ref: '#/components/parameters/skipCount'
2711         - $ref: '#/components/parameters/start'
2712         - $ref: '#/components/parameters/count'
2713         - $ref: '#/components/parameters/videosSort'
2714       responses:
2715         '200':
2716           description: successful operation
2717           content:
2718             application/json:
2719               schema:
2720                 $ref: '#/components/schemas/VideoListResponse'
2721
2722   '/video-channels/{channelHandle}/avatar/pick':
2723     post:
2724       summary: Update channel avatar
2725       security:
2726         - OAuth2: []
2727       tags:
2728         - Video Channels
2729       parameters:
2730         - $ref: '#/components/parameters/channelHandle'
2731       responses:
2732         '200':
2733           description: successful operation
2734           content:
2735             application/json:
2736               schema:
2737                 type: object
2738                 properties:
2739                   avatar:
2740                     $ref: '#/components/schemas/ActorImage'
2741         '413':
2742           description: image file too large
2743           headers:
2744             X-File-Maximum-Size:
2745               schema:
2746                 type: string
2747                 format: Nginx size
2748               description: Maximum file size for the avatar
2749       requestBody:
2750         content:
2751           multipart/form-data:
2752             schema:
2753               type: object
2754               properties:
2755                 avatarfile:
2756                   description: The file to upload.
2757                   type: string
2758                   format: binary
2759             encoding:
2760               avatarfile:
2761                 contentType: image/png, image/jpeg
2762
2763   '/video-channels/{channelHandle}/avatar':
2764     delete:
2765       summary: Delete channel avatar
2766       security:
2767         - OAuth2: []
2768       tags:
2769         - Video Channels
2770       parameters:
2771         - $ref: '#/components/parameters/channelHandle'
2772       responses:
2773         '204':
2774           description: successful operation
2775
2776   '/video-channels/{channelHandle}/banner/pick':
2777     post:
2778       summary: Update channel banner
2779       security:
2780         - OAuth2: []
2781       tags:
2782         - Video Channels
2783       parameters:
2784         - $ref: '#/components/parameters/channelHandle'
2785       responses:
2786         '200':
2787           description: successful operation
2788           content:
2789             application/json:
2790               schema:
2791                 type: object
2792                 properties:
2793                   banner:
2794                     $ref: '#/components/schemas/ActorImage'
2795         '413':
2796           description: image file too large
2797           headers:
2798             X-File-Maximum-Size:
2799               schema:
2800                 type: string
2801                 format: Nginx size
2802               description: Maximum file size for the banner
2803       requestBody:
2804         content:
2805           multipart/form-data:
2806             schema:
2807               type: object
2808               properties:
2809                 bannerfile:
2810                   description: The file to upload.
2811                   type: string
2812                   format: binary
2813             encoding:
2814               bannerfile:
2815                 contentType: image/png, image/jpeg
2816
2817   '/video-channels/{channelHandle}/banner':
2818     delete:
2819       summary: Delete channel banner
2820       security:
2821         - OAuth2: []
2822       tags:
2823         - Video Channels
2824       parameters:
2825         - $ref: '#/components/parameters/channelHandle'
2826       responses:
2827         '204':
2828           description: successful operation
2829
2830   /video-playlists/privacies:
2831     get:
2832       summary: List available playlist privacy policies
2833       operationId: getPlaylistPrivacyPolicies
2834       tags:
2835         - Video Playlists
2836       responses:
2837         '200':
2838           description: successful operation
2839           content:
2840             application/json:
2841               schema:
2842                 type: array
2843                 items:
2844                   type: string
2845               examples:
2846                 nightly:
2847                   externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
2848
2849   /video-playlists:
2850     get:
2851       summary: List video playlists
2852       operationId: getPlaylists
2853       tags:
2854         - Video Playlists
2855       parameters:
2856         - $ref: '#/components/parameters/start'
2857         - $ref: '#/components/parameters/count'
2858         - $ref: '#/components/parameters/sort'
2859       responses:
2860         '200':
2861           description: successful operation
2862           content:
2863             application/json:
2864               schema:
2865                 type: object
2866                 properties:
2867                   total:
2868                     type: integer
2869                     example: 1
2870                   data:
2871                     type: array
2872                     items:
2873                       $ref: '#/components/schemas/VideoPlaylist'
2874     post:
2875       summary: Create a video playlist
2876       description: If the video playlist is set as public, `videoChannelId` is mandatory.
2877       operationId: createPlaylist
2878       security:
2879         - OAuth2: []
2880       tags:
2881         - Video Playlists
2882       responses:
2883         '200':
2884           description: successful operation
2885           content:
2886             application/json:
2887               schema:
2888                 type: object
2889                 properties:
2890                   videoPlaylist:
2891                     type: object
2892                     properties:
2893                       id:
2894                         $ref: '#/components/schemas/VideoPlaylist/properties/id'
2895                       uuid:
2896                         $ref: '#/components/schemas/VideoPlaylist/properties/uuid'
2897       requestBody:
2898         content:
2899           multipart/form-data:
2900             schema:
2901               type: object
2902               properties:
2903                 displayName:
2904                   description: Video playlist display name
2905                   type: string
2906                   minLength: 1
2907                   maxLength: 120
2908                 thumbnailfile:
2909                   description: Video playlist thumbnail file
2910                   type: string
2911                   format: binary
2912                 privacy:
2913                   $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2914                 description:
2915                   description: Video playlist description
2916                   type: string
2917                   minLength: 3
2918                   maxLength: 1000
2919                 videoChannelId:
2920                   allOf:
2921                     - $ref: '#/components/schemas/id'
2922                   description: Video channel in which the playlist will be published
2923               required:
2924                 - displayName
2925             encoding:
2926               thumbnailfile:
2927                 contentType: image/jpeg
2928
2929   /video-playlists/{playlistId}:
2930     get:
2931       summary: Get a video playlist
2932       tags:
2933         - Video Playlists
2934       parameters:
2935         - $ref: '#/components/parameters/playlistId'
2936       responses:
2937         '200':
2938           description: successful operation
2939           content:
2940             application/json:
2941               schema:
2942                 $ref: '#/components/schemas/VideoPlaylist'
2943     put:
2944       summary: Update a video playlist
2945       description: 'If the video playlist is set as public, the playlist must have a assigned channel.'
2946       security:
2947         - OAuth2: []
2948       tags:
2949         - Video Playlists
2950       responses:
2951         '204':
2952           description: successful operation
2953       parameters:
2954         - $ref: '#/components/parameters/playlistId'
2955       requestBody:
2956         content:
2957           multipart/form-data:
2958             schema:
2959               type: object
2960               properties:
2961                 displayName:
2962                   description: Video playlist display name
2963                   type: string
2964                   minLength: 1
2965                   maxLength: 120
2966                 thumbnailfile:
2967                   description: Video playlist thumbnail file
2968                   type: string
2969                   format: binary
2970                 privacy:
2971                   $ref: '#/components/schemas/VideoPlaylistPrivacySet'
2972                 description:
2973                   description: Video playlist description
2974                   type: string
2975                 videoChannelId:
2976                   allOf:
2977                     - $ref: '#/components/schemas/id'
2978                   description: Video channel in which the playlist will be published
2979             encoding:
2980               thumbnailfile:
2981                 contentType: image/jpeg
2982     delete:
2983       summary: Delete a video playlist
2984       security:
2985         - OAuth2: []
2986       tags:
2987         - Video Playlists
2988       parameters:
2989         - $ref: '#/components/parameters/playlistId'
2990       responses:
2991         '204':
2992           description: successful operation
2993
2994   /video-playlists/{playlistId}/videos:
2995     get:
2996       summary: 'List videos of a playlist'
2997       tags:
2998         - Videos
2999         - Video Playlists
3000       parameters:
3001         - $ref: '#/components/parameters/playlistId'
3002       responses:
3003         '200':
3004           description: successful operation
3005           content:
3006             application/json:
3007               schema:
3008                 $ref: '#/components/schemas/VideoListResponse'
3009     post:
3010       summary: Add a video in a playlist
3011       security:
3012         - OAuth2: []
3013       tags:
3014         - Videos
3015         - Video Playlists
3016       parameters:
3017         - $ref: '#/components/parameters/playlistId'
3018       responses:
3019         '200':
3020           description: successful operation
3021           content:
3022             application/json:
3023               schema:
3024                 type: object
3025                 properties:
3026                   videoPlaylistElement:
3027                     type: object
3028                     properties:
3029                       id:
3030                         type: integer
3031                         example: 2
3032       requestBody:
3033         content:
3034           application/json:
3035             schema:
3036               type: object
3037               properties:
3038                 videoId:
3039                   oneOf:
3040                     - $ref: '#/components/schemas/Video/properties/uuid'
3041                     - $ref: '#/components/schemas/Video/properties/id'
3042                   description: Video to add in the playlist
3043                 startTimestamp:
3044                   type: integer
3045                   format: seconds
3046                   description: Start the video at this specific timestamp
3047                 stopTimestamp:
3048                   type: integer
3049                   format: seconds
3050                   description: Stop the video at this specific timestamp
3051               required:
3052                 - videoId
3053
3054   /video-playlists/{playlistId}/videos/reorder:
3055     post:
3056       summary: 'Reorder a playlist'
3057       security:
3058         - OAuth2: []
3059       tags:
3060         - Video Playlists
3061       parameters:
3062         - $ref: '#/components/parameters/playlistId'
3063       responses:
3064         '204':
3065           description: successful operation
3066       requestBody:
3067         content:
3068           application/json:
3069             schema:
3070               type: object
3071               properties:
3072                 startPosition:
3073                   type: integer
3074                   description: 'Start position of the element to reorder'
3075                   minimum: 1
3076                 insertAfterPosition:
3077                   type: integer
3078                   description: 'New position for the block to reorder, to add the block before the first element'
3079                   minimum: 0
3080                 reorderLength:
3081                   type: integer
3082                   description: 'How many element from `startPosition` to reorder'
3083                   minimum: 1
3084               required:
3085                 - startPosition
3086                 - insertAfterPosition
3087
3088   /video-playlists/{playlistId}/videos/{playlistElementId}:
3089     put:
3090       summary: Update a playlist element
3091       security:
3092         - OAuth2: []
3093       tags:
3094         - Video Playlists
3095       parameters:
3096         - $ref: '#/components/parameters/playlistId'
3097         - $ref: '#/components/parameters/playlistElementId'
3098       responses:
3099         '204':
3100           description: successful operation
3101       requestBody:
3102         content:
3103           application/json:
3104             schema:
3105               type: object
3106               properties:
3107                 startTimestamp:
3108                   type: integer
3109                   format: seconds
3110                   description: Start the video at this specific timestamp
3111                 stopTimestamp:
3112                   type: integer
3113                   format: seconds
3114                   description: Stop the video at this specific timestamp
3115     delete:
3116       summary: Delete an element from a playlist
3117       security:
3118         - OAuth2: []
3119       tags:
3120         - Video Playlists
3121       parameters:
3122         - $ref: '#/components/parameters/playlistId'
3123         - $ref: '#/components/parameters/playlistElementId'
3124       responses:
3125         '204':
3126           description: successful operation
3127
3128   '/users/me/video-playlists/videos-exist':
3129     get:
3130       summary: Check video exists in my playlists
3131       security:
3132         - OAuth2: []
3133       tags:
3134         - Video Playlists
3135       parameters:
3136         - name: videoIds
3137           in: query
3138           required: true
3139           description: The video ids to check
3140           schema:
3141             type: array
3142             items:
3143               $ref: '#/components/schemas/Video/properties/id'
3144       responses:
3145         '200':
3146           description: successful operation
3147           content:
3148             application/json:
3149               schema:
3150                 type: object
3151                 properties:
3152                   videoId:
3153                     type: array
3154                     items:
3155                       type: object
3156                       properties:
3157                         playlistElementId:
3158                           type: integer
3159                         playlistId:
3160                           type: integer
3161                         startTimestamp:
3162                           type: integer
3163                           format: seconds
3164                         stopTimestamp:
3165                           type: integer
3166                           format: seconds
3167
3168   '/accounts/{name}/video-channels':
3169     get:
3170       summary: List video channels of an account
3171       tags:
3172         - Video Channels
3173         - Accounts
3174       parameters:
3175         - $ref: '#/components/parameters/name'
3176         - name: withStats
3177           in: query
3178           description: include view statistics for the last 30 days (only if authentified as the account user)
3179           schema:
3180             type: boolean
3181         - $ref: '#/components/parameters/start'
3182         - $ref: '#/components/parameters/count'
3183         - $ref: '#/components/parameters/sort'
3184       responses:
3185         '200':
3186           description: successful operation
3187           content:
3188             application/json:
3189               schema:
3190                 $ref: '#/components/schemas/VideoChannelList'
3191
3192   '/accounts/{name}/ratings':
3193     get:
3194       summary: List ratings of an account
3195       security:
3196         - OAuth2: []
3197       tags:
3198         - Accounts
3199       parameters:
3200         - $ref: '#/components/parameters/name'
3201         - $ref: '#/components/parameters/start'
3202         - $ref: '#/components/parameters/count'
3203         - $ref: '#/components/parameters/sort'
3204         - name: rating
3205           in: query
3206           required: false
3207           description: Optionally filter which ratings to retrieve
3208           schema:
3209             type: string
3210             enum:
3211               - like
3212               - dislike
3213       responses:
3214         '200':
3215           description: successful operation
3216           content:
3217             application/json:
3218               schema:
3219                 type: array
3220                 items:
3221                   $ref: '#/components/schemas/VideoRating'
3222
3223   '/videos/{id}/comment-threads':
3224     get:
3225       summary: List threads of a video
3226       tags:
3227         - Video Comments
3228       parameters:
3229         - $ref: '#/components/parameters/idOrUUID'
3230         - $ref: '#/components/parameters/start'
3231         - $ref: '#/components/parameters/count'
3232         - $ref: '#/components/parameters/commentsSort'
3233       responses:
3234         '200':
3235           description: successful operation
3236           content:
3237             application/json:
3238               schema:
3239                 $ref: '#/components/schemas/CommentThreadResponse'
3240     post:
3241       summary: Create a thread
3242       security:
3243         - OAuth2: []
3244       tags:
3245         - Video Comments
3246       parameters:
3247         - $ref: '#/components/parameters/idOrUUID'
3248       responses:
3249         '200':
3250           description: successful operation
3251           content:
3252             application/json:
3253               schema:
3254                 $ref: '#/components/schemas/CommentThreadPostResponse'
3255         '404':
3256           description: video does not exist
3257       requestBody:
3258         content:
3259           application/json:
3260             schema:
3261               type: object
3262               properties:
3263                 text:
3264                   allOf:
3265                     - $ref: '#/components/schemas/VideoComment/properties/text'
3266                   format: markdown
3267                   maxLength: 10000
3268               required:
3269                 - text
3270
3271   '/videos/{id}/comment-threads/{threadId}':
3272     get:
3273       summary: Get a thread
3274       tags:
3275         - Video Comments
3276       parameters:
3277         - $ref: '#/components/parameters/idOrUUID'
3278         - $ref: '#/components/parameters/threadId'
3279       responses:
3280         '200':
3281           description: successful operation
3282           content:
3283             application/json:
3284               schema:
3285                 $ref: '#/components/schemas/VideoCommentThreadTree'
3286
3287   '/videos/{id}/comments/{commentId}':
3288     post:
3289       summary: Reply to a thread of a video
3290       security:
3291         - OAuth2: []
3292       tags:
3293         - Video Comments
3294       parameters:
3295         - $ref: '#/components/parameters/idOrUUID'
3296         - $ref: '#/components/parameters/commentId'
3297       responses:
3298         '200':
3299           description: successful operation
3300           content:
3301             application/json:
3302               schema:
3303                 $ref: '#/components/schemas/CommentThreadPostResponse'
3304         '404':
3305           description: thread or video does not exist
3306       requestBody:
3307         content:
3308           application/json:
3309             schema:
3310               type: object
3311               properties:
3312                 text:
3313                   allOf:
3314                     - $ref: '#/components/schemas/VideoComment/properties/text'
3315                   format: markdown
3316                   maxLength: 10000
3317               required:
3318                 - text
3319     delete:
3320       summary: Delete a comment or a reply
3321       security:
3322         - OAuth2: []
3323       tags:
3324         - Video Comments
3325       parameters:
3326         - $ref: '#/components/parameters/idOrUUID'
3327         - $ref: '#/components/parameters/commentId'
3328       responses:
3329         '204':
3330           description: successful operation
3331         '403':
3332           description: cannot remove comment of another user
3333         '404':
3334           description: comment or video does not exist
3335         '409':
3336           description: comment is already deleted
3337
3338   '/videos/{id}/rate':
3339     put:
3340       summary: Like/dislike a video
3341       security:
3342         - OAuth2: []
3343       tags:
3344         - Video Rates
3345       parameters:
3346         - $ref: '#/components/parameters/idOrUUID'
3347       requestBody:
3348         content:
3349           application/json:
3350             schema:
3351               type: object
3352               properties:
3353                 rating:
3354                   type: string
3355                   enum:
3356                     - like
3357                     - dislike
3358               required:
3359                 - rating
3360       responses:
3361         '204':
3362           description: successful operation
3363         '404':
3364           description: video does not exist
3365
3366   /search/videos:
3367     get:
3368       tags:
3369         - Search
3370       summary: Search videos
3371       parameters:
3372         - name: search
3373           in: query
3374           required: true
3375           allowEmptyValue: false
3376           description: >
3377             String to search. If the user can make a remote URI search, and the string is an URI then the
3378             PeerTube instance will fetch the remote object and add it to its database. Then,
3379             you can use the REST API to fetch the complete video information and interact with it.
3380           schema:
3381             type: string
3382         - $ref: '#/components/parameters/categoryOneOf'
3383         - $ref: '#/components/parameters/isLive'
3384         - $ref: '#/components/parameters/tagsOneOf'
3385         - $ref: '#/components/parameters/tagsAllOf'
3386         - $ref: '#/components/parameters/licenceOneOf'
3387         - $ref: '#/components/parameters/languageOneOf'
3388         - $ref: '#/components/parameters/nsfw'
3389         - $ref: '#/components/parameters/filter'
3390         - $ref: '#/components/parameters/skipCount'
3391         - $ref: '#/components/parameters/start'
3392         - $ref: '#/components/parameters/count'
3393         - $ref: '#/components/parameters/searchTarget'
3394         - $ref: '#/components/parameters/videosSearchSort'
3395         - name: startDate
3396           in: query
3397           description: Get videos that are published after this date
3398           schema:
3399             type: string
3400             format: date-time
3401         - name: endDate
3402           in: query
3403           description: Get videos that are published before this date
3404           schema:
3405             type: string
3406             format: date-time
3407         - name: originallyPublishedStartDate
3408           in: query
3409           description: Get videos that are originally published after this date
3410           schema:
3411             type: string
3412             format: date-time
3413         - name: originallyPublishedEndDate
3414           in: query
3415           description: Get videos that are originally published before this date
3416           schema:
3417             type: string
3418             format: date-time
3419         - name: durationMin
3420           in: query
3421           description: Get videos that have this minimum duration
3422           schema:
3423             type: integer
3424         - name: durationMax
3425           in: query
3426           description: Get videos that have this maximum duration
3427           schema:
3428             type: integer
3429       callbacks:
3430         'searchTarget === search-index':
3431           $ref: '#/components/callbacks/searchIndex'
3432       responses:
3433         '200':
3434           description: successful operation
3435           content:
3436             application/json:
3437               schema:
3438                 $ref: '#/components/schemas/VideoListResponse'
3439         '500':
3440           description: search index unavailable
3441
3442   /search/video-channels:
3443     get:
3444       tags:
3445         - Search
3446       summary: Search channels
3447       parameters:
3448         - name: search
3449           in: query
3450           required: true
3451           description: >
3452             String to search. If the user can make a remote URI search, and the string is an URI then the
3453             PeerTube instance will fetch the remote object and add it to its database. Then,
3454             you can use the REST API to fetch the complete channel information and interact with it.
3455           schema:
3456             type: string
3457         - $ref: '#/components/parameters/start'
3458         - $ref: '#/components/parameters/count'
3459         - $ref: '#/components/parameters/searchTarget'
3460         - $ref: '#/components/parameters/sort'
3461       callbacks:
3462         'searchTarget === search-index':
3463           $ref: '#/components/callbacks/searchIndex'
3464       responses:
3465         '200':
3466           description: successful operation
3467           content:
3468             application/json:
3469               schema:
3470                 $ref: '#/components/schemas/VideoChannelList'
3471         '500':
3472           description: search index unavailable
3473
3474   /server/blocklist/accounts:
3475     get:
3476       tags:
3477         - Account Blocks
3478       summary: List account blocks
3479       security:
3480         - OAuth2:
3481           - admin
3482       parameters:
3483         - $ref: '#/components/parameters/start'
3484         - $ref: '#/components/parameters/count'
3485         - $ref: '#/components/parameters/sort'
3486       responses:
3487         '200':
3488           description: successful operation
3489     post:
3490       tags:
3491         - Account Blocks
3492       summary: Block an account
3493       security:
3494         - OAuth2:
3495           - admin
3496       requestBody:
3497         content:
3498           application/json:
3499             schema:
3500               type: object
3501               properties:
3502                 accountName:
3503                   type: string
3504                   example: chocobozzz@example.org
3505                   description: account to block, in the form `username@domain`
3506               required:
3507                 - accountName
3508       responses:
3509         '200':
3510           description: successful operation
3511         '409':
3512           description: self-blocking forbidden
3513
3514   '/server/blocklist/accounts/{accountName}':
3515     delete:
3516       tags:
3517         - Account Blocks
3518       summary: Unblock an account by its handle
3519       security:
3520         - OAuth2:
3521           - admin
3522       parameters:
3523         - name: accountName
3524           in: path
3525           required: true
3526           description: account to unblock, in the form `username@domain`
3527           schema:
3528             type: string
3529       responses:
3530         '201':
3531           description: successful operation
3532         '404':
3533           description: account or account block does not exist
3534
3535   /server/blocklist/servers:
3536     get:
3537       tags:
3538         - Server Blocks
3539       summary: List server blocks
3540       security:
3541         - OAuth2:
3542           - admin
3543       parameters:
3544         - $ref: '#/components/parameters/start'
3545         - $ref: '#/components/parameters/count'
3546         - $ref: '#/components/parameters/sort'
3547       responses:
3548         '200':
3549           description: successful operation
3550     post:
3551       tags:
3552         - Server Blocks
3553       summary: Block a server
3554       security:
3555         - OAuth2:
3556           - admin
3557       requestBody:
3558         content:
3559           application/json:
3560             schema:
3561               type: object
3562               properties:
3563                 host:
3564                   type: string
3565                   format: hostname
3566                   description: server domain to block
3567               required:
3568                 - host
3569       responses:
3570         '204':
3571           description: successful operation
3572         '409':
3573           description: self-blocking forbidden
3574
3575   '/server/blocklist/servers/{host}':
3576     delete:
3577       tags:
3578         - Server Blocks
3579       summary: Unblock a server by its domain
3580       security:
3581         - OAuth2:
3582           - admin
3583       parameters:
3584         - name: host
3585           in: path
3586           required: true
3587           description: server domain to unblock
3588           schema:
3589             type: string
3590             format: hostname
3591       responses:
3592         '204':
3593           description: successful operation
3594         '404':
3595           description: account block does not exist
3596
3597   /server/redundancy/{host}:
3598     put:
3599       tags:
3600         - Instance Redundancy
3601       summary: Update a server redundancy policy
3602       security:
3603         - OAuth2:
3604           - admin
3605       parameters:
3606         - name: host
3607           in: path
3608           required: true
3609           description: server domain to mirror
3610           schema:
3611             type: string
3612             format: hostname
3613       requestBody:
3614         content:
3615           application/json:
3616             schema:
3617               type: object
3618               properties:
3619                 redundancyAllowed:
3620                   type: boolean
3621                   description: allow mirroring of the host's local videos
3622               required:
3623                 - redundancyAllowed
3624       responses:
3625         '204':
3626           description: successful operation
3627         '404':
3628           description: server is not already known
3629
3630   /server/redundancy/videos:
3631     get:
3632       tags:
3633         - Video Mirroring
3634       summary: List videos being mirrored
3635       security:
3636         - OAuth2:
3637           - admin
3638       parameters:
3639         - name: target
3640           in: query
3641           required: true
3642           description: direction of the mirror
3643           schema:
3644             type: string
3645             enum:
3646               - my-videos
3647               - remote-videos
3648         - $ref: '#/components/parameters/start'
3649         - $ref: '#/components/parameters/count'
3650         - $ref: '#/components/parameters/videoRedundanciesSort'
3651       responses:
3652         '200':
3653           description: successful operation
3654           content:
3655             application/json:
3656               schema:
3657                 type: array
3658                 items:
3659                   $ref: '#/components/schemas/VideoRedundancy'
3660     post:
3661       tags:
3662         - Video Mirroring
3663       summary: Mirror a video
3664       security:
3665         - OAuth2:
3666           - admin
3667       requestBody:
3668         content:
3669           application/json:
3670             schema:
3671               type: object
3672               properties:
3673                 videoId:
3674                   $ref: '#/components/schemas/Video/properties/id'
3675               required:
3676                 - videoId
3677       responses:
3678         '204':
3679           description: successful operation
3680         '400':
3681           description: cannot mirror a local video
3682         '404':
3683           description: video does not exist
3684         '409':
3685           description: video is already mirrored
3686
3687   /server/redundancy/videos/{redundancyId}:
3688     delete:
3689       tags:
3690         - Video Mirroring
3691       summary: Delete a mirror done on a video
3692       security:
3693         - OAuth2:
3694           - admin
3695       parameters:
3696         - name: redundancyId
3697           in: path
3698           required: true
3699           description: id of an existing redundancy on a video
3700           schema:
3701             type: string
3702       responses:
3703         '204':
3704           description: successful operation
3705         '404':
3706           description: video redundancy not found
3707
3708   '/feeds/video-comments.{format}':
3709     get:
3710       tags:
3711         - Feeds
3712       summary: List comments on videos
3713       parameters:
3714         - name: format
3715           in: path
3716           required: true
3717           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3718           schema:
3719             type: string
3720             enum:
3721               - xml
3722               - rss
3723               - rss2
3724               - atom
3725               - atom1
3726               - json
3727               - json1
3728         - name: videoId
3729           in: query
3730           description: 'limit listing to a specific video'
3731           schema:
3732             type: string
3733         - name: accountId
3734           in: query
3735           description: 'limit listing to a specific account'
3736           schema:
3737             type: string
3738         - name: accountName
3739           in: query
3740           description: 'limit listing to a specific account'
3741           schema:
3742             type: string
3743         - name: videoChannelId
3744           in: query
3745           description: 'limit listing to a specific video channel'
3746           schema:
3747             type: string
3748         - name: videoChannelName
3749           in: query
3750           description: 'limit listing to a specific video channel'
3751           schema:
3752             type: string
3753       responses:
3754         '204':
3755           description: successful operation
3756           headers:
3757             Cache-Control:
3758               schema:
3759                 type: string
3760                 default: 'max-age=900' # 15 min cache
3761           content:
3762             application/xml:
3763               schema:
3764                 $ref: '#/components/schemas/VideoCommentsForXML'
3765               examples:
3766                 nightly:
3767                   externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
3768             application/rss+xml:
3769               schema:
3770                 $ref: '#/components/schemas/VideoCommentsForXML'
3771               examples:
3772                 nightly:
3773                   externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
3774             text/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/atom+xml:
3781               schema:
3782                 $ref: '#/components/schemas/VideoCommentsForXML'
3783               examples:
3784                 nightly:
3785                   externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
3786             application/json:
3787               schema:
3788                 type: object
3789               examples:
3790                 nightly:
3791                   externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
3792         '400':
3793           x-summary: field inconsistencies
3794           description: >
3795             Arises when:
3796               - videoId filter is mixed with a channel filter
3797         '404':
3798           description: video, video channel or account not found
3799         '406':
3800           description: accept header unsupported
3801
3802   '/feeds/videos.{format}':
3803     get:
3804       tags:
3805         - Feeds
3806       summary: List videos
3807       parameters:
3808         - name: format
3809           in: path
3810           required: true
3811           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3812           schema:
3813             type: string
3814             enum:
3815               - xml
3816               - rss
3817               - rss2
3818               - atom
3819               - atom1
3820               - json
3821               - json1
3822         - name: accountId
3823           in: query
3824           description: 'limit listing to a specific account'
3825           schema:
3826             type: string
3827         - name: accountName
3828           in: query
3829           description: 'limit listing to a specific account'
3830           schema:
3831             type: string
3832         - name: videoChannelId
3833           in: query
3834           description: 'limit listing to a specific video channel'
3835           schema:
3836             type: string
3837         - name: videoChannelName
3838           in: query
3839           description: 'limit listing to a specific video channel'
3840           schema:
3841             type: string
3842         - $ref: '#/components/parameters/sort'
3843         - $ref: '#/components/parameters/nsfw'
3844         - $ref: '#/components/parameters/filter'
3845       responses:
3846         '204':
3847           description: successful operation
3848           headers:
3849             Cache-Control:
3850               schema:
3851                 type: string
3852                 default: 'max-age=900' # 15 min cache
3853           content:
3854             application/xml:
3855               schema:
3856                 $ref: '#/components/schemas/VideosForXML'
3857               examples:
3858                 nightly:
3859                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3860             application/rss+xml:
3861               schema:
3862                 $ref: '#/components/schemas/VideosForXML'
3863               examples:
3864                 nightly:
3865                   externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
3866             text/xml:
3867               schema:
3868                 $ref: '#/components/schemas/VideosForXML'
3869               examples:
3870                 nightly:
3871                   externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
3872             application/atom+xml:
3873               schema:
3874                 $ref: '#/components/schemas/VideosForXML'
3875               examples:
3876                 nightly:
3877                   externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
3878             application/json:
3879               schema:
3880                 type: object
3881               examples:
3882                 nightly:
3883                   externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
3884         '404':
3885           description: video channel or account not found
3886         '406':
3887           description: accept header unsupported
3888
3889   '/feeds/subscriptions.{format}':
3890     get:
3891       tags:
3892         - Feeds
3893         - Account
3894       summary: List videos of subscriptions tied to a token
3895       parameters:
3896         - name: format
3897           in: path
3898           required: true
3899           description: 'format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))'
3900           schema:
3901             type: string
3902             enum:
3903               - xml
3904               - rss
3905               - rss2
3906               - atom
3907               - atom1
3908               - json
3909               - json1
3910         - name: accountId
3911           in: query
3912           description: limit listing to a specific account
3913           schema:
3914             type: string
3915           required: true
3916         - name: token
3917           in: query
3918           description: private token allowing access
3919           schema:
3920             type: string
3921           required: true
3922         - $ref: '#/components/parameters/sort'
3923         - $ref: '#/components/parameters/nsfw'
3924         - $ref: '#/components/parameters/filter'
3925       responses:
3926         '204':
3927           description: successful operation
3928           headers:
3929             Cache-Control:
3930               schema:
3931                 type: string
3932                 default: 'max-age=900' # 15 min cache
3933           content:
3934             application/xml:
3935               schema:
3936                 $ref: '#/components/schemas/VideosForXML'
3937             application/rss+xml:
3938               schema:
3939                 $ref: '#/components/schemas/VideosForXML'
3940             text/xml:
3941               schema:
3942                 $ref: '#/components/schemas/VideosForXML'
3943             application/atom+xml:
3944               schema:
3945                 $ref: '#/components/schemas/VideosForXML'
3946             application/json:
3947               schema:
3948                 type: object
3949         '406':
3950           description: accept header unsupported
3951
3952   /plugins:
3953     get:
3954       tags:
3955         - Plugins
3956       summary: List plugins
3957       security:
3958         - OAuth2:
3959           - admin
3960       parameters:
3961         - name: pluginType
3962           in: query
3963           schema:
3964             type: integer
3965         - name: uninstalled
3966           in: query
3967           schema:
3968             type: boolean
3969         - $ref: '#/components/parameters/start'
3970         - $ref: '#/components/parameters/count'
3971         - $ref: '#/components/parameters/sort'
3972       responses:
3973         '200':
3974           description: successful operation
3975           content:
3976             application/json:
3977               schema:
3978                 $ref: '#/components/schemas/PluginResponse'
3979
3980   /plugins/available:
3981     get:
3982       tags:
3983         - Plugins
3984       summary: List available plugins
3985       security:
3986         - OAuth2:
3987           - admin
3988       parameters:
3989         - name: search
3990           in: query
3991           schema:
3992             type: string
3993         - name: pluginType
3994           in: query
3995           schema:
3996             type: integer
3997         - name: currentPeerTubeEngine
3998           in: query
3999           schema:
4000             type: string
4001         - $ref: '#/components/parameters/start'
4002         - $ref: '#/components/parameters/count'
4003         - $ref: '#/components/parameters/sort'
4004       responses:
4005         '200':
4006           description: successful operation
4007           content:
4008             application/json:
4009               schema:
4010                 $ref: '#/components/schemas/PluginResponse'
4011         '503':
4012           description: plugin index unavailable
4013
4014   /plugins/install:
4015     post:
4016       tags:
4017         - Plugins
4018       summary: Install a plugin
4019       security:
4020         - OAuth2:
4021           - admin
4022       requestBody:
4023         content:
4024           application/json:
4025             schema:
4026               oneOf:
4027                 - type: object
4028                   properties:
4029                     npmName:
4030                       type: string
4031                       example: peertube-plugin-auth-ldap
4032                   required:
4033                     - npmName
4034                   additionalProperties: false
4035                 - type: object
4036                   properties:
4037                     path:
4038                       type: string
4039                   required:
4040                     - path
4041                   additionalProperties: false
4042       responses:
4043         '204':
4044           description: successful operation
4045         '400':
4046           description: should have either `npmName` or `path` set
4047
4048   /plugins/update:
4049     post:
4050       tags:
4051         - Plugins
4052       summary: Update a plugin
4053       security:
4054         - OAuth2:
4055           - admin
4056       requestBody:
4057         content:
4058           application/json:
4059             schema:
4060               oneOf:
4061                 - type: object
4062                   properties:
4063                     npmName:
4064                       type: string
4065                       example: peertube-plugin-auth-ldap
4066                   required:
4067                     - npmName
4068                   additionalProperties: false
4069                 - type: object
4070                   properties:
4071                     path:
4072                       type: string
4073                   required:
4074                     - path
4075                   additionalProperties: false
4076       responses:
4077         '204':
4078           description: successful operation
4079         '400':
4080           description: should have either `npmName` or `path` set
4081         '404':
4082           description: existing plugin not found
4083
4084   /plugins/uninstall:
4085     post:
4086       tags:
4087         - Plugins
4088       summary: Uninstall a plugin
4089       security:
4090         - OAuth2:
4091           - admin
4092       requestBody:
4093         content:
4094           application/json:
4095             schema:
4096               type: object
4097               properties:
4098                 npmName:
4099                   type: string
4100                   description: name of the plugin/theme in its package.json
4101                   example: peertube-plugin-auth-ldap
4102               required:
4103                 - npmName
4104       responses:
4105         '204':
4106           description: successful operation
4107         '404':
4108           description: existing plugin not found
4109
4110   /plugins/{npmName}:
4111     get:
4112       tags:
4113         - Plugins
4114       summary: Get a plugin
4115       security:
4116         - OAuth2:
4117           - admin
4118       parameters:
4119         - $ref: '#/components/parameters/npmName'
4120       responses:
4121         '200':
4122           description: successful operation
4123           content:
4124             application/json:
4125               schema:
4126                 $ref: '#/components/schemas/Plugin'
4127         '404':
4128           description: plugin not found
4129
4130   /plugins/{npmName}/settings:
4131     put:
4132       tags:
4133         - Plugins
4134       summary: Set a plugin's settings
4135       security:
4136         - OAuth2:
4137           - admin
4138       parameters:
4139         - $ref: '#/components/parameters/npmName'
4140       requestBody:
4141         content:
4142           application/json:
4143             schema:
4144               type: object
4145               properties:
4146                 settings:
4147                   type: object
4148                   additionalProperties: true
4149       responses:
4150         '204':
4151           description: successful operation
4152         '404':
4153           description: plugin not found
4154
4155   /plugins/{npmName}/public-settings:
4156     get:
4157       tags:
4158         - Plugins
4159       summary: Get a plugin's public settings
4160       parameters:
4161         - $ref: '#/components/parameters/npmName'
4162       responses:
4163         '200':
4164           description: successful operation
4165           content:
4166             application/json:
4167               schema:
4168                 type: object
4169                 additionalProperties: true
4170         '404':
4171           description: plugin not found
4172
4173   /plugins/{npmName}/registered-settings:
4174     get:
4175       tags:
4176         - Plugins
4177       summary: Get a plugin's registered settings
4178       security:
4179         - OAuth2:
4180           - admin
4181       parameters:
4182         - $ref: '#/components/parameters/npmName'
4183       responses:
4184         '200':
4185           description: successful operation
4186           content:
4187             application/json:
4188               schema:
4189                 type: object
4190                 additionalProperties: true
4191         '404':
4192           description: plugin not found
4193
4194 servers:
4195   - url: 'https://peertube2.cpy.re/api/v1'
4196     description: Live Test Server (live data - latest nightly version)
4197   - url: 'https://peertube3.cpy.re/api/v1'
4198     description: Live Test Server (live data - latest RC version)
4199   - url: 'https://peertube.cpy.re/api/v1'
4200     description: Live Test Server (live data - stable version)
4201 components:
4202   parameters:
4203     start:
4204       name: start
4205       in: query
4206       required: false
4207       description: Offset used to paginate results
4208       schema:
4209         type: integer
4210         minimum: 0
4211     count:
4212       name: count
4213       in: query
4214       required: false
4215       description: "Number of items to return"
4216       schema:
4217         type: integer
4218         default: 15
4219         maximum: 100
4220         minimum: 1
4221     sort:
4222       name: sort
4223       in: query
4224       required: false
4225       description: Sort column
4226       schema:
4227         type: string
4228         example: -createdAt
4229     search:
4230       name: search
4231       in: query
4232       required: false
4233       description: Plain text search, applied to various parts of the model depending on endpoint
4234       schema:
4235         type: string
4236     searchTarget:
4237       name: searchTarget
4238       in: query
4239       required: false
4240       description: >
4241         If the administrator enabled search index support, you can override the default search target.
4242
4243
4244         **Warning**: If you choose to make an index search, PeerTube will get results from a third party service.
4245         It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
4246           * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
4247           then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
4248           After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
4249           * 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
4250           the data from the origin instance API
4251       schema:
4252         type: string
4253         enum:
4254           - 'local'
4255           - 'search-index'
4256     videosSort:
4257       name: sort
4258       in: query
4259       required: false
4260       description: Sort videos by criteria
4261       schema:
4262         type: string
4263         enum:
4264         - name
4265         - -duration
4266         - -createdAt
4267         - -publishedAt
4268         - -views
4269         - -likes
4270         - -trending
4271         - -hot
4272     videosSearchSort:
4273       name: sort
4274       in: query
4275       required: false
4276       description: Sort videos by criteria
4277       schema:
4278         type: string
4279         enum:
4280         - name
4281         - -duration
4282         - -createdAt
4283         - -publishedAt
4284         - -views
4285         - -likes
4286         - -match
4287     commentsSort:
4288       name: sort
4289       in: query
4290       required: false
4291       description: Sort comments by criteria
4292       schema:
4293         type: string
4294         enum:
4295         - -createdAt
4296         - -totalReplies
4297     blacklistsSort:
4298       name: sort
4299       in: query
4300       required: false
4301       description: Sort blacklists by criteria
4302       schema:
4303         type: string
4304         enum:
4305         - -id
4306         - name
4307         - -duration
4308         - -views
4309         - -likes
4310         - -dislikes
4311         - -uuid
4312         - -createdAt
4313     usersSearch:
4314       name: search
4315       in: query
4316       required: false
4317       description: Plain text search that will match with user usernames or emails
4318       schema:
4319         type: string
4320     usersBlocked:
4321       name: blocked
4322       in: query
4323       required: false
4324       description: Filter results down to (un)banned users
4325       schema:
4326         type: boolean
4327     usersSort:
4328       name: sort
4329       in: query
4330       required: false
4331       description: Sort users by criteria
4332       schema:
4333         type: string
4334         enum:
4335         - -id
4336         - -username
4337         - -createdAt
4338     abusesSort:
4339       name: sort
4340       in: query
4341       required: false
4342       description: Sort abuses by criteria
4343       schema:
4344         type: string
4345         enum:
4346         - -id
4347         - -createdAt
4348         - -state
4349     videoRedundanciesSort:
4350       name: sort
4351       in: query
4352       required: false
4353       description: Sort abuses by criteria
4354       schema:
4355         type: string
4356         enum:
4357         - name
4358     name:
4359       name: name
4360       in: path
4361       required: true
4362       description: The username or handle of the account
4363       schema:
4364         type: string
4365         example: chocobozzz | chocobozzz@example.org
4366     id:
4367       name: id
4368       in: path
4369       required: true
4370       description: The user id
4371       schema:
4372         $ref: '#/components/schemas/id'
4373     idOrUUID:
4374       name: id
4375       in: path
4376       required: true
4377       description: The object id or uuid
4378       schema:
4379         oneOf:
4380           - $ref: '#/components/schemas/id'
4381           - $ref: '#/components/schemas/UUIDv4'
4382     playlistId:
4383       name: playlistId
4384       in: path
4385       required: true
4386       description: Playlist id
4387       schema:
4388         $ref: '#/components/schemas/VideoPlaylist/properties/id'
4389     playlistElementId:
4390       name: playlistElementId
4391       in: path
4392       required: true
4393       description: Playlist element id
4394       schema:
4395         $ref: '#/components/schemas/id'
4396     abuseId:
4397       name: abuseId
4398       in: path
4399       required: true
4400       description: Abuse id
4401       schema:
4402         $ref: '#/components/schemas/Abuse/properties/id'
4403     abuseMessageId:
4404       name: abuseMessageId
4405       in: path
4406       required: true
4407       description: Abuse message id
4408       schema:
4409         $ref: '#/components/schemas/AbuseMessage/properties/id'
4410     captionLanguage:
4411       name: captionLanguage
4412       in: path
4413       required: true
4414       description: The caption language
4415       schema:
4416         $ref: '#/components/schemas/VideoLanguageSet'
4417     channelHandle:
4418       name: channelHandle
4419       in: path
4420       required: true
4421       description: The video channel handle
4422       schema:
4423         type: string
4424         example: my_username | my_username@example.com
4425     subscriptionHandle:
4426       name: subscriptionHandle
4427       in: path
4428       required: true
4429       description: The subscription handle
4430       schema:
4431         type: string
4432         example: my_username | my_username@example.com
4433     threadId:
4434       name: threadId
4435       in: path
4436       required: true
4437       description: The thread id (root comment id)
4438       schema:
4439         $ref: '#/components/schemas/VideoCommentThreadTree/properties/comment/properties/id'
4440     commentId:
4441       name: commentId
4442       in: path
4443       required: true
4444       description: The comment id
4445       schema:
4446         $ref: '#/components/schemas/VideoComment/properties/id'
4447     isLive:
4448       name: isLive
4449       in: query
4450       required: false
4451       description: whether or not the video is a live
4452       schema:
4453         type: boolean
4454     categoryOneOf:
4455       name: categoryOneOf
4456       in: query
4457       required: false
4458       description: category id of the video (see [/videos/categories](#operation/getCategories))
4459       schema:
4460         oneOf:
4461         - $ref: '#/components/schemas/VideoCategorySet'
4462         - type: array
4463           items:
4464             $ref: '#/components/schemas/VideoCategorySet'
4465       style: form
4466       explode: false
4467     tagsOneOf:
4468       name: tagsOneOf
4469       in: query
4470       required: false
4471       description: tag(s) of the video
4472       schema:
4473         oneOf:
4474         - type: string
4475         - type: array
4476           maxItems: 5
4477           items:
4478             type: string
4479       style: form
4480       explode: false
4481     tagsAllOf:
4482       name: tagsAllOf
4483       in: query
4484       required: false
4485       description: tag(s) of the video, where all should be present in the video
4486       schema:
4487         oneOf:
4488         - type: string
4489         - type: array
4490           items:
4491             type: string
4492       style: form
4493       explode: false
4494     languageOneOf:
4495       name: languageOneOf
4496       in: query
4497       required: false
4498       description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
4499       schema:
4500         oneOf:
4501         - $ref: '#/components/schemas/VideoLanguageSet'
4502         - type: array
4503           items:
4504             $ref: '#/components/schemas/VideoLanguageSet'
4505       style: form
4506       explode: false
4507     licenceOneOf:
4508       name: licenceOneOf
4509       in: query
4510       required: false
4511       description: licence id of the video (see [/videos/licences](#operation/getLicences))
4512       schema:
4513         oneOf:
4514         - $ref: '#/components/schemas/VideoLicenceSet'
4515         - type: array
4516           items:
4517             $ref: '#/components/schemas/VideoLicenceSet'
4518       style: form
4519       explode: false
4520     skipCount:
4521       name: skipCount
4522       in: query
4523       required: false
4524       description: if you don't need the `total` in the response
4525       schema:
4526         type: string
4527         enum:
4528           - 'true'
4529           - 'false'
4530         default: 'false'
4531     nsfw:
4532       name: nsfw
4533       in: query
4534       required: false
4535       description: whether to include nsfw videos, if any
4536       schema:
4537         type: string
4538         enum:
4539         - 'true'
4540         - 'false'
4541     filter:
4542       name: filter
4543       in: query
4544       required: false
4545       description: >
4546         Special filters which might require special rights:
4547          * `local` - only videos local to the instance
4548          * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
4549          * `all` - all videos, showing private and unlisted videos (requires Admin privileges)
4550       schema:
4551         type: string
4552         enum:
4553         - local
4554         - all-local
4555     subscriptionsUris:
4556       name: uris
4557       in: query
4558       required: true
4559       description: list of uris to check if each is part of the user subscriptions
4560       schema:
4561         type: array
4562         items:
4563           type: string
4564           format: uri
4565     npmName:
4566       name: npmName
4567       in: path
4568       required: true
4569       description: name of the plugin/theme on npmjs.com or in its package.json
4570       schema:
4571         type: string
4572         example: peertube-plugin-auth-ldap
4573     jobType:
4574       name: jobType
4575       in: query
4576       required: false
4577       description: job type
4578       schema:
4579         type: string
4580         enum:
4581           - activitypub-follow
4582           - activitypub-http-broadcast
4583           - activitypub-http-fetcher
4584           - activitypub-http-unicast
4585           - email
4586           - video-transcoding
4587           - video-file-import
4588           - video-import
4589           - videos-views
4590           - activitypub-refresher
4591           - video-redundancy
4592           - video-live-ending
4593     followState:
4594       name: state
4595       in: query
4596       schema:
4597         type: string
4598         enum:
4599           - pending
4600           - accepted
4601     actorType:
4602       name: actorType
4603       in: query
4604       schema:
4605         type: string
4606         enum:
4607           - Person
4608           - Application
4609           - Group
4610           - Service
4611           - Organization
4612   securitySchemes:
4613     OAuth2:
4614       description: |
4615         Authenticating via OAuth requires the following steps:
4616         - Have an activated account
4617         - [Generate] an access token for that account at `/api/v1/users/token`.
4618         - Make requests with the *Authorization: Bearer <token\>* header
4619         - Profit, depending on the role assigned to the account
4620
4621         Note that the __access token is valid for 1 day__ and is given
4622         along with a __refresh token valid for 2 weeks__.
4623
4624         [Generate]: https://docs.joinpeertube.org/api-rest-getting-started
4625       type: oauth2
4626       flows:
4627         password:
4628           tokenUrl: /api/v1/users/token
4629           scopes:
4630             admin: Admin scope
4631             moderator: Moderator scope
4632             user: User scope
4633   schemas:
4634     # Resuable core properties
4635     id:
4636       type: integer
4637       minimum: 1
4638       example: 42
4639     UUIDv4:
4640       type: string
4641       format: uuid
4642       example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
4643       pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
4644       minLength: 36
4645       maxLength: 36
4646     username:
4647       type: string
4648       description: immutable name of the user, used to find or mention its actor
4649       example: chocobozzz
4650       pattern: '/^[a-z0-9._]+$/'
4651       minLength: 1
4652       maxLength: 50
4653     usernameChannel:
4654       type: string
4655       description: immutable name of the channel, used to interact with its actor
4656       example: framasoft_videos
4657       pattern: '/^[a-zA-Z0-9\\-_.:]+$/'
4658       minLength: 1
4659       maxLength: 50
4660     password:
4661       type: string
4662       format: password
4663       minLength: 6
4664       maxLength: 255
4665
4666     VideoCategorySet:
4667       type: integer
4668       description: category id of the video (see [/videos/categories](#operation/getCategories))
4669       example: 15
4670     VideoConstantNumber-Category:
4671       properties:
4672         id:
4673           $ref: '#/components/schemas/VideoCategorySet'
4674         label:
4675           type: string
4676           example: Science & Technology
4677
4678     VideoLicenceSet:
4679       type: integer
4680       description: licence id of the video (see [/videos/licences](#operation/getLicences))
4681       example: 2
4682     VideoConstantNumber-Licence:
4683       properties:
4684         id:
4685           $ref: '#/components/schemas/VideoLicenceSet'
4686         label:
4687           type: string
4688           example: Attribution - Share Alike
4689
4690     VideoLanguageSet:
4691       type: string
4692       description: language id of the video (see [/videos/languages](#operation/getLanguages))
4693       example: en
4694     VideoConstantString-Language:
4695       properties:
4696         id:
4697           $ref: '#/components/schemas/VideoLanguageSet'
4698         label:
4699           type: string
4700           example: English
4701
4702     VideoPlaylistPrivacySet:
4703       type: integer
4704       enum:
4705         - 1
4706         - 2
4707         - 3
4708       description: Video playlist privacy policy (see [/video-playlists/privacies])
4709     VideoPlaylistPrivacyConstant:
4710       properties:
4711         id:
4712           $ref: '#/components/schemas/VideoPlaylistPrivacySet'
4713         label:
4714           type: string
4715
4716     VideoPlaylistTypeSet:
4717       type: integer
4718       enum:
4719         - 1
4720         - 2
4721       description: The video playlist type (Regular = `1`, Watch Later = `2`)
4722     VideoPlaylistTypeConstant:
4723       properties:
4724         id:
4725           $ref: '#/components/schemas/VideoPlaylistTypeSet'
4726         label:
4727           type: string
4728
4729     VideoPrivacySet:
4730       type: integer
4731       enum:
4732         - 1
4733         - 2
4734         - 3
4735         - 4
4736       description: privacy id of the video (see [/videos/privacies](#operation/getPrivacyPolicies))
4737     VideoPrivacyConstant:
4738       properties:
4739         id:
4740           $ref: '#/components/schemas/VideoPrivacySet'
4741         label:
4742           type: string
4743
4744     NSFWPolicy:
4745       type: string
4746       enum:
4747         - display
4748         - blur
4749         - do_not_list
4750
4751     UserRole:
4752       type: integer
4753       enum:
4754         - 0
4755         - 1
4756         - 2
4757       description: 'The user role (Admin = `0`, Moderator = `1`, User = `2`)'
4758       example: 2
4759     UserAdminFlags:
4760       type: integer
4761       enum:
4762         - 0
4763         - 1
4764       description: 'Admin flags for the user (None = `0`, Bypass video blacklist = `1`)'
4765       example: 1
4766
4767     VideoStateConstant:
4768       properties:
4769         id:
4770           type: integer
4771           enum:
4772             - 1
4773             - 2
4774             - 3
4775           description: 'The video state (Published = `1`, to transcode = `2`, to import = `3`)'
4776         label:
4777           type: string
4778
4779     AbuseStateSet:
4780       type: integer
4781       enum:
4782         - 1
4783         - 2
4784         - 3
4785       description: 'The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)'
4786     AbuseStateConstant:
4787       properties:
4788         id:
4789           $ref: '#/components/schemas/AbuseStateSet'
4790         label:
4791           type: string
4792     AbusePredefinedReasons:
4793       type: array
4794       items:
4795         type: string
4796         enum:
4797         - violentOrAbusive
4798         - hatefulOrAbusive
4799         - spamOrMisleading
4800         - privacy
4801         - rights
4802         - serverRules
4803         - thumbnails
4804         - captions
4805       example: [spamOrMisleading]
4806
4807     VideoResolutionSet:
4808       type: integer
4809       description: |
4810         Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)
4811
4812         `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
4813       example: 240
4814     VideoResolutionConstant:
4815       description: resolutions and their labels for the video
4816       properties:
4817         id:
4818           $ref: '#/components/schemas/VideoResolutionSet'
4819         label:
4820           type: string
4821           example: 240p
4822     VideoScheduledUpdate:
4823       properties:
4824         privacy:
4825           $ref: '#/components/schemas/VideoPrivacySet'
4826         updateAt:
4827           type: string
4828           format: date
4829           description: When to update the video
4830       required:
4831         - updateAt
4832     AccountSummary:
4833       properties:
4834         id:
4835           type: integer
4836         name:
4837           type: string
4838         displayName:
4839           type: string
4840         url:
4841           type: string
4842           format: url
4843         host:
4844           type: string
4845           format: hostname
4846         avatar:
4847           nullable: true
4848           allOf:
4849             - $ref: '#/components/schemas/ActorImage'
4850     VideoChannelSummary:
4851       properties:
4852         id:
4853           $ref: '#/components/schemas/id'
4854         name:
4855           type: string
4856         displayName:
4857           type: string
4858         url:
4859           type: string
4860           format: url
4861         host:
4862           type: string
4863           format: hostname
4864         avatar:
4865           nullable: true
4866           allOf:
4867             - $ref: '#/components/schemas/ActorImage'
4868     PlaylistElement:
4869       properties:
4870         position:
4871           type: integer
4872         startTimestamp:
4873           type: integer
4874           format: seconds
4875         stopTimestamp:
4876           type: integer
4877           format: seconds
4878         video:
4879           nullable: true
4880           allOf:
4881             - $ref: '#/components/schemas/Video'
4882     VideoFile:
4883       readOnly: true
4884       properties:
4885         magnetUri:
4886           type: string
4887           format: uri
4888           description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
4889           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
4890           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
4891         resolution:
4892           $ref: '#/components/schemas/VideoResolutionConstant'
4893         size:
4894           type: integer
4895           description: Video file size in bytes
4896         torrentUrl:
4897           type: string
4898           description: Direct URL of the torrent file
4899           format: url
4900         torrentDownloadUrl:
4901           type: string
4902           description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
4903           format: url
4904         fileUrl:
4905           type: string
4906           description: Direct URL of the video
4907           format: url
4908         fileDownloadUrl:
4909           type: string
4910           description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
4911           format: url
4912         fps:
4913           type: number
4914           description: Frames per second of the video file
4915         metadataUrl:
4916           type: string
4917           format: url
4918           description: URL dereferencing the output of ffprobe on the file
4919     VideoStreamingPlaylists:
4920       allOf:
4921         - type: object
4922           properties:
4923             id:
4924               $ref: '#/components/schemas/id'
4925             type:
4926               type: integer
4927               enum:
4928                 - 1
4929               description: |
4930                 Playlist type:
4931                 - `1`: HLS
4932         - $ref: '#/components/schemas/VideoStreamingPlaylists-HLS'
4933     VideoStreamingPlaylists-HLS:
4934       properties:
4935         playlistUrl:
4936           type: string
4937           format: url
4938         segmentsSha256Url:
4939           type: string
4940           format: url
4941         files:
4942           type: array
4943           description: |
4944             Video files associated to this playlist.
4945
4946             The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
4947           items:
4948             $ref: '#/components/schemas/VideoFile'
4949         redundancies:
4950           type: array
4951           items:
4952             type: object
4953             properties:
4954               baseUrl:
4955                 type: string
4956                 format: url
4957     VideoInfo:
4958       properties:
4959         id:
4960           $ref: '#/components/schemas/Video/properties/id'
4961         uuid:
4962           $ref: '#/components/schemas/Video/properties/uuid'
4963         name:
4964           $ref: '#/components/schemas/Video/properties/name'
4965     Video:
4966       properties:
4967         id:
4968           description: object id for the video
4969           allOf:
4970             - $ref: '#/components/schemas/id'
4971         uuid:
4972           description: universal identifier for the video, that can be used across instances
4973           allOf:
4974             - $ref: '#/components/schemas/UUIDv4'
4975         isLive:
4976           type: boolean
4977         createdAt:
4978           type: string
4979           format: date-time
4980           example: 2017-10-01T10:52:46.396Z
4981           description: time at which the video object was first drafted
4982         publishedAt:
4983           type: string
4984           format: date-time
4985           example: 2018-10-01T10:52:46.396Z
4986           description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
4987         updatedAt:
4988           type: string
4989           format: date-time
4990           example: 2021-05-04T08:01:01.502Z
4991           description: last time the video's metadata was modified
4992         originallyPublishedAt:
4993           type: string
4994           format: date-time
4995           example: 2010-10-01T10:52:46.396Z
4996           description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
4997         category:
4998           allOf:
4999             - $ref: '#/components/schemas/VideoConstantNumber-Category'
5000           description: category in which the video is classified
5001         licence:
5002           allOf:
5003             - $ref: '#/components/schemas/VideoConstantNumber-Licence'
5004           description: licence under which the video is distributed
5005         language:
5006           allOf:
5007             - $ref: '#/components/schemas/VideoConstantString-Language'
5008           description: main language used in the video
5009         privacy:
5010           allOf:
5011             - $ref: '#/components/schemas/VideoPrivacyConstant'
5012           description: privacy policy used to distribute the video
5013         description:
5014           type: string
5015           example: |
5016             **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
5017             **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
5018           minLength: 3
5019           maxLength: 250
5020           description: |
5021             truncated description of the video, written in Markdown.
5022             Resolve `descriptionPath` to get the full description of maximum `10000` characters.
5023         duration:
5024           type: integer
5025           example: 1419
5026           format: seconds
5027           description: duration of the video in seconds
5028         isLocal:
5029           type: boolean
5030         name:
5031           type: string
5032           description: title of the video
5033           example: What is PeerTube?
5034           minLength: 3
5035           maxLength: 120
5036         thumbnailPath:
5037           type: string
5038           example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5039         previewPath:
5040           type: string
5041           example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
5042         embedPath:
5043           type: string
5044           example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
5045         views:
5046           type: integer
5047           example: 1337
5048         likes:
5049           type: integer
5050           example: 42
5051         dislikes:
5052           type: integer
5053           example: 7
5054         nsfw:
5055           type: boolean
5056         waitTranscoding:
5057           type: boolean
5058           nullable: true
5059         state:
5060           allOf:
5061             - $ref: '#/components/schemas/VideoStateConstant'
5062           description: represents the internal state of the video processing within the PeerTube instance
5063         scheduledUpdate:
5064           nullable: true
5065           allOf:
5066             - $ref: '#/components/schemas/VideoScheduledUpdate'
5067         blacklisted:
5068           nullable: true
5069           type: boolean
5070         blacklistedReason:
5071           nullable: true
5072           type: string
5073         account:
5074           $ref: '#/components/schemas/AccountSummary'
5075         channel:
5076           $ref: '#/components/schemas/VideoChannelSummary'
5077         userHistory:
5078           nullable: true
5079           type: object
5080           properties:
5081             currentTime:
5082               type: integer
5083     VideoDetails:
5084       allOf:
5085         - $ref: '#/components/schemas/Video'
5086         - type: object
5087           properties:
5088             descriptionPath:
5089               type: string
5090               example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
5091               description: path at which to get the full description of maximum `10000` characters
5092             support:
5093               type: string
5094               description: A text tell the audience how to support the video creator
5095               example: Please support our work on https://soutenir.framasoft.org/en/ <3
5096               minLength: 3
5097               maxLength: 1000
5098             channel:
5099               $ref: '#/components/schemas/VideoChannel'
5100             account:
5101               $ref: '#/components/schemas/Account'
5102             tags:
5103               example: [flowers, gardening]
5104               type: array
5105               minItems: 1
5106               maxItems: 5
5107               items:
5108                 type: string
5109                 minLength: 2
5110                 maxLength: 30
5111             commentsEnabled:
5112               type: boolean
5113             downloadEnabled:
5114               type: boolean
5115             trackerUrls:
5116               type: array
5117               items:
5118                 type: string
5119                 format: url
5120               example:
5121                 - https://peertube2.cpy.re/tracker/announce
5122                 - wss://peertube2.cpy.re/tracker/socket
5123             files:
5124               type: array
5125               items:
5126                 $ref: '#/components/schemas/VideoFile'
5127               description: |
5128                 WebTorrent/raw video files. If WebTorrent is disabled on the server:
5129
5130                 - field will be empty
5131                 - video files will be found in `streamingPlaylists[].files` field
5132             streamingPlaylists:
5133               type: array
5134               items:
5135                 $ref: '#/components/schemas/VideoStreamingPlaylists'
5136               description: |
5137                 HLS playlists/manifest files. If HLS is disabled on the server:
5138
5139                 - field will be empty
5140                 - video files will be found in `files` field
5141     FileRedundancyInformation:
5142       properties:
5143         id:
5144           $ref: '#/components/schemas/id'
5145         fileUrl:
5146           type: string
5147           format: url
5148         strategy:
5149           type: string
5150           enum:
5151             - manual
5152             - most-views
5153             - trending
5154             - recently-added
5155         size:
5156           type: integer
5157         createdAt:
5158           type: string
5159           format: date-time
5160         updatedAt:
5161           type: string
5162           format: date-time
5163         expiresOn:
5164           type: string
5165           format: date-time
5166     VideoRedundancy:
5167       properties:
5168         id:
5169           $ref: '#/components/schemas/id'
5170         name:
5171           type: string
5172         url:
5173           type: string
5174           format: url
5175         uuid:
5176           $ref: '#/components/schemas/UUIDv4'
5177         redundancies:
5178           type: object
5179           properties:
5180             files:
5181               type: array
5182               items:
5183                 $ref: '#/components/schemas/FileRedundancyInformation'
5184             streamingPlaylists:
5185               type: array
5186               items:
5187                 $ref: '#/components/schemas/FileRedundancyInformation'
5188     VideoImportStateConstant:
5189       properties:
5190         id:
5191           type: integer
5192           enum:
5193             - 1
5194             - 2
5195             - 3
5196           description: 'The video import state (Pending = `1`, Success = `2`, Failed = `3`)'
5197         label:
5198           type: string
5199           example: Pending
5200     VideoCreateImport:
5201       allOf:
5202         - type: object
5203           additionalProperties: false
5204           oneOf:
5205             - properties:
5206                 targetUrl:
5207                   $ref: '#/components/schemas/VideoImport/properties/targetUrl'
5208               required: [targetUrl]
5209             - properties:
5210                 magnetUri:
5211                   $ref: '#/components/schemas/VideoImport/properties/magnetUri'
5212               required: [magnetUri]
5213             - properties:
5214                 torrentfile:
5215                   $ref: '#/components/schemas/VideoImport/properties/torrentfile'
5216               required: [torrentfile]
5217         - $ref: '#/components/schemas/VideoUploadRequestCommon'
5218       required:
5219         - channelId
5220         - name
5221     VideoImport:
5222       properties:
5223         id:
5224           readOnly: true
5225           allOf:
5226             - $ref: '#/components/schemas/id'
5227         targetUrl:
5228           type: string
5229           format: url
5230           description: remote URL where to find the import's source video
5231           example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
5232         magnetUri:
5233           type: string
5234           format: uri
5235           description: magnet URI allowing to resolve the import's source video
5236           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
5237           pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
5238         torrentfile:
5239           writeOnly: true
5240           type: string
5241           format: binary
5242           description: Torrent file containing only the video file
5243         torrentName:
5244           readOnly: true
5245           type: string
5246         state:
5247           readOnly: true
5248           allOf:
5249             - $ref: '#/components/schemas/VideoImportStateConstant'
5250         error:
5251           readOnly: true
5252           type: string
5253         createdAt:
5254           readOnly: true
5255           type: string
5256           format: date-time
5257         updatedAt:
5258           readOnly: true
5259           type: string
5260           format: date-time
5261         video:
5262           readOnly: true
5263           nullable: true
5264           allOf:
5265             - $ref: '#/components/schemas/Video'
5266     VideoImportsList:
5267       properties:
5268         total:
5269           type: integer
5270           example: 1
5271         data:
5272           type: array
5273           maxItems: 100
5274           items:
5275             $ref: '#/components/schemas/VideoImport'
5276     Abuse:
5277       properties:
5278         id:
5279           $ref: '#/components/schemas/id'
5280         reason:
5281           type: string
5282           example: The video is a spam
5283           minLength: 2
5284           maxLength: 3000
5285         predefinedReasons:
5286           $ref: '#/components/schemas/AbusePredefinedReasons'
5287         reporterAccount:
5288           $ref: '#/components/schemas/Account'
5289         state:
5290           $ref: '#/components/schemas/AbuseStateConstant'
5291         moderationComment:
5292           type: string
5293           example: Decided to ban the server since it spams us regularly
5294           minLength: 2
5295           maxLength: 3000
5296         video:
5297           $ref: '#/components/schemas/VideoInfo'
5298         createdAt:
5299           type: string
5300           format: date-time
5301     AbuseMessage:
5302       properties:
5303         id:
5304           $ref: '#/components/schemas/id'
5305         message:
5306           type: string
5307           minLength: 2
5308           maxLength: 3000
5309         byModerator:
5310           type: boolean
5311         createdAt:
5312           type: string
5313           format: date-time
5314         account:
5315           $ref: '#/components/schemas/AccountSummary'
5316     VideoBlacklist:
5317       properties:
5318         id:
5319           $ref: '#/components/schemas/id'
5320         videoId:
5321           $ref: '#/components/schemas/Video/properties/id'
5322         createdAt:
5323           type: string
5324           format: date-time
5325         updatedAt:
5326           type: string
5327           format: date-time
5328         name:
5329           type: string
5330           minLength: 3
5331           maxLength: 120
5332         uuid:
5333           $ref: '#/components/schemas/UUIDv4'
5334         description:
5335           type: string
5336           minLength: 3
5337           maxLength: 10000
5338         duration:
5339           type: integer
5340         views:
5341           type: integer
5342         likes:
5343           type: integer
5344         dislikes:
5345           type: integer
5346         nsfw:
5347           type: boolean
5348     VideoPlaylist:
5349       properties:
5350         id:
5351           $ref: '#/components/schemas/id'
5352         uuid:
5353           $ref: '#/components/schemas/UUIDv4'
5354         createdAt:
5355           type: string
5356           format: date-time
5357         updatedAt:
5358           type: string
5359           format: date-time
5360         description:
5361           type: string
5362           minLength: 3
5363           maxLength: 1000
5364         displayName:
5365           type: string
5366           minLength: 1
5367           maxLength: 120
5368         isLocal:
5369           type: boolean
5370         videoLength:
5371           type: integer
5372           minimum: 0
5373         thumbnailPath:
5374           type: string
5375         privacy:
5376           $ref: '#/components/schemas/VideoPlaylistPrivacyConstant'
5377         type:
5378           $ref: '#/components/schemas/VideoPlaylistTypeConstant'
5379         ownerAccount:
5380           $ref: '#/components/schemas/AccountSummary'
5381         videoChannel:
5382           $ref: '#/components/schemas/VideoChannelSummary'
5383     VideoComment:
5384       properties:
5385         id:
5386           $ref: '#/components/schemas/id'
5387         url:
5388           type: string
5389           format: url
5390         text:
5391           type: string
5392           format: html
5393           description: Text of the comment
5394           minLength: 1
5395           example: This video is wonderful!
5396         threadId:
5397           $ref: '#/components/schemas/id'
5398         inReplyToCommentId:
5399           nullable: true
5400           allOf:
5401             - $ref: '#/components/schemas/id'
5402         videoId:
5403           $ref: '#/components/schemas/Video/properties/id'
5404         createdAt:
5405           type: string
5406           format: date-time
5407         updatedAt:
5408           type: string
5409           format: date-time
5410         deletedAt:
5411           nullable: true
5412           type: string
5413           format: date-time
5414           default: null
5415         isDeleted:
5416           type: boolean
5417           default: false
5418         totalRepliesFromVideoAuthor:
5419           type: integer
5420           minimum: 0
5421         totalReplies:
5422           type: integer
5423           minimum: 0
5424         account:
5425           $ref: '#/components/schemas/Account'
5426     VideoCommentThreadTree:
5427       properties:
5428         comment:
5429           $ref: '#/components/schemas/VideoComment'
5430         children:
5431           type: array
5432           items:
5433             $ref: '#/components/schemas/VideoCommentThreadTree'
5434     VideoCaption:
5435       properties:
5436         language:
5437           $ref: '#/components/schemas/VideoConstantString-Language'
5438         captionPath:
5439           type: string
5440     ActorImage:
5441       properties:
5442         path:
5443           type: string
5444         createdAt:
5445           type: string
5446           format: date-time
5447         updatedAt:
5448           type: string
5449           format: date-time
5450     ActorInfo:
5451       properties:
5452         id:
5453           $ref: '#/components/schemas/id'
5454         name:
5455           type: string
5456         displayName:
5457           type: string
5458         host:
5459           type: string
5460           format: hostname
5461         avatar:
5462           nullable: true
5463           type: object
5464           properties:
5465             path:
5466               type: string
5467     Actor:
5468       properties:
5469         id:
5470           $ref: '#/components/schemas/id'
5471         url:
5472           type: string
5473           format: url
5474         name:
5475           description: immutable name of the actor, used to find or mention it
5476           allOf:
5477             - $ref: '#/components/schemas/username'
5478         host:
5479           type: string
5480           format: hostname
5481           description: server on which the actor is resident
5482         hostRedundancyAllowed:
5483           type: boolean
5484           description: whether this actor's host allows redundancy of its videos
5485         followingCount:
5486           type: integer
5487           minimum: 0
5488           description: number of actors subscribed to by this actor, as seen by this instance
5489         followersCount:
5490           type: integer
5491           minimum: 0
5492           description: number of followers of this actor, as seen by this instance
5493         createdAt:
5494           type: string
5495           format: date-time
5496         updatedAt:
5497           type: string
5498           format: date-time
5499         avatar:
5500           $ref: '#/components/schemas/ActorImage'
5501     Account:
5502       allOf:
5503         - $ref: '#/components/schemas/Actor'
5504         - properties:
5505             userId:
5506               description: object id for the user tied to this account
5507               allOf:
5508                 - $ref: '#/components/schemas/User/properties/id'
5509             displayName:
5510               type: string
5511               description: editable name of the account, displayed in its representations
5512               minLength: 3
5513               maxLength: 120
5514             description:
5515               type: string
5516               description: text or bio displayed on the account's profile
5517     UserWatchingVideo:
5518       properties:
5519         currentTime:
5520           type: integer
5521           format: seconds
5522           description: timestamp within the video, in seconds
5523           example: 5
5524     ServerConfig:
5525       properties:
5526         instance:
5527           type: object
5528           properties:
5529             name:
5530               type: string
5531             shortDescription:
5532               type: string
5533             defaultClientRoute:
5534               type: string
5535             isNSFW:
5536               type: boolean
5537             defaultNSFWPolicy:
5538               type: string
5539             customizations:
5540               type: object
5541               properties:
5542                 javascript:
5543                   type: string
5544                 css:
5545                   type: string
5546         search:
5547           type: object
5548           properties:
5549             remoteUri:
5550               type: object
5551               properties:
5552                 users:
5553                   type: boolean
5554                 anonymous:
5555                   type: boolean
5556         plugin:
5557           type: object
5558           properties:
5559             registered:
5560               type: array
5561               items:
5562                 type: string
5563         theme:
5564           type: object
5565           properties:
5566             registered:
5567               type: array
5568               items:
5569                 type: string
5570         email:
5571           type: object
5572           properties:
5573             enabled:
5574               type: boolean
5575         contactForm:
5576           type: object
5577           properties:
5578             enabled:
5579               type: boolean
5580         serverVersion:
5581           type: string
5582         serverCommit:
5583           type: string
5584         signup:
5585           type: object
5586           properties:
5587             allowed:
5588               type: boolean
5589             allowedForCurrentIP:
5590               type: boolean
5591             requiresEmailVerification:
5592               type: boolean
5593         transcoding:
5594           type: object
5595           properties:
5596             hls:
5597               type: object
5598               properties:
5599                 enabled:
5600                   type: boolean
5601             webtorrent:
5602               type: object
5603               properties:
5604                 enabled:
5605                   type: boolean
5606             enabledResolutions:
5607               type: array
5608               items:
5609                 $ref: '#/components/schemas/VideoResolutionSet'
5610         import:
5611           type: object
5612           properties:
5613             videos:
5614               type: object
5615               properties:
5616                 http:
5617                   type: object
5618                   properties:
5619                     enabled:
5620                       type: boolean
5621                 torrent:
5622                   type: object
5623                   properties:
5624                     enabled:
5625                       type: boolean
5626         autoBlacklist:
5627           type: object
5628           properties:
5629             videos:
5630               type: object
5631               properties:
5632                 ofUsers:
5633                   type: object
5634                   properties:
5635                     enabled:
5636                       type: boolean
5637         avatar:
5638           type: object
5639           properties:
5640             file:
5641               type: object
5642               properties:
5643                 size:
5644                   type: object
5645                   properties:
5646                     max:
5647                       type: integer
5648             extensions:
5649               type: array
5650               items:
5651                 type: string
5652         video:
5653           type: object
5654           properties:
5655             image:
5656               type: object
5657               properties:
5658                 extensions:
5659                   type: array
5660                   items:
5661                     type: string
5662                 size:
5663                   type: object
5664                   properties:
5665                     max:
5666                       type: integer
5667             file:
5668               type: object
5669               properties:
5670                 extensions:
5671                   type: array
5672                   items:
5673                     type: string
5674         videoCaption:
5675           type: object
5676           properties:
5677             file:
5678               type: object
5679               properties:
5680                 size:
5681                   type: object
5682                   properties:
5683                     max:
5684                       type: integer
5685                 extensions:
5686                   type: array
5687                   items:
5688                     type: string
5689         user:
5690           type: object
5691           properties:
5692             videoQuota:
5693               type: integer
5694               example: 16810141515
5695             videoQuotaDaily:
5696               type: integer
5697               example: 1681014151
5698         trending:
5699           type: object
5700           properties:
5701             videos:
5702               type: object
5703               properties:
5704                 intervalDays:
5705                   type: integer
5706         tracker:
5707           type: object
5708           properties:
5709             enabled:
5710               type: boolean
5711         followings:
5712           type: object
5713           properties:
5714             instance:
5715               type: object
5716               properties:
5717                 autoFollowIndex:
5718                   type: object
5719                   properties:
5720                     indexUrl:
5721                       type: string
5722                       format: url
5723     ServerConfigAbout:
5724       properties:
5725         instance:
5726           type: object
5727           properties:
5728             name:
5729               type: string
5730             shortDescription:
5731               type: string
5732             description:
5733               type: string
5734             terms:
5735               type: string
5736     ServerConfigCustom:
5737       properties:
5738         instance:
5739           type: object
5740           properties:
5741             name:
5742               type: string
5743             shortDescription:
5744               type: string
5745             description:
5746               type: string
5747             terms:
5748               type: string
5749             defaultClientRoute:
5750               type: string
5751             isNSFW:
5752               type: boolean
5753             defaultNSFWPolicy:
5754               type: string
5755             customizations:
5756               type: object
5757               properties:
5758                 javascript:
5759                   type: string
5760                 css:
5761                   type: string
5762         theme:
5763           type: object
5764           properties:
5765             default:
5766               type: string
5767         services:
5768           type: object
5769           properties:
5770             twitter:
5771               type: object
5772               properties:
5773                 username:
5774                   type: string
5775                 whitelisted:
5776                   type: boolean
5777         cache:
5778           type: object
5779           properties:
5780             previews:
5781               type: object
5782               properties:
5783                 size:
5784                   type: integer
5785             captions:
5786               type: object
5787               properties:
5788                 size:
5789                   type: integer
5790         signup:
5791           type: object
5792           properties:
5793             enabled:
5794               type: boolean
5795             limit:
5796               type: integer
5797             requiresEmailVerification:
5798               type: boolean
5799         admin:
5800           type: object
5801           properties:
5802             email:
5803               type: string
5804               format: email
5805         contactForm:
5806           type: object
5807           properties:
5808             enabled:
5809               type: boolean
5810         user:
5811           type: object
5812           description: Settings that apply to new users, if registration is enabled
5813           properties:
5814             videoQuota:
5815               type: integer
5816               example: 16810141515
5817             videoQuotaDaily:
5818               type: integer
5819               example: 1681014151
5820         transcoding:
5821           type: object
5822           description: Settings pertaining to transcoding jobs
5823           properties:
5824             enabled:
5825               type: boolean
5826             allowAdditionalExtensions:
5827               type: boolean
5828               description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
5829             allowAudioFiles:
5830               type: boolean
5831               description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
5832             threads:
5833               type: integer
5834               description: Amount of threads used by ffmpeg for 1 transcoding job
5835             concurrency:
5836               type: number
5837               description: Amount of transcoding jobs to execute in parallel
5838             profile:
5839               type: string
5840               enum:
5841                 - default
5842               description: |
5843                 New profiles can be added by plugins ; available in core PeerTube: 'default'.
5844             resolutions:
5845               type: object
5846               description: Resolutions to transcode _new videos_ to
5847               properties:
5848                 0p:
5849                   type: boolean
5850                 240p:
5851                   type: boolean
5852                 360p:
5853                   type: boolean
5854                 480p:
5855                   type: boolean
5856                 720p:
5857                   type: boolean
5858                 1080p:
5859                   type: boolean
5860                 1440p:
5861                   type: boolean
5862                 2160p:
5863                   type: boolean
5864             webtorrent:
5865               type: object
5866               description: WebTorrent-specific settings
5867               properties:
5868                 enabled:
5869                   type: boolean
5870             hls:
5871               type: object
5872               description: HLS-specific settings
5873               properties:
5874                 enabled:
5875                   type: boolean
5876         import:
5877           type: object
5878           properties:
5879             videos:
5880               type: object
5881               properties:
5882                 http:
5883                   type: object
5884                   properties:
5885                     enabled:
5886                       type: boolean
5887                 torrent:
5888                   type: object
5889                   properties:
5890                     enabled:
5891                       type: boolean
5892         autoBlacklist:
5893           type: object
5894           properties:
5895             videos:
5896               type: object
5897               properties:
5898                 ofUsers:
5899                   type: object
5900                   properties:
5901                     enabled:
5902                       type: boolean
5903         followers:
5904           type: object
5905           properties:
5906             instance:
5907               type: object
5908               properties:
5909                 enabled:
5910                   type: boolean
5911                 manualApproval:
5912                   type: boolean
5913     Follow:
5914       properties:
5915         id:
5916           $ref: '#/components/schemas/id'
5917         follower:
5918           $ref: '#/components/schemas/Actor'
5919         following:
5920           $ref: '#/components/schemas/Actor'
5921         score:
5922           type: number
5923           description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
5924         state:
5925           type: string
5926           enum:
5927             - pending
5928             - accepted
5929         createdAt:
5930           type: string
5931           format: date-time
5932         updatedAt:
5933           type: string
5934           format: date-time
5935
5936     PredefinedAbuseReasons:
5937       description: Reason categories that help triage reports
5938       type: array
5939       maxItems: 8
5940       items:
5941         type: string
5942         enum:
5943         - violentOrAbusive
5944         - hatefulOrAbusive
5945         - spamOrMisleading
5946         - privacy
5947         - rights
5948         - serverRules
5949         - thumbnails
5950         - captions
5951
5952     Job:
5953       properties:
5954         id:
5955           $ref: '#/components/schemas/id'
5956         state:
5957           type: string
5958           enum:
5959             - active
5960             - completed
5961             - failed
5962             - waiting
5963             - delayed
5964         type:
5965           type: string
5966           enum:
5967             - activitypub-http-unicast
5968             - activitypub-http-broadcast
5969             - activitypub-http-fetcher
5970             - activitypub-follow
5971             - video-file-import
5972             - video-transcoding
5973             - email
5974             - video-import
5975             - videos-views
5976             - activitypub-refresher
5977             - video-redundancy
5978         data:
5979           type: object
5980           additionalProperties: true
5981         error:
5982           type: object
5983           additionalProperties: true
5984         createdAt:
5985           type: string
5986           format: date-time
5987         finishedOn:
5988           type: string
5989           format: date-time
5990         processedOn:
5991           type: string
5992           format: date-time
5993     AddUserResponse:
5994       properties:
5995         user:
5996           type: object
5997           properties:
5998             id:
5999               $ref: '#/components/schemas/id'
6000             account:
6001               type: object
6002               properties:
6003                 id:
6004                   $ref: '#/components/schemas/id'
6005     VideoUploadRequestCommon:
6006       properties:
6007         name:
6008           description: Video name
6009           type: string
6010           example: What is PeerTube?
6011           minLength: 3
6012           maxLength: 120
6013         channelId:
6014           description: Channel id that will contain this video
6015           type: integer
6016           example: 3
6017           minimum: 1
6018         privacy:
6019           $ref: '#/components/schemas/VideoPrivacySet'
6020         category:
6021           $ref: '#/components/schemas/VideoCategorySet'
6022         licence:
6023           $ref: '#/components/schemas/VideoLicenceSet'
6024         language:
6025           $ref: '#/components/schemas/VideoLanguageSet'
6026         description:
6027           description: Video description
6028           type: string
6029           example: |
6030             **[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)**
6031         waitTranscoding:
6032           description: Whether or not we wait transcoding before publish the video
6033           type: boolean
6034         support:
6035           description: A text tell the audience how to support the video creator
6036           example: Please support our work on https://soutenir.framasoft.org/en/ <3
6037           type: string
6038         nsfw:
6039           description: Whether or not this video contains sensitive content
6040           type: boolean
6041         tags:
6042           description: Video tags (maximum 5 tags each between 2 and 30 characters)
6043           type: array
6044           minItems: 1
6045           maxItems: 5
6046           uniqueItems: true
6047           example:
6048             - framasoft
6049             - peertube
6050           items:
6051             type: string
6052             minLength: 2
6053             maxLength: 30
6054         commentsEnabled:
6055           description: Enable or disable comments for this video
6056           type: boolean
6057         downloadEnabled:
6058           description: Enable or disable downloading for this video
6059           type: boolean
6060         originallyPublishedAt:
6061           description: Date when the content was originally published
6062           type: string
6063           format: date-time
6064         scheduleUpdate:
6065           $ref: '#/components/schemas/VideoScheduledUpdate'
6066         thumbnailfile:
6067           description: Video thumbnail file
6068           type: string
6069           format: binary
6070         previewfile:
6071           description: Video preview file
6072           type: string
6073           format: binary
6074       required:
6075         - channelId
6076         - name
6077     VideoUploadRequestLegacy:
6078       allOf:
6079         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6080         - type: object
6081           required:
6082             - videofile
6083           properties:
6084             videofile:
6085               description: Video file
6086               type: string
6087               format: binary
6088     VideoUploadRequestResumable:
6089       allOf:
6090         - $ref: '#/components/schemas/VideoUploadRequestCommon'
6091         - type: object
6092           required:
6093             - filename
6094           properties:
6095             filename:
6096               description: Video filename including extension
6097               type: string
6098               format: filename
6099               example: what_is_peertube.mp4
6100             thumbnailfile:
6101               description: Video thumbnail file
6102               type: string
6103               format: binary
6104             previewfile:
6105               description: Video preview file
6106               type: string
6107               format: binary
6108     VideoUploadResponse:
6109       properties:
6110         video:
6111           type: object
6112           properties:
6113             id:
6114               $ref: '#/components/schemas/Video/properties/id'
6115             uuid:
6116               $ref: '#/components/schemas/Video/properties/uuid'
6117     CommentThreadResponse:
6118       properties:
6119         total:
6120           type: integer
6121           example: 1
6122         data:
6123           type: array
6124           maxItems: 100
6125           items:
6126             $ref: '#/components/schemas/VideoComment'
6127     CommentThreadPostResponse:
6128       properties:
6129         comment:
6130           $ref: '#/components/schemas/VideoComment'
6131     VideoListResponse:
6132       properties:
6133         total:
6134           type: integer
6135           example: 1
6136         data:
6137           type: array
6138           maxItems: 100
6139           items:
6140             $ref: '#/components/schemas/Video'
6141     User:
6142       properties:
6143         account:
6144           $ref: '#/components/schemas/Account'
6145         autoPlayNextVideo:
6146           type: boolean
6147           description: Automatically start playing the upcoming video after the currently playing video
6148         autoPlayNextVideoPlaylist:
6149           type: boolean
6150           description: Automatically start playing the video on the playlist after the currently playing video
6151         autoPlayVideo:
6152           type: boolean
6153           description: Automatically start playing the video on the watch page
6154         blocked:
6155           type: boolean
6156         blockedReason:
6157           type: string
6158         createdAt:
6159           type: string
6160         email:
6161           type: string
6162           format: email
6163           description: The user email
6164         emailVerified:
6165           type: boolean
6166           description: Has the user confirmed their email address?
6167         id:
6168           allOf:
6169             - $ref: '#/components/schemas/id'
6170           readOnly: true
6171         pluginAuth:
6172           type: string
6173           description: Auth plugin to use to authenticate the user
6174         lastLoginDate:
6175           type: string
6176           format: date-time
6177         noInstanceConfigWarningModal:
6178           type: boolean
6179         noWelcomeModal:
6180           type: boolean
6181         nsfwPolicy:
6182           $ref: '#/components/schemas/NSFWPolicy'
6183         role:
6184           $ref: '#/components/schemas/UserRole'
6185         roleLabel:
6186           type: string
6187           enum:
6188             - User
6189             - Moderator
6190             - Administrator
6191         theme:
6192           type: string
6193           description: Theme enabled by this user
6194         username:
6195           $ref: '#/components/schemas/username'
6196         videoChannels:
6197           type: array
6198           items:
6199             $ref: '#/components/schemas/VideoChannel'
6200         videoQuota:
6201           type: integer
6202           description: The user video quota in bytes
6203           example: -1
6204         videoQuotaDaily:
6205           type: integer
6206           description: The user daily video quota in bytes
6207           example: -1
6208         webtorrentEnabled:
6209           type: boolean
6210           description: Enable P2P in the player
6211     UserWithStats:
6212       allOf:
6213         - $ref: '#/components/schemas/User'
6214         - properties:
6215             # optionally present fields: they require WITH_STATS scope
6216             videosCount:
6217               type: integer
6218               description: Count of videos published
6219             abusesCount:
6220               type: integer
6221               description: Count of reports/abuses of which the user is a target
6222             abusesAcceptedCount:
6223               type: integer
6224               description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
6225             abusesCreatedCount:
6226               type: integer
6227               description: Count of reports/abuses created by the user
6228             videoCommentsCount:
6229               type: integer
6230               description: Count of comments published
6231     AddUser:
6232       properties:
6233         username:
6234           $ref: '#/components/schemas/username'
6235         password:
6236           $ref: '#/components/schemas/password'
6237         email:
6238           type: string
6239           format: email
6240           description: The user email
6241         videoQuota:
6242           type: integer
6243           description: The user video quota in bytes
6244           example: -1
6245         videoQuotaDaily:
6246           type: integer
6247           description: The user daily video quota in bytes
6248           example: -1
6249         channelName:
6250           $ref: '#/components/schemas/usernameChannel'
6251         role:
6252           $ref: '#/components/schemas/UserRole'
6253         adminFlags:
6254           $ref: '#/components/schemas/UserAdminFlags'
6255       required:
6256         - username
6257         - password
6258         - email
6259         - videoQuota
6260         - videoQuotaDaily
6261         - role
6262     UpdateUser:
6263       properties:
6264         email:
6265           description: The updated email of the user
6266           allOf:
6267             - $ref: '#/components/schemas/User/properties/email'
6268         emailVerified:
6269           type: boolean
6270           description: Set the email as verified
6271         videoQuota:
6272           type: integer
6273           description: The updated video quota of the user in bytes
6274         videoQuotaDaily:
6275           type: integer
6276           description: The updated daily video quota of the user in bytes
6277         pluginAuth:
6278           type: string
6279           nullable: true
6280           description: The auth plugin to use to authenticate the user
6281           example: 'peertube-plugin-auth-saml2'
6282         role:
6283           $ref: '#/components/schemas/UserRole'
6284         adminFlags:
6285           $ref: '#/components/schemas/UserAdminFlags'
6286     UpdateMe:
6287       # see shared/models/users/user-update-me.model.ts:
6288       properties:
6289         password:
6290           $ref: '#/components/schemas/password'
6291         currentPassword:
6292           $ref: '#/components/schemas/password'
6293         email:
6294           description: new email used for login and service communications
6295           allOf:
6296             - $ref: '#/components/schemas/User/properties/email'
6297         displayName:
6298           type: string
6299           description: new name of the user in its representations
6300           minLength: 3
6301           maxLength: 120
6302         displayNSFW:
6303           type: string
6304           description: new NSFW display policy
6305           enum:
6306             - 'true'
6307             - 'false'
6308             - both
6309         webTorrentEnabled:
6310           type: boolean
6311           description: whether to enable P2P in the player or not
6312         autoPlayVideo:
6313           type: boolean
6314           description: new preference regarding playing videos automatically
6315         autoPlayNextVideo:
6316           type: boolean
6317           description: new preference regarding playing following videos automatically
6318         autoPlayNextVideoPlaylist:
6319           type: boolean
6320           description: new preference regarding playing following playlist videos automatically
6321         videosHistoryEnabled:
6322           type: boolean
6323           description: whether to keep track of watched history or not
6324         videoLanguages:
6325           type: array
6326           items:
6327             type: string
6328           description: list of languages to filter videos down to
6329         theme:
6330           type: string
6331         noInstanceConfigWarningModal:
6332           type: boolean
6333         noWelcomeModal:
6334           type: boolean
6335     GetMeVideoRating:
6336       properties:
6337         id:
6338           $ref: '#/components/schemas/id'
6339         rating:
6340           type: string
6341           enum:
6342             - like
6343             - dislike
6344             - none
6345           description: Rating of the video
6346       required:
6347         - id
6348         - rating
6349     VideoRating:
6350       properties:
6351         video:
6352           $ref: '#/components/schemas/Video'
6353         rating:
6354           type: string
6355           enum:
6356             - like
6357             - dislike
6358             - none
6359           description: Rating of the video
6360       required:
6361         - video
6362         - rating
6363     RegisterUser:
6364       properties:
6365         username:
6366           description: immutable name of the user, used to find or mention its actor
6367           allOf:
6368             - $ref: '#/components/schemas/username'
6369         password:
6370           $ref: '#/components/schemas/password'
6371         email:
6372           type: string
6373           format: email
6374           description: email of the user, used for login or service communications
6375         displayName:
6376           type: string
6377           description: editable name of the user, displayed in its representations
6378           minLength: 1
6379           maxLength: 120
6380         channel:
6381           type: object
6382           description: channel base information used to create the first channel of the user
6383           properties:
6384             name:
6385               $ref: '#/components/schemas/usernameChannel'
6386             displayName:
6387               $ref: '#/components/schemas/VideoChannel/properties/displayName'
6388       required:
6389         - username
6390         - password
6391         - email
6392
6393     OAuthClient:
6394       properties:
6395         client_id:
6396           type: string
6397           pattern: /^[a-z0-9]$/
6398           maxLength: 32
6399           minLength: 32
6400           example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
6401         client_secret:
6402           type: string
6403           pattern: /^[a-zA-Z0-9]$/
6404           maxLength: 32
6405           minLength: 32
6406           example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
6407     OAuthToken-password:
6408       allOf:
6409         - $ref: '#/components/schemas/OAuthClient'
6410         - type: object
6411           properties:
6412             grant_type:
6413               type: string
6414               enum:
6415                 - password
6416                 - refresh_token
6417               default: password
6418             username:
6419               $ref: '#/components/schemas/User/properties/username'
6420             password:
6421               $ref: '#/components/schemas/password'
6422       required:
6423         - client_id
6424         - client_secret
6425         - grant_type
6426         - username
6427         - password
6428     OAuthToken-refresh_token:
6429       allOf:
6430         - $ref: '#/components/schemas/OAuthClient'
6431         - type: object
6432           properties:
6433             grant_type:
6434               type: string
6435               enum:
6436                 - password
6437                 - refresh_token
6438               default: password
6439             refresh_token:
6440               type: string
6441               example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
6442       required:
6443         - client_id
6444         - client_secret
6445         - grant_type
6446         - refresh_token
6447
6448     VideoChannel:
6449       properties:
6450         # GET/POST/PUT properties
6451         displayName:
6452           type: string
6453           description: editable name of the channel, displayed in its representations
6454           example: Videos of Framasoft
6455           minLength: 1
6456           maxLength: 120
6457         description:
6458           type: string
6459           example: Videos made with <3 by Framasoft
6460           minLength: 3
6461           maxLength: 1000
6462         support:
6463           type: string
6464           description: text shown by default on all videos of this channel, to tell the audience how to support it
6465           example: Please support our work on https://soutenir.framasoft.org/en/ <3
6466           minLength: 3
6467           maxLength: 1000
6468         # GET-only properties
6469         id:
6470           readOnly: true
6471           allOf:
6472             - $ref: '#/components/schemas/id'
6473         isLocal:
6474           readOnly: true
6475           type: boolean
6476         updatedAt:
6477           readOnly: true
6478           type: string
6479           format: date-time
6480         ownerAccount:
6481           readOnly: true
6482           nullable: true
6483           type: object
6484           properties:
6485             id:
6486               type: integer
6487             uuid:
6488               $ref: '#/components/schemas/UUIDv4'
6489     VideoChannelCreate:
6490       allOf:
6491         - $ref: '#/components/schemas/VideoChannel'
6492         - properties:
6493             name:
6494               description: username of the channel to create
6495               allOf:
6496                 - $ref: '#/components/schemas/usernameChannel'
6497       required:
6498         - name
6499         - displayName
6500     VideoChannelUpdate:
6501       allOf:
6502         - $ref: '#/components/schemas/VideoChannel'
6503         - properties:
6504             bulkVideosSupportUpdate:
6505               type: boolean
6506               description: Update the support field for all videos of this channel
6507     VideoChannelList:
6508       properties:
6509         total:
6510           type: integer
6511           example: 1
6512         data:
6513           type: array
6514           items:
6515             allOf:
6516               - $ref: '#/components/schemas/VideoChannel'
6517               - $ref: '#/components/schemas/Actor'
6518
6519     MRSSPeerLink:
6520       type: object
6521       xml:
6522         name: 'media:peerLink'
6523       properties:
6524         href:
6525           type: string
6526           xml:
6527             attribute: true
6528         type:
6529           type: string
6530           enum:
6531             - application/x-bittorrent
6532           xml:
6533             attribute: true
6534     MRSSGroupContent:
6535       type: object
6536       xml:
6537         name: 'media:content'
6538       properties:
6539         url:
6540           type: string
6541           format: url
6542           xml:
6543             attribute: true
6544         fileSize:
6545           type: integer
6546           xml:
6547             attribute: true
6548         type:
6549           type: string
6550           xml:
6551             attribute: true
6552         framerate:
6553           type: integer
6554           xml:
6555             attribute: true
6556         duration:
6557           type: integer
6558           xml:
6559             attribute: true
6560         height:
6561           type: integer
6562           xml:
6563             attribute: true
6564         lang:
6565           type: string
6566           xml:
6567             attribute: true
6568     VideoCommentsForXML:
6569       type: array
6570       xml:
6571         wrapped: true
6572         name: 'channel'
6573       items:
6574         type: object
6575         xml:
6576           name: 'item'
6577         properties:
6578           link:
6579             type: string
6580             format: url
6581           guid:
6582             type: string
6583           pubDate:
6584             type: string
6585             format: date-time
6586           'content:encoded':
6587             type: string
6588           'dc:creator':
6589             type: string
6590     VideosForXML:
6591       type: array
6592       xml:
6593         wrapped: true
6594         name: 'channel'
6595       items:
6596         type: object
6597         xml:
6598           name: 'item'
6599         properties:
6600           link:
6601             type: string
6602             format: url
6603             description: video watch page URL
6604           guid:
6605             type: string
6606             description: video canonical URL
6607           pubDate:
6608             type: string
6609             format: date-time
6610             description: video publication date
6611           description:
6612             type: string
6613             description: video description
6614           'content:encoded':
6615             type: string
6616             description: video description
6617           'dc:creator':
6618             type: string
6619             description: publisher user name
6620           'media:category':
6621             type: integer
6622             description: video category (MRSS)
6623           'media:community':
6624             type: object
6625             description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
6626             properties:
6627               'media:statistics':
6628                 type: object
6629                 properties:
6630                   views:
6631                     type: integer
6632                     xml:
6633                       attribute: true
6634           'media:embed':
6635             type: object
6636             properties:
6637               url:
6638                 type: string
6639                 format: url
6640                 description: video embed path, relative to the canonical URL domain (MRSS)
6641                 xml:
6642                   attribute: true
6643           'media:player':
6644             type: object
6645             properties:
6646               url:
6647                 type: string
6648                 format: url
6649                 description: video watch path, relative to the canonical URL domain (MRSS)
6650                 xml:
6651                   attribute: true
6652           'media:thumbnail':
6653             type: object
6654             properties:
6655               url:
6656                 type: string
6657                 format: url
6658                 xml:
6659                   attribute: true
6660               height:
6661                 type: integer
6662                 xml:
6663                   attribute: true
6664               width:
6665                 type: integer
6666                 xml:
6667                   attribute: true
6668           'media:title':
6669             type: string
6670             description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
6671           'media:description':
6672             type: string
6673           'media:rating':
6674             type: string
6675             enum:
6676               - nonadult
6677               - adult
6678             description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
6679           'enclosure':
6680             type: object
6681             description: main streamable file for the video
6682             properties:
6683               url:
6684                 type: string
6685                 format: url
6686                 xml:
6687                   attribute: true
6688               type:
6689                 type: string
6690                 enum:
6691                   - application/x-bittorrent
6692                 xml:
6693                   attribute: true
6694               length:
6695                 type: integer
6696                 xml:
6697                   attribute: true
6698           'media:group':
6699             type: array
6700             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)
6701             items:
6702               anyOf:
6703                 - $ref: '#/components/schemas/MRSSPeerLink'
6704                 - $ref: '#/components/schemas/MRSSGroupContent'
6705     NotificationSettingValue:
6706       type: integer
6707       description: >
6708         Notification type
6709
6710         - `0` NONE
6711
6712         - `1` WEB
6713
6714         - `2` EMAIL
6715       enum:
6716         - 0
6717         - 1
6718         - 3
6719     Notification:
6720       properties:
6721         id:
6722           $ref: '#/components/schemas/id'
6723         type:
6724           type: integer
6725           description: >
6726             Notification type, following the `UserNotificationType` enum:
6727
6728             - `1` NEW_VIDEO_FROM_SUBSCRIPTION
6729
6730             - `2` NEW_COMMENT_ON_MY_VIDEO
6731
6732             - `3` NEW_ABUSE_FOR_MODERATORS
6733
6734             - `4` BLACKLIST_ON_MY_VIDEO
6735
6736             - `5` UNBLACKLIST_ON_MY_VIDEO
6737
6738             - `6` MY_VIDEO_PUBLISHED
6739
6740             - `7` MY_VIDEO_IMPORT_SUCCESS
6741
6742             - `8` MY_VIDEO_IMPORT_ERROR
6743
6744             - `9` NEW_USER_REGISTRATION
6745
6746             - `10` NEW_FOLLOW
6747
6748             - `11` COMMENT_MENTION
6749
6750             - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
6751
6752             - `13` NEW_INSTANCE_FOLLOWER
6753
6754             - `14` AUTO_INSTANCE_FOLLOWING
6755         read:
6756           type: boolean
6757         video:
6758           nullable: true
6759           allOf:
6760             - $ref: '#/components/schemas/VideoInfo'
6761             - type: object
6762               properties:
6763                 channel:
6764                   $ref: '#/components/schemas/ActorInfo'
6765         videoImport:
6766           nullable: true
6767           type: object
6768           properties:
6769             id:
6770               $ref: '#/components/schemas/id'
6771             video:
6772               nullable: true
6773               $ref: '#/components/schemas/VideoInfo'
6774             torrentName:
6775               type: string
6776               nullable: true
6777             magnetUri:
6778               $ref: '#/components/schemas/VideoImport/properties/magnetUri'
6779             targetUri:
6780               type: string
6781               format: uri
6782               nullable: true
6783         comment:
6784           nullable: true
6785           type: object
6786           properties:
6787             id:
6788               $ref: '#/components/schemas/id'
6789             threadId:
6790               type: integer
6791             video:
6792               $ref: '#/components/schemas/VideoInfo'
6793             account:
6794               $ref: '#/components/schemas/ActorInfo'
6795         videoAbuse:
6796           nullable: true
6797           type: object
6798           properties:
6799             id:
6800               $ref: '#/components/schemas/id'
6801             video:
6802               allOf:
6803                 - $ref: '#/components/schemas/VideoInfo'
6804         videoBlacklist:
6805           nullable: true
6806           type: object
6807           properties:
6808             id:
6809               $ref: '#/components/schemas/id'
6810             video:
6811               allOf:
6812                 - $ref: '#/components/schemas/VideoInfo'
6813         account:
6814           nullable: true
6815           allOf:
6816             - $ref: '#/components/schemas/ActorInfo'
6817         actorFollow:
6818           type: object
6819           nullable: true
6820           properties:
6821             id:
6822               $ref: '#/components/schemas/id'
6823             follower:
6824               $ref: '#/components/schemas/ActorInfo'
6825             state:
6826               type: string
6827               enum:
6828                 - pending
6829                 - accepted
6830             following:
6831               type: object
6832               properties:
6833                 type:
6834                   type: string
6835                   enum:
6836                     - account
6837                     - channel
6838                     - instance
6839                 name:
6840                   type: string
6841                 displayName:
6842                   type: string
6843                 host:
6844                   type: string
6845                   format: hostname
6846         createdAt:
6847           type: string
6848           format: date-time
6849         updatedAt:
6850           type: string
6851           format: date-time
6852     NotificationListResponse:
6853       properties:
6854         total:
6855           type: integer
6856           example: 1
6857         data:
6858           type: array
6859           maxItems: 100
6860           items:
6861             $ref: '#/components/schemas/Notification'
6862     Plugin:
6863       properties:
6864         name:
6865           type: string
6866           example: peertube-plugin-auth-ldap
6867         type:
6868           type: integer
6869           description: >
6870             - `1`: PLUGIN
6871
6872             - `2`: THEME
6873           enum:
6874             - 1
6875             - 2
6876         latestVersion:
6877           type: string
6878           example: 0.0.3
6879         version:
6880           type: string
6881           example: 0.0.1
6882         enabled:
6883           type: boolean
6884         uninstalled:
6885           type: boolean
6886         peertubeEngine:
6887           type: string
6888           example: 2.2.0
6889         description:
6890           type: string
6891         homepage:
6892           type: string
6893           format: url
6894           example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
6895         settings:
6896           type: object
6897           additionalProperties: true
6898         createdAt:
6899           type: string
6900           format: date-time
6901         updatedAt:
6902           type: string
6903           format: date-time
6904     PluginResponse:
6905       properties:
6906         total:
6907           type: integer
6908           example: 1
6909         data:
6910           type: array
6911           maxItems: 100
6912           items:
6913             $ref: '#/components/schemas/Plugin'
6914
6915     LiveVideoUpdate:
6916       properties:
6917         saveReplay:
6918           type: boolean
6919         permanentLive:
6920           description: User can stream multiple times in a permanent live
6921           type: boolean
6922
6923     LiveVideoResponse:
6924       properties:
6925         rtmpUrl:
6926           type: string
6927         streamKey:
6928           type: string
6929           description: RTMP stream key to use to stream into this live video
6930         saveReplay:
6931           type: boolean
6932         permanentLive:
6933           description: User can stream multiple times in a permanent live
6934           type: boolean
6935
6936
6937
6938   callbacks:
6939     searchIndex:
6940       'https://search.example.org/api/v1/search/videos':
6941         post:
6942           summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
6943           responses:
6944             '200':
6945               description: successful operation
6946               content:
6947                 application/json:
6948                   schema:
6949                     $ref: '#/components/schemas/VideoListResponse'