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

swagger: '2.0'
info:
  title: PeerTube
  version: 1.1.0-alpha.2
  contact:
    name: PeerTube Community
    url: 'https://joinpeertube.org'
  license:
    name: AGPLv3.0
    url: 'https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE'
  x-logo:
    url: 'https://joinpeertube.org/img/brand.png'
  description: |
    # Introduction
    The PeerTube API is built on HTTP(S). Our API is RESTful. It has predictable
    resource URLs. It returns HTTP response codes to indicate errors. It also
    accepts and returns JSON in the HTTP body. You can use your favorite
    HTTP/REST library for your programming language to use PeerTube. No official
    SDK is currently provided.
    
    # Authentication
    When you sign up for an account, you are given the possibility to generate
    sessions, and authenticate using this session token. One session token can 
    currently be used at a time.
securityDefinitions:
  OAuth2:
    description: |
      In the header: *Authorization: Bearer <token\>*
      
      Authenticating via OAuth requires the following steps:

      - Have an account with sufficient authorization levels
      - [Generate](https://docs.joinpeertube.org/lang/en/devdocs/rest.html) a Bearer Token
      - Make Authenticated Requests
    type: oauth2
    flow: password
    # Not implemented yet
    # authorizationUrl: https://example.com/oauth/authorize
    tokenUrl: https://peertube.example.com/api/v1/users/token
    scopes:
      admin: Admin scope
      moderator: Moderator scope
      user: User scope
basePath: '/api/v1'
schemes:
  - https
host: peertube.example.com
x-servers:
  - url: 'https://peertube.cpy.re/api/v1'
    description: Live Server
produces:
  - application/json; charset=utf-8
consumes:
  - application/json
tags:
  - name: Accounts
    description: |
      Using some features of PeerTube require authentication, for which Accounts
      provide different levels of permission as well as associated user information.
      Accounts also encompass remote accounts discovered across the federation.
  - name: Config
    description: |
      Each server exposes public information regarding supported videos and options.
  - name: Feeds
    description: |
      Feeds of videos and feeds of comments allow to see updates and get them in
      an aggregator or script of your choice.
  - name: Job
    description: |
      Jobs are long-running tasks enqueued and processed by the instance itself. 
      No additional worker registration is currently available.
  - name: ServerFollowing
    description: |
      Managing servers which the instance interacts with is crucial to the concept
      of federation in PeerTube and external video indexation. The PeerTube server
      then deals with inter-server ActivityPub operations and propagates 
      information across its social graph by posting activities to actors' inbox
      endpoints.
  - name: VideoAbuse
    description: |
      Video abuses deal with reports of local or remote videos alike.
  - name: Video
    description: |
      Operations dealing with listing, uploading, fetching or modifying videos.
  - name: Search
    description: |
      The search helps to find _videos_ from within the instance and beyond.
      Videos from other instances federated by the instance (that is, instances
      followed by the instance) can be found via keywords and other criteria of
      the advanced search.
  - name: VideoComment
    description: |
      Operations dealing with comments to a video. Comments are organized in threads.
  - name: VideoChannel
    description: |
      Operations dealing with creation, modification and video listing of a user's
      channels.
paths:
  '/accounts/{name}':
    get:
      tags:
        - Accounts
      summary: Get the account by name
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "accounts.yaml#/parameters/name"
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Account'
  '/accounts/{name}/videos':
    get:
      tags:
        - Accounts
        - Video
      summary: Get videos for an account, provided the name of that account
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "accounts.yaml#/parameters/name"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
      x-code-samples:
        - lang: JavaScript
          source: |
            fetch('https://peertube.cpy.re/api/v1/accounts/{name}/videos')
            .then(function(response) {
              return response.json()
            }).then(function(data) {
              console.log(data)
            })
  /accounts:
    get:
      tags:
        - Accounts
      summary: Get all accounts
      consumes:
        - application/json
      produces:
        - application/jsonhttps://peertube.cpy.re/api/v1
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Account'
  /config:
    get:
      tags:
        - Config
      summary: Get the configuration of the server
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ServerConfig'
  /feeds/videos.{format}:
    get:
      summary: Get the feed of videos for the server, with optional filter by account name or id
      tags:
        - Feeds
      produces:
        - application/atom+xml
        - application/rss+xml
        - application/json
      parameters:
        - name: format
          in: path
          required: true
          type: string
          enum: [ 'xml', 'atom', 'json']
          default: 'xml'
          description: 'The format expected (xml defaults to RSS 2.0, atom to ATOM 1.0 and json to JSON FEED 1.0'
        - name: accountId
          in: query
          required: false
          type: number
          description: 'The id of the local account to filter to (beware, users IDs and not actors IDs which will return empty feeds'
        - name: accountName
          in: query
          required: false
          type: string
          description: 'The name of the local account to filter to'
      responses:
        '200':
          description: successful operation
  /jobs:
    get:
      summary: Get list of jobs
      security:
        - OAuth2: [ admin ]
      tags:
        - Job
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: state
          in: path
          required: true
          type: string
          description: 'The state of the job'
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Job'
  '/server/following/{host}':
    delete:
      security:
        - OAuth2: [ admin ]
      tags:
        - ServerFollowing
      summary: Unfollow a server by hostname
      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
      summary: Get followers of the server
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Follow'
  /server/following:
    get:
      tags:
        - ServerFollowing
      summary: Get servers followed by the server
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Follow'
    post:
      security:
        - OAuth2: [ admin ]
      tags:
        - ServerFollowing
      summary: Follow a server
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/Follow'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /users:
    post:
      summary: Creates user
      security:
        - OAuth2: [ admin ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          description: 'User to create'
          schema:
            $ref: '#/definitions/AddUser'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AddUserResponse'
    get:
      summary: Get a list of users
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
  '/users/{id}':
    delete:
      summary: Delete a user by its id
      security:
        - OAuth2: [ admin ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "users.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
    get:
      summary: Get user by its id
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "users.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/User'
    put:
      summary: Update user profile by its id
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "users.yaml#/parameters/id"
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/UpdateUser'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /users/me:
    get:
      summary: Get current user information
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    put:
      summary: Update current user information
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/UpdateMe'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /users/me/video-quota-used:
    get:
      summary: Get current user used quota
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters: []
      responses:
        '200':
          description: successful operation
          schema:
            type: number
  '/users/me/videos/{videoId}/rating':
    get:
      summary: Get rating of video by its id, among those of the current user
      security:
        - OAuth2: [ ]
      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:
      summary: Get videos of the current user
      security:
        - OAuth2: [ ]
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
  /users/register:
    post:
      summary: Register a user
      tags:
        - User
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/RegisterUser'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /users/me/avatar/pick:
    post:
      summary: Update current user avatar
      security:
        - OAuth2: [ ]
      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:
      summary: Get list of videos
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: category
          in: query
          required: false
          type: number
          description: category id of the video
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
  /videos/categories:
    get:
      summary: Get list of video licences known by the server
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/licences:
    get:
      summary: Get list of video licences known by the server
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/languages:
    get:
      summary: Get list of languages known by the server
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  /videos/privacies:
    get:
      summary: Get list of privacy policies supported by the server
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              type: string
  "/videos/{id}":
    put:
      summary: Update metadata for a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - Video
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
        - $ref: "videos.yaml#/parameters/thumbnailfile"
        - $ref: "videos.yaml#/parameters/previewfile"
        - $ref: "videos.yaml#/parameters/category"
        - $ref: "videos.yaml#/parameters/licence"
        - $ref: "videos.yaml#/parameters/language"
        - $ref: "videos.yaml#/parameters/description"
        - $ref: "videos.yaml#/parameters/waitTranscoding"
        - $ref: "videos.yaml#/parameters/support"
        - $ref: "videos.yaml#/parameters/nsfw"
        - $ref: "videos.yaml#/parameters/name"
        - $ref: "videos.yaml#/parameters/tags"
        - $ref: "videos.yaml#/parameters/commentsEnabled"
        - $ref: "videos.yaml#/parameters/privacy"
        - $ref: "videos.yaml#/parameters/scheduleUpdate"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
    get:
      summary: Get a video by its id
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
    delete:
      summary: Delete a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  "/videos/{id}/description":
    get:
      summary: Get a video description by its id
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            type: string
  "/videos/{id}/views":
    post:
      summary: Add a view to the video by its id
      tags:
        - Video
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /videos/upload:
    post:
      summary: Upload a video file with its metadata
      security:
        - OAuth2: [ ]
      tags:
        - Video
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: videofile
          in: formData
          type: file
          required: true
          description: 'Video file'
        - name: channelId
          in: formData
          required: true
          type: number
          description: 'Channel id that will contain this video'
        - $ref: "videos.yaml#/parameters/thumbnailfile"
        - $ref: "videos.yaml#/parameters/previewfile"
        - $ref: "videos.yaml#/parameters/category"
        - $ref: "videos.yaml#/parameters/licence"
        - $ref: "videos.yaml#/parameters/language"
        - $ref: "videos.yaml#/parameters/description"
        - $ref: "videos.yaml#/parameters/waitTranscoding"
        - $ref: "videos.yaml#/parameters/support"
        - $ref: "videos.yaml#/parameters/nsfw"
        - $ref: "videos.yaml#/parameters/name"
        - $ref: "videos.yaml#/parameters/tags"
        - $ref: "videos.yaml#/parameters/commentsEnabled"
        - $ref: "videos.yaml#/parameters/privacy"
        - $ref: "videos.yaml#/parameters/scheduleUpdate"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoUploadResponse'
  /videos/abuse:
    get:
      summary: Get list of reported video abuses
      security:
        - OAuth2: [ ]
      tags:
        - VideoAbuse
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoAbuse'
  "/videos/{id}/abuse":
    post:
      summary: Report an abuse, on a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoAbuse
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  "/videos/{id}/blacklist":
    post:
      summary: Put on blacklist a video by its id
      security:
        - OAuth2: [ admin, moderator ]
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
    delete:
      summary: Delete an entry of the blacklist of a video by its id
      security:
        - OAuth2: [ admin, moderator ]
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /videos/blacklist:
    get:
      summary: Get list of videos on blacklist
      security:
        - OAuth2: [ admin, moderator ]
      tags:
        - VideoBlacklist
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoBlacklist'
  /video-channels:
    get:
      summary: Get list of video channels
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoChannel'
    post:
      summary: Creates a video channel for the current user
      security:
        - OAuth2: [ ]
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          schema:
            $ref: '#/definitions/VideoChannelInput'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  "/video-channels/{id}":
    get:
      summary: Get a video channel by its id
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "video-channels.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoChannel'
    put:
      summary: Update a video channel by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "video-channels.yaml#/parameters/id"
        - in: body
          name: body
          schema:
            $ref: '#/definitions/VideoChannelInput'
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
    delete:
      summary: Delete a video channel by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "video-channels.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  "/video-channels/{id}/videos":
    get:
      summary: Get videos of a video channel by its id
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "video-channels.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Video'
  /accounts/{name}/video-channels:
    get:
      summary: Get video channels of an account by its name
      tags:
        - VideoChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "accounts.yaml#/parameters/name"
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/VideoChannel'
  "/videos/{id}/comment-threads":
    get:
      summary: Get the comment threads of a video by its id
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadResponse'
    post:
      summary: Creates a comment thread, on a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadPostResponse'
  "/videos/{id}/comment-threads/{threadId}":
    get:
      summary: Get the comment thread by its id, of a video by its id
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
        - $ref: "video-comments.yaml#/parameters/threadId"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/VideoCommentThreadTree'
  "/videos/{id}/comments/{commentId}":
    post:
      summary: Creates a comment in a comment thread by its id, of a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
        - $ref: "video-comments.yaml#/parameters/commentId"
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/CommentThreadPostResponse'
    delete:
      summary: Delete a comment in a comment therad by its id, of a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoComment
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
        - $ref: "video-comments.yaml#/parameters/commentId"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  "/videos/{id}/rate":
    put:
      summary: Vote for a video by its id
      security:
        - OAuth2: [ ]
      tags:
        - VideoRate
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "videos.yaml#/parameters/id"
      responses:
        '204':
          $ref: "commons.yaml#/responses/emptySuccess"
  /search/videos:
    get:
      tags:
        - Search
      summary: Get the videos corresponding to a given query
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "commons.yaml#/parameters/start"
        - $ref: "commons.yaml#/parameters/count"
        - $ref: "commons.yaml#/parameters/sort"
        - name: search
          in: query
          required: true
          type: string
          description: 'String to search'
      responses:
        '200':
          description: successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/Video'
definitions:
  VideoConstantNumber:
    properties:
      id:
        type: number
      label:
        type: string
  VideoConstantString:
    properties:
      id:
        type: string
      label:
        type: string
  VideoPrivacy:
    type: string
    enum: [Public, Unlisted, Private]
  Video:
    properties:
      id:
        type: number
      uuid:
        type: string
      createdAt:
        type: string
      publishedAt:
        type: string
      updatedAt:
        type: string
      category:
        $ref: "#/definitions/VideoConstantNumber"
      licence:
        $ref: "#/definitions/VideoConstantNumber"
      language:
        $ref: "#/definitions/VideoConstantString"
      privacy:
        $ref: "#/definitions/VideoPrivacy"
      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:
        type: object
        properties:
          name:
            type: string
          displayName:
            type: string
          url:
            type: string
          host:
            type: string
          avatar:
            $ref: "#/definitions/Avatar"
  VideoAbuse:
    properties:
      id:
        type: number
      reason:
        type: string
      reporterAccount:
        $ref: "#/definitions/Account"
      video:
        type: object
        properties:
          id:
            type: number
          name:
            type: string
          uuid:
            type: string
          url:
            type: 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
      ownerAccount:
        type: object
        properties:
          id:
            type: number
          uuid:
            type: string
  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:
      video:
        type: object
        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