refactor: move all kinds of api path documentation to openapi
This commit is contained in:
Bnyro
GitHub
parent
ba80336585
commit
85155573de
|
|
@ -14,352 +14,10 @@ An example on how this can be done is available at https://github.com/TeamPiped/
|
||||||
|
|
||||||
## Base URL
|
## 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
|
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
|
## API Paths
|
||||||
|
|
||||||
These endpoints work un-authenticated, and you're highly discouraged to send an `Authorization` header for these endpoints.
|
The OpenAPI specification for Piped is located at https://github.com/TeamPiped/OpenAPI/main/swagger.yaml. In order to properly view and inspect the available API routes, you
|
||||||
|
can open https://petstore.swagger.io in a web browser, paste https://raw.githubusercontent.com/TeamPiped/OpenAPI/main/swagger.yaml into the text field at the top and finally
|
||||||
### /streams/:videoId
|
click explore. Swagger UI allows you to test the documented API paths and see the required and returned parameters for requests and their responses.
|
||||||
|
|
||||||
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
|
|
||||||
"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:
|
|
||||||
|
|
||||||
```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
|
|
||||||
"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:
|
|
||||||
|
|
||||||
```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
|
|
||||||
"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.
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### /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
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue