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