documentation/docs/api.md

689 lines
12 KiB
Markdown
Raw Normal View History

# API
2021-01-28 21:04:37 +00:00
### 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).
2019-03-06 02:19:02 +00:00
##### GET `/api/v1/stats`
> Schema:
2019-06-06 03:41:32 +00:00
```javascript
2019-03-06 02:19:02 +00:00
{
"version": String,
"software": {
"name": "invidious",
"version": String,
"branch": String
},
"openRegistrations": Bool,
"usage": {
"users": {
"total": Int32,
"activeHalfyear": Int32,
"activeMonth": Int32
}
},
"metadata": {
"updatedAt": Int64,
"lastChannelRefreshedAt": Int64
}
}
```
2018-08-05 17:19:59 +00:00
##### GET `/api/v1/videos/:id`
2018-09-28 15:58:34 +00:00
> Schema:
2019-06-06 03:41:32 +00:00
```javascript
2018-08-05 17:07:48 +00:00
{
"title": String,
"videoId": String,
"videoThumbnails": [
2018-09-28 15:58:34 +00:00
{
2018-08-05 17:07:48 +00:00
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
2018-08-05 17:07:48 +00:00
],
"description": String,
"descriptionHtml": String,
2018-09-28 15:48:24 +00:00
"published": Int64,
"publishedText": String,
2018-09-28 15:58:34 +00:00
2018-08-05 17:07:48 +00:00
"keywords": Array(String),
"viewCount": Int64,
"likeCount": Int32,
"dislikeCount": Int32,
2018-09-28 15:58:34 +00:00
2018-11-05 01:00:02 +00:00
"paid": Bool,
"premium": Bool,
2018-08-05 17:07:48 +00:00
"isFamilyFriendly": Bool,
"allowedRegions": Array(String),
"genre": String,
2018-09-28 15:48:24 +00:00
"genreUrl": String,
2018-09-28 15:58:34 +00:00
2018-08-05 17:07:48 +00:00
"author": String,
"authorId": String,
"authorUrl": String,
2018-11-05 01:00:02 +00:00
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
2018-08-05 17:07:48 +00:00
2018-11-05 01:00:02 +00:00
"subCountText": String,
2018-08-05 17:07:48 +00:00
"lengthSeconds": Int32,
"allowRatings": Bool,
"rating": Float32,
2019-03-26 23:02:33 +00:00
"isListed": Bool,
"liveNow": Bool,
"isUpcoming": Bool,
"premiereTimestamp": Int64?,
2018-08-05 17:07:48 +00:00
2019-02-25 15:47:40 +00:00
"hlsUrl": String?,
2018-08-05 17:07:48 +00:00
"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?
}
2018-08-05 17:07:48 +00:00
],
"formatStreams": [
{
"url": String,
"itag": String,
"type": String,
"quality": String,
"container": String,
"encoding": String,
"qualityLabel": String,
"resolution": String,
"size": String
}
2018-08-05 17:07:48 +00:00
],
"captions": [
{
"label": String,
2018-09-28 15:48:24 +00:00
"languageCode": String,
2020-06-10 21:31:37 +00:00
"url": String
}
2018-08-05 17:07:48 +00:00
],
"recommendedVideos": [
{
"videoId": String,
"title": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
2018-08-05 17:07:48 +00:00
],
"author": String,
"lengthSeconds": Int32,
2020-06-10 19:02:03 +00:00
"viewCountText": String
2018-08-05 17:07:48 +00:00
}
]
}
```
2019-03-01 16:56:36 +00:00
Parameters:
```
2019-03-01 16:58:19 +00:00
region: ISO 3166 country code (default: "US")
2019-03-01 16:56:36 +00:00
```
2019-04-01 03:44:35 +00:00
##### 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.
2018-09-28 15:58:34 +00:00
##### GET `/api/v1/comments/:id`
> Schema:
2019-06-06 03:41:32 +00:00
```javascript
2018-09-28 15:58:34 +00:00
{
"commentCount": Int32?,
2019-02-09 01:58:06 +00:00
"videoId": String,
2018-09-28 15:58:34 +00:00
"comments": [
{
"author": String,
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
2018-09-28 15:58:34 +00:00
],
"authorId": String,
"authorUrl": String,
"isEdited": Boolean,
"isPinned": Boolean,
2018-09-28 15:58:34 +00:00
"content": String,
"contentHtml": String,
"published": Int64,
"publishedText": String,
"likeCount": Int32,
"commentId": String,
2019-02-09 01:58:06 +00:00
"authorIsChannelOwner": Bool,
"creatorHeart": {
"creatorThumbnail": String,
"creatorName": String
}?,
2018-09-28 15:58:34 +00:00
"replies": {
"replyCount": Int32,
"continuation": String
}?
}
],
"continuation": String?
}
```
Parameters:
```
2019-04-06 01:52:14 +00:00
sort_by: "top", "new" (default: top)
source: "youtube", "reddit" (default: youtube)
2018-09-28 15:58:34 +00:00
continuation: String
```
##### GET `/api/v1/captions/:id`
> Schema:
```javascript
{
"captions": [
{
"label": String,
"languageCode": String,
"url": String
}
]
}
```
Parameters:
```
label: String
2018-11-05 01:00:02 +00:00
lang: String
tlang: String
2019-03-01 16:58:19 +00:00
region: ISO 3166 country code (default: "US")
2018-09-28 15:58:34 +00:00
```
A request with `label` will return the selected captions in WebVTT format.
2018-11-05 01:00:02 +00:00
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).
2018-09-28 15:58:34 +00:00
2018-08-05 17:19:59 +00:00
##### GET `/api/v1/trending`
2018-09-28 15:58:34 +00:00
2018-08-05 17:19:59 +00:00
> Schema:
2018-09-28 15:58:34 +00:00
2019-06-06 03:41:32 +00:00
```javascript
[
2018-08-05 17:30:33 +00:00
{
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
2020-06-10 21:16:13 +00:00
"height": Int32
}
2018-08-05 17:30:33 +00:00
],
"lengthSeconds": Int32,
"viewCount": Int64,
"author": String,
2018-09-28 15:48:24 +00:00
"authorId": String,
2018-08-05 17:30:33 +00:00
"authorUrl": String,
2018-08-05 17:31:51 +00:00
"published": Int64,
2018-09-28 15:48:24 +00:00
"publishedText": String,
2018-08-05 17:30:33 +00:00
"description": String,
2019-02-25 15:47:40 +00:00
"descriptionHtml": String,
"liveNow": Bool,
"paid": Bool,
"premium": Bool
2018-08-05 17:30:33 +00:00
}
]
2018-08-05 17:19:59 +00:00
```
2018-08-05 17:07:48 +00:00
2019-03-01 16:56:36 +00:00
Parameters:
```
type: "music", "gaming", "news", "movies"
2019-03-01 16:58:19 +00:00
region: ISO 3166 country code (default: "US")
2019-03-01 16:56:36 +00:00
```
2019-06-06 03:40:29 +00:00
##### GET `/api/v1/popular`
> Schema:
```javascript
2019-06-06 03:40:29 +00:00
[
{
"type": "shortVideo",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
2019-06-06 03:40:29 +00:00
}
],
"lengthSeconds": Int32,
2020-06-10 21:43:32 +00:00
"viewCount": Int64,
2019-06-06 03:40:29 +00:00
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
2020-06-10 21:45:41 +00:00
"publishedText": String
2019-06-06 03:40:29 +00:00
}
]
```
2019-07-13 03:27:38 +00:00
##### GET `/api/v1/channels/comments/:ucid`, `/api/v1/channels/:ucid/comments`
```javascript
{
"authorId": String,
"comments": [
{
"author": String,
"authorThumbnails": [
"url": String,
"width": Int32,
"height": Int32
],
"authorId": String,
"authorUrl": String,
"isEdited": Bool,
"content": String,
"contentHtml": String,
"published": Int64,
"publishedText": String,
"likeCount": Int32,
"commentId": String,
"authorIsChannelOwner": Bool,
"creatorHeart": {
"creatorThumbnail": String,
"creatorName": String
}?,
"replies": {
"replyCount": Int32,
"continuation": String
}?,
"attachment": Attachment?
}
],
"continuation": String?
}
```
The `authorId` for top-level comments will always(?) be the same as the requested channel. Top-level comments will also have an optional `attachment`, which can be one of:
```javascript
{
"type": "image",
"imageThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
]
}
```
```javascript
{
"type": "video",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"lengthSeconds": Int32,
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
"publishedText": String,
"viewCount": Int64,
"viewCountText": String
}
```
```javascript
{
"type": "unknown",
"error": "Unrecognized attachment type."
}
```
Some attachments may only have a `type` and `error`, similar to the above. Attachments will *only* be present on top-level comments.
Parameters:
```
continuation: String
```
2018-09-28 15:58:34 +00:00
##### GET `/api/v1/channels/search/:ucid`
2018-08-05 17:36:55 +00:00
> Schema:
2018-09-28 15:58:34 +00:00
```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,
2018-11-05 01:00:02 +00:00
liveNow: Bool,
paid: Bool,
premium: Bool
2018-09-28 15:58:34 +00:00
},
{
type: "playlist",
title: String,
playlistId: String,
author: String,
authorId: String,
authorUrl: String,
videoCount: Int32,
videos: [
2018-09-29 00:19:15 +00:00
{
2019-04-01 03:44:35 +00:00
title: String,
videoId: String,
lengthSeconds: Int32,
videoThumbnails: [
2018-09-29 00:19:15 +00:00
{
quality: String,
url: String,
width: Int32,
height: Int32
}
]
}
2018-09-28 15:58:34 +00:00
]
},
{
type: "channel",
author: String,
authorId: String,
authorUrl: String,
authorThumbnails: [
{
url: String,
width: Int32,
height: Int32
}
],
subCount: Int32,
videoCount: Int32,
description: String,
descriptionHtml: String
}
];
```
Parameters:
2018-08-05 17:36:55 +00:00
```
2018-09-28 15:58:34 +00:00
q: String
page: Int32
```
2019-07-13 03:27:38 +00:00
##### GET `/api/v1/search/suggestions`
> Schema:
```javascript
{
"query": String,
"suggestions": Array(String)
}
```
Parameters:
```
q: String
```
2018-09-28 15:58:34 +00:00
##### GET `/api/v1/search`
> Schema:
```javascript
2018-08-07 19:45:21 +00:00
[
{
2018-09-28 15:58:34 +00:00
type: "video",
title: String,
videoId: String,
author: String,
authorId: String,
authorUrl: String,
videoThumbnails: [
2018-08-07 19:45:21 +00:00
{
2018-09-28 15:58:34 +00:00
quality: String,
url: String,
width: Int32,
height: Int32
2018-08-07 19:45:21 +00:00
}
],
2018-09-28 15:58:34 +00:00
description: String,
descriptionHtml: String,
viewCount: Int64,
published: Int64,
publishedText: String,
lengthSeconds: Int32,
2018-11-05 01:00:02 +00:00
liveNow: Bool,
paid: Bool,
premium: Bool
2018-09-28 15:48:24 +00:00
},
{
2018-09-28 15:58:34 +00:00
type: "playlist",
title: String,
playlistId: String,
2023-02-05 13:01:30 +00:00
playlistThumbnail: String,
2018-09-28 15:58:34 +00:00
author: String,
authorId: String,
authorUrl: String,
2023-02-05 13:01:30 +00:00
authorVerified: Boolean,
2018-09-28 15:58:34 +00:00
videoCount: Int32,
videos: [
2018-09-29 00:19:15 +00:00
{
2019-04-01 03:44:35 +00:00
title: String,
videoId: String,
lengthSeconds: Int32,
videoThumbnails: [
2018-09-29 00:19:15 +00:00
{
quality: String,
url: String,
width: Int32,
height: Int32
}
]
}
2018-09-28 15:48:24 +00:00
]
},
{
2018-09-28 15:58:34 +00:00
type: "channel",
author: String,
authorId: String,
authorUrl: String,
2018-09-28 15:48:24 +00:00
2018-09-28 15:58:34 +00:00
authorThumbnails: [
2018-09-28 15:48:24 +00:00
{
2018-09-28 15:58:34 +00:00
url: String,
width: Int32,
height: Int32
2018-09-28 15:48:24 +00:00
}
],
2023-02-05 13:01:30 +00:00
autoGenerated: Bool
2018-09-28 15:58:34 +00:00
subCount: Int32,
videoCount: Int32,
description: String,
descriptionHtml: String
2018-08-07 19:45:21 +00:00
}
2018-09-28 15:58:34 +00:00
];
2018-08-05 17:36:55 +00:00
```
2018-08-07 19:57:58 +00:00
2018-09-28 15:58:34 +00:00
Parameters:
2018-08-08 15:36:46 +00:00
```
2018-09-28 15:58:34 +00:00
q: String
page: Int32
2018-08-08 15:36:46 +00:00
sort_by: "relevance", "rating", "upload_date", "view_count"
date: "hour", "today", "week", "month", "year"
2023-02-05 13:01:30 +00:00
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")
2019-03-01 16:58:19 +00:00
region: ISO 3166 country code (default: "US")
2018-08-08 15:36:46 +00:00
```
2018-09-28 15:58:34 +00:00
##### GET `/api/v1/playlists/:plid`
2018-08-07 19:57:58 +00:00
> Schema:
2018-09-28 15:58:34 +00:00
```javascript
{
"title": String,
"playlistId": String,
2018-08-08 15:36:46 +00:00
2018-09-28 15:58:34 +00:00
"author": String,
"authorId": String,
"authorThumbnails": [
{
"url": String,
"width": String,
"height": String
}
],
"description": String,
"descriptionHtml": String,
2018-08-08 15:36:46 +00:00
2018-09-28 15:58:34 +00:00
"videoCount": Int32,
"viewCount": Int64,
"updated": Int64,
2018-08-08 15:36:46 +00:00
2018-09-28 15:58:34 +00:00
"videos": [
2018-09-29 00:19:15 +00:00
{
"title": String,
"videoId": String,
"author": String,
"authorId": String,
"authorUrl": String,
2019-04-01 03:44:35 +00:00
2018-09-29 00:19:15 +00:00
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"index": Int32,
"lengthSeconds": Int32
}
2018-09-28 15:58:34 +00:00
]
2018-08-07 19:57:58 +00:00
}
2018-08-08 15:36:46 +00:00
```
Parameters:
2018-09-28 15:58:34 +00:00
```
page: Int32
2018-08-08 15:36:46 +00:00
```
2018-11-05 01:00:02 +00:00
##### 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
}
]
}
```