documentation/API.md

939 lines
17 KiB
Markdown
Raw Normal View History

### 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](https://github.com/omarroth/invidious/wiki/List-of-URL-parameters).
2019-04-20 15:12:34 -04:00
### Pretty
All endpoints that return a JSON body support `&pretty=1` for printing the response as formatted JSON.
### Fields
2019-06-04 11:55:53 -04:00
All endpoints that return a JSON body support the [fields API](https://developers.google.com/youtube/v3/getting-started#fields) for specifying desired fields to reduce bandwidth consumption. This can be used by adding `&fields=FIELDS` with the desired fields, for example [`/api/v1/videos/aqz-KE-bpKQ?fields=videoId,title,description&pretty=1`](https://invidio.us/api/v1/videos/aqz-KE-bpKQ?fields=videoId,title,description&pretty=1).
2019-04-20 15:12:34 -04:00
2019-03-05 21:19:02 -05:00
##### GET `/api/v1/stats`
> Schema:
2019-06-05 23:41:32 -04:00
```javascript
2019-03-05 21:19:02 -05: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 13:19:59 -04:00
##### GET `/api/v1/videos/:id`
2018-09-28 11:58:34 -04:00
> Schema:
2019-06-05 23:41:32 -04:00
```javascript
2018-08-05 13:07:48 -04:00
{
"title": String,
"videoId": String,
"videoThumbnails": [
2018-09-28 11:58:34 -04:00
{
2018-08-05 13:07:48 -04:00
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
2018-08-05 13:07:48 -04:00
],
"description": String,
"descriptionHtml": String,
2018-09-28 11:48:24 -04:00
"published": Int64,
"publishedText": String,
2018-09-28 11:58:34 -04:00
2018-08-05 13:07:48 -04:00
"keywords": Array(String),
"viewCount": Int64,
"likeCount": Int32,
"dislikeCount": Int32,
2018-09-28 11:58:34 -04:00
2018-11-04 20:00:02 -05:00
"paid": Bool,
"premium": Bool,
2018-08-05 13:07:48 -04:00
"isFamilyFriendly": Bool,
"allowedRegions": Array(String),
"genre": String,
2018-09-28 11:48:24 -04:00
"genreUrl": String,
2018-09-28 11:58:34 -04:00
2018-08-05 13:07:48 -04:00
"author": String,
"authorId": String,
"authorUrl": String,
2018-11-04 20:00:02 -05:00
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
2018-08-05 13:07:48 -04:00
2018-11-04 20:00:02 -05:00
"subCountText": String,
2018-08-05 13:07:48 -04:00
"lengthSeconds": Int32,
"allowRatings": Bool,
"rating": Float32,
2019-03-26 19:02:33 -04:00
"isListed": Bool,
"liveNow": Bool,
"isUpcoming": Bool,
"premiereTimestamp": Int64?,
2018-08-05 13:07:48 -04:00
2019-02-25 10:47:40 -05:00
"hlsUrl": String?,
2018-08-05 13:07:48 -04: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 13:07:48 -04:00
],
"formatStreams": [
{
"url": String,
"itag": String,
"type": String,
"quality": String,
"container": String,
"encoding": String,
"qualityLabel": String,
"resolution": String,
"size": String
}
2018-08-05 13:07:48 -04:00
],
"captions": [
{
"label": String,
2018-09-28 11:48:24 -04:00
"languageCode": String,
2020-06-10 17:31:37 -04:00
"url": String
}
2018-08-05 13:07:48 -04:00
],
"recommendedVideos": [
{
"videoId": String,
"title": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
2018-08-05 13:07:48 -04:00
],
"author": String,
"lengthSeconds": Int32,
2020-06-10 15:02:03 -04:00
"viewCountText": String
2018-08-05 13:07:48 -04:00
}
]
}
```
2019-03-01 11:56:36 -05:00
Parameters:
```
2019-03-01 11:58:19 -05:00
region: ISO 3166 country code (default: "US")
2019-03-01 11:56:36 -05:00
```
2019-03-31 23:44:35 -04: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 11:58:34 -04:00
##### GET `/api/v1/comments/:id`
> Schema:
2019-06-05 23:41:32 -04:00
```javascript
2018-09-28 11:58:34 -04:00
{
"commentCount": Int32?,
2019-02-08 20:58:06 -05:00
"videoId": String,
2018-09-28 11:58:34 -04:00
"comments": [
{
"author": String,
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
2018-09-28 11:58:34 -04:00
],
"authorId": String,
"authorUrl": String,
2019-02-08 20:58:06 -05:00
"isEdited": Bool,
2018-09-28 11:58:34 -04:00
"content": String,
"contentHtml": String,
"published": Int64,
"publishedText": String,
"likeCount": Int32,
"commentId": String,
2019-02-08 20:58:06 -05:00
"authorIsChannelOwner": Bool,
"creatorHeart": {
"creatorThumbnail": String,
"creatorName": String
}?,
2018-09-28 11:58:34 -04:00
"replies": {
"replyCount": Int32,
"continuation": String
}?
}
],
"continuation": String?
}
```
Parameters:
```
2019-04-05 21:52:14 -04:00
sort_by: "top", "new" (default: top)
source: "youtube", "reddit" (default: youtube)
2018-09-28 11:58:34 -04:00
continuation: String
```
2018-09-28 12:00:38 -04:00
##### GET `/api/v1/insights/:id`
2019-03-31 23:44:35 -04:00
**Will always return 510: `YouTube has removed publicly-available analytics`\***
2019-02-25 10:47:40 -05:00
2018-09-28 12:00:38 -04:00
> Schema:
```javascript
{
"viewCount": Int64,
"timeWatchedText": String,
"subscriptionsDriven": Int32,
"shares": Int32,
"avgViewDurationSeconds": Int32,
"graphData": {
2019-06-05 23:40:29 -04:00
// ...
2018-09-28 12:00:38 -04:00
}
}
```
2018-09-28 11:58:34 -04:00
##### GET `/api/v1/captions/:id`
> Schema:
```javascript
{
"captions": [
{
"label": String,
"languageCode": String,
"url": String
}
]
}
```
Parameters:
```
label: String
2018-11-04 20:00:02 -05:00
lang: String
tlang: String
2019-03-01 11:58:19 -05:00
region: ISO 3166 country code (default: "US")
2018-09-28 11:58:34 -04:00
```
A request with `label` will return the selected captions in WebVTT format.
2018-11-04 20:00:02 -05: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 11:58:34 -04:00
2018-08-05 13:19:59 -04:00
##### GET `/api/v1/trending`
2018-09-28 11:58:34 -04:00
2018-08-05 13:19:59 -04:00
> Schema:
2018-09-28 11:58:34 -04:00
2019-06-05 23:41:32 -04:00
```javascript
[
2018-08-05 13:30:33 -04:00
{
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
2020-06-10 17:16:13 -04:00
"height": Int32
}
2018-08-05 13:30:33 -04:00
],
"lengthSeconds": Int32,
"viewCount": Int64,
"author": String,
2018-09-28 11:48:24 -04:00
"authorId": String,
2018-08-05 13:30:33 -04:00
"authorUrl": String,
2018-08-05 13:31:51 -04:00
"published": Int64,
2018-09-28 11:48:24 -04:00
"publishedText": String,
2018-08-05 13:30:33 -04:00
"description": String,
2019-02-25 10:47:40 -05:00
"descriptionHtml": String,
"liveNow": Bool,
"paid": Bool,
"premium": Bool
2018-08-05 13:30:33 -04:00
}
]
2018-08-05 13:19:59 -04:00
```
2018-08-05 13:07:48 -04:00
2019-03-01 11:56:36 -05:00
Parameters:
```
type: "music", "gaming", "news", "movies"
2019-03-01 11:58:19 -05:00
region: ISO 3166 country code (default: "US")
2019-03-01 11:56:36 -05:00
```
2018-08-05 13:36:55 -04:00
##### GET `/api/v1/top`
2018-09-28 11:58:34 -04:00
2018-08-05 13:36:55 -04:00
> Schema:
2018-09-28 11:58:34 -04:00
2019-06-05 23:40:29 -04:00
```javascript
2018-08-07 15:37:58 -04:00
[
{
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
2019-06-05 23:40:29 -04:00
}
2018-08-07 15:37:58 -04:00
],
"lengthSeconds": Int32,
"viewCount": Int64,
"author": String,
2018-09-28 11:48:24 -04:00
"authorId": String,
2018-08-07 15:37:58 -04:00
"authorUrl": String,
"published": Int64,
2018-09-28 11:48:24 -04:00
"publishedText": String,
2018-08-07 15:37:58 -04:00
"description": String,
"descriptionHtml": String
}
]
2018-08-05 13:36:55 -04:00
```
2018-08-05 13:07:48 -04:00
2019-06-05 23:40:29 -04:00
##### GET `/api/v1/popular`
> Schema:
```javascript
2019-06-05 23:40:29 -04:00
[
{
"type": "shortVideo",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
2019-06-05 23:40:29 -04:00
}
],
"lengthSeconds": Int32,
2020-06-10 17:43:32 -04:00
"viewCount": Int64,
2019-06-05 23:40:29 -04:00
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
2020-06-10 17:45:41 -04:00
"publishedText": String
2019-06-05 23:40:29 -04:00
}
]
```
2018-08-05 13:36:55 -04:00
##### GET `/api/v1/channels/:ucid`
2018-09-28 11:58:34 -04:00
2018-08-05 13:36:55 -04:00
> Schema:
2018-09-28 11:58:34 -04:00
2019-06-05 23:40:29 -04:00
```javascript
2018-08-07 15:37:58 -04:00
{
"author": String,
"authorId": String,
"authorUrl": String,
"authorBanners": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
],
2018-09-28 11:58:34 -04:00
2018-08-07 15:37:58 -04:00
"subCount": Int32,
"totalViews": Int64,
"joined": Int64,
2019-02-25 10:47:40 -05:00
2018-08-07 15:37:58 -04:00
"paid": Bool,
2019-02-25 10:47:40 -05:00
"autoGenerated": Bool,
2018-08-07 15:37:58 -04:00
"isFamilyFriendly": Bool,
"description": String,
2018-09-28 11:48:24 -04:00
"descriptionHtml": String,
2018-08-07 15:37:58 -04:00
"allowedRegions": Array(String),
2019-02-25 10:47:40 -05:00
2018-08-07 15:37:58 -04:00
"latestVideos": [
{
"title": String,
"videoId": String,
2018-09-28 11:48:24 -04:00
"author": String,
"authorId": String,
"authorUrl": String,
2018-08-07 15:37:58 -04:00
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
2018-09-28 11:48:24 -04:00
],
"description": String,
"descriptionHtml": String,
"viewCount": Int64,
"published": Int64,
"publishedText": String,
2018-11-04 20:00:02 -05:00
"lengthSeconds": Int32,
"paid": Bool,
"premium": Bool
2018-08-07 15:37:58 -04:00
}
2019-02-25 10:47:40 -05:00
],
"relatedChannels": [
{
"author": String,
"authorId": String,
"authorUrl": String,
"authorThumbnails": [
{
"url": String,
"width": Int32,
"height": Int32
}
]
}
2018-08-07 15:37:58 -04:00
]
}
2018-08-05 13:36:55 -04:00
```
2018-08-05 13:07:48 -04:00
2018-11-13 21:36:57 -05:00
Parameters:
```
sort_by: "newest", "oldest", "popular" (default: newest)
```
2018-11-04 20:00:02 -05:00
Note that a channel's username (if it doesn't include spaces) is also valid in place of `ucid`, e.g. `/api/v1/channels/BlenderFoundation`.
2018-09-28 11:49:08 -04:00
##### GET `/api/v1/channels/:ucid/videos`, `/api/v1/channels/videos/:ucid`
2018-09-28 11:58:34 -04:00
2018-08-05 13:36:55 -04:00
> Schema:
2018-09-28 11:58:34 -04:00
```javascript
2018-08-07 15:41:28 -04:00
[
{
2018-09-28 11:58:34 -04:00
title: String,
videoId: String,
author: String,
authorId: String,
authorUrl: String,
2018-09-28 11:48:24 -04:00
2018-09-28 11:58:34 -04:00
videoThumbnails: [
2018-08-07 15:41:28 -04:00
{
2018-09-28 11:58:34 -04:00
quality: String,
url: String,
width: Int32,
height: Int32
2018-08-07 15:41:28 -04:00
}
],
2018-09-28 11:58:34 -04:00
description: String,
descriptionHtml: String,
2018-08-07 15:57:58 -04:00
2018-09-28 11:58:34 -04:00
viewCount: Int64,
published: Int64,
publishedText: String,
lengthSeconds: Int32
2018-11-04 20:00:02 -05:00
paid: Bool,
premium: Bool
2018-08-07 15:41:28 -04:00
}
2019-02-25 10:47:40 -05:00
]
2018-08-05 13:36:55 -04:00
```
2018-08-05 13:07:48 -04:00
2018-08-08 11:36:46 -04:00
Parameters:
2018-09-28 11:58:34 -04:00
2018-08-08 11:36:46 -04:00
```
page: Int32
2018-11-13 21:36:57 -05:00
sort_by: "newest", "oldest", "popular" (default: newest)
2018-08-08 11:36:46 -04:00
```
2019-02-25 10:47:40 -05:00
##### GET `/api/v1/channels/:ucid/latest`, `/api/v1/channels/latest/:ucid`
```javascript
[
{
title: String,
videoId: 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
paid: Bool,
premium: Bool
}
]
```
##### GET `/api/v1/channels/playlists/:ucid`, `/api/v1/channels/:ucid/playlists`
```javascript
{
"playlists": [
{
"title": String,
"playlistId": String,
"author": String,
"authorId": String,
"authorUrl": String,
"videoCount": Int32,
"videos": [
{
"title": String,
"videoId": String,
"lengthSeconds": Int32,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
]
}
]
],
"continuation": String?
}
```
2019-03-01 12:04:08 -05:00
Parameters:
```
continuation: String
sort_by: "oldest", "newest", "last"
```
2019-07-12 23:27:38 -04: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 11:58:34 -04:00
##### GET `/api/v1/channels/search/:ucid`
2018-08-05 13:36:55 -04:00
> Schema:
2018-09-28 11:58:34 -04: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-04 20:00:02 -05:00
liveNow: Bool,
paid: Bool,
premium: Bool
2018-09-28 11:58:34 -04:00
},
{
type: "playlist",
title: String,
playlistId: String,
author: String,
authorId: String,
authorUrl: String,
videoCount: Int32,
videos: [
2018-09-28 20:19:15 -04:00
{
2019-03-31 23:44:35 -04:00
title: String,
videoId: String,
lengthSeconds: Int32,
videoThumbnails: [
2018-09-28 20:19:15 -04:00
{
quality: String,
url: String,
width: Int32,
height: Int32
}
]
}
2018-09-28 11:58:34 -04: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 13:36:55 -04:00
```
2018-09-28 11:58:34 -04:00
q: String
page: Int32
```
2019-07-12 23:27:38 -04:00
##### GET `/api/v1/search/suggestions`
> Schema:
```javascript
{
"query": String,
"suggestions": Array(String)
}
```
Parameters:
```
q: String
```
2018-09-28 11:58:34 -04:00
##### GET `/api/v1/search`
> Schema:
```javascript
2018-08-07 15:45:21 -04:00
[
{
2018-09-28 11:58:34 -04:00
type: "video",
title: String,
videoId: String,
author: String,
authorId: String,
authorUrl: String,
videoThumbnails: [
2018-08-07 15:45:21 -04:00
{
2018-09-28 11:58:34 -04:00
quality: String,
url: String,
width: Int32,
height: Int32
2018-08-07 15:45:21 -04:00
}
],
2018-09-28 11:58:34 -04:00
description: String,
descriptionHtml: String,
viewCount: Int64,
published: Int64,
publishedText: String,
lengthSeconds: Int32,
2018-11-04 20:00:02 -05:00
liveNow: Bool,
paid: Bool,
premium: Bool
2018-09-28 11:48:24 -04:00
},
{
2018-09-28 11:58:34 -04:00
type: "playlist",
title: String,
playlistId: String,
author: String,
authorId: String,
authorUrl: String,
videoCount: Int32,
videos: [
2018-09-28 20:19:15 -04:00
{
2019-03-31 23:44:35 -04:00
title: String,
videoId: String,
lengthSeconds: Int32,
videoThumbnails: [
2018-09-28 20:19:15 -04:00
{
quality: String,
url: String,
width: Int32,
height: Int32
}
]
}
2018-09-28 11:48:24 -04:00
]
},
{
2018-09-28 11:58:34 -04:00
type: "channel",
author: String,
authorId: String,
authorUrl: String,
2018-09-28 11:48:24 -04:00
2018-09-28 11:58:34 -04:00
authorThumbnails: [
2018-09-28 11:48:24 -04:00
{
2018-09-28 11:58:34 -04:00
url: String,
width: Int32,
height: Int32
2018-09-28 11:48:24 -04:00
}
],
2018-09-28 11:58:34 -04:00
subCount: Int32,
videoCount: Int32,
description: String,
descriptionHtml: String
2018-08-07 15:45:21 -04:00
}
2018-09-28 11:58:34 -04:00
];
2018-08-05 13:36:55 -04:00
```
2018-08-07 15:57:58 -04:00
2018-09-28 11:58:34 -04:00
Parameters:
2018-08-08 11:36:46 -04:00
```
2018-09-28 11:58:34 -04:00
q: String
page: Int32
2018-08-08 11:36:46 -04:00
sort_by: "relevance", "rating", "upload_date", "view_count"
date: "hour", "today", "week", "month", "year"
duration: "short", "long"
2018-09-28 11:48:24 -04:00
type: "video", "playlist", "channel", "all", (default: video)
2019-03-01 11:23:02 -05:00
features: "hd", "subtitles", "creative_commons", "3d", "live", "purchased", "4k", "360", "location", "hdr" (comma separated: e.g. "&features=hd,subtitles,3d,live")
2019-03-01 11:58:19 -05:00
region: ISO 3166 country code (default: "US")
2018-08-08 11:36:46 -04:00
```
2018-09-28 11:58:34 -04:00
##### GET `/api/v1/playlists/:plid`
2018-08-07 15:57:58 -04:00
> Schema:
2018-09-28 11:58:34 -04:00
```javascript
{
"title": String,
"playlistId": String,
2018-08-08 11:36:46 -04:00
2018-09-28 11:58:34 -04:00
"author": String,
"authorId": String,
"authorThumbnails": [
{
"url": String,
"width": String,
"height": String
}
],
"description": String,
"descriptionHtml": String,
2018-08-08 11:36:46 -04:00
2018-09-28 11:58:34 -04:00
"videoCount": Int32,
"viewCount": Int64,
"updated": Int64,
2018-08-08 11:36:46 -04:00
2018-09-28 11:58:34 -04:00
"videos": [
2018-09-28 20:19:15 -04:00
{
"title": String,
"videoId": String,
"author": String,
"authorId": String,
"authorUrl": String,
2019-03-31 23:44:35 -04:00
2018-09-28 20:19:15 -04:00
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"index": Int32,
"lengthSeconds": Int32
}
2018-09-28 11:58:34 -04:00
]
2018-08-07 15:57:58 -04:00
}
2018-08-08 11:36:46 -04:00
```
Parameters:
2018-09-28 11:58:34 -04:00
```
page: Int32
2018-08-08 11:36:46 -04:00
```
2018-11-04 20:00:02 -05: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
}
]
}
```