documentation/docs/api.md
ChunkyProgrammer bd5c262fb1
Update api documentation with new endpoints and fixes (#501)
* Fix documentation on search's `sort` parameter

* remove `news` from trending type

* Remove channels/comments documentation

* Remove channels search documentation from api.md page

* add missing endpoints

* fix `resolveurl` name

* update param description for community post comments

* update `search-filters.md` and `url-parameters.md` to include api changes
2024-06-26 10:08:11 +02:00

576 lines
9.9 KiB
Markdown

# API
### Language
All endpoints that return a JSON body support `&hl=LANGUAGE` for translating fields into the desired language. A list of languages are provided in [List of URL parameters](./url-parameters.md).
##### GET `/api/v1/stats`
> Schema:
```javascript
{
"version": String,
"software": {
"name": "invidious",
"version": String,
"branch": String
},
"openRegistrations": Bool,
"usage": {
"users": {
"total": Int32,
"activeHalfyear": Int32,
"activeMonth": Int32
}
},
"metadata": {
"updatedAt": Int64,
"lastChannelRefreshedAt": Int64
},
"playback": {
"totalRequests": Int32?
"successfulRequests": Int32?
"ratio": Float32?
}
}
```
##### GET `/api/v1/videos/:id`
> Schema:
```javascript
{
"type": String, // "video"|"published"
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"storyboards": [
{
"url": String,
"templateUrl": String,
"width": Int32,
"height": Int32,
"count": Int32,
"interval ": Int32,
"storyboardWidth": Int32,
"storyboardHeight": Int32,
"storyboardCount": Int32
}
],
"description": String,
"descriptionHtml": String,
"published": Int64,
"publishedText": String,
"keywords": Array(String),
"viewCount": Int64,
"likeCount": Int32,
"dislikeCount": Int32,
"paid": Bool,
"premium": Bool,
"isFamilyFriendly": Bool,
"allowedRegions": Array(String),
"genre": String,
"genreUrl": String,
"author": String,
"authorId": String,
"authorUrl": String,
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
"subCountText": String,
"lengthSeconds": Int32,
"allowRatings": Bool,
"rating": Float32,
"isListed": Bool,
"liveNow": Bool,
"isPostLiveDvr": Bool,
"isUpcoming": Bool,
"dashUrl:" String,
"premiereTimestamp": Int64?,
"hlsUrl": String?,
"adaptiveFormats": [
{
"index": String,
"bitrate": String,
"init": String,
"url": String,
"itag": String,
"type": String,
"clen": String,
"lmt": String,
"projectionType": Int32,
"container": String,
"encoding": String,
"qualityLabel": String?,
"resolution": String?
}
],
"formatStreams": [
{
"url": String,
"itag": String,
"type": String,
"quality": String,
"container": String,
"encoding": String,
"qualityLabel": String,
"resolution": String,
"size": String
}
],
"captions": [
{
"label": String,
"languageCode": String,
"url": String
}
],
"recommendedVideos": [
{
"videoId": String,
"title": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"author": String,
"lengthSeconds": Int32,
"viewCountText": String
}
]
}
```
Parameters:
```
region: ISO 3166 country code (default: "US")
```
##### GET `/api/v1/annotations/:id`
Parameters:
```
source: "archive", "youtube" (default: "archive")
```
Returns annotation XML from YouTube's `/annotations_invideo` endpoint. Alternatively it provides access to legacy annotation data using [this collection](https://archive.org/details/youtubeannotations) on archive.org.
##### GET `/api/v1/comments/:id`
> Schema:
```javascript
{
"commentCount": Int32?,
"videoId": String,
"comments": [
{
"author": String,
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
"authorId": String,
"authorUrl": String,
"isEdited": Boolean,
"isPinned": Boolean,
"content": String,
"contentHtml": String,
"published": Int64,
"publishedText": String,
"likeCount": Int32,
"commentId": String,
"authorIsChannelOwner": Bool,
"creatorHeart": {
"creatorThumbnail": String,
"creatorName": String
}?,
"replies": {
"replyCount": Int32,
"continuation": String
}?
}
],
"continuation": String?
}
```
Parameters:
```
sort_by: "top", "new" (default: top)
source: "youtube", "reddit" (default: youtube)
continuation: String
```
##### GET `/api/v1/captions/:id`
> Schema:
```javascript
{
"captions": [
{
"label": String,
"languageCode": String,
"url": String
}
]
}
```
Parameters:
```
label: String
lang: String
tlang: String
region: ISO 3166 country code (default: "US")
```
A request with `label` will return the selected captions in WebVTT format.
Captions can also be selected with an ISO `lang`, e.g. &lang=en, `tlang` will auto-translate from English into the requested language (if English captions are available).
##### GET `/api/v1/trending`
> Schema:
```javascript
[
{
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"lengthSeconds": Int32,
"viewCount": Int64,
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
"publishedText": String,
"description": String,
"descriptionHtml": String,
"liveNow": Bool,
"paid": Bool,
"premium": Bool
}
]
```
Parameters:
```
type: "music", "gaming", "movies", "default"
region: ISO 3166 country code (default: "US")
```
##### GET `/api/v1/popular`
> Schema:
```javascript
[
{
"type": "shortVideo",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"lengthSeconds": Int32,
"viewCount": Int64,
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
"publishedText": String
}
]
```
##### GET `/api/v1/search/suggestions`
> Schema:
```javascript
{
"query": String,
"suggestions": Array(String)
}
```
Parameters:
```
q: String
```
##### GET `/api/v1/search`
> Schema:
```javascript
[
{
type: "video",
title: String,
videoId: String,
author: String,
authorId: String,
authorUrl: String,
videoThumbnails: [
{
quality: String,
url: String,
width: Int32,
height: Int32
}
],
description: String,
descriptionHtml: String,
viewCount: Int64,
published: Int64,
publishedText: String,
lengthSeconds: Int32,
liveNow: Bool,
paid: Bool,
premium: Bool
},
{
type: "playlist",
title: String,
playlistId: String,
playlistThumbnail: String,
author: String,
authorId: String,
authorUrl: String,
authorVerified: Boolean,
videoCount: Int32,
videos: [
{
title: String,
videoId: String,
lengthSeconds: Int32,
videoThumbnails: [
{
quality: String,
url: String,
width: Int32,
height: Int32
}
]
}
]
},
{
type: "channel",
author: String,
authorId: String,
authorUrl: String,
authorThumbnails: [
{
url: String,
width: Int32,
height: Int32
}
],
autoGenerated: Bool
subCount: Int32,
videoCount: Int32,
description: String,
descriptionHtml: String
}
];
```
Parameters:
```
q: String
page: Int32
sort: "relevance", "rating", "date", "views"
date: "hour", "today", "week", "month", "year"
duration: "short", "long", "medium"
type: "video", "playlist", "channel", "movie", "show", "all", (default: all)
features: "hd", "subtitles", "creative_commons", "3d", "live", "purchased", "4k", "360", "location", "hdr", "vr180" (comma separated: e.g. "&features=hd,subtitles,3d,live")
region: ISO 3166 country code (default: "US")
```
##### GET `/api/v1/playlists/:plid`
> Schema:
```javascript
{
"title": String,
"playlistId": String,
"author": String,
"authorId": String,
"authorThumbnails": [
{
"url": String,
"width": String,
"height": String
}
],
"description": String,
"descriptionHtml": String,
"videoCount": Int32,
"viewCount": Int64,
"updated": Int64,
"videos": [
{
"title": String,
"videoId": String,
"author": String,
"authorId": String,
"authorUrl": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"index": Int32,
"lengthSeconds": Int32
}
]
}
```
Parameters:
```
page: Int32
```
##### GET `/api/v1/mixes/:rdid`
> Schema:
```javascript
{
title: String,
mixId: String,
videos: [
{
title: String,
videoId: String,
author: String,
authorId: String,
authorUrl: String,
videoThumbnails: [
{
quality: String,
url: String,
width: Int32,
height: Int32
}
],
index: Int32,
lengthSeconds: Int32
}
]
}
```
##### GET `/api/v1/hashtag/:tag`
> Schema:
```javascript
{
results: VideoObject[],
}
```
Parameters:
```
page: Int32
```
##### GET `/api/v1/resolveurl`
> Schema:
```javascript
{
ucid?: String,
videoId?: String,
playlistId?: String,
startTimeSeconds?: String,
params?: String,
pageType: string
}
```
Parameters:
```
url: URL
```
##### GET `/api/v1/clips`
> Schema:
```javascript
{
startTime: Float64, // in seconds
endTime: Float64, // in seconds
clipTitle: String,
video: VideoObject
}
```
Parameters:
```
id: string
```