{ "openapi": "3.1.0", "info": { "title": "MarketNewsAPI API", "version": "1.0.0", "summary": "Real-time US stock news, press releases, and legal notices, with AI summaries and entities.", "description": "REST API for MarketNewsAPI. A WebSocket stream is available at wss://ws.marketnewsapi.com/v1/stream and an MCP server at https://mcp.marketnewsapi.com/mcp (Pro). Free plan: 100 requests/day, 15-minute delay, 1 year of history. Pro: unlimited requests, the full archive, 20 req/s burst cap.", "termsOfService": "https://marketnewsapi.com/legal/terms", "contact": { "name": "MarketNewsAPI support", "email": "support@marketnewsapi.com", "url": "https://marketnewsapi.com/contact" } }, "externalDocs": { "description": "Documentation", "url": "https://marketnewsapi.com/docs" }, "servers": [ { "url": "https://api.marketnewsapi.com/v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "apiKeyQuery": [] } ], "paths": { "/news": { "get": { "operationId": "listNews", "summary": "List news", "description": "Search and filter stock news, press releases and legal notices, newest first. Returns articles matching every filter you pass. Filters combine with AND, and comma-separated values inside one filter are OR. Without filters you get the latest stock articles. Use cursor to page through results.", "externalDocs": { "url": "https://marketnewsapi.com/docs/news" }, "parameters": [ { "name": "tickers", "in": "query", "required": false, "description": "Comma-separated symbols, up to 50. Matches articles tagged with any of them, on every exchange. MRVL returns both the US stock and TSXV:MRVL.", "schema": { "type": "string" }, "example": "AAPL,MSFT" }, { "name": "exchange", "in": "query", "required": false, "description": "Comma-separated exchange codes, such as NASDAQ or TSXV. With tickers, only those symbols on those exchanges match. Alone, any article with a listing on one of the exchanges.", "schema": { "type": "string" }, "example": "TSXV" }, { "name": "category", "in": "query", "required": false, "description": "One or more categories, comma-separated.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "One or more of news, press_release, legal. Stock news is category=stocks&type=news. Press releases are category=stocks&type=press_release. Legal is category=stocks&type=legal. stock_news and stockNews mean stock news only. pressRelease means press_release and implies category=stocks.", "schema": { "type": "string", "enum": [ "news", "press_release", "legal" ] } }, { "name": "q", "in": "query", "required": false, "description": "Full-text search over title, summary and snippet. Use quotes for phrases: \"rate cut\". Max 200 characters.", "schema": { "type": "string" }, "example": "\"rate cut\"" }, { "name": "sources", "in": "query", "required": false, "description": "Only these publisher domains, comma-separated.", "schema": { "type": "string" }, "example": "globenewswire.com,businesswire.com" }, { "name": "exclude_sources", "in": "query", "required": false, "description": "Drop these publisher domains, comma-separated.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Earliest published_at (inclusive). ISO 8601 timestamp (2026-10-06T13:30:00Z) or date (2026-10-06). Dates are interpreted in UTC.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Latest published_at (inclusive). ISO 8601 timestamp (2026-10-06T13:30:00Z) or date (2026-10-06). Dates are interpreted in UTC.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Result order. relevance only applies when q is set.", "schema": { "type": "string", "enum": [ "published_desc", "published_asc", "relevance" ], "default": "published_desc" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1–100.", "schema": { "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from meta.next_cursor of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "example": { "data": [ { "id": "art_9f2c1d7e4b8a6035", "title": "Apple unveils new on-device AI features, shares rise in premarket trading", "url": "https://www.example-publisher.com/markets/apple-ai-features", "source": { "name": "Example Publisher", "domain": "example-publisher.com" }, "publisher": "Example Publisher", "published_at": "2026-10-06T12:31:04Z", "ingested_at": "2026-10-06T12:31:09Z", "category": "stocks", "type": "news", "tickers": [ "AAPL" ], "listings": [ { "symbol": "AAPL", "exchange": "NASDAQ" } ], "snippet": "Apple on Tuesday introduced a set of on-device AI features for iPhone and Mac, sending the stock higher before the open.", "summary": "Apple announced new on-device AI features for iPhone and Mac. Shares rose about 2% in premarket trading as analysts called the update a catalyst for the upgrade cycle.", "body": null, "entities": [ { "type": "company", "name": "Apple Inc.", "symbol": "AAPL" }, { "type": "product", "name": "iPhone" } ], "language": "en" } ], "meta": { "count": 1, "next_cursor": "eyJ0IjoxNzU5NzUzODY0MDAwLCJpIjoiYXJ0XzlmMmMxZDdlNGI4YTYwMzUifQ", "plan": "stream", "delayed_minutes": 0 } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/news/{id}": { "get": { "operationId": "getArticle", "summary": "Get an article", "description": "Fetch one article by id, including the latest enrichment. Useful when you stored an id from the stream and want the full record later, or to re-read an article after its AI summary is filled in.", "externalDocs": { "url": "https://marketnewsapi.com/docs/article" }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Article id, e.g. art_9f2c1d7e4b8a6035.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Article" } } }, "example": { "data": { "id": "art_9f2c1d7e4b8a6035", "title": "Apple unveils new on-device AI features, shares rise in premarket trading", "url": "https://www.example-publisher.com/markets/apple-ai-features", "source": { "name": "Example Publisher", "domain": "example-publisher.com" }, "publisher": "Example Publisher", "published_at": "2026-10-06T12:31:04Z", "ingested_at": "2026-10-06T12:31:09Z", "category": "stocks", "type": "news", "tickers": [ "AAPL" ], "listings": [ { "symbol": "AAPL", "exchange": "NASDAQ" } ], "snippet": "Apple on Tuesday introduced a set of on-device AI features for iPhone and Mac, sending the stock higher before the open.", "summary": "Apple announced new on-device AI features for iPhone and Mac. Shares rose about 2% in premarket trading as analysts called the update a catalyst for the upgrade cycle.", "body": null, "entities": [ { "type": "company", "name": "Apple Inc.", "symbol": "AAPL" }, { "type": "product", "name": "iPhone" } ], "language": "en" } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/trending": { "get": { "operationId": "getTrending", "summary": "Trending symbols", "description": "The stock tickers with the most coverage right now. Ranks symbols by article count in the chosen window. Great for a \"most talked about\" widget, a screener input, or detecting unusual news volume.", "externalDocs": { "url": "https://marketnewsapi.com/docs/trending" }, "parameters": [ { "name": "window", "in": "query", "required": false, "description": "Look-back window.", "schema": { "type": "string", "enum": [ "1h", "24h", "7d" ], "default": "24h" } }, { "name": "kind", "in": "query", "required": false, "description": "Stock tickers.", "schema": { "type": "string", "enum": [ "ticker" ], "default": "ticker" } }, { "name": "category", "in": "query", "required": false, "description": "Only count articles in this category.", "schema": { "type": "string", "enum": [ "stocks" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Number of symbols, 1–50.", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "symbol": "NVDA", "kind": "ticker", "articles": 142 }, { "symbol": "AAPL", "kind": "ticker", "articles": 118 }, { "symbol": "TSLA", "kind": "ticker", "articles": 97 } ], "meta": { "window": "24h", "category": null } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/sources": { "get": { "operationId": "listSources", "summary": "List sources", "description": "Every publisher and wire service in the feed, with 30-day volume. Use the returned domain values with the sources and exclude_sources filters.", "externalDocs": { "url": "https://marketnewsapi.com/docs/sources" }, "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Only sources that published in this category.", "schema": { "type": "string", "enum": [ "stocks" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only sources of this article type.", "schema": { "type": "string", "enum": [ "news", "press_release", "legal" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "name": "GlobeNewswire", "domain": "globenewswire.com", "categories": [ "stocks" ], "types": [ "press_release" ], "articles_30d": 18432 }, { "name": "Business Wire", "domain": "businesswire.com", "categories": [ "stocks" ], "types": [ "press_release" ], "articles_30d": 15207 }, { "name": "Example Publisher", "domain": "example-publisher.com", "categories": [ "stocks" ], "types": [ "news" ], "articles_30d": 2310 } ], "meta": { "count": 3 } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/tickers": { "get": { "operationId": "listTickers", "summary": "List tickers", "description": "Every ticker tagged on at least one article. Use a returned symbol with the tickers filter, or subscribe to ticker:{symbol} on the WebSocket. A symbol appears once it has been tagged on an article, including the archive. articles is the total. by_type splits that total into news, press_release, and legal. Optional filters limit the list, and the counts, to tickers that have an article of that category or type.", "externalDocs": { "url": "https://marketnewsapi.com/docs/tickers" }, "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Only tickers tagged on an article in this category.", "schema": { "type": "string", "enum": [ "stocks" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only tickers tagged on an article of this type.", "schema": { "type": "string", "enum": [ "news", "press_release", "legal" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "symbol": "AAPL", "articles": 640, "by_type": { "news": 410, "press_release": 168, "legal": 62 } }, { "symbol": "MSFT", "articles": 512, "by_type": { "news": 301, "press_release": 154, "legal": 57 } }, { "symbol": "NVDA", "articles": 870, "by_type": { "news": 540, "press_release": 220, "legal": 110 } } ], "meta": { "count": 3 } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Usage", "description": "Your plan, today's request count and WebSocket allowance. Calls to /usage don't count toward the Free plan's daily limit, so you can poll it safely.", "externalDocs": { "url": "https://marketnewsapi.com/docs/usage" }, "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "plan": "free", "period": "2026-10-06", "requests_today": 37, "daily_limit": 100, "remaining_today": 63, "burst_limit_per_second": 20, "websocket": { "allowed": false, "max_connections": 0, "open_connections": 0 } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "Status", "description": "Public health check with the latest ingestion time per category. No API key needed. Returns operational, degraded or down for the REST API, the WebSocket stream and ingestion, plus the newest published_at per category. latest_article is the newest stock article, with the ticker, type, headline, source and time the status page shows. archive is the stock-article count published in the last year, split into news, press_release and legal. This is what powers the status page and the totals on coverage.", "externalDocs": { "url": "https://marketnewsapi.com/docs/status-endpoint" }, "security": [], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "operational", "time": "2026-10-06T12:31:15Z", "components": { "rest": "operational", "websocket": "operational", "mcp": "operational", "ingestion": "operational" }, "latest": { "stocks": "2026-10-06T12:31:04Z" }, "latest_article": { "id": "art_9f2c1d7e4b8a6035", "title": "Apple unveils new on-device AI features, shares rise in premarket trading", "url": "https://www.example-publisher.com/markets/apple-ai-features", "published_at": "2026-10-06T12:31:04Z", "type": "news", "tickers": [ "AAPL" ], "listings": [ { "symbol": "AAPL", "exchange": "NASDAQ" } ], "source": { "name": "Example Publisher", "domain": "example-publisher.com" } }, "articles_24h": 17240, "articles_24h_by_category": { "stocks": 17240 }, "archive": { "since": "2025-10-06", "total": 4128831, "by_type": { "news": 2411020, "press_release": 1394406, "legal": 323405 } } } } } }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer mna-live-..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" } }, "schemas": { "Article": { "type": "object", "required": [ "id", "title", "url", "source", "published_at", "category", "type", "tickers" ], "properties": { "id": { "type": "string", "example": "art_9f2c1d7e4b8a6035" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } } }, "published_at": { "type": "string", "format": "date-time" }, "ingested_at": { "type": "string", "format": "date-time" }, "category": { "type": "string", "enum": [ "stocks" ] }, "type": { "type": "string", "enum": [ "news", "press_release", "legal" ], "description": "news (stock news when category is stocks), press_release, or legal. Same three-way split as Vantafin." }, "tickers": { "type": "array", "items": { "type": "string" } }, "snippet": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ], "description": "Full text, press releases only." }, "entities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" } } } }, "language": { "type": "string" } } }, "ListMeta": { "type": "object", "properties": { "count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "plan": { "type": "string", "enum": [ "free", "pro" ] }, "delayed_minutes": { "type": "integer" }, "notice": { "type": "string" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_parameter", "missing_api_key", "invalid_api_key", "plan_required", "not_found", "daily_limit_reached", "rate_limited", "server_error", "unavailable" ] }, "message": { "type": "string" }, "status": { "type": "integer" } } } } } }, "responses": { "E400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "plan_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "daily_limit_reached, rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "server_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }