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: unauthenticated description: Requests that can be made by anyone - 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: - 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 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: - unauthenticated summary: Gets Channel Information 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 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: - unauthenticated summary: Gets Channel Information 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: - unauthenticated summary: Gets Channel Information 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: - 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 - 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: - 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 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: - 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 - 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: - 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: - 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: - 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 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: required: - duration - thumbnail - title - url properties: 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. 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: 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: 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 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.