From ce7b59a8be67273af797d9ca297712d4e6e18980 Mon Sep 17 00:00:00 2001 From: arabcoders Date: Wed, 21 Jan 2026 18:54:56 +0300 Subject: [PATCH] refactor: update API documentation --- API.md | 475 +++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 325 insertions(+), 150 deletions(-) diff --git a/API.md b/API.md index 1d408c44..6085f82f 100644 --- a/API.md +++ b/API.md @@ -57,15 +57,28 @@ This document describes the available endpoints and their usage. All endpoints r - [GET /api/download/{filename}](#get-apidownloadfilename) - [GET /api/random/background](#get-apirandombackground) - [GET /api/presets](#get-apipresets) - - [GET /api/dl\_fields](#get-apidl_fields) - - [PUT /api/dl\_fields](#put-apidl_fields) + - [GET /api/dl\_fields/](#get-apidl_fields) + - [POST /api/dl\_fields/](#post-apidl_fields) + - [GET /api/dl\_fields/{id}](#get-apidl_fieldsid) + - [PATCH /api/dl\_fields/{id}](#patch-apidl_fieldsid) + - [PUT /api/dl\_fields/{id}](#put-apidl_fieldsid) + - [DELETE /api/dl\_fields/{id}](#delete-apidl_fieldsid) - [PUT /api/presets](#put-apipresets) - - [GET /api/conditions](#get-apiconditions) - - [PUT /api/conditions](#put-apiconditions) + - [GET /api/conditions/](#get-apiconditions) + - [POST /api/conditions/](#post-apiconditions) + - [GET /api/conditions/{id}](#get-apiconditionsid) + - [PATCH /api/conditions/{id}](#patch-apiconditionsid) + - [PUT /api/conditions/{id}](#put-apiconditionsid) + - [DELETE /api/conditions/{id}](#delete-apiconditionsid) - [POST /api/conditions/test](#post-apiconditionstest) - [GET /api/logs](#get-apilogs) - - [GET /api/notifications](#get-apinotifications) - - [PUT /api/notifications](#put-apinotifications) + - [GET /api/notifications/](#get-apinotifications) + - [GET /api/notifications/events/](#get-apinotificationsevents) + - [POST /api/notifications/](#post-apinotifications) + - [GET /api/notifications/{id}](#get-apinotificationsid) + - [PATCH /api/notifications/{id}](#patch-apinotificationsid) + - [PUT /api/notifications/{id}](#put-apinotificationsid) + - [DELETE /api/notifications/{id}](#delete-apinotificationsid) - [POST /api/yt-dlp/archive\_id/](#post-apiyt-dlparchive_id) - [POST /api/notifications/test](#post-apinotificationstest) - [GET /api/yt-dlp/options](#get-apiyt-dlpoptions) @@ -85,7 +98,9 @@ This document describes the available endpoints and their usage. All endpoints r - [`connect` (Built-in)](#connect-built-in) - [`disconnect` (Built-in)](#disconnect-built-in) - [`configuration` (Server → Client)](#configuration-server--client) + - [`config_update` (Server → Client)](#config_update-server--client) - [`connected` (Server → Client)](#connected-server--client) + - [`active_queue` (Server → Client)](#active_queue-server--client) - [Logging Events](#logging-events) - [`log_info` (Server → Client)](#log_info-server--client) - [`log_success` (Server → Client)](#log_success-server--client) @@ -99,6 +114,9 @@ This document describes the available endpoints and their usage. All endpoints r - [`item_cancelled` (Server → Client)](#item_cancelled-server--client) - [`item_deleted` (Server → Client)](#item_deleted-server--client) - [`item_moved` (Server → Client)](#item_moved-server--client) + - [`item_status` (Server → Client)](#item_status-server--client) + - [`paused` (Server → Client)](#paused-server--client) + - [`resumed` (Server → Client)](#resumed-server--client) - [Terminal/CLI Events](#terminalcli-events) - [`cli_post` (Client → Server)](#cli_post-client--server) - [`cli_output` (Server → Client)](#cli_output-server--client) @@ -160,6 +178,9 @@ If you fail to provide valid credentials, a `401 Unauthorized` response is retur } ``` +**Notes**: +- IDs are integer values generated by the database. + --- ### POST /api/yt-dlp/convert @@ -1424,43 +1445,105 @@ Binary image data with appropriate headers --- -### GET /api/dl_fields -**Purpose**: Retrieve the list of configured download fields. +### GET /api/dl_fields/ +**Purpose**: Retrieve download fields with pagination. -**Query Parameters (optional)**: -- `filter`: Comma-separated list of field names to include in each object. +**Query Parameters**: +- `page` (optional): Page number (1-indexed). Default: `1`. +- `per_page` (optional): Items per page. Default: `config.default_pagination`. **Response**: ```json -[ - { "id": "", "name": "...", ... }, - ... -] +{ + "items": [ + { "id": 1, "name": "...", "description": "...", "field": "...", "kind": "text", "order": 0, "value": "", "extras": {} } + ], + "pagination": { + "page": 1, + "per_page": 50, + "total": 1, + "total_pages": 1, + "has_next": false, + "has_prev": false + } +} ``` --- -### PUT /api/dl_fields -**Purpose**: Save the list of download fields. Replaces existing entries. +### POST /api/dl_fields/ +**Purpose**: Create a new download field. -**Body**: Array of objects. Required per-item fields: `name`. `id` is auto-generated if missing or invalid. +**Body**: ```json -[ - { "name": "...", "id": "", ... }, - { "name": "..." } -] +{ + "name": "Title", + "description": "...", + "field": "title", + "kind": "text", + "order": 0, + "value": "", + "icon": "fa-solid fa-tag", + "extras": {} +} ``` **Response**: ```json -[ - { "id": "", "name": "...", ... }, - ... -] +{ "id": 1, "name": "Title", "description": "...", "field": "title", "kind": "text", "order": 0, "value": "", "icon": "fa-solid fa-tag", "extras": {} } ``` -or an error: + +--- + +### GET /api/dl_fields/{id} +**Purpose**: Retrieve a single download field by ID. + +**Response**: ```json -{ "error": "text" } +{ "id": 1, "name": "Title", "description": "...", "field": "title", "kind": "text", "order": 0, "value": "", "icon": "fa-solid fa-tag", "extras": {} } +``` + +--- + +### PATCH /api/dl_fields/{id} +**Purpose**: Partially update a download field. + +**Body**: +```json +{ "description": "Updated description", "order": 1 } +``` + +**Response**: Updated download field object. + +--- + +### PUT /api/dl_fields/{id} +**Purpose**: Replace a download field. + +**Body**: +```json +{ + "name": "Title", + "description": "...", + "field": "title", + "kind": "text", + "order": 0, + "value": "", + "icon": "fa-solid fa-tag", + "extras": {} +} +``` + +**Response**: Updated download field object. + +--- + +### DELETE /api/dl_fields/{id} +**Purpose**: Delete a download field by ID. + +**Response**: +```json +{ "id": 1, "name": "Title", "description": "...", "field": "title", "kind": "text", "order": 0, "value": "", "icon": "fa-solid fa-tag", "extras": {} } ``` --- @@ -1498,73 +1581,98 @@ or an error: --- -### GET /api/conditions -**Purpose**: Retrieve all configured download conditions. +### GET /api/conditions/ +**Purpose**: Retrieve download conditions with pagination. + +**Query Parameters**: +- `page` (optional): Page number (1-indexed). Default: `1`. +- `per_page` (optional): Items per page. Default: `config.default_pagination`. **Response**: ```json -[ - { - "id": "", - "name": "condition_name", - "filter": "...", - "cli": "...", - "extras": {}, - "enabled": true, - "priority": 0, - "description": "What this condition does" - }, - ... -] +{ + "items": [ + { + "id": 1, + "name": "condition_name", + "filter": "...", + "cli": "...", + "extras": {}, + "enabled": true, + "priority": 0, + "description": "What this condition does" + } + ], + "pagination": { + "page": 1, + "per_page": 50, + "total": 1, + "total_pages": 1, + "has_next": false, + "has_prev": false + } +} ``` **Notes**: - Conditions are evaluated in priority order (higher priority first). - Priority defaults to 0 when not specified. +- IDs are integer values generated by the database. --- -### PUT /api/conditions -**Purpose**: Save/update download conditions. +### POST /api/conditions/ +**Purpose**: Create a new download condition. -**Body**: An array of condition objects: +**Body**: ```json -[ - { - "id": "", // optional, will be generated if not provided - "name": "Use proxy for region locked content", - "filter": "availability = 'needs_auth' & channel_id = 'channel_id'", - "cli": "--proxy http://myproxy.com:8080", - "extras": {}, - "enabled": true, - "priority": 10, - "description": "Apply proxy for region-locked videos" - }, - ... -] +{ + "name": "Use proxy for region locked content", + "filter": "availability = 'needs_auth' & channel_id = 'channel_id'", + "cli": "--proxy http://myproxy.com:8080", + "extras": {}, + "enabled": true, + "priority": 10, + "description": "Apply proxy for region-locked videos" +} ``` -**Response**: +**Response**: Created condition object. + +--- + +### GET /api/conditions/{id} +**Purpose**: Retrieve a condition by ID. + +**Response**: Condition object. + +--- + +### PATCH /api/conditions/{id} +**Purpose**: Partially update a condition. + +**Body**: ```json -[ - { - "id": "", - "name": "Use proxy for region locked content", - "filter": "availability = 'needs_auth' & channel_id = 'channel_id'", - "cli": "--proxy http://myproxy.com:8080", - "extras": {}, - "enabled": true, - "priority": 10, - "description": "Apply proxy for region-locked videos" - }, - ... -] +{ "enabled": false, "priority": 5 } ``` -**Notes**: -- Disabled conditions (`enabled: false`) will be stored but ignored during matching. -- All conditions are enabled by default when the `enabled` field is not provided. -- Priority determines check order. Higher priority conditions are checked first. +**Response**: Updated condition object. + +--- + +### PUT /api/conditions/{id} +**Purpose**: Replace a condition. + +**Body**: Full condition object. + +**Response**: Updated condition object. + +--- + +### DELETE /api/conditions/{id} +**Purpose**: Delete a condition by ID. + +**Response**: Deleted condition object. --- @@ -1618,85 +1726,118 @@ or an error: --- -### GET /api/notifications -**Purpose**: Retrieve the configured notification targets and which event types are allowed. +### GET /api/notifications/ +**Purpose**: Retrieve notification targets with pagination. -**Response** (example): -```json -{ - "notifications": [ - { - "id": "uuid", - "name":"...", - "on": ["completed", "error",...], // empty array means all events. - "request":{ - "type":"json|form", - "method":"POST|PUT", - "url":"https://...", - "headers":[ - {"key":"...", "value":"..."}, - ... - ] - } - } - } - ], - "allowedTypes": ["added", "completed", "error", "cancelled", "cleared", "log_info", "log_success", "log_warning", "log_error", "test"] -} -``` - ---- - -### PUT /api/notifications -**Purpose**: Overwrites the entire list of notification targets. - -**Body**: An array of notification target configurations. Example: -```json -[ - { - "id": "uuid", - "name": "My Webhook", - "on": ["completed", "error"], - "request": { - "type": "json", - "method": "POST", - "url": "https://...", - "headers": [ - { "key": "Authorization", "value": "Bearer ..." } - ] - } - }, - { - "name": "Another Webhook", - "on": ["completed"], - "request": { - "type": "form", - "method": "PUT", - "url": "https://...", - "headers": [] - } - } - ... -] -``` -- If `id` is not provided or is not a valid UUIDv4, it will be auto-generated. -- If the payload list is empty, all existing notifications are removed. +**Query Parameters**: +- `page` (optional): Page number (1-indexed). Default: `1`. +- `per_page` (optional): Items per page. Default: `config.default_pagination`. **Response**: ```json { - "notifications": [ + "items": [ { - "id": "uuid", - "name": "...", - "on": ["completed", "error", ...], - "request": { ... } - }, - ... + "id": 1, + "name": "My Webhook", + "on": ["item_completed"], + "presets": ["default"], + "enabled": true, + "request": { + "type": "json", + "method": "POST", + "url": "https://example.com/webhook", + "data_key": "data", + "headers": [{ "key": "Authorization", "value": "Bearer ..." }] + } + } ], - "allowedTypes": ["added", "completed", "error", "cancelled", "cleared", "log_info", "log_success", ...] + "pagination": { + "page": 1, + "per_page": 50, + "total": 1, + "total_pages": 1, + "has_next": false, + "has_prev": false + } } ``` + +**Notes**: +- Empty `on` and `presets` arrays mean all events/presets. +- `request.method` supports `POST` and `PUT`. +- `request.type` supports `json` and `form`. +- IDs are integer values generated by the database. + +--- + +### GET /api/notifications/events/ +**Purpose**: Retrieve allowed notification event names. + +**Response**: +```json +{ "events": ["item_added", "item_completed", "log_error", "test"] } +``` + +--- + +### POST /api/notifications/ +**Purpose**: Create a notification target. + +**Body**: +```json +{ + "name": "My Webhook", + "on": ["item_completed"], + "presets": ["default"], + "enabled": true, + "request": { + "type": "json", + "method": "POST", + "url": "https://example.com/webhook", + "data_key": "data", + "headers": [{ "key": "Authorization", "value": "Bearer ..." }] + } +} +``` + +**Response**: Created notification target. + +--- + +### GET /api/notifications/{id} +**Purpose**: Retrieve a notification target by ID. + +**Response**: Notification target object. + +--- + +### PATCH /api/notifications/{id} +**Purpose**: Partially update a notification target. + +**Body**: +```json +{ "enabled": false } +``` + +**Response**: Updated notification target. + +--- + +### PUT /api/notifications/{id} +**Purpose**: Replace a notification target. + +**Body**: Full notification target object. + +**Response**: Updated notification target. + +--- + +### DELETE /api/notifications/{id} +**Purpose**: Delete a notification target. + +**Response**: Deleted notification target. + --- ### POST /api/yt-dlp/archive_id/ @@ -1740,10 +1881,7 @@ or an error: **Response**: ```json -{ - "type": "test", - "message": "This is a test notification." -} +{} ``` --- @@ -1955,12 +2093,36 @@ Sends the current application configuration. - `dl_fields`: Available download fields - `paused`: Queue pause status (boolean) +##### `config_update` (Server → Client) +Emitted when configuration-backed resources change (presets, dl fields, conditions, notifications). + +**Data Fields**: +- `feature`: One of `presets`, `dl_fields`, `conditions`, `notifications` +- `action`: `create`, `update`, `delete`, `replace` +- `data`: Updated payload (object or list of objects) + +**Example**: +```json +{ + "feature": "notifications", + "action": "update", + "data": { "id": 1, "name": "My Webhook", "enabled": true } +} +``` + ##### `connected` (Server → Client) When a client connects, this events sends the folder and current queue. **Data Fields**: - `queue`: Current download queue (array of items) - `folders`: Directory structure for downloads +- `history_count`: Count of completed download items + +##### `active_queue` (Server → Client) +Provides the current active queue snapshot. + +**Data Fields**: +- `queue`: Current download queue (array of items) #### Logging Events @@ -2064,6 +2226,19 @@ socket.on('item_moved', (stream: string) => { }); ``` +#### `item_status` (Server → Client) +Emitted after add-url attempts via WebSocket to report enqueue status. + +**Data Fields**: +- `status`: Status payload from queue add operation +- `preset`: Preset name used for the request + +#### `paused` (Server → Client) +Emitted when the download queue is paused. + +#### `resumed` (Server → Client) +Emitted when the download queue is resumed. + ### Terminal/CLI Events The terminal feature requires `YTP_CONSOLE_ENABLED=true`.