Skip to content

Additional API endpoints#

Login#

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
}

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:

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

Check your youtube cookie settings, status turns to true if cookie has been validated.
GET /api/cookie/

{
    "cookie_enabled": true,
    "status": true,
    "validated": 1680953715,
    "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
}

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.

{
    "id": "xxxxxxx",
    "is_watched": true
}

Ping#

Validate your connection and authentication with the API
GET /api/ping/

When valid returns message with user id and TubeArchivist version:

{
    "response": "pong",
    "user": 1,
    "version": "v0.4.7"
}

Notification List#

Get all current notifications. GET /api/notification/

Parameter:

  • filter: "download" | "settings" | "channel"
[
  {
    "title": "Rescan your Subscriptions",
    "group": "download:scan",
    "api-start": true,
    "api-stop": true,
    "level": "info",
    "id": "1111111-1111-1111-1111-1111111",
    "command": false,
    "messages": ["Task completed successfully"],
    "progress": 0.000001
  }
]

"command" can be false || "STOP" || "KILL".