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:
```
METHOD1;METHOD2...:ENDPOINT(*)?
```
Where `METHOD` can be one of `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.
An `ENDPOINT` can be any of the documented endpoints below.
Examples:
-`POST:playlists*`: authorizes `POST` methods 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`: authorizes `GET` only to playlist `IVPAAAAAA`.
-`:preferences`: authorizes _any_ method to `/api/v1/auth/preferences`
-`GET;POST:preferences`: authorizes `GET` or `POST` to `/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:
```
max_results: Int32
page: Int32
```
> Schema:
```javascript
{
"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](https://developer.mozilla.org/en-US/docs/Web/API/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`. The `fields` API can be used, which will be applied to each object.
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.
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:
```javascript
[
{
"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:
```javascript
{
"title": String,
"privacy": "private"
}
```
`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:
```javascript
{
"title": String,
"playlistId": String
}
```
##### 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:
```javascript
{
"title": String,
"description": String,
"privacy": "private"
}
```
`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:
```javascript
{
"videoId": String
}
```
Returns a 201 on success with the following schema:
