path: root/support/doc/api/openapi.yaml

swagger: '2.0'
info:
  title: PeerTube
  version: 1.0.0-beta
  description: Federated (ActivityPub) video streaming platform using P2P (BitTorrent) directly in the web browser with WebTorrent and Angular.
host: peertube.example.com
basePath: '/api/v1'
schemes:
  - https
paths:
  '/accounts/{id}':
    get:
      tags:
        - Accounts
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The id of the account'
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Account'
  /accounts:
    get:
      tags:
        - Accounts
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Account'
  /config:
    get:
      tags:
        - Config
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ServerConfig'
  /jobs:
    get:
      tags:
        - Job
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: state
          in: path
          required: true
          type: string
          description: 'The id of the account'
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: count
          in: query
          required: false
          type: number
          description: ''
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Job'
  '/server/following/{host}':
    delete:
      tags:
        - ServerFollowing
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: host
          in: path
          required: true
          type: string
          description: 'The host to unfollow '
      responses:
        '201':
          description: successful operation
  /server/followers:
    get:
      tags:
        - ServerFollowing
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Follow'
  /server/following:
    get:
      tags:
        - ServerFollowing
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Follow'
    post:
      tags:
        - ServerFollowing
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Follow'
      responses:
        '204':
          description: successful operation
  /users:
    post:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/AddUser'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AddUserResponse'
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
  '/users/{id}':
    delete:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The user id '
      responses:
        '204':
          description: successful operation
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The user id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/User'
    put:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The user id '
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/UpdateUser'
      responses:
        '204':
          description: successful operation
  /users/me:
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    put:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/UpdateMe'
      responses:
        '204':
          description: successful operation
  /users/me/video-quota-used:
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: successful operation
          schema:
            type: number
  '/users/me/videos/{videoId}/rating':
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/GetMeVideoRating'
  /users/me/videos:
    get:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
  /users/register:
    post:
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/RegisterUser'
      responses:
        '204':
          description: successful operation
  /users/me/avatar/pick:
    post:
      tags:
        - User
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - in: formData
          name: avatarfile
          type: file
          description: The file to upload.
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Avatar'
  /videos:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
  /videos/categories:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/licences:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/languages:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/privacies:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/search:
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
  "/videos/{id}":
    put:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
    delete:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
  "/videos/{id}/description":
    get:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            type: string
  "/videos/{id}/views":
    post:
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
  /videos/upload:
    post:
      tags:
        - Video
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - in: formData
          name: videofile
          type: file
          description: The file to upload.
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoUploadResponse'
  /videos/abuse:
    get:
      tags:
        - VideoAbuse
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoAbuse'
  "/videos/{id}/abuse":
    post:
      tags:
        - VideoAbuse
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
  "/videos/{videoId}/blacklist":
    post:
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
    delete:
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
  /videos/blacklist:
    get:
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoBlacklist'
  /videos/channels:
    get:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoChannel'
    post:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/VideoChannelInput'
      responses:
        '204':
          description: successful operation
  "/videos/channels/{id}":
    get:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoChannel'
    put:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
        - in: body
          name: body
          schema:
            $ref: '#/definitions/VideoChannelInput'
      responses:
        '204':
          description: successful operation
    delete:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
  /videos/accounts/{accountId}/channels:
    get:
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: accountId
          in: path
          required: true
          type: string
          description: 'The account id '
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoChannel'
  "/videos/{videoId}/comment-threads":
    get:
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
        - name: start
          in: query
          required: false
          type: number
          description: 'starting page'
        - name: stop
          in: query
          required: false
          type: number
          description: 'stoping page'
        - name: sort
          in: query
          required: false
          type: number
          description: 'sorting'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadResponse'
    post:
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadPostResponse'
  "/videos/{videoId}/comment-threads/{threadId}":
    get:
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
        - name: threadId
          in: path
          required: true
          type: string
          description: 'The thread id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoCommentThreadTree'
  "/videos/{videoId}/comments/{commentId}":
    post:
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
        - name: commentId
          in: path
          required: true
          type: string
          description: 'The comment id '
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadPostResponse'
    delete:
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: videoId
          in: path
          required: true
          type: string
          description: 'The video id '
        - name: commentId
          in: path
          required: true
          type: string
          description: 'The comment id '
      responses:
        '204':
          description: successful operation
  "/videos/{id}/rate":
    put:
      tags:
        - VideoRate
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          required: true
          type: string
          description: 'The video id '
      responses:
        '204':
          description: successful operation
