OpenAPI/swagger.yaml
2024-02-25 17:02:29 +01:00

949 lines
27 KiB
YAML

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",
"music_artists",
]
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:
itag:
type: integer
description: The itag of the stream, or -1 if not available.
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
audioTrackId:
type: string
nullable: true
audioTrackName:
type: string
nullable: true
audioTrackType:
type: string
nullable: true
audioTrackLocale:
type: string
nullable: true
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
format: int64
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
contentLength:
type: integer
description: The content length of the video.
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.
creatorReplied:
type: boolean
description: Whether the video's uploader replied to the comment.
channelOwner:
type: boolean
description: Whether the author of the comment is the video's uploader.
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
mapping:
stream: "#/components/schemas/StreamItem"
channel: "#/components/schemas/ChannelItem"
playlist: "#/components/schemas/PlaylistItem"
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.