support/doc/api/openapi.yaml

   1 openapi: 3.0.0
   2 info:
   3   title: PeerTube
   4   version: 1.1.0-alpha.2
   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.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   - name: Videos
 100     tags:
 101       - Video
 102       - Video Channel
 103       - Video Comment
 104       - Video Abuse
 105       - Video Following
 106       - Video Rate
 107   - name: Moderation
 108     tags:
 109       - Video Blacklist
 110   - name: Public Instance Information
 111     tags:
 112       - Config
 113       - Server Following
 114   - name: Notifications
 115     tags:
 116       - Feeds
 117   - name: Jobs
 118     tags:
 119       - Job
 120   - name: Search
 121     tags:
 122       - Search
 123 paths:
 124   '/accounts/{name}':
 125     get:
 126       tags:
 127         - Accounts
 128       summary: Get the account by name
 129       parameters:
 130         - $ref: '#/components/parameters/name'
 131         - $ref: '#/components/parameters/start'
 132         - $ref: '#/components/parameters/count'
 133         - $ref: '#/components/parameters/sort'
 134       responses:
 135         '200':
 136           description: successful operation
 137           content:
 138             application/json:
 139               schema:
 140                 $ref: '#/components/schemas/Account'
 141   '/accounts/{name}/videos':
 142     get:
 143       tags:
 144         - Accounts
 145         - Video
 146       summary: 'Get videos for an account, provided the name of that account'
 147       parameters:
 148         - $ref: '#/components/parameters/name'
 149       responses:
 150         '200':
 151           description: successful operation
 152           content:
 153             application/json:
 154               schema:
 155                 $ref: '#/components/schemas/Video'
 156       x-code-samples:
 157         - lang: JavaScript
 158           source: |
 159             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
 160             .then(function(response) {
 161               return response.json()
 162             }).then(function(data) {
 163               console.log(data)
 164             })
 165         - lang: Shell
 166           source: |
 167             # pip install httpie
 168             http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
 169         - lang: Ruby
 170           source: |
 171             require 'uri'
 172             require 'net/http'
 173
 174             url = URI("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")
 175
 176             http = Net::HTTP.new(url.host, url.port)
 177             http.use_ssl = true
 178             http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 179
 180             request = Net::HTTP::Post.new(url)
 181             request["content-type"] = 'application/json'
 182             response = http.request(request)
 183             puts response.read_body
 184         - lang: Python
 185           source: |
 186             import http.client
 187
 188             conn = http.client.HTTPSConnection("https://peertube2.cpy.re/api/v1")
 189
 190             headers = {
 191               'content-type': "application/json"
 192             }
 193
 194             conn.request("POST", "/accounts/{name}/videos", None, headers)
 195
 196             res = conn.getresponse()
 197             data = res.read()
 198
 199             print(data.decode("utf-8"))
 200   /accounts:
 201     get:
 202       tags:
 203         - Accounts
 204       summary: Get all accounts
 205       responses:
 206         '200':
 207           description: successful operation
 208           content:
 209             'application/json':
 210               schema:
 211                 type: array
 212                 items:
 213                   $ref: '#/components/schemas/Account'
 214   /config:
 215     get:
 216       tags:
 217         - Config
 218       summary: Get the public configuration of the server
 219       responses:
 220         '200':
 221           description: successful operation
 222           content:
 223             application/json:
 224               schema:
 225                 $ref: '#/components/schemas/ServerConfig'
 226   /config/about:
 227     get:
 228       summary: Get the instance about page content
 229       tags:
 230         - Config
 231       responses:
 232         '200':
 233           description: successful operation
 234   /config/custom:
 235     get:
 236       summary: Get the runtime configuration of the server
 237       tags:
 238         - Config
 239       security:
 240         - OAuth2:
 241             - admin
 242       responses:
 243         '200':
 244           description: successful operation
 245     put:
 246       summary: Set the runtime configuration of the server
 247       tags:
 248         - Config
 249       security:
 250         - OAuth2:
 251             - admin
 252       responses:
 253         '200':
 254           description: successful operation
 255     delete:
 256       summary: Delete the runtime configuration of the server
 257       tags:
 258         - Config
 259       security:
 260         - OAuth2:
 261             - admin
 262       responses:
 263         '200':
 264           description: successful operation
 265   '/feeds/videos.{format}':
 266     get:
 267       summary: >-
 268         Get the feed of videos for the server, with optional filter by account
 269         name or id
 270       tags:
 271         - Feeds
 272       parameters:
 273         - name: format
 274           in: path
 275           required: true
 276           description: >-
 277             The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
 278             json to JSON FEED 1.0
 279           schema:
 280             type: string
 281             enum:
 282               - xml
 283               - atom
 284               - json
 285             default: xml
 286         - name: accountId
 287           in: query
 288           required: false
 289           description: >-
 290             The id of the local account to filter to (beware, users IDs and not
 291             actors IDs which will return empty feeds
 292           schema:
 293             type: number
 294         - name: accountName
 295           in: query
 296           required: false
 297           description: The name of the local account to filter to
 298           schema:
 299             type: string
 300       responses:
 301         '200':
 302           description: successful operation
 303   /jobs:
 304     get:
 305       summary: Get list of jobs
 306       security:
 307         - OAuth2:
 308             - admin
 309       tags:
 310         - Job
 311       parameters:
 312         - name: state
 313           in: path
 314           required: true
 315           description: The state of the job
 316           schema:
 317             type: string
 318         - $ref: '#/components/parameters/start'
 319         - $ref: '#/components/parameters/count'
 320         - $ref: '#/components/parameters/sort'
 321       responses:
 322         '200':
 323           description: successful operation
 324           content:
 325             application/json:
 326               schema:
 327                 type: array
 328                 items:
 329                   $ref: '#/components/schemas/Job'
 330   '/server/following/{host}':
 331     delete:
 332       security:
 333         - OAuth2:
 334             - admin
 335       tags:
 336         - Server Following
 337       summary: Unfollow a server by hostname
 338       parameters:
 339         - name: host
 340           in: path
 341           required: true
 342           description: 'The host to unfollow '
 343           schema:
 344             type: string
 345       responses:
 346         '201':
 347           description: successful operation
 348   /server/followers:
 349     get:
 350       tags:
 351         - Server Following
 352       summary: Get followers of the server
 353       parameters:
 354         - $ref: '#/components/parameters/start'
 355         - $ref: '#/components/parameters/count'
 356         - $ref: '#/components/parameters/sort'
 357       responses:
 358         '200':
 359           description: successful operation
 360           content:
 361             application/json:
 362               schema:
 363                 type: array
 364                 items:
 365                   $ref: '#/components/schemas/Follow'
 366   /server/following:
 367     get:
 368       tags:
 369         - Server Following
 370       summary: Get servers followed by the server
 371       parameters:
 372         - $ref: '#/components/parameters/start'
 373         - $ref: '#/components/parameters/count'
 374         - $ref: '#/components/parameters/sort'
 375       responses:
 376         '200':
 377           description: successful operation
 378           content:
 379             application/json:
 380               schema:
 381                 type: array
 382                 items:
 383                   $ref: '#/components/schemas/Follow'
 384     post:
 385       security:
 386         - OAuth2:
 387             - admin
 388       tags:
 389         - Server Following
 390       summary: Follow a server
 391       responses:
 392         '204':
 393           $ref: '#/paths/~1users~1me/put/responses/204'
 394       requestBody:
 395         content:
 396           application/json:
 397             schema:
 398               $ref: '#/components/schemas/Follow'
 399   /users:
 400     post:
 401       summary: Creates user
 402       security:
 403         - OAuth2:
 404             - admin
 405       tags:
 406         - User
 407       responses:
 408         '200':
 409           description: successful operation
 410           content:
 411             application/json:
 412               schema:
 413                 $ref: '#/components/schemas/AddUserResponse'
 414       requestBody:
 415         content:
 416           application/json:
 417             schema:
 418               $ref: '#/components/schemas/AddUser'
 419         description: User to create
 420         required: true
 421     get:
 422       summary: Get a list of users
 423       security:
 424         - OAuth2: []
 425       tags:
 426         - User
 427       parameters:
 428         - $ref: '#/components/parameters/start'
 429         - $ref: '#/components/parameters/count'
 430         - $ref: '#/components/parameters/sort'
 431       responses:
 432         '200':
 433           description: successful operation
 434           content:
 435             application/json:
 436               schema:
 437                 type: array
 438                 items:
 439                   $ref: '#/components/schemas/User'
 440   '/users/{id}':
 441     delete:
 442       summary: Delete a user by its id
 443       security:
 444         - OAuth2:
 445             - admin
 446       tags:
 447         - User
 448       parameters:
 449         - $ref: '#/components/parameters/id'
 450       responses:
 451         '204':
 452           $ref: '#/paths/~1users~1me/put/responses/204'
 453     get:
 454       summary: Get user by its id
 455       security:
 456         - OAuth2: []
 457       tags:
 458         - User
 459       parameters:
 460         - $ref: '#/components/parameters/id'
 461       responses:
 462         '200':
 463           description: successful operation
 464           content:
 465             application/json:
 466               schema:
 467                 $ref: '#/components/schemas/User'
 468     put:
 469       summary: Update user profile by its id
 470       security:
 471         - OAuth2: []
 472       tags:
 473         - User
 474       parameters:
 475         - $ref: '#/components/parameters/id'
 476       responses:
 477         '204':
 478           $ref: '#/paths/~1users~1me/put/responses/204'
 479       requestBody:
 480         content:
 481           application/json:
 482             schema:
 483               $ref: '#/components/schemas/UpdateUser'
 484         required: true
 485   /users/me:
 486     get:
 487       summary: Get current user information
 488       security:
 489         - OAuth2: []
 490       tags:
 491         - User
 492       responses:
 493         '200':
 494           description: successful operation
 495           content:
 496             application/json:
 497               schema:
 498                 type: array
 499                 items:
 500                   $ref: '#/components/schemas/User'
 501     put:
 502       summary: Update current user information
 503       security:
 504         - OAuth2: []
 505       tags:
 506         - User
 507       responses:
 508         '204':
 509           description: Successful operation
 510       requestBody:
 511         content:
 512           application/json:
 513             schema:
 514               $ref: '#/components/schemas/UpdateMe'
 515         required: true
 516   /users/me/video-quota-used:
 517     get:
 518       summary: Get current user used quota
 519       security:
 520         - OAuth2: []
 521       tags:
 522         - User
 523       responses:
 524         '200':
 525           description: successful operation
 526           content:
 527             application/json:
 528               schema:
 529                 type: number
 530   '/users/me/videos/{videoId}/rating':
 531     get:
 532       summary: 'Get rating of video by its id, among those of the current user'
 533       security:
 534         - OAuth2: []
 535       tags:
 536         - User
 537       parameters:
 538         - name: videoId
 539           in: path
 540           required: true
 541           description: 'The video id '
 542           schema:
 543             type: string
 544       responses:
 545         '200':
 546           description: successful operation
 547           content:
 548             application/json:
 549               schema:
 550                 $ref: '#/components/schemas/GetMeVideoRating'
 551   /users/me/videos:
 552     get:
 553       summary: Get videos of the current user
 554       security:
 555         - OAuth2: []
 556       tags:
 557         - User
 558       parameters:
 559         - $ref: '#/components/parameters/start'
 560         - $ref: '#/components/parameters/count'
 561         - $ref: '#/components/parameters/sort'
 562       responses:
 563         '200':
 564           description: successful operation
 565           content:
 566             application/json:
 567               schema:
 568                 type: array
 569                 items:
 570                   $ref: '#/components/schemas/Video'
 571   /users/register:
 572     post:
 573       summary: Register a user
 574       tags:
 575         - User
 576       responses:
 577         '204':
 578           $ref: '#/paths/~1users~1me/put/responses/204'
 579       requestBody:
 580         content:
 581           application/json:
 582             schema:
 583               $ref: '#/components/schemas/RegisterUser'
 584         required: true
 585   /users/me/avatar/pick:
 586     post:
 587       summary: Update current user avatar
 588       security:
 589         - OAuth2: []
 590       tags:
 591         - User
 592       responses:
 593         '200':
 594           description: successful operation
 595           content:
 596             application/json:
 597               schema:
 598                 $ref: '#/components/schemas/Avatar'
 599       requestBody:
 600         content:
 601           multipart/form-data:
 602             schema:
 603               type: object
 604               properties:
 605                 avatarfile:
 606                   description: The file to upload.
 607                   type: string
 608                   format: binary
 609             encoding:
 610               profileImage:
 611                 # only accept png/jpeg
 612                 contentType: image/png, image/jpeg
 613   /videos:
 614     get:
 615       summary: Get list of videos
 616       tags:
 617         - Video
 618       parameters:
 619         - name: category
 620           in: query
 621           required: false
 622           description: category id of the video
 623           schema:
 624             type: number
 625         - $ref: '#/components/parameters/start'
 626         - $ref: '#/components/parameters/count'
 627         - $ref: '#/components/parameters/sort'
 628       responses:
 629         '200':
 630           description: successful operation
 631           content:
 632             application/json:
 633               schema:
 634                 type: array
 635                 items:
 636                   $ref: '#/components/schemas/Video'
 637   /videos/categories:
 638     get:
 639       summary: Get list of video licences known by the server
 640       tags:
 641         - Video
 642       responses:
 643         '200':
 644           description: successful operation
 645           content:
 646             application/json:
 647               schema:
 648                 type: array
 649                 items:
 650                   type: string
 651   /videos/licences:
 652     get:
 653       summary: Get list of video licences known by the server
 654       tags:
 655         - Video
 656       responses:
 657         '200':
 658           description: successful operation
 659           content:
 660             application/json:
 661               schema:
 662                 type: array
 663                 items:
 664                   type: string
 665   /videos/languages:
 666     get:
 667       summary: Get list of languages known by the server
 668       tags:
 669         - Video
 670       responses:
 671         '200':
 672           description: successful operation
 673           content:
 674             application/json:
 675               schema:
 676                 type: array
 677                 items:
 678                   type: string
 679   /videos/privacies:
 680     get:
 681       summary: Get list of privacy policies supported by the server
 682       tags:
 683         - Video
 684       responses:
 685         '200':
 686           description: successful operation
 687           content:
 688             application/json:
 689               schema:
 690                 type: array
 691                 items:
 692                   type: string
 693   '/videos/{id}':
 694     put:
 695       summary: Update metadata for a video by its id
 696       security:
 697         - OAuth2: []
 698       tags:
 699         - Video
 700       parameters:
 701         - $ref: '#/components/parameters/id2'
 702       responses:
 703         '200':
 704           description: successful operation
 705           content:
 706             application/json:
 707               schema:
 708                 $ref: '#/components/schemas/Video'
 709       requestBody:
 710         content:
 711           multipart/form-data:
 712             schema:
 713               type: object
 714               properties:
 715                 thumbnailfile:
 716                   description: Video thumbnail file
 717                   type: string
 718                 previewfile:
 719                   description: Video preview file
 720                   type: string
 721                 category:
 722                   description: Video category
 723                   type: string
 724                 licence:
 725                   description: Video licence
 726                   type: string
 727                 language:
 728                   description: Video language
 729                   type: string
 730                 description:
 731                   description: Video description
 732                   type: string
 733                 waitTranscoding:
 734                   description: Whether or not we wait transcoding before publish the video
 735                   type: string
 736                 support:
 737                   description: Text describing how to support the video uploader
 738                   type: string
 739                 nsfw:
 740                   description: Whether or not this video contains sensitive content
 741                   type: string
 742                 name:
 743                   description: Video name
 744                   type: string
 745                 tags:
 746                   description: Video tags
 747                   type: string
 748                 commentsEnabled:
 749                   description: Enable or disable comments for this video
 750                   type: string
 751                 scheduleUpdate: &ref_0
 752                   type: object
 753                   properties:
 754                     privacy:
 755                       type: string
 756                       enum:
 757                         - Public
 758                         - Unlisted
 759                       description: Video privacy target
 760                     updateAt:
 761                       type: string
 762                       format: date
 763                       description: When to update the video
 764                   required:
 765                     - updateAt
 766     get:
 767       summary: Get a video by its id
 768       tags:
 769         - Video
 770       parameters:
 771         - $ref: '#/components/parameters/id2'
 772       responses:
 773         '200':
 774           description: successful operation
 775           content:
 776             application/json:
 777               schema:
 778                 $ref: '#/components/schemas/Video'
 779     delete:
 780       summary: Delete a video by its id
 781       security:
 782         - OAuth2: []
 783       tags:
 784         - Video
 785       parameters:
 786         - $ref: '#/components/parameters/id2'
 787       responses:
 788         '204':
 789           $ref: '#/paths/~1users~1me/put/responses/204'
 790   '/videos/{id}/description':
 791     get:
 792       summary: Get a video description by its id
 793       tags:
 794         - Video
 795       parameters:
 796         - $ref: '#/components/parameters/id2'
 797       responses:
 798         '200':
 799           description: successful operation
 800           content:
 801             application/json:
 802               schema:
 803                 type: string
 804   '/videos/{id}/views':
 805     post:
 806       summary: Add a view to the video by its id
 807       tags:
 808         - Video
 809       parameters:
 810         - $ref: '#/components/parameters/id2'
 811       responses:
 812         '204':
 813           $ref: '#/paths/~1users~1me/put/responses/204'
 814   '/videos/{id}/watching':
 815     put:
 816       summary: Indicate progress of in watching the video by its id for a user
 817       tags:
 818         - Video
 819       security:
 820         - OAuth2: []
 821       parameters:
 822         - $ref: '#/components/parameters/id2'
 823       requestBody:
 824         content:
 825           application/json:
 826             schema:
 827               $ref: '#/components/schemas/UserWatchingVideo'
 828         required: true
 829       responses:
 830         '204':
 831           $ref: '#/paths/~1users~1me/put/responses/204'
 832   /videos/ownership:
 833     get:
 834       summary: Get list of video ownership changes requests
 835       tags:
 836         - Video
 837       security:
 838         - OAuth2: []
 839       parameters:
 840         - $ref: '#/components/parameters/id2'
 841       responses:
 842         '200':
 843           description: successful operation
 844   '/videos/ownership/{id}/accept':
 845     post:
 846       summary: Refuse ownership change request for video by its id
 847       tags:
 848         - Video
 849       security:
 850         - OAuth2: []
 851       parameters:
 852         - $ref: '#/components/parameters/id2'
 853       responses:
 854         '204':
 855           $ref: '#/paths/~1users~1me/put/responses/204'
 856   '/videos/ownership/{id}/refuse':
 857     post:
 858       summary: Accept ownership change request for video by its id
 859       tags:
 860         - Video
 861       security:
 862         - OAuth2: []
 863       parameters:
 864         - $ref: '#/components/parameters/id2'
 865       responses:
 866         '204':
 867           $ref: '#/paths/~1users~1me/put/responses/204'
 868   '/videos/{id}/give-ownership':
 869     post:
 870       summary: Request change of ownership for a video you own, by its id
 871       tags:
 872         - Video
 873       security:
 874         - OAuth2: []
 875       parameters:
 876         - $ref: '#/components/parameters/id2'
 877       requestBody:
 878         required: true
 879         content:
 880           application/x-www-form-urlencoded:
 881             schema:
 882               type: object
 883               properties:
 884                 username:
 885                   type: string
 886               required:
 887                 - username
 888       responses:
 889         '204':
 890           $ref: '#/paths/~1users~1me/put/responses/204'
 891         '400':
 892           description: 'Changing video ownership to a remote account is not supported yet'
 893   /videos/upload:
 894     post:
 895       summary: Upload a video file with its metadata
 896       security:
 897         - OAuth2: []
 898       tags:
 899         - Video
 900       responses:
 901         '200':
 902           description: successful operation
 903           content:
 904             application/json:
 905               schema:
 906                 $ref: '#/components/schemas/VideoUploadResponse'
 907       requestBody:
 908         content:
 909           multipart/form-data:
 910             schema:
 911               type: object
 912               properties:
 913                 videofile:
 914                   description: Video file
 915                   type: string
 916                   format: binary
 917                 channelId:
 918                   description: Channel id that will contain this video
 919                   type: number
 920                 thumbnailfile:
 921                   description: Video thumbnail file
 922                   type: string
 923                 previewfile:
 924                   description: Video preview file
 925                   type: string
 926                 privacy:
 927                   $ref: '#/components/schemas/VideoPrivacy'
 928                 category:
 929                   description: Video category
 930                   type: string
 931                 licence:
 932                   description: Video licence
 933                   type: string
 934                 language:
 935                   description: Video language
 936                   type: string
 937                 description:
 938                   description: Video description
 939                   type: string
 940                 waitTranscoding:
 941                   description: Whether or not we wait transcoding before publish the video
 942                   type: string
 943                 support:
 944                   description: Text describing how to support the video uploader
 945                   type: string
 946                 nsfw:
 947                   description: Whether or not this video contains sensitive content
 948                   type: string
 949                 name:
 950                   description: Video name
 951                   type: string
 952                 tags:
 953                   description: Video tags
 954                   type: string
 955                 commentsEnabled:
 956                   description: Enable or disable comments for this video
 957                   type: string
 958                 scheduleUpdate: *ref_0
 959               required:
 960                 - videofile
 961                 - channelId
 962                 - name
 963       x-code-samples:
 964         - lang: Shell
 965           source: |
 966             ## DEPENDENCIES: httpie, jq
 967             # pip install httpie
 968             USERNAME="<your_username>"
 969             PASSWORD="<your_password>"
 970             FILE_PATH="<your_file_path>"
 971             CHANNEL_ID="<your_channel_id>"
 972             NAME="<video_name>"
 973
 974             API_PATH="https://peertube2.cpy.re/api/v1"
 975             ## AUTH
 976             client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
 977             client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
 978             token=$(http -b --form POST "$API_PATH/users/token" \
 979               client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
 980               username=$USERNAME \
 981               password=$PASSWORD \
 982               | jq -r ".access_token")
 983             ## VIDEO UPLOAD
 984             http -b --form POST "$API_PATH/videos/upload" \
 985               videofile@$FILE_PATH \
 986               channelId=$CHANNEL_ID \
 987               name=$NAME \
 988               "Authorization:Bearer $token"
 989   /videos/abuse:
 990     get:
 991       summary: Get list of reported video abuses
 992       security:
 993         - OAuth2: []
 994       tags:
 995         - Video Abuse
 996       parameters:
 997         - $ref: '#/components/parameters/start'
 998         - $ref: '#/components/parameters/count'
 999         - $ref: '#/components/parameters/sort'
1000       responses:
1001         '200':
1002           description: successful operation
1003           content:
1004             application/json:
1005               schema:
1006                 type: array
1007                 items:
1008                   $ref: '#/components/schemas/VideoAbuse'
1009   '/videos/{id}/abuse':
1010     post:
1011       summary: 'Report an abuse, on a video by its id'
1012       security:
1013         - OAuth2: []
1014       tags:
1015         - Video Abuse
1016       parameters:
1017         - $ref: '#/components/parameters/id2'
1018       responses:
1019         '204':
1020           $ref: '#/paths/~1users~1me/put/responses/204'
1021   '/videos/{id}/blacklist':
1022     post:
1023       summary: Put on blacklist a video by its id
1024       security:
1025         - OAuth2:
1026             - admin
1027             - moderator
1028       tags:
1029         - Video Blacklist
1030       parameters:
1031         - $ref: '#/components/parameters/id2'
1032       responses:
1033         '204':
1034           $ref: '#/paths/~1users~1me/put/responses/204'
1035     delete:
1036       summary: Delete an entry of the blacklist of a video by its id
1037       security:
1038         - OAuth2:
1039             - admin
1040             - moderator
1041       tags:
1042         - Video Blacklist
1043       parameters:
1044         - $ref: '#/components/parameters/id2'
1045       responses:
1046         '204':
1047           $ref: '#/paths/~1users~1me/put/responses/204'
1048   /videos/blacklist:
1049     get:
1050       summary: Get list of videos on blacklist
1051       security:
1052         - OAuth2:
1053             - admin
1054             - moderator
1055       tags:
1056         - Video Blacklist
1057       parameters:
1058         - $ref: '#/components/parameters/start'
1059         - $ref: '#/components/parameters/count'
1060         - $ref: '#/components/parameters/sort'
1061       responses:
1062         '200':
1063           description: successful operation
1064           content:
1065             application/json:
1066               schema:
1067                 type: array
1068                 items:
1069                   $ref: '#/components/schemas/VideoBlacklist'
1070   /video-channels:
1071     get:
1072       summary: Get list of video channels
1073       tags:
1074         - Video Channel
1075       parameters:
1076         - $ref: '#/components/parameters/start'
1077         - $ref: '#/components/parameters/count'
1078         - $ref: '#/components/parameters/sort'
1079       responses:
1080         '200':
1081           description: successful operation
1082           content:
1083             application/json:
1084               schema:
1085                 type: array
1086                 items:
1087                   $ref: '#/components/schemas/VideoChannel'
1088     post:
1089       summary: Creates a video channel for the current user
1090       security:
1091         - OAuth2: []
1092       tags:
1093         - Video Channel
1094       responses:
1095         '204':
1096           $ref: '#/paths/~1users~1me/put/responses/204'
1097       requestBody:
1098         $ref: '#/components/requestBodies/VideoChannelInput'
1099   '/video-channels/{id}':
1100     get:
1101       summary: Get a video channel by its id
1102       tags:
1103         - Video Channel
1104       parameters:
1105         - $ref: '#/components/parameters/id3'
1106       responses:
1107         '200':
1108           description: successful operation
1109           content:
1110             application/json:
1111               schema:
1112                 $ref: '#/components/schemas/VideoChannel'
1113     put:
1114       summary: Update a video channel by its id
1115       security:
1116         - OAuth2: []
1117       tags:
1118         - Video Channel
1119       parameters:
1120         - $ref: '#/components/parameters/id3'
1121       responses:
1122         '204':
1123           $ref: '#/paths/~1users~1me/put/responses/204'
1124       requestBody:
1125         $ref: '#/components/requestBodies/VideoChannelInput'
1126     delete:
1127       summary: Delete a video channel by its id
1128       security:
1129         - OAuth2: []
1130       tags:
1131         - Video Channel
1132       parameters:
1133         - $ref: '#/components/parameters/id3'
1134       responses:
1135         '204':
1136           $ref: '#/paths/~1users~1me/put/responses/204'
1137   '/video-channels/{id}/videos':
1138     get:
1139       summary: Get videos of a video channel by its id
1140       tags:
1141         - Video Channel
1142       parameters:
1143         - $ref: '#/components/parameters/id3'
1144       responses:
1145         '200':
1146           description: successful operation
1147           content:
1148             application/json:
1149               schema:
1150                 $ref: '#/components/schemas/Video'
1151   '/accounts/{name}/video-channels':
1152     get:
1153       summary: Get video channels of an account by its name
1154       tags:
1155         - Video Channel
1156       parameters:
1157         - $ref: '#/components/parameters/name'
1158       responses:
1159         '200':
1160           description: successful operation
1161           content:
1162             application/json:
1163               schema:
1164                 type: array
1165                 items:
1166                   $ref: '#/components/schemas/VideoChannel'
1167   '/videos/{id}/comment-threads':
1168     get:
1169       summary: Get the comment threads of a video by its id
1170       tags:
1171         - Video Comment
1172       parameters:
1173         - $ref: '#/components/parameters/id2'
1174         - $ref: '#/components/parameters/start'
1175         - $ref: '#/components/parameters/count'
1176         - $ref: '#/components/parameters/sort'
1177       responses:
1178         '200':
1179           description: successful operation
1180           content:
1181             application/json:
1182               schema:
1183                 $ref: '#/components/schemas/CommentThreadResponse'
1184     post:
1185       summary: 'Creates a comment thread, on a video by its id'
1186       security:
1187         - OAuth2: []
1188       tags:
1189         - Video Comment
1190       parameters:
1191         - $ref: '#/components/parameters/id2'
1192       responses:
1193         '200':
1194           description: successful operation
1195           content:
1196             application/json:
1197               schema:
1198                 $ref: '#/components/schemas/CommentThreadPostResponse'
1199   '/videos/{id}/comment-threads/{threadId}':
1200     get:
1201       summary: 'Get the comment thread by its id, of a video by its id'
1202       tags:
1203         - Video Comment
1204       parameters:
1205         - $ref: '#/components/parameters/id2'
1206         - name: threadId
1207           in: path
1208           required: true
1209           description: The thread id (root comment id)
1210           schema:
1211             type: number
1212       responses:
1213         '200':
1214           description: successful operation
1215           content:
1216             application/json:
1217               schema:
1218                 $ref: '#/components/schemas/VideoCommentThreadTree'
1219   '/videos/{id}/comments/{commentId}':
1220     post:
1221       summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1222       security:
1223         - OAuth2: []
1224       tags:
1225         - Video Comment
1226       parameters:
1227         - $ref: '#/components/parameters/id2'
1228         - $ref: '#/components/parameters/commentId'
1229       responses:
1230         '200':
1231           description: successful operation
1232           content:
1233             application/json:
1234               schema:
1235                 $ref: '#/components/schemas/CommentThreadPostResponse'
1236     delete:
1237       summary: 'Delete a comment in a comment therad by its id, of a video by its id'
1238       security:
1239         - OAuth2: []
1240       tags:
1241         - Video Comment
1242       parameters:
1243         - $ref: '#/components/parameters/id2'
1244         - $ref: '#/components/parameters/commentId'
1245       responses:
1246         '204':
1247           $ref: '#/paths/~1users~1me/put/responses/204'
1248   '/videos/{id}/rate':
1249     put:
1250       summary: Vote for a video by its id
1251       security:
1252         - OAuth2: []
1253       tags:
1254         - Video Rate
1255       parameters:
1256         - $ref: '#/components/parameters/id2'
1257       responses:
1258         '204':
1259           $ref: '#/paths/~1users~1me/put/responses/204'
1260   /search/videos:
1261     get:
1262       tags:
1263         - Search
1264       summary: Get the videos corresponding to a given query
1265       parameters:
1266         - $ref: '#/components/parameters/start'
1267         - $ref: '#/components/parameters/count'
1268         - $ref: '#/components/parameters/sort'
1269         - name: search
1270           in: query
1271           required: true
1272           description: String to search
1273           schema:
1274             type: string
1275       responses:
1276         '200':
1277           description: successful operation
1278           content:
1279             application/json:
1280               schema:
1281                 type: array
1282                 items:
1283                   $ref: '#/components/schemas/Video'
1284 servers:
1285   - url: 'https://peertube.cpy.re/api/v1'
1286     description: Live Test Server (live data - stable version)
1287   - url: 'https://peertube2.cpy.re/api/v1'
1288     description: Live Test Server (live data - bleeding edge version)
1289   - url: 'https://peertube3.cpy.re/api/v1'
1290     description: Live Test Server (live data - bleeding edge version)
1291 components:
1292   parameters:
1293     start:
1294       name: start
1295       in: query
1296       required: false
1297       description: Offset
1298       schema:
1299         type: number
1300     count:
1301       name: count
1302       in: query
1303       required: false
1304       description: Number of items
1305       schema:
1306         type: number
1307     sort:
1308       name: sort
1309       in: query
1310       required: false
1311       description: Sort column (-createdAt for example)
1312       schema:
1313         type: string
1314     name:
1315       name: name
1316       in: path
1317       required: true
1318       description: >-
1319         The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1320         example)
1321       schema:
1322         type: string
1323     id:
1324       name: id
1325       in: path
1326       required: true
1327       description: The user id
1328       schema:
1329         type: number
1330     id2:
1331       name: id
1332       in: path
1333       required: true
1334       description: The video id or uuid
1335       schema:
1336         type: string
1337     id3:
1338       name: id
1339       in: path
1340       required: true
1341       description: The video channel id or uuid
1342       schema:
1343         type: string
1344     commentId:
1345       name: threadId
1346       in: path
1347       required: true
1348       description: The comment id
1349       schema:
1350         type: number
1351   requestBodies:
1352     VideoChannelInput:
1353       content:
1354         application/json:
1355           schema:
1356             $ref: '#/components/schemas/VideoChannelInput'
1357   securitySchemes:
1358     OAuth2:
1359       description: >
1360         In the header: *Authorization: Bearer <token\>*
1361
1362
1363         Authenticating via OAuth requires the following steps:
1364
1365
1366         - Have an account with sufficient authorization levels
1367
1368         - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
1369         Bearer Token
1370
1371         - Make Authenticated Requests
1372       type: oauth2
1373       flows:
1374         password:
1375           tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1376           scopes:
1377             admin: Admin scope
1378             moderator: Moderator scope
1379             user: User scope
1380   schemas:
1381     VideoConstantNumber:
1382       properties:
1383         id:
1384           type: number
1385         label:
1386           type: string
1387     VideoConstantString:
1388       properties:
1389         id:
1390           type: string
1391         label:
1392           type: string
1393     VideoPrivacy:
1394       type: string
1395       enum:
1396         - Public
1397         - Unlisted
1398         - Private
1399     Video:
1400       properties:
1401         id:
1402           type: number
1403         uuid:
1404           type: string
1405         createdAt:
1406           type: string
1407         publishedAt:
1408           type: string
1409         updatedAt:
1410           type: string
1411         category:
1412           $ref: '#/components/schemas/VideoConstantNumber'
1413         licence:
1414           $ref: '#/components/schemas/VideoConstantNumber'
1415         language:
1416           $ref: '#/components/schemas/VideoConstantString'
1417         privacy:
1418           $ref: '#/components/schemas/VideoPrivacy'
1419         description:
1420           type: string
1421         duration:
1422           type: number
1423         isLocal:
1424           type: boolean
1425         name:
1426           type: string
1427         thumbnailPath:
1428           type: string
1429         previewPath:
1430           type: string
1431         embedPath:
1432           type: string
1433         views:
1434           type: number
1435         likes:
1436           type: number
1437         dislikes:
1438           type: number
1439         nsfw:
1440           type: boolean
1441         account:
1442           type: object
1443           properties:
1444             name:
1445               type: string
1446             displayName:
1447               type: string
1448             url:
1449               type: string
1450             host:
1451               type: string
1452             avatar:
1453               $ref: '#/components/schemas/Avatar'
1454     VideoAbuse:
1455       properties:
1456         id:
1457           type: number
1458         reason:
1459           type: string
1460         reporterAccount:
1461           $ref: '#/components/schemas/Account'
1462         video:
1463           type: object
1464           properties:
1465             id:
1466               type: number
1467             name:
1468               type: string
1469             uuid:
1470               type: string
1471             url:
1472               type: string
1473         createdAt:
1474           type: string
1475     VideoBlacklist:
1476       properties:
1477         id:
1478           type: number
1479         videoId:
1480           type: number
1481         createdAt:
1482           type: string
1483         updatedAt:
1484           type: string
1485         name:
1486           type: string
1487         uuid:
1488           type: string
1489         description:
1490           type: string
1491         duration:
1492           type: number
1493         views:
1494           type: number
1495         likes:
1496           type: number
1497         dislikes:
1498           type: number
1499         nsfw:
1500           type: boolean
1501     VideoChannel:
1502       properties:
1503         displayName:
1504           type: string
1505         description:
1506           type: string
1507         isLocal:
1508           type: boolean
1509         ownerAccount:
1510           type: object
1511           properties:
1512             id:
1513               type: number
1514             uuid:
1515               type: string
1516     VideoComment:
1517       properties:
1518         id:
1519           type: number
1520         url:
1521           type: string
1522         text:
1523           type: string
1524         threadId:
1525           type: number
1526         inReplyToCommentId:
1527           type: number
1528         videoId:
1529           type: number
1530         createdAt:
1531           type: string
1532         updatedAt:
1533           type: string
1534         totalReplies:
1535           type: number
1536         account:
1537           $ref: '#/components/schemas/Account'
1538     VideoCommentThreadTree:
1539       properties:
1540         comment:
1541           $ref: '#/components/schemas/VideoComment'
1542         children:
1543           type: array
1544           items:
1545             $ref: '#/components/schemas/VideoCommentThreadTree'
1546     Avatar:
1547       properties:
1548         path:
1549           type: string
1550         createdAt:
1551           type: string
1552         updatedAt:
1553           type: string
1554     Actor:
1555       properties:
1556         id:
1557           type: number
1558         uuid:
1559           type: string
1560         url:
1561           type: string
1562         name:
1563           type: string
1564         host:
1565           type: string
1566         followingCount:
1567           type: number
1568         followersCount:
1569           type: number
1570         createdAt:
1571           type: string
1572         updatedAt:
1573           type: string
1574         avatar:
1575           $ref: '#/components/schemas/Avatar'
1576     Account:
1577       allOf:
1578         - $ref: '#/components/schemas/Actor'
1579         - properties:
1580             displayName:
1581               type: string
1582     User:
1583       properties:
1584         id:
1585           type: number
1586         username:
1587           type: string
1588         email:
1589           type: string
1590         displayNSFW:
1591           type: boolean
1592         autoPlayVideo:
1593           type: boolean
1594         role:
1595           type: string
1596           enum:
1597             - User
1598             - Moderator
1599             - Administrator
1600         videoQuota:
1601           type: number
1602         createdAt:
1603           type: string
1604         account:
1605           $ref: '#/components/schemas/Account'
1606         videoChannels:
1607           type: array
1608           items:
1609             $ref: '#/components/schemas/VideoChannel'
1610     UserWatchingVideo:
1611       properties:
1612         currentTime:
1613           type: number
1614     ServerConfig:
1615       properties:
1616         signup:
1617           type: object
1618           properties:
1619             allowed:
1620               type: boolean
1621         transcoding:
1622           type: object
1623           properties:
1624             enabledResolutions:
1625               type: array
1626               items:
1627                 type: number
1628         avatar:
1629           type: object
1630           properties:
1631             file:
1632               type: object
1633               properties:
1634                 size:
1635                   type: object
1636                   properties:
1637                     max:
1638                       type: number
1639             extensions:
1640               type: array
1641               items:
1642                 type: string
1643         video:
1644           type: object
1645           properties:
1646             file:
1647               type: object
1648               properties:
1649                 extensions:
1650                   type: array
1651                   items:
1652                     type: string
1653     Follow:
1654       properties:
1655         id:
1656           type: number
1657         follower:
1658           $ref: '#/components/schemas/Actor'
1659         following:
1660           $ref: '#/components/schemas/Actor'
1661         score:
1662           type: number
1663         state:
1664           type: string
1665           enum:
1666             - pending
1667             - accepted
1668         createdAt:
1669           type: string
1670         updatedAt:
1671           type: string
1672     Job:
1673       properties:
1674         id:
1675           type: number
1676         state:
1677           type: string
1678           enum:
1679             - pending
1680             - processing
1681             - error
1682             - success
1683         category:
1684           type: string
1685           enum:
1686             - transcoding
1687             - activitypub-http
1688         handlerName:
1689           type: string
1690         handlerInputData:
1691           type: string
1692         createdAt:
1693           type: string
1694         updatedAt:
1695           type: string
1696     AddUserResponse:
1697       properties:
1698         id:
1699           type: number
1700         uuid:
1701           type: string
1702     VideoUploadResponse:
1703       properties:
1704         video:
1705           type: object
1706           properties:
1707             id:
1708               type: number
1709             uuid:
1710               type: string
1711     CommentThreadResponse:
1712       properties:
1713         total:
1714           type: number
1715         data:
1716           type: array
1717           items:
1718             $ref: '#/components/schemas/VideoComment'
1719     CommentThreadPostResponse:
1720       properties:
1721         comment:
1722           $ref: '#/components/schemas/VideoComment'
1723     AddUser:
1724       properties:
1725         username:
1726           type: string
1727           description: 'The user username '
1728         password:
1729           type: string
1730           description: 'The user password '
1731         email:
1732           type: string
1733           description: 'The user email '
1734         videoQuota:
1735           type: string
1736           description: 'The user videoQuota '
1737         role:
1738           type: string
1739           description: 'The user role '
1740       required:
1741         - username
1742         - password
1743         - email
1744         - videoQuota
1745         - role
1746     UpdateUser:
1747       properties:
1748         id:
1749           type: string
1750           description: 'The user id '
1751         email:
1752           type: string
1753           description: 'The updated email of the user '
1754         videoQuota:
1755           type: string
1756           description: 'The updated videoQuota of the user '
1757         role:
1758           type: string
1759           description: 'The updated role of the user '
1760       required:
1761         - id
1762         - email
1763         - videoQuota
1764         - role
1765     UpdateMe:
1766       properties:
1767         password:
1768           type: string
1769           description: 'Your new password '
1770         email:
1771           type: string
1772           description: 'Your new email '
1773         displayNSFW:
1774           type: string
1775           description: 'Your new displayNSFW '
1776         autoPlayVideo:
1777           type: string
1778           description: 'Your new autoPlayVideo '
1779       required:
1780         - password
1781         - email
1782         - displayNSFW
1783         - autoPlayVideo
1784     GetMeVideoRating:
1785       properties:
1786         id:
1787           type: string
1788           description: 'Id of the video '
1789         rating:
1790           type: number
1791           description: 'Rating of the video '
1792       required:
1793         - id
1794         - rating
1795     RegisterUser:
1796       properties:
1797         username:
1798           type: string
1799           description: 'The username of the user '
1800         password:
1801           type: string
1802           description: 'The password of the user '
1803         email:
1804           type: string
1805           description: 'The email of the user '
1806       required:
1807         - username
1808         - password
1809         - email
1810     VideoChannelInput:
1811       properties:
1812         name:
1813           type: string
1814         description:
1815           type: string
1816