API - Authenticated endpoints
All endpoints under namespace /api/v1/auth require authentication.
Authentication can be in one of two forms:
- A
Cookie: <SID>header (for logged in users) - An
Authentication: Bearer <TOKEN>(recommended)
A new token can be generated from /authorize_token with the given parameters:
scopes: Comma-separated list of scopes
callback_url: URL to redirect to with generated token
expire: Int64 how long a given token should be valid (in seconds)
Each scope has the following format:
Where METHOD can be one of GET, POST, PUT, DELETE, PATCH.
An ENDPOINT can be any of the documented endpoints below.
Examples:
-
POST:playlists*: authorizesPOSTmethods to any endpoint under/api/v1/auth/playlists(/api/v1/auth/playlists,/api/v1/playlists/:id/videos, etc.) -
:playlists/*: authorizes any method to endpoints under/api/v1/auth/playlists/(/api/v1/auth/playlists/:id,/api/v1/playlists/:id/videos, etc.) -
GET:playlists/IVPAAAAAAA: authorizesGETonly to playlistIVPAAAAAAA. -
:preferences: authorizes any method to/api/v1/auth/preferences -
GET;POST:preferences: authorizesGETorPOSTto/api/v1/auth/preferences
When a callback_url is specified, after a user has authorized a token with the desired scopes, a GET request will be made to the callback_url with the token URL-escaped and appended as token=TOKEN.
GET /api/v1/auth/feed
Get subscription feed for the authenticated user.
Parameters:
Schema:
{
"notifications": [
{
"type": "shortVideo",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int64,
"height": Int64
}
],
"lengthSeconds": Int64,
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
"publishedText": String,
"viewCount": Int64
}
],
"videos": [
{
"type": "shortVideo",
"title": String,
"videoId": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int64,
"height": Int64
}
],
"lengthSeconds": Int64,
"author": String,
"authorId": String,
"authorUrl": String,
"published": Int64,
"publishedText": String,
"viewCount": Int64
}
]
}
GET /api/v1/auth/notifications
Parameters:
topics: Array(String) (comma separated: e.g. "UCID1,UCID2) limit of 1000 topics
since: Int64, timestamp
Provides an EventSource for receiving changes from each topic in topics. Currently the only supported topic-type is ucid, which will return an updated video object whenever the given channel uploads a video.
Important to note is that an event will also be sent when a channel changes an already uploaded video, for example changing description or title.
Each event is a JSON object with the same schema as /api/v1/videos.
A debug topic can also provided which will return a (psuedo-)randomly selected video every minute.
since will return all videos uploaded since TIMESTAMP, with a limit of the 15 most recent videos from each topic.
More details in #469.
POST /api/v1/auth/notifications
Same as above GET endpoint, however topics is moved into post body as Content-Type: application/x-www-form-urlencoded.
GET /api/v1/auth/playlists
Get list of playlists for the given user.
Schema:
[
{
"type": "invidiousPlaylist",
"title": String,
"playlistId": String,
"author": String,
"authorId": null,
"authorUrl": null,
"authorThumbnails": [],
"description": String,
"descriptionHtml": String,
"videoCount": Int32,
"viewCount": 0,
"updated": Int64,
"isListed": Boolean,
"videos": [
{
"title": String,
"videoId": String,
"author": String,
"authorId": String,
"authorUrl": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
],
"index": Int32,
"indexId": String,
"lengthSeconds": Int32
}
]
}
]
POST /api/v1/auth/playlists
Content-Type: application/json
Create new playlist.
Example request body:
privacy can be any of: public, unlisted, private
If successful, returns 201, a link to the created resource as a Location header, and the following response:
GET /api/v1/auth/playlists/:id
Returns same result as unauthenticated /api/v1/playlists/:id.
Important to note is that if the requested playlist is marked as private, it will return an error if the request is not authenticated as the playlist's author.
PATCH /api/v1/auth/playlists/:id
Content-Type: application/json
Modify a playlist's description, title, description, or privacy.
Example request body:
privacy can be any of: public, unlisted, private
Will return 204 on success.
DELETE /api/v1/auth/playlists/:id
Delete a given playlist :id.
Will return 204 on success.
POST /api/v1/auth/playlists/:id/videos
Content-Type: application/json
Add a video to the given playlist :id.
Example request body:
Returns a 201 on success with the following schema:
{
"title": String,
"videoId": String,
"author": String,
"authorId": String,
"authorUrl": String,
"videoThumbnails": [
{
"quality": String,
"url": String,
"width": Int32,
"height": Int32
}
]
}
DELETE /api/v1/auth/playlists/:id/videos/:index
Delete a video from the given playlist :id with indexId :index.
Will return 204 on success.
GET /api/v1/auth/preferences
Get preferences for authenticated user.
Schema:
{
"annotations": false,
"annotations_subscribed": false,
"autoplay": false,
"captions": [
"",
"",
""
],
"comments": [
"youtube",
""
],
"continue": false,
"continue_autoplay": true,
"dark_mode": "light",
"latest_only": false,
"listen": false,
"local": false,
"locale": "en-US",
"max_results": 40,
"notifications_only": false,
"player_style": "invidious",
"quality": "hd720",
"default_home": "Popular",
"feed_menu": [
"Trending",
"Playlists"
],
"related_videos": true,
"sort": "published",
"speed": 1.0,
"thin_mode": false,
"unseen_only": false,
"video_loop": false,
"volume": 100
}
POST /api/v1/auth/preferences
Content-Type: application/json
Patch user preferences.
Example body:
GET /api/v1/auth/subscriptions
Get user's subscriptions.
Schema:
POST /api/v1/auth/subscriptions/:ucid
Content-Type: application/json
Add a given ucid to a user's subscriptions.
Will return 204 on success.
DELETE /api/v1/auth/subscriptions/:ucid
Removes a given ucid from a user's subscriptions.
Will return 204 on success.
GET /api/v1/auth/tokens
Get a list of tokens for the authenticated user.
Schema:
POST /api/v1/auth/tokens/register
Content-Type: application/json
Create a new token for the authenticated user.
Example request body:
{
"scopes": Array(String), // Each scope has same format as each scope in `/authorize_token`
"callbackUrl": String?,
"expire": Int64
}
Returns a 200 on success with the newly created token as the response body.
Example response:
{
"session":"v1:YUwKEL1XwHQzp7-AAAAAAAAAAAAAAAAAA=",
"scopes":["GET:notifications"],
"signature":"jNYdAAAAAAAAAAAAAAAAAAAAAAAAAAAAVAXGb__2Gv-w="
}
POST /api/v1/auth/tokens/unregister
Content-Type: application/json
Revoke a token for the authenticated user.
Example request:
Returns 204 on success.
GET /api/v1/auth/history
Get the history of videos played by the user.
Parameters:
Schema:
POST /api/v1/auth/history/:id
Set a video as watched.
Returns 204 on success.
DELETE /api/v1/auth/history/:id
Delete a video from the user watched history.
Returns 204 on success.