9.1 KiB
TubeArchivist API
Documentation of available API endpoints.
Note:
- This has changed in the past and will change again while building out additional integrations and functionality.
- All changes to the API are marked with a
[API]
keyword for easy searching, for example search for commits. You'll find the same in the release notes. - Check the commit history and release notes to see if a documented feature is already in your release.
Table of contents
Video
- Video List
- Video Single
- Video Comments
- Video Similar
- Video Single Progress
- Video Single Sponsorblock WIP
Channel
Playlist
Download queue
Snapshot management
Additional
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:
curl -v /api/video/<video-id>/ \
-H "Authorization: Token xxxxxxxxxx"
Python requests example:
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
.
Video List View
/api/video/
Video Item View
GET: /api/video/<video_id>/
DELETE: /api/video/<video_id>/
Video Comment View
/api/video/<video_id>/comment/
Video Similar View
/api/video/<video_id>/similar/
Video Progress View
/api/video/<video_id>/progress/
Progress is stored for each user.
Get last player position of a video
GET /api/video/<video_id>/progress/
{
"youtube_id": "<video_id>",
"user_id": 1,
"position": 100
}
Post player position of video
POST /api/video/<video_id>/progress/
{
"position": 100
}
Delete player position of video
DELETE /api/video/<video_id>/progress/
Sponsor Block View
/api/video/<video_id>/sponsor/
Integrate with sponsorblock
Get list of segments
GET /api/video/<video_id>/sponsor/
Vote on existing segment
This only simulates the request
POST /api/video/<video_id>/sponsor/
{
"vote": {
"uuid": "<uuid>",
"yourVote": 1
}
}
yourVote needs to be int: 0 for downvote, 1 for upvote, 20 to undo vote
Create new segment
This only simulates the request
POST /api/video/<video_id>/sponsor/
{
"segment": {
"startTime": 5,
"endTime": 10
}
}
Timestamps either int or float, end time can't be before start time.
Channel List View
/api/channel/
Parameter:
- filter: subscribed
Subscribe to a list of channels
POST /api/channel/
{
"data": [
{"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true}
]
}
Channel Item View
GET: /api/channel/<channel_id>/
DELETE: /api/channel/<channel_id>/
- Will delete channel with all it's videos
Channel Videos View
/api/channel/<channel_id>/video/
Playlist List View
/api/playlist/
Playlist Item View
/api/playlist/<playlist_id>/
Playlist Videos View
/api/playlist/<playlist_id>/video/
Download Queue List View
GET /api/download/
Parameter:
- filter: pending, ignore
- channel: channel-id
Add list of videos to download queue
POST /api/download/
{
"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 View
GET /api/download/<video_id>/
POST /api/download/<video_id>/
Ignore video in download queue:
{
"status": "ignore"
}
Add to queue previously ignored video:
{
"status": "pending"
}
Download existing video now:
{
"status": "priority"
}
DELETE /api/download/<video_id>/
Forget or delete from download queue
Snapshot List View
GET /api/snapshot/
Return snapshot config and a list of available snapshots.
{
"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, will return snapshot name:
{
"snapshot_name": "ta_daily_<random-id>
}
Snapshot Item View
GET /api/snapshot/<snapshot-id>/
Return metadata of a single snapshot
{
"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
}
GET /api/snapshot/<snapshot-id>/
Restore this snapshot
DELETE /api/snapshot/<snapshot-id>/
Remove this snapshot from index
Login View
Return token and user ID for username and password:
POST /api/login/
{
"username": "tubearchivist",
"password": "verysecret"
}
after successful login returns
{
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"user_id": 1
}
Task View
GET /api/task/ POST /api/task/
Check if there is an ongoing task: GET /api/task/
Returns:
{
"rescan": false,
"downloading": false
}
Start a background task
POST /api/task/
{
"run": "task_name"
}
List of valid task names:
- download_pending: Start the download queue
- rescan_pending: Rescan your subscriptions
Refresh View
GET /api/refresh/
parameters:
- type: one of video, channel, playlist, optional
- id: item id, optional
without specifying type: return total for all queued items:
{
"total_queued": 2,
"type": "all",
"state": "running"
}
specify type: return total items queue of this type:
{
"total_queued": 2,
"type": "video",
"state": "running"
}
specify type and id to get state of item in queue:
{
"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.
{
"video": ["video1", "video2", "video3"],
"channel": ["channel1", "channel2", "channel3"],
"playlist": ["playlist1", "playlist2"]
}
Cookie View
Check your youtube cookie settings, status turns to true
if cookie has been validated.
GET /api/cookie/
{
"cookie_enabled": true,
"status": true,
"validated": <timestamp>,
"validated_str": "timestamp"
}
POST /api/cookie/
Send empty post request to validate cookie.
{
"cookie_validated": true
}
PUT /api/cookie/
Send put request containing the cookie as a string:
{
"cookie": "your-cookie-as-string"
}
Imports and validates cookie, returns on success:
{
"cookie_import": "done",
"cookie_validated": true
}
Or returns status code 400 on failure:
{
"cookie_import": "fail",
"cookie_validated": false
}
Search View
GET /api/search/?query=<query>
Returns search results from your query.
Watched View
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.
{
"id": "xxxxxxx",
"is_watched": True
}
Ping View
Validate your connection with the API
GET /api/ping/
When valid returns message with user id:
{
"response": "pong",
"user": 1
}