support/doc/api/openapi.yaml

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