--- title: "API Documentation" weight: 4 summary: A guide on how to use Piped's API. --- ## API Servers A list of public instances can be found at https://github.com/TeamPiped/Piped/wiki/Instances To keep up-to date with the instances list, you are expected to dynamically parse it. An example on how this can be done is available at https://github.com/TeamPiped/Piped/blob/85e2296dc410fd20375d623465900c55b5483da9/src/components/Preferences.vue#L202-L221 ## Base URL For all endpoints in this documentation, you will have to use an API url as a prefix. For example, the official instance's base URL would be https://pipedapi.kavin.rocks ## Unauthenticated Endpoints These endpoints work un-authenticated, and you're highly discouraged to send an `Authorization` header for these endpoints. ### /streams/:videoId Parameters: - `videoId`: The video ID of the YouTube video you want to get information about. Response: ```javascript { "audioStreams": [ { "bitrate": 0, // The bitrate of the audio stream in bytes "codec": "mp4a.40.5", // The codec of the audio stream "format": "M4A", // The format of the audio stream "indexEnd": 0, // Useful for creating dash streams "indexStart": 0, // Useful for creating dash streams "initStart": 0, // Useful for creating dash streams "initEnd": 0, // Useful for creating dash streams "mimeType": "audio/mp4", // The mime type of the audio stream "quality": "48 kbps", // The quality of the audio stream "url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL "videoOnly": false // Whether or not the stream is video only } ], // The audio streams of the video "dash": null, // The dash manifest URL, to be used if not null (for OTF streams) "description": "", // The description of the video "dislikes": 0, // The number of dislikes the video has "duration": 0, // The duration of the video in seconds "hls": null, // The hls manifest URL, to be used for Livestreams, "lbryId": "", // The lbry id of the video, if available "likes": 0, // The number of likes the video has "livestream": false, // Whether or not the video is a livestream "proxyUrl": "https://pipedproxy-bom.kavin.rocks", // The proxy url to be used for rewrites "relatedStreams": [ { "duration": 0, // The duration of the related video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the related video "title": "", // The title of the related video "uploadedDate": "3 months ago", // The date the related video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the related video "uploaderUrl": "/channel/...", // The URL of the channel of the related video "uploaderVerified": true, // Whether or not the channel of the related video is verified "url": "/watch?v=..." // The URL of the related video "views": 0 // The number of views the related video has } ], // A list of related streams "subtitles": [ { "autoGenerated": false, // Whether or not the subtitle was auto-generated "code": "en", // The language code of the subtitle "mimeType": "application/ttml+xml", // The mime type of the subtitle "name": "English", // The name of the subtitle "url": "https://pipedproxy-bom.kavin.rocks/api/timedtext?..." // The URL of the subtitle } ], // A list of subtitles "thumbnailUrl": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the video "title": "", // The title of the video "uploadedDate": "2021-01-01", // The date the video was uploaded "uploader": "", // The name of the channel of the video "uploaderUrl": "/channel/...", // The URL of the channel of the video "uploaderVerified": true, // Whether or not the channel of the video is verified "videoStreams": [ { "bitrate": 0, // The bitrate of the video stream in bytes "codec": "avc1.64002a", // The codec of the video stream "format": "MPEG_4", // The format of the video stream "fps": 30, // The frames per second of the video stream "height": 720, // The height of the video stream "indexEnd": 0, // Useful for creating dash streams "indexStart": 0, // Useful for creating dash streams "initStart": 0, // Useful for creating dash streams "initEnd": 0, // Useful for creating dash streams "mimeType": "video/mp4", // The mime type of the video stream "quality": "720p", // The quality of the video stream "url": "https://pipedproxy-bom.kavin.rocks/videoplayback?...", // The stream's URL "videoOnly": false // Whether or not the stream is video only "width": 1280 // The width of the video stream } ], // The video streams of the video "views": 0 // The number of views the video has } ``` ### /comments/:videoId Parameters: - `videoId`: The video ID of the YouTube video you want to get comments for. Response: ```javascript { "comments": [ { "author": "", // The name of the author of the comment "commentId": "", // The comment ID "commentText": "", // The text of the comment "commentedTime": "14 hours ago", // The time the comment was made "commentorUrl": "/channel/...", // The URL of the channel of the comment "hearted": false, // Whether or not the comment has been hearted "likeCount": 0, // The number of likes the comment has "pinned": false, // Whether or not the comment is pinned "thumbnail": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the comment "verified": false // Whether or not the author of the comment is verified } ], // A list of comments "disabled": false, // Whether or not the comments are disabled "nextpage": "" // A JSON encoded page, which is used for the nextpage endpoint. } ``` ### /nextpage/comments/:videoId Parameters: - `videoId`: The video ID of the YouTube video you want to get comments for. - `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. Response: ```javascript { "comments": [ { "author": "", // The name of the author of the comment "commentId": "", // The comment ID "commentText": "", // The text of the comment "commentedTime": "14 hours ago", // The time the comment was made "commentorUrl": "/channel/...", // The URL of the channel of the comment "hearted": false, // Whether or not the comment has been hearted "likeCount": 0, // The number of likes the comment has "pinned": false, // Whether or not the comment is pinned "thumbnail": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the comment "verified": false // Whether or not the author of the comment is verified } ], // A list of comments "disabled": false, // Whether or not the comments are disabled "nextpage": "" // A JSON encoded page, which is used for the nextpage endpoint. } ``` ### /trending Parameters: - `region`: The region you want to get trending YouTube videos from. Example: `US`. Response: ```javascript [ { "duration": 0, // The duration of the trending video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the trending video "title": "", // The title of the trending video "uploadedDate": "12 hours ago", // The date the trending video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the trending video "uploaderUrl": "/channel/...", // The URL of the channel of the trending video "uploaderVerified": true, // Whether or not the channel of the trending video is verified "url": "/watch?v=..." // The URL of the trending video "views": 0 // The number of views the trending video has } ] // A list of trending videos ``` ### /channel/:channelId Parameters: - `channelId`: The channel ID of the YouTube channel you want to get information about. ### /c/:name Parameters: - `name`: The name of the channel you want to get information about. ### /user/:name Parameters: - `name`: The name of the user's channel you want to get information about. Response: ```javascript { "avatarUrl": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel "bannerUrl": "https://pipedproxy-bom.kavin.rocks/...", // The banner of the channel "description": "", // The description of the channel "id": "", // The ID of the channel "name": "", // The name of the channel "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. "relatedStreams: [ { "duration": 0, // The duration of the channel's video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the channel's video "title": "", // The title of the channel's video "uploadedDate": "3 months ago", // The date the channel's video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the channel's video "uploaderUrl": "/channel/...", // The URL of the channel "uploaderVerified": true, // Whether or not the channel is verified "url": "/watch?v=..." // The URL of the channel's video "views": 0, // The number of views the channel's video has } ], // A list of videos from the channel "subscriberCount": 0, // The number of subscribers the channel has "verified": false // Whether or not the channel is verified } ``` ### /nextpage/channel/:channelId Parameters: - `channelId`: The channel ID of the YouTube channel you want to get information about. - `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. Response: ```javascript { "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. "relatedStreams: [ { "duration": 0, // The duration of the channel's video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the channel's video "title": "", // The title of the channel's video "uploadedDate": "3 months ago", // The date the channel's video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the channel's video "uploaderUrl": "/channel/...", // The URL of the channel "uploaderVerified": true, // Whether or not the channel is verified "url": "/watch?v=..." // The URL of the channel's video "views": 0, // The number of views the channel's video has } ] // A list of videos from the channel } ``` ### /playlists/:playlistId Parameters: - `playlistId`: The playlist ID of the YouTube playlist you want to get information about. Response: ```javascript { "bannerUrl": "https://pipedproxy-bom.kavin.rocks/...", // The banner of the playlist "name": "", // The name of the playlist "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. "relatedStreams: [ { "duration": 0, // The duration of the playlist's video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the playlist's video "title": "", // The title of the playlist's video "uploadedDate": "3 months ago", // The date the playlist's video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the playlist's video "uploaderUrl": "/channel/...", // The URL of the channel of the playlist's video "uploaderVerified": true, // Whether or not the playlist is verified "url": "/watch?v=..." // The URL of the playlist's video "views": 0, // The number of views the playlist's video has } ], // A list of videos from the playlist "thumbnailUrl": "https://pipedproxy-bom.kavin.rocks/...", // The thumbnail of the playlist "uploader": "", // The name of the creator of the playlist "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the creator of the playlist "uploaderUrl": "/channel/...", // The URL of the creator of the playlist "videos": 0 // The number of videos in the playlist } ``` ### /nextpage/playlists/:playlistId Parameters: - `playlistId`: The playlist ID of the YouTube playlist you want to get information about. - `nextpage`: The JSON encoded nextpage variable, to be sent as a query string. Response: ```javascript { "nextpage": "", // A JSON encoded page, which is used for the nextpage endpoint. "relatedStreams: [ { "duration": 0, // The duration of the playlist's video in seconds "thumbnail": "https://pipedproxy-bom.kavin.rocks/vi/...", // The thumbnail of the playlist's video "title": "", // The title of the playlist's video "uploadedDate": "3 months ago", // The date the playlist's video was uploaded "uploaderAvatar": "https://pipedproxy-bom.kavin.rocks/...", // The avatar of the channel of the playlist's video "uploaderUrl": "/channel/...", // The URL of the channel of the playlist's video "uploaderVerified": true, // Whether or not the playlist is verified "url": "/watch?v=..." // The URL of the playlist's video "views": 0, // The number of views the playlist's video has } ] // A list of videos from the playlist } ``` ### /suggestions Parameters: - `query`: The query string to get search suggestions for. Response: ```javascript [ "", // The search suggestion "" // Another search suggestion ] // A list of search suggestions ``` ### /sponsors/:videoId Parameters: - `videoId`: The video ID of the YouTube video you want to get information about. - `category`: The category of sponsors you would like to skip. Example: `["sponsor"]`. See the [SponsorBlock Wiki](https://wiki.sponsor.ajay.app/index.php/Segment_Categories) for more information. Response: ```javascript { "hash": "", // The hash of the videoId "segments": [ { "UUID": "", // The UUID of the segment "actionType": "skip", // The action type of the segment "category": "sponsor", // The category of the segment "segment": [0, 10], // The start and end time of the segment "videoDuration": 0 // The duration of the video } "videoID": "" // The video ID of the segment } ```