mirror of
https://github.com/tubearchivist/docs.git
synced 2024-11-14 16:10:12 +00:00
add api docs
This commit is contained in:
parent
1b37761979
commit
62c2a5da6f
141
mkdocs/docs/api/additional.md
Normal file
141
mkdocs/docs/api/additional.md
Normal file
@ -0,0 +1,141 @@
|
|||||||
|
# Additional API endpoints
|
||||||
|
|
||||||
|
## Login
|
||||||
|
Return token and user ID for username and password:
|
||||||
|
**POST** `/api/login/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "tubearchivist",
|
||||||
|
"password": "verysecret"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
after successful login returns
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
||||||
|
"user_id": 1
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Refresh
|
||||||
|
**GET** `/api/refresh/`
|
||||||
|
|
||||||
|
Parameters:
|
||||||
|
|
||||||
|
- **type**: one of *video*, *channel*, *playlist*, optional
|
||||||
|
- **id**: item id, optional
|
||||||
|
|
||||||
|
without specifying type: return total for all queued items:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"total_queued": 2,
|
||||||
|
"type": "all",
|
||||||
|
"state": "running"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
specify type: return total items queue of this type:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"total_queued": 2,
|
||||||
|
"type": "video",
|
||||||
|
"state": "running"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
specify type *and* id to get state of item in queue:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"total_queued": 2,
|
||||||
|
"type": "video",
|
||||||
|
"state": "in_queue",
|
||||||
|
"id": "video-id"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**POST** `/api/refresh/`
|
||||||
|
|
||||||
|
Parameter:
|
||||||
|
|
||||||
|
- extract_videos: to refresh all videos for channels/playlists, default False
|
||||||
|
|
||||||
|
Manually start a refresh task: post list of *video*, *channel*, *playlist* IDs:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"video": ["video1", "video2", "video3"],
|
||||||
|
"channel": ["channel1", "channel2", "channel3"],
|
||||||
|
"playlist": ["playlist1", "playlist2"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cookie
|
||||||
|
Check your youtube cookie settings, *status* turns to `true` if cookie has been validated.
|
||||||
|
**GET** `/api/cookie/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cookie_enabled": true,
|
||||||
|
"status": true,
|
||||||
|
"validated": 1680953715,
|
||||||
|
"validated_str": "timestamp"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**POST** `/api/cookie/`
|
||||||
|
Send empty post request to validate cookie.
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cookie_validated": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**PUT** `/api/cookie/`
|
||||||
|
Send put request containing the cookie as a string:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cookie": "your-cookie-as-string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Imports and validates cookie, returns on success:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cookie_import": "done",
|
||||||
|
"cookie_validated": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Or returns status code 400 on failure:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"cookie_import": "fail",
|
||||||
|
"cookie_validated": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Search
|
||||||
|
**GET** `/api/search/?query=<query>`
|
||||||
|
|
||||||
|
Returns search results from your query.
|
||||||
|
|
||||||
|
## Watched
|
||||||
|
**POST** `/api/watched/`
|
||||||
|
|
||||||
|
Change watched state, where the `id` can be a single video, or channel/playlist to change all videos belonging to that channel/playlist.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "xxxxxxx",
|
||||||
|
"is_watched": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Ping
|
||||||
|
Validate your connection with the API
|
||||||
|
**GET** `/api/ping/`
|
||||||
|
|
||||||
|
When valid returns message with user id:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"response": "pong",
|
||||||
|
"user": 1
|
||||||
|
}
|
||||||
|
```
|
27
mkdocs/docs/api/channel.md
Normal file
27
mkdocs/docs/api/channel.md
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
# Channel
|
||||||
|
|
||||||
|
## Channel List
|
||||||
|
`/api/channel/`
|
||||||
|
|
||||||
|
Parameter:
|
||||||
|
|
||||||
|
- filter: subscribed
|
||||||
|
|
||||||
|
Subscribe to a list of channels:
|
||||||
|
**POST** `/api/channel/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": [
|
||||||
|
{"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Channel Item
|
||||||
|
**GET** `/api/channel/<channel_id>/`
|
||||||
|
**DELETE** `/api/channel/\<channel_id>/`
|
||||||
|
|
||||||
|
- Will delete channel with all it's videos
|
||||||
|
|
||||||
|
## Channel Videos
|
||||||
|
**GET** /api/channel/\<channel_id>/video/
|
51
mkdocs/docs/api/download.md
Normal file
51
mkdocs/docs/api/download.md
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
# Download
|
||||||
|
|
||||||
|
## Download Queue List
|
||||||
|
**GET** `/api/download/`
|
||||||
|
|
||||||
|
Parameter:
|
||||||
|
|
||||||
|
- filter: pending, ignore
|
||||||
|
- channel: channel-id
|
||||||
|
|
||||||
|
Add list of videos to download queue:
|
||||||
|
**POST** `/api/download/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"data": [
|
||||||
|
{"youtube_id": "NYj3DnI81AQ", "status": "pending"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Delete download queue items by filter:
|
||||||
|
**DELETE** `/api/download/?filter=ignore`
|
||||||
|
**DELETE** `/api/download/?filter=pending`
|
||||||
|
|
||||||
|
## Download Queue Item
|
||||||
|
**GET** `/api/download/<video_id>/`
|
||||||
|
**POST** `/api/download/<video_id>/`
|
||||||
|
|
||||||
|
Ignore video in download queue:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ignore"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Add to queue previously ignored video:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "pending"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Download existing video now:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "priority"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**DELETE** `/api/download/<video_id>/`
|
||||||
|
Forget or delete from download queue
|
43
mkdocs/docs/api/introduction.md
Normal file
43
mkdocs/docs/api/introduction.md
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
# Introduction
|
||||||
|
|
||||||
|
This page has a generic overview with how the Tube Archivist API functions. This is the place to start.
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
These API endpoints *have* changed in the past and *will* change again while building out additional integrations and functionality. For the time being, don't expect backwards compatibility for third party integrations using these endpoints.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
- All changes to the API are marked with a `[API]` keyword for easy searching, for example search for [commits](https://github.com/tubearchivist/tubearchivist/search?o=desc&q=%5Bapi%5D&s=committer-date&type=commits). You'll find the same in the [release notes](https://github.com/tubearchivist/tubearchivist/releases).
|
||||||
|
- Check the commit history and release notes to see if a documented feature is already in your release. The documentation might be ahead of the regular release schedule.
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
API token will get automatically created, accessible on the settings page. Token needs to be passed as an authorization header with every request. Additionally session based authentication is enabled too: When you are logged into your TubeArchivist instance, you'll have access to the api in the browser for testing.
|
||||||
|
|
||||||
|
Curl example:
|
||||||
|
```shell
|
||||||
|
curl -v /api/video/<video-id>/ \
|
||||||
|
-H "Authorization: Token xxxxxxxxxx"
|
||||||
|
```
|
||||||
|
|
||||||
|
Python requests example:
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
|
||||||
|
url = "/api/video/<video-id>/"
|
||||||
|
headers = {"Authorization": "Token xxxxxxxxxx"}
|
||||||
|
response = requests.get(url, headers=headers)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pagination
|
||||||
|
The list views return a paginate object with the following keys:
|
||||||
|
|
||||||
|
- page_size: *int* current page size set in config
|
||||||
|
- page_from: *int* first result idx
|
||||||
|
- prev_pages: *array of ints* of previous pages, if available
|
||||||
|
- current_page: *int* current page from query
|
||||||
|
- max_hits: *bool* if max of 10k results is reached
|
||||||
|
- params: *str* additional url encoded query parameters
|
||||||
|
- last_page: *int* of last page link
|
||||||
|
- next_pages: *array of ints* of next pages
|
||||||
|
- total_hits: *int* total results
|
||||||
|
|
||||||
|
Pass page number as a query parameter: `page=2`. Defaults to *0*, `page=1` is redundant and falls back to *0*. If a page query doesn't return any results, you'll get `HTTP 404 Not Found`.
|
10
mkdocs/docs/api/playlist.md
Normal file
10
mkdocs/docs/api/playlist.md
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
# Playlist
|
||||||
|
|
||||||
|
## Playlist List
|
||||||
|
**GET** `/api/playlist/`
|
||||||
|
|
||||||
|
## Playlist Item
|
||||||
|
**GET** `/api/playlist/<playlist_id>/`
|
||||||
|
|
||||||
|
## Playlist Videos
|
||||||
|
**GET** `/api/playlist/<playlist_id>/video/`
|
43
mkdocs/docs/api/snapshot.md
Normal file
43
mkdocs/docs/api/snapshot.md
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
# Snapshot
|
||||||
|
|
||||||
|
## Snapshot List
|
||||||
|
**GET** `/api/snapshot/`
|
||||||
|
Return snapshot config and a list of available snapshots.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"next_exec": epoch,
|
||||||
|
"next_exec_str": "date_str",
|
||||||
|
"expire_after": "30d",
|
||||||
|
"snapshots": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**POST** `/api/snapshot/`
|
||||||
|
Create new snapshot now, will return immediately, task will run async in the background, returns snapshot name:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"snapshot_name": "ta_daily_<random-id>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Snapshot Item View
|
||||||
|
**GET** `/api/snapshot/<snapshot-id>/`
|
||||||
|
Return metadata of a single snapshot
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "ta_daily_<random-id>",
|
||||||
|
"state": "SUCCESS",
|
||||||
|
"es_version": "0.0.0",
|
||||||
|
"start_date": "date_str",
|
||||||
|
"end_date": "date_str",
|
||||||
|
"end_stamp": epoch,
|
||||||
|
"duration_s": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**POST** `/api/snapshot/<snapshot-id>/`
|
||||||
|
Restore this snapshot
|
||||||
|
|
||||||
|
**DELETE** `/api/snapshot/<snapshot-id>/`
|
||||||
|
Remove this snapshot from index
|
24
mkdocs/docs/api/task.md
Normal file
24
mkdocs/docs/api/task.md
Normal file
@ -0,0 +1,24 @@
|
|||||||
|
# Task Name and Task ID
|
||||||
|
|
||||||
|
## Task Name List View
|
||||||
|
**GET** `/api/task-name/`
|
||||||
|
Return all task results.
|
||||||
|
|
||||||
|
## Task Name Item View
|
||||||
|
**GET** `/api/task-name/<task-name>/`
|
||||||
|
Return all ask results by task name
|
||||||
|
|
||||||
|
**POST** `/api/task-name/<task-name>/`
|
||||||
|
Start a new task by task name, only tasks without arguments can be started like that, see `home.tasks.BaseTask.TASK_CONFIG` for more info.
|
||||||
|
|
||||||
|
## Task ID view
|
||||||
|
**GET** `/api/task-id/<task-id>/`
|
||||||
|
Return task status by task ID
|
||||||
|
|
||||||
|
**POST** `/api/task-id/<task-id>/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"command": "stop|kill"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Send command to a task, valid commands: `stop` and `kill`. Not all tasks implement these commands `home.tasks.BaseTask.TASK_CONFIG` for details.
|
78
mkdocs/docs/api/video.md
Normal file
78
mkdocs/docs/api/video.md
Normal file
@ -0,0 +1,78 @@
|
|||||||
|
# Video
|
||||||
|
|
||||||
|
|
||||||
|
## Video List
|
||||||
|
**GET** `/api/video/`
|
||||||
|
|
||||||
|
## Video Item
|
||||||
|
**GET** `/api/video/<video_id>/`
|
||||||
|
**DELETE** `/api/video/<video_id>/`
|
||||||
|
|
||||||
|
## Video Comment
|
||||||
|
**GET** `/api/video/<video_id>/comment/`
|
||||||
|
|
||||||
|
## Video Similar
|
||||||
|
**GET** `/api/video/<video_id>/similar/`
|
||||||
|
|
||||||
|
## Video Progress
|
||||||
|
`/api/video/<video_id>/progress/`
|
||||||
|
|
||||||
|
Progress is stored for each user.
|
||||||
|
|
||||||
|
Get last player position of a video:
|
||||||
|
**GET** `/api/video/<video_id>/progress/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"youtube_id": "<video_id>",
|
||||||
|
"user_id": 1,
|
||||||
|
"position": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Update player position of video:
|
||||||
|
**POST** `/api/video/<video_id>/progress/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"position": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Delete player position:
|
||||||
|
**DELETE** `/api/video/<video_id>/progress/`
|
||||||
|
|
||||||
|
|
||||||
|
## Sponsor Block
|
||||||
|
`/api/video/<video_id>/sponsor/`
|
||||||
|
|
||||||
|
Integrate with sponsorblock
|
||||||
|
|
||||||
|
Get list of segments:
|
||||||
|
**GET** `/api/video/<video_id>/sponsor/`
|
||||||
|
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
Writing to Sponsorblock enpoints is only simulated for now and won't forward any requests. This needs some clever UI/UX implementation first.
|
||||||
|
|
||||||
|
Vote on existing segment:
|
||||||
|
**POST** `/api/video/<video_id>/sponsor/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"vote": {
|
||||||
|
"uuid": "<uuid>",
|
||||||
|
"yourVote": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
yourVote needs to be *int*: 0 for downvote, 1 for upvote, 20 to undo vote
|
||||||
|
|
||||||
|
Create new segment
|
||||||
|
**POST** `/api/video/<video_id>/sponsor/`
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"segment": {
|
||||||
|
"startTime": 5,
|
||||||
|
"endTime": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Timestamps either *int* or *float*, end time can't be before start time.
|
@ -10,12 +10,17 @@
|
|||||||
font-family: 'Sen-Regular';
|
font-family: 'Sen-Regular';
|
||||||
}
|
}
|
||||||
|
|
||||||
* {
|
p, a, span, h3 {
|
||||||
font-family: Sen-Regular;
|
font-family: Sen-Regular;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
code span {
|
||||||
|
font-family: monospace;
|
||||||
|
}
|
||||||
|
|
||||||
h1,
|
h1,
|
||||||
h2 {
|
h2,
|
||||||
|
strong {
|
||||||
font-family: Sen-Bold;
|
font-family: Sen-Bold;
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -50,6 +55,11 @@ footer {
|
|||||||
--md-admonition-bg-color: var(--highlight-bg);
|
--md-admonition-bg-color: var(--highlight-bg);
|
||||||
--md-admonition-fg-color: var(--main-font);
|
--md-admonition-fg-color: var(--main-font);
|
||||||
--md-footer-bg-color: var(--highlight-bg);
|
--md-footer-bg-color: var(--highlight-bg);
|
||||||
|
--md-code-hl-punctuation-color: var(--main-font);
|
||||||
|
--md-code-hl-name-color: var(--accent-font-light);
|
||||||
|
--md-code-hl-string-color: var(--accent-font-dark);
|
||||||
|
--md-code-hl-number-color: var(--highlight-error-light);
|
||||||
|
--md-code-hl-operator-color: var(--highlight-error);
|
||||||
}
|
}
|
||||||
|
|
||||||
:root {
|
:root {
|
||||||
|
@ -21,6 +21,15 @@ nav:
|
|||||||
- Configuration:
|
- Configuration:
|
||||||
- 'LDAP Authentication': 'configuration/ldap.md'
|
- 'LDAP Authentication': 'configuration/ldap.md'
|
||||||
- 'Cast Support': 'configuration/cast.md'
|
- 'Cast Support': 'configuration/cast.md'
|
||||||
|
- API:
|
||||||
|
- 'Introduction': 'api/introduction.md'
|
||||||
|
- 'Video': 'api/video.md'
|
||||||
|
- 'Channel': 'api/channel.md'
|
||||||
|
- 'Playlist': 'api/playlist.md'
|
||||||
|
- 'Download': 'api/download.md'
|
||||||
|
- 'Snapshot': 'api/snapshot.md'
|
||||||
|
- 'Task': 'api/task.md'
|
||||||
|
- 'Additional': 'api/additional.md'
|
||||||
- Links:
|
- Links:
|
||||||
- 'Main site': https://www.tubearchivist.com
|
- 'Main site': https://www.tubearchivist.com
|
||||||
- 'Join us on Discord!': https://www.tubearchivist.com/discord
|
- 'Join us on Discord!': https://www.tubearchivist.com/discord
|
||||||
|
Loading…
Reference in New Issue
Block a user