tubearchivist/tubearchivist/api

TubeArchivist API

Documentation of available API endpoints.

Note:

• This is very early stages and will change!
• Check the commit history to see if a documented feature is already in your release

Table of contents

• Authentication
• Pagination

Video

• Video List
• Video Single
• Video Comments
• Video Similar
• Video Single Progress
• Video Single Sponsorblock WIP

Channel

• Channel List
• Channel Single
• Channel Video List

Playlist

• Playlist List
• Playlist Single
• Playlist Videos List

Download queue

• Download Queue List
• Download Queue Single

Snapshot management

• Snapshot List
• Snapshot Single

Additional

• Login
• Task WIP
• Refresh
• Cookie
• Search
• Ping

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

/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/

Subscribe to a list of channels

POST /api/channel/

{
    "data": [
        {"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true}
    ]
}

Channel Item View

/api/channel/<channel_id>/

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"
}

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/
POST /api/refresh/
Parameter:

• extract_videos: to refresh all videos for channels/playlists, default False

Manually start a refresh task: post list of videos, channels, playlists

{
    "videos": ["video1", "video2", "video3"],
    "channels": ["channel1", "channel2", "channel3"],
    "playlists": ["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.

Ping View

Validate your connection with the API
GET /api/ping

When valid returns message with user id:

{
    "response": "pong",
    "user": 1
}