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