openapi: 3.0.0
servers:
  - description: Live Test Server (live data - latest nightly version)
    url: https://peertube2.cpy.re
  - description: Live Test Server (live data - latest RC version)
    url: https://peertube3.cpy.re
  - description: Live Test Server (live data - stable version)
    url: https://peertube.cpy.re
info:
  contact:
    name: PeerTube Community
    url: https://joinpeertube.org
  description: |
    The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite
    HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with
    [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO)
    which generates a client SDK in the language of your choice - we generate some client SDKs automatically:

    - [Python](https://framagit.org/framasoft/peertube/clients/python)
    - [Go](https://framagit.org/framasoft/peertube/clients/go)
    - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin)

    See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few
    examples of using the PeerTube API.

    # Authentication

    When you sign up for an account on a PeerTube instance, you are given the possibility
    to generate sessions on it, and authenticate there using an access token. Only __one
    access token can currently be used at a time__.

    ## Roles

    Accounts are given permissions based on their role. There are three roles on
    PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions.

    # Errors

    The API uses standard HTTP status codes to indicate the success or failure
    of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body.

    ```
    HTTP 1.1 404 Not Found
    Content-Type: application/problem+json; charset=utf-8

    {
      "detail": "Video not found",
      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
      "status": 404,
      "title": "Not Found",
      "type": "about:blank"
    }
    ```

    We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
    but it is still optional. Types are used to disambiguate errors that bear the same status code
    and are non-obvious:

    ```
    HTTP 1.1 403 Forbidden
    Content-Type: application/problem+json; charset=utf-8

    {
      "detail": "Cannot get this video regarding follow constraints",
      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
      "status": 403,
      "title": "Forbidden",
      "type": "https://docs.joinpeertube.org/api/rest-reference.html#section/Errors/does_not_respect_follow_constraints"
    }
    ```

    Here a 403 error could otherwise mean that the video is private or blocklisted.

    ### Validation errors

    Each parameter is evaluated on its own against a set of rules before the route validator
    proceeds with potential testing involving parameter combinations. Errors coming from validation
    errors appear earlier and benefit from a more detailed error description:

    ```
    HTTP 1.1 400 Bad Request
    Content-Type: application/problem+json; charset=utf-8

    {
      "detail": "Incorrect request parameters: id",
      "docs": "https://docs.joinpeertube.org/api/rest-reference.html#operation/getVideo",
      "instance": "/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180",
      "invalid-params": {
        "id": {
          "location": "params",
          "msg": "Invalid value",
          "param": "id",
          "value": "9c9de5e8-0a1e-484a-b099-e80766180"
        }
      },
      "status": 400,
      "title": "Bad Request",
      "type": "about:blank"
    }
    ```

    Where `id` is the name of the field concerned by the error, within the route definition.
    `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and
    `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
    is about.

    ### Deprecated error fields

    Some fields could be included with previous versions. They are still included but their use is deprecated:
    - `error`: superseded by `detail`
    - `code`: superseded by `type` (which is now an URI)

    # Rate limits

    We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:

    | Endpoint (prefix: `/api/v1`) | Calls         | Time frame   |
    |------------------------------|---------------|--------------|
    | `/*`                         | 50            | 10 seconds   |
    | `POST /users/token`          | 15            | 5 minutes    |
    | `POST /users/register`       | 2<sup>*</sup> | 5 minutes    |
    | `POST /users/ask-send-verify-email` | 3      | 5 minutes    |

    Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service
    limit is announced by a `429 Too Many Requests` status code.

    You can get details about the current state of your rate limit by reading the
    following headers:

    | Header                  | Description                                                |
    |-------------------------|------------------------------------------------------------|
    | `X-RateLimit-Limit`     | Number of max requests allowed in the current time period  |
    | `X-RateLimit-Remaining` | Number of remaining requests in the current time period    |
    | `X-RateLimit-Reset`     | Timestamp of end of current time period as UNIX timestamp  |
    | `Retry-After`           | Seconds to delay after the first `429` is received         |

    # CORS

    This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/),
    allowing cross-domain communication from the browser for some routes:

    | Endpoint                    |
    |------------------------- ---|
    | `/api/*`                    |
    | `/download/*`               |
    | `/lazy-static/*`            |
    | `/.well-known/webfinger`    |

    In addition, all routes serving ActivityPub are CORS-enabled for all origins.
  license:
    name: AGPLv3.0
    url: https://github.com/Chocobozzz/PeerTube/blob/master/LICENSE
  title: PeerTube
  version: 5.1.0
  x-apisguru-categories:
    - social
  x-logo:
    altText: PeerTube Project Homepage
    url: https://joinpeertube.org/img/brand.png
  x-origin:
    - converter:
        url: https://github.com/mermade/oas-kit
        version: 7.0.4
      format: openapi
      url: https://raw.githubusercontent.com/Chocobozzz/PeerTube/develop/support/doc/api/openapi.yaml
      version: "3.0"
  x-providerName: cpy.re
  x-serviceName: peertube
externalDocs:
  url: https://docs.joinpeertube.org/api/rest-reference.html