definitions:
  VideoConstant:
    properties:
      id:
        type: number
      label:
        type: string
  Video:
    properties:
      id:
        type: number
      uuid:
        type: string
      createdAt:
        type: string
      updatedAt:
        type: string
      category:
        $ref: "#/definitions/VideoConstant"
      licence:
        $ref: "#/definitions/VideoConstant"
      language:
        $ref: "#/definitions/VideoConstant"
      description:
        type: string
      duration:
        type: number
      isLocal:
        type: boolean
      name:
        type: string
      thumbnailPath:
        type: string
      previewPath:
        type: string
      embedPath:
        type: string
      views:
        type: number
      likes:
        type: number
      dislikes:
        type: number
      nsfw:
        type: boolean
      account:
        name: string
        displayName: string
        url: string
        host: string
        avatar:
          $ref: "#/definitions/Avatar"
  VideoAbuse:
    properties:
      id:
        type: number
      reason:
        type: string
      reporterAccount:
        $ref: "#/definitions/Account"
      video:
        id: number
        name: string
        uuid: string
        url: string
      createdAt:
        type: string
  VideoBlacklist:
    properties:
      id:
        type: number
      videoId:
        type: number
      createdAt:
        type: string
      updatedAt:
        type: string
      name:
        type: string
      uuid:
        type: string
      description:
        type: string
      duration:
        type: number
      views:
        type: number
      likes:
        type: number
      dislikes:
        type: number
      nsfw:
        type: boolean
  VideoChannel:
    properties:
      displayName:
        type: string
      description:
        type: string
      isLocal:
        type: boolean
      owner:
        type: object
        properties:
          name:
            type: string
          uuid:
            type: string
      videos:
        type: array
        items:
          $ref: "#/definitions/Video"
  VideoComment:
    properties:
      id:
        type: number
      url:
        type: string
      text:
        type: string
      threadId:
        type: number
      inReplyToCommentId:
        type: number
      videoId:
        type: number
      createdAt:
        type: string
      updatedAt:
        type: string
      totalReplies:
        type: number
      account:
        $ref: "#/definitions/Account"
  VideoCommentThreadTree:
    properties:
      comment:
        $ref: "#/definitions/VideoComment"
      children:
        type: array
        items:
          $ref: "#/definitions/VideoCommentThreadTree"
  Avatar:
    properties:
      path:
        type: string
      createdAt:
        type: string
      updatedAt:
        type: string
  Actor:
    properties:
      id:
        type: number
      uuid:
        type: string
      url:
        type: string
      name:
        type: string
      host:
        type: string
      followingCount:
        type: number
      followersCount:
        type: number
      createdAt:
        type: string
      updatedAt:
        type: string
      avatar:
        $ref: "#/definitions/Avatar"
  Account:
    allOf:
      - $ref: "#/definitions/Actor"
      - properties:
          displayName:
            type: string
  User:
    properties:
      id:
        type: number
      username:
        type: string
      email:
        type: string
      displayNSFW:
        type: boolean
      autoPlayVideo:
        type: boolean
      role:
        type: string
        enum: [User, Moderator, Administrator]
      videoQuota:
        type: number
      createdAt:
        type: string
      account:
        $ref: "#/definitions/Account"
      videoChannels:
        type:  array
        items:
          $ref: "#/definitions/VideoChannel"
  ServerConfig:
    properties:
      signup:
        type: object
        properties:
          allowed:
            type: boolean
      transcoding:
        type: object
        properties:
          enabledResolutions:
            type: array
            items:
              type: number
      avatar:
        type: object
        properties:
          file:
            type: object
            properties:
              size:
                type: object
                properties:
                  max:
                    type: number
          extensions:
            type: array
            items:
              type: string
      video:
        type: object
        properties:
          file:
            type: object
            properties:
              extensions:
                type: array
                items:
                  type: string
  Follow:
    properties:
      id:
        type: number
      follower:
        $ref: "#/definitions/Actor"
      following:
        $ref: "#/definitions/Actor"
      score:
        type: number
      state:
        type: string
        enum: [pending, accepted]
      createdAt:
        type: string
      updatedAt:
        type: string
  Job:
    properties:
      id:
        type: number
      state:
        type: string
        enum: [pending, processing, error, success]
      category:
        type: string
        enum: [transcoding, activitypub-http]
      handlerName:
        type: string
      handlerInputData:
        type: string
      createdAt:
        type: string
      updatedAt:
        type: string

#Api responses
  AddUserResponse:
    properties:
      id:
        type: number
      uuid:
        type: string
  VideoUploadResponse:
    properties:
      id:
        type: number
      uuid:
        type: string
  CommentThreadResponse:
    properties:
      total:
        type: number
      data:
        type: array
        items:
          $ref: "#/definitions/VideoComment"
  CommentThreadPostResponse:
    properties:
      comment:
        $ref: "#/definitions/VideoComment"

#request bodies
  AddUser:
    properties:
      username:
        type: string
        description: 'The user username '
      password:
        type: string
        description: 'The user password '
      email:
        type: string
        description: 'The user email '
      videoQuota:
        type: string
        description: 'The user videoQuota '
      role:
        type: string
        description: 'The user role '
    required:
      - username
      - password
      - email
      - videoQuota
      - role
  UpdateUser:
    properties:
      id:
        type: string
        description: 'The user id '
      email:
        type: string
        description: 'The updated email of the user '
      videoQuota:
        type: string
        description: 'The updated videoQuota of the user '
      role:
        type: string
        description: 'The updated role of the user '
    required:
      - id
      - email
      - videoQuota
      - role
  UpdateMe:
    properties:
      password:
        type: string
        description: 'Your new password '
      email:
        type: string
        description: 'Your new email '
      displayNSFW:
        type: string
        description: 'Your new displayNSFW '
      autoPlayVideo:
        type: string
        description: 'Your new autoPlayVideo '
    required:
      - password
      - email
      - displayNSFW
      - autoPlayVideo
  GetMeVideoRating:
    properties:
      id:
        type: string
        description: 'Id of the video '
      rating:
        type: number
        description: 'Rating of the video '
    required:
      - id
      - rating
  RegisterUser:
    properties:
      username:
        type: string
        description: 'The username of the user '
      password:
        type: string
        description: 'The password of the user '
      email:
        type: string
        description: 'The email of the user '
    required:
      - username
      - password
      - email
  VideoChannelInput:
    properties:
      name:
        type: string
      description:
        type: string