diff --git a/mkdocs/docs/api/additional.md b/mkdocs/docs/api/additional.md deleted file mode 100644 index 5031a21..0000000 --- a/mkdocs/docs/api/additional.md +++ /dev/null @@ -1,169 +0,0 @@ -# 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=` - -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 and authentication with the API -**GET** `/api/ping/` - -When valid returns message with user id and TubeArchivist version: -```json -{ - "response": "pong", - "user": 1, - "version": "v0.4.7" -} -``` - -## Notification List -Get all current notifications. -**GET** `/api/notification/` - -Parameter: - -- filter: "download" | "settings" | "channel" - -```json -[ - { - "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". - diff --git a/mkdocs/docs/api/backup.md b/mkdocs/docs/api/backup.md deleted file mode 100644 index 69b5a78..0000000 --- a/mkdocs/docs/api/backup.md +++ /dev/null @@ -1,38 +0,0 @@ -# Backup - -Index [snapshots](snapshot.md) are a more reliable way than zip file backup as described here. - -## Backup List -**GET** `/api/backup/` -Return a list of available backup files with metadata. - -**POST** `/api/backup/` -Start a backup task now. This will return immediately, triggering an async task in the background. The message will contain a `task_id` key that can be monitored separately. - -Example return message: -```json -{ - "message": "backup task started", - "task_id": "f22f6981-35bb-4b7c-bd91-80a57d960b52" -} -``` - -## Backup Item -**GET** `/api/backup//` -Return metadata of a single backup file. - -**POST** `/api/backup//` -Start a backup restore task now. This will return immediately, triggering an async task in the background. The message will contain a `task_id` key that can be monitored separately. - -Example return message: - -```json -{ - "message": "backup restore task started", - "filename": "ta_backup-20231101-auto.zip", - "task_id": "4fc2afdf-4045-4288-a33c-e3267a9efb5a" -} -``` - -**DELETE** `/api/backup//` -Delete backup file from the filesystem. diff --git a/mkdocs/docs/api/channel.md b/mkdocs/docs/api/channel.md deleted file mode 100644 index d42bc7f..0000000 --- a/mkdocs/docs/api/channel.md +++ /dev/null @@ -1,37 +0,0 @@ -# Channel - -## Channel List -`/api/channel/` - -Parameter: - -- filter: subscribed - -Subscribe/Unsubscribe to a list of channels: -**POST** `/api/channel/` -```json -{ - "data": [ - {"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true} - ] -} -``` - -## Channel Search - -⚠️ **Experimental** - -**GET** `/api/channel/?q=` - -Parameter: - -- q: Query to search channel - -## Channel Item -**GET** `/api/channel//` -**DELETE** `/api/channel/\/` - -- Will delete channel with all it's videos - -## Channel Videos -**GET** /api/channel/\/video/ diff --git a/mkdocs/docs/api/config.md b/mkdocs/docs/api/config.md deleted file mode 100644 index 3667314..0000000 --- a/mkdocs/docs/api/config.md +++ /dev/null @@ -1,18 +0,0 @@ -# Config - -## User Config -Per user modified config values. - -**GET** `/api/config/user/` -Return all config values *modified* by user. - -**POST** `/api/config/user/` -Modify one or more config values. For possible key, values, see `UserConfig` class. - -Example post data: -```json -{ - "colors": "dark", - "page_size": 20 -} -``` diff --git a/mkdocs/docs/api/docs.md b/mkdocs/docs/api/docs.md new file mode 100644 index 0000000..54377d0 --- /dev/null +++ b/mkdocs/docs/api/docs.md @@ -0,0 +1,6 @@ +# API Documentation + +!!! note + Complete API documentation is available on your **Tube Archivist** instance at `/api/docs/`. + +TODO: Figure out how to host/serve/display a copy of the documentation here from a generated `api-schema.json` file. diff --git a/mkdocs/docs/api/download.md b/mkdocs/docs/api/download.md deleted file mode 100644 index 790a9b4..0000000 --- a/mkdocs/docs/api/download.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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"} - ] -} -``` -Parameter: - -- autostart: true - -Delete download queue items by filter: -**DELETE** `/api/download/?filter=ignore` -**DELETE** `/api/download/?filter=pending` - -???+ "Curl Example" - ```bash - # add video to download queue - curl -XPOST -v /api/download/ \ - -H "Authorization: Token xxxxxxxxxx" \ - -H 'Content-Type: application/json' \ - -d '{"data":[{"youtube_id": "", "status":"pending"}]}' - ``` - -## Download Queue Item -**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 diff --git a/mkdocs/docs/api/playlist.md b/mkdocs/docs/api/playlist.md deleted file mode 100644 index 8c9ae77..0000000 --- a/mkdocs/docs/api/playlist.md +++ /dev/null @@ -1,41 +0,0 @@ -# Playlist - -## Playlist List -**GET** `/api/playlist/` - -Parameter: - -- playlist_type: filter py playlist type. - -Subscribe/Unsubscribe to a list of playlists: -**POST** `/api/playlist/` -```json -{ - "data": [ - {"playlist_id": "PL96C35uN7xGLLeET0dOWaKHkAlPsrkcha", "playlist_subscribed": true} - ] -} -``` - -## Playlist Item -**GET** `/api/playlist//` - -**POST**: Update Playlist item, only valid for custom playlists - -This expects an object with a key `video_id` to indicate the video in the playlist to modify and a key `action` to represent what to do. The action can be: - -- `create`: Create a video entry in the playlist -- `remove`: Remove a video from the playlist -- `up`: Move a video up -- `down`: Move a video down -- `top`: Move a video to the top -- `bottom`: Move a video to the bottom - -Delete playlist, metadata only: -**DELETE** `/api/playlist//` -Delete playlist, also delete all videos in playlist: -**DELETE** `/api/playlist//?delete-videos=true` - - -## Playlist Videos -**GET** `/api/playlist//video/` diff --git a/mkdocs/docs/api/snapshot.md b/mkdocs/docs/api/snapshot.md deleted file mode 100644 index e46bfd8..0000000 --- a/mkdocs/docs/api/snapshot.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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_" -} -``` - -## 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 -} -``` - -**POST** `/api/snapshot//` -Restore this snapshot - -**DELETE** `/api/snapshot//` -Remove this snapshot from index diff --git a/mkdocs/docs/api/stats.md b/mkdocs/docs/api/stats.md deleted file mode 100644 index 46ecd69..0000000 --- a/mkdocs/docs/api/stats.md +++ /dev/null @@ -1,50 +0,0 @@ -# Statistics API endpoints - -⚠️ **Experimental** -All stats endpoints are considered experimental. - -## Video - -**GET** `/api/stats/video/` - -Get stats for your downloaded videos. - -## Channel - -**GET** `/api/stats/channel/` - -Get stats for your channels. - -## Playlist - -**GET** `/api/stats/playlist/` - -Get stats for your playlists. - -## Download - -**GET** `/api/stats/download/` - -Get stats for your download queue. - -## Watch Progress - -**GET** `/api/stats/watch/` - -Get statistics over your watch progress. - -## Download History - -**GET** `/api/stats/downloadhist/` - -Get statistics for last days download history. - -## Biggest Channels - -**GET** `/api/stats/biggestchannels/` - -Get a list of biggest channels, specify *order* parameter. - -Parameter: - -- order: doc_count (default), duration, media_size diff --git a/mkdocs/docs/api/task.md b/mkdocs/docs/api/task.md deleted file mode 100644 index 4e2f324..0000000 --- a/mkdocs/docs/api/task.md +++ /dev/null @@ -1,47 +0,0 @@ -# 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//` -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`. Not all tasks implement these commands `home.tasks.BaseTask.TASK_CONFIG` for details. - -## Schedule View -**DEL** `/api/schedule/` - -Delete schedule by task name - -Parameter: - -- `task_name`: See task config module - -## Schedule Notification View -**GET** `/api/schedule/notification/` - -Get a list of all task schedule notifications - -**DEL** `/api/schedule/notification/` - -Delete notification of a task. - -Parameter: - -- `task_name`: See task config module -- `url`: Url to be deleted diff --git a/mkdocs/docs/api/video.md b/mkdocs/docs/api/video.md deleted file mode 100644 index 0d5e73f..0000000 --- a/mkdocs/docs/api/video.md +++ /dev/null @@ -1,78 +0,0 @@ -# Video - - -## Video List -**GET** `/api/video/` - -## Video Item -**GET** `/api/video//` -**DELETE** `/api/video//` - -## Video Comment -**GET** `/api/video//comment/` - -## Video Similar -**GET** `/api/video//similar/` - -## Video Progress -`/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 -} -``` - -Update player position of video: -**POST** `/api/video//progress/` -```json -{ - "position": 100 -} -``` - -Delete player position: -**DELETE** `/api/video//progress/` - - -## Sponsor Block -`/api/video//sponsor/` - -Integrate with sponsorblock - -Get list of segments: -**GET** `/api/video//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//sponsor/` -```json -{ - "vote": { - "uuid": "", - "yourVote": 1 - } -} -``` -yourVote needs to be *int*: 0 for downvote, 1 for upvote, 20 to undo vote - -Create new segment -**POST** `/api/video//sponsor/` -```json -{ - "segment": { - "startTime": 5, - "endTime": 10 - } -} -``` -Timestamps either *int* or *float*, end time can't be before start time. diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 9d0dfd2..e0150de 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -34,16 +34,7 @@ nav: - 'Stylesheets': 'configuration/stylesheets.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' - - 'Backup': 'api/backup.md' - - 'Task': 'api/task.md' - - 'Stats': 'api/stats.md' - - 'Config': 'api/config.md' - - 'Additional': 'api/additional.md' + - 'Docs': 'api/docs.md' - Links: - 'Main site': https://www.tubearchivist.com - 'Join us on Discord!': https://www.tubearchivist.com/discord