tags:
  - description: |
      As a visitor, you can use this API to open an account (if registrations are open on
      that PeerTube instance). As an admin, you should use the dedicated [User creation
      API](#operation/addUser) instead.
    name: Register
  - description: |
      Sessions deal with access tokens over time. Only __one session token can currently be used at a time__.
    name: Session
    x-displayName: Login/Logout
  - description: |
      Accounts encompass remote accounts discovered across the federation, and correspond to the main Actor, along with video channels a user can create, which are also Actors.
      When a comment is posted, it is done with your Account's Actor.
    name: Accounts
  - description: |
      Using some features of PeerTube require authentication, for which User provide different levels of permission as well as associated user information. Each user has a corresponding local Account for federation.
    name: Users
  - description: |
      Operations related to your own User, when logged-in.
    name: My User
  - description: |
      Operations related to your subscriptions to video channels, their new videos, and how to keep up to date with their latest publications!
    name: My Subscriptions
  - description: |
      Operations related to your watch history.
    name: My History
  - description: |
      Notifications following new videos, follows or reports. They allow you to keep track of the interactions and overall important information that concerns you. You MAY set per-notification type delivery preference, to receive the info either by mail, by in-browser notification or both.
    name: My Notifications
  - description: |
      Each server exposes public information regarding supported videos and options.
    name: Config
  - description: |
      Jobs are long-running tasks enqueued and processed by the instance itself. No additional worker registration is currently available.
    name: Job
  - 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.
    externalDocs:
      url: https://docs.joinpeertube.org/admin/following-instances#instances-follows
    name: Instance Follows
  - description: |
      Redundancy is part of the inter-server solidarity that PeerTube fosters. Manage the list of instances you wish to help by seeding their videos according to the policy of video selection of your choice. Note that you have a similar functionality to mirror individual videos, see [video mirroring](#tag/Video-Mirroring).
    externalDocs:
      url: https://docs.joinpeertube.org/admin/following-instances#instances-redundancy
    name: Instance Redundancy
  - description: |
      Managing plugins installed from a local path or from NPM, or search for new ones.
    externalDocs:
      url: https://docs.joinpeertube.org/api/plugins
    name: Plugins
  - description: |
      Abuses deal with reports of local or remote videos/comments/accounts alike.
    name: Abuses
  - description: |
      Operations dealing with listing, uploading, fetching or modifying videos.
    name: Video
  - description: |
      Operations dealing with adding video or audio. PeerTube supports two upload modes, and three import modes.

      ### Upload

      - [_legacy_](#operation/uploadLegacy), where the video file is sent in a single request
      - [_resumable_](#operation/uploadResumableInit), where the video file is sent in chunks

      You can upload videos more reliably by using the resumable variant. Its protocol lets
      you resume an upload operation after a network interruption or other transmission failure,
      saving time and bandwidth in the event of network failures.

      Favor using resumable uploads in any of the following cases:
      - You are transferring large files
      - The likelihood of a network interruption is high
      - Uploads are originating from a device with a low-bandwidth or unstable Internet connection,
        such as a mobile device

      ### Import

      - _URL_-based: where the URL points to any service supported by [youtube-dl](https://ytdl-org.github.io/youtube-dl/)
      - _magnet_-based: where the URI resolves to a BitTorrent resource containing a single supported video file
      - _torrent_-based: where the metainfo file resolves to a BitTorrent resource containing a single supported video file

      The import function is practical when the desired video/audio is available online. It makes PeerTube
      download it for you, saving you as much bandwidth and avoiding any instability or limitation your network might have.
    name: Video Upload
  - description: Operations dealing with listing, adding and removing video imports.
    name: Video Imports
  - description: Operations dealing with synchronizing PeerTube user's channel with channels of other platforms
    name: Channels Sync
  - description: Operations dealing with listing, adding and removing closed captions of a video.
    name: Video Captions
  - description: Operations dealing with the creation, modification and listing of videos within a channel.
    name: Video Channels
  - description: |
      Operations dealing with comments to a video. Comments are organized in threads: adding a comment in response to the video starts a thread, adding a reply to a comment adds it to its root comment thread.
    name: Video Comments
  - description: Operations dealing with blocking videos (removing them from view and preventing interactions).
    name: Video Blocks
  - description: Like/dislike a video.
    name: Video Rates
  - description: Operations dealing with playlists of videos. Playlists are bound to users and/or channels.
    name: Video Playlists
  - description: Operations on video files
    name: Video Files
  - description: Video transcoding related operations
    name: Video Transcoding
  - description: Video statistics
    name: Video stats
  - description: Server syndication feeds of videos
    name: Video Feeds
  - description: |
      The search helps to find _videos_ or _channels_ 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.

      Administrators can also enable the use of a remote search system, indexing
      videos and channels not could be not federated by the instance.
    name: Search
  - description: Get and update the custom homepage
    name: Homepage
  - description: |
      PeerTube instances can mirror videos from one another, and help distribute some videos.

      For importing videos as your own, refer to [video imports](#operation/importVideo).
    name: Video Mirroring
  - description: |
      Statistics
    name: Stats
paths:
  /api/v1/abuses:
    get:
      operationId: getAbuses
      parameters:
        - description: only list the report with this id
          in: query
          name: id
          schema:
            type: integer
        - description: predefined reason the listed reports should contain
          in: query
          name: predefinedReason
          schema:
            $ref: "#/components/schemas/PredefinedAbuseReasons"
        - description: plain search that will match with video titles, reporter names and more
          in: query
          name: search
          schema:
            type: string
        - in: query
          name: state
          schema:
            $ref: "#/components/schemas/AbuseStateSet"
        - description: only list reports of a specific reporter
          in: query
          name: searchReporter
          schema:
            type: string
        - description: only list reports of a specific reportee
          in: query
          name: searchReportee
          schema:
            type: string
        - description: only list reports of a specific video
          in: query
          name: searchVideo
          schema:
            type: string
        - description: only list reports of a specific video channel
          in: query
          name: searchVideoChannel
          schema:
            type: string
        - description: only list deleted or blocklisted videos
          in: query
          name: videoIs
          schema:
            enum:
              - deleted
              - blacklisted
            type: string
        - description: only list account, comment or video reports
          in: query
          name: filter
          schema:
            enum:
              - video
              - comment
              - account
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/abusesSort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Abuse"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: List abuses
      tags:
        - Abuses
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account:
                  properties:
                    id:
                      description: Account id to report
                      type: integer
                  type: object
                comment:
                  properties:
                    id:
                      allOf:
                        - $ref: "#/components/schemas/VideoComment/properties/id"
                      description: Comment id to report
                  type: object
                predefinedReasons:
                  $ref: "#/components/schemas/PredefinedAbuseReasons"
                reason:
                  description: Reason why the user reports this video
                  maxLength: 3000
                  minLength: 2
                  type: string
                video:
                  properties:
                    endAt:
                      description: Timestamp in the video that marks the ending of the report
                      format: seconds
                      minimum: 0
                      type: integer
                    id:
                      allOf:
                        - $ref: "#/components/schemas/Video/properties/id"
                      description: Video id to report
                    startAt:
                      description: Timestamp in the video that marks the beginning of the report
                      format: seconds
                      minimum: 0
                      type: integer
                  type: object
              required:
                - reason
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  abuse:
                    properties:
                      id:
                        $ref: "#/components/schemas/id"
                    type: object
                type: object
          description: successful operation
        "400":
          description: incorrect request parameters
      security:
        - OAuth2: []
      summary: Report an abuse
      tags:
        - Abuses
  "/api/v1/abuses/{abuseId}":
    delete:
      parameters:
        - $ref: "#/components/parameters/abuseId"
      responses:
        "204":
          description: successful operation
        "404":
          description: block not found
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Delete an abuse
      tags:
        - Abuses
    put:
      parameters:
        - $ref: "#/components/parameters/abuseId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                moderationComment:
                  description: Update the report comment visible only to the moderation team
                  maxLength: 3000
                  minLength: 2
                  type: string
                state:
                  $ref: "#/components/schemas/AbuseStateSet"
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: abuse not found
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Update an abuse
      tags:
        - Abuses
  "/api/v1/abuses/{abuseId}/messages":
    get:
      parameters:
        - $ref: "#/components/parameters/abuseId"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/AbuseMessage"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: List messages of an abuse
      tags:
        - Abuses
    post:
      parameters:
        - $ref: "#/components/parameters/abuseId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                message:
                  description: Message to send
                  maxLength: 3000
                  minLength: 2
                  type: string
              required:
                - message
              type: object
        required: true
      responses:
        "200":
          description: successful operation
        "400":
          description: incorrect request parameters
      security:
        - OAuth2: []
      summary: Add message to an abuse
      tags:
        - Abuses
  "/api/v1/abuses/{abuseId}/messages/{abuseMessageId}":
    delete:
      parameters:
        - $ref: "#/components/parameters/abuseId"
        - $ref: "#/components/parameters/abuseMessageId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete an abuse message
      tags:
        - Abuses
  /api/v1/accounts:
    get:
      operationId: getAccounts
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Account"
                type: array
          description: successful operation
      summary: List accounts
      tags:
        - Accounts
  "/api/v1/accounts/{name}":
    get:
      operationId: getAccount
      parameters:
        - $ref: "#/components/parameters/name"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
          description: successful operation
        "404":
          description: account not found
      summary: Get an account
      tags:
        - Accounts
  "/api/v1/accounts/{name}/followers":
    get:
      operationId: getAccountFollowers
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/followersSort"
        - $ref: "#/components/parameters/search"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Follow"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: List followers of an account
      tags:
        - Accounts
  "/api/v1/accounts/{name}/ratings":
    get:
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
        - description: Optionally filter which ratings to retrieve
          in: query
          name: rating
          required: false
          schema:
            enum:
              - like
              - dislike
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/VideoRating"
                type: array
          description: successful operation
      security:
        - OAuth2: []
      summary: List ratings of an account
      tags:
        - Accounts
  "/api/v1/accounts/{name}/video-channel-syncs":
    get:
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannelSyncList"
          description: successful operation
      summary: List the synchronizations of video channels of an account
      tags:
        - Video Channels
        - Channels Sync
        - Accounts
  "/api/v1/accounts/{name}/video-channels":
    get:
      parameters:
        - $ref: "#/components/parameters/name"
        - description: include daily view statistics for the last 30 days and total views (only if authentified as the account user)
          in: query
          name: withStats
          schema:
            type: boolean
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannelList"
          description: successful operation
      summary: List video channels of an account
      tags:
        - Video Channels
        - Accounts
  "/api/v1/accounts/{name}/video-playlists":
    get:
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/search"
        - $ref: "#/components/parameters/videoPlaylistType"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoPlaylist"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List playlists of an account
      tags:
        - Video Playlists
        - Accounts
  "/api/v1/accounts/{name}/videos":
    get:
      operationId: getAccountVideos
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/categoryOneOf"
        - $ref: "#/components/parameters/isLive"
        - $ref: "#/components/parameters/tagsOneOf"
        - $ref: "#/components/parameters/tagsAllOf"
        - $ref: "#/components/parameters/licenceOneOf"
        - $ref: "#/components/parameters/languageOneOf"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
        - $ref: "#/components/parameters/skipCount"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/videosSort"
        - $ref: "#/components/parameters/excludeAlreadyWatched"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      summary: List videos of an account
      tags:
        - Accounts
        - Video
      x-codeSamples:
        - lang: JavaScript
          source: |
            fetch('https://peertube2.cpy.re/api/v1/accounts/{name}/videos')
            .then(function(response) {
              return response.json()
            }).then(function(data) {
              console.log(data)
            })
        - lang: Shell
          source: |
            ## DEPENDENCIES: jq
            curl -s https://peertube2.cpy.re/api/v1/accounts/{name}/videos | jq
        - lang: Ruby
          source: |
            require 'net/http'
            require 'json'

            uri = URI.parse("https://peertube2.cpy.re/api/v1/accounts/{name}/videos")

            http = Net::HTTP.new(uri.host, uri.port)
            http.use_ssl = true

            response = http.get(uri.request_uri)

            puts JSON.parse(response.read_body)
        - lang: Python
          source: |
            import requests

            r = requests.get("https://peertube2.cpy.re/api/v1//accounts/{name}/videos")
            json = r.json()

            print(json)
  /api/v1/blocklist/status:
    get:
      parameters:
        - description: Check if these accounts are blocked
          example:
            - goofy@example.com
            - donald@example.com
          in: query
          name: accounts
          schema:
            items:
              type: string
            type: array
        - description: Check if these hosts are blocked
          example:
            - example.com
          in: query
          name: hosts
          schema:
            items:
              type: string
            type: array
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockStatus"
          description: successful operation
      summary: Get block status of accounts/hosts
      tags:
        - Account Blocks
        - Server Blocks
  /api/v1/config:
    get:
      operationId: getConfig
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/config
              schema:
                $ref: "#/components/schemas/ServerConfig"
          description: successful operation
      summary: Get instance public configuration
      tags:
        - Config
  /api/v1/config/about:
    get:
      operationId: getAbout
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/config/about
              schema:
                $ref: "#/components/schemas/ServerConfigAbout"
          description: successful operation
      summary: Get instance "About" information
      tags:
        - Config
  /api/v1/config/custom:
    delete:
      operationId: delCustomConfig
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Delete instance runtime configuration
      tags:
        - Config
    get:
      operationId: getCustomConfig
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerConfigCustom"
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Get instance runtime configuration
      tags:
        - Config
    put:
      operationId: putCustomConfig
      responses:
        "200":
          description: successful operation
        "400":
          description: |
            Arises when:
              - the emailer is disabled and the instance is open to registrations
              - webtorrent and hls are disabled with transcoding enabled - you need at least one enabled
          x-summary: field inconsistencies
      security:
        - OAuth2:
            - admin
      summary: Set instance runtime configuration
      tags:
        - Config
  /api/v1/custom-pages/homepage/instance:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomHomepage"
          description: successful operation
        "404":
          description: No homepage set
      summary: Get instance custom homepage
      tags:
        - Homepage
    put:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                content:
                  description: content of the homepage, that will be injected in the client
                  type: string
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Set instance custom homepage
      tags:
        - Homepage
  /api/v1/jobs/pause:
    post:
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Pause job queue
      tags:
        - Job
  /api/v1/jobs/resume:
    post:
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Resume job queue
      tags:
        - Job
  "/api/v1/jobs/{state}":
    get:
      operationId: getJobs
      parameters:
        - description: The state of the job ('' for for no filter)
          in: path
          name: state
          required: true
          schema:
            enum:
              - ""
              - active
              - completed
              - failed
              - waiting
              - delayed
            type: string
        - $ref: "#/components/parameters/jobType"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Job"
                    maxItems: 100
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List instance jobs
      tags:
        - Job
  /api/v1/metrics/playback:
    post:
      description: These metrics are exposed by OpenTelemetry metrics exporter if enabled.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlaybackMetricCreate"
      responses:
        "204":
          description: successful operation
      summary: Create playback metrics
      tags:
        - Stats
  /api/v1/oauth-clients/local:
    get:
      description: You need to retrieve a client id and secret before [logging in](#operation/getOAuthToken).
      operationId: getOAuthClient
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthClient"
          description: successful operation
          links:
            UseOAuthClientToLogin:
              operationId: getOAuthToken
              parameters:
                client_id: $response.body#/client_id
                client_secret: $response.body#/client_secret
      summary: Login prerequisite
      tags:
        - Session
      x-codeSamples:
        - lang: Shell
          source: |
            API="https://peertube2.cpy.re/api/v1"

            ## AUTH
            curl -s "$API/oauth-clients/local"
  /api/v1/plugins:
    get:
      operationId: getPlugins
      parameters:
        - in: query
          name: pluginType
          schema:
            type: integer
        - in: query
          name: uninstalled
          schema:
            type: boolean
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PluginResponse"
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List plugins
      tags:
        - Plugins
  /api/v1/plugins/available:
    get:
      operationId: getAvailablePlugins
      parameters:
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: pluginType
          schema:
            type: integer
        - in: query
          name: currentPeerTubeEngine
          schema:
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PluginResponse"
          description: successful operation
        "503":
          description: plugin index unavailable
      security:
        - OAuth2:
            - admin
      summary: List available plugins
      tags:
        - Plugins
  /api/v1/plugins/install:
    post:
      operationId: addPlugin
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - additionalProperties: false
                  properties:
                    npmName:
                      example: peertube-plugin-auth-ldap
                      type: string
                  required:
                    - npmName
                  type: object
                - additionalProperties: false
                  properties:
                    path:
                      type: string
                  required:
                    - path
                  type: object
      responses:
        "204":
          description: successful operation
        "400":
          description: should have either `npmName` or `path` set
      security:
        - OAuth2:
            - admin
      summary: Install a plugin
      tags:
        - Plugins
  /api/v1/plugins/uninstall:
    post:
      operationId: uninstallPlugin
      requestBody:
        content:
          application/json:
            schema:
              properties:
                npmName:
                  description: name of the plugin/theme in its package.json
                  example: peertube-plugin-auth-ldap
                  type: string
              required:
                - npmName
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: existing plugin not found
      security:
        - OAuth2:
            - admin
      summary: Uninstall a plugin
      tags:
        - Plugins
  /api/v1/plugins/update:
    post:
      operationId: updatePlugin
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - additionalProperties: false
                  properties:
                    npmName:
                      example: peertube-plugin-auth-ldap
                      type: string
                  required:
                    - npmName
                  type: object
                - additionalProperties: false
                  properties:
                    path:
                      type: string
                  required:
                    - path
                  type: object
      responses:
        "204":
          description: successful operation
        "400":
          description: should have either `npmName` or `path` set
        "404":
          description: existing plugin not found
      security:
        - OAuth2:
            - admin
      summary: Update a plugin
      tags:
        - Plugins
  "/api/v1/plugins/{npmName}":
    get:
      operationId: getPlugin
      parameters:
        - $ref: "#/components/parameters/npmName"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Plugin"
          description: successful operation
        "404":
          description: plugin not found
      security:
        - OAuth2:
            - admin
      summary: Get a plugin
      tags:
        - Plugins
  "/api/v1/plugins/{npmName}/public-settings":
    get:
      parameters:
        - $ref: "#/components/parameters/npmName"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: successful operation
        "404":
          description: plugin not found
      summary: Get a plugin's public settings
      tags:
        - Plugins
  "/api/v1/plugins/{npmName}/registered-settings":
    get:
      parameters:
        - $ref: "#/components/parameters/npmName"
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
          description: successful operation
        "404":
          description: plugin not found
      security:
        - OAuth2:
            - admin
      summary: Get a plugin's registered settings
      tags:
        - Plugins
  "/api/v1/plugins/{npmName}/settings":
    put:
      parameters:
        - $ref: "#/components/parameters/npmName"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                settings:
                  additionalProperties: true
                  type: object
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: plugin not found
      security:
        - OAuth2:
            - admin
      summary: Set a plugin's settings
      tags:
        - Plugins
  /api/v1/search/video-channels:
    get:
      callbacks:
        searchTarget === search-index:
          $ref: "#/components/callbacks/searchIndex"
      operationId: searchChannels
      parameters:
        - description: |
            String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete channel information and interact with it.
          in: query
          name: search
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/searchTarget"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannelList"
          description: successful operation
        "500":
          description: search index unavailable
      summary: Search channels
      tags:
        - Search
  /api/v1/search/video-playlists:
    get:
      callbacks:
        searchTarget === search-index:
          $ref: "#/components/callbacks/searchIndex"
      operationId: searchPlaylists
      parameters:
        - description: |
            String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete playlist information and interact with it.
          in: query
          name: search
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/searchTarget"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoPlaylist"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
        "500":
          description: search index unavailable
      summary: Search playlists
      tags:
        - Search
  /api/v1/search/videos:
    get:
      callbacks:
        searchTarget === search-index:
          $ref: "#/components/callbacks/searchIndex"
      operationId: searchVideos
      parameters:
        - allowEmptyValue: false
          description: |
            String to search. If the user can make a remote URI search, and the string is an URI then the PeerTube instance will fetch the remote object and add it to its database. Then, you can use the REST API to fetch the complete video information and interact with it.
          in: query
          name: search
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/categoryOneOf"
        - $ref: "#/components/parameters/isLive"
        - $ref: "#/components/parameters/tagsOneOf"
        - $ref: "#/components/parameters/tagsAllOf"
        - $ref: "#/components/parameters/licenceOneOf"
        - $ref: "#/components/parameters/languageOneOf"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/uuids"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
        - $ref: "#/components/parameters/skipCount"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/searchTarget"
        - $ref: "#/components/parameters/videosSearchSort"
        - $ref: "#/components/parameters/excludeAlreadyWatched"
        - description: Get videos that are published after this date
          in: query
          name: startDate
          schema:
            format: date-time
            type: string
        - description: Get videos that are published before this date
          in: query
          name: endDate
          schema:
            format: date-time
            type: string
        - description: Get videos that are originally published after this date
          in: query
          name: originallyPublishedStartDate
          schema:
            format: date-time
            type: string
        - description: Get videos that are originally published before this date
          in: query
          name: originallyPublishedEndDate
          schema:
            format: date-time
            type: string
        - description: Get videos that have this minimum duration
          in: query
          name: durationMin
          schema:
            type: integer
        - description: Get videos that have this maximum duration
          in: query
          name: durationMax
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
        "500":
          description: search index unavailable
      summary: Search videos
      tags:
        - Search
  /api/v1/server/audit-logs:
    get:
      operationId: getInstanceAuditLogs
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Get instance audit logs
      tags:
        - Logs
  /api/v1/server/blocklist/accounts:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List account blocks
      tags:
        - Account Blocks
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                accountName:
                  description: account to block, in the form `username@domain`
                  example: chocobozzz@example.org
                  type: string
              required:
                - accountName
              type: object
      responses:
        "200":
          description: successful operation
        "409":
          description: self-blocking forbidden
      security:
        - OAuth2:
            - admin
      summary: Block an account
      tags:
        - Account Blocks
  "/api/v1/server/blocklist/accounts/{accountName}":
    delete:
      parameters:
        - description: account to unblock, in the form `username@domain`
          in: path
          name: accountName
          required: true
          schema:
            type: string
      responses:
        "201":
          description: successful operation
        "404":
          description: account or account block does not exist
      security:
        - OAuth2:
            - admin
      summary: Unblock an account by its handle
      tags:
        - Account Blocks
  /api/v1/server/blocklist/servers:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List server blocks
      tags:
        - Server Blocks
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                host:
                  description: server domain to block
                  format: hostname
                  type: string
              required:
                - host
              type: object
      responses:
        "204":
          description: successful operation
        "409":
          description: self-blocking forbidden
      security:
        - OAuth2:
            - admin
      summary: Block a server
      tags:
        - Server Blocks
  "/api/v1/server/blocklist/servers/{host}":
    delete:
      parameters:
        - description: server domain to unblock
          in: path
          name: host
          required: true
          schema:
            format: hostname
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: account block does not exist
      security:
        - OAuth2:
            - admin
      summary: Unblock a server by its domain
      tags:
        - Server Blocks
  /api/v1/server/followers:
    get:
      parameters:
        - $ref: "#/components/parameters/followState"
        - $ref: "#/components/parameters/actorType"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Follow"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List instances following the server
      tags:
        - Instance Follows
  "/api/v1/server/followers/{nameWithHost}":
    delete:
      parameters:
        - description: The remote actor handle to remove from your followers
          in: path
          name: nameWithHost
          required: true
          schema:
            format: email
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: follower not found
      security:
        - OAuth2:
            - admin
      summary: Remove or reject a follower to your server
      tags:
        - Instance Follows
  "/api/v1/server/followers/{nameWithHost}/accept":
    post:
      parameters:
        - description: The remote actor handle to remove from your followers
          in: path
          name: nameWithHost
          required: true
          schema:
            format: email
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: follower not found
      security:
        - OAuth2:
            - admin
      summary: Accept a pending follower to your server
      tags:
        - Instance Follows
  "/api/v1/server/followers/{nameWithHost}/reject":
    post:
      parameters:
        - description: The remote actor handle to remove from your followers
          in: path
          name: nameWithHost
          required: true
          schema:
            format: email
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: follower not found
      security:
        - OAuth2:
            - admin
      summary: Reject a pending follower to your server
      tags:
        - Instance Follows
  /api/v1/server/following:
    get:
      parameters:
        - $ref: "#/components/parameters/followState"
        - $ref: "#/components/parameters/actorType"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Follow"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List instances followed by the server
      tags:
        - Instance Follows
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                handles:
                  items:
                    type: string
                  type: array
                  uniqueItems: true
                hosts:
                  items:
                    format: hostname
                    type: string
                  type: array
                  uniqueItems: true
              type: object
      responses:
        "204":
          description: successful operation
        "500":
          description: cannot follow a non-HTTPS server
      security:
        - OAuth2:
            - admin
      summary: Follow a list of actors (PeerTube instance, channel or account)
      tags:
        - Instance Follows
  "/api/v1/server/following/{hostOrHandle}":
    delete:
      parameters:
        - description: The hostOrHandle to unfollow
          in: path
          name: hostOrHandle
          required: true
          schema:
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: host or handle not found
      security:
        - OAuth2:
            - admin
      summary: Unfollow an actor (PeerTube instance, channel or account)
      tags:
        - Instance Follows
  /api/v1/server/logs:
    get:
      operationId: getInstanceLogs
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Get instance logs
      tags:
        - Logs
  /api/v1/server/logs/client:
    post:
      operationId: sendClientLog
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendClientLog"
      responses:
        "204":
          description: successful operation
      summary: Send client log
      tags:
        - Logs
  /api/v1/server/redundancy/videos:
    get:
      operationId: getMirroredVideos
      parameters:
        - description: direction of the mirror
          in: query
          name: target
          required: true
          schema:
            enum:
              - my-videos
              - remote-videos
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/videoRedundanciesSort"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/VideoRedundancy"
                type: array
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List videos being mirrored
      tags:
        - Video Mirroring
    post:
      operationId: putMirroredVideo
      requestBody:
        content:
          application/json:
            schema:
              properties:
                videoId:
                  $ref: "#/components/schemas/Video/properties/id"
              required:
                - videoId
              type: object
      responses:
        "204":
          description: successful operation
        "400":
          description: cannot mirror a local video
        "404":
          description: video does not exist
        "409":
          description: video is already mirrored
      security:
        - OAuth2:
            - admin
      summary: Mirror a video
      tags:
        - Video Mirroring
  "/api/v1/server/redundancy/videos/{redundancyId}":
    delete:
      operationId: delMirroredVideo
      parameters:
        - description: id of an existing redundancy on a video
          in: path
          name: redundancyId
          required: true
          schema:
            type: string
      responses:
        "204":
          description: successful operation
        "404":
          description: video redundancy not found
      security:
        - OAuth2:
            - admin
      summary: Delete a mirror done on a video
      tags:
        - Video Mirroring
  "/api/v1/server/redundancy/{host}":
    put:
      parameters:
        - description: server domain to mirror
          in: path
          name: host
          required: true
          schema:
            format: hostname
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                redundancyAllowed:
                  description: allow mirroring of the host's local videos
                  type: boolean
              required:
                - redundancyAllowed
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: server is not already known
      security:
        - OAuth2:
            - admin
      summary: Update a server redundancy policy
      tags:
        - Instance Redundancy
  /api/v1/server/stats:
    get:
      description: Get instance public statistics. This endpoint is cached.
      operationId: getInstanceStats
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerStats"
          description: successful operation
      summary: Get instance stats
      tags:
        - Stats
  /api/v1/users:
    get:
      operationId: getUsers
      parameters:
        - $ref: "#/components/parameters/usersSearch"
        - $ref: "#/components/parameters/usersBlocked"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/usersSort"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/User"
                type: array
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: List users
      tags:
        - Users
    post:
      operationId: addUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddUser"
        description: |
          If the smtp server is configured, you can leave the password empty and an email will be sent
          asking the user to set it first.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddUserResponse"
          description: user created
          links:
            DelUser:
              operationId: delUser
              parameters:
                id: $response.body#/user/id
            GetUser:
              operationId: getUser
              parameters:
                id: $response.body#/user/id
            PutUser:
              operationId: putUser
              parameters:
                id: $response.body#/user/id
        "403":
          description: insufficient authority to create an admin or moderator
      security:
        - OAuth2:
            - admin
      summary: Create a user
      tags:
        - Users
  /api/v1/users/ask-send-verify-email:
    post:
      operationId: resendEmailToVerifyUser
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  description: User email
                  type: string
              required:
                - email
              type: object
      responses:
        "204":
          description: successful operation
      summary: Resend user verification link
      tags:
        - Users
        - Register
  /api/v1/users/me:
    get:
      operationId: getUserInfo
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/User"
                type: array
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get my user information
      tags:
        - My User
    put:
      operationId: putUserInfo
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMe"
        required: true
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Update my user information
      tags:
        - My User
  /api/v1/users/me/abuses:
    get:
      operationId: getMyAbuses
      parameters:
        - description: only list the report with this id
          in: query
          name: id
          schema:
            type: integer
        - in: query
          name: state
          schema:
            $ref: "#/components/schemas/AbuseStateSet"
        - $ref: "#/components/parameters/abusesSort"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Abuse"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: List my abuses
      tags:
        - Abuses
        - My User
  /api/v1/users/me/avatar:
    delete:
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete my avatar
      tags:
        - My User
  /api/v1/users/me/avatar/pick:
    post:
      requestBody:
        content:
          multipart/form-data:
            encoding:
              avatarfile:
                contentType: image/png, image/jpeg
            schema:
              properties:
                avatarfile:
                  description: The file to upload
                  format: binary
                  type: string
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  avatars:
                    items:
                      $ref: "#/components/schemas/ActorImage"
                    type: array
                type: object
          description: successful operation
        "413":
          description: image file too large
          headers:
            X-File-Maximum-Size:
              description: Maximum file size for the avatar
              schema:
                format: Nginx size
                type: string
      security:
        - OAuth2: []
      summary: Update my user avatar
      tags:
        - My User
  /api/v1/users/me/history/videos:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/search"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      security:
        - OAuth2: []
      summary: List watched videos history
      tags:
        - My History
  /api/v1/users/me/history/videos/remove:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                beforeDate:
                  description: history before this date will be deleted
                  format: date-time
                  type: string
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Clear video history
      tags:
        - My History
  "/api/v1/users/me/history/videos/{videoId}":
    delete:
      parameters:
        - in: path
          name: videoId
          required: true
          schema:
            $ref: "#/components/schemas/Video/properties/id"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete history element
      tags:
        - My History
  /api/v1/users/me/notification-settings:
    put:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                abuseAsModerator:
                  $ref: "#/components/schemas/NotificationSettingValue"
                autoInstanceFollowing:
                  $ref: "#/components/schemas/NotificationSettingValue"
                blacklistOnMyVideo:
                  $ref: "#/components/schemas/NotificationSettingValue"
                commentMention:
                  $ref: "#/components/schemas/NotificationSettingValue"
                myVideoImportFinished:
                  $ref: "#/components/schemas/NotificationSettingValue"
                myVideoPublished:
                  $ref: "#/components/schemas/NotificationSettingValue"
                newCommentOnMyVideo:
                  $ref: "#/components/schemas/NotificationSettingValue"
                newFollow:
                  $ref: "#/components/schemas/NotificationSettingValue"
                newInstanceFollower:
                  $ref: "#/components/schemas/NotificationSettingValue"
                newUserRegistration:
                  $ref: "#/components/schemas/NotificationSettingValue"
                newVideoFromSubscription:
                  $ref: "#/components/schemas/NotificationSettingValue"
                videoAutoBlacklistAsModerator:
                  $ref: "#/components/schemas/NotificationSettingValue"
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update my notification settings
      tags:
        - My Notifications
  /api/v1/users/me/notifications:
    get:
      parameters:
        - description: only list unread notifications
          in: query
          name: unread
          schema:
            type: boolean
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationListResponse"
          description: successful operation
      security:
        - OAuth2: []
      summary: List my notifications
      tags:
        - My Notifications
  /api/v1/users/me/notifications/read:
    post:
      requestBody:
        content:
          application/json:
            schema:
              properties:
                ids:
                  description: ids of the notifications to mark as read
                  items:
                    type: integer
                  type: array
              required:
                - ids
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Mark notifications as read by their id
      tags:
        - My Notifications
  /api/v1/users/me/notifications/read-all:
    post:
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Mark all my notification as read
      tags:
        - My Notifications
  /api/v1/users/me/subscriptions:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannelList"
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get my user subscriptions
      tags:
        - My Subscriptions
    post:
      requestBody:
        content:
          application/json:
            examples:
              default:
                value:
                  uri: 008a0e54-375d-49d0-8379-143202e24152@video.lqdn.fr
            schema:
              properties:
                uri:
                  description: uri of the video channels to subscribe to
                  format: uri
                  type: string
              required:
                - uri
              type: object
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Add subscription to my user
      tags:
        - My Subscriptions
  /api/v1/users/me/subscriptions/exist:
    get:
      parameters:
        - $ref: "#/components/parameters/subscriptionsUris"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get if subscriptions exist for my user
      tags:
        - My Subscriptions
  /api/v1/users/me/subscriptions/videos:
    get:
      parameters:
        - $ref: "#/components/parameters/categoryOneOf"
        - $ref: "#/components/parameters/isLive"
        - $ref: "#/components/parameters/tagsOneOf"
        - $ref: "#/components/parameters/tagsAllOf"
        - $ref: "#/components/parameters/licenceOneOf"
        - $ref: "#/components/parameters/languageOneOf"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
        - $ref: "#/components/parameters/skipCount"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/videosSort"
        - $ref: "#/components/parameters/excludeAlreadyWatched"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: List videos of subscriptions of my user
      tags:
        - My Subscriptions
        - Videos
  "/api/v1/users/me/subscriptions/{subscriptionHandle}":
    delete:
      parameters:
        - $ref: "#/components/parameters/subscriptionHandle"
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Delete subscription of my user
      tags:
        - My Subscriptions
    get:
      parameters:
        - $ref: "#/components/parameters/subscriptionHandle"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannel"
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get subscription of my user
      tags:
        - My Subscriptions
  /api/v1/users/me/video-playlists/videos-exist:
    get:
      parameters:
        - description: The video ids to check
          in: query
          name: videoIds
          required: true
          schema:
            items:
              $ref: "#/components/schemas/Video/properties/id"
            type: array
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoId:
                    items:
                      properties:
                        playlistElementId:
                          type: integer
                        playlistId:
                          type: integer
                        startTimestamp:
                          format: seconds
                          type: integer
                        stopTimestamp:
                          type: integer
                      type: object
                    type: array
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: Check video exists in my playlists
      tags:
        - Video Playlists
  /api/v1/users/me/video-quota-used:
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoQuotaUsed:
                    description: The user video quota used so far in bytes
                    example: 16810141515
                    type: number
                  videoQuotaUsedDaily:
                    description: The user video quota used today in bytes
                    example: 1681014151
                    type: number
                type: object
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get my user used quota
      tags:
        - My User
  /api/v1/users/me/videos:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get videos of my user
      tags:
        - My User
        - Videos
  /api/v1/users/me/videos/imports:
    get:
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
        - description: Filter on import target URL
          in: query
          name: targetUrl
          required: false
          schema:
            type: string
        - description: Filter on imports created by a specific channel synchronization
          in: query
          name: videoChannelSyncId
          required: false
          schema:
            type: number
        - description: Search in video names
          in: query
          name: search
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoImportsList"
          description: successful operation
      security:
        - OAuth2:
            - user
      summary: Get video imports of my user
      tags:
        - Videos
        - My User
  "/api/v1/users/me/videos/{videoId}/rating":
    get:
      parameters:
        - description: The video id
          in: path
          name: videoId
          required: true
          schema:
            $ref: "#/components/schemas/Video/properties/id"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetMeVideoRating"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get rate of my user for a video
      tags:
        - My User
        - Video Rates
  /api/v1/users/register:
    post:
      description: Signup has to be enabled and signup approval is not required
      operationId: registerUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterUser"
        required: true
      responses:
        "204":
          description: successful operation
        "400":
          description: request error
        "403":
          description: user registration is not enabled, user limit is reached, registration is not allowed for the ip, requires approval or blocked by a plugin
        "409":
          description: a user with this username, channel name or email already exists
      summary: Register a user
      tags:
        - Register
  /api/v1/users/registrations:
    get:
      operationId: listRegistrations
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - in: query
          name: search
          required: false
          schema:
            type: string
        - in: query
          name: sort
          required: false
          schema:
            enum:
              - -createdAt
              - createdAt
              - state
              - -state
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/UserRegistration"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: List registrations
      tags:
        - Register
  /api/v1/users/registrations/ask-send-verify-email:
    post:
      operationId: resendEmailToVerifyRegistration
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  description: Registration email
                  type: string
              required:
                - email
              type: object
      responses:
        "204":
          description: successful operation
      summary: Resend verification link to registration email
      tags:
        - Register
  /api/v1/users/registrations/request:
    post:
      description: Signup has to be enabled and require approval on the instance
      operationId: requestRegistration
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegistrationRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserRegistration"
          description: successful operation
        "400":
          description: request error or signup approval is not enabled on the instance
        "403":
          description: user registration is not enabled, user limit is reached, registration is not allowed for the ip or blocked by a plugin
        "409":
          description: a user or registration with this username, channel name or email already exists
      summary: Request registration
      tags:
        - Register
  "/api/v1/users/registrations/{registrationId}":
    delete:
      description: Delete the registration entry. It will not remove the user associated with this registration (if any)
      operationId: deleteRegistration
      parameters:
        - $ref: "#/components/parameters/registrationId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Delete registration
      tags:
        - Register
  "/api/v1/users/registrations/{registrationId}/accept":
    post:
      operationId: acceptRegistration
      parameters:
        - $ref: "#/components/parameters/registrationId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegistrationAcceptOrReject"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Accept registration
      tags:
        - Register
  "/api/v1/users/registrations/{registrationId}/reject":
    post:
      operationId: rejectRegistration
      parameters:
        - $ref: "#/components/parameters/registrationId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserRegistrationAcceptOrReject"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Reject registration
      tags:
        - Register
  "/api/v1/users/registrations/{registrationId}/verify-email":
    post:
      description: |
        Following a user registration request, the user will receive an email asking to click a link
        containing a secret.
      operationId: verifyRegistrationEmail
      parameters:
        - $ref: "#/components/parameters/registrationId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                verificationString:
                  format: url
                  type: string
              required:
                - verificationString
              type: object
      responses:
        "204":
          description: successful operation
        "403":
          description: invalid verification string
        "404":
          description: registration not found
      summary: Verify a registration email
      tags:
        - Register
  /api/v1/users/revoke-token:
    post:
      description: Revokes your access token and its associated refresh token, destroying your current session.
      operationId: revokeOAuthToken
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2: []
      summary: Logout
      tags:
        - Session
  /api/v1/users/token:
    post:
      description: With your [client id and secret](#operation/getOAuthClient), you can retrieve an access and refresh tokens.
      operationId: getOAuthToken
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              discriminator:
                mapping:
                  password: "#/components/schemas/OAuthToken-password"
                  refresh_token: "#/components/schemas/OAuthToken-refresh_token"
                propertyName: grant_type
              oneOf:
                - $ref: "#/components/schemas/OAuthToken-password"
                - $ref: "#/components/schemas/OAuthToken-refresh_token"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    description: valid for 1 day
                    example: 90286a0bdf0f7315d9d3fe8dabf9e1d2be9c97d0
                    type: string
                  expires_in:
                    example: 14399
                    minimum: 0
                    type: integer
                  refresh_token:
                    description: valid for 2 weeks
                    example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
                    type: string
                  refresh_token_expires_in:
                    example: 1209600
                    minimum: 0
                    type: integer
                  token_type:
                    example: Bearer
                    type: string
                type: object
          description: successful operation
        "400":
          description: |
            Disambiguate via `type`:
            - `invalid_client` for an unmatched `client_id`
            - `invalid_grant` for unmatched credentials
          x-summary: client or credentials are invalid
        "401":
          description: |
            Disambiguate via `type`:
            - default value for a regular authentication failure
            - `invalid_token` for an expired token
          x-summary: token expired
      summary: Login
      tags:
        - Session
      x-codeSamples:
        - lang: Shell
          source: |
            ## DEPENDENCIES: jq
            API="https://peertube2.cpy.re/api/v1"
            USERNAME="<your_username>"
            PASSWORD="<your_password>"

            ## AUTH
            client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
            client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
            curl -s "$API/users/token" \
              --data client_id="$client_id" \
              --data client_secret="$client_secret" \
              --data grant_type=password \
              --data username="$USERNAME" \
              --data password="$PASSWORD" \
              | jq -r ".access_token"
  "/api/v1/users/{id}":
    delete:
      operationId: delUser
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
      summary: Delete a user
      tags:
        - Users
    get:
      operationId: getUser
      parameters:
        - description: include statistics about the user (only available as a moderator/admin)
          in: query
          name: withStats
          schema:
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/User"
                  - $ref: "#/components/schemas/UserWithStats"
          description: |
            As an admin/moderator, you can request a response augmented with statistics about the user's
            moderation relations and videos usage, by using the `withStats` parameter.
          x-summary: successful operation
      security:
        - OAuth2: []
      summary: Get a user
      tags:
        - Users
    parameters:
      - $ref: "#/components/parameters/id"
    put:
      operationId: putUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUser"
        required: true
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update a user
      tags:
        - Users
  "/api/v1/users/{id}/two-factor/confirm-request":
    post:
      description: Confirm a two factor authentication request
      operationId: confirmTwoFactorRequest
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                otpToken:
                  description: OTP token generated by the app
                  type: string
                requestToken:
                  description: Token to identify the two factor request
                  type: string
              required:
                - requestToken
                - otpToken
              type: object
      responses:
        "204":
          description: successful operation
        "403":
          description: invalid request token or OTP token
        "404":
          description: user not found
      summary: Confirm two factor auth
      tags:
        - Users
  "/api/v1/users/{id}/two-factor/disable":
    post:
      description: Disable two factor authentication of a user
      operationId: disableTwoFactor
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                currentPassword:
                  description: Password of the currently authenticated user
                  type: string
              type: object
      responses:
        "204":
          description: successful operation
        "403":
          description: invalid password
        "404":
          description: user not found
      summary: Disable two factor auth
      tags:
        - Users
  "/api/v1/users/{id}/two-factor/request":
    post:
      description: Request two factor authentication for a user
      operationId: requestTwoFactor
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                currentPassword:
                  description: Password of the currently authenticated user
                  type: string
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/RequestTwoFactorResponse"
                type: array
          description: successful operation
        "403":
          description: invalid password
        "404":
          description: user not found
      summary: Request two factor auth
      tags:
        - Users
  "/api/v1/users/{id}/verify-email":
    post:
      description: |
        Following a user registration, the new user will receive an email asking to click a link
        containing a secret.
        This endpoint can also be used to verify a new email set in the user account.
      operationId: verifyUser
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                isPendingEmail:
                  type: boolean
                verificationString:
                  format: url
                  type: string
              required:
                - verificationString
              type: object
      responses:
        "204":
          description: successful operation
        "403":
          description: invalid verification string
        "404":
          description: user not found
      summary: Verify a user
      tags:
        - Users
        - Register
  /api/v1/video-channel-syncs:
    post:
      operationId: addVideoChannelSync
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoChannelSyncCreate"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoChannelSync:
                    $ref: "#/components/schemas/VideoChannelSync"
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: Create a synchronization for a video channel
      tags:
        - Channels Sync
  "/api/v1/video-channel-syncs/{channelSyncId}":
    delete:
      operationId: delVideoChannelSync
      parameters:
        - $ref: "#/components/parameters/channelSyncId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete a video channel synchronization
      tags:
        - Channels Sync
  "/api/v1/video-channel-syncs/{channelSyncId}/sync":
    post:
      operationId: triggerVideoChannelSync
      parameters:
        - $ref: "#/components/parameters/channelSyncId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Triggers the channel synchronization job, fetching all the videos from the remote channel
      tags:
        - Channels Sync
  /api/v1/video-channels:
    get:
      operationId: getVideoChannels
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannelList"
          description: successful operation
      summary: List video channels
      tags:
        - Video Channels
    post:
      operationId: addVideoChannel
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoChannelCreate"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoChannel:
                    properties:
                      id:
                        $ref: "#/components/schemas/id"
                    type: object
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: Create a video channel
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}":
    delete:
      operationId: delVideoChannel
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete a video channel
      tags:
        - Video Channels
    get:
      operationId: getVideoChannel
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoChannel"
          description: successful operation
      summary: Get a video channel
      tags:
        - Video Channels
    put:
      operationId: putVideoChannel
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoChannelUpdate"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update a video channel
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/avatar":
    delete:
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete channel avatar
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/avatar/pick":
    post:
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      requestBody:
        content:
          multipart/form-data:
            encoding:
              avatarfile:
                contentType: image/png, image/jpeg
            schema:
              properties:
                avatarfile:
                  description: The file to upload.
                  format: binary
                  type: string
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  avatars:
                    items:
                      $ref: "#/components/schemas/ActorImage"
                    type: array
                type: object
          description: successful operation
        "413":
          description: image file too large
          headers:
            X-File-Maximum-Size:
              description: Maximum file size for the avatar
              schema:
                format: Nginx size
                type: string
      security:
        - OAuth2: []
      summary: Update channel avatar
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/banner":
    delete:
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete channel banner
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/banner/pick":
    post:
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      requestBody:
        content:
          multipart/form-data:
            encoding:
              bannerfile:
                contentType: image/png, image/jpeg
            schema:
              properties:
                bannerfile:
                  description: The file to upload.
                  format: binary
                  type: string
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  banners:
                    items:
                      $ref: "#/components/schemas/ActorImage"
                    type: array
                type: object
          description: successful operation
        "413":
          description: image file too large
          headers:
            X-File-Maximum-Size:
              description: Maximum file size for the banner
              schema:
                format: Nginx size
                type: string
      security:
        - OAuth2: []
      summary: Update channel banner
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/followers":
    get:
      operationId: getVideoChannelFollowers
      parameters:
        - $ref: "#/components/parameters/channelHandle"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/followersSort"
        - $ref: "#/components/parameters/search"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/Follow"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: List followers of a video channel
      tags:
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/import-videos":
    post:
      description: Import a remote channel/playlist videos into a channel
      parameters:
        - $ref: "#/components/parameters/channelHandle"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportVideosInChannelCreate"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Import videos in channel
      tags:
        - Video Channels
        - Channels Sync
  "/api/v1/video-channels/{channelHandle}/video-playlists":
    get:
      parameters:
        - $ref: "#/components/parameters/channelHandle"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/videoPlaylistType"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoPlaylist"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List playlists of a channel
      tags:
        - Video Playlists
        - Video Channels
  "/api/v1/video-channels/{channelHandle}/videos":
    get:
      operationId: getVideoChannelVideos
      parameters:
        - $ref: "#/components/parameters/channelHandle"
        - $ref: "#/components/parameters/categoryOneOf"
        - $ref: "#/components/parameters/isLive"
        - $ref: "#/components/parameters/tagsOneOf"
        - $ref: "#/components/parameters/tagsAllOf"
        - $ref: "#/components/parameters/licenceOneOf"
        - $ref: "#/components/parameters/languageOneOf"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
        - $ref: "#/components/parameters/skipCount"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/videosSort"
        - $ref: "#/components/parameters/excludeAlreadyWatched"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      summary: List videos of a video channel
      tags:
        - Video
        - Video Channels
  /api/v1/video-playlists:
    get:
      operationId: getPlaylists
      parameters:
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/videoPlaylistType"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoPlaylist"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List video playlists
      tags:
        - Video Playlists
    post:
      description: If the video playlist is set as public, `videoChannelId` is mandatory.
      operationId: addPlaylist
      requestBody:
        content:
          multipart/form-data:
            encoding:
              thumbnailfile:
                contentType: image/jpeg
            schema:
              properties:
                description:
                  description: Video playlist description
                  maxLength: 1000
                  minLength: 3
                  type: string
                displayName:
                  description: Video playlist display name
                  maxLength: 120
                  minLength: 1
                  type: string
                privacy:
                  $ref: "#/components/schemas/VideoPlaylistPrivacySet"
                thumbnailfile:
                  description: Video playlist thumbnail file
                  format: binary
                  type: string
                videoChannelId:
                  allOf:
                    - $ref: "#/components/schemas/id"
                  description: Video channel in which the playlist will be published
              required:
                - displayName
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoPlaylist:
                    properties:
                      id:
                        $ref: "#/components/schemas/VideoPlaylist/properties/id"
                      shortUUID:
                        $ref: "#/components/schemas/VideoPlaylist/properties/shortUUID"
                      uuid:
                        $ref: "#/components/schemas/VideoPlaylist/properties/uuid"
                    type: object
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: Create a video playlist
      tags:
        - Video Playlists
  /api/v1/video-playlists/privacies:
    get:
      operationId: getPlaylistPrivacyPolicies
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/video-playlists/privacies
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      summary: List available playlist privacy policies
      tags:
        - Video Playlists
  "/api/v1/video-playlists/{playlistId}":
    delete:
      parameters:
        - $ref: "#/components/parameters/playlistId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete a video playlist
      tags:
        - Video Playlists
    get:
      parameters:
        - $ref: "#/components/parameters/playlistId"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoPlaylist"
          description: successful operation
      summary: Get a video playlist
      tags:
        - Video Playlists
    put:
      description: If the video playlist is set as public, the playlist must have a assigned channel.
      parameters:
        - $ref: "#/components/parameters/playlistId"
      requestBody:
        content:
          multipart/form-data:
            encoding:
              thumbnailfile:
                contentType: image/jpeg
            schema:
              properties:
                description:
                  description: Video playlist description
                  type: string
                displayName:
                  description: Video playlist display name
                  maxLength: 120
                  minLength: 1
                  type: string
                privacy:
                  $ref: "#/components/schemas/VideoPlaylistPrivacySet"
                thumbnailfile:
                  description: Video playlist thumbnail file
                  format: binary
                  type: string
                videoChannelId:
                  allOf:
                    - $ref: "#/components/schemas/id"
                  description: Video channel in which the playlist will be published
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update a video playlist
      tags:
        - Video Playlists
  "/api/v1/video-playlists/{playlistId}/videos":
    get:
      operationId: getVideoPlaylistVideos
      parameters:
        - $ref: "#/components/parameters/playlistId"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      summary: List videos of a playlist
      tags:
        - Videos
        - Video Playlists
    post:
      operationId: addVideoPlaylistVideo
      parameters:
        - $ref: "#/components/parameters/playlistId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                startTimestamp:
                  description: Start the video at this specific timestamp
                  format: seconds
                  type: integer
                stopTimestamp:
                  description: Stop the video at this specific timestamp
                  format: seconds
                  type: integer
                videoId:
                  description: Video to add in the playlist
                  oneOf:
                    - $ref: "#/components/schemas/Video/properties/uuid"
                    - $ref: "#/components/schemas/Video/properties/id"
              required:
                - videoId
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  videoPlaylistElement:
                    properties:
                      id:
                        example: 2
                        type: integer
                    type: object
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: Add a video in a playlist
      tags:
        - Videos
        - Video Playlists
  "/api/v1/video-playlists/{playlistId}/videos/reorder":
    post:
      operationId: reorderVideoPlaylist
      parameters:
        - $ref: "#/components/parameters/playlistId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                insertAfterPosition:
                  description: New position for the block to reorder, to add the block before the first element
                  minimum: 0
                  type: integer
                reorderLength:
                  description: How many element from `startPosition` to reorder
                  minimum: 1
                  type: integer
                startPosition:
                  description: Start position of the element to reorder
                  minimum: 1
                  type: integer
              required:
                - startPosition
                - insertAfterPosition
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Reorder a playlist
      tags:
        - Video Playlists
  "/api/v1/video-playlists/{playlistId}/videos/{playlistElementId}":
    delete:
      operationId: delVideoPlaylistVideo
      parameters:
        - $ref: "#/components/parameters/playlistId"
        - $ref: "#/components/parameters/playlistElementId"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete an element from a playlist
      tags:
        - Video Playlists
    put:
      operationId: putVideoPlaylistVideo
      parameters:
        - $ref: "#/components/parameters/playlistId"
        - $ref: "#/components/parameters/playlistElementId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                startTimestamp:
                  description: Start the video at this specific timestamp
                  format: seconds
                  type: integer
                stopTimestamp:
                  description: Stop the video at this specific timestamp
                  format: seconds
                  type: integer
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update a playlist element
      tags:
        - Video Playlists
  /api/v1/videos:
    get:
      operationId: getVideos
      parameters:
        - $ref: "#/components/parameters/categoryOneOf"
        - $ref: "#/components/parameters/isLive"
        - $ref: "#/components/parameters/tagsOneOf"
        - $ref: "#/components/parameters/tagsAllOf"
        - $ref: "#/components/parameters/licenceOneOf"
        - $ref: "#/components/parameters/languageOneOf"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
        - $ref: "#/components/parameters/skipCount"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/videosSort"
        - $ref: "#/components/parameters/excludeAlreadyWatched"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoListResponse"
          description: successful operation
      summary: List videos
      tags:
        - Video
  /api/v1/videos/blacklist:
    get:
      operationId: getVideoBlocks
      parameters:
        - description: |
            list only blocks that match this type:
            - `1`: manual block
            - `2`: automatic block that needs review
          in: query
          name: type
          schema:
            enum:
              - 1
              - 2
            type: integer
        - description: plain search that will match with video titles, and more
          in: query
          name: search
          schema:
            type: string
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/blacklistsSort"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoBlacklist"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: List video blocks
      tags:
        - Video Blocks
  /api/v1/videos/categories:
    get:
      operationId: getCategories
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/videos/categories
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      summary: List available video categories
      tags:
        - Video
  /api/v1/videos/imports:
    post:
      description: Import a torrent or magnetURI or HTTP resource (if enabled by the instance administrator)
      operationId: importVideo
      requestBody:
        content:
          multipart/form-data:
            encoding:
              previewfile:
                contentType: image/jpeg
              thumbnailfile:
                contentType: image/jpeg
              torrentfile:
                contentType: application/x-bittorrent
            schema:
              $ref: "#/components/schemas/VideoCreateImport"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoUploadResponse"
          description: successful operation
        "400":
          description: "`magnetUri` or `targetUrl` or a torrent file missing"
        "403":
          description: video didn't pass pre-import filter
        "409":
          description: HTTP or Torrent/magnetURI import not enabled
      security:
        - OAuth2: []
      summary: Import a video
      tags:
        - Video Imports
        - Video Upload
  "/api/v1/videos/imports/{id}":
    delete:
      description: Delete ended video import
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete video import
      tags:
        - Video Imports
  "/api/v1/videos/imports/{id}/cancel":
    post:
      description: Cancel a pending video import
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Cancel video import
      tags:
        - Video Imports
  /api/v1/videos/languages:
    get:
      operationId: getLanguages
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/videos/languages
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      summary: List available video languages
      tags:
        - Video
  /api/v1/videos/licences:
    get:
      operationId: getLicences
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/videos/licences
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      summary: List available video licences
      tags:
        - Video
  /api/v1/videos/live:
    post:
      operationId: addLive
      requestBody:
        content:
          multipart/form-data:
            encoding:
              previewfile:
                contentType: image/jpeg
              thumbnailfile:
                contentType: image/jpeg
            schema:
              properties:
                category:
                  $ref: "#/components/schemas/VideoCategorySet"
                channelId:
                  description: Channel id that will contain this live video
                  type: integer
                commentsEnabled:
                  description: Enable or disable comments for this live video/replay
                  type: boolean
                description:
                  description: Live video/replay description
                  type: string
                downloadEnabled:
                  description: Enable or disable downloading for the replay of this live video
                  type: boolean
                language:
                  $ref: "#/components/schemas/VideoLanguageSet"
                latencyMode:
                  $ref: "#/components/schemas/LiveVideoLatencyMode"
                  description: User can select live latency mode if enabled by the instance
                licence:
                  $ref: "#/components/schemas/VideoLicenceSet"
                name:
                  description: Live video/replay name
                  maxLength: 120
                  minLength: 3
                  type: string
                nsfw:
                  description: Whether or not this live video/replay contains sensitive content
                  type: boolean
                permanentLive:
                  description: User can stream multiple times in a permanent live
                  type: boolean
                previewfile:
                  description: Live video/replay preview file
                  format: binary
                  type: string
                privacy:
                  $ref: "#/components/schemas/VideoPrivacySet"
                replaySettings:
                  $ref: "#/components/schemas/LiveVideoReplaySettings"
                saveReplay:
                  type: boolean
                support:
                  description: A text tell the audience how to support the creator
                  example: Please support our work on https://soutenir.framasoft.org/en/ <3
                  type: string
                tags:
                  description: Live video/replay tags (maximum 5 tags each between 2 and 30 characters)
                  items:
                    maxLength: 30
                    minLength: 2
                    type: string
                  maxItems: 5
                  minItems: 1
                  type: array
                thumbnailfile:
                  description: Live video/replay thumbnail file
                  format: binary
                  type: string
              required:
                - channelId
                - name
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoUploadResponse"
          description: successful operation
        "400":
          description: |
            Disambiguate via `type`:
            - default type for a validation error
            - `live_conflicting_permanent_and_save_replay` for conflicting parameters set
          x-summary: validation error, or conflicting `saveReplay` and `permanentLive` parameter set
        "403":
          description: |
            Disambiguate via `type`:
            - `live_not_enabled` for a disabled live feature
            - `live_not_allowing_replay` for a disabled replay feature
            - `max_instance_lives_limit_reached` for the absolute concurrent live limit
            - `max_user_lives_limit_reached` for the user concurrent live limit
          x-summary: live is not enabled, allow replay is not enabled, or max instance/user live videos limit is exceeded
      security:
        - OAuth2: []
      summary: Create a live
      tags:
        - Live Videos
        - Video
  "/api/v1/videos/live/{id}":
    get:
      operationId: getLiveId
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveVideoResponse"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get information about a live
      tags:
        - Live Videos
        - Video
    put:
      operationId: updateLiveId
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LiveVideoUpdate"
      responses:
        "204":
          description: successful operation
        "400":
          description: bad parameters or trying to update a live that has already started
        "403":
          description: trying to save replay of the live but saving replay is not enabled on the instance
      security:
        - OAuth2: []
      summary: Update information about a live
      tags:
        - Live Videos
        - Video
  "/api/v1/videos/live/{id}/sessions":
    get:
      description: List all sessions created in a particular live
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/LiveVideoSessionResponse"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      security:
        - OAuth2: []
      summary: List live sessions
      tags:
        - Live Videos
  /api/v1/videos/ownership:
    get:
      responses:
        "200":
          description: successful operation
      security:
        - OAuth2: []
      summary: List video ownership changes
      tags:
        - Video Ownership Change
  "/api/v1/videos/ownership/{id}/accept":
    post:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
        "403":
          description: cannot terminate an ownership change of another user
        "404":
          description: video ownership change not found
      security:
        - OAuth2: []
      summary: Accept ownership change request
      tags:
        - Video Ownership Change
  "/api/v1/videos/ownership/{id}/refuse":
    post:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
        "403":
          description: cannot terminate an ownership change of another user
        "404":
          description: video ownership change not found
      security:
        - OAuth2: []
      summary: Refuse ownership change request
      tags:
        - Video Ownership Change
  /api/v1/videos/privacies:
    get:
      operationId: getVideoPrivacyPolicies
      responses:
        "200":
          content:
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/api/v1/videos/privacies
              schema:
                items:
                  type: string
                type: array
          description: successful operation
      summary: List available video privacy policies
      tags:
        - Video
  /api/v1/videos/upload:
    post:
      description: Uses a single request to upload a video.
      operationId: uploadLegacy
      requestBody:
        content:
          multipart/form-data:
            encoding:
              previewfile:
                contentType: image/jpeg
              thumbnailfile:
                contentType: image/jpeg
              videofile:
                contentType: video/mp4, video/webm, video/ogg, video/avi, video/quicktime, video/x-msvideo, video/x-flv, video/x-matroska, application/octet-stream
            schema:
              $ref: "#/components/schemas/VideoUploadRequestLegacy"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoUploadResponse"
          description: successful operation
        "403":
          description: video didn't pass upload filter
        "408":
          description: upload has timed out
        "413":
          description: |
            If the response has no body, it means the reverse-proxy didn't let it through. Otherwise disambiguate via `type`:
            - `quota_reached` for quota limits whether daily or global
          headers:
            X-File-Maximum-Size:
              description: Maximum file size for the video
              schema:
                format: Nginx size
                type: string
          x-summary: video file too large, due to quota or max body size limit set by the reverse-proxy
        "415":
          description: video type unsupported
        "422":
          description: video unreadable
      security:
        - OAuth2: []
      summary: Upload a video
      tags:
        - Video
        - Video Upload
      x-codeSamples:
        - lang: Shell
          source: |
            ## DEPENDENCIES: jq
            USERNAME="<your_username>"
            PASSWORD="<your_password>"
            FILE_PATH="<your_file_path>"
            CHANNEL_ID="<your_channel_id>"
            NAME="<video_name>"
            API="https://peertube2.cpy.re/api/v1"

            ## AUTH
            client_id=$(curl -s "$API/oauth-clients/local" | jq -r ".client_id")
            client_secret=$(curl -s "$API/oauth-clients/local" | jq -r ".client_secret")
            token=$(curl -s "$API/users/token" \
              --data client_id="$client_id" \
              --data client_secret="$client_secret" \
              --data grant_type=password \
              --data username="$USERNAME" \
              --data password="$PASSWORD" \
              | jq -r ".access_token")

            ## VIDEO UPLOAD
            curl -s "$API/videos/upload" \
              -H "Authorization: Bearer $token" \
              --max-time 600 \
              --form videofile=@"$FILE_PATH" \
              --form channelId=$CHANNEL_ID \
              --form name="$NAME"
  /api/v1/videos/upload-resumable:
    delete:
      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to cancel the upload of a video
      operationId: uploadResumableCancel
      parameters:
        - description: |
            Created session id to proceed with. If you didn't send chunks in the last 12 hours, it is
            not valid anymore and the upload session has already been deleted with its data ;-)
          in: query
          name: upload_id
          required: true
          schema:
            type: string
        - in: header
          name: Content-Length
          required: true
          schema:
            example: 0
            type: number
      responses:
        "204":
          description: upload cancelled
          headers:
            Content-Length:
              schema:
                example: 0
                type: number
        "404":
          description: upload not found
      security:
        - OAuth2: []
      summary: Cancel the resumable upload of a video, deleting any data uploaded so far
      tags:
        - Video
        - Video Upload
    post:
      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to initialize the upload of a video
      operationId: uploadResumableInit
      parameters:
        - description: Number of bytes that will be uploaded in subsequent requests. Set this value to the size of the file you are uploading.
          in: header
          name: X-Upload-Content-Length
          required: true
          schema:
            example: 2469036
            type: number
        - description: MIME type of the file that you are uploading. Depending on your instance settings, acceptable values might vary.
          in: header
          name: X-Upload-Content-Type
          required: true
          schema:
            example: video/mp4
            format: mimetype
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VideoUploadRequestResumable"
      responses:
        "200":
          description: file already exists, send a [`resume`](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) request instead
        "201":
          description: created
          headers:
            Content-Length:
              schema:
                example: 0
                type: number
            Location:
              schema:
                example: /api/v1/videos/upload-resumable?upload_id=471e97554f21dec3b8bb5d4602939c51
                format: url
                type: string
        "413":
          description: |
            Disambiguate via `type`:
            - `max_file_size_reached` for the absolute file size limit
            - `quota_reached` for quota limits whether daily or global
          x-summary: video file too large, due to quota, absolute max file size or concurrent partial upload limit
        "415":
          description: video type unsupported
      security:
        - OAuth2: []
      summary: Initialize the resumable upload of a video
      tags:
        - Video
        - Video Upload
    put:
      description: Uses [a resumable protocol](https://github.com/kukhariev/node-uploadx/blob/master/proto.md) to continue, pause or resume the upload of a video
      operationId: uploadResumable
      parameters:
        - description: |
            Created session id to proceed with. If you didn't send chunks in the last hour, it is
            not valid anymore and you need to initialize a new upload.
          in: query
          name: upload_id
          required: true
          schema:
            type: string
        - description: |
            Specifies the bytes in the file that the request is uploading.

            For example, a value of `bytes 0-262143/1000000` shows that the request is sending the first
            262144 bytes (256 x 1024) in a 2,469,036 byte file.
          in: header
          name: Content-Range
          required: true
          schema:
            example: bytes 0-262143/2469036
            type: string
        - description: |
            Size of the chunk that the request is sending.

            Remember that larger chunks are more efficient. PeerTube's web client uses chunks varying from
            1048576 bytes (~1MB) and increases or reduces size depending on connection health.
          in: header
          name: Content-Length
          required: true
          schema:
            example: 262144
            type: number
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoUploadResponse"
          description: last chunk received
          headers:
            Content-Length:
              schema:
                type: number
        "308":
          description: resume incomplete
          headers:
            Content-Length:
              schema:
                example: 0
                type: number
            Range:
              schema:
                example: bytes=0-262143
                type: string
        "403":
          description: video didn't pass upload filter
        "404":
          description: upload not found
        "409":
          description: chunk doesn't match range
        "422":
          description: video unreadable
        "429":
          description: too many concurrent requests
        "503":
          description: upload is already being processed
          headers:
            Retry-After:
              schema:
                example: 300
                type: number
      security:
        - OAuth2: []
      summary: Send chunk for the resumable upload of a video
      tags:
        - Video
        - Video Upload
  "/api/v1/videos/{id}":
    delete:
      operationId: delVideo
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Delete a video
      tags:
        - Video
    get:
      operationId: getVideo
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoDetails"
          description: successful operation
      summary: Get a video
      tags:
        - Video
    put:
      operationId: putVideo
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          multipart/form-data:
            encoding:
              previewfile:
                contentType: image/jpeg
              thumbnailfile:
                contentType: image/jpeg
            schema:
              properties:
                category:
                  $ref: "#/components/schemas/VideoCategorySet"
                commentsEnabled:
                  description: Enable or disable comments for this video
                  type: boolean
                description:
                  description: Video description
                  type: string
                downloadEnabled:
                  description: Enable or disable downloading for this video
                  type: boolean
                language:
                  $ref: "#/components/schemas/VideoLanguageSet"
                licence:
                  $ref: "#/components/schemas/VideoLicenceSet"
                name:
                  description: Video name
                  maxLength: 120
                  minLength: 3
                  type: string
                nsfw:
                  description: Whether or not this video contains sensitive content
                  type: boolean
                originallyPublishedAt:
                  description: Date when the content was originally published
                  format: date-time
                  type: string
                previewfile:
                  description: Video preview file
                  format: binary
                  type: string
                privacy:
                  $ref: "#/components/schemas/VideoPrivacySet"
                scheduleUpdate:
                  $ref: "#/components/schemas/VideoScheduledUpdate"
                support:
                  description: A text tell the audience how to support the video creator
                  example: Please support our work on https://soutenir.framasoft.org/en/ <3
                  type: string
                tags:
                  description: Video tags (maximum 5 tags each between 2 and 30 characters)
                  items:
                    maxLength: 30
                    minLength: 2
                    type: string
                  maxItems: 5
                  minItems: 1
                  type: array
                thumbnailfile:
                  description: Video thumbnail file
                  format: binary
                  type: string
                waitTranscoding:
                  description: Whether or not we wait transcoding before publish the video
                  type: string
              type: object
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Update a video
      tags:
        - Video
  "/api/v1/videos/{id}/blacklist":
    delete:
      operationId: delVideoBlock
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
        "404":
          description: block not found
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Unblock a video by its id
      tags:
        - Video Blocks
    post:
      operationId: addVideoBlock
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2:
            - admin
            - moderator
      summary: Block a video
      tags:
        - Video Blocks
  "/api/v1/videos/{id}/captions":
    get:
      operationId: getVideoCaptions
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: "#/components/schemas/VideoCaption"
                    type: array
                  total:
                    example: 1
                    type: integer
                type: object
          description: successful operation
      summary: List captions of a video
      tags:
        - Video Captions
  "/api/v1/videos/{id}/captions/{captionLanguage}":
    delete:
      operationId: delVideoCaption
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/captionLanguage"
      responses:
        "204":
          description: successful operation
        "404":
          description: video or language or caption for that language not found
      security:
        - OAuth2:
            - user
      summary: Delete a video caption
      tags:
        - Video Captions
    put:
      operationId: addVideoCaption
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/captionLanguage"
      requestBody:
        content:
          multipart/form-data:
            encoding:
              captionfile:
                contentType: text/vtt, application/x-subrip, text/plain
            schema:
              properties:
                captionfile:
                  description: The file to upload.
                  format: binary
                  type: string
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: video or language not found
      security:
        - OAuth2:
            - user
      summary: Add or replace a video caption
      tags:
        - Video Captions
  "/api/v1/videos/{id}/comment-threads":
    get:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/start"
        - $ref: "#/components/parameters/count"
        - $ref: "#/components/parameters/commentsSort"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentThreadResponse"
          description: successful operation
      summary: List threads of a video
      tags:
        - Video Comments
    post:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                text:
                  allOf:
                    - $ref: "#/components/schemas/VideoComment/properties/text"
                  format: markdown
                  maxLength: 10000
              required:
                - text
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentThreadPostResponse"
          description: successful operation
        "404":
          description: video does not exist
      security:
        - OAuth2: []
      summary: Create a thread
      tags:
        - Video Comments
  "/api/v1/videos/{id}/comment-threads/{threadId}":
    get:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/threadId"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoCommentThreadTree"
          description: successful operation
      summary: Get a thread
      tags:
        - Video Comments
  "/api/v1/videos/{id}/comments/{commentId}":
    delete:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/commentId"
      responses:
        "204":
          description: successful operation
        "403":
          description: cannot remove comment of another user
        "404":
          description: comment or video does not exist
        "409":
          description: comment is already deleted
      security:
        - OAuth2: []
      summary: Delete a comment or a reply
      tags:
        - Video Comments
    post:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - $ref: "#/components/parameters/commentId"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                text:
                  allOf:
                    - $ref: "#/components/schemas/VideoComment/properties/text"
                  format: markdown
                  maxLength: 10000
              required:
                - text
              type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentThreadPostResponse"
          description: successful operation
        "404":
          description: thread or video does not exist
      security:
        - OAuth2: []
      summary: Reply to a thread of a video
      tags:
        - Video Comments
  "/api/v1/videos/{id}/description":
    get:
      operationId: getVideoDesc
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                example: |
                  **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
                maxLength: 10000
                minLength: 3
                nullable: true
                type: string
          description: successful operation
      summary: Get complete video description
      tags:
        - Video
  "/api/v1/videos/{id}/give-ownership":
    post:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                username:
                  type: string
              required:
                - username
              type: object
        required: true
      responses:
        "204":
          description: successful operation
        "400":
          description: changing video ownership to a remote account is not supported yet
        "404":
          description: video not found
      security:
        - OAuth2: []
      summary: Request ownership change
      tags:
        - Video Ownership Change
  "/api/v1/videos/{id}/hls":
    delete:
      operationId: delVideoHLS
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
        "404":
          description: video does not exist
      security:
        - OAuth2:
            - admin
      summary: Delete video HLS files
      tags:
        - Video Files
  "/api/v1/videos/{id}/live-session":
    get:
      description: If the video is a replay of a live, you can find the associated live session using this endpoint
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveVideoSessionResponse"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get live session of a replay
      tags:
        - Live Videos
  "/api/v1/videos/{id}/rate":
    put:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                rating:
                  enum:
                    - like
                    - dislike
                  type: string
              required:
                - rating
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: video does not exist
      security:
        - OAuth2: []
      summary: Like/dislike a video
      tags:
        - Video Rates
  "/api/v1/videos/{id}/source":
    post:
      operationId: getVideoSource
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoSource"
          description: successful operation
      summary: Get video source file metadata
      tags:
        - Video
  "/api/v1/videos/{id}/stats/overall":
    get:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - description: Filter stats by start date
          in: query
          name: startDate
          schema:
            format: date-time
            type: string
        - description: Filter stats by end date
          in: query
          name: endDate
          schema:
            format: date-time
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoStatsOverall"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get overall stats of a video
      tags:
        - Video Stats
  "/api/v1/videos/{id}/stats/retention":
    get:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoStatsRetention"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get retention stats of a video
      tags:
        - Video Stats
  "/api/v1/videos/{id}/stats/timeseries/{metric}":
    get:
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
        - description: The metric to get
          in: path
          name: metric
          required: true
          schema:
            enum:
              - viewers
              - aggregateWatchTime
            type: string
        - description: Filter stats by start date
          in: query
          name: startDate
          schema:
            format: date-time
            type: string
        - description: Filter stats by end date
          in: query
          name: endDate
          schema:
            format: date-time
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoStatsTimeserie"
          description: successful operation
      security:
        - OAuth2: []
      summary: Get timeserie stats of a video
      tags:
        - Video Stats
  "/api/v1/videos/{id}/studio/edit":
    post:
      description: Create a task to edit a video  (cut, add intro/outro etc)
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/VideoStudioCreateTask"
        required: true
      responses:
        "204":
          description: successful operation
        "400":
          description: incorrect parameters
        "404":
          description: video not found
      security:
        - OAuth2: []
      summary: Create a studio task
      tags:
        - Video Transcoding
        - Video
  "/api/v1/videos/{id}/token":
    post:
      description: Request special tokens that expire quickly to use them in some context (like accessing private static files)
      operationId: requestVideoToken
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoTokenResponse"
          description: successful operation
        "400":
          description: incorrect parameters
        "404":
          description: video not found
      security:
        - OAuth2: []
      summary: Request video token
      tags:
        - Video
  "/api/v1/videos/{id}/transcoding":
    post:
      operationId: createVideoTranscoding
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                transcodingType:
                  enum:
                    - hls
                    - webtorrent
                  type: string
              required:
                - transcodingType
              type: object
      responses:
        "204":
          description: successful operation
        "404":
          description: video does not exist
      security:
        - OAuth2:
            - admin
      summary: Create a transcoding job
      tags:
        - Video Transcoding
  "/api/v1/videos/{id}/views":
    post:
      description: Call this endpoint regularly (every 5-10 seconds for example) to notify the server the user is watching the video. After a while, PeerTube will increase video's viewers counter. If the user is authenticated, PeerTube will also store the current player time.
      operationId: addView
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserViewingVideo"
        required: true
      responses:
        "204":
          description: successful operation
      summary: Notify user is watching a video
      tags:
        - Video
  "/api/v1/videos/{id}/watching":
    put:
      deprecated: true
      description: This endpoint has been deprecated. Use `/videos/{id}/views` instead
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserViewingVideo"
        required: true
      responses:
        "204":
          description: successful operation
      security:
        - OAuth2: []
      summary: Set watching progress of a video
      tags:
        - Video
  "/api/v1/videos/{id}/webtorrent":
    delete:
      operationId: delVideoWebTorrent
      parameters:
        - $ref: "#/components/parameters/idOrUUID"
      responses:
        "204":
          description: successful operation
        "404":
          description: video does not exist
      security:
        - OAuth2:
            - admin
      summary: Delete video WebTorrent files
      tags:
        - Video Files
  "/feeds/subscriptions.{format}":
    get:
      operationId: getSyndicatedSubscriptionVideos
      parameters:
        - description: format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))
          in: path
          name: format
          required: true
          schema:
            enum:
              - xml
              - rss
              - rss2
              - atom
              - atom1
              - json
              - json1
            type: string
        - description: limit listing to a specific account
          in: query
          name: accountId
          required: true
          schema:
            type: string
        - description: private token allowing access
          in: query
          name: token
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
      responses:
        "204":
          content:
            application/atom+xml:
              schema:
                $ref: "#/components/schemas/VideosForXML"
            application/json:
              schema:
                type: object
            application/rss+xml:
              schema:
                $ref: "#/components/schemas/VideosForXML"
            application/xml:
              schema:
                $ref: "#/components/schemas/VideosForXML"
            text/xml:
              schema:
                $ref: "#/components/schemas/VideosForXML"
          description: successful operation
          headers:
            Cache-Control:
              schema:
                default: max-age=900
                type: string
        "406":
          description: accept header unsupported
      summary: List videos of subscriptions tied to a token
      tags:
        - Video Feeds
  "/feeds/video-comments.{format}":
    get:
      operationId: getSyndicatedComments
      parameters:
        - description: format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))
          in: path
          name: format
          required: true
          schema:
            enum:
              - xml
              - rss
              - rss2
              - atom
              - atom1
              - json
              - json1
            type: string
        - description: limit listing to a specific video
          in: query
          name: videoId
          schema:
            type: string
        - description: limit listing to a specific account
          in: query
          name: accountId
          schema:
            type: string
        - description: limit listing to a specific account
          in: query
          name: accountName
          schema:
            type: string
        - description: limit listing to a specific video channel
          in: query
          name: videoChannelId
          schema:
            type: string
        - description: limit listing to a specific video channel
          in: query
          name: videoChannelName
          schema:
            type: string
      responses:
        "204":
          content:
            application/atom+xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/video-comments.atom?filter=local
              schema:
                $ref: "#/components/schemas/VideoCommentsForXML"
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/video-comments.json?filter=local
              schema:
                type: object
            application/rss+xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/video-comments.rss?filter=local
              schema:
                $ref: "#/components/schemas/VideoCommentsForXML"
            application/xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
              schema:
                $ref: "#/components/schemas/VideoCommentsForXML"
            text/xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/video-comments.xml?filter=local
              schema:
                $ref: "#/components/schemas/VideoCommentsForXML"
          description: successful operation
          headers:
            Cache-Control:
              schema:
                default: max-age=900
                type: string
        "400":
          description: |
            Arises when:
              - videoId filter is mixed with a channel filter
          x-summary: field inconsistencies
        "404":
          description: video, video channel or account not found
        "406":
          description: accept header unsupported
      summary: List comments on videos
      tags:
        - Video Feeds
  "/feeds/videos.{format}":
    get:
      operationId: getSyndicatedVideos
      parameters:
        - description: format expected (we focus on making `rss` the most featureful ; it serves [Media RSS](https://www.rssboard.org/media-rss))
          in: path
          name: format
          required: true
          schema:
            enum:
              - xml
              - rss
              - rss2
              - atom
              - atom1
              - json
              - json1
            type: string
        - description: limit listing to a specific account
          in: query
          name: accountId
          schema:
            type: string
        - description: limit listing to a specific account
          in: query
          name: accountName
          schema:
            type: string
        - description: limit listing to a specific video channel
          in: query
          name: videoChannelId
          schema:
            type: string
        - description: limit listing to a specific video channel
          in: query
          name: videoChannelName
          schema:
            type: string
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/nsfw"
        - $ref: "#/components/parameters/isLocal"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/privacyOneOf"
        - $ref: "#/components/parameters/hasHLSFiles"
        - $ref: "#/components/parameters/hasWebtorrentFiles"
      responses:
        "204":
          content:
            application/atom+xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/videos.atom?filter=local
              schema:
                $ref: "#/components/schemas/VideosForXML"
            application/json:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/videos.json?filter=local
              schema:
                type: object
            application/rss+xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/videos.rss?filter=local
              schema:
                $ref: "#/components/schemas/VideosForXML"
            application/xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
              schema:
                $ref: "#/components/schemas/VideosForXML"
            text/xml:
              examples:
                nightly:
                  externalValue: https://peertube2.cpy.re/feeds/videos.xml?filter=local
              schema:
                $ref: "#/components/schemas/VideosForXML"
          description: successful operation
          headers:
            Cache-Control:
              schema:
                default: max-age=900
                type: string
        "404":
          description: video channel or account not found
        "406":
          description: accept header unsupported
      summary: List videos
      tags:
        - Video Feeds
  "/static/streaming-playlists/hls/private/{filename}":
    get:
      parameters:
        - $ref: "#/components/parameters/staticFilename"
        - $ref: "#/components/parameters/videoFileToken"
        - $ref: "#/components/parameters/reinjectVideoFileToken"
      responses:
        "200":
          description: successful operation
        "403":
          description: invalid auth
        "404":
          description: not found
      security:
        - OAuth2: []
      summary: Get private HLS video file
      tags:
        - Static Video Files
  "/static/streaming-playlists/hls/{filename}":
    get:
      parameters:
        - $ref: "#/components/parameters/staticFilename"
      responses:
        "200":
          description: successful operation
        "403":
          description: invalid auth
        "404":
          description: not found
      security:
        - OAuth2: []
      summary: Get public HLS video file
      tags:
        - Static Video Files
  "/static/webseed/private/{filename}":
    get:
      parameters:
        - $ref: "#/components/parameters/staticFilename"
        - $ref: "#/components/parameters/videoFileToken"
      responses:
        "200":
          description: successful operation
        "403":
          description: invalid auth
        "404":
          description: not found
      security:
        - OAuth2: []
      summary: Get private WebTorrent video file
      tags:
        - Static Video Files
  "/static/webseed/{filename}":
    get:
      parameters:
        - $ref: "#/components/parameters/staticFilename"
      responses:
        "200":
          description: successful operation
        "404":
          description: not found
      summary: Get public WebTorrent video file
      tags:
        - Static Video Files
components:
  callbacks:
    searchIndex:
      https://search.example.org/api/v1/search/videos:
        post:
          responses:
            "200":
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/VideoListResponse"
              description: successful operation
          summary: third-party search index MAY be used instead of the local index, if enabled by the instance admin. see `searchTarget`
  parameters:
    abuseId:
      description: Abuse id
      in: path
      name: abuseId
      required: true
      schema:
        $ref: "#/components/schemas/Abuse/properties/id"
    abuseMessageId:
      description: Abuse message id
      in: path
      name: abuseMessageId
      required: true
      schema:
        $ref: "#/components/schemas/AbuseMessage/properties/id"
    abusesSort:
      description: Sort abuses by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - -id
          - -createdAt
          - -state
        type: string
    actorType:
      in: query
      name: actorType
      schema:
        enum:
          - Person
          - Application
          - Group
          - Service
          - Organization
        type: string
    blacklistsSort:
      description: Sort blocklists by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - -id
          - name
          - -duration
          - -views
          - -likes
          - -dislikes
          - -uuid
          - -createdAt
        type: string
    captionLanguage:
      description: The caption language
      in: path
      name: captionLanguage
      required: true
      schema:
        $ref: "#/components/schemas/VideoLanguageSet"
    categoryOneOf:
      description: category id of the video (see [/videos/categories](#operation/getCategories))
      explode: false
      in: query
      name: categoryOneOf
      required: false
      schema:
        oneOf:
          - $ref: "#/components/schemas/VideoCategorySet"
          - items:
              $ref: "#/components/schemas/VideoCategorySet"
            type: array
      style: form
    channelHandle:
      description: The video channel handle
      in: path
      name: channelHandle
      required: true
      schema:
        example: my_username | my_username@example.com
        type: string
    channelSyncId:
      description: Channel Sync id
      in: path
      name: channelSyncId
      required: true
      schema:
        $ref: "#/components/schemas/Abuse/properties/id"
    commentId:
      description: The comment id
      in: path
      name: commentId
      required: true
      schema:
        $ref: "#/components/schemas/VideoComment/properties/id"
    commentsSort:
      description: Sort comments by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - -createdAt
          - -totalReplies
        type: string
    count:
      description: Number of items to return
      in: query
      name: count
      required: false
      schema:
        default: 15
        maximum: 100
        minimum: 1
        type: integer
    excludeAlreadyWatched:
      description: Whether or not to exclude videos that are in the user's video history
      in: query
      name: excludeAlreadyWatched
      schema:
        type: boolean
    followState:
      in: query
      name: state
      schema:
        enum:
          - pending
          - accepted
        type: string
    followersSort:
      description: Sort followers by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - createdAt
        type: string
    hasHLSFiles:
      description: "**PeerTube >= 4.0** Display only videos that have HLS files"
      in: query
      name: hasHLSFiles
      required: false
      schema:
        type: boolean
    hasWebtorrentFiles:
      description: "**PeerTube >= 4.0** Display only videos that have WebTorrent files"
      in: query
      name: hasWebtorrentFiles
      required: false
      schema:
        type: boolean
    id:
      description: Entity id
      in: path
      name: id
      required: true
      schema:
        $ref: "#/components/schemas/id"
    idOrUUID:
      description: The object id, uuid or short uuid
      in: path
      name: id
      required: true
      schema:
        oneOf:
          - $ref: "#/components/schemas/id"
          - $ref: "#/components/schemas/UUIDv4"
          - $ref: "#/components/schemas/shortUUID"
    include:
      description: |
        **PeerTube >= 4.0** Include additional videos in results (can be combined using bitwise or operator)
        - `0` NONE
        - `1` NOT_PUBLISHED_STATE
        - `2` BLACKLISTED
        - `4` BLOCKED_OWNER
        - `8` FILES
      in: query
      name: include
      required: false
      schema:
        enum:
          - 0
          - 1
          - 2
          - 4
          - 8
        type: integer
    isLive:
      description: whether or not the video is a live
      in: query
      name: isLive
      required: false
      schema:
        type: boolean
    isLocal:
      description: "**PeerTube >= 4.0** Display only local or remote videos"
      in: query
      name: isLocal
      required: false
      schema:
        type: boolean
    jobType:
      description: job type
      in: query
      name: jobType
      required: false
      schema:
        enum:
          - activitypub-follow
          - activitypub-http-broadcast
          - activitypub-http-fetcher
          - activitypub-http-unicast
          - email
          - video-transcoding
          - video-file-import
          - video-import
          - videos-views-stats
          - activitypub-refresher
          - video-redundancy
          - video-live-ending
          - video-channel-import
        type: string
    languageOneOf:
      description: language id of the video (see [/videos/languages](#operation/getLanguages)). Use `_unknown` to filter on videos that don't have a video language
      explode: false
      in: query
      name: languageOneOf
      required: false
      schema:
        oneOf:
          - $ref: "#/components/schemas/VideoLanguageSet"
          - items:
              $ref: "#/components/schemas/VideoLanguageSet"
            type: array
      style: form
    licenceOneOf:
      description: licence id of the video (see [/videos/licences](#operation/getLicences))
      explode: false
      in: query
      name: licenceOneOf
      required: false
      schema:
        oneOf:
          - $ref: "#/components/schemas/VideoLicenceSet"
          - items:
              $ref: "#/components/schemas/VideoLicenceSet"
            type: array
      style: form
    name:
      description: The username or handle of the account
      in: path
      name: name
      required: true
      schema:
        example: chocobozzz | chocobozzz@example.org
        type: string
    npmName:
      description: name of the plugin/theme on npmjs.com or in its package.json
      in: path
      name: npmName
      required: true
      schema:
        example: peertube-plugin-auth-ldap
        type: string
    nsfw:
      description: whether to include nsfw videos, if any
      in: query
      name: nsfw
      required: false
      schema:
        enum:
          - "true"
          - "false"
        type: string
    playlistElementId:
      description: Playlist element id
      in: path
      name: playlistElementId
      required: true
      schema:
        $ref: "#/components/schemas/id"
    playlistId:
      description: Playlist id
      in: path
      name: playlistId
      required: true
      schema:
        $ref: "#/components/schemas/VideoPlaylist/properties/id"
    privacyOneOf:
      description: "**PeerTube >= 4.0** Display only videos in this specific privacy/privacies"
      in: query
      name: privacyOneOf
      required: false
      schema:
        $ref: "#/components/schemas/VideoPrivacySet"
    registrationId:
      description: Registration ID
      in: path
      name: registrationId
      required: true
      schema:
        $ref: "#/components/schemas/id"
    reinjectVideoFileToken:
      description: Ask the server to reinject videoFileToken in URLs in m3u8 playlist
      in: query
      name: reinjectVideoFileToken
      required: false
      schema:
        type: boolean
    search:
      description: Plain text search, applied to various parts of the model depending on endpoint
      in: query
      name: search
      required: false
      schema:
        type: string
    searchTarget:
      description: |
        If the administrator enabled search index support, you can override the default search target.

        **Warning**: If you choose to make an index search, PeerTube will get results from a third party service. It means the instance may not yet know the objects you fetched. If you want to load video/channel information:
          * If the current user has the ability to make a remote URI search (this information is available in the config endpoint),
          then reuse the search API to make a search using the object URI so PeerTube instance fetches the remote object and fill its database.
          After that, you can use the classic REST API endpoints to fetch the complete object or interact with it
          * If the current user doesn't have the ability to make a remote URI search, then redirect the user on the origin instance or fetch
          the data from the origin instance API
      in: query
      name: searchTarget
      required: false
      schema:
        enum:
          - local
          - search-index
        type: string
    skipCount:
      description: if you don't need the `total` in the response
      in: query
      name: skipCount
      required: false
      schema:
        default: "false"
        enum:
          - "true"
          - "false"
        type: string
    sort:
      description: Sort column
      in: query
      name: sort
      required: false
      schema:
        example: -createdAt
        type: string
    start:
      description: Offset used to paginate results
      in: query
      name: start
      required: false
      schema:
        minimum: 0
        type: integer
    staticFilename:
      description: Filename
      in: path
      name: filename
      required: true
      schema:
        type: string
    subscriptionHandle:
      description: The subscription handle
      in: path
      name: subscriptionHandle
      required: true
      schema:
        example: my_username | my_username@example.com
        type: string
    subscriptionsUris:
      description: list of uris to check if each is part of the user subscriptions
      in: query
      name: uris
      required: true
      schema:
        items:
          format: uri
          type: string
        type: array
    tagsAllOf:
      description: tag(s) of the video, where all should be present in the video
      explode: false
      in: query
      name: tagsAllOf
      required: false
      schema:
        oneOf:
          - type: string
          - items:
              type: string
            type: array
      style: form
    tagsOneOf:
      description: tag(s) of the video
      explode: false
      in: query
      name: tagsOneOf
      required: false
      schema:
        oneOf:
          - type: string
          - items:
              type: string
            maxItems: 5
            type: array
      style: form
    threadId:
      description: The thread id (root comment id)
      in: path
      name: threadId
      required: true
      schema:
        type: integer
    usersBlocked:
      description: Filter results down to (un)banned users
      in: query
      name: blocked
      required: false
      schema:
        type: boolean
    usersSearch:
      description: Plain text search that will match with user usernames or emails
      in: query
      name: search
      required: false
      schema:
        type: string
    usersSort:
      description: Sort users by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - -id
          - -username
          - -createdAt
        type: string
    uuids:
      description: Find videos with specific UUIDs
      in: query
      name: uuids
      required: false
      schema:
        items:
          type: string
    videoFileToken:
      description: Video file token [generated](#operation/requestVideoToken) by PeerTube so you don't need to provide an OAuth token in the request header.
      in: query
      name: videoFileToken
      required: false
      schema:
        type: string
    videoPlaylistType:
      in: query
      name: playlistType
      required: false
      schema:
        $ref: "#/components/schemas/VideoPlaylistTypeSet"
    videoRedundanciesSort:
      description: Sort abuses by criteria
      in: query
      name: sort
      required: false
      schema:
        enum:
          - name
        type: string
    videosSearchSort:
      description: |
        Sort videos by criteria (prefixing with `-` means `DESC` order):
      in: query
      name: sort
      required: false
      schema:
        enum:
          - name
          - -duration
          - -createdAt
          - -publishedAt
          - -views
          - -likes
          - -match
        type: string
    videosSort:
      in: query
      name: sort
      required: false
      schema:
        description: |
          Sort videos by criteria (prefixing with `-` means `DESC` order):
            * `hot` - Adaptation of Reddit "hot" algorithm taking into account video views, likes, dislikes and comments and publication date
            * `best` - Same than `hot`, but also takes into account user video history
            * `trending` - Sort videos by recent views ("recent" is defined by the admin)
            * `views` - Sort videos using their `views` counter
            * `publishedAt` - Sort by video publication date (when it became publicly available)
        enum:
          - name
          - -duration
          - -createdAt
          - -publishedAt
          - -views
          - -likes
          - -trending
          - -hot
          - -best
        type: string
  schemas:
    Abuse:
      properties:
        createdAt:
          format: date-time
          type: string
        id:
          $ref: "#/components/schemas/id"
        moderationComment:
          example: Decided to ban the server since it spams us regularly
          maxLength: 3000
          minLength: 2
          type: string
        predefinedReasons:
          $ref: "#/components/schemas/AbusePredefinedReasons"
        reason:
          example: The video is a spam
          maxLength: 3000
          minLength: 2
          type: string
        reporterAccount:
          $ref: "#/components/schemas/Account"
        state:
          $ref: "#/components/schemas/AbuseStateConstant"
        video:
          $ref: "#/components/schemas/VideoInfo"
    AbuseMessage:
      properties:
        account:
          $ref: "#/components/schemas/AccountSummary"
        byModerator:
          type: boolean
        createdAt:
          format: date-time
          type: string
        id:
          $ref: "#/components/schemas/id"
        message:
          maxLength: 3000
          minLength: 2
          type: string
    AbusePredefinedReasons:
      example:
        - spamOrMisleading
      items:
        enum:
          - violentOrAbusive
          - hatefulOrAbusive
          - spamOrMisleading
          - privacy
          - rights
          - serverRules
          - thumbnails
          - captions
        type: string
      type: array
    AbuseStateConstant:
      properties:
        id:
          $ref: "#/components/schemas/AbuseStateSet"
        label:
          type: string
    AbuseStateSet:
      description: The abuse state (Pending = `1`, Rejected = `2`, Accepted = `3`)
      enum:
        - 1
        - 2
        - 3
      type: integer
    Account:
      allOf:
        - $ref: "#/components/schemas/Actor"
        - properties:
            description:
              description: text or bio displayed on the account's profile
              type: string
            displayName:
              description: editable name of the account, displayed in its representations
              maxLength: 120
              minLength: 3
              type: string
            userId:
              allOf:
                - $ref: "#/components/schemas/User/properties/id"
              description: object id for the user tied to this account
    AccountSummary:
      properties:
        avatars:
          items:
            $ref: "#/components/schemas/ActorImage"
          type: array
        displayName:
          type: string
        host:
          format: hostname
          type: string
        id:
          type: integer
        name:
          type: string
        url:
          format: url
          type: string
    Actor:
      properties:
        createdAt:
          format: date-time
          type: string
        followersCount:
          description: number of followers of this actor, as seen by this instance
          minimum: 0
          type: integer
        followingCount:
          description: number of actors subscribed to by this actor, as seen by this instance
          minimum: 0
          type: integer
        host:
          description: server on which the actor is resident
          format: hostname
          type: string
        hostRedundancyAllowed:
          description: whether this actor's host allows redundancy of its videos
          type: boolean
        id:
          $ref: "#/components/schemas/id"
        name:
          allOf:
            - $ref: "#/components/schemas/username"
          description: immutable name of the actor, used to find or mention it
        updatedAt:
          format: date-time
          type: string
        url:
          format: url
          type: string
    ActorImage:
      properties:
        createdAt:
          format: date-time
          type: string
        path:
          type: string
        updatedAt:
          format: date-time
          type: string
        width:
          type: integer
    ActorInfo:
      properties:
        avatars:
          items:
            $ref: "#/components/schemas/ActorImage"
          type: array
        displayName:
          type: string
        host:
          format: hostname
          type: string
        id:
          $ref: "#/components/schemas/id"
        name:
          type: string
    AddUser:
      properties:
        adminFlags:
          $ref: "#/components/schemas/UserAdminFlags"
        channelName:
          $ref: "#/components/schemas/usernameChannel"
        email:
          description: The user email
          format: email
          type: string
        password:
          $ref: "#/components/schemas/password"
        role:
          $ref: "#/components/schemas/UserRole"
        username:
          $ref: "#/components/schemas/username"
        videoQuota:
          description: The user video quota in bytes
          example: -1
          type: integer
        videoQuotaDaily:
          description: The user daily video quota in bytes
          example: -1
          type: integer
      required:
        - username
        - password
        - email
        - role
    AddUserResponse:
      properties:
        user:
          properties:
            account:
              properties:
                id:
                  $ref: "#/components/schemas/id"
              type: object
            id:
              $ref: "#/components/schemas/id"
          type: object
    BlockStatus:
      properties:
        accounts:
          additionalProperties:
            properties:
              blockedByServer:
                type: boolean
              blockedByUser:
                type: boolean
            type: object
            x-additionalPropertiesName: account
          type: object
        hosts:
          additionalProperties:
            properties:
              blockedByServer:
                type: boolean
              blockedByUser:
                type: boolean
            type: object
            x-additionalPropertiesName: host
          type: object
    CommentThreadPostResponse:
      properties:
        comment:
          $ref: "#/components/schemas/VideoComment"
    CommentThreadResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/VideoComment"
          maxItems: 100
          type: array
        total:
          example: 1
          type: integer
    CustomHomepage:
      properties:
        content:
          type: string
    FileRedundancyInformation:
      properties:
        createdAt:
          format: date-time
          type: string
        expiresOn:
          format: date-time
          type: string
        fileUrl:
          format: url
          type: string
        id:
          $ref: "#/components/schemas/id"
        size:
          type: integer
        strategy:
          enum:
            - manual
            - most-views
            - trending
            - recently-added
          type: string
        updatedAt:
          format: date-time
          type: string
    Follow:
      properties:
        createdAt:
          format: date-time
          type: string
        follower:
          $ref: "#/components/schemas/Actor"
        following:
          $ref: "#/components/schemas/Actor"
        id:
          $ref: "#/components/schemas/id"
        score:
          description: score reflecting the reachability of the actor, with steps of `10` and a base score of `1000`.
          type: number
        state:
          enum:
            - pending
            - accepted
          type: string
        updatedAt:
          format: date-time
          type: string
    GetMeVideoRating:
      properties:
        id:
          $ref: "#/components/schemas/id"
        rating:
          description: Rating of the video
          enum:
            - like
            - dislike
            - none
          type: string
      required:
        - id
        - rating
    ImportVideosInChannelCreate:
      properties:
        externalChannelUrl:
          example: https://youtube.com/c/UC_myfancychannel
          type: string
        videoChannelSyncId:
          description: If part of a channel sync process, specify its id to assign video imports to this channel synchronization
          type: integer
      required:
        - externalChannelUrl
      type: object
    Job:
      properties:
        createdAt:
          format: date-time
          type: string
        data:
          additionalProperties: true
          type: object
        error:
          additionalProperties: true
          type: object
        finishedOn:
          format: date-time
          type: string
        id:
          $ref: "#/components/schemas/id"
        processedOn:
          format: date-time
          type: string
        state:
          enum:
            - active
            - completed
            - failed
            - waiting
            - delayed
          type: string
        type:
          enum:
            - activitypub-http-unicast
            - activitypub-http-broadcast
            - activitypub-http-fetcher
            - activitypub-follow
            - video-file-import
            - video-transcoding
            - email
            - video-import
            - videos-views-stats
            - activitypub-refresher
            - video-redundancy
            - video-channel-import
          type: string
    LiveVideoLatencyMode:
      description: The live latency mode (Default = `1`, High latency = `2`, Small Latency = `3`)
      enum:
        - 1
        - 2
        - 3
      type: integer
    LiveVideoReplaySettings:
      properties:
        privacy:
          $ref: "#/components/schemas/VideoPrivacySet"
      type: object
    LiveVideoResponse:
      properties:
        latencyMode:
          $ref: "#/components/schemas/LiveVideoLatencyMode"
          description: User can select live latency mode if enabled by the instance
        permanentLive:
          description: User can stream multiple times in a permanent live
          type: boolean
        replaySettings:
          $ref: "#/components/schemas/LiveVideoReplaySettings"
        rtmpUrl:
          description: Included in the response if an appropriate token is provided
          type: string
        rtmpsUrl:
          description: Included in the response if an appropriate token is provided
          type: string
        saveReplay:
          type: boolean
        streamKey:
          description: RTMP stream key to use to stream into this live video. Included in the response if an appropriate token is provided
          type: string
    LiveVideoSessionResponse:
      properties:
        endDate:
          description: End date of the live session
          format: date-time
          nullable: true
          type: string
        error:
          description: |
            Error type if an error occurred during the live session:
              - `1`: Bad socket health (transcoding is too slow)
              - `2`: Max duration exceeded
              - `3`: Quota exceeded
              - `4`: Quota FFmpeg error
              - `5`: Video has been blacklisted during the live
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
          nullable: true
          type: integer
        id:
          type: integer
        replayVideo:
          description: Video replay information
          properties:
            id:
              type: number
            shortUUID:
              $ref: "#/components/schemas/shortUUID"
            uuid:
              $ref: "#/components/schemas/UUIDv4"
          type: object
        startDate:
          description: Start date of the live session
          format: date-time
          type: string
    LiveVideoUpdate:
      properties:
        latencyMode:
          $ref: "#/components/schemas/LiveVideoLatencyMode"
          description: User can select live latency mode if enabled by the instance
        permanentLive:
          description: User can stream multiple times in a permanent live
          type: boolean
        replaySettings:
          $ref: "#/components/schemas/LiveVideoReplaySettings"
        saveReplay:
          type: boolean
    MRSSGroupContent:
      properties:
        duration:
          type: integer
          xml:
            attribute: true
        fileSize:
          type: integer
          xml:
            attribute: true
        framerate:
          type: integer
          xml:
            attribute: true
        height:
          type: integer
          xml:
            attribute: true
        lang:
          type: string
          xml:
            attribute: true
        type:
          type: string
          xml:
            attribute: true
        url:
          format: url
          type: string
          xml:
            attribute: true
      type: object
      xml:
        name: media:content
    MRSSPeerLink:
      properties:
        href:
          type: string
          xml:
            attribute: true
        type:
          enum:
            - application/x-bittorrent
          type: string
          xml:
            attribute: true
      type: object
      xml:
        name: media:peerLink
    NSFWPolicy:
      enum:
        - display
        - blur
        - do_not_list
      type: string
    Notification:
      properties:
        account:
          allOf:
            - $ref: "#/components/schemas/ActorInfo"
          nullable: true
        actorFollow:
          nullable: true
          properties:
            follower:
              $ref: "#/components/schemas/ActorInfo"
            following:
              properties:
                displayName:
                  type: string
                host:
                  format: hostname
                  type: string
                name:
                  type: string
                type:
                  enum:
                    - account
                    - channel
                    - instance
                  type: string
              type: object
            id:
              $ref: "#/components/schemas/id"
            state:
              enum:
                - pending
                - accepted
              type: string
          type: object
        comment:
          nullable: true
          properties:
            account:
              $ref: "#/components/schemas/ActorInfo"
            id:
              $ref: "#/components/schemas/id"
            threadId:
              type: integer
            video:
              $ref: "#/components/schemas/VideoInfo"
          type: object
        createdAt:
          format: date-time
          type: string
        id:
          $ref: "#/components/schemas/id"
        read:
          type: boolean
        type:
          description: |
            Notification type, following the `UserNotificationType` enum:
            - `1` NEW_VIDEO_FROM_SUBSCRIPTION
            - `2` NEW_COMMENT_ON_MY_VIDEO
            - `3` NEW_ABUSE_FOR_MODERATORS
            - `4` BLACKLIST_ON_MY_VIDEO
            - `5` UNBLACKLIST_ON_MY_VIDEO
            - `6` MY_VIDEO_PUBLISHED
            - `7` MY_VIDEO_IMPORT_SUCCESS
            - `8` MY_VIDEO_IMPORT_ERROR
            - `9` NEW_USER_REGISTRATION
            - `10` NEW_FOLLOW
            - `11` COMMENT_MENTION
            - `12` VIDEO_AUTO_BLACKLIST_FOR_MODERATORS
            - `13` NEW_INSTANCE_FOLLOWER
            - `14` AUTO_INSTANCE_FOLLOWING
            - `15` ABUSE_STATE_CHANGE
            - `16` ABUSE_NEW_MESSAGE
            - `17` NEW_PLUGIN_VERSION
            - `18` NEW_PEERTUBE_VERSION
          type: integer
        updatedAt:
          format: date-time
          type: string
        video:
          allOf:
            - $ref: "#/components/schemas/VideoInfo"
            - properties:
                channel:
                  $ref: "#/components/schemas/ActorInfo"
              type: object
          nullable: true
        videoAbuse:
          nullable: true
          properties:
            id:
              $ref: "#/components/schemas/id"
            video:
              allOf:
                - $ref: "#/components/schemas/VideoInfo"
          type: object
        videoBlacklist:
          nullable: true
          properties:
            id:
              $ref: "#/components/schemas/id"
            video:
              allOf:
                - $ref: "#/components/schemas/VideoInfo"
          type: object
        videoImport:
          nullable: true
          properties:
            id:
              $ref: "#/components/schemas/id"
            magnetUri:
              $ref: "#/components/schemas/VideoImport/properties/magnetUri"
            targetUri:
              format: uri
              nullable: true
              type: string
            torrentName:
              nullable: true
              type: string
            video:
              $ref: "#/components/schemas/VideoInfo"
              nullable: true
          type: object
    NotificationListResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/Notification"
          maxItems: 100
          type: array
        total:
          example: 1
          type: integer
    NotificationSettingValue:
      description: |
        Notification type. One of the following values, or a sum of multiple values:
        - `0` NONE
        - `1` WEB
        - `2` EMAIL
      type: integer
    OAuthClient:
      properties:
        client_id:
          example: v1ikx5hnfop4mdpnci8nsqh93c45rldf
          maxLength: 32
          minLength: 32
          pattern: /^[a-z0-9]$/
          type: string
        client_secret:
          example: AjWiOapPltI6EnsWQwlFarRtLh4u8tDt
          maxLength: 32
          minLength: 32
          pattern: /^[a-zA-Z0-9]$/
          type: string
    OAuthToken-password:
      allOf:
        - $ref: "#/components/schemas/OAuthClient"
        - properties:
            grant_type:
              default: password
              enum:
                - password
                - refresh_token
              type: string
            password:
              $ref: "#/components/schemas/password"
            username:
              $ref: "#/components/schemas/User/properties/username"
          type: object
      required:
        - client_id
        - client_secret
        - grant_type
        - username
        - password
    OAuthToken-refresh_token:
      allOf:
        - $ref: "#/components/schemas/OAuthClient"
        - properties:
            grant_type:
              default: password
              enum:
                - password
                - refresh_token
              type: string
            refresh_token:
              example: 2e0d675df9fc96d2e4ec8a3ebbbf45eca9137bb7
              type: string
          type: object
      required:
        - client_id
        - client_secret
        - grant_type
        - refresh_token
    PlaybackMetricCreate:
      properties:
        downloadedBytesHTTP:
          description: How many bytes were downloaded with HTTP since the last metric creation
          type: number
        downloadedBytesP2P:
          description: How many bytes were downloaded with P2P since the last metric creation
          type: number
        errors:
          description: How many errors occured since the last metric creation
          type: number
        fps:
          description: Current player video fps
          type: number
        playerMode:
          enum:
            - p2p-media-loader
            - webtorrent
          type: string
        resolution:
          description: Current player video resolution
          type: number
        resolutionChanges:
          description: How many resolution changes occured since the last metric creation
          type: number
        uploadedBytesP2P:
          description: How many bytes were uploaded with P2P since the last metric creation
          type: number
        videoId:
          oneOf:
            - $ref: "#/components/schemas/id"
            - $ref: "#/components/schemas/UUIDv4"
            - $ref: "#/components/schemas/shortUUID"
      required:
        - playerMode
        - resolutionChanges
        - errors
        - downloadedBytesP2P
        - downloadedBytesHTTP
        - uploadedBytesP2P
        - videoId
    PlaylistElement:
      properties:
        position:
          type: integer
        startTimestamp:
          format: seconds
          type: integer
        stopTimestamp:
          format: seconds
          type: integer
        video:
          allOf:
            - $ref: "#/components/schemas/Video"
          nullable: true
    Plugin:
      properties:
        createdAt:
          format: date-time
          type: string
        description:
          type: string
        enabled:
          type: boolean
        homepage:
          example: https://framagit.org/framasoft/peertube/official-plugins/tree/master/peertube-plugin-auth-ldap
          format: url
          type: string
        latestVersion:
          example: 0.0.3
          type: string
        name:
          example: peertube-plugin-auth-ldap
          type: string
        peertubeEngine:
          example: 2.2.0
          type: string
        settings:
          additionalProperties: true
          type: object
        type:
          description: |
            - `1`: PLUGIN
            - `2`: THEME
          enum:
            - 1
            - 2
          type: integer
        uninstalled:
          type: boolean
        updatedAt:
          format: date-time
          type: string
        version:
          example: 0.0.1
          type: string
    PluginResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/Plugin"
          maxItems: 100
          type: array
        total:
          example: 1
          type: integer
    PredefinedAbuseReasons:
      description: Reason categories that help triage reports
      items:
        enum:
          - violentOrAbusive
          - hatefulOrAbusive
          - spamOrMisleading
          - privacy
          - rights
          - serverRules
          - thumbnails
          - captions
        type: string
      maxItems: 8
      type: array
    RegisterUser:
      properties:
        channel:
          description: channel base information used to create the first channel of the user
          properties:
            displayName:
              type: string
            name:
              $ref: "#/components/schemas/usernameChannel"
          type: object
        displayName:
          description: editable name of the user, displayed in its representations
          maxLength: 120
          minLength: 1
          type: string
        email:
          description: email of the user, used for login or service communications
          format: email
          type: string
        password:
          $ref: "#/components/schemas/password"
        username:
          allOf:
            - $ref: "#/components/schemas/username"
          description: immutable name of the user, used to find or mention its actor
      required:
        - username
        - password
        - email
    RequestTwoFactorResponse:
      properties:
        otpRequest:
          properties:
            requestToken:
              description: The token to send to confirm this request
              type: string
            secret:
              description: The OTP secret
              type: string
            uri:
              description: The OTP URI
              type: string
          type: object
    SendClientLog:
      properties:
        level:
          enum:
            - error
            - warn
        message:
          type: string
        meta:
          description: Additional information regarding this log
          type: string
        stackTrace:
          description: Stack trace of the error if there is one
          type: string
        url:
          description: URL of the current user page
          type: string
        userAgent:
          description: User agent of the web browser that sends the message
          type: string
      required:
        - message
        - url
        - level
    ServerConfig:
      properties:
        autoBlacklist:
          properties:
            videos:
              properties:
                ofUsers:
                  properties:
                    enabled:
                      type: boolean
                  type: object
              type: object
          type: object
        avatar:
          properties:
            extensions:
              items:
                type: string
              type: array
            file:
              properties:
                size:
                  properties:
                    max:
                      type: integer
                  type: object
              type: object
          type: object
        contactForm:
          properties:
            enabled:
              type: boolean
          type: object
        email:
          properties:
            enabled:
              type: boolean
          type: object
        followings:
          properties:
            instance:
              properties:
                autoFollowIndex:
                  properties:
                    indexUrl:
                      format: url
                      type: string
                  type: object
              type: object
          type: object
        homepage:
          properties:
            enabled:
              type: boolean
          type: object
        import:
          properties:
            videoChannelSynchronization:
              properties:
                enabled:
                  type: boolean
              type: object
            videos:
              properties:
                http:
                  properties:
                    enabled:
                      type: boolean
                  type: object
                torrent:
                  properties:
                    enabled:
                      type: boolean
                  type: object
              type: object
          type: object
        instance:
          properties:
            customizations:
              properties:
                css:
                  type: string
                javascript:
                  type: string
              type: object
            defaultClientRoute:
              type: string
            defaultNSFWPolicy:
              type: string
            isNSFW:
              type: boolean
            name:
              type: string
            shortDescription:
              type: string
          type: object
        plugin:
          properties:
            registered:
              items:
                type: string
              type: array
          type: object
        search:
          properties:
            remoteUri:
              properties:
                anonymous:
                  type: boolean
                users:
                  type: boolean
              type: object
          type: object
        serverCommit:
          type: string
        serverVersion:
          type: string
        signup:
          properties:
            allowed:
              type: boolean
            allowedForCurrentIP:
              type: boolean
            requiresEmailVerification:
              type: boolean
          type: object
        theme:
          properties:
            registered:
              items:
                type: string
              type: array
          type: object
        tracker:
          properties:
            enabled:
              type: boolean
          type: object
        transcoding:
          properties:
            enabledResolutions:
              items:
                $ref: "#/components/schemas/VideoResolutionSet"
              type: array
            hls:
              properties:
                enabled:
                  type: boolean
              type: object
            webtorrent:
              properties:
                enabled:
                  type: boolean
              type: object
          type: object
        trending:
          properties:
            videos:
              properties:
                intervalDays:
                  type: integer
              type: object
          type: object
        user:
          properties:
            videoQuota:
              example: 16810141515
              type: integer
            videoQuotaDaily:
              example: 1681014151
              type: integer
          type: object
        video:
          properties:
            file:
              properties:
                extensions:
                  items:
                    type: string
                  type: array
              type: object
            image:
              properties:
                extensions:
                  items:
                    type: string
                  type: array
                size:
                  properties:
                    max:
                      type: integer
                  type: object
              type: object
          type: object
        videoCaption:
          properties:
            file:
              properties:
                extensions:
                  items:
                    type: string
                  type: array
                size:
                  properties:
                    max:
                      type: integer
                  type: object
              type: object
          type: object
    ServerConfigAbout:
      properties:
        instance:
          properties:
            description:
              type: string
            name:
              type: string
            shortDescription:
              type: string
            terms:
              type: string
          type: object
    ServerConfigCustom:
      properties:
        admin:
          properties:
            email:
              format: email
              type: string
          type: object
        autoBlacklist:
          properties:
            videos:
              properties:
                ofUsers:
                  properties:
                    enabled:
                      type: boolean
                  type: object
              type: object
          type: object
        cache:
          properties:
            captions:
              properties:
                size:
                  type: integer
              type: object
            previews:
              properties:
                size:
                  type: integer
              type: object
          type: object
        contactForm:
          properties:
            enabled:
              type: boolean
          type: object
        followers:
          properties:
            instance:
              properties:
                enabled:
                  type: boolean
                manualApproval:
                  type: boolean
              type: object
          type: object
        import:
          properties:
            video_channel_synchronization:
              properties:
                enabled:
                  type: boolean
              type: object
            videos:
              properties:
                http:
                  properties:
                    enabled:
                      type: boolean
                  type: object
                torrent:
                  properties:
                    enabled:
                      type: boolean
                  type: object
              type: object
          type: object
        instance:
          properties:
            customizations:
              properties:
                css:
                  type: string
                javascript:
                  type: string
              type: object
            defaultClientRoute:
              type: string
            defaultNSFWPolicy:
              type: string
            description:
              type: string
            isNSFW:
              type: boolean
            name:
              type: string
            shortDescription:
              type: string
            terms:
              type: string
          type: object
        services:
          properties:
            twitter:
              properties:
                username:
                  type: string
                whitelisted:
                  type: boolean
              type: object
          type: object
        signup:
          properties:
            enabled:
              type: boolean
            limit:
              type: integer
            requiresEmailVerification:
              type: boolean
          type: object
        theme:
          properties:
            default:
              type: string
          type: object
        transcoding:
          description: Settings pertaining to transcoding jobs
          properties:
            allowAdditionalExtensions:
              description: Allow your users to upload .mkv, .mov, .avi, .wmv, .flv, .f4v, .3g2, .3gp, .mts, m2ts, .mxf, .nut videos
              type: boolean
            allowAudioFiles:
              description: If a user uploads an audio file, PeerTube will create a video by merging the preview file and the audio file
              type: boolean
            concurrency:
              description: Amount of transcoding jobs to execute in parallel
              type: number
            enabled:
              type: boolean
            hls:
              description: HLS-specific settings
              properties:
                enabled:
                  type: boolean
              type: object
            profile:
              description: |
                New profiles can be added by plugins ; available in core PeerTube: 'default'.
              enum:
                - default
              type: string
            resolutions:
              description: Resolutions to transcode _new videos_ to
              properties:
                0p:
                  type: boolean
                1080p:
                  type: boolean
                1440p:
                  type: boolean
                144p:
                  type: boolean
                2160p:
                  type: boolean
                240p:
                  type: boolean
                360p:
                  type: boolean
                480p:
                  type: boolean
                720p:
                  type: boolean
              type: object
            threads:
              description: Amount of threads used by ffmpeg for 1 transcoding job
              type: integer
            webtorrent:
              description: WebTorrent-specific settings
              properties:
                enabled:
                  type: boolean
              type: object
          type: object
        user:
          description: Settings that apply to new users, if registration is enabled
          properties:
            videoQuota:
              example: 16810141515
              type: integer
            videoQuotaDaily:
              example: 1681014151
              type: integer
          type: object
    ServerStats:
      properties:
        activityPubMessagesProcessedPerSecond:
          type: number
        totalActivityPubMessagesErrors:
          type: number
        totalActivityPubMessagesProcessed:
          type: number
        totalActivityPubMessagesSuccesses:
          type: number
        totalActivityPubMessagesWaiting:
          type: number
        totalDailyActiveUsers:
          type: number
        totalInstanceFollowers:
          type: number
        totalInstanceFollowing:
          type: number
        totalLocalDailyActiveVideoChannels:
          type: number
        totalLocalMonthlyActiveVideoChannels:
          type: number
        totalLocalPlaylists:
          type: number
        totalLocalVideoChannels:
          type: number
        totalLocalVideoComments:
          description: Total comments made by local users
          type: number
        totalLocalVideoFilesSize:
          type: number
        totalLocalVideoViews:
          description: Total video views made on the instance
          type: number
        totalLocalVideos:
          type: number
        totalLocalWeeklyActiveVideoChannels:
          type: number
        totalMonthlyActiveUsers:
          type: number
        totalUsers:
          type: number
        totalVideoComments:
          type: number
        totalVideos:
          type: number
        totalWeeklyActiveUsers:
          type: number
        videosRedundancy:
          items:
            properties:
              strategy:
                type: string
              totalSize:
                type: number
              totalUsed:
                type: number
              totalVideoFiles:
                type: number
              totalVideos:
                type: number
            type: object
          type: array
    UUIDv4:
      example: 9c9de5e8-0a1e-484a-b099-e80766180a6d
      format: uuid
      maxLength: 36
      minLength: 36
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      type: string
    UpdateMe:
      properties:
        autoPlayNextVideo:
          description: new preference regarding playing following videos automatically
          type: boolean
        autoPlayNextVideoPlaylist:
          description: new preference regarding playing following playlist videos automatically
          type: boolean
        autoPlayVideo:
          description: new preference regarding playing videos automatically
          type: boolean
        currentPassword:
          $ref: "#/components/schemas/password"
        displayNSFW:
          description: new NSFW display policy
          enum:
            - "true"
            - "false"
            - both
          type: string
        displayName:
          description: new name of the user in its representations
          maxLength: 120
          minLength: 3
          type: string
        email:
          allOf:
            - $ref: "#/components/schemas/User/properties/email"
          description: new email used for login and service communications
        noAccountSetupWarningModal:
          type: boolean
        noInstanceConfigWarningModal:
          type: boolean
        noWelcomeModal:
          type: boolean
        p2pEnabled:
          description: whether to enable P2P in the player or not
          type: boolean
        password:
          $ref: "#/components/schemas/password"
        theme:
          type: string
        videoLanguages:
          description: list of languages to filter videos down to
          items:
            type: string
          type: array
        videosHistoryEnabled:
          description: whether to keep track of watched history or not
          type: boolean
    UpdateUser:
      properties:
        adminFlags:
          $ref: "#/components/schemas/UserAdminFlags"
        email:
          allOf:
            - $ref: "#/components/schemas/User/properties/email"
          description: The updated email of the user
        emailVerified:
          description: Set the email as verified
          type: boolean
        password:
          $ref: "#/components/schemas/password"
        pluginAuth:
          description: The auth plugin to use to authenticate the user
          example: peertube-plugin-auth-saml2
          nullable: true
          type: string
        role:
          $ref: "#/components/schemas/UserRole"
        videoQuota:
          description: The updated video quota of the user in bytes
          type: integer
        videoQuotaDaily:
          description: The updated daily video quota of the user in bytes
          type: integer
    User:
      properties:
        account:
          $ref: "#/components/schemas/Account"
        autoPlayNextVideo:
          description: Automatically start playing the upcoming video after the currently playing video
          type: boolean
        autoPlayNextVideoPlaylist:
          description: Automatically start playing the video on the playlist after the currently playing video
          type: boolean
        autoPlayVideo:
          description: Automatically start playing the video on the watch page
          type: boolean
        blocked:
          type: boolean
        blockedReason:
          type: string
        createdAt:
          type: string
        email:
          description: The user email
          format: email
          type: string
        emailVerified:
          description: Has the user confirmed their email address?
          type: boolean
        id:
          allOf:
            - $ref: "#/components/schemas/id"
          readOnly: true
        lastLoginDate:
          format: date-time
          type: string
        noAccountSetupWarningModal:
          type: boolean
        noInstanceConfigWarningModal:
          type: boolean
        noWelcomeModal:
          type: boolean
        nsfwPolicy:
          $ref: "#/components/schemas/NSFWPolicy"
        p2pEnabled:
          description: Enable P2P in the player
          type: boolean
        pluginAuth:
          description: Auth plugin to use to authenticate the user
          type: string
        role:
          properties:
            id:
              $ref: "#/components/schemas/UserRole"
            label:
              enum:
                - User
                - Moderator
                - Administrator
              type: string
          type: object
        theme:
          description: Theme enabled by this user
          type: string
        username:
          $ref: "#/components/schemas/username"
        videoChannels:
          items:
            $ref: "#/components/schemas/VideoChannel"
          type: array
        videoQuota:
          description: The user video quota in bytes
          example: -1
          type: integer
        videoQuotaDaily:
          description: The user daily video quota in bytes
          example: -1
          type: integer
    UserAdminFlags:
      description: Admin flags for the user (None = `0`, Bypass video blocklist = `1`)
      enum:
        - 0
        - 1
      example: 1
      type: integer
    UserRegistration:
      properties:
        accountDisplayName:
          type: string
        channelDisplayName:
          type: string
        channelHandle:
          type: string
        createdAt:
          format: date-time
          type: string
        email:
          format: email
          type: string
        emailVerified:
          type: boolean
        id:
          $ref: "#/components/schemas/id"
        moderationResponse:
          nullable: true
          type: string
        registrationReason:
          type: string
        state:
          properties:
            id:
              description: The registration state (Pending = `1`, Rejected = `2`, Accepted = `3`)
              enum:
                - 1
                - 2
                - 3
              type: integer
            label:
              type: string
          type: object
        updatedAt:
          format: date-time
          type: string
        user:
          description: If the registration has been accepted, this is a partial user object created by the registration
          nullable: true
          properties:
            id:
              $ref: "#/components/schemas/id"
          type: object
        username:
          type: string
    UserRegistrationAcceptOrReject:
      properties:
        moderationResponse:
          description: Moderation response to send to the user
          type: string
        preventEmailDelivery:
          description: Set it to true if you don't want PeerTube to send an email to the user
          type: boolean
      required:
        - moderationResponse
      type: object
    UserRegistrationRequest:
      allOf:
        - $ref: "#/components/schemas/RegisterUser"
        - properties:
            registrationReason:
              description: reason for the user to register on the instance
              type: string
          required:
            - registrationReason
          type: object
    UserRole:
      description: The user role (Admin = `0`, Moderator = `1`, User = `2`)
      enum:
        - 0
        - 1
        - 2
      example: 2
      type: integer
    UserViewingVideo:
      properties:
        currentTime:
          description: timestamp within the video, in seconds
          example: 5
          format: seconds
          type: integer
        viewEvent:
          description: |
            Event since last viewing call:
             * `seek` - If the user seeked the video
          enum:
            - seek
          type: string
      required:
        - currentTime
    UserWithStats:
      allOf:
        - $ref: "#/components/schemas/User"
        - properties:
            abusesAcceptedCount:
              description: Count of reports/abuses created by the user and accepted/acted upon by the moderation team
              type: integer
            abusesCount:
              description: Count of reports/abuses of which the user is a target
              type: integer
            abusesCreatedCount:
              description: Count of reports/abuses created by the user
              type: integer
            videoCommentsCount:
              description: Count of comments published
              type: integer
            videosCount:
              description: Count of videos published
              type: integer
    Video:
      properties:
        account:
          $ref: "#/components/schemas/AccountSummary"
        blacklisted:
          nullable: true
          type: boolean
        blacklistedReason:
          nullable: true
          type: string
        category:
          allOf:
            - $ref: "#/components/schemas/VideoConstantNumber-Category"
          description: category in which the video is classified
        channel:
          $ref: "#/components/schemas/VideoChannelSummary"
        createdAt:
          description: time at which the video object was first drafted
          example: 2017-10-01T10:52:46.396Z
          format: date-time
          type: string
        description:
          description: |
            truncated description of the video, written in Markdown.
            Resolve `descriptionPath` to get the full description of maximum `10000` characters.
          example: |
            **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n
            **Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**\r\n*A decentralized video hosting network, based on fr...
          maxLength: 250
          minLength: 3
          type: string
        dislikes:
          example: 7
          type: integer
        duration:
          description: duration of the video in seconds
          example: 1419
          format: seconds
          type: integer
        embedPath:
          example: /videos/embed/a65bc12f-9383-462e-81ae-8207e8b434ee
          type: string
        id:
          allOf:
            - $ref: "#/components/schemas/id"
          description: object id for the video
        isLive:
          type: boolean
        isLocal:
          type: boolean
        language:
          allOf:
            - $ref: "#/components/schemas/VideoConstantString-Language"
          description: main language used in the video
        licence:
          allOf:
            - $ref: "#/components/schemas/VideoConstantNumber-Licence"
          description: licence under which the video is distributed
        likes:
          example: 42
          type: integer
        name:
          description: title of the video
          example: What is PeerTube?
          maxLength: 120
          minLength: 3
          type: string
        nsfw:
          type: boolean
        originallyPublishedAt:
          description: used to represent a date of first publication, prior to the practical publication date of `publishedAt`
          example: 2010-10-01T10:52:46.396Z
          format: date-time
          type: string
        previewPath:
          example: /lazy-static/previews/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
          type: string
        privacy:
          allOf:
            - $ref: "#/components/schemas/VideoPrivacyConstant"
          description: privacy policy used to distribute the video
        publishedAt:
          description: time at which the video was marked as ready for playback (with restrictions depending on `privacy`). Usually set after a `state` evolution.
          example: 2018-10-01T10:52:46.396Z
          format: date-time
          type: string
        scheduledUpdate:
          allOf:
            - $ref: "#/components/schemas/VideoScheduledUpdate"
          nullable: true
        shortUUID:
          allOf:
            - $ref: "#/components/schemas/shortUUID"
        state:
          allOf:
            - $ref: "#/components/schemas/VideoStateConstant"
          description: represents the internal state of the video processing within the PeerTube instance
        thumbnailPath:
          example: /static/thumbnails/a65bc12f-9383-462e-81ae-8207e8b434ee.jpg
          type: string
        updatedAt:
          description: last time the video's metadata was modified
          example: 2021-05-04T08:01:01.502Z
          format: date-time
          type: string
        userHistory:
          nullable: true
          properties:
            currentTime:
              type: integer
          type: object
        uuid:
          allOf:
            - $ref: "#/components/schemas/UUIDv4"
          description: universal identifier for the video, that can be used across instances
        views:
          example: 1337
          type: integer
        waitTranscoding:
          nullable: true
          type: boolean
    VideoBlacklist:
      properties:
        createdAt:
          format: date-time
          type: string
        description:
          maxLength: 10000
          minLength: 3
          type: string
        dislikes:
          type: integer
        duration:
          type: integer
        id:
          $ref: "#/components/schemas/id"
        likes:
          type: integer
        name:
          maxLength: 120
          minLength: 3
          type: string
        nsfw:
          type: boolean
        updatedAt:
          format: date-time
          type: string
        uuid:
          $ref: "#/components/schemas/UUIDv4"
        videoId:
          $ref: "#/components/schemas/Video/properties/id"
        views:
          type: integer
    VideoCaption:
      properties:
        captionPath:
          type: string
        language:
          $ref: "#/components/schemas/VideoConstantString-Language"
    VideoCategorySet:
      description: category id of the video (see [/videos/categories](#operation/getCategories))
      example: 15
      type: integer
    VideoChannel:
      allOf:
        - $ref: "#/components/schemas/Actor"
        - properties:
            banners:
              items:
                $ref: "#/components/schemas/ActorImage"
              type: array
            description:
              example: Videos made with <3 by Framasoft
              maxLength: 1000
              minLength: 3
              type: string
            displayName:
              description: editable name of the channel, displayed in its representations
              example: Videos of Framasoft
              maxLength: 120
              minLength: 1
              type: string
            isLocal:
              readOnly: true
              type: boolean
            ownerAccount:
              nullable: true
              properties:
                id:
                  type: integer
                uuid:
                  $ref: "#/components/schemas/UUIDv4"
              readOnly: true
              type: object
            support:
              description: text shown by default on all videos of this channel, to tell the audience how to support it
              example: Please support our work on https://soutenir.framasoft.org/en/ <3
              maxLength: 1000
              minLength: 3
              type: string
            updatedAt:
              format: date-time
              readOnly: true
              type: string
          type: object
    VideoChannelCreate:
      allOf:
        - $ref: "#/components/schemas/VideoChannelEdit"
        - properties:
            name:
              allOf:
                - $ref: "#/components/schemas/usernameChannel"
              description: username of the channel to create
      required:
        - name
        - displayName
    VideoChannelEdit:
      properties:
        description:
          description: Channel description
        displayName:
          description: Channel display name
        support:
          description: How to support/fund the channel
    VideoChannelList:
      properties:
        data:
          items:
            allOf:
              - $ref: "#/components/schemas/VideoChannel"
              - $ref: "#/components/schemas/Actor"
          type: array
        total:
          example: 1
          type: integer
    VideoChannelSummary:
      properties:
        avatars:
          items:
            $ref: "#/components/schemas/ActorImage"
          type: array
        displayName:
          type: string
        host:
          format: hostname
          type: string
        id:
          $ref: "#/components/schemas/id"
        name:
          type: string
        url:
          format: url
          type: string
    VideoChannelSync:
      properties:
        channel:
          $ref: "#/components/schemas/VideoChannel"
        createdAt:
          format: date-time
          type: string
        externalChannelUrl:
          example: https://youtube.com/c/UC_myfancychannel
          type: string
        id:
          $ref: "#/components/schemas/id"
        lastSyncAt:
          format: date-time
          nullable: true
          type: string
        state:
          properties:
            id:
              example: 2
              type: integer
            label:
              example: PROCESSING
              type: string
          type: object
      type: object
    VideoChannelSyncCreate:
      properties:
        externalChannelUrl:
          example: https://youtube.com/c/UC_myfancychannel
          type: string
        videoChannelId:
          $ref: "#/components/schemas/id"
      type: object
    VideoChannelSyncList:
      properties:
        data:
          items:
            allOf:
              - $ref: "#/components/schemas/VideoChannelSync"
          type: array
        total:
          example: 1
          type: integer
      type: object
    VideoChannelUpdate:
      allOf:
        - $ref: "#/components/schemas/VideoChannelEdit"
        - properties:
            bulkVideosSupportUpdate:
              description: Update the support field for all videos of this channel
              type: boolean
    VideoComment:
      properties:
        account:
          $ref: "#/components/schemas/Account"
        createdAt:
          format: date-time
          type: string
        deletedAt:
          default: null
          format: date-time
          nullable: true
          type: string
        id:
          $ref: "#/components/schemas/id"
        inReplyToCommentId:
          allOf:
            - $ref: "#/components/schemas/id"
          nullable: true
        isDeleted:
          default: false
          type: boolean
        text:
          description: Text of the comment
          example: This video is wonderful!
          format: html
          minLength: 1
          type: string
        threadId:
          $ref: "#/components/schemas/id"
        totalReplies:
          minimum: 0
          type: integer
        totalRepliesFromVideoAuthor:
          minimum: 0
          type: integer
        updatedAt:
          format: date-time
          type: string
        url:
          format: url
          type: string
        videoId:
          $ref: "#/components/schemas/Video/properties/id"
    VideoCommentThreadTree:
      properties:
        children:
          items:
            $ref: "#/components/schemas/VideoCommentThreadTree"
          type: array
        comment:
          $ref: "#/components/schemas/VideoComment"
    VideoCommentsForXML:
      items:
        properties:
          content:encoded:
            type: string
          dc:creator:
            type: string
          guid:
            type: string
          link:
            format: url
            type: string
          pubDate:
            format: date-time
            type: string
        type: object
        xml:
          name: item
      type: array
      xml:
        name: channel
        wrapped: true
    VideoConstantNumber-Category:
      properties:
        id:
          $ref: "#/components/schemas/VideoCategorySet"
        label:
          example: Science & Technology
          type: string
    VideoConstantNumber-Licence:
      properties:
        id:
          $ref: "#/components/schemas/VideoLicenceSet"
        label:
          example: Attribution - Share Alike
          type: string
    VideoConstantString-Language:
      properties:
        id:
          $ref: "#/components/schemas/VideoLanguageSet"
        label:
          example: English
          type: string
    VideoCreateImport:
      allOf:
        - additionalProperties: false
          oneOf:
            - properties:
                targetUrl:
                  $ref: "#/components/schemas/VideoImport/properties/targetUrl"
              required:
                - targetUrl
            - properties:
                magnetUri:
                  $ref: "#/components/schemas/VideoImport/properties/magnetUri"
              required:
                - magnetUri
            - properties:
                torrentfile:
                  $ref: "#/components/schemas/VideoImport/properties/torrentfile"
              required:
                - torrentfile
          type: object
        - $ref: "#/components/schemas/VideoUploadRequestCommon"
      required:
        - channelId
        - name
    VideoDetails:
      allOf:
        - $ref: "#/components/schemas/Video"
        - properties:
            account:
              $ref: "#/components/schemas/Account"
            channel:
              $ref: "#/components/schemas/VideoChannel"
            commentsEnabled:
              type: boolean
            descriptionPath:
              description: path at which to get the full description of maximum `10000` characters
              example: /api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180a6d/description
              type: string
            downloadEnabled:
              type: boolean
            files:
              description: |
                WebTorrent/raw video files. If WebTorrent is disabled on the server:

                - field will be empty
                - video files will be found in `streamingPlaylists[].files` field
              items:
                $ref: "#/components/schemas/VideoFile"
              type: array
            streamingPlaylists:
              description: |
                HLS playlists/manifest files. If HLS is disabled on the server:

                - field will be empty
                - video files will be found in `files` field
              items:
                $ref: "#/components/schemas/VideoStreamingPlaylists"
              type: array
            support:
              description: A text tell the audience how to support the video creator
              example: Please support our work on https://soutenir.framasoft.org/en/ <3
              maxLength: 1000
              minLength: 3
              type: string
            tags:
              example:
                - flowers
                - gardening
              items:
                maxLength: 30
                minLength: 2
                type: string
              maxItems: 5
              minItems: 1
              type: array
            trackerUrls:
              example:
                - https://peertube2.cpy.re/tracker/announce
                - wss://peertube2.cpy.re/tracker/socket
              items:
                format: url
                type: string
              type: array
            viewers:
              description: If the video is a live, you have the amount of current viewers
              type: integer
          type: object
    VideoFile:
      properties:
        fileDownloadUrl:
          description: URL endpoint that transfers the video file as an attachment (so that the browser opens a download dialog)
          format: url
          type: string
        fileUrl:
          description: Direct URL of the video
          format: url
          type: string
        fps:
          description: Frames per second of the video file
          type: number
        id:
          $ref: "#/components/schemas/id"
        magnetUri:
          description: magnet URI allowing to resolve the video via BitTorrent without a metainfo file
          format: uri
          pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
          type: string
        metadataUrl:
          description: URL dereferencing the output of ffprobe on the file
          format: url
          type: string
        resolution:
          $ref: "#/components/schemas/VideoResolutionConstant"
        size:
          description: Video file size in bytes
          type: integer
        torrentDownloadUrl:
          description: URL endpoint that transfers the torrent file as an attachment (so that the browser opens a download dialog)
          format: url
          type: string
        torrentUrl:
          description: Direct URL of the torrent file
          format: url
          type: string
      readOnly: true
    VideoImport:
      properties:
        createdAt:
          format: date-time
          readOnly: true
          type: string
        error:
          readOnly: true
          type: string
        id:
          allOf:
            - $ref: "#/components/schemas/id"
          readOnly: true
        magnetUri:
          description: magnet URI allowing to resolve the import's source video
          format: uri
          pattern: /magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32}/i
          type: string
        state:
          allOf:
            - $ref: "#/components/schemas/VideoImportStateConstant"
          readOnly: true
        targetUrl:
          description: remote URL where to find the import's source video
          example: https://framatube.org/videos/watch/9c9de5e8-0a1e-484a-b099-e80766180a6d
          format: url
          type: string
        torrentName:
          readOnly: true
          type: string
        torrentfile:
          description: Torrent file containing only the video file
          format: binary
          type: string
          writeOnly: true
        updatedAt:
          format: date-time
          readOnly: true
          type: string
        video:
          allOf:
            - $ref: "#/components/schemas/Video"
          nullable: true
          readOnly: true
    VideoImportStateConstant:
      properties:
        id:
          description: The video import state (Pending = `1`, Success = `2`, Failed = `3`)
          enum:
            - 1
            - 2
            - 3
          type: integer
        label:
          example: Pending
          type: string
    VideoImportsList:
      properties:
        data:
          items:
            $ref: "#/components/schemas/VideoImport"
          maxItems: 100
          type: array
        total:
          example: 1
          type: integer
    VideoInfo:
      properties:
        id:
          $ref: "#/components/schemas/Video/properties/id"
        name:
          $ref: "#/components/schemas/Video/properties/name"
        uuid:
          $ref: "#/components/schemas/Video/properties/uuid"
    VideoLanguageSet:
      description: language id of the video (see [/videos/languages](#operation/getLanguages))
      example: en
      type: string
    VideoLicenceSet:
      description: licence id of the video (see [/videos/licences](#operation/getLicences))
      example: 2
      type: integer
    VideoListResponse:
      properties:
        data:
          items:
            $ref: "#/components/schemas/Video"
          maxItems: 100
          type: array
        total:
          example: 1
          type: integer
    VideoPlaylist:
      properties:
        createdAt:
          format: date-time
          type: string
        description:
          maxLength: 1000
          minLength: 3
          type: string
        displayName:
          maxLength: 120
          minLength: 1
          type: string
        id:
          $ref: "#/components/schemas/id"
        isLocal:
          type: boolean
        ownerAccount:
          $ref: "#/components/schemas/AccountSummary"
        privacy:
          $ref: "#/components/schemas/VideoPlaylistPrivacyConstant"
        shortUUID:
          allOf:
            - $ref: "#/components/schemas/shortUUID"
        thumbnailPath:
          type: string
        type:
          $ref: "#/components/schemas/VideoPlaylistTypeConstant"
        updatedAt:
          format: date-time
          type: string
        uuid:
          $ref: "#/components/schemas/UUIDv4"
        videoChannel:
          $ref: "#/components/schemas/VideoChannelSummary"
        videoLength:
          minimum: 0
          type: integer
    VideoPlaylistPrivacyConstant:
      properties:
        id:
          $ref: "#/components/schemas/VideoPlaylistPrivacySet"
        label:
          type: string
    VideoPlaylistPrivacySet:
      description: Video playlist privacy policy (see [/video-playlists/privacies](#operation/getPlaylistPrivacyPolicies))
      enum:
        - 1
        - 2
        - 3
      type: integer
    VideoPlaylistTypeConstant:
      properties:
        id:
          $ref: "#/components/schemas/VideoPlaylistTypeSet"
        label:
          type: string
    VideoPlaylistTypeSet:
      description: The video playlist type (Regular = `1`, Watch Later = `2`)
      enum:
        - 1
        - 2
      type: integer
    VideoPrivacyConstant:
      properties:
        id:
          $ref: "#/components/schemas/VideoPrivacySet"
        label:
          type: string
    VideoPrivacySet:
      description: privacy id of the video (see [/videos/privacies](#operation/getVideoPrivacyPolicies))
      enum:
        - 1
        - 2
        - 3
        - 4
      type: integer
    VideoRating:
      properties:
        rating:
          description: Rating of the video
          enum:
            - like
            - dislike
            - none
          type: string
        video:
          $ref: "#/components/schemas/Video"
      required:
        - video
        - rating
    VideoRedundancy:
      properties:
        id:
          $ref: "#/components/schemas/id"
        name:
          type: string
        redundancies:
          properties:
            files:
              items:
                $ref: "#/components/schemas/FileRedundancyInformation"
              type: array
            streamingPlaylists:
              items:
                $ref: "#/components/schemas/FileRedundancyInformation"
              type: array
          type: object
        url:
          format: url
          type: string
        uuid:
          $ref: "#/components/schemas/UUIDv4"
    VideoResolutionConstant:
      description: resolutions and their labels for the video
      properties:
        id:
          $ref: "#/components/schemas/VideoResolutionSet"
        label:
          example: 240p
          type: string
    VideoResolutionSet:
      description: |
        Video resolution (`0`, `240`, `360`, `720`, `1080`, `1440` or `2160`)

        `0` is used as a special value for stillimage videos dedicated to audio, a.k.a. audio-only videos.
      example: 240
      type: integer
    VideoScheduledUpdate:
      properties:
        privacy:
          $ref: "#/components/schemas/VideoPrivacySet"
        updateAt:
          description: When to update the video
          format: date
          type: string
      required:
        - updateAt
    VideoSource:
      properties:
        filename:
          type: string
    VideoStateConstant:
      properties:
        id:
          description: |
            The video state:
            - `1`: Published
            - `2`: To transcode
            - `3`: To import
            - `4`: Waiting for live stream
            - `5`: Live ended
            - `6`: To move to an external storage (object storage...)
            - `7`: Transcoding failed
            - `8`: Moving to an external storage failed
            - `9`: To edit using studio edition feature
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
          type: integer
        label:
          type: string
    VideoStatsOverall:
      properties:
        averageWatchTime:
          type: number
        countries:
          items:
            properties:
              isoCode:
                type: string
              viewers:
                type: number
            type: object
          type: array
        totalWatchTime:
          type: number
        viewersPeak:
          type: number
        viewersPeakDate:
          format: date-time
          type: string
    VideoStatsRetention:
      properties:
        data:
          items:
            properties:
              retentionPercent:
                type: number
              second:
                type: number
            type: object
          type: array
    VideoStatsTimeserie:
      properties:
        data:
          items:
            properties:
              date:
                type: string
              value:
                type: number
            type: object
          type: array
    VideoStreamingPlaylists:
      allOf:
        - properties:
            id:
              $ref: "#/components/schemas/id"
            type:
              description: |
                Playlist type:
                - `1`: HLS
              enum:
                - 1
              type: integer
          type: object
        - $ref: "#/components/schemas/VideoStreamingPlaylists-HLS"
    VideoStreamingPlaylists-HLS:
      properties:
        files:
          description: |
            Video files associated to this playlist.

            The difference with the root `files` property is that these files are fragmented, so they can be used in this streaming playlist (HLS, etc.)
          items:
            $ref: "#/components/schemas/VideoFile"
          type: array
        playlistUrl:
          format: url
          type: string
        redundancies:
          items:
            properties:
              baseUrl:
                format: url
                type: string
            type: object
          type: array
        segmentsSha256Url:
          format: url
          type: string
    VideoStudioCreateTask:
      items:
        anyOf:
          - properties:
              name:
                enum:
                  - cut
                type: string
              options:
                properties:
                  end:
                    type: integer
                  start:
                    type: integer
                type: object
            title: cut
            type: object
          - properties:
              name:
                enum:
                  - add-intro
                type: string
              options:
                properties:
                  file:
                    format: binary
                    type: string
                type: object
            title: add-intro
            type: object
          - properties:
              name:
                enum:
                  - add-outro
                type: string
              options:
                properties:
                  file:
                    format: binary
                    type: string
                type: object
            title: add-outro
            type: object
          - properties:
              name:
                enum:
                  - add-watermark
                type: string
              options:
                properties:
                  file:
                    format: binary
                    type: string
                type: object
            title: add-watermark
            type: object
      type: array
    VideoTokenResponse:
      properties:
        files:
          properties:
            expires:
              format: date-time
              type: string
            token:
              type: string
          type: object
    VideoUploadRequestCommon:
      properties:
        category:
          $ref: "#/components/schemas/VideoCategorySet"
        channelId:
          description: Channel id that will contain this video
          example: 3
          minimum: 1
          type: integer
        commentsEnabled:
          description: Enable or disable comments for this video
          type: boolean
        description:
          description: Video description
          example: |
            **[Want to help to translate this video?](https://weblate.framasoft.org/projects/what-is-peertube-video/)**\r\n\r\n**Take back the control of your videos! [#JoinPeertube](https://joinpeertube.org)**
          type: string
        downloadEnabled:
          description: Enable or disable downloading for this video
          type: boolean
        language:
          $ref: "#/components/schemas/VideoLanguageSet"
        licence:
          $ref: "#/components/schemas/VideoLicenceSet"
        name:
          description: Video name
          example: What is PeerTube?
          maxLength: 120
          minLength: 3
          type: string
        nsfw:
          description: Whether or not this video contains sensitive content
          type: boolean
        originallyPublishedAt:
          description: Date when the content was originally published
          format: date-time
          type: string
        previewfile:
          description: Video preview file
          format: binary
          type: string
        privacy:
          $ref: "#/components/schemas/VideoPrivacySet"
        scheduleUpdate:
          $ref: "#/components/schemas/VideoScheduledUpdate"
        support:
          description: A text tell the audience how to support the video creator
          example: Please support our work on https://soutenir.framasoft.org/en/ <3
          type: string
        tags:
          description: Video tags (maximum 5 tags each between 2 and 30 characters)
          example:
            - framasoft
            - peertube
          items:
            maxLength: 30
            minLength: 2
            type: string
          maxItems: 5
          minItems: 1
          type: array
          uniqueItems: true
        thumbnailfile:
          description: Video thumbnail file
          format: binary
          type: string
        waitTranscoding:
          description: Whether or not we wait transcoding before publish the video
          type: boolean
      required:
        - channelId
        - name
    VideoUploadRequestLegacy:
      allOf:
        - $ref: "#/components/schemas/VideoUploadRequestCommon"
        - properties:
            videofile:
              description: Video file
              format: binary
              type: string
          required:
            - videofile
          type: object
    VideoUploadRequestResumable:
      allOf:
        - $ref: "#/components/schemas/VideoUploadRequestCommon"
        - properties:
            filename:
              description: Video filename including extension
              example: what_is_peertube.mp4
              format: filename
              type: string
            previewfile:
              description: Video preview file
              format: binary
              type: string
            thumbnailfile:
              description: Video thumbnail file
              format: binary
              type: string
          required:
            - filename
          type: object
    VideoUploadResponse:
      properties:
        video:
          properties:
            id:
              $ref: "#/components/schemas/Video/properties/id"
            shortUUID:
              $ref: "#/components/schemas/Video/properties/shortUUID"
            uuid:
              $ref: "#/components/schemas/Video/properties/uuid"
          type: object
    VideosForXML:
      items:
        properties:
          content:encoded:
            description: video description
            type: string
          dc:creator:
            description: publisher user name
            type: string
          description:
            description: video description
            type: string
          enclosure:
            description: main streamable file for the video
            properties:
              length:
                type: integer
                xml:
                  attribute: true
              type:
                enum:
                  - application/x-bittorrent
                type: string
                xml:
                  attribute: true
              url:
                format: url
                type: string
                xml:
                  attribute: true
            type: object
          guid:
            description: video canonical URL
            type: string
          link:
            description: video watch page URL
            format: url
            type: string
          media:category:
            description: video category (MRSS)
            type: integer
          media:community:
            description: see [media:community](https://www.rssboard.org/media-rss#media-community) (MRSS)
            properties:
              media:statistics:
                properties:
                  views:
                    type: integer
                    xml:
                      attribute: true
                type: object
            type: object
          media:description:
            type: string
          media:embed:
            properties:
              url:
                description: video embed path, relative to the canonical URL domain (MRSS)
                format: url
                type: string
                xml:
                  attribute: true
            type: object
          media:group:
            description: list of streamable files for the video. see [media:peerLink](https://www.rssboard.org/media-rss#media-peerlink) and [media:content](https://www.rssboard.org/media-rss#media-content) or  (MRSS)
            items:
              anyOf:
                - $ref: "#/components/schemas/MRSSPeerLink"
                - $ref: "#/components/schemas/MRSSGroupContent"
            type: array
          media:player:
            properties:
              url:
                description: video watch path, relative to the canonical URL domain (MRSS)
                format: url
                type: string
                xml:
                  attribute: true
            type: object
          media:rating:
            description: see [media:rating](https://www.rssboard.org/media-rss#media-rating) (MRSS)
            enum:
              - nonadult
              - adult
            type: string
          media:thumbnail:
            properties:
              height:
                type: integer
                xml:
                  attribute: true
              url:
                format: url
                type: string
                xml:
                  attribute: true
              width:
                type: integer
                xml:
                  attribute: true
            type: object
          media:title:
            description: see [media:title](https://www.rssboard.org/media-rss#media-title) (MRSS). We only use `plain` titles.
            type: string
          pubDate:
            description: video publication date
            format: date-time
            type: string
        type: object
        xml:
          name: item
      type: array
      xml:
        name: channel
        wrapped: true
    id:
      example: 42
      minimum: 1
      type: integer
    password:
      format: password
      maxLength: 255
      minLength: 6
      type: string
    shortUUID:
      description: translation of a uuid v4 with a bigger alphabet to have a shorter uuid
      example: 2y84q2MQUMWPbiEcxNXMgC
      type: string
    username:
      description: immutable name of the user, used to find or mention its actor
      example: chocobozzz
      maxLength: 50
      minLength: 1
      pattern: /^[a-z0-9._]+$/
      type: string
    usernameChannel:
      description: immutable name of the channel, used to interact with its actor
      example: framasoft_videos
      maxLength: 50
      minLength: 1
      pattern: /^[a-zA-Z0-9\\-_.:]+$/
      type: string
  securitySchemes:
    OAuth2:
      description: |
        Authenticating via OAuth requires the following steps:
        - Have an activated account
        - [Generate] an access token for that account at `/api/v1/users/token`.
        - Make requests with the *Authorization: Bearer <token\>* header
        - Profit, depending on the role assigned to the account

        Note that the __access token is valid for 1 day__ and is given
        along with a __refresh token valid for 2 weeks__.

        [Generate]: https://docs.joinpeertube.org/api/rest-getting-started
      flows:
        password:
          scopes:
            admin: Admin scope
            moderator: Moderator scope
            user: User scope
          tokenUrl: /api/v1/users/token
      type: oauth2
x-tagGroups:
  - name: Static endpoints
    tags:
      - Static Video Files
  - name: Feeds
    tags:
      - Video Feeds
  - name: Auth
    tags:
      - Register
      - Session
  - name: Accounts
    tags:
      - Accounts
      - Users
      - My User
      - My Subscriptions
      - My Notifications
      - My History
  - name: Videos
    tags:
      - Video
      - Video Upload
      - Video Imports
      - Video Captions
      - Video Channels
      - Video Comments
      - Video Rates
      - Video Playlists
      - Video Stats
      - Video Ownership Change
      - Video Mirroring
      - Video Files
      - Video Transcoding
      - Live Videos
      - Channels Sync
  - name: Search
    tags:
      - Search
  - name: Moderation
    tags:
      - Abuses
      - Video Blocks
      - Account Blocks
      - Server Blocks
  - name: Instance
    tags:
      - Config
      - Homepage
      - Instance Follows
      - Instance Redundancy
      - Plugins
      - Stats
      - Logs
      - Job
