support/doc/api/openapi.yaml

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