support/doc/api/openapi.yaml

   1 openapi: 3.0.0
   2 info:
   3   title: PeerTube
   4   version: 2.1.0-rc.1
   5   contact:
   6     name: PeerTube Community
   7     url: 'https://joinpeertube.org'
   8   license:
   9     name: AGPLv3.0
  10     url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
  11   x-logo:
  12     url: 'https://joinpeertube.org/img/brand.png'
  13     altText: PeerTube Project Homepage
  14   description: |
  15     # Introduction
  16     The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
  17     resource URLs. It returns HTTP response codes to indicate errors. It also
  18     accepts and returns JSON in the HTTP body. You can use your favorite
  19     HTTP/REST library for your programming language to use PeerTube. No official
  20     SDK is currently provided, but the spec API is fully compatible with
  21     [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
  22     which generates a client SDK in the language of your choice.
  23
  24     # Authentication
  25     When you sign up for an account, you are given the possibility to generate
  26     sessions, and authenticate using this session token. One session token can
  27     currently be used at a time.
  28
  29     # Errors
  30     The API uses standard HTTP status codes to indicate the success or failure
  31     of the API call. The body of the response will be JSON in the following
  32     format.
  33
  34     ```
  35     {
  36       "code": "unauthorized_request", // example inner error code
  37       "error": "Token is invalid." // example exposed error message
  38     }
  39     ```
  40 externalDocs:
  41   url: https://docs.joinpeertube.org/api-rest-reference.html
  42 tags:
  43   - name: Accounts
  44     description: >
  45       Using some features of PeerTube require authentication, for which Accounts
  46       provide different levels of permission as well as associated user
  47       information. Accounts also encompass remote accounts discovered across the federation.
  48   - name: Config
  49     description: >
  50       Each server exposes public information regarding supported videos and
  51       options.
  52   - name: Job
  53     description: >
  54       Jobs are long-running tasks enqueued and processed by the instance
  55       itself. No additional worker registration is currently available.
  56   - name: Server Following
  57     description: >
  58       Managing servers which the instance interacts with is crucial to the
  59       concept of federation in PeerTube and external video indexation. The PeerTube
  60       server then deals with inter-server ActivityPub operations and propagates
  61       information across its social graph by posting activities to actors' inbox
  62       endpoints.
  63   - name: Video Abuse
  64     description: |
  65       Video abuses deal with reports of local or remote videos alike.
  66   - name: Video
  67     description: |
  68       Operations dealing with listing, uploading, fetching or modifying videos.
  69   - name: Search
  70     description: |
  71       The search helps to find _videos_ from within the instance and beyond.
  72       Videos from other instances federated by the instance (that is, instances
  73       followed by the instance) can be found via keywords and other criteria of
  74       the advanced search.
  75   - name: Video Comment
  76     description: >
  77       Operations dealing with comments to a video. Comments are organized in
  78       threads.
  79   - name: Video Playlist
  80     description: >
  81       Operations dealing with playlists of videos. Playlists are bound to users
  82       and/or channels.
  83   - name: Video Channel
  84     description: >
  85       Operations dealing with creation, modification and video listing of a
  86       user's channels.
  87   - name: Video Blacklist
  88     description: >
  89       Operations dealing with blacklisting videos (removing them from view and
  90       preventing interactions).
  91   - name: Video Rate
  92     description: >
  93       Voting for a video.
  94 x-tagGroups:
  95   - name: Accounts
  96     tags:
  97       - Accounts
  98       - User
  99       - My User
 100   - name: Videos
 101     tags:
 102       - Video
 103       - Video Caption
 104       - Video Channel
 105       - Video Comment
 106       - Video Following
 107       - Video Rate
 108   - name: Moderation
 109     tags:
 110       - Video Abuse
 111       - Video Blacklist
 112   - name: Instance Configuration
 113     tags:
 114       - Config
 115       - Server Following
 116   - name: Jobs
 117     tags:
 118       - Job
 119   - name: Search
 120     tags:
 121       - Search
 122 paths:
 123   '/accounts/{name}':
 124     get:
 125       tags:
 126         - Accounts
 127       summary: Get the account by name
 128       parameters:
 129         - $ref: '#/components/parameters/name'
 130       responses:
 131         '200':
 132           description: successful operation
 133           content:
 134             application/json:
 135               schema:
 136                 $ref: '#/components/schemas/Account'
 137   '/accounts/{name}/videos':
 138     get:
 139       tags:
 140         - Accounts
 141         - Video
 142       summary: 'Get videos for an account, provided the name of that account'
 143       parameters:
 144         - $ref: '#/components/parameters/name'
 145       responses:
 146         '200':
 147           description: successful operation
 148           content:
 149             application/json:
 150               schema:
 151                 $ref: '#/components/schemas/VideoListResponse'
 152       x-code-samples:
 153         - lang: JavaScript
 154           source: |
 155             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
 156             .then(function(response) {
 157               return response.json()
 158             }).then(function(data) {
 159               console.log(data)
 160             })
 161         - lang: Shell
 162           source: |
 163             # pip install httpie
 164             http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
 165         - lang: Ruby
 166           source: |
 167             require 'net/http'
 168             require 'json'
 169
 170             uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
 171
 172             http = Net::HTTP.new(uri.host, uri.port)
 173             http.use_ssl = true
 174
 175             response = http.get(uri.request_uri)
 176
 177             puts JSON.parse(response.read_body)
 178         - lang: Python
 179           source: |
 180             import requests
 181
 182             r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
 183             json = r.json()
 184
 185             print(json)
 186   /accounts:
 187     get:
 188       tags:
 189         - Accounts
 190       summary: Get all accounts
 191       parameters:
 192         - $ref: '#/components/parameters/start'
 193         - $ref: '#/components/parameters/count'
 194         - $ref: '#/components/parameters/sort'
 195       responses:
 196         '200':
 197           description: successful operation
 198           content:
 199             'application/json':
 200               schema:
 201                 type: array
 202                 items:
 203                   $ref: '#/components/schemas/Account'
 204   /config:
 205     get:
 206       tags:
 207         - Config
 208       summary: Get the public configuration of the server
 209       responses:
 210         '200':
 211           description: successful operation
 212           content:
 213             application/json:
 214               schema:
 215                 $ref: '#/components/schemas/ServerConfig'
 216   /config/about:
 217     get:
 218       summary: Get the instance about page content
 219       tags:
 220         - Config
 221       responses:
 222         '200':
 223           description: successful operation
 224           content:
 225             application/json:
 226               schema:
 227                 $ref: '#/components/schemas/ServerConfigAbout'
 228   /config/custom:
 229     get:
 230       summary: Get the runtime configuration of the server
 231       tags:
 232         - Config
 233       security:
 234         - OAuth2:
 235             - admin
 236       responses:
 237         '200':
 238           description: successful operation
 239           content:
 240             application/json:
 241               schema:
 242                 $ref: '#/components/schemas/ServerConfigCustom'
 243     put:
 244       summary: Set the runtime configuration of the server
 245       tags:
 246         - Config
 247       security:
 248         - OAuth2:
 249             - admin
 250       responses:
 251         '200':
 252           description: successful operation
 253     delete:
 254       summary: Delete the runtime configuration of the server
 255       tags:
 256         - Config
 257       security:
 258         - OAuth2:
 259             - admin
 260       responses:
 261         '200':
 262           description: successful operation
 263   /jobs/{state}:
 264     get:
 265       summary: Get list of jobs
 266       security:
 267         - OAuth2:
 268             - admin
 269       tags:
 270         - Job
 271       parameters:
 272         - name: state
 273           in: path
 274           required: true
 275           description: The state of the job
 276           schema:
 277             type: string
 278             enum:
 279               - active
 280               - completed
 281               - failed
 282               - waiting
 283               - delayed
 284         - $ref: '#/components/parameters/start'
 285         - $ref: '#/components/parameters/count'
 286         - $ref: '#/components/parameters/sort'
 287       responses:
 288         '200':
 289           description: successful operation
 290           content:
 291             application/json:
 292               schema:
 293                 type: array
 294                 items:
 295                   $ref: '#/components/schemas/Job'
 296   '/server/following/{host}':
 297     delete:
 298       security:
 299         - OAuth2:
 300             - admin
 301       tags:
 302         - Server Following
 303       summary: Unfollow a server by hostname
 304       parameters:
 305         - name: host
 306           in: path
 307           required: true
 308           description: 'The host to unfollow '
 309           schema:
 310             type: string
 311       responses:
 312         '201':
 313           description: successful operation
 314   /server/followers:
 315     get:
 316       tags:
 317         - Server Following
 318       summary: Get followers of the server
 319       parameters:
 320         - $ref: '#/components/parameters/start'
 321         - $ref: '#/components/parameters/count'
 322         - $ref: '#/components/parameters/sort'
 323       responses:
 324         '200':
 325           description: successful operation
 326           content:
 327             application/json:
 328               schema:
 329                 type: array
 330                 items:
 331                   $ref: '#/components/schemas/Follow'
 332   /server/following:
 333     get:
 334       tags:
 335         - Server Following
 336       summary: Get servers followed by the server
 337       parameters:
 338         - $ref: '#/components/parameters/start'
 339         - $ref: '#/components/parameters/count'
 340         - $ref: '#/components/parameters/sort'
 341       responses:
 342         '200':
 343           description: successful operation
 344           content:
 345             application/json:
 346               schema:
 347                 type: array
 348                 items:
 349                   $ref: '#/components/schemas/Follow'
 350     post:
 351       security:
 352         - OAuth2:
 353             - admin
 354       tags:
 355         - Server Following
 356       summary: Follow a server
 357       responses:
 358         '204':
 359           $ref: '#/paths/~1users~1me/put/responses/204'
 360       requestBody:
 361         content:
 362           application/json:
 363             schema:
 364               $ref: '#/components/schemas/Follow'
 365   /users:
 366     post:
 367       summary: Creates user
 368       security:
 369         - OAuth2:
 370             - admin
 371       tags:
 372         - User
 373       responses:
 374         '200':
 375           description: successful operation
 376           content:
 377             application/json:
 378               schema:
 379                 $ref: '#/components/schemas/AddUserResponse'
 380       requestBody:
 381         content:
 382           application/json:
 383             schema:
 384               $ref: '#/components/schemas/AddUser'
 385         description: User to create
 386         required: true
 387     get:
 388       summary: Get a list of users
 389       security:
 390         - OAuth2: []
 391       tags:
 392         - User
 393       parameters:
 394         - $ref: '#/components/parameters/start'
 395         - $ref: '#/components/parameters/count'
 396         - $ref: '#/components/parameters/usersSort'
 397       responses:
 398         '200':
 399           description: successful operation
 400           content:
 401             application/json:
 402               schema:
 403                 type: array
 404                 items:
 405                   $ref: '#/components/schemas/User'
 406   '/users/{id}':
 407     delete:
 408       summary: Delete a user by its id
 409       security:
 410         - OAuth2:
 411             - admin
 412       tags:
 413         - User
 414       parameters:
 415         - $ref: '#/components/parameters/id'
 416       responses:
 417         '204':
 418           $ref: '#/paths/~1users~1me/put/responses/204'
 419     get:
 420       summary: Get user by its id
 421       security:
 422         - OAuth2: []
 423       tags:
 424         - User
 425       parameters:
 426         - $ref: '#/components/parameters/id'
 427       responses:
 428         '200':
 429           description: successful operation
 430           content:
 431             application/json:
 432               schema:
 433                 $ref: '#/components/schemas/User'
 434     put:
 435       summary: Update user profile by its id
 436       security:
 437         - OAuth2: []
 438       tags:
 439         - User
 440       parameters:
 441         - $ref: '#/components/parameters/id'
 442       responses:
 443         '204':
 444           $ref: '#/paths/~1users~1me/put/responses/204'
 445       requestBody:
 446         content:
 447           application/json:
 448             schema:
 449               $ref: '#/components/schemas/UpdateUser'
 450         required: true
 451   /users/register:
 452     post:
 453       summary: Register a user
 454       tags:
 455         - User
 456       responses:
 457         '204':
 458           $ref: '#/paths/~1users~1me/put/responses/204'
 459       requestBody:
 460         content:
 461           application/json:
 462             schema:
 463               $ref: '#/components/schemas/RegisterUser'
 464         required: true
 465   /users/me:
 466     get:
 467       summary: Get current user information
 468       security:
 469         - OAuth2:
 470           - user
 471       tags:
 472         - My User
 473       responses:
 474         '200':
 475           description: successful operation
 476           content:
 477             application/json:
 478               schema:
 479                 type: array
 480                 items:
 481                   $ref: '#/components/schemas/User'
 482     put:
 483       summary: Update current user information
 484       security:
 485         - OAuth2:
 486           - user
 487       tags:
 488         - My User
 489       responses:
 490         '204':
 491           description: successful operation
 492       requestBody:
 493         content:
 494           application/json:
 495             schema:
 496               $ref: '#/components/schemas/UpdateMe'
 497         required: true
 498   /users/me/videos/imports:
 499     get:
 500       summary: Get video imports of current user
 501       security:
 502         - OAuth2:
 503             - user
 504       tags:
 505         - My User
 506       parameters:
 507         - $ref: '#/components/parameters/start'
 508         - $ref: '#/components/parameters/count'
 509         - $ref: '#/components/parameters/sort'
 510       responses:
 511         '200':
 512           description: successful operation
 513           content:
 514             application/json:
 515               schema:
 516                 $ref: '#/components/schemas/VideoImport'
 517   /users/me/video-quota-used:
 518     get:
 519       summary: Get current user used quota
 520       security:
 521         - OAuth2:
 522           - user
 523       tags:
 524         - My User
 525       responses:
 526         '200':
 527           description: successful operation
 528           content:
 529             application/json:
 530               schema:
 531                 type: number
 532   '/users/me/videos/{videoId}/rating':
 533     get:
 534       summary: 'Get rating of video by its id, among those of the current user'
 535       security:
 536         - OAuth2: []
 537       tags:
 538         - My User
 539       parameters:
 540         - name: videoId
 541           in: path
 542           required: true
 543           description: 'The video id '
 544           schema:
 545             type: string
 546       responses:
 547         '200':
 548           description: successful operation
 549           content:
 550             application/json:
 551               schema:
 552                 $ref: '#/components/schemas/GetMeVideoRating'
 553   /users/me/videos:
 554     get:
 555       summary: Get videos of the current user
 556       security:
 557         - OAuth2:
 558           - user
 559       tags:
 560         - My User
 561       parameters:
 562         - $ref: '#/components/parameters/start'
 563         - $ref: '#/components/parameters/count'
 564         - $ref: '#/components/parameters/sort'
 565       responses:
 566         '200':
 567           description: successful operation
 568           content:
 569             application/json:
 570               schema:
 571                 $ref: '#/components/schemas/VideoListResponse'
 572   /users/me/subscriptions:
 573     get:
 574       summary: Get subscriptions of the current user
 575       security:
 576         - OAuth2:
 577             - user
 578       tags:
 579         - My User
 580       parameters:
 581         - $ref: '#/components/parameters/start'
 582         - $ref: '#/components/parameters/count'
 583         - $ref: '#/components/parameters/sort'
 584       responses:
 585         '200':
 586           description: successful operation
 587     post:
 588       summary: Add subscription to the current user
 589       security:
 590         - OAuth2:
 591             - user
 592       tags:
 593         - My User
 594       responses:
 595         '200':
 596           description: successful operation
 597   /users/me/subscriptions/exist:
 598     get:
 599       summary: Get if subscriptions exist for the current user
 600       security:
 601         - OAuth2:
 602             - user
 603       tags:
 604         - My User
 605       parameters:
 606         - $ref: '#/components/parameters/subscriptionsUris'
 607       responses:
 608         '200':
 609           description: successful operation
 610           content:
 611             application/json:
 612               schema:
 613                 type: object
 614   /users/me/subscriptions/videos:
 615     get:
 616       summary: Get videos of subscriptions of the current user
 617       security:
 618         - OAuth2:
 619           - user
 620       tags:
 621         - My User
 622       parameters:
 623         - $ref: '#/components/parameters/start'
 624         - $ref: '#/components/parameters/count'
 625         - $ref: '#/components/parameters/sort'
 626       responses:
 627         '200':
 628           description: successful operation
 629           content:
 630             application/json:
 631               schema:
 632                 $ref: '#/components/schemas/VideoListResponse'
 633   '/users/me/subscriptions/{subscriptionHandle}':
 634     get:
 635       summary: Get subscription of the current user for a given uri
 636       security:
 637         - OAuth2:
 638             - user
 639       tags:
 640         - My User
 641       parameters:
 642         - $ref: '#/components/parameters/subscriptionHandle'
 643       responses:
 644         '200':
 645           description: successful operation
 646           content:
 647             application/json:
 648               schema:
 649                 $ref: '#/components/schemas/VideoChannel'
 650     delete:
 651       summary: Delete subscription of the current user for a given uri
 652       security:
 653         - OAuth2:
 654             - user
 655       tags:
 656         - My User
 657       parameters:
 658         - $ref: '#/components/parameters/subscriptionHandle'
 659       responses:
 660         '200':
 661           description: successful operation
 662   /users/me/avatar/pick:
 663     post:
 664       summary: Update current user avatar
 665       security:
 666         - OAuth2: []
 667       tags:
 668         - My User
 669       responses:
 670         '200':
 671           description: successful operation
 672           content:
 673             application/json:
 674               schema:
 675                 $ref: '#/components/schemas/Avatar'
 676       requestBody:
 677         content:
 678           multipart/form-data:
 679             schema:
 680               type: object
 681               properties:
 682                 avatarfile:
 683                   description: The file to upload.
 684                   type: string
 685                   format: binary
 686             encoding:
 687               avatarfile:
 688                 contentType: image/png, image/jpeg
 689   /videos:
 690     get:
 691       summary: Get list of videos
 692       tags:
 693         - Video
 694       parameters:
 695         - $ref: '#/components/parameters/categoryOneOf'
 696         - $ref: '#/components/parameters/tagsOneOf'
 697         - $ref: '#/components/parameters/tagsAllOf'
 698         - $ref: '#/components/parameters/licenceOneOf'
 699         - $ref: '#/components/parameters/languageOneOf'
 700         - $ref: '#/components/parameters/nsfw'
 701         - $ref: '#/components/parameters/filter'
 702         - $ref: '#/components/parameters/start'
 703         - $ref: '#/components/parameters/count'
 704         - $ref: '#/components/parameters/videosSort'
 705       responses:
 706         '200':
 707           description: successful operation
 708           content:
 709             application/json:
 710               schema:
 711                 $ref: '#/components/schemas/VideoListResponse'
 712   /videos/categories:
 713     get:
 714       summary: Get list of video categories known by the server
 715       tags:
 716         - Video
 717       responses:
 718         '200':
 719           description: successful operation
 720           content:
 721             application/json:
 722               schema:
 723                 type: array
 724                 items:
 725                   type: string
 726   /videos/licences:
 727     get:
 728       summary: Get list of video licences known by the server
 729       tags:
 730         - Video
 731       responses:
 732         '200':
 733           description: successful operation
 734           content:
 735             application/json:
 736               schema:
 737                 type: array
 738                 items:
 739                   type: string
 740   /videos/languages:
 741     get:
 742       summary: Get list of languages known by the server
 743       tags:
 744         - Video
 745       responses:
 746         '200':
 747           description: successful operation
 748           content:
 749             application/json:
 750               schema:
 751                 type: array
 752                 items:
 753                   type: string
 754   /videos/privacies:
 755     get:
 756       summary: Get list of privacy policies supported by the server
 757       tags:
 758         - Video
 759       responses:
 760         '200':
 761           description: successful operation
 762           content:
 763             application/json:
 764               schema:
 765                 type: array
 766                 items:
 767                   type: string
 768   '/videos/{id}':
 769     put:
 770       summary: Update metadata for a video by its id
 771       security:
 772         - OAuth2: []
 773       tags:
 774         - Video
 775       parameters:
 776         - $ref: '#/components/parameters/idOrUUID'
 777       responses:
 778         '204':
 779           description: successful operation
 780       requestBody:
 781         content:
 782           multipart/form-data:
 783             schema:
 784               type: object
 785               properties:
 786                 thumbnailfile:
 787                   description: Video thumbnail file
 788                   type: string
 789                   format: binary
 790                 previewfile:
 791                   description: Video preview file
 792                   type: string
 793                   format: binary
 794                 category:
 795                   description: Video category
 796                   type: string
 797                 licence:
 798                   description: Video licence
 799                   type: string
 800                 language:
 801                   description: Video language
 802                   type: string
 803                 description:
 804                   description: Video description
 805                   type: string
 806                 waitTranscoding:
 807                   description: Whether or not we wait transcoding before publish the video
 808                   type: string
 809                 support:
 810                   description: Text describing how to support the video uploader
 811                   type: string
 812                 nsfw:
 813                   description: Whether or not this video contains sensitive content
 814                   type: string
 815                 name:
 816                   description: Video name
 817                   type: string
 818                 tags:
 819                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
 820                   type: array
 821                   minItems: 1
 822                   maxItems: 5
 823                   items:
 824                     type: string
 825                     minLength: 2
 826                     maxLength: 30
 827                 commentsEnabled:
 828                   description: Enable or disable comments for this video
 829                   type: string
 830                 originallyPublishedAt:
 831                   description: Date when the content was originally published
 832                   type: string
 833                   format: date-time
 834                 scheduleUpdate:
 835                   $ref: '#/components/schemas/VideoScheduledUpdate'
 836             encoding:
 837               thumbnailfile:
 838                 contentType: image/jpeg
 839               previewfile:
 840                 contentType: image/jpeg
 841     get:
 842       summary: Get a video by its id
 843       tags:
 844         - Video
 845       parameters:
 846         - $ref: '#/components/parameters/idOrUUID'
 847       responses:
 848         '200':
 849           description: successful operation
 850           content:
 851             application/json:
 852               schema:
 853                 $ref: '#/components/schemas/VideoDetails'
 854     delete:
 855       summary: Delete a video by its id
 856       security:
 857         - OAuth2: []
 858       tags:
 859         - Video
 860       parameters:
 861         - $ref: '#/components/parameters/idOrUUID'
 862       responses:
 863         '204':
 864           $ref: '#/paths/~1users~1me/put/responses/204'
 865   '/videos/{id}/description':
 866     get:
 867       summary: Get a video description by its id
 868       tags:
 869         - Video
 870       parameters:
 871         - $ref: '#/components/parameters/idOrUUID'
 872       responses:
 873         '200':
 874           description: successful operation
 875           content:
 876             application/json:
 877               schema:
 878                 type: string
 879   '/videos/{id}/views':
 880     post:
 881       summary: Add a view to the video by its id
 882       tags:
 883         - Video
 884       parameters:
 885         - $ref: '#/components/parameters/idOrUUID'
 886       responses:
 887         '204':
 888           $ref: '#/paths/~1users~1me/put/responses/204'
 889   '/videos/{id}/watching':
 890     put:
 891       summary: Set watching progress of a video by its id for a user
 892       tags:
 893         - Video
 894       security:
 895         - OAuth2: []
 896       parameters:
 897         - $ref: '#/components/parameters/idOrUUID'
 898       requestBody:
 899         content:
 900           application/json:
 901             schema:
 902               $ref: '#/components/schemas/UserWatchingVideo'
 903         required: true
 904       responses:
 905         '204':
 906           $ref: '#/paths/~1users~1me/put/responses/204'
 907   /videos/ownership:
 908     get:
 909       summary: Get list of video ownership changes requests
 910       tags:
 911         - Video
 912       security:
 913         - OAuth2: []
 914       responses:
 915         '200':
 916           description: successful operation
 917   '/videos/ownership/{id}/accept':
 918     post:
 919       summary: Refuse ownership change request for video by its id
 920       tags:
 921         - Video
 922       security:
 923         - OAuth2: []
 924       parameters:
 925         - $ref: '#/components/parameters/idOrUUID'
 926       responses:
 927         '204':
 928           $ref: '#/paths/~1users~1me/put/responses/204'
 929   '/videos/ownership/{id}/refuse':
 930     post:
 931       summary: Accept ownership change request for video by its id
 932       tags:
 933         - Video
 934       security:
 935         - OAuth2: []
 936       parameters:
 937         - $ref: '#/components/parameters/idOrUUID'
 938       responses:
 939         '204':
 940           $ref: '#/paths/~1users~1me/put/responses/204'
 941   '/videos/{id}/give-ownership':
 942     post:
 943       summary: Request change of ownership for a video you own, by its id
 944       tags:
 945         - Video
 946       security:
 947         - OAuth2: []
 948       parameters:
 949         - $ref: '#/components/parameters/idOrUUID'
 950       requestBody:
 951         required: true
 952         content:
 953           application/x-www-form-urlencoded:
 954             schema:
 955               type: object
 956               properties:
 957                 username:
 958                   type: string
 959               required:
 960                 - username
 961       responses:
 962         '204':
 963           $ref: '#/paths/~1users~1me/put/responses/204'
 964         '400':
 965           description: 'Changing video ownership to a remote account is not supported yet'
 966   /videos/upload:
 967     post:
 968       summary: Upload a video file with its metadata
 969       security:
 970         - OAuth2: []
 971       tags:
 972         - Video
 973       responses:
 974         '200':
 975           description: successful operation
 976           content:
 977             application/json:
 978               schema:
 979                 $ref: '#/components/schemas/VideoUploadResponse'
 980         '403':
 981           description: 'The user video quota is exceeded with this video.'
 982         '408':
 983           description: 'Upload has timed out'
 984         '422':
 985           description: 'Invalid input file.'
 986       requestBody:
 987         content:
 988           multipart/form-data:
 989             schema:
 990               type: object
 991               properties:
 992                 videofile:
 993                   description: Video file
 994                   type: string
 995                   format: binary
 996                 channelId:
 997                   description: Channel id that will contain this video
 998                   type: number
 999                 thumbnailfile:
1000                   description: Video thumbnail file
1001                   type: string
1002                   format: binary
1003                 previewfile:
1004                   description: Video preview file
1005                   type: string
1006                   format: binary
1007                 privacy:
1008                   $ref: '#/components/schemas/VideoPrivacySet'
1009                 category:
1010                   description: Video category
1011                   type: string
1012                 licence:
1013                   description: Video licence
1014                   type: string
1015                 language:
1016                   description: Video language
1017                   type: string
1018                 description:
1019                   description: Video description
1020                   type: string
1021                 waitTranscoding:
1022                   description: Whether or not we wait transcoding before publish the video
1023                   type: string
1024                 support:
1025                   description: Text describing how to support the video uploader
1026                   type: string
1027                 nsfw:
1028                   description: Whether or not this video contains sensitive content
1029                   type: string
1030                 name:
1031                   description: Video name
1032                   type: string
1033                 tags:
1034                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
1035                   type: array
1036                   minItems: 1
1037                   maxItems: 5
1038                   items:
1039                     type: string
1040                     minLength: 2
1041                     maxLength: 30
1042                 commentsEnabled:
1043                   description: Enable or disable comments for this video
1044                   type: string
1045                 originallyPublishedAt:
1046                   description: Date when the content was originally published
1047                   type: string
1048                   format: date-time
1049                 scheduleUpdate:
1050                   $ref: '#/components/schemas/VideoScheduledUpdate'
1051               required:
1052                 - videofile
1053                 - channelId
1054                 - name
1055             encoding:
1056               videofile:
1057                 contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
1058               thumbnailfile:
1059                 contentType: image/jpeg
1060               previewfile:
1061                 contentType: image/jpeg
1062       x-code-samples:
1063         - lang: Shell
1064           source: |
1065             ## DEPENDENCIES: httpie, jq
1066             # pip install httpie
1067             USERNAME="<your_username>"
1068             PASSWORD="<your_password>"
1069             FILE_PATH="<your_file_path>"
1070             CHANNEL_ID="<your_channel_id>"
1071             NAME="<video_name>"
1072
1073             API_PATH="https://peertube2.cpy.re/api/v1"
1074             ## AUTH
1075             client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
1076             client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
1077             token=$(http -b --form POST "$API_PATH/users/token" \
1078               client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
1079               username=$USERNAME \
1080               password=$PASSWORD \
1081               | jq -r ".access_token")
1082             ## VIDEO UPLOAD
1083             http -b --form POST "$API_PATH/videos/upload" \
1084               videofile@$FILE_PATH \
1085               channelId=$CHANNEL_ID \
1086               name=$NAME \
1087               "Authorization:Bearer $token"
1088   /videos/imports:
1089     post:
1090       summary: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
1091       security:
1092         - OAuth2: []
1093       tags:
1094         - Video
1095       responses:
1096         '200':
1097           description: successful operation
1098           content:
1099             application/json:
1100               schema:
1101                 $ref: '#/components/schemas/VideoUploadResponse'
1102       requestBody:
1103         content:
1104           multipart/form-data:
1105             schema:
1106               type: object
1107               properties:
1108                 torrentfile:
1109                   description: Torrent File
1110                   type: string
1111                   format: binary
1112                 targetUrl:
1113                   description: HTTP target URL
1114                   type: string
1115                 magnetUri:
1116                   description: Magnet URI
1117                   type: string
1118                 channelId:
1119                   description: Channel id that will contain this video
1120                   type: number
1121                 thumbnailfile:
1122                   description: Video thumbnail file
1123                   type: string
1124                   format: binary
1125                 previewfile:
1126                   description: Video preview file
1127                   type: string
1128                   format: binary
1129                 privacy:
1130                   $ref: '#/components/schemas/VideoPrivacySet'
1131                 category:
1132                   description: Video category
1133                   type: string
1134                 licence:
1135                   description: Video licence
1136                   type: string
1137                 language:
1138                   description: Video language
1139                   type: string
1140                 description:
1141                   description: Video description
1142                   type: string
1143                 waitTranscoding:
1144                   description: Whether or not we wait transcoding before publish the video
1145                   type: string
1146                 support:
1147                   description: Text describing how to support the video uploader
1148                   type: string
1149                 nsfw:
1150                   description: Whether or not this video contains sensitive content
1151                   type: string
1152                 name:
1153                   description: Video name
1154                   type: string
1155                 tags:
1156                   description: Video tags (maximum 5 tags each between 2 and 30 characters)
1157                   type: array
1158                   minItems: 1
1159                   maxItems: 5
1160                   items:
1161                     type: string
1162                     minLength: 2
1163                     maxLength: 30
1164                 commentsEnabled:
1165                   description: Enable or disable comments for this video
1166                   type: string
1167                 scheduleUpdate:
1168                   $ref: '#/components/schemas/VideoScheduledUpdate'
1169               required:
1170                 - channelId
1171                 - name
1172             encoding:
1173               torrentfile:
1174                 contentType: application/x-bittorrent
1175               thumbnailfile:
1176                 contentType: image/jpeg
1177               previewfile:
1178                 contentType: image/jpeg
1179   /videos/abuse:
1180     get:
1181       summary: Get list of reported video abuses
1182       security:
1183         - OAuth2: []
1184       tags:
1185         - Video Abuse
1186       parameters:
1187         - $ref: '#/components/parameters/start'
1188         - $ref: '#/components/parameters/count'
1189         - $ref: '#/components/parameters/abusesSort'
1190       responses:
1191         '200':
1192           description: successful operation
1193           content:
1194             application/json:
1195               schema:
1196                 type: array
1197                 items:
1198                   $ref: '#/components/schemas/VideoAbuse'
1199   '/videos/{id}/abuse':
1200     post:
1201       summary: 'Report an abuse, on a video by its id'
1202       security:
1203         - OAuth2: []
1204       tags:
1205         - Video Abuse
1206       parameters:
1207         - $ref: '#/components/parameters/idOrUUID'
1208       responses:
1209         '204':
1210           $ref: '#/paths/~1users~1me/put/responses/204'
1211   '/videos/{id}/blacklist':
1212     post:
1213       summary: Put on blacklist a video by its id
1214       security:
1215         - OAuth2:
1216             - admin
1217             - moderator
1218       tags:
1219         - Video Blacklist
1220       parameters:
1221         - $ref: '#/components/parameters/idOrUUID'
1222       responses:
1223         '204':
1224           $ref: '#/paths/~1users~1me/put/responses/204'
1225     delete:
1226       summary: Delete an entry of the blacklist of a video by its id
1227       security:
1228         - OAuth2:
1229             - admin
1230             - moderator
1231       tags:
1232         - Video Blacklist
1233       parameters:
1234         - $ref: '#/components/parameters/idOrUUID'
1235       responses:
1236         '204':
1237           $ref: '#/paths/~1users~1me/put/responses/204'
1238   /videos/blacklist:
1239     get:
1240       summary: Get list of videos on blacklist
1241       security:
1242         - OAuth2:
1243             - admin
1244             - moderator
1245       tags:
1246         - Video Blacklist
1247       parameters:
1248         - $ref: '#/components/parameters/start'
1249         - $ref: '#/components/parameters/count'
1250         - $ref: '#/components/parameters/blacklistsSort'
1251       responses:
1252         '200':
1253           description: successful operation
1254           content:
1255             application/json:
1256               schema:
1257                 type: array
1258                 items:
1259                   $ref: '#/components/schemas/VideoBlacklist'
1260   /videos/{id}/captions:
1261     get:
1262       summary: Get list of video's captions
1263       tags:
1264         - Video Caption
1265       parameters:
1266         - $ref: '#/components/parameters/idOrUUID'
1267       responses:
1268         '200':
1269           description: successful operation
1270           content:
1271             application/json:
1272               schema:
1273                 type: object
1274                 properties:
1275                   total:
1276                     type: integer
1277                   data:
1278                     type: array
1279                     items:
1280                       $ref: '#/components/schemas/VideoCaption'
1281   /videos/{id}/captions/{captionLanguage}:
1282     put:
1283       summary: Add or replace a video caption
1284       tags:
1285         - Video Caption
1286       parameters:
1287         - $ref: '#/components/parameters/idOrUUID'
1288         - $ref: '#/components/parameters/captionLanguage'
1289       requestBody:
1290         content:
1291           multipart/form-data:
1292             schema:
1293               type: object
1294               properties:
1295                 captionfile:
1296                   description: The file to upload.
1297                   type: string
1298                   format: binary
1299             encoding:
1300               captionfile:
1301                 contentType: text/vtt, application/x-subrip, text/plain
1302       responses:
1303         '204':
1304           $ref: '#/paths/~1users~1me/put/responses/204'
1305     delete:
1306       summary: Delete a video caption
1307       tags:
1308         - Video Caption
1309       parameters:
1310         - $ref: '#/components/parameters/idOrUUID'
1311         - $ref: '#/components/parameters/captionLanguage'
1312       responses:
1313         '204':
1314           $ref: '#/paths/~1users~1me/put/responses/204'
1315   /video-channels:
1316     get:
1317       summary: Get list of video channels
1318       tags:
1319         - Video Channel
1320       parameters:
1321         - $ref: '#/components/parameters/start'
1322         - $ref: '#/components/parameters/count'
1323         - $ref: '#/components/parameters/sort'
1324       responses:
1325         '200':
1326           description: successful operation
1327           content:
1328             application/json:
1329               schema:
1330                 type: array
1331                 items:
1332                   $ref: '#/components/schemas/VideoChannel'
1333     post:
1334       summary: Creates a video channel for the current user
1335       security:
1336         - OAuth2: []
1337       tags:
1338         - Video Channel
1339       responses:
1340         '204':
1341           $ref: '#/paths/~1users~1me/put/responses/204'
1342       requestBody:
1343         content:
1344           application/json:
1345             schema:
1346               $ref: '#/components/schemas/VideoChannelCreate'
1347   '/video-channels/{channelHandle}':
1348     get:
1349       summary: Get a video channel by its id
1350       tags:
1351         - Video Channel
1352       parameters:
1353         - $ref: '#/components/parameters/channelHandle'
1354       responses:
1355         '200':
1356           description: successful operation
1357           content:
1358             application/json:
1359               schema:
1360                 $ref: '#/components/schemas/VideoChannel'
1361     put:
1362       summary: Update a video channel by its id
1363       security:
1364         - OAuth2: []
1365       tags:
1366         - Video Channel
1367       parameters:
1368         - $ref: '#/components/parameters/channelHandle'
1369       responses:
1370         '204':
1371           $ref: '#/paths/~1users~1me/put/responses/204'
1372       requestBody:
1373         content:
1374           application/json:
1375             schema:
1376               $ref: '#/components/schemas/VideoChannelUpdate'
1377     delete:
1378       summary: Delete a video channel by its id
1379       security:
1380         - OAuth2: []
1381       tags:
1382         - Video Channel
1383       parameters:
1384         - $ref: '#/components/parameters/channelHandle'
1385       responses:
1386         '204':
1387           $ref: '#/paths/~1users~1me/put/responses/204'
1388   '/video-channels/{channelHandle}/videos':
1389     get:
1390       summary: Get videos of a video channel by its id
1391       tags:
1392         - Video
1393         - Video Channel
1394       parameters:
1395         - $ref: '#/components/parameters/channelHandle'
1396       responses:
1397         '200':
1398           description: successful operation
1399           content:
1400             application/json:
1401               schema:
1402                 $ref: '#/components/schemas/VideoListResponse'
1403   /video-playlists:
1404     get:
1405       summary: Get list of video playlists
1406       tags:
1407         - Video Playlist
1408       parameters:
1409         - $ref: '#/components/parameters/start'
1410         - $ref: '#/components/parameters/count'
1411         - $ref: '#/components/parameters/sort'
1412       responses:
1413         '200':
1414           description: successful operation
1415           content:
1416             application/json:
1417               schema:
1418                 type: array
1419                 items:
1420                   $ref: '#/components/schemas/VideoPlaylist'
1421   '/accounts/{name}/video-channels':
1422     get:
1423       summary: Get video channels of an account by its name
1424       tags:
1425         - Video Channel
1426       parameters:
1427         - $ref: '#/components/parameters/name'
1428       responses:
1429         '200':
1430           description: successful operation
1431           content:
1432             application/json:
1433               schema:
1434                 type: array
1435                 items:
1436                   $ref: '#/components/schemas/VideoChannel'
1437   '/accounts/{name}/ratings':
1438     get:
1439       summary: Get ratings of an account by its name
1440       security:
1441         - OAuth2: []
1442       tags:
1443         - User
1444       parameters:
1445         - $ref: '#/components/parameters/name'
1446         - $ref: '#/components/parameters/start'
1447         - $ref: '#/components/parameters/count'
1448         - $ref: '#/components/parameters/sort'
1449         - name: rating
1450           in: query
1451           required: false
1452           description: Optionally filter which ratings to retrieve
1453           schema:
1454             type: string
1455             enum:
1456               - like
1457               - dislike
1458       responses:
1459         '200':
1460           description: successful operation
1461           content:
1462             application/json:
1463               schema:
1464                 type: array
1465                 items:
1466                   $ref: '#/components/schemas/VideoRating'
1467   '/videos/{id}/comment-threads':
1468     get:
1469       summary: Get the comment threads of a video by its id
1470       tags:
1471         - Video Comment
1472       parameters:
1473         - $ref: '#/components/parameters/idOrUUID'
1474         - $ref: '#/components/parameters/start'
1475         - $ref: '#/components/parameters/count'
1476         - $ref: '#/components/parameters/commentsSort'
1477       responses:
1478         '200':
1479           description: successful operation
1480           content:
1481             application/json:
1482               schema:
1483                 $ref: '#/components/schemas/CommentThreadResponse'
1484     post:
1485       summary: 'Creates a comment thread, on a video by its id'
1486       security:
1487         - OAuth2: []
1488       tags:
1489         - Video Comment
1490       parameters:
1491         - $ref: '#/components/parameters/idOrUUID'
1492       responses:
1493         '200':
1494           description: successful operation
1495           content:
1496             application/json:
1497               schema:
1498                 $ref: '#/components/schemas/CommentThreadPostResponse'
1499   '/videos/{id}/comment-threads/{threadId}':
1500     get:
1501       summary: 'Get the comment thread by its id, of a video by its id'
1502       tags:
1503         - Video Comment
1504       parameters:
1505         - $ref: '#/components/parameters/idOrUUID'
1506         - $ref: '#/components/parameters/threadId'
1507       responses:
1508         '200':
1509           description: successful operation
1510           content:
1511             application/json:
1512               schema:
1513                 $ref: '#/components/schemas/VideoCommentThreadTree'
1514   '/videos/{id}/comments/{commentId}':
1515     post:
1516       summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1517       security:
1518         - OAuth2: []
1519       tags:
1520         - Video Comment
1521       parameters:
1522         - $ref: '#/components/parameters/idOrUUID'
1523         - $ref: '#/components/parameters/commentId'
1524       responses:
1525         '200':
1526           description: successful operation
1527           content:
1528             application/json:
1529               schema:
1530                 $ref: '#/components/schemas/CommentThreadPostResponse'
1531     delete:
1532       summary: 'Delete a comment in a comment thread by its id, of a video by its id'
1533       security:
1534         - OAuth2: []
1535       tags:
1536         - Video Comment
1537       parameters:
1538         - $ref: '#/components/parameters/idOrUUID'
1539         - $ref: '#/components/parameters/commentId'
1540       responses:
1541         '204':
1542           $ref: '#/paths/~1users~1me/put/responses/204'
1543   '/videos/{id}/rate':
1544     put:
1545       summary: Vote for a video by its id
1546       security:
1547         - OAuth2: []
1548       tags:
1549         - Video Rate
1550       parameters:
1551         - $ref: '#/components/parameters/idOrUUID'
1552       responses:
1553         '204':
1554           $ref: '#/paths/~1users~1me/put/responses/204'
1555   /search/videos:
1556     get:
1557       tags:
1558         - Search
1559       summary: Get the videos corresponding to a given query
1560       parameters:
1561         - $ref: '#/components/parameters/start'
1562         - $ref: '#/components/parameters/count'
1563         - $ref: '#/components/parameters/videosSearchSort'
1564         - name: search
1565           in: query
1566           required: true
1567           description: String to search
1568           schema:
1569             type: string
1570       responses:
1571         '200':
1572           description: successful operation
1573           content:
1574             application/json:
1575               schema:
1576                 $ref: '#/components/schemas/VideoListResponse'
1577 servers:
1578   - url: 'https://peertube.cpy.re/api/v1'
1579     description: Live Test Server (live data - stable version)
1580   - url: 'https://peertube2.cpy.re/api/v1'
1581     description: Live Test Server (live data - bleeding edge version)
1582   - url: 'https://peertube3.cpy.re/api/v1'
1583     description: Live Test Server (live data - bleeding edge version)
1584 components:
1585   parameters:
1586     start:
1587       name: start
1588       in: query
1589       required: false
1590       description: Offset
1591       schema:
1592         type: number
1593     count:
1594       name: count
1595       in: query
1596       required: false
1597       description: Number of items
1598       schema:
1599         type: number
1600     sort:
1601       name: sort
1602       in: query
1603       required: false
1604       description: Sort column (-createdAt for example)
1605       schema:
1606         type: string
1607     videosSort:
1608       name: sort
1609       in: query
1610       required: false
1611       description: Sort videos by criteria
1612       schema:
1613         type: string
1614         enum:
1615         - -name
1616         - -duration
1617         - -createdAt
1618         - -publishedAt
1619         - -views
1620         - -likes
1621         - -trending
1622     videosSearchSort:
1623       name: sort
1624       in: query
1625       required: false
1626       description: Sort videos by criteria
1627       schema:
1628         type: string
1629         enum:
1630         - -name
1631         - -duration
1632         - -createdAt
1633         - -publishedAt
1634         - -views
1635         - -likes
1636         - -match
1637     commentsSort:
1638       name: sort
1639       in: query
1640       required: false
1641       description: Sort comments by criteria
1642       schema:
1643         type: string
1644         enum:
1645         - -createdAt
1646         - -totalReplies
1647     blacklistsSort:
1648       name: sort
1649       in: query
1650       required: false
1651       description: Sort blacklists by criteria
1652       schema:
1653         type: string
1654         enum:
1655         - -id
1656         - -name
1657         - -duration
1658         - -views
1659         - -likes
1660         - -dislikes
1661         - -uuid
1662         - -createdAt
1663     usersSort:
1664       name: sort
1665       in: query
1666       required: false
1667       description: Sort users by criteria
1668       schema:
1669         type: string
1670         enum:
1671         - -id
1672         - -username
1673         - -createdAt
1674     abusesSort:
1675       name: sort
1676       in: query
1677       required: false
1678       description: Sort abuses by criteria
1679       schema:
1680         type: string
1681         enum:
1682         - -id
1683         - -createdAt
1684         - -state
1685     name:
1686       name: name
1687       in: path
1688       required: true
1689       description: >-
1690         The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1691         example)
1692       schema:
1693         type: string
1694     id:
1695       name: id
1696       in: path
1697       required: true
1698       description: The user id
1699       schema:
1700         type: number
1701     idOrUUID:
1702       name: id
1703       in: path
1704       required: true
1705       description: The video id or uuid
1706       schema:
1707         type: string
1708     captionLanguage:
1709       name: captionLanguage
1710       in: path
1711       required: true
1712       description: The caption language
1713       schema:
1714         type: string
1715     channelHandle:
1716       name: channelHandle
1717       in: path
1718       required: true
1719       description: "The video channel handle (example: 'my_username@example.com' or 'my_username')"
1720       schema:
1721         type: string
1722     subscriptionHandle:
1723       name: subscriptionHandle
1724       in: path
1725       required: true
1726       description: "The subscription handle (example: 'my_username@example.com' or 'my_username')"
1727       schema:
1728         type: string
1729     threadId:
1730       name: threadId
1731       in: path
1732       required: true
1733       description: The thread id (root comment id)
1734       schema:
1735         type: number
1736     commentId:
1737       name: commentId
1738       in: path
1739       required: true
1740       description: The comment id
1741       schema:
1742         type: number
1743     categoryOneOf:
1744       name: categoryOneOf
1745       in: query
1746       required: false
1747       description: category id of the video
1748       schema:
1749         oneOf:
1750         - type: number
1751         - type: array
1752           items:
1753             type: number
1754       style: form
1755       explode: false
1756     tagsOneOf:
1757       name: tagsOneOf
1758       in: query
1759       required: false
1760       description: tag(s) of the video
1761       schema:
1762         oneOf:
1763         - type: string
1764         - type: array
1765           items:
1766             type: string
1767       style: form
1768       explode: false
1769     tagsAllOf:
1770       name: tagsAllOf
1771       in: query
1772       required: false
1773       description: tag(s) of the video, where all should be present in the video
1774       schema:
1775         oneOf:
1776         - type: string
1777         - type: array
1778           items:
1779             type: string
1780       style: form
1781       explode: false
1782     languageOneOf:
1783       name: languageOneOf
1784       in: query
1785       required: false
1786       description: language id of the video
1787       schema:
1788         oneOf:
1789         - type: string
1790         - type: array
1791           items:
1792             type: string
1793       style: form
1794       explode: false
1795     licenceOneOf:
1796       name: licenceOneOf
1797       in: query
1798       required: false
1799       description: licence id of the video
1800       schema:
1801         oneOf:
1802         - type: number
1803         - type: array
1804           items:
1805             type: number
1806       style: form
1807       explode: false
1808     nsfw:
1809       name: nsfw
1810       in: query
1811       required: false
1812       description: whether to include nsfw videos, if any
1813       schema:
1814         type: string
1815         enum:
1816         - 'true'
1817         - 'false'
1818     filter:
1819       name: filter
1820       in: query
1821       required: false
1822       description: >
1823         Special filters (local for instance) which might require special rights:
1824          * `local` - only videos local to the instance
1825          * `all-local` - only videos local to the instance, but showing private and unlisted videos (requires Admin privileges)
1826       schema:
1827         type: string
1828         enum:
1829         - local
1830         - all-local
1831     subscriptionsUris:
1832       name: uris
1833       in: query
1834       required: true
1835       description: list of uris to check if each is part of the user subscriptions
1836       schema:
1837         type: array
1838         items:
1839           type: string
1840   securitySchemes:
1841     OAuth2:
1842       description: >
1843         In the header: *Authorization: Bearer <token\>*
1844
1845
1846         Authenticating via OAuth requires the following steps:
1847
1848
1849         - Have an account with sufficient authorization levels
1850
1851         - [Generate](https://docs.joinpeertube.org/#/api-rest-getting-started) a
1852         Bearer Token
1853
1854         - Make Authenticated Requests
1855       type: oauth2
1856       flows:
1857         password:
1858           tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1859           scopes:
1860             admin: Admin scope
1861             moderator: Moderator scope
1862             user: User scope
1863   schemas:
1864     VideoConstantNumber:
1865       properties:
1866         id:
1867           type: number
1868         label:
1869           type: string
1870     VideoConstantString:
1871       properties:
1872         id:
1873           type: string
1874         label:
1875           type: string
1876     VideoPrivacySet:
1877       type: integer
1878       enum:
1879         - 1
1880         - 2
1881         - 3
1882       description: 'The video privacy (Public = 1, Unlisted = 2, Private = 3)'
1883     VideoPrivacyConstant:
1884       properties:
1885         id:
1886           type: integer
1887           enum:
1888             - 1
1889             - 2
1890             - 3
1891         label:
1892           type: string
1893     VideoStateConstant:
1894       properties:
1895         id:
1896           type: integer
1897           enum:
1898             - 1
1899             - 2
1900             - 3
1901           description: 'The video state (Published = 1, to transcode = 2, to import = 3)'
1902         label:
1903           type: string
1904     VideoResolutionConstant:
1905       properties:
1906         id:
1907           type: integer
1908           description: 'Video resolution (240, 360, 720 ...)'
1909         label:
1910           type: string
1911     VideoScheduledUpdate:
1912       properties:
1913         privacy:
1914           $ref: '#/components/schemas/VideoPrivacySet'
1915           description: Video privacy target
1916         updateAt:
1917           type: string
1918           format: date
1919           description: When to update the video
1920       required:
1921         - updateAt
1922     VideoAccountSummary:
1923       properties:
1924         id:
1925           type: number
1926         name:
1927           type: string
1928         displayName:
1929           type: string
1930         url:
1931           type: string
1932         host:
1933           type: string
1934         avatar:
1935           nullable: true
1936           $ref: '#/components/schemas/Avatar'
1937     VideoChannelSummary:
1938       properties:
1939         id:
1940           type: number
1941         name:
1942           type: string
1943         displayName:
1944           type: string
1945         url:
1946           type: string
1947         host:
1948           type: string
1949         avatar:
1950           nullable: true
1951           $ref: '#/components/schemas/Avatar'
1952     PlaylistElement:
1953       properties:
1954         position:
1955           type: number
1956         startTimestamp:
1957           type: number
1958         stopTimestamp:
1959           type: number
1960         video:
1961           nullable: true
1962           $ref: '#/components/schemas/Video'
1963     VideoFile:
1964       properties:
1965         magnetUri:
1966           type: string
1967         resolution:
1968           $ref: '#/components/schemas/VideoResolutionConstant'
1969         size:
1970           type: number
1971           description: 'Video file size in bytes'
1972         torrentUrl:
1973           type: string
1974         torrentDownloadUrl:
1975           type: string
1976         fileUrl:
1977           type: string
1978         fileDownloadUrl:
1979           type: string
1980         fps:
1981           type: number
1982     VideoStreamingPlaylists:
1983       properties:
1984         id:
1985           type: number
1986         type:
1987           type: number
1988           enum:
1989             - 1
1990           description: 'Playlist type (HLS = 1)'
1991         playlistUrl:
1992           type: string
1993         segmentsSha256Url:
1994           type: string
1995         redundancies:
1996           type: array
1997           items:
1998             type: object
1999             properties:
2000               baseUrl:
2001                 type: string
2002     Video:
2003       properties:
2004         id:
2005           type: number
2006         uuid:
2007           type: string
2008         createdAt:
2009           type: string
2010         publishedAt:
2011           type: string
2012         updatedAt:
2013           type: string
2014         originallyPublishedAt:
2015           type: string
2016         category:
2017           $ref: '#/components/schemas/VideoConstantNumber'
2018         licence:
2019           $ref: '#/components/schemas/VideoConstantNumber'
2020         language:
2021           $ref: '#/components/schemas/VideoConstantString'
2022         privacy:
2023           $ref: '#/components/schemas/VideoPrivacyConstant'
2024         description:
2025           type: string
2026         duration:
2027           type: number
2028         isLocal:
2029           type: boolean
2030         name:
2031           type: string
2032         thumbnailPath:
2033           type: string
2034         previewPath:
2035           type: string
2036         embedPath:
2037           type: string
2038         views:
2039           type: number
2040         likes:
2041           type: number
2042         dislikes:
2043           type: number
2044         nsfw:
2045           type: boolean
2046         waitTranscoding:
2047           type: boolean
2048           nullable: true
2049         state:
2050           $ref: '#/components/schemas/VideoStateConstant'
2051         scheduledUpdate:
2052           nullable: true
2053           $ref: '#/components/schemas/VideoScheduledUpdate'
2054         blacklisted:
2055           nullable: true
2056           type: boolean
2057         blacklistedReason:
2058           nullable: true
2059           type: string
2060         account:
2061           $ref: '#/components/schemas/VideoAccountSummary'
2062         channel:
2063           $ref: '#/components/schemas/VideoChannelSummary'
2064         userHistory:
2065           nullable: true
2066           type: object
2067           properties:
2068             currentTime:
2069               type: number
2070     VideoDetails:
2071       allOf:
2072         - $ref: '#/components/schemas/Video'
2073         - type: object
2074           properties:
2075             descriptionPath:
2076               type: string
2077             support:
2078               type: string
2079             channel:
2080               $ref: '#/components/schemas/VideoChannel'
2081             account:
2082               $ref: '#/components/schemas/Account'
2083             tags:
2084               type: array
2085               items:
2086                 type: string
2087             files:
2088               type: array
2089               items:
2090                 $ref: '#/components/schemas/VideoFile'
2091             commentsEnabled:
2092               type: boolean
2093             downloadEnabled:
2094               type: boolean
2095             trackerUrls:
2096               type: array
2097               items:
2098                 type: string
2099             streamingPlaylists:
2100               type: array
2101               items:
2102                 $ref: '#/components/schemas/VideoStreamingPlaylists'
2103     VideoImportStateConstant:
2104       properties:
2105         id:
2106           type: integer
2107           enum:
2108             - 1
2109             - 2
2110             - 3
2111           description: 'The video import state (Pending = 1, Success = 2, Failed = 3)'
2112         label:
2113           type: string
2114     VideoImport:
2115       properties:
2116         id:
2117           type: number
2118         targetUrl:
2119           type: string
2120         magnetUri:
2121           type: string
2122         torrentName:
2123           type: string
2124         state:
2125           type: object
2126           properties:
2127             id:
2128               $ref: '#/components/schemas/VideoImportStateConstant'
2129             label:
2130               type: string
2131         error:
2132           type: string
2133         createdAt:
2134           type: string
2135         updatedAt:
2136           type: string
2137         video:
2138           $ref: '#/components/schemas/Video'
2139     VideoAbuse:
2140       properties:
2141         id:
2142           type: number
2143         reason:
2144           type: string
2145         reporterAccount:
2146           $ref: '#/components/schemas/Account'
2147         video:
2148           type: object
2149           properties:
2150             id:
2151               type: number
2152             name:
2153               type: string
2154             uuid:
2155               type: string
2156             url:
2157               type: string
2158         createdAt:
2159           type: string
2160     VideoBlacklist:
2161       properties:
2162         id:
2163           type: number
2164         videoId:
2165           type: number
2166         createdAt:
2167           type: string
2168         updatedAt:
2169           type: string
2170         name:
2171           type: string
2172         uuid:
2173           type: string
2174         description:
2175           type: string
2176         duration:
2177           type: number
2178         views:
2179           type: number
2180         likes:
2181           type: number
2182         dislikes:
2183           type: number
2184         nsfw:
2185           type: boolean
2186     VideoChannel:
2187       properties:
2188         displayName:
2189           type: string
2190         description:
2191           type: string
2192         isLocal:
2193           type: boolean
2194         ownerAccount:
2195           type: object
2196           properties:
2197             id:
2198               type: number
2199             uuid:
2200               type: string
2201     VideoPlaylist:
2202       properties:
2203         id:
2204           type: number
2205         createdAt:
2206           type: string
2207         updatedAt:
2208           type: string
2209         description:
2210           type: string
2211         uuid:
2212           type: string
2213         displayName:
2214           type: string
2215         isLocal:
2216           type: boolean
2217         videoLength:
2218           type: number
2219         thumbnailPath:
2220           type: string
2221         privacy:
2222           type: object
2223           properties:
2224             id:
2225               type: number
2226             label:
2227               type: string
2228         type:
2229           type: object
2230           properties:
2231             id:
2232               type: number
2233             label:
2234               type: string
2235         ownerAccount:
2236           type: object
2237           properties:
2238             id:
2239               type: number
2240             name:
2241               type: string
2242             displayName:
2243               type: string
2244             url:
2245               type: string
2246             host:
2247               type: string
2248     VideoComment:
2249       properties:
2250         id:
2251           type: number
2252         url:
2253           type: string
2254         text:
2255           type: string
2256         threadId:
2257           type: number
2258         inReplyToCommentId:
2259           type: number
2260         videoId:
2261           type: number
2262         createdAt:
2263           type: string
2264         updatedAt:
2265           type: string
2266         totalRepliesFromVideoAuthor:
2267           type: number
2268         totalReplies:
2269           type: number
2270         account:
2271           $ref: '#/components/schemas/Account'
2272     VideoCommentThreadTree:
2273       properties:
2274         comment:
2275           $ref: '#/components/schemas/VideoComment'
2276         children:
2277           type: array
2278           items:
2279             $ref: '#/components/schemas/VideoCommentThreadTree'
2280     VideoCaption:
2281       properties:
2282         language:
2283           $ref: '#/components/schemas/VideoConstantString'
2284         captionPath:
2285           type: string
2286     Avatar:
2287       properties:
2288         path:
2289           type: string
2290         createdAt:
2291           type: string
2292         updatedAt:
2293           type: string
2294     Actor:
2295       properties:
2296         id:
2297           type: number
2298         url:
2299           type: string
2300         name:
2301           type: string
2302         host:
2303           type: string
2304         followingCount:
2305           type: number
2306         followersCount:
2307           type: number
2308         createdAt:
2309           type: string
2310         updatedAt:
2311           type: string
2312         avatar:
2313           $ref: '#/components/schemas/Avatar'
2314     Account:
2315       allOf:
2316         - $ref: '#/components/schemas/Actor'
2317         - properties:
2318             userId:
2319               type: string
2320             displayName:
2321               type: string
2322             description:
2323               type: string
2324     User:
2325       properties:
2326         id:
2327           type: number
2328         username:
2329           type: string
2330         email:
2331           type: string
2332         displayNSFW:
2333           type: boolean
2334         autoPlayVideo:
2335           type: boolean
2336         role:
2337           type: integer
2338           enum:
2339             - 0
2340             - 1
2341             - 2
2342           description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2343         roleLabel:
2344           type: string
2345           enum:
2346             - User
2347             - Moderator
2348             - Administrator
2349         videoQuota:
2350           type: number
2351         videoQuotaDaily:
2352           type: number
2353         createdAt:
2354           type: string
2355         account:
2356           $ref: '#/components/schemas/Account'
2357         videoChannels:
2358           type: array
2359           items:
2360             $ref: '#/components/schemas/VideoChannel'
2361     UserWatchingVideo:
2362       properties:
2363         currentTime:
2364           type: number
2365     ServerConfig:
2366       properties:
2367         instance:
2368           type: object
2369           properties:
2370             name:
2371               type: string
2372             shortDescription:
2373               type: string
2374             defaultClientRoute:
2375               type: string
2376             isNSFW:
2377               type: boolean
2378             defaultNSFWPolicy:
2379               type: string
2380             customizations:
2381               type: object
2382               properties:
2383                 javascript:
2384                   type: string
2385                 css:
2386                   type: string
2387         plugin:
2388           type: object
2389           properties:
2390             registered:
2391               type: array
2392               items:
2393                 type: string
2394         theme:
2395           type: object
2396           properties:
2397             registered:
2398               type: array
2399               items:
2400                 type: string
2401         email:
2402           type: object
2403           properties:
2404             enabled:
2405               type: boolean
2406         contactForm:
2407           type: object
2408           properties:
2409             enabled:
2410               type: boolean
2411         serverVersion:
2412           type: string
2413         serverCommit:
2414           type: string
2415         signup:
2416           type: object
2417           properties:
2418             allowed:
2419               type: boolean
2420             allowedForCurrentIP:
2421               type: boolean
2422             requiresEmailVerification:
2423               type: boolean
2424         transcoding:
2425           type: object
2426           properties:
2427             hls:
2428               type: object
2429               properties:
2430                 enabled:
2431                   type: boolean
2432             enabledResolutions:
2433               type: array
2434               items:
2435                 type: number
2436         import:
2437           type: object
2438           properties:
2439             videos:
2440               type: object
2441               properties:
2442                 http:
2443                   type: object
2444                   properties:
2445                     enabled:
2446                       type: boolean
2447                 torrent:
2448                   type: object
2449                   properties:
2450                     enabled:
2451                       type: boolean
2452         autoBlacklist:
2453           type: object
2454           properties:
2455             videos:
2456               type: object
2457               properties:
2458                 ofUsers:
2459                   type: object
2460                   properties:
2461                     enabled:
2462                       type: boolean
2463         avatar:
2464           type: object
2465           properties:
2466             file:
2467               type: object
2468               properties:
2469                 size:
2470                   type: object
2471                   properties:
2472                     max:
2473                       type: number
2474             extensions:
2475               type: array
2476               items:
2477                 type: string
2478         video:
2479           type: object
2480           properties:
2481             image:
2482               type: object
2483               properties:
2484                 extensions:
2485                   type: array
2486                   items:
2487                     type: string
2488                 size:
2489                   type: object
2490                   properties:
2491                     max:
2492                       type: number
2493             file:
2494               type: object
2495               properties:
2496                 extensions:
2497                   type: array
2498                   items:
2499                     type: string
2500         videoCaption:
2501           type: object
2502           properties:
2503             file:
2504               type: object
2505               properties:
2506                 size:
2507                   type: object
2508                   properties:
2509                     max:
2510                       type: number
2511                 extensions:
2512                   type: array
2513                   items:
2514                     type: string
2515         user:
2516           type: object
2517           properties:
2518             videoQuota:
2519               type: number
2520             videoQuotaDaily:
2521               type: number
2522         trending:
2523           type: object
2524           properties:
2525             videos:
2526               type: object
2527               properties:
2528                 intervalDays:
2529                   type: number
2530         tracker:
2531           type: object
2532           properties:
2533             enabled:
2534               type: boolean
2535     ServerConfigAbout:
2536       properties:
2537         instance:
2538           type: object
2539           properties:
2540             name:
2541               type: string
2542             shortDescription:
2543               type: string
2544             description:
2545               type: string
2546             terms:
2547               type: string
2548     ServerConfigCustom:
2549       properties:
2550         instance:
2551           type: object
2552           properties:
2553             name:
2554               type: string
2555             shortDescription:
2556               type: string
2557             description:
2558               type: string
2559             terms:
2560               type: string
2561             defaultClientRoute:
2562               type: string
2563             isNSFW:
2564               type: boolean
2565             defaultNSFWPolicy:
2566               type: string
2567             customizations:
2568               type: object
2569               properties:
2570                 javascript:
2571                   type: string
2572                 css:
2573                   type: string
2574         theme:
2575           type: object
2576           properties:
2577             default:
2578               type: string
2579         services:
2580           type: object
2581           properties:
2582             twitter:
2583               type: object
2584               properties:
2585                 username:
2586                   type: string
2587                 whitelisted:
2588                   type: boolean
2589         cache:
2590           type: object
2591           properties:
2592             previews:
2593               type: object
2594               properties:
2595                 size:
2596                   type: number
2597             captions:
2598               type: object
2599               properties:
2600                 size:
2601                   type: number
2602         signup:
2603           type: object
2604           properties:
2605             enabled:
2606               type: boolean
2607             limit:
2608               type: number
2609             requiresEmailVerification:
2610               type: boolean
2611         admin:
2612           type: object
2613           properties:
2614             email:
2615               type: string
2616         contactForm:
2617           type: object
2618           properties:
2619             enabled:
2620               type: boolean
2621         user:
2622           type: object
2623           properties:
2624             videoQuota:
2625               type: number
2626             videoQuotaDaily:
2627               type: number
2628         transcoding:
2629           type: object
2630           properties:
2631             enabled:
2632               type: boolean
2633             allowAdditionalExtensions:
2634               type: boolean
2635             allowAudioFiles:
2636               type: boolean
2637             threads:
2638               type: number
2639             resolutions:
2640               type: object
2641               properties:
2642                 240p:
2643                   type: boolean
2644                 360p:
2645                   type: boolean
2646                 480p:
2647                   type: boolean
2648                 720p:
2649                   type: boolean
2650                 1080p:
2651                   type: boolean
2652                 2160p:
2653                   type: boolean
2654             hls:
2655               type: object
2656               properties:
2657                 enabled:
2658                   type: boolean
2659         import:
2660           type: object
2661           properties:
2662             videos:
2663               type: object
2664               properties:
2665                 http:
2666                   type: object
2667                   properties:
2668                     enabled:
2669                       type: boolean
2670                 torrent:
2671                   type: object
2672                   properties:
2673                     enabled:
2674                       type: boolean
2675         autoBlacklist:
2676           type: object
2677           properties:
2678             videos:
2679               type: object
2680               properties:
2681                 ofUsers:
2682                   type: object
2683                   properties:
2684                     enabled:
2685                       type: boolean
2686         followers:
2687           type: object
2688           properties:
2689             instance:
2690               type: object
2691               properties:
2692                 enabled:
2693                   type: boolean
2694                 manualApproval:
2695                   type: boolean
2696     Follow:
2697       properties:
2698         id:
2699           type: number
2700         follower:
2701           $ref: '#/components/schemas/Actor'
2702         following:
2703           $ref: '#/components/schemas/Actor'
2704         score:
2705           type: number
2706         state:
2707           type: string
2708           enum:
2709             - pending
2710             - accepted
2711         createdAt:
2712           type: string
2713         updatedAt:
2714           type: string
2715     Job:
2716       properties:
2717         id:
2718           type: number
2719         state:
2720           type: string
2721           enum:
2722             - pending
2723             - processing
2724             - error
2725             - success
2726         category:
2727           type: string
2728           enum:
2729             - transcoding
2730             - activitypub-http
2731         handlerName:
2732           type: string
2733         handlerInputData:
2734           type: string
2735         createdAt:
2736           type: string
2737         updatedAt:
2738           type: string
2739     AddUserResponse:
2740       properties:
2741         id:
2742           type: number
2743         uuid:
2744           type: string
2745     VideoUploadResponse:
2746       properties:
2747         video:
2748           type: object
2749           properties:
2750             id:
2751               type: number
2752             uuid:
2753               type: string
2754     CommentThreadResponse:
2755       properties:
2756         total:
2757           type: number
2758         data:
2759           type: array
2760           items:
2761             $ref: '#/components/schemas/VideoComment'
2762     CommentThreadPostResponse:
2763       properties:
2764         comment:
2765           $ref: '#/components/schemas/VideoComment'
2766     VideoListResponse:
2767       properties:
2768         total:
2769           type: number
2770         data:
2771           type: array
2772           items:
2773             $ref: '#/components/schemas/Video'
2774     AddUser:
2775       properties:
2776         username:
2777           type: string
2778           description: 'The user username '
2779         password:
2780           type: string
2781           description: 'The user password '
2782         email:
2783           type: string
2784           description: 'The user email '
2785         videoQuota:
2786           type: string
2787           description: 'The user videoQuota '
2788         videoQuotaDaily:
2789           type: string
2790           description: 'The user daily video quota '
2791         role:
2792           type: integer
2793           enum:
2794             - 0
2795             - 1
2796             - 2
2797           description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2798       required:
2799         - username
2800         - password
2801         - email
2802         - videoQuota
2803         - videoQuotaDaily
2804         - role
2805     UpdateUser:
2806       properties:
2807         id:
2808           type: string
2809           description: 'The user id '
2810         email:
2811           type: string
2812           description: 'The updated email of the user '
2813         videoQuota:
2814           type: string
2815           description: 'The updated videoQuota of the user '
2816         videoQuotaDaily:
2817           type: string
2818           description: 'The updated daily video quota of the user '
2819         role:
2820           type: integer
2821           enum:
2822             - 0
2823             - 1
2824             - 2
2825           description: 'The user role (Admin = 0, Moderator = 1, User = 2)'
2826       required:
2827         - id
2828         - email
2829         - videoQuota
2830         - videoQuotaDaily
2831         - role
2832     UpdateMe:
2833       properties:
2834         password:
2835           type: string
2836           description: 'Your new password '
2837         email:
2838           type: string
2839           description: 'Your new email '
2840         displayNSFW:
2841           type: string
2842           description: 'Your new displayNSFW '
2843         autoPlayVideo:
2844           type: string
2845           description: 'Your new autoPlayVideo '
2846       required:
2847         - password
2848         - email
2849         - displayNSFW
2850         - autoPlayVideo
2851     GetMeVideoRating:
2852       properties:
2853         id:
2854           type: string
2855           description: 'Id of the video '
2856         rating:
2857           type: number
2858           description: 'Rating of the video '
2859       required:
2860         - id
2861         - rating
2862     VideoRating:
2863       properties:
2864         video:
2865           $ref: '#/components/schemas/Video'
2866         rating:
2867           type: number
2868           description: 'Rating of the video'
2869       required:
2870         - video
2871         - rating
2872     RegisterUser:
2873       properties:
2874         username:
2875           type: string
2876           description: 'The username of the user '
2877         password:
2878           type: string
2879           description: 'The password of the user '
2880         email:
2881           type: string
2882           description: 'The email of the user '
2883         displayName:
2884           type: string
2885           description: 'The user display name'
2886         channel:
2887           type: object
2888           properties:
2889             name:
2890               type: string
2891               description: 'The default channel name'
2892             displayName:
2893               type: string
2894               description: 'The default channel display name'
2895
2896       required:
2897         - username
2898         - password
2899         - email
2900     VideoChannelCreate:
2901       properties:
2902         name:
2903           type: string
2904         displayName:
2905           type: string
2906         description:
2907           type: string
2908         support:
2909           type: string
2910       required:
2911         - name
2912         - displayName
2913     VideoChannelUpdate:
2914       properties:
2915         displayName:
2916           type: string
2917         description:
2918           type: string
2919         support:
2920           type: string
2921         bulkVideosSupportUpdate:
2922           type: boolean
2923           description: 'Update all videos support field of this channel'
2924