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