refactor: update API documentation
This commit is contained in:
arabcoders
parent
48feca72d3
commit
ce7b59a8be
1 changed files with 325 additions and 150 deletions
475
API.md
475
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": "<uuid>", "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": "<uuid>", ... },
|
||||
{ "name": "..." }
|
||||
]
|
||||
{
|
||||
"name": "Title",
|
||||
"description": "...",
|
||||
"field": "title",
|
||||
"kind": "text",
|
||||
"order": 0,
|
||||
"value": "",
|
||||
"icon": "fa-solid fa-tag",
|
||||
"extras": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
[
|
||||
{ "id": "<uuid>", "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": "<uuid>",
|
||||
"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": "<uuid>", // 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": "<uuid>",
|
||||
"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`.
|
||||
|
|
|
|||
Loading…
Reference in a new issue