support/doc/api/openapi.yaml

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