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   description: |
  14     # Introduction
  15     The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
  16     resource URLs. It returns HTTP response codes to indicate errors. It also
  17     accepts and returns JSON in the HTTP body. You can use your favorite
  18     HTTP/REST library for your programming language to use PeerTube. No official
  19     SDK is currently provided.
  20
  21     # Authentication
  22     When you sign up for an account, you are given the possibility to generate
  23     sessions, and authenticate using this session token. One session token can
  24     currently be used at a time.
  25 tags:
  26   - name: Accounts
  27     description: >
  28       Using some features of PeerTube require authentication, for which Accounts
  29
  30       provide different levels of permission as well as associated user
  31       information.
  32
  33       Accounts also encompass remote accounts discovered across the federation.
  34   - name: Config
  35     description: >
  36       Each server exposes public information regarding supported videos and
  37       options.
  38   - name: Feeds
  39     description: |
  40       Feeds of videos and feeds of comments allow to see updates and get them in
  41       an aggregator or script of your choice.
  42   - name: Job
  43     description: >
  44       Jobs are long-running tasks enqueued and processed by the instance
  45       itself.
  46
  47       No additional worker registration is currently available.
  48   - name: ServerFollowing
  49     description: >
  50       Managing servers which the instance interacts with is crucial to the
  51       concept
  52
  53       of federation in PeerTube and external video indexation. The PeerTube
  54       server
  55
  56       then deals with inter-server ActivityPub operations and propagates
  57
  58       information across its social graph by posting activities to actors' inbox
  59
  60       endpoints.
  61   - name: VideoAbuse
  62     description: |
  63       Video abuses deal with reports of local or remote videos alike.
  64   - name: Video
  65     description: |
  66       Operations dealing with listing, uploading, fetching or modifying videos.
  67   - name: Search
  68     description: |
  69       The search helps to find _videos_ from within the instance and beyond.
  70       Videos from other instances federated by the instance (that is, instances
  71       followed by the instance) can be found via keywords and other criteria of
  72       the advanced search.
  73   - name: VideoComment
  74     description: >
  75       Operations dealing with comments to a video. Comments are organized in
  76       threads.
  77   - name: VideoChannel
  78     description: >
  79       Operations dealing with creation, modification and video listing of a
  80       user's
  81
  82       channels.
  83 paths:
  84   '/accounts/{name}':
  85     get:
  86       tags:
  87         - Accounts
  88       summary: Get the account by name
  89       parameters:
  90         - $ref: '#/components/parameters/name'
  91         - $ref: '#/components/parameters/start'
  92         - $ref: '#/components/parameters/count'
  93         - $ref: '#/components/parameters/sort'
  94       responses:
  95         '200':
  96           description: successful operation
  97           content:
  98             application/json:
  99               schema:
 100                 $ref: '#/components/schemas/Account'
 101   '/accounts/{name}/videos':
 102     get:
 103       tags:
 104         - Accounts
 105         - Video
 106       summary: 'Get videos for an account, provided the name of that account'
 107       parameters:
 108         - $ref: '#/components/parameters/name'
 109       responses:
 110         '200':
 111           description: successful operation
 112           content:
 113             application/json:
 114               schema:
 115                 $ref: '#/components/schemas/Video'
 116       x-code-samples:
 117         - lang: JavaScript
 118           source: |
 119             fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
 120             .then(function(response) {
 121               return response.json()
 122             }).then(function(data) {
 123               console.log(data)
 124             })
 125         - lang: Shell
 126           source: |
 127             # pip install httpie
 128             http -b GET https://peertube2.cpy.re/api/v1/accounts/{name}/videos
 129   /accounts:
 130     get:
 131       tags:
 132         - Accounts
 133       summary: Get all accounts
 134       responses:
 135         '200':
 136           description: successful operation
 137           content:
 138             'application/json':
 139               schema:
 140                 type: array
 141                 items:
 142                   $ref: '#/components/schemas/Account'
 143   /config:
 144     get:
 145       tags:
 146         - Config
 147       summary: Get the configuration of the server
 148       responses:
 149         '200':
 150           description: successful operation
 151           content:
 152             application/json:
 153               schema:
 154                 $ref: '#/components/schemas/ServerConfig'
 155   '/feeds/videos.{format}':
 156     get:
 157       summary: >-
 158         Get the feed of videos for the server, with optional filter by account
 159         name or id
 160       tags:
 161         - Feeds
 162       parameters:
 163         - name: format
 164           in: path
 165           required: true
 166           description: >-
 167             The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and
 168             json to JSON FEED 1.0
 169           schema:
 170             type: string
 171             enum:
 172               - xml
 173               - atom
 174               - json
 175             default: xml
 176         - name: accountId
 177           in: query
 178           required: false
 179           description: >-
 180             The id of the local account to filter to (beware, users IDs and not
 181             actors IDs which will return empty feeds
 182           schema:
 183             type: number
 184         - name: accountName
 185           in: query
 186           required: false
 187           description: The name of the local account to filter to
 188           schema:
 189             type: string
 190       responses:
 191         '200':
 192           description: successful operation
 193   /jobs:
 194     get:
 195       summary: Get list of jobs
 196       security:
 197         - OAuth2:
 198             - admin
 199       tags:
 200         - Job
 201       parameters:
 202         - name: state
 203           in: path
 204           required: true
 205           description: The state of the job
 206           schema:
 207             type: string
 208         - $ref: '#/components/parameters/start'
 209         - $ref: '#/components/parameters/count'
 210         - $ref: '#/components/parameters/sort'
 211       responses:
 212         '200':
 213           description: successful operation
 214           content:
 215             application/json:
 216               schema:
 217                 type: array
 218                 items:
 219                   $ref: '#/components/schemas/Job'
 220   '/server/following/{host}':
 221     delete:
 222       security:
 223         - OAuth2:
 224             - admin
 225       tags:
 226         - ServerFollowing
 227       summary: Unfollow a server by hostname
 228       parameters:
 229         - name: host
 230           in: path
 231           required: true
 232           description: 'The host to unfollow '
 233           schema:
 234             type: string
 235       responses:
 236         '201':
 237           description: successful operation
 238   /server/followers:
 239     get:
 240       tags:
 241         - ServerFollowing
 242       summary: Get followers of the server
 243       parameters:
 244         - $ref: '#/components/parameters/start'
 245         - $ref: '#/components/parameters/count'
 246         - $ref: '#/components/parameters/sort'
 247       responses:
 248         '200':
 249           description: successful operation
 250           content:
 251             application/json:
 252               schema:
 253                 type: array
 254                 items:
 255                   $ref: '#/components/schemas/Follow'
 256   /server/following:
 257     get:
 258       tags:
 259         - ServerFollowing
 260       summary: Get servers followed by the server
 261       parameters:
 262         - $ref: '#/components/parameters/start'
 263         - $ref: '#/components/parameters/count'
 264         - $ref: '#/components/parameters/sort'
 265       responses:
 266         '200':
 267           description: successful operation
 268           content:
 269             application/json:
 270               schema:
 271                 type: array
 272                 items:
 273                   $ref: '#/components/schemas/Follow'
 274     post:
 275       security:
 276         - OAuth2:
 277             - admin
 278       tags:
 279         - ServerFollowing
 280       summary: Follow a server
 281       responses:
 282         '204':
 283           $ref: '#/paths/~1users~1me/put/responses/204'
 284       requestBody:
 285         content:
 286           application/json:
 287             schema:
 288               $ref: '#/components/schemas/Follow'
 289   /users:
 290     post:
 291       summary: Creates user
 292       security:
 293         - OAuth2:
 294             - admin
 295       tags:
 296         - User
 297       responses:
 298         '200':
 299           description: successful operation
 300           content:
 301             application/json:
 302               schema:
 303                 $ref: '#/components/schemas/AddUserResponse'
 304       requestBody:
 305         content:
 306           application/json:
 307             schema:
 308               $ref: '#/components/schemas/AddUser'
 309         description: User to create
 310         required: true
 311     get:
 312       summary: Get a list of users
 313       security:
 314         - OAuth2: []
 315       tags:
 316         - User
 317       parameters:
 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/User'
 330   '/users/{id}':
 331     delete:
 332       summary: Delete a user by its id
 333       security:
 334         - OAuth2:
 335             - admin
 336       tags:
 337         - User
 338       parameters:
 339         - $ref: '#/components/parameters/id'
 340       responses:
 341         '204':
 342           $ref: '#/paths/~1users~1me/put/responses/204'
 343     get:
 344       summary: Get user by its id
 345       security:
 346         - OAuth2: []
 347       tags:
 348         - User
 349       parameters:
 350         - $ref: '#/components/parameters/id'
 351       responses:
 352         '200':
 353           description: successful operation
 354           content:
 355             application/json:
 356               schema:
 357                 $ref: '#/components/schemas/User'
 358     put:
 359       summary: Update user profile by its id
 360       security:
 361         - OAuth2: []
 362       tags:
 363         - User
 364       parameters:
 365         - $ref: '#/components/parameters/id'
 366       responses:
 367         '204':
 368           $ref: '#/paths/~1users~1me/put/responses/204'
 369       requestBody:
 370         content:
 371           application/json:
 372             schema:
 373               $ref: '#/components/schemas/UpdateUser'
 374         required: true
 375   /users/me:
 376     get:
 377       summary: Get current user information
 378       security:
 379         - OAuth2: []
 380       tags:
 381         - User
 382       responses:
 383         '200':
 384           description: successful operation
 385           content:
 386             application/json:
 387               schema:
 388                 type: array
 389                 items:
 390                   $ref: '#/components/schemas/User'
 391     put:
 392       summary: Update current user information
 393       security:
 394         - OAuth2: []
 395       tags:
 396         - User
 397       responses:
 398         '204':
 399           description: Successful operation
 400       requestBody:
 401         content:
 402           application/json:
 403             schema:
 404               $ref: '#/components/schemas/UpdateMe'
 405         required: true
 406   /users/me/video-quota-used:
 407     get:
 408       summary: Get current user used quota
 409       security:
 410         - OAuth2: []
 411       tags:
 412         - User
 413       responses:
 414         '200':
 415           description: successful operation
 416           content:
 417             application/json:
 418               schema:
 419                 type: number
 420   '/users/me/videos/{videoId}/rating':
 421     get:
 422       summary: 'Get rating of video by its id, among those of the current user'
 423       security:
 424         - OAuth2: []
 425       tags:
 426         - User
 427       parameters:
 428         - name: videoId
 429           in: path
 430           required: true
 431           description: 'The video id '
 432           schema:
 433             type: string
 434       responses:
 435         '200':
 436           description: successful operation
 437           content:
 438             application/json:
 439               schema:
 440                 $ref: '#/components/schemas/GetMeVideoRating'
 441   /users/me/videos:
 442     get:
 443       summary: Get videos of the current user
 444       security:
 445         - OAuth2: []
 446       tags:
 447         - User
 448       parameters:
 449         - $ref: '#/components/parameters/start'
 450         - $ref: '#/components/parameters/count'
 451         - $ref: '#/components/parameters/sort'
 452       responses:
 453         '200':
 454           description: successful operation
 455           content:
 456             application/json:
 457               schema:
 458                 type: array
 459                 items:
 460                   $ref: '#/components/schemas/Video'
 461   /users/register:
 462     post:
 463       summary: Register a user
 464       tags:
 465         - User
 466       responses:
 467         '204':
 468           $ref: '#/paths/~1users~1me/put/responses/204'
 469       requestBody:
 470         content:
 471           application/json:
 472             schema:
 473               $ref: '#/components/schemas/RegisterUser'
 474         required: true
 475   /users/me/avatar/pick:
 476     post:
 477       summary: Update current user avatar
 478       security:
 479         - OAuth2: []
 480       tags:
 481         - User
 482       responses:
 483         '200':
 484           description: successful operation
 485           content:
 486             application/json:
 487               schema:
 488                 $ref: '#/components/schemas/Avatar'
 489       requestBody:
 490         content:
 491           multipart/form-data:
 492             schema:
 493               type: object
 494               properties:
 495                 avatarfile:
 496                   description: The file to upload.
 497                   type: string
 498                   format: binary
 499             encoding:
 500               profileImage:
 501                 # only accept png/jpeg
 502                 contentType: image/png, image/jpeg
 503   /videos:
 504     get:
 505       summary: Get list of videos
 506       tags:
 507         - Video
 508       parameters:
 509         - name: category
 510           in: query
 511           required: false
 512           description: category id of the video
 513           schema:
 514             type: number
 515         - $ref: '#/components/parameters/start'
 516         - $ref: '#/components/parameters/count'
 517         - $ref: '#/components/parameters/sort'
 518       responses:
 519         '200':
 520           description: successful operation
 521           content:
 522             application/json:
 523               schema:
 524                 type: array
 525                 items:
 526                   $ref: '#/components/schemas/Video'
 527   /videos/categories:
 528     get:
 529       summary: Get list of video licences known by the server
 530       tags:
 531         - Video
 532       responses:
 533         '200':
 534           description: successful operation
 535           content:
 536             application/json:
 537               schema:
 538                 type: array
 539                 items:
 540                   type: string
 541   /videos/licences:
 542     get:
 543       summary: Get list of video licences known by the server
 544       tags:
 545         - Video
 546       responses:
 547         '200':
 548           description: successful operation
 549           content:
 550             application/json:
 551               schema:
 552                 type: array
 553                 items:
 554                   type: string
 555   /videos/languages:
 556     get:
 557       summary: Get list of languages known by the server
 558       tags:
 559         - Video
 560       responses:
 561         '200':
 562           description: successful operation
 563           content:
 564             application/json:
 565               schema:
 566                 type: array
 567                 items:
 568                   type: string
 569   /videos/privacies:
 570     get:
 571       summary: Get list of privacy policies supported by the server
 572       tags:
 573         - Video
 574       responses:
 575         '200':
 576           description: successful operation
 577           content:
 578             application/json:
 579               schema:
 580                 type: array
 581                 items:
 582                   type: string
 583   '/videos/{id}':
 584     put:
 585       summary: Update metadata for a video by its id
 586       security:
 587         - OAuth2: []
 588       tags:
 589         - Video
 590       parameters:
 591         - $ref: '#/components/parameters/id2'
 592       responses:
 593         '200':
 594           description: successful operation
 595           content:
 596             application/json:
 597               schema:
 598                 $ref: '#/components/schemas/Video'
 599       requestBody:
 600         content:
 601           multipart/form-data:
 602             schema:
 603               type: object
 604               properties:
 605                 thumbnailfile:
 606                   description: Video thumbnail file
 607                   type: string
 608                 previewfile:
 609                   description: Video preview file
 610                   type: string
 611                 category:
 612                   description: Video category
 613                   type: string
 614                 licence:
 615                   description: Video licence
 616                   type: string
 617                 language:
 618                   description: Video language
 619                   type: string
 620                 description:
 621                   description: Video description
 622                   type: string
 623                 waitTranscoding:
 624                   description: Whether or not we wait transcoding before publish the video
 625                   type: string
 626                 support:
 627                   description: Text describing how to support the video uploader
 628                   type: string
 629                 nsfw:
 630                   description: Whether or not this video contains sensitive content
 631                   type: string
 632                 name:
 633                   description: Video name
 634                   type: string
 635                 tags:
 636                   description: Video tags
 637                   type: string
 638                 commentsEnabled:
 639                   description: Enable or disable comments for this video
 640                   type: string
 641                 scheduleUpdate: &ref_0
 642                   type: object
 643                   properties:
 644                     privacy:
 645                       type: string
 646                       enum:
 647                         - Public
 648                         - Unlisted
 649                       description: Video privacy target
 650                     updateAt:
 651                       type: string
 652                       format: date
 653                       description: When to update the video
 654                   required:
 655                     - updateAt
 656     get:
 657       summary: Get a video by its id
 658       tags:
 659         - Video
 660       parameters:
 661         - $ref: '#/components/parameters/id2'
 662       responses:
 663         '200':
 664           description: successful operation
 665           content:
 666             application/json:
 667               schema:
 668                 $ref: '#/components/schemas/Video'
 669     delete:
 670       summary: Delete a video by its id
 671       security:
 672         - OAuth2: []
 673       tags:
 674         - Video
 675       parameters:
 676         - $ref: '#/components/parameters/id2'
 677       responses:
 678         '204':
 679           $ref: '#/paths/~1users~1me/put/responses/204'
 680   '/videos/{id}/description':
 681     get:
 682       summary: Get a video description by its id
 683       tags:
 684         - Video
 685       parameters:
 686         - $ref: '#/components/parameters/id2'
 687       responses:
 688         '200':
 689           description: successful operation
 690           content:
 691             application/json:
 692               schema:
 693                 type: string
 694   '/videos/{id}/views':
 695     post:
 696       summary: Add a view to the video by its id
 697       tags:
 698         - Video
 699       parameters:
 700         - $ref: '#/components/parameters/id2'
 701       responses:
 702         '204':
 703           $ref: '#/paths/~1users~1me/put/responses/204'
 704   /videos/upload:
 705     post:
 706       summary: Upload a video file with its metadata
 707       security:
 708         - OAuth2: []
 709       tags:
 710         - Video
 711       responses:
 712         '200':
 713           description: successful operation
 714           content:
 715             application/json:
 716               schema:
 717                 $ref: '#/components/schemas/VideoUploadResponse'
 718       requestBody:
 719         content:
 720           multipart/form-data:
 721             schema:
 722               type: object
 723               properties:
 724                 videofile:
 725                   description: Video file
 726                   type: string
 727                   format: binary
 728                 channelId:
 729                   description: Channel id that will contain this video
 730                   type: number
 731                 thumbnailfile:
 732                   description: Video thumbnail file
 733                   type: string
 734                 previewfile:
 735                   description: Video preview file
 736                   type: string
 737                 privacy:
 738                   $ref: '#/components/schemas/VideoPrivacy'
 739                 category:
 740                   description: Video category
 741                   type: string
 742                 licence:
 743                   description: Video licence
 744                   type: string
 745                 language:
 746                   description: Video language
 747                   type: string
 748                 description:
 749                   description: Video description
 750                   type: string
 751                 waitTranscoding:
 752                   description: Whether or not we wait transcoding before publish the video
 753                   type: string
 754                 support:
 755                   description: Text describing how to support the video uploader
 756                   type: string
 757                 nsfw:
 758                   description: Whether or not this video contains sensitive content
 759                   type: string
 760                 name:
 761                   description: Video name
 762                   type: string
 763                 tags:
 764                   description: Video tags
 765                   type: string
 766                 commentsEnabled:
 767                   description: Enable or disable comments for this video
 768                   type: string
 769                 scheduleUpdate: *ref_0
 770               required:
 771                 - videofile
 772                 - channelId
 773                 - name
 774                 - privacy
 775       x-code-samples:
 776         - lang: Shell
 777           source: |
 778             ## DEPENDENCIES: httpie, jq
 779             # pip install httpie
 780             USERNAME="<your_username>"
 781             PASSWORD="<your_password>"
 782             FILE_PATH="<your_file_path>"
 783             CHANNEL_ID="<your_channel_id>"
 784             PRIVACY="1" # public: 1, unlisted: 2, private: 3
 785             NAME="<video_name>"
 786
 787             API_PATH="https://peertube2.cpy.re/api/v1"
 788             ## AUTH
 789             client_id=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_id")
 790             client_secret=$(http -b GET "$API_PATH/oauth-clients/local" | jq -r ".client_secret")
 791             token=$(http -b --form POST "$API_PATH/users/token" \
 792               client_id="$client_id" client_secret="$client_secret" grant_type=password response_type=code \
 793               username=$USERNAME \
 794               password=$PASSWORD \
 795               | jq -r ".access_token")
 796             ## VIDEO UPLOAD
 797             http -b --form POST "$API_PATH/videos/upload" \
 798               videofile@$FILE_PATH \
 799               channelId=$CHANNEL_ID \
 800               name=$NAME \
 801               privacy=$PRIVACY \
 802               "Authorization:Bearer $token"
 803   /videos/abuse:
 804     get:
 805       summary: Get list of reported video abuses
 806       security:
 807         - OAuth2: []
 808       tags:
 809         - VideoAbuse
 810       parameters:
 811         - $ref: '#/components/parameters/start'
 812         - $ref: '#/components/parameters/count'
 813         - $ref: '#/components/parameters/sort'
 814       responses:
 815         '200':
 816           description: successful operation
 817           content:
 818             application/json:
 819               schema:
 820                 type: array
 821                 items:
 822                   $ref: '#/components/schemas/VideoAbuse'
 823   '/videos/{id}/abuse':
 824     post:
 825       summary: 'Report an abuse, on a video by its id'
 826       security:
 827         - OAuth2: []
 828       tags:
 829         - VideoAbuse
 830       parameters:
 831         - $ref: '#/components/parameters/id2'
 832       responses:
 833         '204':
 834           $ref: '#/paths/~1users~1me/put/responses/204'
 835   '/videos/{id}/blacklist':
 836     post:
 837       summary: Put on blacklist a video by its id
 838       security:
 839         - OAuth2:
 840             - admin
 841             - moderator
 842       tags:
 843         - VideoBlacklist
 844       parameters:
 845         - $ref: '#/components/parameters/id2'
 846       responses:
 847         '204':
 848           $ref: '#/paths/~1users~1me/put/responses/204'
 849     delete:
 850       summary: Delete an entry of the blacklist of a video by its id
 851       security:
 852         - OAuth2:
 853             - admin
 854             - moderator
 855       tags:
 856         - VideoBlacklist
 857       parameters:
 858         - $ref: '#/components/parameters/id2'
 859       responses:
 860         '204':
 861           $ref: '#/paths/~1users~1me/put/responses/204'
 862   /videos/blacklist:
 863     get:
 864       summary: Get list of videos on blacklist
 865       security:
 866         - OAuth2:
 867             - admin
 868             - moderator
 869       tags:
 870         - VideoBlacklist
 871       parameters:
 872         - $ref: '#/components/parameters/start'
 873         - $ref: '#/components/parameters/count'
 874         - $ref: '#/components/parameters/sort'
 875       responses:
 876         '200':
 877           description: successful operation
 878           content:
 879             application/json:
 880               schema:
 881                 type: array
 882                 items:
 883                   $ref: '#/components/schemas/VideoBlacklist'
 884   /video-channels:
 885     get:
 886       summary: Get list of video channels
 887       tags:
 888         - VideoChannel
 889       parameters:
 890         - $ref: '#/components/parameters/start'
 891         - $ref: '#/components/parameters/count'
 892         - $ref: '#/components/parameters/sort'
 893       responses:
 894         '200':
 895           description: successful operation
 896           content:
 897             application/json:
 898               schema:
 899                 type: array
 900                 items:
 901                   $ref: '#/components/schemas/VideoChannel'
 902     post:
 903       summary: Creates a video channel for the current user
 904       security:
 905         - OAuth2: []
 906       tags:
 907         - VideoChannel
 908       responses:
 909         '204':
 910           $ref: '#/paths/~1users~1me/put/responses/204'
 911       requestBody:
 912         $ref: '#/components/requestBodies/VideoChannelInput'
 913   '/video-channels/{id}':
 914     get:
 915       summary: Get a video channel by its id
 916       tags:
 917         - VideoChannel
 918       parameters:
 919         - $ref: '#/components/parameters/id3'
 920       responses:
 921         '200':
 922           description: successful operation
 923           content:
 924             application/json:
 925               schema:
 926                 $ref: '#/components/schemas/VideoChannel'
 927     put:
 928       summary: Update a video channel by its id
 929       security:
 930         - OAuth2: []
 931       tags:
 932         - VideoChannel
 933       parameters:
 934         - $ref: '#/components/parameters/id3'
 935       responses:
 936         '204':
 937           $ref: '#/paths/~1users~1me/put/responses/204'
 938       requestBody:
 939         $ref: '#/components/requestBodies/VideoChannelInput'
 940     delete:
 941       summary: Delete a video channel by its id
 942       security:
 943         - OAuth2: []
 944       tags:
 945         - VideoChannel
 946       parameters:
 947         - $ref: '#/components/parameters/id3'
 948       responses:
 949         '204':
 950           $ref: '#/paths/~1users~1me/put/responses/204'
 951   '/video-channels/{id}/videos':
 952     get:
 953       summary: Get videos of a video channel by its id
 954       tags:
 955         - VideoChannel
 956       parameters:
 957         - $ref: '#/components/parameters/id3'
 958       responses:
 959         '200':
 960           description: successful operation
 961           content:
 962             application/json:
 963               schema:
 964                 $ref: '#/components/schemas/Video'
 965   '/accounts/{name}/video-channels':
 966     get:
 967       summary: Get video channels of an account by its name
 968       tags:
 969         - VideoChannel
 970       parameters:
 971         - $ref: '#/components/parameters/name'
 972       responses:
 973         '200':
 974           description: successful operation
 975           content:
 976             application/json:
 977               schema:
 978                 type: array
 979                 items:
 980                   $ref: '#/components/schemas/VideoChannel'
 981   '/videos/{id}/comment-threads':
 982     get:
 983       summary: Get the comment threads of a video by its id
 984       tags:
 985         - VideoComment
 986       parameters:
 987         - $ref: '#/components/parameters/id2'
 988         - $ref: '#/components/parameters/start'
 989         - $ref: '#/components/parameters/count'
 990         - $ref: '#/components/parameters/sort'
 991       responses:
 992         '200':
 993           description: successful operation
 994           content:
 995             application/json:
 996               schema:
 997                 $ref: '#/components/schemas/CommentThreadResponse'
 998     post:
 999       summary: 'Creates a comment thread, on a video by its id'
1000       security:
1001         - OAuth2: []
1002       tags:
1003         - VideoComment
1004       parameters:
1005         - $ref: '#/components/parameters/id2'
1006       responses:
1007         '200':
1008           description: successful operation
1009           content:
1010             application/json:
1011               schema:
1012                 $ref: '#/components/schemas/CommentThreadPostResponse'
1013   '/videos/{id}/comment-threads/{threadId}':
1014     get:
1015       summary: 'Get the comment thread by its id, of a video by its id'
1016       tags:
1017         - VideoComment
1018       parameters:
1019         - $ref: '#/components/parameters/id2'
1020         - name: threadId
1021           in: path
1022           required: true
1023           description: The thread id (root comment id)
1024           schema:
1025             type: number
1026       responses:
1027         '200':
1028           description: successful operation
1029           content:
1030             application/json:
1031               schema:
1032                 $ref: '#/components/schemas/VideoCommentThreadTree'
1033   '/videos/{id}/comments/{commentId}':
1034     post:
1035       summary: 'Creates a comment in a comment thread by its id, of a video by its id'
1036       security:
1037         - OAuth2: []
1038       tags:
1039         - VideoComment
1040       parameters:
1041         - $ref: '#/components/parameters/id2'
1042         - $ref: '#/components/parameters/commentId'
1043       responses:
1044         '200':
1045           description: successful operation
1046           content:
1047             application/json:
1048               schema:
1049                 $ref: '#/components/schemas/CommentThreadPostResponse'
1050     delete:
1051       summary: 'Delete a comment in a comment therad by its id, of a video by its id'
1052       security:
1053         - OAuth2: []
1054       tags:
1055         - VideoComment
1056       parameters:
1057         - $ref: '#/components/parameters/id2'
1058         - $ref: '#/components/parameters/commentId'
1059       responses:
1060         '204':
1061           $ref: '#/paths/~1users~1me/put/responses/204'
1062   '/videos/{id}/rate':
1063     put:
1064       summary: Vote for a video by its id
1065       security:
1066         - OAuth2: []
1067       tags:
1068         - VideoRate
1069       parameters:
1070         - $ref: '#/components/parameters/id2'
1071       responses:
1072         '204':
1073           $ref: '#/paths/~1users~1me/put/responses/204'
1074   /search/videos:
1075     get:
1076       tags:
1077         - Search
1078       summary: Get the videos corresponding to a given query
1079       parameters:
1080         - $ref: '#/components/parameters/start'
1081         - $ref: '#/components/parameters/count'
1082         - $ref: '#/components/parameters/sort'
1083         - name: search
1084           in: query
1085           required: true
1086           description: String to search
1087           schema:
1088             type: string
1089       responses:
1090         '200':
1091           description: successful operation
1092           content:
1093             application/json:
1094               schema:
1095                 type: array
1096                 items:
1097                   $ref: '#/components/schemas/Video'
1098 servers:
1099   - url: 'https://peertube2.cpy.re/api/v1'
1100     description: Live Server
1101 components:
1102   parameters:
1103     start:
1104       name: start
1105       in: query
1106       required: false
1107       description: Offset
1108       schema:
1109         type: number
1110     count:
1111       name: count
1112       in: query
1113       required: false
1114       description: Number of items
1115       schema:
1116         type: number
1117     sort:
1118       name: sort
1119       in: query
1120       required: false
1121       description: Sort column (-createdAt for example)
1122       schema:
1123         type: string
1124     name:
1125       name: name
1126       in: path
1127       required: true
1128       description: >-
1129         The name of the account (chocobozzz or chocobozzz@peertube.cpy.re for
1130         example)
1131       schema:
1132         type: string
1133     id:
1134       name: id
1135       in: path
1136       required: true
1137       description: The user id
1138       schema:
1139         type: number
1140     id2:
1141       name: id
1142       in: path
1143       required: true
1144       description: The video id or uuid
1145       schema:
1146         type: string
1147     id3:
1148       name: id
1149       in: path
1150       required: true
1151       description: The video channel id or uuid
1152       schema:
1153         type: string
1154     commentId:
1155       name: threadId
1156       in: path
1157       required: true
1158       description: The comment id
1159       schema:
1160         type: number
1161   requestBodies:
1162     VideoChannelInput:
1163       content:
1164         application/json:
1165           schema:
1166             $ref: '#/components/schemas/VideoChannelInput'
1167   securitySchemes:
1168     OAuth2:
1169       description: >
1170         In the header: *Authorization: Bearer <token\>*
1171
1172
1173         Authenticating via OAuth requires the following steps:
1174
1175
1176         - Have an account with sufficient authorization levels
1177
1178         - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a
1179         Bearer Token
1180
1181         - Make Authenticated Requests
1182       type: oauth2
1183       flows:
1184         password:
1185           tokenUrl: 'https://peertube.example.com/api/v1/users/token'
1186           scopes:
1187             admin: Admin scope
1188             moderator: Moderator scope
1189             user: User scope
1190   schemas:
1191     VideoConstantNumber:
1192       properties:
1193         id:
1194           type: number
1195         label:
1196           type: string
1197     VideoConstantString:
1198       properties:
1199         id:
1200           type: string
1201         label:
1202           type: string
1203     VideoPrivacy:
1204       type: string
1205       enum:
1206         - Public
1207         - Unlisted
1208         - Private
1209     Video:
1210       properties:
1211         id:
1212           type: number
1213         uuid:
1214           type: string
1215         createdAt:
1216           type: string
1217         publishedAt:
1218           type: string
1219         updatedAt:
1220           type: string
1221         category:
1222           $ref: '#/components/schemas/VideoConstantNumber'
1223         licence:
1224           $ref: '#/components/schemas/VideoConstantNumber'
1225         language:
1226           $ref: '#/components/schemas/VideoConstantString'
1227         privacy:
1228           $ref: '#/components/schemas/VideoPrivacy'
1229         description:
1230           type: string
1231         duration:
1232           type: number
1233         isLocal:
1234           type: boolean
1235         name:
1236           type: string
1237         thumbnailPath:
1238           type: string
1239         previewPath:
1240           type: string
1241         embedPath:
1242           type: string
1243         views:
1244           type: number
1245         likes:
1246           type: number
1247         dislikes:
1248           type: number
1249         nsfw:
1250           type: boolean
1251         account:
1252           type: object
1253           properties:
1254             name:
1255               type: string
1256             displayName:
1257               type: string
1258             url:
1259               type: string
1260             host:
1261               type: string
1262             avatar:
1263               $ref: '#/components/schemas/Avatar'
1264     VideoAbuse:
1265       properties:
1266         id:
1267           type: number
1268         reason:
1269           type: string
1270         reporterAccount:
1271           $ref: '#/components/schemas/Account'
1272         video:
1273           type: object
1274           properties:
1275             id:
1276               type: number
1277             name:
1278               type: string
1279             uuid:
1280               type: string
1281             url:
1282               type: string
1283         createdAt:
1284           type: string
1285     VideoBlacklist:
1286       properties:
1287         id:
1288           type: number
1289         videoId:
1290           type: number
1291         createdAt:
1292           type: string
1293         updatedAt:
1294           type: string
1295         name:
1296           type: string
1297         uuid:
1298           type: string
1299         description:
1300           type: string
1301         duration:
1302           type: number
1303         views:
1304           type: number
1305         likes:
1306           type: number
1307         dislikes:
1308           type: number
1309         nsfw:
1310           type: boolean
1311     VideoChannel:
1312       properties:
1313         displayName:
1314           type: string
1315         description:
1316           type: string
1317         isLocal:
1318           type: boolean
1319         ownerAccount:
1320           type: object
1321           properties:
1322             id:
1323               type: number
1324             uuid:
1325               type: string
1326     VideoComment:
1327       properties:
1328         id:
1329           type: number
1330         url:
1331           type: string
1332         text:
1333           type: string
1334         threadId:
1335           type: number
1336         inReplyToCommentId:
1337           type: number
1338         videoId:
1339           type: number
1340         createdAt:
1341           type: string
1342         updatedAt:
1343           type: string
1344         totalReplies:
1345           type: number
1346         account:
1347           $ref: '#/components/schemas/Account'
1348     VideoCommentThreadTree:
1349       properties:
1350         comment:
1351           $ref: '#/components/schemas/VideoComment'
1352         children:
1353           type: array
1354           items:
1355             $ref: '#/components/schemas/VideoCommentThreadTree'
1356     Avatar:
1357       properties:
1358         path:
1359           type: string
1360         createdAt:
1361           type: string
1362         updatedAt:
1363           type: string
1364     Actor:
1365       properties:
1366         id:
1367           type: number
1368         uuid:
1369           type: string
1370         url:
1371           type: string
1372         name:
1373           type: string
1374         host:
1375           type: string
1376         followingCount:
1377           type: number
1378         followersCount:
1379           type: number
1380         createdAt:
1381           type: string
1382         updatedAt:
1383           type: string
1384         avatar:
1385           $ref: '#/components/schemas/Avatar'
1386     Account:
1387       allOf:
1388         - $ref: '#/components/schemas/Actor'
1389         - properties:
1390             displayName:
1391               type: string
1392     User:
1393       properties:
1394         id:
1395           type: number
1396         username:
1397           type: string
1398         email:
1399           type: string
1400         displayNSFW:
1401           type: boolean
1402         autoPlayVideo:
1403           type: boolean
1404         role:
1405           type: string
1406           enum:
1407             - User
1408             - Moderator
1409             - Administrator
1410         videoQuota:
1411           type: number
1412         createdAt:
1413           type: string
1414         account:
1415           $ref: '#/components/schemas/Account'
1416         videoChannels:
1417           type: array
1418           items:
1419             $ref: '#/components/schemas/VideoChannel'
1420     ServerConfig:
1421       properties:
1422         signup:
1423           type: object
1424           properties:
1425             allowed:
1426               type: boolean
1427         transcoding:
1428           type: object
1429           properties:
1430             enabledResolutions:
1431               type: array
1432               items:
1433                 type: number
1434         avatar:
1435           type: object
1436           properties:
1437             file:
1438               type: object
1439               properties:
1440                 size:
1441                   type: object
1442                   properties:
1443                     max:
1444                       type: number
1445             extensions:
1446               type: array
1447               items:
1448                 type: string
1449         video:
1450           type: object
1451           properties:
1452             file:
1453               type: object
1454               properties:
1455                 extensions:
1456                   type: array
1457                   items:
1458                     type: string
1459     Follow:
1460       properties:
1461         id:
1462           type: number
1463         follower:
1464           $ref: '#/components/schemas/Actor'
1465         following:
1466           $ref: '#/components/schemas/Actor'
1467         score:
1468           type: number
1469         state:
1470           type: string
1471           enum:
1472             - pending
1473             - accepted
1474         createdAt:
1475           type: string
1476         updatedAt:
1477           type: string
1478     Job:
1479       properties:
1480         id:
1481           type: number
1482         state:
1483           type: string
1484           enum:
1485             - pending
1486             - processing
1487             - error
1488             - success
1489         category:
1490           type: string
1491           enum:
1492             - transcoding
1493             - activitypub-http
1494         handlerName:
1495           type: string
1496         handlerInputData:
1497           type: string
1498         createdAt:
1499           type: string
1500         updatedAt:
1501           type: string
1502     AddUserResponse:
1503       properties:
1504         id:
1505           type: number
1506         uuid:
1507           type: string
1508     VideoUploadResponse:
1509       properties:
1510         video:
1511           type: object
1512           properties:
1513             id:
1514               type: number
1515             uuid:
1516               type: string
1517     CommentThreadResponse:
1518       properties:
1519         total:
1520           type: number
1521         data:
1522           type: array
1523           items:
1524             $ref: '#/components/schemas/VideoComment'
1525     CommentThreadPostResponse:
1526       properties:
1527         comment:
1528           $ref: '#/components/schemas/VideoComment'
1529     AddUser:
1530       properties:
1531         username:
1532           type: string
1533           description: 'The user username '
1534         password:
1535           type: string
1536           description: 'The user password '
1537         email:
1538           type: string
1539           description: 'The user email '
1540         videoQuota:
1541           type: string
1542           description: 'The user videoQuota '
1543         role:
1544           type: string
1545           description: 'The user role '
1546       required:
1547         - username
1548         - password
1549         - email
1550         - videoQuota
1551         - role
1552     UpdateUser:
1553       properties:
1554         id:
1555           type: string
1556           description: 'The user id '
1557         email:
1558           type: string
1559           description: 'The updated email of the user '
1560         videoQuota:
1561           type: string
1562           description: 'The updated videoQuota of the user '
1563         role:
1564           type: string
1565           description: 'The updated role of the user '
1566       required:
1567         - id
1568         - email
1569         - videoQuota
1570         - role
1571     UpdateMe:
1572       properties:
1573         password:
1574           type: string
1575           description: 'Your new password '
1576         email:
1577           type: string
1578           description: 'Your new email '
1579         displayNSFW:
1580           type: string
1581           description: 'Your new displayNSFW '
1582         autoPlayVideo:
1583           type: string
1584           description: 'Your new autoPlayVideo '
1585       required:
1586         - password
1587         - email
1588         - displayNSFW
1589         - autoPlayVideo
1590     GetMeVideoRating:
1591       properties:
1592         id:
1593           type: string
1594           description: 'Id of the video '
1595         rating:
1596           type: number
1597           description: 'Rating of the video '
1598       required:
1599         - id
1600         - rating
1601     RegisterUser:
1602       properties:
1603         username:
1604           type: string
1605           description: 'The username of the user '
1606         password:
1607           type: string
1608           description: 'The password of the user '
1609         email:
1610           type: string
1611           description: 'The email of the user '
1612       required:
1613         - username
1614         - password
1615         - email
1616     VideoChannelInput:
1617       properties:
1618         name:
1619           type: string
1620         description:
1621           type: string
1622