openapi: 3.0.0
servers:
  - description: Official Instance
    url: https://pipedapi.kavin.rocks
info:
  description: This is an API specification for Piped API instances.
  version: "1.0.0"
  title: Piped API
  contact:
    email: kavin@kavin.rocks
    url: https://github.com/TeamPiped/Piped/issues
  license:
    name: MIT
    url: "https://opensource.org/licenses/MIT"
tags:
  - name: video
    description: Video related operations.
  - name: channel
    description: Channel related operations.
  - name: playlist
    description: Playlist related operations.
  - name: search
    description: Search related operations.
  - name: feed
    description: Feed related operations.
  - name: unauthenticated
    description: Requests that can be made by anyone, without any authentication.
  - name: authenticated
    description: Requests that can only be made when logged in, with an authToken.
paths:
  /trending:
    get:
      tags:
        - unauthenticated
      summary: Gets all Trending Videos
      operationId: trending
      description: Gets all Trending Videos in the requested country.
      parameters:
        - in: query
          name: region
          description: The Region to get trending videos from.
          required: true
          example: US
          schema:
            $ref: "#/components/schemas/Regions"
      responses:
        "200":
          description: Array of trending Videos.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/StreamItem"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /streams/{videoId}:
    get:
      tags:
        - video
        - unauthenticated
      summary: Gets Video Information
      operationId: streamInfo
      description: |
        Gets all available Stream information about a video.
      parameters:
        - in: path
          name: videoId
          description: The video ID of the YouTube video you want to get information about.
          required: true
          example: dQw4w9WgXcQ
          schema:
            type: string
            pattern: ^([a-zA-Z0-9_-]{11})$
      responses:
        "200":
          description: The information about the video.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoInfo"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /channel/{channelId}:
    get:
      tags:
        - channel
        - unauthenticated
      summary: Gets Channel Information from ID.
      operationId: channelInfoId
      description: |
        Gets all available Channel information about a channel.
      parameters:
        - in: path
          name: channelId
          description: The channel ID of the YouTube channel you want to get information about.
          required: true
          example: UCs6KfncB4OV6Vug4o_bzijg
          schema:
            type: string
            pattern: ^([a-zA-Z0-9_-]{24})$
      responses:
        "200":
          description: The information about the channel.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelInfo"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /c/{name}:
    get:
      tags:
        - channel
        - unauthenticated
      summary: Gets Channel Information from name.
      operationId: channelInfoName
      description: |
        Gets all available Channel information about a channel.
      parameters:
        - in: path
          name: name
          description: The name of the YouTube channel you want to get information about.
          required: true
          example: Dream
          schema:
            type: string
      responses:
        "200":
          description: The information about the channel.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelInfo"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /user/{username}:
    get:
      tags:
        - channel
        - unauthenticated
      summary: Gets Channel Information from username.
      operationId: channelInfoUsername
      description: |
        Gets all available Channel information about a channel.
      parameters:
        - in: path
          name: username
          description: The username of the YouTube channel you want to get information about.
          required: true
          example: DreamTraps
          schema:
            type: string
      responses:
        "200":
          description: The information about the channel.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChannelInfo"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /nextpage/channel/{channelId}:
    get:
      tags:
        - channel
        - unauthenticated
      summary: Gets more channel videos
      operationId: channelNextPage
      description: |
        Gets more channel videos.
      parameters:
        - in: path
          name: channelId
          description: The channel ID of the YouTube channel you want to get more videos from.
          required: true
          example: UCs6KfncB4OV6Vug4o_bzijg
          schema:
            type: string
            pattern: "^[a-zA-Z0-9_-]{24}$"
        - in: query
          name: nextpage
          description: The next page token to get more videos from.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The information about the channel.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StreamsPage"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /comments/{videoId}:
    get:
      tags:
        - video
        - unauthenticated
      summary: Gets Comments
      operationId: comments
      description: |
        Gets the comments for a video.
      parameters:
        - in: path
          name: videoId
          description: The video ID of the YouTube video you want to get comments from.
          required: true
          example: dQw4w9WgXcQ
          schema:
            type: string
            pattern: ^([a-zA-Z0-9_-]{11})$
      responses:
        "200":
          description: The first page of comments for the video.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentsPage"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /nextpage/comments/{videoId}:
    get:
      tags:
        - video
        - unauthenticated
      summary: Gets more comments
      operationId: commentsNextPage
      description: |
        Gets more comments.
      parameters:
        - in: path
          name: videoId
          description: The video ID of the YouTube video you want to get more comments from.
          required: true
          example: dQw4w9WgXcQ
          schema:
            type: string
            pattern: ^([a-zA-Z0-9_-]{11})$
        - in: query
          name: nextpage
          description: The next page token to get more comments from.
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The page of comments from the video.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommentsPage"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /search:
    get:
      tags:
        - search
        - unauthenticated
      summary: Searches for videos, channels, and playlists.
      operationId: search
      description: |
        Searches for videos, channels, and playlists.
      parameters:
        - in: query
          name: q
          description: The search query string.
          required: true
          example: "Techlore"
          schema:
            type: string
        - in: query
          name: filter
          description: The filter parameter specifies a filter query that restricts the results to items that match the filter.
          required: true
          schema:
            $ref: "#/components/schemas/SearchFilter"
      responses:
        "200":
          description: The first page of search results.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchPage"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /nextpage/search:
    get:
      tags:
        - search
        - unauthenticated
      summary: Gets more search results
      operationId: searchNextPage
      description: |
        Gets more search results.
      parameters:
        - in: query
          name: nextpage
          description: The next page token to get more search results from.
          required: true
          schema:
            type: string
        - in: query
          name: q
          description: The search query string.
          required: true
          example: "Techlore"
          schema:
            type: string
        - in: query
          name: filter
          description: The filter parameter specifies a filter query that restricts the results to items that match the filter.
          required: true
          schema:
            $ref: "#/components/schemas/SearchFilter"
      responses:
        "200":
          description: The page of search results.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchPage"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
  /feed/unauthenticated:
    get:
      tags:
        - feed
        - unauthenticated
      summary: Generate a feed while unauthenticated, from a list of channelIds.
      operationId: feedUnauthenticated
      description: |
        Generates a user feed while unauthenticated.
      parameters:
        - in: query
          name: channels
          description: A list of channelIds to generate a feed from.
          required: true
          explode: false
          schema:
            type: array
            items:
              type: string
              pattern: "^[a-zA-Z0-9_-]{24}$"
            example:
              - UCs6KfncB4OV6Vug4o_bzijg
              - UClcE-kVhqyiHCcjYwcpfj9w
      responses:
        "200":
          description: The video items from the feed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/StreamItem"
        "500":
          description: Server Side exception
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExceptionError"
components:
  schemas:
    Regions:
      type: string
      enum:
        [
          "DZ",
          "AR",
          "AU",
          "AT",
          "AZ",
          "BH",
          "BD",
          "BY",
          "BE",
          "BO",
          "BA",
          "BR",
          "BG",
          "CA",
          "CL",
          "CO",
          "CR",
          "HR",
          "CY",
          "CZ",
          "DK",
          "DO",
          "EC",
          "EG",
          "SV",
          "EE",
          "FI",
          "FR",
          "GE",
          "DE",
          "GH",
          "GR",
          "GT",
          "HN",
          "HK",
          "HU",
          "IS",
          "IN",
          "ID",
          "IQ",
          "IE",
          "IL",
          "IT",
          "JM",
          "JP",
          "JO",
          "KZ",
          "KE",
          "KW",
          "LV",
          "LB",
          "LY",
          "LI",
          "LT",
          "LU",
          "MY",
          "MT",
          "MX",
          "ME",
          "MA",
          "NP",
          "NL",
          "NZ",
          "NI",
          "NG",
          "MK",
          "NO",
          "OM",
          "PK",
          "PA",
          "PG",
          "PY",
          "PE",
          "PH",
          "PL",
          "PT",
          "PR",
          "QA",
          "RO",
          "RU",
          "SA",
          "SN",
          "RS",
          "SG",
          "SK",
          "SI",
          "ZA",
          "KR",
          "ES",
          "LK",
          "SE",
          "CH",
          "TW",
          "TZ",
          "TH",
          "TN",
          "TR",
          "UG",
          "UA",
          "AE",
          "GB",
          "US",
          "UY",
          "VE",
          "VN",
          "YE",
          "ZW",
        ]
    SearchFilter:
      type: string
      enum:
        [
          "all",
          "videos",
          "channels",
          "playlists",
          "music_songs",
          "music_videos",
          "music_albums",
          "music_playlists",
        ]
    VideoInfo:
      type: object
      properties:
        audioStreams:
          type: array
          items:
            $ref: "#/components/schemas/Stream"
        videoStreams:
          type: array
          items:
            $ref: "#/components/schemas/Stream"
        description:
          type: string
          description: The video's description.
        dislikes:
          type: integer
          description: The number of dislikes the video has.
        duration:
          type: integer
          description: The video's duration in seconds.
        hls:
          type: string
          description: The stream of the video in a HLS manifest.
        lbryId:
          type: string
          description: The LBRY ID of the video.
        likes:
          type: integer
          description: The number of likes the video has.
        livestream:
          type: boolean
          description: Whether the video is a livestream.
        proxyUrl:
          type: string
          description: The base URL of the backend instance's proxy.
        subtitles:
          type: array
          items:
            $ref: "#/components/schemas/Subtitle"
        dash:
          type: string
          description: The URL of the DASH manifest.
        thumbnailUrl:
          type: string
          description: The URL of the video's thumbnail.
        title:
          type: string
          description: The video's title.
        uploadDate:
          type: string
          description: The date the video was uploaded.
        uploader:
          type: string
          description: The video's uploader.
        uploaderAvatar:
          type: string
          description: The URL of the video's uploader's avatar.
        uploaderUrl:
          type: string
          description: The relative URL of the video's uploader.
        uploaderVerified:
          type: boolean
          description: Whether the video's uploader is verified.
        views:
          type: integer
          description: The number of views the video has.
        relatedStreams:
          type: array
          items:
            $ref: "#/components/schemas/StreamItem"
            description: The related videos for the current video.
    ChannelInfo:
      type: object
      properties:
        avatarUrl:
          type: string
          description: The URL of the channel's avatar.
        bannerUrl:
          type: string
          description: The URL of the channel's banner.
        description:
          type: string
          description: The channel's description.
        id:
          type: string
          description: The ID of the channel.
          example: UCs6KfncB4OV6Vug4o_bzijg
        name:
          type: string
          description: The name of the channel.
          example: Techlore
        nextpage:
          type: string
          description: The parameter used to get the next page of related videos.
        relatedStreams:
          type: array
          items:
            $ref: "#/components/schemas/StreamItem"
        subscriberCount:
          type: integer
          description: The number of subscribers the channel has.
          example: 170000
        verified:
          type: boolean
          description: Whether the channel is verified.
          example: true
    Stream:
      properties:
        url:
          type: string
          description: The URL of the stream.
        format:
          type: string
          description: The format of the stream.
          enum: [MPEG_4, v3GPP, WEBM, M4A, WEBMA_OPUS]
          example: MPEG_4
        quality:
          type: string
          description: The quality of the stream.
          example: 1080p
        mimeType:
          type: string
          description: The mime type of the stream.
          example: video/mp4
        codec:
          type: string
          description: The codec of the stream.
          example: avc1.64002a
        videoOnly:
          type: boolean
        bitrate:
          type: integer
        initStart:
          type: integer
        initEnd:
          type: integer
        indexStart:
          type: integer
        indexEnd:
          type: integer
        width:
          type: integer
        height:
          type: integer
        fps:
          type: integer
    StreamItem:
      type: object
      required:
        - duration
        - thumbnail
        - title
        - url
      properties:
        type:
          type: string
          description: The type of the stream item. Always stream.
          example: stream
        duration:
          type: integer
          description: The duration of the video in seconds.
        thumbnail:
          type: string
          description: The thumbnail of the video.
        title:
          type: string
          description: The title of the video.
        uploaded:
          type: integer
          description: The date in unix epoch the video was uploaded.
        uploadedDate:
          type: string
          example: 3 months ago
          description: The relative date the video was uploaded on.
          deprecated: true
          nullable: true
        uploaderAvatar:
          type: string
          description: The avatar of the channel of the video.
          nullable: true
        uploaderName:
          type: string
          description: The name of the channel of the video.
        uploaderUrl:
          type: string
          description: The relative URL of the channel of the video.
        uploaderVerified:
          type: boolean
          description: Whether or not the channel has a verified badge.
        url:
          type: string
          description: The relative URL to the video.
        views:
          type: integer
          description: The number of views the video has.
        isShort:
          type: boolean
          description: Whether or not the video is a short video.
        shortDescription:
          type: string
          description: The short description of the video.
          nullable: true
    StreamsPage:
      type: object
      properties:
        relatedStreams:
          type: array
          items:
            $ref: "#/components/schemas/StreamItem"
        nextpage:
          type: string
          nullable: true
          description: The parameter used to get the next page of this page.
    ExceptionError:
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: The stacktrace provided by the server.
        message:
          type: string
          description: The error message from the stacktrace.
      description: When a server-side exception takes place.
    Subtitle:
      type: object
      properties:
        autoGenerated:
          type: boolean
          description: Whether the subtitle is auto generated.
        code:
          type: string
          description: The language code of the subtitle.
        mimeType:
          type: string
          description: The mime type of the subtitle.
        url:
          type: string
          description: The URL of the subtitle.
    Comment:
      type: object
      properties:
        author:
          type: string
          description: The name of the author of the comment.
        thumbnail:
          type: string
          description: The thumbnail/avatar of the author of the comment.
        commentId:
          type: string
          description: The ID of the comment.
        commentText:
          type: string
          description: The text of the comment.
        commentedTime:
          type: string
          example: 3 months ago
          description: The relative time the comment was made.
        commentorUrl:
          type: string
          description: The relative URL of the author of the comment.
          example: "/channel/UCs6KfncB4OV6Vug4o_bzijg"
        repliesPage:
          type: string
          description: The parameter used as the nextpage to fetch replies for this comment.
        likeCount:
          type: integer
          description: The number of likes the comment has.
        replyCount:
          type: integer
          description: The number of replies the comment has.
        hearted:
          type: boolean
          description: Whether the comment was hearted by the video's uploader.
        pinned:
          type: boolean
          description: Whether the comment was pinned by the video's uploader.
        verified:
          type: boolean
          description: Whether the author of the comment is verified.
    CommentsPage:
      type: object
      properties:
        comments:
          type: array
          items:
            $ref: "#/components/schemas/Comment"
        nextpage:
          type: string
          nullable: true
          description: The parameter used to get the next page of comments.
        disabled:
          type: boolean
          description: Whether or not comments are disabled on the video.
    ChannelItem:
      type: object
      properties:
        type:
          type: string
          description: The type of the channel item. Always channel.
          example: channel
        description:
          type: string
          description: The description of the channel.
        name:
          type: string
          description: The name of the channel.
        subscribers:
          type: integer
          description: The number of subscribers the channel has.
        thumbnail:
          type: string
          description: The thumbnail of the channel.
        url:
          type: string
          description: The relative URL of the channel.
        verified:
          type: boolean
          description: Whether the channel is verified.
        videos:
          type: integer
          description: The number of videos the channel has.
    PlaylistItem:
      type: object
      properties:
        type:
          type: string
          description: The type of the playlist item. Always playlist.
          example: playlist
        name:
          type: string
          description: The name of the playlist.
        thumbnail:
          type: string
          description: The thumbnail of the playlist.
        url:
          type: string
          description: The relative URL of the playlist.
        videos:
          type: integer
          description: The number of videos in the playlist.
    SearchItem:
      type: object
      discriminator:
        propertyName: type
      oneOf:
        - $ref: "#/components/schemas/StreamItem"
        - $ref: "#/components/schemas/ChannelItem"
        - $ref: "#/components/schemas/PlaylistItem"
    SearchPage:
      type: object
      properties:
        corrected:
          type: boolean
          description: Whether the search query was corrected.
        items:
          type: array
          items:
            $ref: "#/components/schemas/SearchItem"
          example:
            - description: "Join us in spreading privacy and security to the masses. Home of: 🕵️‍♀️ Go Incognito | A Guide To Security, Privacy, ..."
              name: "Techlore"
              subscribers: 192000
              thumbnail: "https://pipedproxy.kavin.rocks/lwHqZYuTM3v0oBB_RevOFbD_cHL7AWUfYID_iv8trv6_4u4r7Go_t4qFJplYiJNQVC-14Tb8=s88-c-k-c0x00ffffff-no-rw-mo?host=yt3.ggpht.com"
              url: "/channel/UCs6KfncB4OV6Vug4o_bzijg"
              verified: true
              videos: 320
            - duration: 527
              shortDescription: "Top 10 best tools to boost privacy and security today. Most times, you need to put in a lot of effort to gain privacy, security, and ..."
              thumbnail: "https://pipedproxy.kavin.rocks/vi/LLpLU317zfc/hq720.jpg?sqp=-oaymwEcCOgCEMoBSFbyq4qpAw4IARUAAIhCGAFwAcABBg==&rs=AOn4CLDZO4ZxHFoyHKmPQTZAVVVDTmB8FA&host=i.ytimg.com"
              title: "Top 10 Tools To Boost Privacy & Security!"
              uploaded: 1625590800000
              uploadedDate: "1 year ago"
              uploaderAvatar: "https://pipedproxy.kavin.rocks/lwHqZYuTM3v0oBB_RevOFbD_cHL7AWUfYID_iv8trv6_4u4r7Go_t4qFJplYiJNQVC-14Tb8=s68-c-k-c0x00ffffff-no-rw?host=yt3.ggpht.com"
              uploaderName: "Techlore"
              uploaderUrl: "/channel/UCs6KfncB4OV6Vug4o_bzijg"
              uploaderVerified: true
              url: "/watch?v=LLpLU317zfc"
              views: 113599
        nextpage:
          type: string
          nullable: true
          description: The parameter used to get the next page of this page.
        suggestion:
          type: string
          nullable: true
          example: null
          description: The suggested search query.