{ "openapi": "3.1.0", "info": { "title": "Sparkfeed API", "version": "1.0.0", "description": "Read and manage a Sparkfeed workspace: folders, feeds and articles. The same capabilities are available over MCP at /api/mcp — both are generated from one definition, so they never disagree." }, "servers": [ { "url": "https://demo.sparkfeed.dev/api/v1", "description": "This deployment" }, { "url": "https://demo.sparkfeed.dev/api/v1", "description": "Public demo workspace, read-only" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from Developer → API Keys, sent as `Authorization: Bearer sfk_live_…`. The public demo key `sfk_demo_public` works against the demo server and is read-only." } } }, "tags": [ { "name": "Workspace" }, { "name": "Folders" }, { "name": "Feeds" }, { "name": "Articles" }, { "name": "Discover" }, { "name": "Read" }, { "name": "Charts" } ], "paths": { "/workspace": { "get": { "operationId": "get_workspace_info", "summary": "Get workspace info", "description": "Overview of the whole workspace: how many folders, feeds and articles there are, how much is unread, which folders and feeds are busiest, and which feeds are failing. Call this first for any question about the size, shape or health of the workspace — it answers \"how many feeds do I have\" completely, so no follow-up calls are needed.", "tags": [ "Workspace" ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "Get workspace info", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true } }, "/folders": { "get": { "operationId": "list_folders", "summary": "List folders", "description": "Every folder, with its parent folder, feed count and unread count. Use this to describe how the workspace is organised, or to find a folder id before filtering or writing. Cheap; returns no article content.", "tags": [ "Folders" ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "List folders", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true }, "post": { "operationId": "create_folder", "summary": "Create folder", "description": "Create a folder, optionally nested inside an existing one.", "tags": [ "Folders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "parent_id": { "description": "Nest inside this folder, e.g. \"fld_abc123\".", "type": "string" } }, "required": [ "name" ] } } } }, "security": [ { "bearerAuth": [ "feeds:write" ] } ], "responses": { "200": { "description": "Create folder", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"feeds:write\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "feeds:write", "x-read-only": false } }, "/feeds": { "get": { "operationId": "list_feeds", "summary": "List feeds", "description": "Feed sources with their folder, recent volume, unread count, last fetch time and last error. Includes both RSS feeds and scraped sites. Use it to answer \"what am I subscribed to\" or to find a feed id.", "tags": [ "Feeds" ], "parameters": [ { "name": "folder_id", "in": "query", "required": false, "description": "Restrict to one folder, e.g. \"fld_abc123\".", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 100, max 200.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "List feeds", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true }, "post": { "operationId": "add_feed", "summary": "Add feed", "description": "Subscribe to a feed and import its recent articles. Accepts a feed URL or a site homepage — the feed is resolved either way. Confirm the source with the user first unless they named it explicitly.", "tags": [ "Feeds" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Feed URL or site homepage." }, "folder_id": { "description": "Folder to file it under, e.g. \"fld_abc123\".", "type": "string" }, "name": { "description": "Override the feed title.", "type": "string" }, "allow_scrape": { "description": "Allow a verified Website source when no native feed exists.", "type": "boolean" } }, "required": [ "url" ] } } } }, "security": [ { "bearerAuth": [ "feeds:write" ] } ], "responses": { "200": { "description": "Add feed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"feeds:write\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "feeds:write", "x-read-only": false } }, "/articles": { "get": { "operationId": "search_articles", "summary": "Search articles", "description": "Search the workspace, or omit `query` to get the most recent articles — which is the right call for \"what is new in X\". Also the way to list one feed's latest items: pass feed_id. Returns titles, sources, dates and a short snippet only; use get_article for the full text of one piece.", "tags": [ "Articles" ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Free-text search over title and summary.", "schema": { "type": "string" } }, { "name": "folder_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "feed_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO date, or relative like \"7d\" or \"24h\".", "schema": { "type": "string" } }, { "name": "until", "in": "query", "required": false, "description": "ISO date, or relative like \"7d\".", "schema": { "type": "string" } }, { "name": "favorites_only", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "unread_only", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 20, max 50.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from a previous call.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "articles:read" ] } ], "responses": { "200": { "description": "Search articles", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"articles:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "articles:read", "x-read-only": true } }, "/articles/{id}": { "get": { "operationId": "get_article", "summary": "Get article", "description": "The full text of one article, as markdown by default. The only way to read a whole post, and deliberately one article per call. Served from cache when available, otherwise fetched and extracted on demand. Use this before summarising or quoting.", "tags": [ "Articles" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Article id from search_articles, e.g. \"art_abc123\".", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "markdown", "text", "html" ] } }, { "name": "max_chars", "in": "query", "required": false, "description": "Default 50000, max 80000.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "offset", "in": "query", "required": false, "description": "Continue a long article from here.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "security": [ { "bearerAuth": [ "articles:read" ] } ], "responses": { "200": { "description": "Get article", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"articles:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "articles:read", "x-read-only": true } }, "/discover": { "get": { "operationId": "find_feeds", "summary": "Find feeds", "description": "Find RSS feeds the workspace does not have yet. Give a `topic` to search a curated catalogue of quality sources, or a `url` to scan a specific site for its feeds. Returns sample headlines so the user can judge a source before subscribing, and marks anything already subscribed. Use this before add_feed.", "tags": [ "Discover" ], "parameters": [ { "name": "topic", "in": "query", "required": false, "description": "What to look for, e.g. \"climate tech\".", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "A site to scan, e.g. \"https://theverge.com\".", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 8, max 20.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "Find feeds", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true } }, "/discover/verify": { "get": { "operationId": "verify_feed", "summary": "Verify a feed URL", "description": "Check one address and report whether it is really an RSS or Atom feed, by fetching and parsing it. Returns the feed's title, how many items it carries, its posting rate, when it last published, its latest headlines, and whether this workspace already subscribes. Use this when the user pastes a URL, or before recommending a feed you have not seen — `find_feeds` searches for candidates, this one confirms a specific address. A URL that is not a feed comes back with `valid: false` and a reason, which is an answer, not a failure: say so plainly and suggest what to try instead.", "tags": [ "Discover" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The address to check, e.g. \"https://bair.berkeley.edu/blog/feed.xml\". A homepage works too.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "Verify a feed URL", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true } }, "/read": { "get": { "operationId": "read_url", "summary": "Read a web page", "description": "Fetch a public web page and read its main article text. Use this when the user pastes a link, or asks about a specific page that is not in their feeds. For an article that IS in the workspace, use `get_article` with its id instead — that one reuses cached text and does not refetch. A page that cannot be extracted (a paywall, a login, an app shell) comes back with `source_quality: \"failed\"` and no content: say you could not read it rather than guessing at what it said.", "tags": [ "Read" ], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "The page to read, e.g. https://example.com/some-article.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "articles:read" ] } ], "responses": { "200": { "description": "Read a web page", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"articles:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "articles:read", "x-read-only": true } }, "/charts": { "get": { "operationId": "chart_workspace", "summary": "Chart the workspace", "description": "Draw one of four charts of the user's reading, as a card they can file into a report: `articles_over_time` (daily volume), `posting_cadence` (which day of the week is busiest), `unread_by_folder` (where the backlog is), `top_sources` (which feeds post most). The result carries a one-line summary — say that, and let the chart show the shape. Do not describe every bar; the user can see them.", "tags": [ "Charts" ], "parameters": [ { "name": "metric", "in": "query", "required": true, "description": "Which chart. Pick the one that answers the question asked.", "schema": { "type": "string", "enum": [ "articles_over_time", "unread_by_folder", "top_sources", "posting_cadence" ] } }, { "name": "days", "in": "query", "required": false, "description": "History for the time-based metrics. Default 30, max 365.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "description": "Bars to show for the rankings. Default 8, max 20.", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "security": [ { "bearerAuth": [ "workspace:read" ] } ], "responses": { "200": { "description": "Chart the workspace", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"workspace:read\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "workspace:read", "x-read-only": true } }, "/feeds/{feed_id}": { "patch": { "operationId": "move_feed", "summary": "Move feed", "description": "Move a feed into a different folder. Pass folder_id as null to move it to the top level.", "tags": [ "Feeds" ], "parameters": [ { "name": "feed_id", "in": "path", "required": true, "description": "Feed id, e.g. \"fed_abc123\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Destination folder, or null for top level." } }, "required": [ "folder_id" ] } } } }, "security": [ { "bearerAuth": [ "feeds:write" ] } ], "responses": { "200": { "description": "Move feed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"feeds:write\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "feeds:write", "x-read-only": false } }, "/articles/read": { "post": { "operationId": "mark_read", "summary": "Mark read", "description": "Mark articles read or unread. Accepts up to 100 ids so a triage pass is one call. Note read state is shared across the whole workspace, so this affects every member.", "tags": [ "Articles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "article_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Article ids from search_articles, e.g. [\"art_abc123\"]." }, "state": { "type": "boolean" } }, "required": [ "article_ids", "state" ] } } } }, "security": [ { "bearerAuth": [ "articles:write" ] } ], "responses": { "200": { "description": "Mark read", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"articles:write\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "articles:write", "x-read-only": false } }, "/articles/favorite": { "post": { "operationId": "set_favorite", "summary": "Set favorite", "description": "Mark or unmark articles as favourites. Accepts up to 100 ids.", "tags": [ "Articles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "article_ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Article ids from search_articles, e.g. [\"art_abc123\"]." }, "state": { "type": "boolean" } }, "required": [ "article_ids", "state" ] } } } }, "security": [ { "bearerAuth": [ "articles:write" ] } ], "responses": { "200": { "description": "Set favorite", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid or missing parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the \"articles:write\" scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit exceeded. See Retry-After.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "x-scope": "articles:write", "x-read-only": false } } } }