support/doc/api/openapi.yaml

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