API Documentation

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:

{  "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  "uploadDate": "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:

{  "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  "creatorReplied": false // Whether the creator has replied to the comment  }  ], // 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:

{  "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  "creatorReplied": false // Whether the creator has replied to the comment  }  ], // 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. } 

Parameters:

  • region: The region you want to get trending YouTube videos from. Example: US.

Response:

[  {  "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:

{  "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:

{  "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:

{  "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:

{  "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:

[ "", // 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 for more information.

Response:

{  "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 }