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