{ "swagger": "2.0", "info": { "description": "MrRSS is a modern, cross-platform desktop RSS reader with auto-translation, smart feed discovery, and AI-powered summarization.", "title": "MrRSS API", "contact": { "name": "API Support", "url": "https://github.com/WCY-dt/MrRSS", "email": "mail@ch3nyang.top" }, "license": { "name": "GPL-3.0", "url": "https://www.gnu.org/licenses/gpl-3.0.en.html" }, "version": "1.3.25" }, "host": "localhost:1234", "basePath": "/api", "paths": { "/ai/profiles": { "get": { "description": "Get all AI configuration profiles (without API keys for security)", "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "List AI profiles", "responses": { "200": { "description": "List of AI profiles", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.AIProfile" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Create a new AI configuration profile", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Create AI profile", "parameters": [ { "description": "Profile data", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.ProfileRequest" } } ], "responses": { "201": { "description": "Created profile", "schema": { "$ref": "#/definitions/models.AIProfile" } }, "400": { "description": "Invalid request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/profiles/test-all": { "post": { "description": "Test all AI profiles' connections and configurations", "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Test all AI profiles", "responses": { "200": { "description": "Test results for all profiles", "schema": { "type": "array", "items": { "$ref": "#/definitions/handlers.ProfileTestResult" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/profiles/test-config": { "post": { "description": "Test an AI configuration without creating/saving a profile", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Test AI configuration without saving", "parameters": [ { "description": "Configuration to test", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.ProfileTestRequest" } } ], "responses": { "200": { "description": "Test result", "schema": { "$ref": "#/definitions/handlers.ProfileTestResult" } }, "400": { "description": "Invalid request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/profiles/{id}": { "get": { "description": "Get a specific AI configuration profile by ID (includes API key)", "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Get AI profile", "parameters": [ { "type": "integer", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "AI profile", "schema": { "$ref": "#/definitions/models.AIProfile" } }, "400": { "description": "Invalid profile ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Profile not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "description": "Update an existing AI configuration profile", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Update AI profile", "parameters": [ { "type": "integer", "description": "Profile ID", "name": "id", "in": "path", "required": true }, { "description": "Profile data", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.ProfileRequest" } } ], "responses": { "200": { "description": "Updated profile", "schema": { "$ref": "#/definitions/models.AIProfile" } }, "400": { "description": "Invalid request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Profile not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Delete an AI configuration profile", "tags": [ "ai-profiles" ], "summary": "Delete AI profile", "parameters": [ { "type": "integer", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid profile ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/profiles/{id}/default": { "post": { "description": "Set an AI profile as the default", "tags": [ "ai-profiles" ], "summary": "Set default AI profile", "parameters": [ { "type": "integer", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Invalid profile ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/profiles/{id}/test": { "post": { "description": "Test an AI profile's connection and configuration", "produces": [ "application/json" ], "tags": [ "ai-profiles" ], "summary": "Test AI profile", "parameters": [ { "type": "integer", "description": "Profile ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "Test result", "schema": { "$ref": "#/definitions/handlers.ProfileTestResult" } }, "400": { "description": "Invalid profile ID", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Profile not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/search": { "post": { "description": "Use AI to expand keywords and search articles with relevance ranking", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai" ], "summary": "AI-powered article search", "parameters": [ { "description": "Search query", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/handlers.AISearchRequest" } } ], "responses": { "200": { "description": "Search results", "schema": { "$ref": "#/definitions/handlers.AISearchResponse" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/test": { "post": { "description": "Test AI service configuration (endpoint, API key, model availability)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai" ], "summary": "Test AI configuration", "responses": { "200": { "description": "Test result (config_valid, connection_success, model_available, response_time_ms, test_time, error_message)", "schema": { "$ref": "#/definitions/handlers.TestResult" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/ai/test/info": { "get": { "description": "Get the last AI configuration test result (returns empty/default result as tests are not stored persistently)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "ai" ], "summary": "Get AI test info", "responses": { "200": { "description": "Empty test result (config_valid, connection_success, model_available, response_time_ms, test_time)", "schema": { "$ref": "#/definitions/handlers.TestResult" } } } } }, "/ai/usage": { "get": { "description": "Get current AI usage (tokens used, limit, and whether limit is reached)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Get AI usage statistics", "responses": { "200": { "description": "AI usage stats (usage, limit, limit_reached)", "schema": { "type": "object", "additionalProperties": true } } } } }, "/ai/usage/reset": { "post": { "description": "Reset the AI usage token counter to zero", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Reset AI usage counter", "responses": { "200": { "description": "Success status", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/api/rsshub/add": { "post": { "description": "Adds a new RSSHub feed subscription with the specified route, category, and title", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Add RSSHub feed", "parameters": [ { "description": "RSSHub feed details", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "category": { "type": "string" }, "route": { "type": "string" }, "title": { "type": "string" } } } } ], "responses": { "200": { "description": "Feed added successfully", "schema": { "type": "object", "properties": { "feed_id": { "type": "integer", "format": "int64" }, "success": { "type": "boolean" } } } }, "400": { "description": "Invalid request", "schema": { "type": "object", "properties": { "error": { "type": "string" } } } }, "500": { "description": "Server error", "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "/api/rsshub/test-connection": { "post": { "description": "Tests the connection to RSSHub endpoint with the provided API key by validating a common route", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rsshub" ], "summary": "Test RSSHub connection", "parameters": [ { "description": "RSSHub connection details", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "endpoint": { "type": "string" } } } } ], "responses": { "200": { "description": "Connection failed", "schema": { "type": "object", "properties": { "error": { "type": "string" }, "success": { "type": "boolean" } } } } } } }, "/api/rsshub/transform-url": { "post": { "description": "Transforms a rsshub:// protocol URL to full RSSHub URL with endpoint and API key", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rsshub" ], "summary": "Transform RSSHub URL", "parameters": [ { "description": "RSSHub URL to transform (rsshub:// protocol)", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "url": { "type": "string" } } } } ], "responses": { "200": { "description": "Transformed URL", "schema": { "type": "object", "properties": { "url": { "type": "string" } } } }, "400": { "description": "Invalid request or URL", "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "/api/rsshub/validate-route": { "post": { "description": "Validates if a specific RSSHub route exists and is accessible using the configured endpoint and API key", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rsshub" ], "summary": "Validate RSSHub route", "parameters": [ { "description": "Route to validate", "name": "request", "in": "body", "required": true, "schema": { "type": "object", "properties": { "route": { "type": "string" } } } } ], "responses": { "200": { "description": "Route is invalid", "schema": { "type": "object", "properties": { "error": { "type": "string" }, "valid": { "type": "boolean" } } } } } } }, "/api/statistics": { "get": { "produces": [ "application/json" ], "tags": [ "statistics" ], "summary": "Get statistics", "parameters": [ { "enum": [ "week", "month", "year", "all", "custom" ], "type": "string", "default": "week", "description": "Time period", "name": "period", "in": "query" }, { "type": "integer", "default": 0, "description": "Period offset for navigation (e.g., -1 for previous, 1 for next)", "name": "offset", "in": "query" }, { "type": "string", "description": "Start date (YYYY-MM-DD format, required for period=custom)", "name": "start_date", "in": "query" }, { "type": "string", "description": "End date (YYYY-MM-DD format, required for period=custom)", "name": "end_date", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/statistics.StatSummary" } } } }, "delete": { "description": "Deletes all statistics data from the database", "produces": [ "application/json" ], "tags": [ "statistics" ], "summary": "Reset all statistics", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": true } } } } }, "/api/statistics/all-time": { "get": { "produces": [ "application/json" ], "tags": [ "statistics" ], "summary": "Get all-time statistics", "responses": { "200": { "description": "OK", "schema": { "type": "object", "additionalProperties": { "type": "integer" } } } } } }, "/api/statistics/available-months": { "get": { "produces": [ "application/json" ], "tags": [ "statistics" ], "summary": "Get available months", "responses": { "200": { "description": "OK", "schema": { "type": "array", "items": { "type": "string" } } } } } }, "/articles": { "get": { "description": "Retrieve articles with optional filtering by feed, category, status, and pagination", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get articles with filtering", "parameters": [ { "enum": [ "all", "unread", "favorite", "read_later" ], "type": "string", "description": "Filter: 'all', 'unread', 'favorite', 'read_later'", "name": "filter", "in": "query" }, { "type": "integer", "format": "int64", "description": "Filter by feed ID", "name": "feed_id", "in": "query" }, { "type": "string", "description": "Filter by category name", "name": "category", "in": "query" }, { "minimum": 1, "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "maximum": 500, "minimum": 1, "type": "integer", "description": "Items per page (default: 50, max: 500)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "List of articles", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Article" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/cleanup": { "post": { "description": "Delete all articles and article contents (keeps feeds and settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Cleanup all articles", "responses": { "200": { "description": "Cleanup statistics (deleted, articles, contents, type)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/cleanup-content": { "post": { "description": "Clear all cached article content (articles remain, only content cache is cleared)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Cleanup article content cache", "responses": { "200": { "description": "Cleanup result (success, entries_cleaned)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/clear-read-later": { "post": { "description": "Remove all articles from the read-later list", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Clear read-later list", "responses": { "200": { "description": "Read-later list cleared successfully", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/content": { "get": { "description": "Fetch the full HTML content of an article (uses cache if available)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get article content", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Article content (content, feed_url)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (invalid article ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/content-cache-info": { "get": { "description": "Get statistics about the article content cache", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get article content cache info", "responses": { "200": { "description": "Cache info (cached_articles count)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/export/notion": { "post": { "description": "Export an article to Notion as a page (requires notion_enabled, notion_api_key, and notion_page_id settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Export article to Notion", "parameters": [ { "description": "Article export request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/article.ExportToNotionRequest" } } ], "responses": { "200": { "description": "Export result (success, page_url, message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (Notion not configured or invalid article ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Article not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/export/obsidian": { "post": { "description": "Export an article to Obsidian vault as a Markdown file (requires obsidian_enabled and obsidian_vault_path settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Export article to Obsidian", "parameters": [ { "description": "Article export request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/article.ExportToObsidianRequest" } } ], "responses": { "200": { "description": "Export result (success, file_path, message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (Obsidian not configured or invalid article ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Article not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/export/zotero": { "post": { "description": "Export an article to Zotero as a webpage item (requires zotero_enabled, zotero_api_key, and zotero_user_id settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Export article to Zotero", "parameters": [ { "description": "Article export request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/article.ExportToZoteroRequest" } } ], "responses": { "200": { "description": "Export result (success, item_key, message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (Zotero not configured or invalid article ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Article not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/extract-images": { "get": { "description": "Extract all image URLs from article content (including relative URLs resolved to absolute)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Extract all images from article", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "List of image URLs (images, feed_url)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid article ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/fetch-full": { "post": { "description": "Fetch the full article content from the original URL using readability extraction (requires full_text_fetch_enabled setting)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Fetch full article content", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Full article content (content, feed_url)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (invalid ID or missing URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Full-text fetching disabled", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/filter": { "post": { "description": "Retrieve articles with advanced filtering conditions", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get filtered articles", "parameters": [ { "description": "Filter criteria", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/article.FilterRequest" } } ], "responses": { "200": { "description": "Filtered articles", "schema": { "$ref": "#/definitions/article.FilterResponse" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/filter-counts": { "get": { "description": "Get per-feed counts for different filter types (unread, favorites, read_later, images)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get filter-specific feed counts", "responses": { "200": { "description": "Filter counts for all filter types", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/image-gallery": { "get": { "description": "Retrieve articles from image-mode feeds (visual/rss-gallery feeds) with pagination", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get image gallery articles", "parameters": [ { "type": "integer", "format": "int64", "description": "Filter by feed ID", "name": "feed_id", "in": "query" }, { "type": "string", "description": "Filter by category name", "name": "category", "in": "query" }, { "type": "boolean", "description": "Filter for only unread articles", "name": "only_unread", "in": "query" }, { "minimum": 1, "type": "integer", "description": "Page number (default: 1)", "name": "page", "in": "query" }, { "minimum": 1, "type": "integer", "description": "Items per page (default: 50)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "List of image gallery articles", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Article" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/mark-all-read": { "post": { "description": "Mark all articles as read globally, by feed, or by category", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Mark all articles as read", "parameters": [ { "type": "integer", "format": "int64", "description": "Mark all as read for specific feed ID", "name": "feed_id", "in": "query" }, { "type": "string", "description": "Mark all as read for specific category", "name": "category", "in": "query" } ], "responses": { "200": { "description": "Articles marked as read successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request (invalid feed_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/mark-read-sync": { "post": { "description": "Mark a specific article as read or unread and immediately sync to FreshRSS if configured", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Mark article as read/unread with immediate FreshRSS sync", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true }, { "enum": [ "true", "1", "false", "0" ], "type": "string", "description": "Read status: 'true', '1', 'false', or '0'", "name": "read", "in": "query", "required": true } ], "responses": { "200": { "description": "Article marked and sync triggered successfully", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/mark-relative": { "post": { "description": "Marks articles as read based on their published time relative to a reference article (above = newer, below = older)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Mark articles relative to reference article", "parameters": [ { "type": "integer", "format": "int64", "description": "Reference article ID", "name": "id", "in": "query", "required": true }, { "enum": [ "above", "below" ], "type": "string", "description": "Direction: 'above' for newer articles, 'below' for older articles", "name": "direction", "in": "query", "required": true }, { "type": "integer", "format": "int64", "description": "Optional: only mark articles from this feed", "name": "feed_id", "in": "query" }, { "type": "string", "description": "Optional: only mark articles from this category", "name": "category", "in": "query" } ], "responses": { "200": { "description": "Number of articles marked as read", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Article not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/refresh": { "post": { "description": "Trigger a background refresh of all feeds", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Refresh all feeds", "responses": { "200": { "description": "Refresh started successfully", "schema": { "type": "string" } } } } }, "/articles/toggle-favorite-sync": { "post": { "description": "Toggle the favorite/starred status of an article and immediately sync to FreshRSS if configured", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Toggle article favorite status with immediate FreshRSS sync", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Favorite toggled and sync triggered successfully", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/toggle-hide": { "post": { "description": "Toggle the hidden status of an article (hidden articles are filtered out by default)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Toggle article hidden status", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Success status", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/toggle-read-later": { "post": { "description": "Toggle the read-later status of an article (add to/remove from reading list)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Toggle article read-later status", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Success status", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/articles/unread-counts": { "get": { "description": "Get total unread count and per-feed unread counts", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get unread counts", "responses": { "200": { "description": "Unread counts (total + feed_counts map)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/browser/open": { "get": { "description": "Open a URL in the user's default web browser", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "browser" ], "summary": "Open URL in browser", "parameters": [ { "type": "string", "description": "URL to open (for GET requests)", "name": "url", "in": "query" }, { "description": "Open URL request (url) (for POST requests)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Success status (status) or redirect URL (redirect)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (invalid URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Returns redirect response for client-side URL opening", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "browser" ], "summary": "Open URL in browser (server mode)", "parameters": [ { "description": "Open URL request (url)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Redirect URL (redirect)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (invalid URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat": { "post": { "description": "Send messages to AI for discussing article content (requires ai_chat_enabled setting)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "AI chat with article", "parameters": [ { "description": "Chat request (messages, article info)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/chat.ChatRequest" } } ], "responses": { "200": { "description": "AI response (response, html)", "schema": { "$ref": "#/definitions/chat.ChatResponse" } }, "400": { "description": "Bad request (missing messages)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "AI chat is disabled or limit reached", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat/message": { "delete": { "description": "Delete a specific chat message", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Delete chat message", "parameters": [ { "type": "integer", "format": "int64", "description": "Message ID", "name": "message_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Deletion status (status: 'deleted')", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (missing or invalid message_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat/messages": { "get": { "description": "Get all messages in a specific chat session", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "List chat messages", "parameters": [ { "type": "integer", "format": "int64", "description": "Session ID", "name": "session_id", "in": "query", "required": true } ], "responses": { "200": { "description": "List of chat messages (with HTML for assistant messages)", "schema": { "type": "array", "items": { "type": "object" } } }, "400": { "description": "Bad request (missing or invalid session_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat/session": { "get": { "description": "Get details of a specific chat session", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Get chat session", "parameters": [ { "type": "integer", "format": "int64", "description": "Session ID", "name": "session_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Chat session details", "schema": { "$ref": "#/definitions/database.ChatSession" } }, "400": { "description": "Bad request (missing or invalid session_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Session not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "put": { "description": "Update the title of a chat session", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Update chat session", "parameters": [ { "type": "integer", "format": "int64", "description": "Session ID", "name": "session_id", "in": "query", "required": true }, { "description": "Update request (title)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/chat.UpdateSessionRequest" } } ], "responses": { "200": { "description": "Updated chat session", "schema": { "$ref": "#/definitions/database.ChatSession" } }, "400": { "description": "Bad request (missing session_id or title)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Delete a specific chat session and all its messages", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Delete chat session", "parameters": [ { "type": "integer", "format": "int64", "description": "Session ID", "name": "session_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Session deleted successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request (missing or invalid session_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat/sessions": { "get": { "description": "Get all chat sessions for a specific article", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "List chat sessions", "parameters": [ { "type": "integer", "format": "int64", "description": "Article ID", "name": "article_id", "in": "query", "required": true } ], "responses": { "200": { "description": "List of chat sessions", "schema": { "type": "array", "items": { "$ref": "#/definitions/database.ChatSession" } } }, "400": { "description": "Bad request (missing or invalid article_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Create a new chat session for an article", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Create chat session", "parameters": [ { "description": "Session creation request (article_id, title)", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/chat.CreateSessionRequest" } } ], "responses": { "200": { "description": "Created chat session", "schema": { "$ref": "#/definitions/database.ChatSession" } }, "400": { "description": "Bad request (missing article_id)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/chat/sessions/all": { "delete": { "description": "Delete all chat sessions and their messages", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "chat" ], "summary": "Delete all chat sessions", "responses": { "200": { "description": "Deletion result (status, count)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/custom-css": { "get": { "description": "Get the content of the uploaded custom CSS file", "consumes": [ "application/json" ], "produces": [ "text/css" ], "tags": [ "custom-css" ], "summary": "Get custom CSS", "responses": { "200": { "description": "CSS file content", "schema": { "type": "string" } }, "404": { "description": "No custom CSS file configured", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Delete the custom CSS file and clear the setting", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-css" ], "summary": "Delete custom CSS", "responses": { "200": { "description": "Delete success (status, message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/custom-css/dialog": { "post": { "description": "File dialog not available in server mode. Use /api/custom-css/upload endpoint instead", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "custom-css" ], "summary": "Upload CSS dialog (not available)", "responses": { "501": { "description": "Not implemented error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/custom-css/upload": { "post": { "description": "Upload a custom CSS file to style article content (max 1MB, .css files only)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "custom-css" ], "summary": "Upload custom CSS file", "parameters": [ { "type": "file", "description": "CSS file to upload", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "Upload success (status, message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (invalid file or size)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/all": { "post": { "description": "Discover new blogs by analyzing friend links from all feeds that haven't been discovered yet", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Discover feeds from all subscriptions", "responses": { "200": { "description": "Discovery results (discovered_from, feeds_found, feeds)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/batch/clear": { "post": { "description": "Clear the current batch discovery state and results", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Clear batch discovery state", "responses": { "200": { "description": "Clear status (status)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/batch/progress": { "get": { "description": "Get the current progress and status of the batch discovery operation", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Get batch discovery progress", "responses": { "200": { "description": "Discovery state (is_running, is_complete, progress, feeds, error)", "schema": { "$ref": "#/definitions/core.DiscoveryState" } } } } }, "/discovery/batch/start": { "post": { "description": "Start an asynchronous blog discovery process for all undiscovered feeds", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Start batch discovery", "responses": { "202": { "description": "Discovery started (status, total)", "schema": { "type": "object", "additionalProperties": true } }, "409": { "description": "Batch discovery already in progress", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/blogs": { "post": { "description": "Discover new blogs by analyzing friend links from a specific feed's RSS content", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Discover blogs from feed", "parameters": [ { "description": "Discovery request (feed_id)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "List of discovered blogs", "schema": { "type": "array", "items": { "$ref": "#/definitions/discovery.DiscoveredBlog" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Feed not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/single/clear": { "post": { "description": "Clear the current single feed discovery state and results", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Clear single discovery state", "responses": { "200": { "description": "Clear status (status)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/discovery/single/progress": { "get": { "description": "Get the current progress and status of the single feed discovery operation", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Get single discovery progress", "responses": { "200": { "description": "Discovery state (is_running, is_complete, progress, feeds, error)", "schema": { "$ref": "#/definitions/core.DiscoveryState" } } } } }, "/discovery/single/start": { "post": { "description": "Start an asynchronous blog discovery process for a specific feed", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Start single feed discovery", "parameters": [ { "description": "Discovery request (feed_id)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "202": { "description": "Discovery started (status)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Feed not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Discovery already in progress", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/email/imap/test": { "post": { "description": "Test IMAP server connection with provided credentials", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "email" ], "summary": "Test IMAP connection", "parameters": [ { "description": "IMAP connection test (email_imap_server, email_imap_port, email_username, email_password, email_folder)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Connection successful (message)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (missing required fields)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "401": { "description": "Authentication failed", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds": { "get": { "description": "Retrieve all RSS feed subscriptions (passwords are cleared)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Get all feeds", "responses": { "200": { "description": "List of feeds", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Feed" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds/add": { "post": { "description": "Add a new RSS/Atom/Email/Script/XPath feed subscription", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Add a new feed", "parameters": [ { "description": "Feed details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Feed added successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Feed URL already exists", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds/delete": { "post": { "description": "Delete a feed subscription by ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Delete a feed", "parameters": [ { "type": "integer", "format": "int64", "description": "Feed ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Feed deleted successfully", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds/refresh": { "post": { "description": "Trigger a refresh for a specific feed (runs in background with progress tracking)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Refresh a single feed", "parameters": [ { "type": "integer", "format": "int64", "description": "Feed ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Feed refresh started successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request (invalid feed ID)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "404": { "description": "Feed not found", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds/reorder": { "post": { "description": "Change the position and optionally the category of a feed", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Reorder a feed", "parameters": [ { "description": "Reorder details (feed_id, category, position)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Reorder status", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/feeds/update": { "post": { "description": "Update properties of an existing feed subscription", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "feeds" ], "summary": "Update a feed", "parameters": [ { "description": "Feed update details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Feed updated successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "409": { "description": "Feed URL already exists", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/freshrss/status": { "get": { "description": "Get the current synchronization status with FreshRSS", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "freshrss" ], "summary": "Get FreshRSS sync status", "responses": { "200": { "description": "Sync status (pending_changes, failed_items, last_sync_time)", "schema": { "type": "object", "additionalProperties": true } } } } }, "/freshrss/sync": { "post": { "description": "Perform bidirectional synchronization with FreshRSS server (pull and push changes)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "freshrss" ], "summary": "Sync with FreshRSS", "responses": { "200": { "description": "Sync started status (status, message)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (FreshRSS disabled or incomplete settings)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/freshrss/sync-feed": { "post": { "description": "Synchronize articles for a specific FreshRSS feed/stream", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "freshrss" ], "summary": "Sync single FreshRSS feed", "parameters": [ { "type": "string", "description": "FreshRSS stream ID", "name": "stream_id", "in": "query", "required": true } ], "responses": { "200": { "description": "Sync started status (status, message)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (FreshRSS disabled or stream_id missing)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/media/cache/cleanup": { "post": { "description": "Clean up the media cache by age and size", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "media" ], "summary": "Cleanup media cache", "parameters": [ { "type": "boolean", "default": false, "description": "Clean all files (ignores age/size settings)", "name": "all", "in": "query" } ], "responses": { "200": { "description": "Cleanup result (success, files_cleaned)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/media/cache/info": { "get": { "description": "Get media cache statistics (size in MB)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "media" ], "summary": "Get media cache info", "responses": { "200": { "description": "Cache info (cache_size_mb)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/media/proxy": { "get": { "description": "Proxy and cache media files (images, videos, audio) from external URLs", "consumes": [ "application/json" ], "produces": [ "application/octet-stream" ], "tags": [ "media" ], "summary": "Proxy media file", "parameters": [ { "type": "string", "description": "Media URL to proxy", "name": "url", "in": "query", "required": true }, { "type": "string", "description": "Referer URL for hotlink protection", "name": "referer", "in": "query" }, { "type": "boolean", "description": "Force caching even if globally disabled", "name": "force_cache", "in": "query" } ], "responses": { "200": { "description": "Media file", "schema": { "type": "file" } }, "400": { "description": "Bad request (missing or invalid URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "403": { "description": "Media proxy is disabled", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/media/proxy-webpage": { "get": { "description": "Proxy webpage HTML content and rewrite resource URLs to bypass CORS restrictions", "consumes": [ "application/json" ], "produces": [ "text/html" ], "tags": [ "media" ], "summary": "Proxy webpage content", "parameters": [ { "type": "string", "description": "Webpage URL to proxy", "name": "url", "in": "query", "required": true } ], "responses": { "200": { "description": "Webpage HTML content", "schema": { "type": "string" } }, "400": { "description": "Bad request (missing or invalid URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/network/detect": { "post": { "description": "Detect network speed and latency, then optimize max concurrent refreshes setting", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "network" ], "summary": "Detect network speed", "responses": { "200": { "description": "Network detection result (speed_level, bandwidth_mbps, latency_ms, max_concurrency)", "schema": { "$ref": "#/definitions/network.DetectionResult" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/network/info": { "get": { "description": "Get the last network detection information (speed, bandwidth, latency, concurrent refreshes)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "network" ], "summary": "Get network info", "responses": { "200": { "description": "Network info (speed_level, bandwidth_mbps, latency_ms, max_concurrent_refreshes, last_network_test)", "schema": { "type": "object", "additionalProperties": true } } } } }, "/opml/export": { "get": { "description": "Export all feeds as an OPML file (server mode - direct download)", "consumes": [ "application/json" ], "produces": [ "text/xml" ], "tags": [ "opml" ], "summary": "Export OPML file", "responses": { "200": { "description": "OPML XML file", "schema": { "type": "string" } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/opml/export/dialog": { "post": { "description": "File dialog operations are not available in server mode. Use /api/opml/export with direct download instead", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "opml" ], "summary": "Export dialog (not available in server mode)", "responses": { "501": { "description": "Not implemented error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/opml/import": { "post": { "description": "Import feeds from an OPML file (server mode - requires file upload)", "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "opml" ], "summary": "Import OPML file", "parameters": [ { "type": "file", "description": "OPML file", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "Import result (success, imported, total)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid file or format)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/opml/import/dialog": { "post": { "description": "File dialog operations are not available in server mode. Use /api/opml/import with file upload instead", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "opml" ], "summary": "Import dialog (not available in server mode)", "responses": { "501": { "description": "Not implemented error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/progress": { "get": { "description": "Get the current feed fetching progress with statistics", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get fetch progress", "responses": { "200": { "description": "Progress information", "schema": { "type": "object", "additionalProperties": true } } } } }, "/progress/task-details": { "get": { "description": "Get detailed information about tasks in pool and queue", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "articles" ], "summary": "Get task details", "responses": { "200": { "description": "Task details", "schema": { "$ref": "#/definitions/article.TaskDetailsResponse" } } } } }, "/rules/apply": { "post": { "description": "Apply a rule with conditions and actions to matching articles (mark as read, favorite, etc.)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "rules" ], "summary": "Apply rule to articles", "parameters": [ { "description": "Rule definition (conditions and actions)", "name": "rule", "in": "body", "required": true, "schema": { "$ref": "#/definitions/rules.Rule" } } ], "responses": { "200": { "description": "Application result (success, affected count)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid rule or no actions)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/saved-filters": { "get": { "description": "Retrieve all saved article filters\nCreate a new article filter with custom conditions", "consumes": [ "application/json", "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "filters", "filters" ], "summary": "Create a new saved filter", "parameters": [ { "description": "Filter details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "List of saved filters", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.SavedFilter" } } }, "201": { "description": "Created filter", "schema": { "$ref": "#/definitions/models.SavedFilter" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Retrieve all saved article filters\nCreate a new article filter with custom conditions", "consumes": [ "application/json", "application/json" ], "produces": [ "application/json", "application/json" ], "tags": [ "filters", "filters" ], "summary": "Create a new saved filter", "parameters": [ { "description": "Filter details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "List of saved filters", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.SavedFilter" } } }, "201": { "description": "Created filter", "schema": { "$ref": "#/definitions/models.SavedFilter" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/saved-filters/filter": { "put": { "description": "Update an existing saved filter's name or conditions\nDelete a saved filter by ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "filters", "filters" ], "summary": "Delete a saved filter", "parameters": [ { "type": "integer", "description": "Filter ID", "name": "id", "in": "query", "required": true }, { "description": "Updated filter details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } }, { "type": "integer", "description": "Filter ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "delete": { "description": "Update an existing saved filter's name or conditions\nDelete a saved filter by ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "filters", "filters" ], "summary": "Delete a saved filter", "parameters": [ { "type": "integer", "description": "Filter ID", "name": "id", "in": "query", "required": true }, { "description": "Updated filter details", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } }, { "type": "integer", "description": "Filter ID", "name": "id", "in": "query", "required": true } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/saved-filters/reorder": { "post": { "description": "Update the position of multiple saved filters", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "filters" ], "summary": "Reorder saved filters", "parameters": [ { "description": "Filters with updated positions", "name": "request", "in": "body", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/models.SavedFilter" } } } ], "responses": { "200": { "description": "Success message", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/scripts/dir": { "get": { "description": "Get the file system path to the scripts directory", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "scripts" ], "summary": "Get scripts directory path", "responses": { "200": { "description": "Scripts directory path (scripts_dir)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/scripts/dir/open": { "post": { "description": "Open the scripts directory in the system's file explorer/finder", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "scripts" ], "summary": "Open scripts directory", "responses": { "200": { "description": "Open status (status, scripts_dir)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Unsupported platform", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/scripts/list": { "get": { "description": "Get a list of all available scripts in the scripts directory (Python, Shell, PowerShell, Node.js, Ruby)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "scripts" ], "summary": "List available scripts", "responses": { "200": { "description": "List of scripts (scripts array with name, path, type)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/summaries/clear": { "delete": { "description": "Clear all cached article summaries from the database", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "summary" ], "summary": "Clear all summaries", "responses": { "200": { "description": "Success status", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/summarize": { "post": { "description": "Generate a summary for an article's content (uses local algorithm or AI based on settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "summary" ], "summary": "Summarize article", "parameters": [ { "description": "Summarize request (article_id, length, content)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Summary result (summary, html, sentence_count, is_too_short, cached, limit_reached, thinking)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid length parameter)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/tags": { "get": { "description": "GET: Retrieve all tags. POST: Create a new tag with name and color.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "List or create tags", "parameters": [ { "description": "Tag details (for POST)", "name": "request", "in": "body", "schema": { "type": "object" } } ], "responses": { "200": { "description": "List of tags (GET)", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Tag" } } }, "201": { "description": "Created tag (POST)", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "GET: Retrieve all tags. POST: Create a new tag with name and color.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "List or create tags", "parameters": [ { "description": "Tag details (for POST)", "name": "request", "in": "body", "schema": { "type": "object" } } ], "responses": { "200": { "description": "List of tags (GET)", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Tag" } } }, "201": { "description": "Created tag (POST)", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/tags/delete": { "post": { "description": "Delete an existing tag by its ID", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Delete a tag", "parameters": [ { "description": "Tag ID to delete", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Deletion status", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/tags/reorder": { "post": { "description": "Change the display position of a tag in the list", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Reorder a tag", "parameters": [ { "description": "Tag ID and new position", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Updated list of all tags", "schema": { "type": "array", "items": { "$ref": "#/definitions/models.Tag" } } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/tags/update": { "post": { "description": "Update an existing tag's name, color, and position", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "tags" ], "summary": "Update a tag", "parameters": [ { "description": "Tag update details (id, name, color, position)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Updated tag", "schema": { "$ref": "#/definitions/models.Tag" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/translate/article": { "post": { "description": "Translate an article's title to the target language (uses AI or Google based on settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Translate article title", "parameters": [ { "description": "Translation request (article_id, title, target_language)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Translation result (translated_title, limit_reached)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (missing required fields)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/translate/text": { "post": { "description": "Translate any text to the target language (uses AI or Google based on settings)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Translate text", "parameters": [ { "description": "Translation request (text, target_language)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Translation result (translated_text, html)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "400": { "description": "Bad request (missing required fields)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/translation/test-custom": { "post": { "description": "Test a custom translation API configuration", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Test custom translation", "parameters": [ { "description": "Test request", "name": "request", "in": "body", "required": true, "schema": { "$ref": "#/definitions/translation.TestCustomTranslationRequest" } } ], "responses": { "200": { "description": "Test result", "schema": { "$ref": "#/definitions/translation.TestCustomTranslationResponse" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/translations/clear": { "post": { "description": "Clear all translated article titles from the database", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "translation" ], "summary": "Clear all translations", "responses": { "200": { "description": "Success status", "schema": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/update/check": { "get": { "description": "Check GitHub for the latest stable release version (pre-releases are filtered out)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "update" ], "summary": "Check for updates", "responses": { "200": { "description": "Update info (current_version, latest_version, update_available, download_url, release_notes)", "schema": { "type": "object", "additionalProperties": true } }, "500": { "description": "Error checking for updates", "schema": { "type": "object", "additionalProperties": true } } } } }, "/update/download": { "post": { "description": "Download the update file from GitHub releases to the temp directory", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "update" ], "summary": "Download update", "parameters": [ { "description": "Download request (download_url, asset_name)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Download success (success, file_path, total_bytes, bytes_written)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid URL or asset name)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/update/install": { "post": { "description": "Install the downloaded update (will restart the application)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "update" ], "summary": "Install update", "parameters": [ { "description": "Install request (file_path)", "name": "request", "in": "body", "required": true, "schema": { "type": "object" } } ], "responses": { "200": { "description": "Installation started (success, message)", "schema": { "type": "object", "additionalProperties": true } }, "400": { "description": "Bad request (invalid file path or type)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/version": { "get": { "description": "Get the current application version string", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "update" ], "summary": "Get application version", "responses": { "200": { "description": "Application version (version)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/webpage/resource": { "get": { "description": "Proxy individual resources (CSS, JS, images, fonts, etc.) from a webpage", "consumes": [ "application/json" ], "produces": [ "application/octet-stream" ], "tags": [ "media" ], "summary": "Proxy webpage resource", "parameters": [ { "type": "string", "description": "Resource URL to proxy", "name": "url", "in": "query", "required": true }, { "type": "string", "description": "Referer URL for the webpage", "name": "referer", "in": "query", "required": true } ], "responses": { "200": { "description": "Resource file", "schema": { "type": "file" } }, "400": { "description": "Bad request (missing or invalid URL)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/window/state": { "get": { "description": "Get the saved window state (position, size, maximized status)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "window" ], "summary": "Get window state", "responses": { "200": { "description": "Window state (x, y, width, height, maximized)", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "post": { "description": "Save the current window state (position, size, maximized status)", "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "window" ], "summary": "Save window state", "parameters": [ { "description": "Window state to save", "name": "state", "in": "body", "required": true, "schema": { "$ref": "#/definitions/window.WindowState" } } ], "responses": { "200": { "description": "Window state saved successfully", "schema": { "type": "string" } }, "400": { "description": "Bad request", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "500": { "description": "Internal server error", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "definitions": { "article.ExportToNotionRequest": { "type": "object", "properties": { "article_id": { "type": "integer" } } }, "article.ExportToObsidianRequest": { "type": "object", "properties": { "article_id": { "type": "integer" } } }, "article.ExportToZoteroRequest": { "type": "object", "properties": { "article_id": { "type": "integer" } } }, "article.FilterCondition": { "type": "object", "properties": { "field": { "description": "\"feed_name\", \"feed_category\", \"article_title\", \"published_after\", \"published_before\"", "type": "string" }, "id": { "type": "integer" }, "logic": { "description": "\"and\", \"or\" (null for first condition)", "type": "string" }, "negate": { "description": "NOT modifier for this condition", "type": "boolean" }, "operator": { "description": "\"contains\", \"exact\" (null for date fields and multi-select)", "type": "string" }, "value": { "description": "Single value for text/date fields", "type": "string" }, "values": { "description": "Multiple values for feed_name and feed_category", "type": "array", "items": { "type": "string" } } } }, "article.FilterRequest": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/definitions/article.FilterCondition" } }, "limit": { "type": "integer" }, "page": { "type": "integer" } } }, "article.FilterResponse": { "type": "object", "properties": { "articles": { "type": "array", "items": { "$ref": "#/definitions/models.Article" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" } } }, "article.PoolTaskInfo": { "type": "object", "properties": { "created_at": { "type": "string" }, "feed_id": { "type": "integer" }, "feed_title": { "type": "string" }, "reason": { "type": "integer" } } }, "article.QueueTaskInfo": { "type": "object", "properties": { "feed_id": { "type": "integer" }, "feed_title": { "type": "string" }, "position": { "type": "integer" } } }, "article.TaskDetailsResponse": { "type": "object", "properties": { "pool_tasks": { "type": "array", "items": { "$ref": "#/definitions/article.PoolTaskInfo" } }, "queue_tasks": { "type": "array", "items": { "$ref": "#/definitions/article.QueueTaskInfo" } } } }, "chat.ChatMessage": { "type": "object", "properties": { "content": { "type": "string" }, "role": { "description": "\"system\", \"user\", or \"assistant\"", "type": "string" } } }, "chat.ChatRequest": { "type": "object", "properties": { "article_content": { "type": "string" }, "article_title": { "type": "string" }, "article_url": { "type": "string" }, "is_first_message": { "type": "boolean" }, "messages": { "type": "array", "items": { "$ref": "#/definitions/chat.ChatMessage" } } } }, "chat.ChatResponse": { "type": "object", "properties": { "html": { "description": "Rendered HTML version of markdown response", "type": "string" }, "response": { "type": "string" } } }, "chat.CreateSessionRequest": { "type": "object", "properties": { "article_id": { "type": "integer" }, "title": { "type": "string" } } }, "chat.UpdateSessionRequest": { "type": "object", "properties": { "title": { "type": "string" } } }, "core.DiscoveryState": { "type": "object", "properties": { "error": { "type": "string" }, "feeds": { "type": "array", "items": { "$ref": "#/definitions/discovery.DiscoveredBlog" } }, "is_complete": { "type": "boolean" }, "is_running": { "type": "boolean" }, "progress": { "$ref": "#/definitions/discovery.Progress" } } }, "database.ChatSession": { "type": "object", "properties": { "article_id": { "type": "integer" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "message_count": { "type": "integer" }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "discovery.DiscoveredBlog": { "type": "object", "properties": { "homepage": { "type": "string" }, "icon_url": { "type": "string" }, "name": { "type": "string" }, "recent_articles": { "type": "array", "items": { "$ref": "#/definitions/discovery.RecentArticle" } }, "rss_feed": { "type": "string" } } }, "discovery.Progress": { "type": "object", "properties": { "current": { "description": "Current item index", "type": "integer" }, "detail": { "description": "Additional detail (e.g., current URL being checked)", "type": "string" }, "feed_name": { "description": "Name of the feed being processed (for batch discovery)", "type": "string" }, "found_count": { "description": "Number of feeds found so far", "type": "integer" }, "message": { "description": "Human-readable message", "type": "string" }, "stage": { "description": "Current stage (e.g., \"fetching_homepage\", \"finding_friend_links\", \"checking_rss\")", "type": "string" }, "total": { "description": "Total items to process", "type": "integer" } } }, "discovery.RecentArticle": { "type": "object", "properties": { "date": { "description": "ISO 8601 format or relative time", "type": "string" }, "title": { "type": "string" } } }, "handlers.AISearchRequest": { "type": "object", "properties": { "query": { "type": "string" } } }, "handlers.AISearchResponse": { "type": "object", "properties": { "articles": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "error": { "type": "string" }, "search_terms": { "type": "string" }, "success": { "type": "boolean" }, "total_count": { "type": "integer" } } }, "handlers.ProfileRequest": { "type": "object", "properties": { "api_key": { "type": "string" }, "custom_headers": { "type": "string" }, "endpoint": { "type": "string" }, "is_default": { "type": "boolean" }, "model": { "type": "string" }, "name": { "type": "string" } } }, "handlers.ProfileTestRequest": { "type": "object", "properties": { "api_key": { "type": "string" }, "custom_headers": { "type": "string" }, "endpoint": { "type": "string" }, "model": { "type": "string" } } }, "handlers.ProfileTestResult": { "type": "object", "properties": { "config_valid": { "type": "boolean" }, "connection_success": { "type": "boolean" }, "error_message": { "type": "string" }, "model_available": { "type": "boolean" }, "profile_id": { "type": "integer" }, "profile_name": { "type": "string" }, "response_time_ms": { "type": "integer" } } }, "handlers.TestResult": { "type": "object", "properties": { "config_valid": { "type": "boolean" }, "connection_success": { "type": "boolean" }, "error_message": { "type": "string" }, "model_available": { "type": "boolean" }, "response_time_ms": { "type": "integer" }, "test_time": { "type": "string" } } }, "models.AIProfile": { "type": "object", "properties": { "api_key": { "description": "Hidden in responses, only sent when needed", "type": "string" }, "created_at": { "type": "string" }, "custom_headers": { "description": "JSON string of key-value pairs", "type": "string" }, "endpoint": { "type": "string" }, "id": { "type": "integer" }, "is_default": { "description": "Default profile for new features", "type": "boolean" }, "model": { "type": "string" }, "name": { "type": "string" }, "updated_at": { "type": "string" } } }, "models.Article": { "type": "object", "properties": { "audio_url": { "type": "string" }, "author": { "description": "Article author", "type": "string" }, "feed_id": { "type": "integer" }, "feed_title": { "description": "Joined field", "type": "string" }, "freshrss_item_id": { "description": "FreshRSS/Google Reader item ID for API operations", "type": "string" }, "id": { "type": "integer" }, "image_url": { "type": "string" }, "is_favorite": { "type": "boolean" }, "is_hidden": { "type": "boolean" }, "is_read": { "type": "boolean" }, "is_read_later": { "type": "boolean" }, "published_at": { "type": "string" }, "summary": { "description": "Cached AI-generated summary", "type": "string" }, "title": { "type": "string" }, "translated_title": { "type": "string" }, "unique_id": { "description": "Unique identifier for deduplication (title+feed_id+published_date)", "type": "string" }, "url": { "type": "string" }, "video_url": { "description": "YouTube video URL for embedded player", "type": "string" } } }, "models.Feed": { "type": "object", "properties": { "article_view_mode": { "description": "Article view mode override ('global', 'webpage', 'rendered')", "type": "string" }, "articles_per_month": { "description": "Average articles per month (last 90 days / 3)", "type": "number" }, "auto_expand_content": { "description": "Auto expand content mode ('global', 'enabled', 'disabled')", "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "discovery_completed": { "description": "Track if discovery has been run", "type": "boolean" }, "email_address": { "description": "Email/Newsletter support", "type": "string" }, "email_folder": { "description": "IMAP folder to monitor (default INBOX)", "type": "string" }, "email_imap_port": { "description": "IMAP server port (default 993)", "type": "integer" }, "email_imap_server": { "description": "IMAP server address", "type": "string" }, "email_last_uid": { "description": "Last processed email UID for incremental updates", "type": "integer" }, "email_password": { "description": "IMAP password (encrypted)", "type": "string" }, "email_username": { "description": "IMAP username", "type": "string" }, "freshrss_stream_id": { "description": "FreshRSS stream ID (e.g., \"feed/http://...\")", "type": "string" }, "hide_from_timeline": { "description": "Hide articles from timeline views", "type": "boolean" }, "id": { "type": "integer" }, "image_url": { "description": "New field", "type": "string" }, "is_freshrss_source": { "description": "FreshRSS integration", "type": "boolean" }, "is_image_mode": { "description": "Whether this feed is for image gallery mode", "type": "boolean" }, "last_error": { "description": "Track last fetch error", "type": "string" }, "last_update_status": { "description": "Last update status (\"success\" or \"failed\")", "type": "string" }, "last_updated": { "type": "string" }, "latest_article_time": { "description": "Statistics", "type": "string" }, "link": { "description": "Website homepage link", "type": "string" }, "position": { "description": "Position within category for custom ordering", "type": "integer" }, "proxy_enabled": { "description": "Whether to use proxy for this feed", "type": "boolean" }, "proxy_url": { "description": "Custom proxy URL for this feed (overrides global)", "type": "string" }, "refresh_interval": { "description": "Custom refresh interval in minutes (0 = use global, -1 = intelligent, -2 = never, \u003e0 = custom minutes)", "type": "integer" }, "script_path": { "description": "Path to custom script for fetching feed", "type": "string" }, "tags": { "description": "Tags (populated by API handlers)", "type": "array", "items": { "$ref": "#/definitions/models.Tag" } }, "title": { "type": "string" }, "type": { "description": "XPath support for HTML/XML scraping", "type": "string" }, "url": { "type": "string" }, "xpath_item": { "description": "XPath to extract feed items", "type": "string" }, "xpath_item_author": { "description": "XPath to extract item author", "type": "string" }, "xpath_item_categories": { "description": "XPath to extract item categories", "type": "string" }, "xpath_item_content": { "description": "XPath to extract item content", "type": "string" }, "xpath_item_thumbnail": { "description": "XPath to extract item thumbnail", "type": "string" }, "xpath_item_time_format": { "description": "Time format for parsing timestamp", "type": "string" }, "xpath_item_timestamp": { "description": "XPath to extract item timestamp", "type": "string" }, "xpath_item_title": { "description": "XPath to extract item title", "type": "string" }, "xpath_item_uid": { "description": "XPath to extract item unique ID", "type": "string" }, "xpath_item_uri": { "description": "XPath to extract item URI", "type": "string" } } }, "models.SavedFilter": { "type": "object", "properties": { "conditions": { "description": "JSON string of FilterCondition[]", "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "updated_at": { "type": "string" } } }, "models.Tag": { "type": "object", "properties": { "color": { "type": "string" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" } } }, "network.DetectionResult": { "type": "object", "properties": { "bandwidth_mbps": { "type": "number" }, "detection_success": { "type": "boolean" }, "detection_time": { "type": "string" }, "error_message": { "type": "string" }, "latency_ms": { "type": "integer" }, "max_concurrency": { "type": "integer" }, "speed_level": { "$ref": "#/definitions/network.SpeedLevel" } } }, "network.SpeedLevel": { "type": "string", "enum": [ "slow", "medium", "fast" ], "x-enum-varnames": [ "SpeedSlow", "SpeedMedium", "SpeedFast" ] }, "rules.Condition": { "type": "object", "properties": { "field": { "description": "\"feed_name\", \"feed_category\", \"article_title\", etc.", "type": "string" }, "id": { "type": "integer" }, "logic": { "description": "\"and\", \"or\" (null for first condition)", "type": "string" }, "negate": { "description": "NOT modifier for this condition", "type": "boolean" }, "operator": { "description": "\"contains\", \"exact\"", "type": "string" }, "value": { "description": "Single value for text/date fields", "type": "string" }, "values": { "description": "Multiple values for feed_name and feed_category", "type": "array", "items": { "type": "string" } } } }, "rules.Rule": { "type": "object", "properties": { "actions": { "description": "\"favorite\", \"unfavorite\", \"hide\", \"unhide\", \"mark_read\", \"mark_unread\"", "type": "array", "items": { "type": "string" } }, "conditions": { "type": "array", "items": { "$ref": "#/definitions/rules.Condition" } }, "enabled": { "type": "boolean" }, "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "description": "Execution order (0 = first)", "type": "integer" } } }, "statistics.StatPeriod": { "type": "string", "enum": [ "week", "month", "year", "all", "custom" ], "x-enum-varnames": [ "PeriodWeek", "PeriodMonth", "PeriodYear", "PeriodAll", "PeriodCustom" ] }, "statistics.StatSummary": { "type": "object", "properties": { "can_navigate": { "type": "boolean" }, "daily_data": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } }, "display_label": { "type": "string" }, "end_date": { "type": "string" }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "period": { "$ref": "#/definitions/statistics.StatPeriod" }, "start_date": { "type": "string" }, "totals": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "translation.CustomTranslatorConfig": { "type": "object", "properties": { "bodyTemplate": { "description": "Request body template with placeholders", "type": "string" }, "endpoint": { "description": "API endpoint URL", "type": "string" }, "headers": { "description": "Custom HTTP headers", "type": "object", "additionalProperties": { "type": "string" } }, "langCodeMapping": { "description": "Custom language code mapping", "type": "object", "additionalProperties": { "type": "string" } }, "method": { "description": "HTTP method (GET/POST)", "type": "string" }, "name": { "description": "Configuration name", "type": "string" }, "responsePath": { "description": "JSONPath to extract translation from response", "type": "string" }, "timeout": { "description": "Request timeout in seconds", "type": "integer" } } }, "translation.TestCustomTranslationRequest": { "type": "object", "properties": { "config": { "$ref": "#/definitions/translation.CustomTranslatorConfig" }, "target_lang": { "type": "string", "example": "zh" }, "text": { "type": "string", "example": "Hello, world!" } } }, "translation.TestCustomTranslationResponse": { "type": "object", "properties": { "error": { "type": "string" }, "result": { "type": "string" }, "success": { "type": "boolean" } } }, "window.WindowState": { "type": "object", "properties": { "height": { "type": "integer" }, "maximized": { "type": "boolean" }, "width": { "type": "integer" }, "x": { "type": "integer" }, "y": { "type": "integer" } } } }, "securityDefinitions": { "BearerAuth": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } } }