{ "openapi": "3.1.0", "info": { "title": "Glanced API", "description": "REST API for Glanced, the RSS reader for news, blogs, and newsletters.\n\nRequests authenticate with an API key: `Authorization: Bearer glanced_live_…`. Operations carrying the Bearer scheme accept an API key; the remaining /v1 operations are reserved for the first-party app and reject API keys. Full documentation: https://docs.glanced.io", "version": "0.15.2" }, "servers": [ { "url": "https://api.glanced.io", "description": "Production" } ], "paths": { "/v1/items": { "get": { "tags": [ "Items" ], "summary": "List items", "description": "Get user's items with optional filters and search using cursor-based pagination.", "operationId": "list_items_v1_items_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor for fetching next page of items. Use for infinite scroll pagination.", "title": "Cursor" }, "description": "Pagination cursor for fetching next page of items. Use for infinite scroll pagination." }, { "name": "subscription_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Filter by subscription IDs", "title": "Subscription Ids" }, "description": "Filter by subscription IDs" }, { "name": "is_read", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(read|unread)$" }, { "type": "null" } ], "description": "Filter by read state: 'read' for read items, 'unread' for unread items. If not provided, shows all items", "title": "Is Read" }, "description": "Filter by read state: 'read' for read items, 'unread' for unread items. If not provided, shows all items" }, { "name": "tag_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Filter by tag IDs.", "title": "Tag Ids" }, "description": "Filter by tag IDs." }, { "name": "folder_ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid" } }, { "type": "null" } ], "description": "Filter by folder IDs", "title": "Folder Ids" }, "description": "Filter by folder IDs" }, { "name": "is_saved", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(true|false)$" }, { "type": "null" } ], "description": "Filter by saved state: 'true' for saved items, 'false' for items not saved. If not provided, shows all items", "title": "Is Saved" }, "description": "Filter by saved state: 'true' for saved items, 'false' for items not saved. If not provided, shows all items" }, { "name": "q", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ], "description": "Search query string for full-text search", "title": "Q" }, "description": "Search query string for full-text search" }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Filter items published on or after this date (ISO 8601)", "title": "From Date" }, "description": "Filter items published on or after this date (ISO 8601)" }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Filter items published on or before this date (ISO 8601)", "title": "To Date" }, "description": "Filter items published on or before this date (ISO 8601)" }, { "name": "item_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(article|episode)$" }, { "type": "null" } ], "description": "Filter by item type: 'article' or 'episode'. If not provided, shows all items", "title": "Item Type" }, "description": "Filter by item type: 'article' or 'episode'. If not provided, shows all items" }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(newest|oldest|recently_played)$" }, { "type": "null" } ], "description": "Sort order: 'newest' (default), 'oldest', or 'recently_played' (by last_played_at; episodes only). Only affects episodes (item_type=episode); articles and mixed lists always return newest-first.", "title": "Order By" }, "description": "Sort order: 'newest' (default), 'oldest', or 'recently_played' (by last_played_at; episodes only). Only affects episodes (item_type=episode); articles and mixed lists always return newest-first." }, { "name": "in_progress", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter to in-progress episodes (started, not completed). Episodes only.", "title": "In Progress" }, "description": "Filter to in-progress episodes (started, not completed). Episodes only." }, { "name": "include_global", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Plus: append global corpus matches after your library's (requires a search query).", "default": false, "title": "Include Global" }, "description": "Plus: append global corpus matches after your library's (requires a search query)." }, { "name": "include_body", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Search article bodies in addition to heads; search surfaces disable this to ride the candidate index.", "default": true, "title": "Include Body" }, "description": "Search article bodies in addition to heads; search surfaces disable this to ride the candidate index." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of items to return", "default": 50, "title": "Limit" }, "description": "Number of items to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_ItemListResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "A filter references a folder, subscription, or tag that doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "put": { "tags": [ "Items" ], "summary": "Mark all as read", "description": "Mark all items as read or unread for the current user with optional filtering.", "operationId": "mark_all_as_read_v1_items_put", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAllReadRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "A filter references a folder, subscription, or tag that doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Items" ], "summary": "Bulk item actions", "description": "Perform bulk actions on selected items: mark read/unread or save/unsave.", "operationId": "bulk_update_items_v1_items_patch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkItemActionRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Saved-items limit reached (save action).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/items/{item_id}": { "get": { "tags": [ "Items" ], "summary": "Get item details", "description": "Get specific item details.", "operationId": "get_item_v1_items__item_id__get", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The item's id", "title": "Item Id" }, "description": "The item's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Item not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Items" ], "summary": "Update item state", "description": "Update user's item state (read/unread, save/unsave) and tags.", "operationId": "update_item_state_v1_items__item_id__patch", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The item's id", "title": "Item Id" }, "description": "The item's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemStateUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemResponse" } } } }, "400": { "description": "Invalid state change, e.g. notes on an episode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Plan doesn't include the requested feature (notes, full content), or saved-items limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Item not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/items/{item_id}/similar": { "get": { "tags": [ "Items" ], "summary": "Find similar items", "description": "Find semantically similar items using vector search.", "operationId": "get_similar_articles_v1_items__item_id__similar_get", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The item's id", "title": "Item Id" }, "description": "The item's id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum number of similar items to return", "default": 10, "title": "Limit" }, "description": "Maximum number of similar items to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarItemsResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Similar items are not available on your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/items/{item_id}/readlater": { "post": { "tags": [ "Items" ], "summary": "Send to read-later", "description": "Send an article to a linked read-later service. The integration must be connected in Automation first.", "operationId": "send_to_read_later_v1_items__item_id__readlater_post", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The item's id", "title": "Item Id" }, "description": "The item's id" }, { "name": "service", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/IntegrationService", "description": "Read-later service: readwise, cubox, raindrop, or instapaper" }, "description": "Read-later service: readwise, cubox, raindrop, or instapaper" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "400": { "description": "Service not linked or doesn't support this item type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Read-later integrations are not available on your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Item not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/items/{item_id}/playback-progress": { "post": { "tags": [ "Items" ], "summary": "Record playback progress", "description": "Record episode playback position. Last-write-wins across devices (send the client's clock as client_timestamp). Marks the episode read once within 5% of its duration.", "operationId": "record_playback_progress_v1_items__item_id__playback_progress_post", "parameters": [ { "name": "item_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The item's id", "title": "Item Id" }, "description": "The item's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackProgressRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackProgressResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/stories": { "get": { "tags": [ "Stories" ], "summary": "List stories", "description": "Grouped same-event articles across the user's sources (story clusters), newest first. Each story carries the user's subset of its articles.", "operationId": "list_stories_v1_stories_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of stories to return", "default": 50, "title": "Limit" }, "description": "Number of stories to return" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponse_StoryResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Stories are not available on your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions", "description": "Get user's subscriptions with optional folder filtering and pagination.", "operationId": "get_subscriptions_v1_subscriptions_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of subscriptions to return", "default": 50, "title": "Limit" }, "description": "Number of subscriptions to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of subscriptions to skip (used for alphabetical ordering)", "default": 0, "title": "Offset" }, "description": "Number of subscriptions to skip (used for alphabetical ordering)" }, { "name": "folder_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Filter subscriptions by folder ID. If not provided, returns subscriptions without folder assignment (unless all=True)", "title": "Folder Id" }, "description": "Filter subscriptions by folder ID. If not provided, returns subscriptions without folder assignment (unless all=True)" }, { "name": "all", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Return all subscriptions regardless of folder assignment. When true, folder_id is ignored", "default": false, "title": "All" }, "description": "Return all subscriptions regardless of folder assignment. When true, folder_id is ignored" }, { "name": "order_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(name|recent)$" }, { "type": "null" } ], "description": "Order subscriptions: 'name' for alphabetical A-Z with offset pagination, 'recent' for cursor-based pagination (newest items first)", "title": "Order By" }, "description": "Order subscriptions: 'name' for alphabetical A-Z with offset pagination, 'recent' for cursor-based pagination (newest items first)" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination cursor for fetching next page when order_by='recent'", "title": "Cursor" }, "description": "Pagination cursor for fetching next page when order_by='recent'" }, { "name": "source_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(feed|newsletter|podcast)$" }, { "type": "null" } ], "description": "Filter by source type: 'feed', 'newsletter', or 'podcast'", "title": "Source Type" }, "description": "Filter by source type: 'feed', 'newsletter', or 'podcast'" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_SubscriptionListResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Subscriptions" ], "summary": "Subscribe to feed", "description": "Subscribe to a feed by URL. Feeds already known to Glanced are subscribed synchronously; unknown URLs are fetched, created, and subscribed inline.", "operationId": "subscribe_to_feed_v1_subscriptions_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" } } } }, "responses": { "200": { "description": "Already subscribed; returned with status already_subscribed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateResponse" } } } }, "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateResponse" } } } }, "400": { "description": "Invalid URL or target folder, or the URL does not host a parseable feed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Feed limit reached for your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "Feed URL could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Subscriptions" ], "summary": "Bulk update subscriptions", "description": "Bulk update subscriptions (pause/resume, pin/unpin, move to folder).", "operationId": "bulk_update_subscriptions_v1_subscriptions_patch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateSubscriptionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionListResponse" }, "title": "Response Bulk Update Subscriptions V1 Subscriptions Patch" } } } }, "400": { "description": "Invalid update payload or target folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Feed limit reached when resuming paused subscriptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Subscriptions" ], "summary": "Bulk unsubscribe", "description": "Unsubscribe from multiple subscriptions at once.", "operationId": "bulk_unsubscribe_v1_subscriptions_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteSubscriptionsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/subscriptions/check": { "get": { "tags": [ "Subscriptions" ], "summary": "Check subscription presence", "description": "Lightweight presence check for onboarding and dashboard layout: whether the user has any feed (article) or podcast subscriptions.", "operationId": "check_subscriptions_v1_subscriptions_check_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCheckResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/subscriptions/{subscription_id}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get subscription details", "description": "Get subscription details by ID.", "operationId": "get_subscription_v1_subscriptions__subscription_id__get", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The subscription's id", "title": "Subscription Id" }, "description": "The subscription's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Subscription not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Subscriptions" ], "summary": "Update subscription", "description": "Update subscription by ID.", "operationId": "update_subscription_v1_subscriptions__subscription_id__patch", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The subscription's id", "title": "Subscription Id" }, "description": "The subscription's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionListResponse" } } } }, "400": { "description": "Invalid update payload or target folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Feed limit reached when resuming a paused subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Subscription not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Subscriptions" ], "summary": "Unsubscribe", "description": "Unsubscribe by subscription ID. This will delete the subscription and remove items that aren't accessible via other subscriptions.", "operationId": "unsubscribe_v1_subscriptions__subscription_id__delete", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The subscription's id", "title": "Subscription Id" }, "description": "The subscription's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Subscription not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/subscriptions/newsletters": { "post": { "tags": [ "Subscriptions" ], "summary": "Create newsletter address", "description": "Generate unique email address for newsletter subscriptions.", "operationId": "create_newsletter_address_v1_subscriptions_newsletters_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewsletterCreateResponse" } } } }, "400": { "description": "Invalid newsletter title.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Newsletter limit reached for your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/folders": { "get": { "tags": [ "Folders" ], "summary": "List user folders", "description": "Get user's folders with pagination.", "operationId": "list_folders_v1_folders_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of folders to return", "default": 50, "title": "Limit" }, "description": "Number of folders to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of folders to skip", "default": 0, "title": "Offset" }, "description": "Number of folders to skip" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_FolderListResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Folders" ], "summary": "Create folder", "description": "Create a new folder.", "operationId": "create_folder_v1_folders_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderListResponse" } } } }, "400": { "description": "Invalid name or parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "409": { "description": "A folder with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Folders" ], "summary": "Bulk update folders", "description": "Bulk update folders (pin/unpin or move to parent).", "operationId": "bulk_update_folders_v1_folders_patch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateFoldersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FolderListResponse" }, "title": "Response Bulk Update Folders V1 Folders Patch" } } } }, "400": { "description": "Invalid payload, e.g. a circular parent move.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "One or more folders not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Folders" ], "summary": "Bulk delete folders", "description": "Delete multiple folders.", "operationId": "bulk_delete_folders_v1_folders_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteFoldersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "One or more folders not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/folders/{folder_id}": { "get": { "tags": [ "Folders" ], "summary": "Get folder details", "description": "Get folder details.", "operationId": "get_folder_details_v1_folders__folder_id__get", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The folder's id", "title": "Folder Id" }, "description": "The folder's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Folder not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Folders" ], "summary": "Update folder", "description": "Update folder.", "operationId": "update_folder_v1_folders__folder_id__patch", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The folder's id", "title": "Folder Id" }, "description": "The folder's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderListResponse" } } } }, "400": { "description": "Invalid name or parent folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Folder not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The new name collides with an existing folder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Folders" ], "summary": "Delete folder", "description": "Delete folder.", "operationId": "delete_folder_v1_folders__folder_id__delete", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The folder's id", "title": "Folder Id" }, "description": "The folder's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Folder not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/folders/{folder_id}/subscriptions": { "put": { "tags": [ "Folders" ], "summary": "Bulk update folder subscriptions", "description": "Pause or resume all subscriptions in a folder (recursive through subfolders).", "operationId": "bulk_update_folder_subscriptions_v1_folders__folder_id__subscriptions_put", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The folder's id", "title": "Folder Id" }, "description": "The folder's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderSubscriptionsBulkUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "description": "Get tags for the current user with pagination.", "operationId": "get_tags_v1_tags_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of tags to return", "default": 50, "title": "Limit" }, "description": "Number of tags to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of tags to skip (for alphabetical pagination)", "default": 0, "title": "Offset" }, "description": "Number of tags to skip (for alphabetical pagination)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_TagListResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Tags" ], "summary": "Create tag", "description": "Create a new user tag.", "operationId": "create_tag_v1_tags_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "409": { "description": "A tag with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Tags" ], "summary": "Bulk delete tags", "description": "Delete multiple tags at once.", "operationId": "bulk_delete_tags_v1_tags_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteTagsRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/tags/{tag_id}": { "get": { "tags": [ "Tags" ], "summary": "Get tag", "description": "Get a specific tag by ID.", "operationId": "get_tag_v1_tags__tag_id__get", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The tag's id", "title": "Tag Id" }, "description": "The tag's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Tag not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Tags" ], "summary": "Update tag", "description": "Update a user tag.", "operationId": "update_tag_v1_tags__tag_id__patch", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The tag's id", "title": "Tag Id" }, "description": "The tag's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagListResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Tag not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A tag with the new name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Tags" ], "summary": "Delete tag", "description": "Delete a user tag.", "operationId": "delete_tag_v1_tags__tag_id__delete", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The tag's id", "title": "Tag Id" }, "description": "The tag's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Tag not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/search": { "get": { "tags": [ "Search" ], "summary": "Universal search", "description": "Search across items, feeds, tags, and folders with intelligent ranking. Returns up to 20 results.", "operationId": "universal_search_v1_search_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search query string", "title": "Q" }, "description": "Search query string" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/search/feeds": { "get": { "tags": [ "Search" ], "summary": "Search feeds", "description": "Search across user's feed subscriptions.", "operationId": "search_subscriptions_v1_search_feeds_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search query string", "title": "Q" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Maximum number of results", "default": 20, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Result offset for pagination", "default": 0, "title": "Offset" }, "description": "Result offset for pagination" }, { "name": "source_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^(feed|newsletter|podcast)$" }, { "type": "null" } ], "description": "Filter by source type", "title": "Source Type" }, "description": "Filter by source type" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/search/folders": { "get": { "tags": [ "Search" ], "summary": "Search folders", "description": "Search across user's folders.", "operationId": "search_folders_v1_search_folders_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search query string", "title": "Q" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum number of results", "default": 20, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Result offset for pagination", "default": 0, "title": "Offset" }, "description": "Result offset for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/search/tags": { "get": { "tags": [ "Search" ], "summary": "Search tags", "description": "Search across user's tags.", "operationId": "search_tags_v1_search_tags_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search query string", "title": "Q" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum number of results", "default": 20, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Result offset for pagination", "default": 0, "title": "Offset" }, "description": "Result offset for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/search/saved-searches": { "get": { "tags": [ "Search" ], "summary": "Search saved searches", "description": "Search across user's saved searches.", "operationId": "search_saved_searches_v1_search_saved_searches_get", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Search query string", "title": "Q" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Maximum number of results", "default": 20, "title": "Limit" }, "description": "Maximum number of results" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Result offset for pagination", "default": 0, "title": "Offset" }, "description": "Result offset for pagination" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/saved-searches": { "get": { "tags": [ "Saved Searches" ], "summary": "List saved searches", "description": "Get saved searches for the current user with pagination and filtering.", "operationId": "get_saved_searches_v1_saved_searches_get", "parameters": [ { "name": "is_pinned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Filter to only pinned searches", "title": "Is Pinned" }, "description": "Filter to only pinned searches" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of searches to return", "default": 50, "title": "Limit" }, "description": "Number of searches to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Number of searches to skip", "default": 0, "title": "Offset" }, "description": "Number of searches to skip" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_SavedSearchResponse_" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "post": { "tags": [ "Saved Searches" ], "summary": "Create saved search", "description": "Save a search query for later use.", "operationId": "create_saved_search_v1_saved_searches_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Saved searches are not available on your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "409": { "description": "A saved search with this name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Saved Searches" ], "summary": "Bulk delete saved searches", "description": "Delete multiple saved searches at once.", "operationId": "bulk_delete_saved_searches_v1_saved_searches_delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteSavedSearchesRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } }, "/v1/saved-searches/{search_id}": { "get": { "tags": [ "Saved Searches" ], "summary": "Get saved search", "description": "Get a specific saved search by ID, including its filter parameters.", "operationId": "get_saved_search_v1_saved_searches__search_id__get", "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The saved search's id", "title": "Search Id" }, "description": "The saved search's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Saved search not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "patch": { "tags": [ "Saved Searches" ], "summary": "Update saved search", "description": "Update a saved search name, filters, or pinned status.", "operationId": "update_saved_search_v1_saved_searches__search_id__patch", "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The saved search's id", "title": "Search Id" }, "description": "The saved search's id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchResponse" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "402": { "description": "Saved searches are not available on your plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Saved search not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A saved search with the new name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] }, "delete": { "tags": [ "Saved Searches" ], "summary": "Delete saved search", "description": "Delete a saved search.", "operationId": "delete_saved_search_v1_saved_searches__search_id__delete", "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The saved search's id", "title": "Search Id" }, "description": "The saved search's id" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseMessage" } } } }, "401": { "description": "A missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthErrorResponse" } } } }, "403": { "description": "A banned or locked account, or a token used on an endpoint outside its allowed scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } }, "404": { "description": "Saved search not found or access denied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed. `message` joins one friendly sentence per invalid field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "A rate limit was hit. Wait out `Retry-After` before retrying.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "503": { "description": "The service was temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthErrorResponse" }, { "$ref": "#/components/schemas/ErrorResponse" } ] } } } } }, "security": [ { "Bearer": [] } ] } } }, "components": { "schemas": { "PaginatedResponse_ItemListResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ItemListResponse" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "PaginatedResponse[ItemListResponse]" }, "ItemListResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Item id." }, "title": { "type": "string", "title": "Title", "description": "Item title." }, "feeds": { "items": { "$ref": "#/components/schemas/ItemFeedList" }, "type": "array", "title": "Feeds", "description": "Subscription(s) the item was received through." }, "item_type": { "type": "string", "enum": [ "article", "episode" ], "title": "Item Type", "description": "Article or podcast episode.", "default": "article" }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url", "description": "Enclosure URL attached to the article, if any." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Published At", "description": "Publisher's original publication time." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url", "description": "Deduplicated canonical URL of the article." }, "is_read": { "type": "boolean", "title": "Is Read", "description": "Read state for the current user.", "default": false }, "is_saved": { "type": "boolean", "title": "Is Saved", "description": "Saved/starred state for the current user.", "default": false }, "is_global": { "type": "boolean", "title": "Is Global", "description": "Corpus match outside your library (global search results).", "default": false }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Publisher summary, or the AI summary when your preferences and plan enable AI summaries and one exists." }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audio Url", "description": "Episode audio URL (episodes only)." }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Episode duration (episodes only)." }, "episode_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Episode Number", "description": "Episode number within the podcast (episodes only)." }, "episode_type": { "anyOf": [ { "type": "string", "enum": [ "full", "trailer", "bonus" ] }, { "type": "null" } ], "title": "Episode Type", "description": "Episode type (episodes only)." }, "playback_position": { "type": "integer", "title": "Playback Position", "description": "Your playback position in seconds (episodes only).", "default": 0 }, "last_played_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Played At", "description": "When you last played this item." }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url", "description": "Podcast artwork URL (episodes only)." }, "explicit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Explicit", "description": "Podcast explicit flag (episodes only)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Episode/podcast description (episodes only)." } }, "type": "object", "required": [ "id", "title" ], "title": "ItemListResponse", "description": "Item shape returned by list and search endpoints." }, "ItemFeedList": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription id." }, "title": { "type": "string", "title": "Title", "description": "Subscription title." }, "source_type": { "type": "string", "enum": [ "feed", "newsletter", "podcast" ], "title": "Source Type", "description": "Subscription source type." }, "website": { "type": "string", "title": "Website", "description": "Publisher website; may be empty." } }, "type": "object", "required": [ "id", "title", "source_type", "website" ], "title": "ItemFeedList", "description": "The subscription an item was received through." }, "PaginationMetadata": { "properties": { "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total", "description": "Total matching records; null where the endpoint doesn't count (e.g. list items)." }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit", "description": "Page size in effect." }, "offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Offset", "description": "Echoed request offset; 0 on cursor-paginated endpoints." }, "has_more": { "type": "boolean", "title": "Has More", "description": "Whether another page follows." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque cursor for the next page. Pass back as the endpoint's cursor parameter. Null on the last page and on offset-paginated endpoints." } }, "type": "object", "required": [ "has_more" ], "title": "PaginationMetadata", "description": "Paging info shared by paginated endpoints.\n\nEndpoints page either by cursor or by offset; which fields carry meaning\ndepends on the mode. Cursor endpoints (list items; subscriptions with\norder_by=recent) populate next_cursor and leave offset at 0; offset\nendpoints echo the requested offset and leave next_cursor null." }, "AuthErrorResponse": { "description": "Body of errors produced directly by the auth middleware.", "properties": { "error": { "description": "Reason the request was rejected, e.g. 'Invalid or revoked API key'.", "title": "Error", "type": "string" }, "status_code": { "description": "HTTP status code, mirrored from the response.", "title": "Status Code", "type": "integer" } }, "required": [ "error", "status_code" ], "title": "AuthErrorResponse", "type": "object" }, "ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error", "description": "Machine-readable code: the exception class name upper-cased (e.g. NOTFOUNDERROR, QUOTAEXCEEDEDERROR) or VALIDATION_ERROR." }, "message": { "type": "string", "title": "Message", "description": "Human-readable description of the error." }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Error-specific payload (e.g. quota_type/current/limit on 402, validation_errors on 422 in development)." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Server time of the error." }, "request_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Request Id", "description": "Correlation id; include when contacting support." } }, "type": "object", "required": [ "error", "message", "timestamp" ], "title": "ErrorResponse", "description": "Envelope returned by the application exception handlers." }, "RateLimitErrorResponse": { "description": "Body of 429s produced by the request rate limiter.", "properties": { "error": { "description": "Always \"Rate limit exceeded\".", "title": "Error", "type": "string" }, "message": { "description": "Human-readable retry guidance.", "title": "Message", "type": "string" }, "type": { "const": "rate_limit", "description": "Always \"rate_limit\".", "title": "Type", "type": "string" } }, "required": [ "error", "message", "type" ], "title": "RateLimitErrorResponse", "type": "object" }, "MarkAllReadRequest": { "properties": { "is_read": { "type": "boolean", "title": "Is Read", "description": "Mark matching items read (true) or unread (false).", "default": true }, "subscription_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Subscription Ids", "description": "Limit to these subscriptions." }, "folder_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Folder Ids", "description": "Limit to items in these folders (direct membership only)." }, "tag_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Tag Ids", "description": "Limit to these tags." }, "is_read_filter": { "anyOf": [ { "type": "string", "pattern": "^(read|unread)$" }, { "type": "null" } ], "title": "Is Read Filter", "description": "Only touch items currently in this read state." }, "is_saved": { "anyOf": [ { "type": "string", "pattern": "^(true|false)$" }, { "type": "null" } ], "title": "Is Saved", "description": "Only touch items in this saved state." }, "q": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1 }, { "type": "null" } ], "title": "Q", "description": "Full-text query; only matching items are touched." }, "from_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "From Date", "description": "Only items published on or after this date." }, "to_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "To Date", "description": "Only items published on or before this date." }, "item_type": { "anyOf": [ { "type": "string", "enum": [ "article", "episode" ] }, { "type": "null" } ], "title": "Item Type", "description": "Limit to articles or episodes." } }, "type": "object", "title": "MarkAllReadRequest", "description": "PUT '/v1/items'." }, "ResponseMessage": { "properties": { "message": { "type": "string", "title": "Message", "description": "Human-readable result summary." } }, "type": "object", "required": [ "message" ], "title": "ResponseMessage", "description": "Plain acknowledgement returned by action endpoints." }, "BulkItemActionRequest": { "properties": { "item_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Item Ids", "description": "Items to act on." }, "action": { "type": "string", "enum": [ "mark_read", "mark_unread", "save", "unsave" ], "title": "Action", "description": "Action to apply to every listed item." } }, "type": "object", "required": [ "item_ids", "action" ], "title": "BulkItemActionRequest", "description": "PATCH '/v1/items'." }, "ItemResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Item id." }, "title": { "type": "string", "title": "Title", "description": "Item title." }, "feeds": { "items": { "$ref": "#/components/schemas/ItemFeedList" }, "type": "array", "title": "Feeds", "description": "Subscription(s) the item was received through." }, "item_type": { "type": "string", "enum": [ "article", "episode" ], "title": "Item Type", "description": "Article or podcast episode.", "default": "article" }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url", "description": "Enclosure URL attached to the article, if any." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Published At", "description": "Publisher's original publication time." }, "is_read": { "type": "boolean", "title": "Is Read", "description": "Read state for the current user.", "default": false }, "is_saved": { "type": "boolean", "title": "Is Saved", "description": "Saved/starred state for the current user.", "default": false }, "prefers_full_content": { "type": "boolean", "title": "Prefers Full Content", "description": "Whether you opted to read the full article instead of the feed excerpt for this item.", "default": false }, "is_global": { "type": "boolean", "title": "Is Global", "description": "Corpus match outside your library (global search results).", "default": false }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Publisher-provided summary, unmodified. The AI summary (when your preferences and plan enable one) is in ai_summary; list endpoints swap it into their summary field." }, "ai_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Summary", "description": "AI-generated summary; null unless your preferences and plan enable summaries and one exists." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Author", "description": "Article author byline." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url", "description": "Deduplicated canonical URL of the article." }, "tags": { "items": { "$ref": "#/components/schemas/TagListResponse" }, "type": "array", "title": "Tags", "description": "Your tags on this item." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "description": "Article body: full text when fetched for you, otherwise the feed-provided content." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 800 }, { "type": "null" } ], "title": "Notes", "description": "Your notes on this item." }, "reading_time": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Reading Time", "description": "Estimated reading time in minutes (~200 wpm)." }, "suggested_tags": { "items": { "type": "string" }, "type": "array", "title": "Suggested Tags", "description": "AI-suggested tags (Plus; empty until enriched)." }, "platform_metadata": { "additionalProperties": true, "type": "object", "title": "Platform Metadata", "description": "Podcast platform metadata, e.g. iTunes/Apple fields." }, "audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Audio Url", "description": "Episode audio URL (episodes only)." }, "duration_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Duration Seconds", "description": "Episode duration (episodes only)." }, "episode_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Episode Number", "description": "Episode number within the podcast (episodes only)." }, "episode_type": { "anyOf": [ { "type": "string", "enum": [ "full", "trailer", "bonus" ] }, { "type": "null" } ], "title": "Episode Type", "description": "Episode type (episodes only)." }, "playback_position": { "type": "integer", "title": "Playback Position", "description": "Your playback position in seconds (episodes only).", "default": 0 }, "last_played_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Played At", "description": "When you last played this item." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Episode/podcast description (episodes only)." }, "artwork_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artwork Url", "description": "Podcast artwork URL (episodes only)." }, "explicit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Explicit", "description": "Podcast explicit flag (episodes only)." } }, "type": "object", "required": [ "id", "title" ], "title": "ItemResponse", "description": "Full item detail, including content, notes, and tags." }, "TagListResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Tag name." }, "item_count": { "type": "integer", "title": "Item Count", "description": "Items carrying this tag.", "default": 0 } }, "type": "object", "required": [ "id", "name" ], "title": "TagListResponse", "description": "A user tag and how many items carry it." }, "ItemStateUpdateRequest": { "properties": { "is_read": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Read", "description": "Set read state." }, "is_saved": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Saved", "description": "Set saved/starred state." }, "prefers_full_content": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Prefers Full Content", "description": "Opt in/out of full-article text for this item (articles only)." }, "tag_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Tag Ids", "description": "Replaces your tags on this item when provided." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 800 }, { "type": "null" } ], "title": "Notes", "description": "Your notes (articles only)." }, "playback_position": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "title": "Playback Position", "description": "Playback position in seconds (episodes only)." } }, "type": "object", "title": "ItemStateUpdateRequest", "description": "PATCH '/v1/items/{item_id}'." }, "SimilarItemsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ItemSearchHit" }, "type": "array", "title": "Data", "description": "Results (unpaginated)." } }, "type": "object", "required": [ "data" ], "title": "SimilarItemsResponse" }, "ItemSearchHit": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Item id." }, "title": { "type": "string", "title": "Title", "description": "Item title." }, "item_type": { "type": "string", "enum": [ "article", "episode" ], "title": "Item Type", "description": "Article or podcast episode.", "default": "article" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Publisher summary, or the AI summary when your preferences and plan enable AI summaries and one exists." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Published At", "description": "Publisher's original publication time." }, "is_read": { "type": "boolean", "title": "Is Read", "description": "Read state for the current user.", "default": false }, "is_saved": { "type": "boolean", "title": "Is Saved", "description": "Saved/starred state for the current user.", "default": false }, "is_global": { "type": "boolean", "title": "Is Global", "description": "Corpus match outside your library (global search results).", "default": false }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url", "description": "Enclosure URL attached to the article, if any." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url", "description": "Deduplicated canonical URL of the article." }, "feeds": { "items": { "$ref": "#/components/schemas/ItemFeedList" }, "type": "array", "title": "Feeds", "description": "Subscription(s) the item was received through." } }, "type": "object", "required": [ "id", "title" ], "title": "ItemSearchHit", "description": "An item returned by item search and similar-items." }, "IntegrationService": { "type": "string", "enum": [ "readwise", "cubox", "raindrop", "instapaper" ], "title": "IntegrationService" }, "PlaybackProgressRequest": { "properties": { "position_seconds": { "type": "integer", "maximum": 86400, "minimum": 0, "title": "Position Seconds", "description": "Current playback position; last write across devices wins." }, "client_timestamp": { "type": "string", "format": "date-time", "title": "Client Timestamp", "description": "Client clock for last-write-wins resolution; defaults to now." } }, "type": "object", "required": [ "position_seconds" ], "title": "PlaybackProgressRequest", "description": "POST '/v1/items/{item_id}/playback-progress'." }, "PlaybackProgressResponse": { "properties": { "playback_position": { "type": "integer", "title": "Playback Position", "description": "Stored position in seconds.", "default": 0 }, "last_played_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Played At", "description": "When this item was last played." }, "is_read": { "type": "boolean", "title": "Is Read", "description": "Read state; episodes auto-mark read near completion.", "default": false }, "completed": { "type": "boolean", "title": "Completed", "description": "True the first time playback reaches (near) the end.", "default": false } }, "type": "object", "title": "PlaybackProgressResponse", "description": "Response for playback-progress writes (authoritative post-write state)." }, "ListResponse_StoryResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/StoryResponse" }, "type": "array", "title": "Data", "description": "Results (unpaginated)." } }, "type": "object", "required": [ "data" ], "title": "ListResponse[StoryResponse]" }, "StoryResponse": { "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "AI-generated headline for the event; null if unlabeled." }, "item_count": { "type": "integer", "title": "Item Count", "description": "Articles in the cluster." }, "latest_published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest Published At", "description": "Newest publication time in the cluster." }, "items": { "items": { "$ref": "#/components/schemas/StoryItemMember" }, "type": "array", "title": "Items", "description": "Your articles from the cluster, newest first." } }, "type": "object", "required": [ "item_count" ], "title": "StoryResponse", "description": "A cluster of articles covering the same event." }, "StoryItemMember": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "title": { "type": "string", "title": "Title", "description": "Article title." }, "feeds": { "items": { "$ref": "#/components/schemas/ItemFeedList" }, "type": "array", "title": "Feeds", "description": "Subscription(s) the article was received through." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Published At", "description": "Publisher's original publication time." }, "is_read": { "type": "boolean", "title": "Is Read", "description": "Read state for the current user.", "default": false }, "media_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Media Url", "description": "Enclosure URL attached to the article, if any." }, "ai_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ai Summary", "description": "AI summary; null unless summaries are enabled." } }, "type": "object", "required": [ "id", "title" ], "title": "StoryItemMember", "description": "Your copy of one article inside a story cluster." }, "PaginatedResponse_SubscriptionListResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SubscriptionListResponse" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "PaginatedResponse[SubscriptionListResponse]" }, "SubscriptionListResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription id." }, "source_type": { "type": "string", "enum": [ "feed", "newsletter", "podcast" ], "title": "Source Type", "description": "RSS/Atom feed, newsletter address, or podcast." }, "title": { "type": "string", "title": "Title", "description": "Your display title for the subscription." }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Items not yet read.", "default": 0 }, "status": { "type": "string", "enum": [ "healthy", "error", "stale", "broken" ], "title": "Status", "description": "Fetch health: healthy; error (last fetch failed); stale (no successful fetch within the expected cadence); broken (3+ consecutive failures, refresh paused).", "default": "healthy" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Publisher website." }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of the sidebar.", "default": false }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Paused subscriptions stop fetching new content.", "default": true }, "newsletter_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Newsletter Address", "description": "Inbound email address (newsletters only); send newsletters here." }, "podcast_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Podcast Id", "description": "Catalog podcast id (podcasts only)." }, "artist": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artist", "description": "Podcast artist/publisher (podcasts only)." }, "playback_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Playback Speed", "description": "Per-subscription playback speed override (podcasts only); null = use your global default." }, "history_capped": { "type": "boolean", "title": "History Capped", "description": "Older articles exist but your tier's history window hides them; a higher tier would reveal more.", "default": false } }, "type": "object", "required": [ "id", "source_type", "title" ], "title": "SubscriptionListResponse", "description": "Subscription shape returned by list endpoints." }, "SubscriptionCreateRequest": { "properties": { "url": { "type": "string", "pattern": "^https?://", "title": "Url", "description": "Feed URL to subscribe to. Unknown feeds are fetched and created synchronously." }, "title": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Title", "description": "Optional display title override; defaults to the feed's own title." }, "folder_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Folder Id", "description": "Folder to place the subscription in." } }, "type": "object", "required": [ "url" ], "title": "SubscriptionCreateRequest", "description": "POST '/v1/subscriptions'" }, "SubscriptionCreateResponse": { "properties": { "status": { "type": "string", "enum": [ "subscribed", "already_subscribed" ], "title": "Status", "description": "Whether a subscription was created or already existed." }, "subscription_id": { "type": "string", "format": "uuid", "title": "Subscription Id", "description": "The subscription's id." }, "title": { "type": "string", "title": "Title", "description": "Resolved display title." } }, "type": "object", "required": [ "status", "subscription_id", "title" ], "title": "SubscriptionCreateResponse" }, "BulkUpdateSubscriptionsRequest": { "properties": { "subscription_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Subscription Ids", "description": "Subscriptions to update." }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Pause (false) or resume (true) all listed." }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Pinned", "description": "Set pinned state on all listed." }, "folder_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "string" }, { "type": "null" } ], "title": "Folder Id", "description": "Move all listed into this folder; send an empty string to unassign." } }, "type": "object", "required": [ "subscription_ids" ], "title": "BulkUpdateSubscriptionsRequest", "description": "PATCH '/v1/subscriptions'." }, "BulkDeleteSubscriptionsRequest": { "properties": { "subscription_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Subscription Ids", "description": "Subscriptions to remove." } }, "type": "object", "required": [ "subscription_ids" ], "title": "BulkDeleteSubscriptionsRequest", "description": "DELETE '/v1/subscriptions'." }, "SubscriptionCheckResponse": { "properties": { "feed": { "type": "boolean", "title": "Feed", "description": "Whether any feed is subscribed.", "default": false }, "podcast": { "type": "boolean", "title": "Podcast", "description": "Whether any podcast is subscribed.", "default": false } }, "type": "object", "title": "SubscriptionCheckResponse", "description": "GET '/v1/subscriptions/check'." }, "SubscriptionResponse": { "properties": { "source_type": { "type": "string", "enum": [ "feed", "newsletter", "podcast" ], "title": "Source Type", "description": "RSS/Atom feed, newsletter address, or podcast." }, "title": { "type": "string", "title": "Title", "description": "Your display title for the subscription." }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Items not yet read.", "default": 0 }, "status": { "type": "string", "enum": [ "healthy", "error", "stale", "broken" ], "title": "Status", "description": "Fetch health: healthy; error (last fetch failed); stale (no successful fetch within the expected cadence); broken (3+ consecutive failures, refresh paused).", "default": "healthy" }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Publisher website." }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of the sidebar.", "default": false }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Paused subscriptions stop fetching new content.", "default": true }, "folder_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Folder Id", "description": "Folder the subscription is in." }, "folder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Folder Name", "description": "Name of that folder." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Feed-declared language code." }, "last_update": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Update", "description": "Most recent successful fetch or delivery." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Feed/podcast description." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Url", "description": "Canonical feed or podcast feed URL." }, "newsletter_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Newsletter Address", "description": "Inbound email address (newsletters only); send newsletters here." }, "podcast_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Podcast Id", "description": "Catalog podcast id (podcasts only)." }, "artist": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artist", "description": "Podcast artist/publisher (podcasts only)." }, "episode_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Episode Count", "description": "Episodes retained (podcasts only; newest 1000 kept)." }, "explicit": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Explicit", "description": "Podcast explicit flag (podcasts only)." }, "podcast_summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Podcast Summary", "description": "Catalog podcast summary (podcasts only)." }, "playback_speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Playback Speed", "description": "Per-subscription playback speed override (podcasts only); null = use your global default." }, "history_capped": { "type": "boolean", "title": "History Capped", "description": "Older articles exist but your tier's history window hides them; a higher tier would reveal more.", "default": false } }, "type": "object", "required": [ "source_type", "title" ], "title": "SubscriptionResponse", "description": "Full subscription detail." }, "SubscriptionUpdateRequest": { "properties": { "title": { "anyOf": [ { "type": "string", "maxLength": 256 }, { "type": "null" } ], "title": "Title", "description": "New display title." }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Pinned", "description": "Set pinned state." }, "folder_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Folder Id", "description": "Move to this folder; null removes it from any folder." }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Pause (false) or resume (true) the subscription." }, "playback_speed": { "anyOf": [ { "type": "number", "maximum": 3, "minimum": 0.5 }, { "type": "null" } ], "title": "Playback Speed", "description": "Playback speed override (podcasts only)." } }, "type": "object", "title": "SubscriptionUpdateRequest", "description": "PATCH '/v1/subscriptions/{subscription_id}'" }, "NewsletterCreateRequest": { "properties": { "title": { "type": "string", "maxLength": 256, "minLength": 1, "title": "Title", "description": "Display title for the newsletter." }, "folder_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Folder Id", "description": "Folder to place the subscription in." } }, "type": "object", "required": [ "title" ], "title": "NewsletterCreateRequest", "description": "POST '/v1/subscriptions/newsletters'" }, "NewsletterCreateResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription id." }, "newsletter_address": { "type": "string", "title": "Newsletter Address", "description": "Reserved inbound address; newsletters sent here appear as items." }, "title": { "type": "string", "title": "Title", "description": "Display title." } }, "type": "object", "required": [ "id", "newsletter_address", "title" ], "title": "NewsletterCreateResponse", "description": "The newly reserved newsletter address." }, "PaginatedResponse_FolderListResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FolderListResponse" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "PaginatedResponse[FolderListResponse]" }, "FolderListResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent folder; null = root." }, "subscription_count": { "type": "integer", "title": "Subscription Count", "description": "Direct subscriptions in this folder.", "default": 0 }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Unread items across this folder's subscriptions.", "default": 0 }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of its level.", "default": false }, "depth": { "type": "integer", "maximum": 9, "minimum": 0, "title": "Depth", "description": "Nesting level; 0 = root.", "default": 0 } }, "type": "object", "required": [ "id", "name" ], "title": "FolderListResponse", "description": "Folder shape returned by list endpoints." }, "FolderCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Name", "description": "Folder name." }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent folder; omit or null for a root folder." } }, "type": "object", "required": [ "name" ], "title": "FolderCreateRequest", "description": "POST '/v1/folders'." }, "BulkUpdateFoldersRequest": { "properties": { "folder_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Folder Ids", "description": "Folders to update." }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Pinned", "description": "Set pinned state on all listed." }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Move all listed under this folder; null moves them to root." } }, "type": "object", "required": [ "folder_ids" ], "title": "BulkUpdateFoldersRequest", "description": "PATCH '/v1/folders'." }, "BulkDeleteFoldersRequest": { "properties": { "folder_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Folder Ids", "description": "Folders to delete." } }, "type": "object", "required": [ "folder_ids" ], "title": "BulkDeleteFoldersRequest", "description": "DELETE '/v1/folders'." }, "FolderResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Folder name." }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Parent folder; null = root." }, "subscription_count": { "type": "integer", "title": "Subscription Count", "description": "Direct subscriptions in this folder.", "default": 0 }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Unread items across this folder's subscriptions.", "default": 0 }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of its level.", "default": false }, "depth": { "type": "integer", "maximum": 9, "minimum": 0, "title": "Depth", "description": "Nesting level; 0 = root.", "default": 0 } }, "type": "object", "required": [ "id", "name" ], "title": "FolderResponse", "description": "Full folder detail." }, "FolderUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New name." }, "parent_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Parent Id", "description": "Move under this folder; null moves the folder to root." }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Pinned", "description": "Set pinned state." } }, "type": "object", "title": "FolderUpdateRequest", "description": "PATCH '/v1/folders/{folder_id}'." }, "FolderSubscriptionsBulkUpdateRequest": { "properties": { "is_active": { "type": "boolean", "title": "Is Active", "description": "Pause (false) or resume (true) every subscription in the folder." } }, "type": "object", "required": [ "is_active" ], "title": "FolderSubscriptionsBulkUpdateRequest", "description": "PUT '/v1/folders/{folder_id}/subscriptions'." }, "PaginatedResponse_TagListResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TagListResponse" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "PaginatedResponse[TagListResponse]" }, "TagCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Name", "description": "Tag name." } }, "type": "object", "required": [ "name" ], "title": "TagCreateRequest", "description": "POST '/v1/tags'." }, "BulkDeleteTagsRequest": { "properties": { "tag_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Tag Ids", "description": "Tags to delete." } }, "type": "object", "required": [ "tag_ids" ], "title": "BulkDeleteTagsRequest", "description": "POST '/v1/tags/bulk-delete'." }, "TagUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New name." } }, "type": "object", "title": "TagUpdateRequest", "description": "PATCH '/v1/tags/{tag_id}'." }, "UnifiedSearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UnifiedSearchHit" }, "type": "array", "title": "Data", "description": "Results (unpaginated)." } }, "type": "object", "required": [ "data" ], "title": "UnifiedSearchResponse" }, "UnifiedSearchHit": { "properties": { "type": { "type": "string", "enum": [ "article", "episode", "feed", "tag", "folder", "saved_search" ], "title": "Type", "description": "Which entity this hit is; article/episode carry ItemSearchHit, feed FeedSearchHit, tag TagSearchHit, folder FolderSearchHit, saved_search SavedSearchSearchHit." }, "data": { "anyOf": [ { "$ref": "#/components/schemas/ItemSearchHit" }, { "$ref": "#/components/schemas/FeedSearchHit" }, { "$ref": "#/components/schemas/TagSearchHit" }, { "$ref": "#/components/schemas/FolderSearchHit" }, { "$ref": "#/components/schemas/SavedSearchSearchHit" } ], "title": "Data", "description": "The hit itself; shape follows `type`." } }, "type": "object", "required": [ "type", "data" ], "title": "UnifiedSearchHit", "description": "One result from unified search; `type` selects the `data` shape." }, "FeedSearchHit": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription id." }, "source_type": { "type": "string", "enum": [ "feed", "newsletter", "podcast" ], "title": "Source Type", "description": "RSS/Atom feed, newsletter address, or podcast." }, "title": { "type": "string", "title": "Title", "description": "Your display title." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website", "description": "Publisher website." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "False when paused.", "default": true }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of the sidebar.", "default": false }, "newsletter_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Newsletter Address", "description": "Inbound email address (newsletters only); send newsletters here." }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Items not yet read.", "default": 0 }, "podcast_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Podcast Id", "description": "Catalog podcast id (podcasts only)." }, "artist": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Artist", "description": "Podcast artist/publisher (podcasts only)." } }, "type": "object", "required": [ "id", "source_type", "title" ], "title": "FeedSearchHit", "description": "A subscription returned by feed search." }, "TagSearchHit": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Tag id." }, "name": { "type": "string", "title": "Name", "description": "Tag name." }, "item_count": { "type": "integer", "title": "Item Count", "description": "Items carrying this tag.", "default": 0 } }, "type": "object", "required": [ "id", "name" ], "title": "TagSearchHit", "description": "A tag returned by tag search." }, "FolderSearchHit": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Folder id." }, "name": { "type": "string", "title": "Name", "description": "Folder name." }, "unread_count": { "type": "integer", "title": "Unread Count", "description": "Unread items across this folder's subscriptions.", "default": 0 }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned to the top of its level.", "default": false } }, "type": "object", "required": [ "id", "name" ], "title": "FolderSearchHit", "description": "A folder returned by folder search." }, "SavedSearchSearchHit": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Saved search id." }, "name": { "type": "string", "title": "Name", "description": "Saved search name." }, "query_data": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Query Data", "description": "The saved filter set (the SavedSearchParams object)." }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned for quick access.", "default": false }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last modification time." } }, "type": "object", "required": [ "id", "name", "updated_at" ], "title": "SavedSearchSearchHit", "description": "A saved search returned by saved-search search." }, "FeedSearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FeedSearchHit" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "FeedSearchResponse" }, "FolderSearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/FolderSearchHit" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "FolderSearchResponse" }, "TagSearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TagSearchHit" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "TagSearchResponse" }, "SavedSearchSearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SavedSearchSearchHit" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "SavedSearchSearchResponse" }, "PaginatedResponse_SavedSearchResponse_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SavedSearchResponse" }, "type": "array", "title": "Data", "description": "Page of results." }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata", "description": "Paging info." } }, "type": "object", "required": [ "data", "pagination" ], "title": "PaginatedResponse[SavedSearchResponse]" }, "SavedSearchResponse": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id" }, "name": { "type": "string", "title": "Name", "description": "Saved search name." }, "query_data": { "additionalProperties": true, "type": "object", "title": "Query Data", "description": "The saved filter set (the SavedSearchParams object)." }, "is_pinned": { "type": "boolean", "title": "Is Pinned", "description": "Pinned for quick access.", "default": false }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "Last modification time." } }, "type": "object", "required": [ "id", "name", "query_data", "updated_at" ], "title": "SavedSearchResponse", "description": "A saved search." }, "SavedSearchCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Name", "description": "Saved search name." }, "query_data": { "$ref": "#/components/schemas/SavedSearchParams", "description": "Filters to save and replay." } }, "type": "object", "required": [ "name", "query_data" ], "title": "SavedSearchCreateRequest", "description": "POST /v1/saved-searches." }, "SavedSearchParams": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Full-text query." }, "include_global": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Global", "description": "Plus: append global corpus matches after the library's (requires a query)." }, "subscription_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Subscription Ids", "description": "Limit to these subscriptions." }, "is_read": { "anyOf": [ { "type": "string", "pattern": "^(read|unread)$" }, { "type": "null" } ], "title": "Is Read", "description": "Limit to this read state." }, "tag_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Tag Ids", "description": "Limit to these tags." }, "folder_ids": { "anyOf": [ { "items": { "type": "string", "format": "uuid" }, "type": "array" }, { "type": "null" } ], "title": "Folder Ids", "description": "Limit to these folders." }, "is_saved": { "anyOf": [ { "type": "string", "pattern": "^(true|false)$" }, { "type": "null" } ], "title": "Is Saved", "description": "Limit to this saved state." }, "from_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "From Date", "description": "Items published on or after this date." }, "to_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "To Date", "description": "Items published on or before this date." }, "subscription_options": { "anyOf": [ { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Subscription Options", "description": "Display metadata (label/value pairs) captured by the UI when the search was saved; not applied as a filter." }, "tag_options": { "anyOf": [ { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Tag Options", "description": "Display metadata for the chosen tags; not a filter." }, "folder_options": { "anyOf": [ { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Folder Options", "description": "Display metadata for the chosen folders; not a filter." } }, "type": "object", "title": "SavedSearchParams", "description": "The filter set a saved search replays." }, "BulkDeleteSavedSearchesRequest": { "properties": { "search_ids": { "items": { "type": "string", "format": "uuid" }, "type": "array", "maxItems": 20, "minItems": 1, "title": "Search Ids", "description": "Saved searches to delete." } }, "type": "object", "required": [ "search_ids" ], "title": "BulkDeleteSavedSearchesRequest", "description": "POST /v1/saved-searches/bulk-delete." }, "SavedSearchUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New name." }, "query_data": { "anyOf": [ { "$ref": "#/components/schemas/SavedSearchParams" }, { "type": "null" } ], "description": "Replaces the saved filter set when provided." }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Pinned", "description": "Set pinned state." } }, "type": "object", "title": "SavedSearchUpdateRequest", "description": "PATCH /v1/saved-searches/{search_id}." } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "glanced_live_…", "description": "API key (glanced_live_…). Required on operations marked with this scheme; rejected elsewhere." } } }, "tags": [ { "name": "Items", "description": "Read and manage items with bulk actions, read state, playback progress, and similar items." }, { "name": "Stories", "description": "List stories, ranked groups of articles collected by Glanced." }, { "name": "Subscriptions", "description": "Add, list, update, and unsubscribe from feed and newsletter subscriptions." }, { "name": "Folders", "description": "Organize subscriptions into folders with full create, read, update, and delete operations." }, { "name": "Tags", "description": "Create, list, update, and delete tags used to organize subscriptions." }, { "name": "Search", "description": "Search items, feeds, tags, folders, and saved searches." }, { "name": "Saved Searches", "description": "Create and manage saved searches that run against your items and feeds." } ] }