support/doc/api/openapi.yaml

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