diff --git a/README.md b/README.md index 6c0329d..23f7df3 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ ![home screenshot](assets/tube-archivist-screenshot-home.png?raw=true "Tube Archivist Home") ## Table of contents: -* [Docs](https://docs.tubearchivist.com/) with [FAQ](https://docs.tubearchivist.com/faq/), [API endpoints](https://github.com/tubearchivist/tubearchivist/tree/master/tubearchivist/api) +* [Docs](https://docs.tubearchivist.com/) with [FAQ](https://docs.tubearchivist.com/faq/), and API documentation * [Core functionality](#core-functionality) * [Resources](#resources) * [Installing](#installing) diff --git a/tubearchivist/api/README.md b/tubearchivist/api/README.md index b87980f..2815b6e 100644 --- a/tubearchivist/api/README.md +++ b/tubearchivist/api/README.md @@ -1,442 +1,3 @@ # 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](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. - -## Table of contents -- [Authentication](#authentication) -- [Pagination](#pagination) - -**Video** -- [Video List](#video-list-view) -- [Video Single](#video-item-view) -- [Video Comments](#video-comment-view) -- [Video Similar](#video-similar-view) -- [Video Single Progress](#video-progress-view) -- [Video Single Sponsorblock](#sponsor-block-view) WIP - -**Channel** -- [Channel List](#channel-list-view) -- [Channel Single](#channel-item-view) -- [Channel Video List](#channel-videos-view) - -**Playlist** -- [Playlist List](#playlist-list-view) -- [Playlist Single](#playlist-item-view) -- [Playlist Videos List](#playlist-videos-view) - -**Download queue** -- [Download Queue List](#download-queue-list-view) -- [Download Queue Single](#download-queue-item-view) - -**Snapshot management** -- [Snapshot List](#snapshot-list-view) -- [Snapshot Single](#snapshot-item-view) - -**Task management** -- [Task Name List](#task-name-list-view) -- [Task Name Single](#task-name-item-view) -- [Task ID](#task-id-view) - -**Additional** -- [Login](#login-view) -- [Refresh](#refresh-view) -- [Cookie](#cookie-view) -- [Search](#search-view) -- [Watched](#watched-view) -- [Ping](#ping-view) - -## 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// \ - -H "Authorization: Token xxxxxxxxxx" -``` - -Python requests example: -```python -import requests - -url = "/api/video//" -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/\/ -DELETE: /api/video/\/ - -## Video Comment View -/api/video/\/comment/ - -## Video Similar View -/api/video/\/similar/ - -## Video Progress View -/api/video/\/progress/ - -Progress is stored for each user. - -### Get last player position of a video -GET /api/video/\/progress/ -```json -{ - "youtube_id": "", - "user_id": 1, - "position": 100 -} -``` - -### Post player position of video -POST /api/video/\/progress/ -```json -{ - "position": 100 -} -``` - -### Delete player position of video -DELETE /api/video/\/progress/ - - -## Sponsor Block View -/api/video/\/sponsor/ - -Integrate with sponsorblock - -### Get list of segments -GET /api/video/\/sponsor/ - - -### Vote on existing segment -**This only simulates the request** -POST /api/video/\/sponsor/ -```json -{ - "vote": { - "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/\/sponsor/ -```json -{ - "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/ -```json -{ - "data": [ - {"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true} - ] -} -``` - -## Channel Item View -GET: /api/channel/\/ -DELETE: /api/channel/\/ -- Will delete channel with all it's videos - -## Channel Videos View -/api/channel/\/video/ - -## Playlist List View -/api/playlist/ - -## Playlist Item View -/api/playlist/\/ - -## Playlist Videos View -/api/playlist/\/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/ -```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 View -GET /api/download/\/ -POST /api/download/\/ - -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/\/ -Forget or delete from download queue - -## Snapshot List View -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, will return snapshot name: -```json -{ - "snapshot_name": "ta_daily_" -} -``` - -## Snapshot Item View -GET /api/snapshot/\/ -Return metadata of a single snapshot -```json -{ - "id": "ta_daily_", - "state": "SUCCESS", - "es_version": "0.0.0", - "start_date": "date_str", - "end_date": "date_str", - "end_stamp": epoch, - "duration_s": 0 -} -``` - -GET /api/snapshot/\/ -Restore this snapshot - -DELETE /api/snapshot/\/ -Remove this snapshot from index - -## Task Name List View -GET /api/task-name/ -Return all task results - -## Task Name Item View -GET /api/task-name/\/ -Return all ask results by task name - -POST /api/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/\/ -Return task status by task ID - -POST /api/task-id/\/ -```json -{ - "command": "stop|kill" -} -``` -Send command to a task, valid commands: `stop` and `kill`. - -## Login View -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 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: -```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 View -Check your youtube cookie settings, *status* turns to `true` if cookie has been validated. -GET /api/cookie/ -```json -{ - "cookie_enabled": true, - "status": true, - "validated": , - "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 View -GET /api/search/?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. - -```json -{ - "id": "xxxxxxx", - "is_watched": True -} -``` - - -## Ping View -Validate your connection with the API -GET /api/ping/ - -When valid returns message with user id: -```json -{ - "response": "pong", - "user": 1 -} -``` +All API documentation has moved to [docs.tubearchivist.com](https://docs.tubearchivist.com/).