{"openapi":"3.1.0","info":{"title":"APITube News API","version":"1.0.0","summary":"Search and filter news articles from thousands of sources worldwide.","description":"APITube News API provides programmatic access to a comprehensive, real-time news database aggregated from thousands of sources worldwide. Use it to search, filter, and retrieve news articles with advanced query capabilities.\n\n## Key Endpoints\n\n- **Everything** (`/v1/news/everything`) — full-text search across all indexed articles with filters by title, date range, language, country, source, sentiment, category, topic, industry, and named entities (people, organizations, locations, brands, etc.).\n- **Top Headlines** (`/v1/news/top-headlines`) — breaking and trending news from high-authority sources ranked by OPR score.\n- **Story** (`/v1/news/story/{articleId}`) — retrieve related articles for a given story.\n- **Article** (`/v1/news/article`) — fetch one or more articles by ID.\n- **Dictionaries** — list available categories, topics, industries, and entities.\n- **Trends** — discover trending topics and entities over time.\n- **Stream** (`/v1/news/stream`) — real-time Server-Sent Events (SSE) stream of new articles.\n- **Webhooks** — subscribe to push notifications for new articles matching your filters.\n\n## Export Formats\n\nJSON (default), CSV, TSV, XML, RSS, XLSX, Parquet, JSONL, and NDJSON.\n\n## Authentication\n\nAll requests require an API key passed via the `X-API-Key` header or the `api_key` query parameter.","contact":{"name":"APITube Support","url":"https://apitube.io","email":"support@apitube.io"},"termsOfService":"https://apitube.io/terms/terms-of-service"},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key passed via X-API-Key header"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key passed as query parameter"}},"schemas":{}},"paths":{"/ping":{"get":{"summary":"Ping (Health Check)","tags":["System"],"description":"Returns \"pong\" if the server is running.","responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"description":"Server is healthy","type":"string"},"example":"pong"}}}}}},"/v1/balance":{"get":{"summary":"Get API key balance","tags":["Account"],"description":"Returns the current balance and plan information for the provided API key.","responses":{"200":{"description":"API key balance information","content":{"application/json":{"schema":{"description":"API key balance information","type":"object","properties":{"api_key":{"type":"string","description":"The API key"},"points":{"type":"integer","description":"Remaining points"},"plan":{"type":"string","description":"Subscription plan name"}}},"example":{"api_key":"ak_live_abc123...","points":48500,"plan":"professional"}}}},"400":{"description":"API key is required","content":{"application/json":{"schema":{"description":"API key is required","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"description":"Invalid API key","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/everything":{"post":{"summary":"Search all news articles","tags":["News"],"description":"Search and filter news articles from thousands of sources worldwide. Supports advanced filtering by title, date, language, source, category, topic, industry, entity, sentiment, readability, media, location, and more. Results can be exported in multiple formats (CSV, TSV, XML, RSS, XLSX, Parquet, JSONL).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/raw":{"post":{"summary":"Get raw articles (before parsing & enrichment)","tags":["News"],"description":"Returns raw articles straight from the discovery stage, before HTML parsing and NLP enrichment. This is a fast-churning staging feed (rows are continuously consumed by the pipeline and expire within ~1 day). Enrichment fields (language, categories, topics, entities, sentiment, etc.) are not available at this stage. Supports pagination, source filtering, a published date range, and basic sorting.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","description":"Page number (default 1).","example":1},"per_page":{"type":"integer","description":"Results per page (default 100, max 250; Free is capped at 10, Starter at 50, Basic at 200).","example":100},"source.id":{"type":"string","description":"Comma-separated source (sitemap) IDs (max 3).","example":"123"},"ignore.source.id":{"type":"string","description":"Comma-separated source IDs to exclude (max 3).","example":"789"},"published_at":{"type":"string","description":"Single day filter (creates a 24h range). ISO 8601 / YYYY-MM-DD / relative.","example":"2026-05-27"},"published_at.start":{"type":"string","description":"Start of the publication date range.","example":"2026-05-26"},"published_at.end":{"type":"string","description":"End of the publication date range.","example":"2026-05-27"},"sort.by":{"type":"string","enum":["id","published_at","created_at"],"description":"Sort field (default id).","example":"id"},"sort.order":{"type":"string","enum":["asc","desc"],"description":"Sort direction (default desc).","example":"desc"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want. Only PARTIALLY applied here: this endpoint understands published_at.start, published_at.end, sort.order and per_page, so anything else the prompt produced is reported in meta.prompt.ignored with reason \"unsupported_on_endpoint\". The 2-point translation fee still applies on a cache miss. Available on Basic and above — on Free and Starter the request fails with 403 ER0706."}}}}}},"responses":{"200":{"description":"Successful response with raw articles","content":{"application/json":{"schema":{"description":"Successful response with raw articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if none)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if none)"},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Raw article ID"},"title":{"type":["string","null"],"description":"Article title from RSS"},"href":{"type":["string","null"],"description":"Article URL"},"created_at":{"type":["string","null"],"description":"Publication date from RSS (may be null)"},"description":{"type":["string","null"],"description":"Short description from RSS"},"body":{"type":"string","description":"Article body with HTML stripped (plain text)"},"body_html":{"type":"string","description":"Article body as received from RSS (HTML)"},"author":{"type":["string","null"],"description":"Author from RSS"},"keywords":{"type":["array","null"],"items":{"type":"string"},"description":"Raw RSS keywords/categories"},"source":{"type":"object","description":"Source (publisher) details, resolved from the sitemap repository","properties":{"id":{"type":["integer","null"],"description":"Source (sitemap) ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source resource type"},"bias":{"type":"string","description":"Political bias (left/center/right)"},"rankings":{"type":"object","properties":{"opr":{"type":["number","null"],"description":"Open PageRank"}}},"location":{"type":"object","properties":{"country_name":{"type":"string"},"country_code":{"type":"string"}}},"favicon":{"type":"string","description":"Favicon URL"}}}}},"description":"Array of raw (unenriched) articles"}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/fact-check":{"post":{"summary":"Fact-check an article or a claim","tags":["Fact Check"],"description":"Verifies factual claims against APITube’s live news corpus (retrieval-augmented). Accepts an article `id` (loaded from the corpus), raw article `text`, or a single `claim`. Returns per-claim verdicts on an 8-level scale with calibrated confidence, an explanation, and the supporting/refuting evidence articles.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"APITube article id to fact-check. The article is loaded from the corpus and its claims are extracted and verified. Takes priority over `text` and `claim`.","example":123456789},"text":{"type":"string","description":"Raw article text (title + body), 100–10000 characters. Claims are extracted automatically.","minLength":100,"maxLength":10000},"claim":{"type":"string","description":"A single factual statement to verify directly (5–500 characters).","minLength":5,"maxLength":500,"example":"OpenAI released GPT-5 in 2024"},"max_claims":{"type":"integer","description":"Maximum number of claims to extract and verify (capped server-side).","example":5},"evidence_per_claim":{"type":"integer","description":"Maximum number of evidence articles to retrieve per claim (capped server-side).","example":5}}}}}},"responses":{"200":{"description":"Fact-check result","content":{"application/json":{"schema":{"description":"Fact-check result","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"request_id":{"type":["string","null"]},"input":{"type":"object","properties":{"type":{"type":"string","enum":["id","text","claim"]},"language":{"type":"string"}}},"summary":{"type":"object","properties":{"overall_verdict":{"type":"string","enum":["true","mostly_true","mixed","misleading","mostly_false","false","unverified","outdated"]},"overall_confidence":{"type":"number"},"claims_total":{"type":"integer"},"claims_checked":{"type":"integer"},"verdict_breakdown":{"type":"object","additionalProperties":{"type":"integer"}}}},"claims":{"type":"array","items":{"type":"object","properties":{"claim":{"type":"string"},"normalized_claim":{"type":"string"},"checkworthy":{"type":"boolean"},"verdict":{"type":"string","enum":["true","mostly_true","mixed","misleading","mostly_false","false","unverified","outdated"]},"confidence":{"type":"number","description":"Calibrated confidence in the verdict (0..1)"},"as_of":{"type":"string","description":"Date the verdict is valid as of (YYYY-MM-DD)"},"explanation":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","properties":{"article_id":{"type":"integer","description":"APITube article id of the evidence"},"title":{"type":"string"},"url":{"type":"string"},"source":{"type":"string","description":"Source domain"},"source_authority":{"type":"integer","description":"Source authority/OPR rank (higher = more authoritative)"},"published_at":{"type":["string","null"],"format":"date-time"},"snippet":{"type":"string"},"stance":{"type":"string","enum":["supports","refutes","neutral"]},"relevance":{"type":"number","description":"Relevance of the evidence to the claim (0..1)"}}}}}}}}}}}},"400":{"description":"Invalid request (no input, or out-of-range text/claim/id)","content":{"application/json":{"schema":{"description":"Invalid request (no input, or out-of-range text/claim/id)","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"402":{"description":"No points / balance on the account","content":{"application/json":{"schema":{"description":"No points / balance on the account","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"403":{"description":"Not available on the free plan, or API key lacks the fact_check scope","content":{"application/json":{"schema":{"description":"Not available on the free plan, or API key lacks the fact_check scope","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Article with the provided id was not found","content":{"application/json":{"schema":{"description":"Article with the provided id was not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"502":{"description":"Fact-check upstream temporarily unavailable","content":{"application/json":{"schema":{"description":"Fact-check upstream temporarily unavailable","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/top-headlines":{"post":{"summary":"Get top headlines","tags":["News"],"description":"Returns top headlines — breaking and important news from high-authority sources (OPR rank >= 5). Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Successful response with top headlines","content":{"application/json":{"schema":{"description":"Successful response with top headlines","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/local":{"post":{"summary":"Local news around a point","tags":["News"],"description":"Returns news articles whose mentioned locations fall within `radius` km of `lat`/`lng`, sorted by proximity. Each article is enriched with `distance_km` and `nearest_location`. Supports the same filters as `/v1/news/everything`. Optionally returns a `local_insights` dashboard (mood, hotspots, extracted events, top entities, media-bias split, top sources, timeline) via the `insights` parameter. Costs 1 point + 1 per requested insight block.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the search center (required unless `place` is given)"},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the search center (required unless `place` is given)"},"place":{"type":"string","description":"Place name to geocode into the search center instead of lat/lng (e.g. `Berlin`). Resolved heuristically against the entity graph; ambiguous names are matched to the best candidate — add `country` or pass `lat`/`lng` for precision. Explicit lat/lng take precedence over `place`.","example":"Berlin"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code to disambiguate `place` (e.g. `de`)","example":"de"},"radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"default":50,"description":"Search radius in kilometers (default 50, max 20000)"},"sort":{"type":"string","enum":["distance","published_at","relevance"],"default":"distance","description":"Sort order: nearest first (`distance`), newest first (`published_at`), or `relevance` (blends proximity + source authority + recency + breaking; adds `relevance_score` to each article)"},"ranking":{"type":"string","enum":["balanced","proximity","authority","fresh"],"default":"balanced","description":"Relevance weighting preset (only when sort=relevance): balanced, proximity (closer wins), authority (bigger sources win), fresh (recency wins). Override individual weights with w.* params."},"w.distance":{"type":"number","minimum":0,"description":"Relevance weight for proximity (overrides preset)"},"w.opr":{"type":"number","minimum":0,"description":"Relevance weight for source authority (overrides preset)"},"w.recency":{"type":"number","minimum":0,"description":"Relevance weight for recency (overrides preset)"},"w.important":{"type":"number","minimum":0,"description":"Relevance weight for breaking/importance (overrides preset)"},"insights":{"type":"string","description":"Comma-separated local intelligence blocks to compute over the radius. Values: mood, hotspots, events, entities, bias, sources, timeline, top_categories, top_topics, breaking, velocity, movers. `velocity`/`movers` use rolling time windows and are most accurate without an explicit published_at filter. Each block costs 1 additional point.","example":"top_categories,breaking,movers"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Articles near the point with optional local insights","content":{"application/json":{"schema":{"description":"Articles near the point with optional local insights","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"query":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"radius_km":{"type":"number"},"place":{"type":"string","description":"Resolved place name (only when `place` was used)"},"resolved_entity_id":{"type":["integer","null"],"description":"Entity id the place was geocoded to"}}},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":["string","null"]},"published_at":{"type":["string","null"]},"distance_km":{"type":["number","null"],"description":"Distance to the nearest location, km"},"relevance_score":{"type":["number","null"],"description":"Composite relevance (only when sort=relevance)"},"nearest_location":{"type":["object","null"],"properties":{"entity_id":{"type":["integer","null"]},"name":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"country":{"type":"string"}}}}}},"local_insights":{"type":"object","description":"Present only when `insights` is requested","properties":{"mood":{"type":"object","properties":{"avg_sentiment":{"type":["number","null"]},"distribution":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"hotspots":{"type":"array","items":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"count":{"type":"integer"}}}},"top_events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"category":{"type":["string","null"]},"count":{"type":"integer"},"avg_sentiment":{"type":["number","null"]}}}},"top_entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"type_id":{"type":["integer","null"]},"count":{"type":"integer"}}}},"bias_split":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"avg_sentiment":{"type":["number","null"]}}}},"top_sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"domain":{"type":["string","null"]},"bias":{"type":["string","null"]},"opr":{"type":["integer","null"]},"count":{"type":"integer"}}}},"timeline":{"type":"object","additionalProperties":{"type":"integer"}},"top_categories":{"type":"array","items":{"type":"object","properties":{"id":{},"name":{"type":["string","null"]},"count":{"type":"integer"}}}},"top_topics":{"type":"array","items":{"type":"object","properties":{"id":{},"name":{"type":["string","null"]},"count":{"type":"integer"}}}},"breaking":{"type":"object","properties":{"count":{"type":"integer"},"share":{"type":"number","description":"Percentage of breaking articles"}}},"velocity":{"type":"object","properties":{"articles_per_hour":{"type":["number","null"]},"window_hours":{"type":"integer"}}},"movers":{"type":"array","description":"Entities/topics accelerating vs their 14-day baseline","items":{"type":"object","properties":{"type":{"type":"string","enum":["entity","topic"]},"id":{},"name":{"type":["string","null"]},"count_now":{"type":"integer"},"count_baseline":{"type":"integer"},"growth_pct":{"type":["number","null"]}}}}}},"total":{"type":"integer","description":"Exact number of matching articles in radius"},"ranking_weights":{"type":"object","description":"Effective relevance weights (only when sort=relevance)","properties":{"distance":{"type":"number"},"opr":{"type":"number"},"recency":{"type":"number"},"important":{"type":"number"}}},"request_id":{"type":["string","null"]}}},"example":{"status":"ok","query":{"lat":52.52,"lng":13.4,"radius_km":50},"results":[{"id":88412091,"title":"Berlin transit strike enters second day","published_at":"2026-05-22T07:10:00.000Z","distance_km":1.83,"nearest_location":{"entity_id":1234,"name":"Berlin Mitte","lat":52.52,"lng":13.4,"country":"de"}}],"local_insights":{"mood":{"avg_sentiment":-0.21,"distribution":{"positive":41,"neutral":88,"negative":132}},"top_events":[{"type":"protest","category":"society","count":23,"avg_sentiment":-0.38}],"top_entities":[{"id":567,"name":"Kai Wegner","type_id":1,"count":19}],"bias_split":{"left":{"count":88,"avg_sentiment":-0.18},"center":{"count":154,"avg_sentiment":-0.2},"right":{"count":19,"avg_sentiment":-0.41}}},"request_id":"req_abc123def456"}}}},"400":{"description":"Invalid request (missing/invalid lat, lng, radius or insights)","content":{"application/json":{"schema":{"description":"Invalid request (missing/invalid lat, lng, radius or insights)","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/event-types":{"get":{"summary":"List valid event types","tags":["Reference"],"description":"Returns every valid value for the `event.type` and `event.category` filters. Use `event_types[].code` in the `event.type` / `ignore.event.type` filters and `categories[]` in the `event.category` filter.","responses":{"200":{"description":"Valid event types and the categories they belong to","content":{"application/json":{"schema":{"description":"Valid event types and the categories they belong to","type":"object","properties":{"status":{"type":"string","description":"ok"},"categories":{"type":"array","items":{"type":"string"},"description":"Valid values for the event.category filter"},"event_types":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Valid value for the event.type filter"},"category":{"type":"string","description":"Category this event type belongs to"}}}}}},"example":{"status":"ok","categories":["business","society","environment"],"event_types":[{"code":"ipo","category":"business"},{"code":"layoffs","category":"business"},{"code":"election","category":"society"},{"code":"earthquake","category":"environment"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/story/{articleId}":{"post":{"summary":"Get related articles for a story","tags":["News"],"description":"Returns articles related to a given article ID. Finds similar articles based on title similarity. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"articleId","required":true,"description":"Source article ID to find related stories for"}],"responses":{"200":{"description":"Successful response with related articles","content":{"application/json":{"schema":{"description":"Successful response with related articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"400":{"description":"Article ID is required","content":{"application/json":{"schema":{"description":"Article ID is required","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/article":{"post":{"summary":"Get articles by ID","tags":["News"],"description":"Returns one or more articles by their IDs (comma-separated, max 100). Supports filtering, faceting, field selection, and export.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Comma-separated article IDs (max 100). Required.","example":"12345"},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"400":{"description":"Article ID is required","content":{"application/json":{"schema":{"description":"Article ID is required","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/category/{taxonomy}/{categoryId}":{"post":{"summary":"Get articles by category","tags":["News"],"description":"Returns articles for a specific category within a taxonomy. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"taxonomy","required":true,"description":"Category taxonomy (e.g. iptc_mediatopics)"},{"schema":{"type":"string"},"in":"path","name":"categoryId","required":true,"description":"Category ID"}],"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"description":"Category not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/topic/{topicId}":{"post":{"summary":"Get articles by topic","tags":["News"],"description":"Returns articles for a specific topic. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"topicId","required":true,"description":"Topic ID"}],"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Topic not found","content":{"application/json":{"schema":{"description":"Topic not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/industry/{industryId}":{"post":{"summary":"Get articles by industry","tags":["News"],"description":"Returns articles for a specific industry. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"industryId","required":true,"description":"Industry ID"}],"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Industry not found","content":{"application/json":{"schema":{"description":"Industry not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/entity/{entityId}":{"post":{"summary":"Get articles by entity","tags":["News"],"description":"Returns articles mentioning a specific entity (person, organization, location, brand, etc.). Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search":{"type":"string","description":"Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.","example":"tesla,elon musk"},"hl":{"type":"string","enum":["0","1","true","false"],"description":"Enable highlighting"},"hl.fl":{"type":"string","default":"title,description","description":"Comma-separated fields to highlight (max 5). Values: title, description, body","example":"title,description"},"hl.fragsize":{"type":"integer","minimum":50,"maximum":500,"default":150,"description":"Size of highlighted fragment in characters (50-500)"},"hl.snippets":{"type":"integer","minimum":1,"maximum":10,"default":3,"description":"Number of highlighted snippets per field (max 10)"},"hl.tag.pre":{"type":"string","description":"Opening tag for highlighted text","default":"<em>"},"hl.tag.post":{"type":"string","description":"Closing tag for highlighted text","default":"</em>"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination"},"per_page":{"type":"integer","minimum":1,"maximum":250,"default":100,"description":"Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)"},"sort.by":{"type":"string","enum":["published_at","relevance","engagement","quality","controversy","trust","id","new","created_at","source.rank.opr","sentiment.overall.score","sentiment.title.score","sentiment.body.score","read_time","media.images.count","media.videos.count","media.images.width.min","media.images.width.max","media.images.height.min","media.images.height.max","media_richness","shares.facebook.min","shares.facebook.max","shares.twitter.min","shares.twitter.max","shares.reddit.min","shares.reddit.max"],"default":"published_at","description":"Field to sort results by"},"sort.order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"facet":{"type":"string","enum":["0","1","true","false"],"description":"Enable faceting"},"facet.field":{"type":"string","description":"Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day","example":"source.id,category.id"},"facet.limit":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Maximum number of facet values per field (max 100)"},"facet.mincount":{"type":"integer","minimum":1,"default":1,"description":"Minimum count for a facet value to be included"},"facet.range":{"type":"string","enum":["0","1","true","false"],"description":"Enable range faceting"},"facet.range.field":{"type":"string","description":"Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count"},"facet.range.start":{"type":"string","description":"Start value for range faceting (required with facet.range)"},"facet.range.end":{"type":"string","description":"End value for range faceting (required with facet.range)"},"facet.range.gap":{"type":"string","default":"+1DAY","description":"Gap value for range faceting"},"export":{"type":"string","enum":["json","csv","tsv","xml","rss","xlsx","parquet","jsonl","ndjson"],"description":"Export format"},"fl":{"type":"string","description":"Comma-separated list of fields to include in the response","example":"id,title,published_at,source.domain"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"entityId","required":true,"description":"Entity ID"}],"responses":{"200":{"description":"Successful response with articles","content":{"application/json":{"schema":{"description":"Successful response with articles","type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Response status"},"limit":{"type":"integer","description":"Results per page"},"path":{"type":"string","description":"Current request URL"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"next_page":{"type":"string","description":"URL for the next page (empty if no next page)"},"has_previous_page":{"type":"boolean","description":"Whether a previous page exists"},"previous_page":{"type":"string","description":"URL for the previous page (empty if no previous page)"},"export":{"type":"object","description":"Export format URLs","properties":{"json":{"type":"string"},"xlsx":{"type":"string"},"csv":{"type":"string"},"tsv":{"type":"string"},"xml":{"type":"string"},"rss":{"type":"string"},"parquet":{"type":"string"},"jsonl":{"type":"string"}}},"request_id":{"type":"string","description":"Unique request identifier"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}},"description":"Array of articles"},"facets":{"type":"object","description":"Facet results (present when facet.field is specified)","additionalProperties":true},"highlighting":{"type":"object","description":"Highlighting results (present when hl=1)","additionalProperties":true},"headlines":{"type":"array","description":"Headlines (present in some responses)","items":{"type":"object","additionalProperties":true}},"meta":{"type":"object","description":"Additional metadata. Present only when there is something to report about how the request was handled: `prompt` (the request used the prompt parameter) and/or `warnings` (the query was silently narrowed, e.g. ER0366 clamping a title search to the last 31 days).","properties":{"prompt":{"type":"object","description":"How the `prompt` parameter was translated into filters. Returned by every JSON response to a request that used it (the SSE stream has no JSON envelope, so it carries none).","properties":{"text":{"type":"string","description":"The prompt as it was parsed, trimmed"},"applied":{"type":"object","description":"Parameters the prompt was translated into — the request that actually ran","additionalProperties":{"type":"string"}},"ignored":{"type":"array","description":"Values understood but not used","items":{"type":"object","properties":{"field":{"type":"string","description":"Parameter that was not applied"},"value":{"type":"string","description":"Value the prompt produced for it"},"reason":{"type":"string","enum":["not_found","explicit_param","unsupported_on_endpoint","invalid_date","title_too_long","title_window_clamped"],"description":"Why the value was not applied"}}}},"cached":{"type":"boolean","description":"true when this wording had been parsed before, so no parse fee was charged"}}},"warnings":{"type":"array","description":"Non-fatal notices — the request still returned HTTP 200","items":{"type":"object","properties":{"code":{"type":"string","description":"Warning code, e.g. ER0366"},"message":{"type":"string","description":"Human-readable explanation"},"links":{"type":"object","additionalProperties":true}}}}},"additionalProperties":true},"user_input":{"type":"object","description":"Debug info — original request parameters (present when debug=1)","additionalProperties":true}},"required":["status","limit","path","page","has_next_pages","has_previous_page","request_id","results"]},"example":{"status":"ok","limit":50,"path":"/v1/news/everything","page":1,"has_next_pages":true,"next_page":"/v1/news/everything?page=2","has_previous_page":false,"previous_page":"","export":{"json":"/v1/news/everything?export=json","csv":"/v1/news/everything?export=csv","rss":"/v1/news/everything?export=rss"},"request_id":"req_abc123def456","results":[{"id":84029371,"href":"https://example.com/article/spacex-launch","published_at":"2026-03-23T14:30:00Z","title":"SpaceX Successfully Launches New Starship Prototype","description":"SpaceX completed another successful test flight of its Starship rocket...","language":"en","author":{"id":1024,"name":"Jane Smith"},"image":"https://example.com/images/starship.jpg","categories":[{"id":201,"name":"Science & Technology","score":0.95,"taxonomy":"iptc_mediatopics"}],"topics":[{"id":"space-exploration","name":"Space Exploration","score":0.92}],"industries":[{"id":88,"name":"Aerospace & Defense"}],"entities":[{"id":5012,"name":"SpaceX","type":"organization","frequency":8,"links":{"wikipedia":"https://en.wikipedia.org/wiki/SpaceX"}},{"id":3401,"name":"Elon Musk","type":"person","frequency":3,"links":{"wikipedia":"https://en.wikipedia.org/wiki/Elon_Musk"}}],"source":{"id":7823,"domain":"reuters.com","home_page_url":"https://www.reuters.com","type":"news_agency","location":{"country_name":"United States","country_code":"us"},"rankings":{"opr":8}},"sentiment":{"overall":{"score":0.65,"polarity":"positive"},"title":{"score":0.72,"polarity":"positive"},"body":{"score":0.61,"polarity":"positive"}},"readability":{"flesch_kincaid_grade":10.2,"flesch_reading_ease":52.3,"difficulty_level":"intermediate","target_audience":"general"},"keywords":["spacex","starship","rocket","launch"],"is_duplicate":false,"is_breaking":true,"read_time":4,"words_count":847}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"description":"Entity not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/trends":{"post":{"summary":"Get trending topics and entities","tags":["News"],"description":"Returns trending aggregations across news articles. Analyze trends by source, category, topic, industry, or entity. Supports time bucketing, comparison windows, growth rate analysis, and percentile filtering. Maximum date range: 30 days.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"field":{"type":"string","description":"Comma-separated fields to aggregate (max 5). Required.","enum":["source.id","category.id","topic.id","industry.id","entity.id"]},"per_page":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per field"},"offset":{"type":"integer","minimum":0,"default":0,"description":"Offset for pagination"},"mincount":{"type":"integer","minimum":1,"maximum":10000,"default":1,"description":"Minimum article count for a value to be included"},"sort":{"type":"string","enum":["count","value","growth_rate","change","trending_score"],"default":"count","description":"Sort field (change and trending_score require compare=1)"},"order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order"},"time_bucket":{"type":"string","enum":["hour","day","week","month"],"description":"Time bucket for time-series breakdown"},"trending":{"type":"string","enum":["0","1"],"description":"Enable trending analysis with growth rate calculation"},"trending_days":{"type":"integer","minimum":7,"maximum":30,"default":14,"description":"Number of days for trending analysis window"},"compare":{"type":"string","enum":["0","1"],"description":"Enable period comparison"},"compare_window":{"type":"string","description":"Comparison window (required when compare=1). Examples: 24HOURS, 7DAYS, 1WEEK, 1w, 2m"},"percentile":{"type":"integer","minimum":1,"maximum":100,"description":"Filter results above this percentile"},"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Successful response with trend data","content":{"application/json":{"schema":{"description":"Successful response with trend data","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"field":{"type":"string","description":"Aggregated field (single-field request)"},"fields":{"type":"array","items":{"type":"string"},"description":"Aggregated fields (multi-field request)"},"per_page":{"type":"integer","description":"Results per field"},"offset":{"type":"integer","description":"Pagination offset"},"total_count":{"type":"integer","description":"Distinct values count (single-field request)"},"total_articles":{"type":"integer","description":"Total matching articles (single-field request)"},"sort":{"type":"string","description":"Sort field used"},"order":{"type":"string","enum":["asc","desc"],"description":"Sort order used"},"mincount":{"type":"integer","description":"Minimum article count threshold used"},"percentile":{"type":"integer","description":"Percentile filter (present when percentile is set)"},"time_bucket":{"type":"string","description":"Time bucket (present when time_bucket is set)"},"compare_window":{"type":"string","description":"Comparison window (present when compare=1)"},"trending_days":{"type":"integer","description":"Trending window in days (present when trending=1)"},"cached":{"type":"boolean","description":"Whether the result was served from cache"},"trends":{"description":"For a single field — an array of trend items. For multiple fields — an object keyed by field name, each holding { trends, total_count, total_articles }.","oneOf":[{"type":"array","items":{"type":"object","properties":{"value":{"description":"Aggregated value. A plain string when no enrichment is available, or an enriched object (id, name, type, ...) for entities/categories/topics/sources.","oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]},"count":{"type":"integer","description":"Article count for this value"},"percentage":{"type":"number","description":"Share of total matching articles (%)"},"growth_rate":{"type":["number","null"],"description":"Articles per hour over the value lifetime"},"trending_score":{"type":"number","description":"Trending score (present when trending=1)"},"trending_history":{"type":"object","description":"Per-bucket history (present when trending=1)","additionalProperties":true},"previous_count":{"type":"integer","description":"Count in the comparison window (present when compare=1)"},"change_absolute":{"type":"integer","description":"Absolute change vs comparison window (present when compare=1)"},"change_percent":{"type":"number","description":"Percentage change vs comparison window (present when compare=1)"},"buckets":{"type":"object","description":"Counts per time bucket (present when time_bucket is set)","additionalProperties":true},"total":{"type":"integer","description":"Total across buckets (present when time_bucket is set)"}}}},{"type":"object","additionalProperties":{"type":"object","properties":{"trends":{"type":"array","items":{"type":"object","additionalProperties":true}},"total_count":{"type":"integer"},"total_articles":{"type":"integer"}}}}]},"request_id":{"type":"string"}}},"example":{"status":"ok","field":"entity.id","per_page":10,"offset":0,"total_count":1240,"total_articles":58213,"sort":"count","order":"desc","mincount":1,"trends":[{"value":{"id":5012,"name":"SpaceX","type":"organization"},"count":342,"percentage":0.59,"growth_rate":2.15},{"value":{"id":3401,"name":"Elon Musk","type":"person"},"count":218,"percentage":0.37,"growth_rate":1.45}],"request_id":"req_abc123def456"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/news/count":{"post":{"summary":"Count matching articles","tags":["News"],"description":"Returns only the number of articles matching the given filters, without loading any article content. Accepts the same filters as `/v1/news/everything`, but runs a single `count(*)` in ClickHouse — much cheaper and faster when you only need the total (dashboards, sample size estimation, progress bars).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":500,"description":"Plain-language description of the news you want, e.g. \"Elon Musk, Tesla, news for the last 10 days\". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt)."},"query":{"type":"string","maxLength":4000,"description":"Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.","example":"bitcoin AND NOT (etf OR futures)"},"article.id":{"type":"string","description":"Comma-separated article IDs (max 5)","example":"12345"},"title":{"type":"string","minLength":2,"maxLength":100,"description":"Search in article titles. Supports phrase search with proximity: \"climate change\"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110."},"ignore.title":{"type":"string","minLength":2,"maxLength":100,"description":"Exclude articles containing this text in the title"},"title_starts_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title starts with the given text. Same 31-day window limit as title"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text. Same 31-day window limit as title"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern. Same 31-day window limit as title"},"published_at":{"type":"string","description":"Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601","example":"2025-01-15"},"published_at.start":{"type":"string","description":"Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)","example":"2025-01-31"},"language.code":{"type":"string","description":"Comma-separated ISO 639-1 language codes (max 3)","example":"en"},"ignore.language.code":{"type":"string","description":"Exclude articles in these languages (comma-separated, max 3)","example":"zh,ar"},"source.country.code":{"type":"string","description":"Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)","example":"us"},"ignore.source.country.code":{"type":"string","description":"Exclude sources from these countries (comma-separated, max 3)","example":"us"},"source.rank.opr.min":{"type":"integer","minimum":0,"description":"Minimum Open PageRank score"},"source.rank.opr.max":{"type":"integer","minimum":0,"description":"Maximum Open PageRank score"},"source.id":{"type":"string","description":"Comma-separated source IDs (max 3)","example":"100"},"ignore.source.id":{"type":"string","description":"Exclude these source IDs (comma-separated, max 3)"},"source.domain":{"type":"string","description":"Comma-separated source domains (max 3)","example":"nytimes.com"},"ignore.source.domain":{"type":"string","description":"Exclude these source domains (comma-separated, max 3)"},"source.bias":{"type":"string","description":"Filter by media bias (comma-separated). Values: left, center, right","example":"left"},"ignore.source.bias":{"type":"string","description":"Exclude sources with this media bias (comma-separated). Values: left, center, right","example":"right"},"is_premium_source":{"type":"integer","enum":[0,1],"description":"Filter by premium source status"},"is_verified_source":{"type":"integer","enum":[0,1],"description":"Filter by verified source status"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000","example":"medtop:04000000"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news","example":"industry.technology_news"},"ignore.topic.id":{"type":"string","description":"Exclude these topics (comma-separated, max 3)"},"industry.id":{"type":"string","description":"Comma-separated industry IDs (max 3)","example":"1"},"ignore.industry.id":{"type":"string","description":"Exclude these industries (comma-separated, max 3)"},"entity.id":{"type":"string","description":"Comma-separated entity IDs (max 3)","example":"12345"},"ignore.entity.id":{"type":"string","description":"Exclude these entity IDs (comma-separated, max 3)"},"entity.sentiment.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293."},"entity.sentiment.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum sentiment score toward the entity"},"entity.sentiment.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum sentiment score toward the entity"},"person.name":{"type":"string","maxLength":120,"description":"Filter by person name (comma-separated, max 3)","example":"Elon Musk"},"ignore.person.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these persons (comma-separated, max 3)"},"organization.name":{"type":"string","maxLength":120,"description":"Filter by organization name (comma-separated, max 3)","example":"Google"},"ignore.organization.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these organizations (comma-separated, max 3)"},"location.name":{"type":"string","maxLength":120,"description":"Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218","example":"New York City"},"ignore.location.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these locations (comma-separated, max 3)"},"brand.name":{"type":"string","maxLength":120,"description":"Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222"},"ignore.brand.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these brands (comma-separated, max 3)"},"disaster.name":{"type":"string","maxLength":120,"description":"Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224"},"ignore.disaster.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these disasters (comma-separated, max 3)"},"disease.name":{"type":"string","maxLength":120,"description":"Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226"},"ignore.disease.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these diseases (comma-separated, max 3)"},"event.name":{"type":"string","maxLength":120,"description":"Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228"},"ignore.event.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these events (comma-separated, max 3)"},"sport.name":{"type":"string","maxLength":120,"description":"Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250"},"ignore.sport.name":{"type":"string","maxLength":120,"description":"Exclude articles mentioning these sports (comma-separated, max 3)"},"event.type":{"type":"string","description":"Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche","example":"ipo"},"event.category":{"type":"string","enum":["business","society","environment"],"description":"Filter by event category"},"ignore.event.type":{"type":"string","description":"Exclude these event types (comma-separated, max 5)"},"sentiment.overall.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact overall sentiment score"},"sentiment.overall.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum overall sentiment score"},"sentiment.overall.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum overall sentiment score"},"sentiment.overall.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Overall sentiment polarity"},"sentiment.title.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact title sentiment score"},"sentiment.title.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum title sentiment score"},"sentiment.title.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum title sentiment score"},"sentiment.title.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Title sentiment polarity"},"sentiment.body.score":{"type":"number","minimum":-1,"maximum":1,"description":"Exact body sentiment score"},"sentiment.body.score.min":{"type":"number","minimum":-1,"maximum":1,"description":"Minimum body sentiment score"},"sentiment.body.score.max":{"type":"number","minimum":-1,"maximum":1,"description":"Maximum body sentiment score"},"sentiment.body.polarity":{"type":"string","enum":["positive","negative","neutral"],"description":"Body sentiment polarity"},"sentiment.mixed":{"type":"integer","enum":[0,1],"description":"Filter for mixed sentiment (title polarity != body polarity)"},"sentiment.consistent":{"type":"integer","enum":[0,1],"description":"Filter for consistent sentiment (title polarity == body polarity)"},"is_clickbait":{"type":"integer","enum":[0,1],"description":"Filter by clickbait detection"},"sentiment_gap.min":{"type":"number","minimum":0,"maximum":2,"description":"Minimum sentiment gap between title and body"},"sentiment_gap.max":{"type":"number","minimum":0,"maximum":2,"description":"Maximum sentiment gap between title and body"},"media.images.count":{"type":"integer","minimum":0,"description":"Exact number of images"},"media.images.count.min":{"type":"integer","minimum":0,"description":"Minimum number of images"},"media.images.count.max":{"type":"integer","minimum":0,"description":"Maximum number of images"},"media.images.width.min":{"type":"integer","minimum":0,"description":"Minimum image width in pixels"},"media.images.width.max":{"type":"integer","minimum":0,"description":"Maximum image width in pixels"},"media.images.height.min":{"type":"integer","minimum":0,"description":"Minimum image height in pixels"},"media.images.height.max":{"type":"integer","minimum":0,"description":"Maximum image height in pixels"},"media.videos.count":{"type":"integer","minimum":0,"description":"Exact number of videos"},"media.videos.count.min":{"type":"integer","minimum":0,"description":"Minimum number of videos"},"media.videos.count.max":{"type":"integer","minimum":0,"description":"Maximum number of videos"},"has_image":{"type":"integer","enum":[0,1],"description":"Filter articles with/without images"},"has_video":{"type":"integer","enum":[0,1],"description":"Filter articles with/without videos"},"has_hq_images":{"type":"integer","enum":[0,1],"description":"Filter articles with high-quality images (>= 1200px width)"},"is_media_rich":{"type":"integer","enum":[0,1],"description":"Filter articles with both images and videos"},"is_landscape_media":{"type":"integer","enum":[0,1],"description":"Filter articles with landscape-oriented media"},"is_portrait_media":{"type":"integer","enum":[0,1],"description":"Filter articles with portrait-oriented media"},"has_multiple_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 2+ images"},"has_fullhd_images":{"type":"integer","enum":[0,1],"description":"Filter articles with Full HD images (>= 1920px width)"},"has_4k_images":{"type":"integer","enum":[0,1],"description":"Filter articles with 4K images (>= 3840px width)"},"has_mobile_optimized_images":{"type":"integer","enum":[0,1],"description":"Filter articles with mobile-optimized images (320-800px width)"},"is_instagram_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Instagram-ready images (>= 1080px + aspect ratio)"},"is_twitter_card_ready":{"type":"integer","enum":[0,1],"description":"Filter articles with Twitter Card-ready images (>= 800px + landscape)"},"has_consistent_image_sizes":{"type":"integer","enum":[0,1],"description":"Filter articles with consistent image dimensions"},"has_thumbnail":{"type":"integer","enum":[0,1],"description":"Filter articles with thumbnail images (<= 300px width)"},"has_social_share_image":{"type":"integer","enum":[0,1],"description":"Filter articles with social share images (>= 1200x630px)"},"has_mixed_media":{"type":"integer","enum":[0,1],"description":"Filter articles with both image and video media types"},"readability.fk_grade":{"type":"number","minimum":0,"maximum":30,"description":"Exact Flesch-Kincaid grade level"},"readability.fk_grade.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Flesch-Kincaid grade level"},"readability.fk_grade.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Flesch-Kincaid grade level"},"readability.ease":{"type":"number","minimum":0,"maximum":100,"description":"Exact Flesch Reading Ease score"},"readability.ease.min":{"type":"number","minimum":0,"maximum":100,"description":"Minimum Flesch Reading Ease score"},"readability.ease.max":{"type":"number","minimum":0,"maximum":100,"description":"Maximum Flesch Reading Ease score"},"readability.ari":{"type":"number","minimum":0,"maximum":30,"description":"Exact Automated Readability Index"},"readability.ari.min":{"type":"number","minimum":0,"maximum":30,"description":"Minimum Automated Readability Index"},"readability.ari.max":{"type":"number","minimum":0,"maximum":30,"description":"Maximum Automated Readability Index"},"readability.difficulty":{"type":"string","enum":["beginner","intermediate","advanced","expert"],"description":"Difficulty level"},"readability.audience":{"type":"string","enum":["children","general","professional","academic"],"description":"Target audience"},"readability.age":{"type":"integer","minimum":6,"maximum":22,"description":"Exact reading age"},"readability.age.min":{"type":"integer","minimum":6,"maximum":22,"description":"Minimum reading age"},"readability.age.max":{"type":"integer","minimum":6,"maximum":22,"description":"Maximum reading age"},"is_easy_read":{"type":"integer","enum":[0,1],"description":"Filter for easy-to-read articles (Flesch Reading Ease >= 60)"},"is_difficult_read":{"type":"integer","enum":[0,1],"description":"Filter for difficult-to-read articles (Flesch Reading Ease < 40)"},"read_time":{"type":"integer","minimum":0,"maximum":1000,"description":"Exact read time in minutes"},"read_time.min":{"type":"integer","minimum":0,"maximum":1000,"description":"Minimum read time in minutes"},"read_time.max":{"type":"integer","minimum":0,"maximum":1000,"description":"Maximum read time in minutes"},"is_long_read":{"type":"integer","enum":[0,1],"description":"Filter for long reads (>= 5 minutes)"},"is_short_read":{"type":"integer","enum":[0,1],"description":"Filter for short reads (< 3 minutes)"},"is_quick_read":{"type":"integer","enum":[0,1],"description":"Filter for quick reads (<= 2 minutes)"},"is_medium_read":{"type":"integer","enum":[0,1],"description":"Filter for medium-length reads (3-7 minutes)"},"is_deep_dive":{"type":"integer","enum":[0,1],"description":"Filter for deep dives (>= 10 minutes)"},"location.bbox":{"type":"string","description":"Bounding box: minLat,maxLat,minLng,maxLng","example":"40.0,41.0,-74.5,-73.5"},"has_location_geo":{"type":"integer","enum":[0,1],"description":"Filter articles with/without geo-location data"},"location.lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude for radius search"},"location.lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude for radius search"},"location.radius":{"type":"number","exclusiveMinimum":0,"maximum":20000,"description":"Search radius in kilometers (requires location.lat and location.lng)"},"location.radius.min":{"type":"number","minimum":0,"maximum":20000,"description":"Minimum distance from point in km"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_paywall":{"type":"integer","enum":[0,1],"description":"Filter paywalled articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"is_high_quality":{"type":"integer","enum":[0,1],"description":"Filter high-quality articles (not duplicate, rank >= 5, has images, has author)"},"author.id":{"type":"string","description":"Comma-separated author IDs (max 3)"},"ignore.author.id":{"type":"string","description":"Exclude these author IDs (comma-separated, max 3)"},"author.name":{"type":"string","maxLength":100,"description":"Filter by author name (comma-separated, max 3)"},"ignore.author.name":{"type":"string","maxLength":100,"description":"Exclude articles by these authors (comma-separated, max 3)"},"has_author":{"type":"integer","enum":[0,1],"description":"Filter articles with/without author"},"debug":{"type":"string","enum":["0","1","true","false"],"description":"Include user_input in response for debugging"},"api_key":{"type":"string","description":"API key (alternative to X-API-Key header)"}}}}}},"responses":{"200":{"description":"Successful response with matching article count","content":{"application/json":{"schema":{"description":"Successful response with matching article count","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"count":{"type":"integer","description":"Number of articles matching the filters"},"request_id":{"type":"string"}}},"example":{"status":"ok","count":12345,"request_id":"req_abc123def456"}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"description":"Rate limit exceeded","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/suggest/entities":{"get":{"summary":"Autocomplete entities","tags":["Suggest"],"description":"Returns entity suggestions matching a given prefix. Useful for building autocomplete/typeahead UI.","parameters":[{"schema":{"type":"string"},"in":"query","name":"prefix","required":true,"description":"Search prefix for entity name. Required."}],"responses":{"200":{"description":"Array of matching entities","content":{"application/json":{"schema":{"description":"Array of matching entities","type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata","additionalProperties":true}}}},"example":[{"id":5012,"name":"SpaceX","type":"organization","links":{"self":"/v1/news/entity/5012","wikipedia":"https://en.wikipedia.org/wiki/SpaceX","wikidata":"https://www.wikidata.org/wiki/Q193701"},"metadata":{}},{"id":9284,"name":"Spotify","type":"brand","links":{"self":"/v1/news/entity/9284","wikipedia":"https://en.wikipedia.org/wiki/Spotify","wikidata":"https://www.wikidata.org/wiki/Q689141"},"metadata":{}}]}}},"400":{"description":"Missing prefix parameter","content":{"application/json":{"schema":{"description":"Missing prefix parameter","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/suggest/categories":{"get":{"summary":"Autocomplete categories","tags":["Suggest"],"description":"Returns category suggestions matching a given prefix. The returned `id` can be used directly in the `category.id` filter. Useful for building autocomplete/typeahead UI.","parameters":[{"schema":{"type":"string"},"in":"query","name":"prefix","required":true,"description":"Search prefix for category name. Required."}],"responses":{"200":{"description":"Array of matching categories","content":{"application/json":{"schema":{"description":"Array of matching categories","type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID (use in category.id filter)"},"name":{"type":"string","description":"Category name"},"taxonomy":{"type":"string","description":"Category taxonomy"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"example":[{"id":11100000,"name":"sport","taxonomy":"iptc_mediatopics","links":{"self":"/v1/news/category/iptc_mediatopics/11100000"}}]}}},"400":{"description":"Missing prefix parameter","content":{"application/json":{"schema":{"description":"Missing prefix parameter","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/suggest/topics":{"get":{"summary":"Autocomplete topics","tags":["Suggest"],"description":"Returns topic suggestions matching a given prefix. The returned `id` can be used directly in the `topic.id` filter. Useful for building autocomplete/typeahead UI.","parameters":[{"schema":{"type":"string"},"in":"query","name":"prefix","required":true,"description":"Search prefix for topic name. Required."}],"responses":{"200":{"description":"Array of matching topics","content":{"application/json":{"schema":{"description":"Array of matching topics","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID (use in topic.id filter)"},"name":{"type":"string","description":"Topic name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"example":[{"id":"elections","name":"Elections","links":{"self":"/v1/news/topic/elections"}}]}}},"400":{"description":"Missing prefix parameter","content":{"application/json":{"schema":{"description":"Missing prefix parameter","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/suggest/industries":{"get":{"summary":"Autocomplete industries","tags":["Suggest"],"description":"Returns industry suggestions matching a given prefix. The returned `id` can be used directly in the `industry.id` filter. Useful for building autocomplete/typeahead UI.","parameters":[{"schema":{"type":"string"},"in":"query","name":"prefix","required":true,"description":"Search prefix for industry name. Required."}],"responses":{"200":{"description":"Array of matching industries","content":{"application/json":{"schema":{"description":"Array of matching industries","type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID (use in industry.id filter)"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"example":[{"id":312,"name":"Technology","links":{"self":"/v1/news/industry/312"}}]}}},"400":{"description":"Missing prefix parameter","content":{"application/json":{"schema":{"description":"Missing prefix parameter","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/people":{"get":{"summary":"List & search people","tags":["Reference"],"description":"Directory of known persons (public figures, politicians, executives) with Wikidata-enriched profiles. Filter by name or Wikidata ID. Pivot to coverage via the `links.articles` URL.","parameters":[{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter by person name (substring match)."},{"schema":{"type":"string"},"in":"query","name":"wikidata_id","required":false,"description":"Filter by Wikidata ID (e.g. Q317521 or 317521)."},{"schema":{"type":"integer"},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer"},"in":"query","name":"per_page","required":false,"description":"Results per page (default 100, max 250; Free is capped at 10, Starter at 50, Basic at 200)."}],"responses":{"200":{"description":"Paginated list of people","content":{"application/json":{"schema":{"description":"Paginated list of people","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"limit":{"type":"integer","description":"Results per page"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Person (entity) ID"},"name":{"type":"string","description":"Person name"},"type":{"type":"string","description":"Entity type (person)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this reference profile"},"articles":{"type":"string","description":"Link to articles mentioning this entity"},"wikipedia":{"type":"string","description":"Wikipedia URL (empty if unknown)"},"wikidata":{"type":"string","description":"Wikidata URL (empty if unknown)"}}},"profile":{"type":["object","null"],"description":"Wikidata-enriched metadata (varies by entity)","additionalProperties":true}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/people/{id}":{"get":{"summary":"Get a person profile","tags":["Reference"],"description":"Returns a single person profile with Wikidata-enriched metadata and links to coverage.","parameters":[{"schema":{"type":"string"},"in":"query","name":"coverage","required":false,"description":"Set to \"false\" to skip the coverage block (article counts, timeline, top sources/topics)."},{"schema":{"type":"integer"},"in":"path","name":"id","required":true,"description":"Person (entity) ID."}],"responses":{"200":{"description":"A single person profile","content":{"application/json":{"schema":{"description":"A single person profile","type":"object","properties":{"id":{"type":"integer","description":"Person (entity) ID"},"name":{"type":"string","description":"Person name"},"type":{"type":"string","description":"Entity type (person)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this reference profile"},"articles":{"type":"string","description":"Link to articles mentioning this entity"},"wikipedia":{"type":"string","description":"Wikipedia URL (empty if unknown)"},"wikidata":{"type":"string","description":"Wikidata URL (empty if unknown)"}}},"profile":{"type":["object","null"],"description":"Wikidata-enriched metadata (varies by entity)","additionalProperties":true},"coverage":{"type":["object","null"],"description":"Aggregated coverage stats (omitted when coverage=false, null on error)","properties":{"article_count":{"type":"integer","description":"Total articles in coverage scope"},"first_seen":{"type":["string","null"],"description":"Date of the earliest article (YYYY-MM-DD)"},"last_seen":{"type":["string","null"],"description":"Date of the latest article (YYYY-MM-DD)"},"sentiment":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}},"momentum":{"type":"object","properties":{"last_30_days":{"type":"integer"},"previous_30_days":{"type":"integer"},"change_pct":{"type":["integer","null"],"description":"Percent change vs previous 30 days"}}},"timeline":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Month bucket (YYYY-MM-DD)"},"count":{"type":"integer"}}}},"top_sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"},"count":{"type":"integer"}}}},"top_topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}},"top_countries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}},"top_languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}},"related_entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}}}},"recent_articles":{"type":"array","description":"Up to 5 most recent articles (full article objects)","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"402":{"description":"No points left on account","content":{"application/json":{"schema":{"description":"No points left on account","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"description":"Person not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/companies":{"get":{"summary":"List & search companies","tags":["Reference"],"description":"Directory of organizations and brands with Wikidata-enriched profiles (headquarters, founded, website, key people, subsidiaries). Filter by name or Wikidata ID. Pivot to coverage via the `links.articles` URL.","parameters":[{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter by company name (substring match)."},{"schema":{"type":"string"},"in":"query","name":"wikidata_id","required":false,"description":"Filter by Wikidata ID (e.g. Q95 or 95)."},{"schema":{"type":"integer"},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer"},"in":"query","name":"per_page","required":false,"description":"Results per page (default 100, max 250; Free is capped at 10, Starter at 50, Basic at 200)."}],"responses":{"200":{"description":"Paginated list of companies","content":{"application/json":{"schema":{"description":"Paginated list of companies","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"limit":{"type":"integer","description":"Results per page"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Company (entity) ID"},"name":{"type":"string","description":"Company name"},"type":{"type":"string","description":"Entity type (organization or brand)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this reference profile"},"articles":{"type":"string","description":"Link to articles mentioning this entity"},"wikipedia":{"type":"string","description":"Wikipedia URL (empty if unknown)"},"wikidata":{"type":"string","description":"Wikidata URL (empty if unknown)"}}},"profile":{"type":["object","null"],"description":"Wikidata-enriched metadata (varies by entity)","additionalProperties":true}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/companies/{id}":{"get":{"summary":"Get a company profile","tags":["Reference"],"description":"Returns a single company profile with Wikidata-enriched metadata and links to coverage.","parameters":[{"schema":{"type":"string"},"in":"query","name":"coverage","required":false,"description":"Set to \"false\" to skip the coverage block (article counts, timeline, top sources/topics)."},{"schema":{"type":"integer"},"in":"path","name":"id","required":true,"description":"Company (entity) ID."}],"responses":{"200":{"description":"A single company profile","content":{"application/json":{"schema":{"description":"A single company profile","type":"object","properties":{"id":{"type":"integer","description":"Company (entity) ID"},"name":{"type":"string","description":"Company name"},"type":{"type":"string","description":"Entity type (organization or brand)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this reference profile"},"articles":{"type":"string","description":"Link to articles mentioning this entity"},"wikipedia":{"type":"string","description":"Wikipedia URL (empty if unknown)"},"wikidata":{"type":"string","description":"Wikidata URL (empty if unknown)"}}},"profile":{"type":["object","null"],"description":"Wikidata-enriched metadata (varies by entity)","additionalProperties":true},"coverage":{"type":["object","null"],"description":"Aggregated coverage stats (omitted when coverage=false, null on error)","properties":{"article_count":{"type":"integer","description":"Total articles in coverage scope"},"first_seen":{"type":["string","null"],"description":"Date of the earliest article (YYYY-MM-DD)"},"last_seen":{"type":["string","null"],"description":"Date of the latest article (YYYY-MM-DD)"},"sentiment":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}},"momentum":{"type":"object","properties":{"last_30_days":{"type":"integer"},"previous_30_days":{"type":"integer"},"change_pct":{"type":["integer","null"],"description":"Percent change vs previous 30 days"}}},"timeline":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Month bucket (YYYY-MM-DD)"},"count":{"type":"integer"}}}},"top_sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"domain":{"type":"string"},"count":{"type":"integer"}}}},"top_topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}},"top_countries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}},"top_languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}},"related_entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}}}},"recent_articles":{"type":"array","description":"Up to 5 most recent articles (full article objects)","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"402":{"description":"No points left on account","content":{"application/json":{"schema":{"description":"No points left on account","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"description":"Company not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/journalists":{"get":{"summary":"List & search journalists","tags":["Reference"],"description":"Directory of journalists, normalized by name (bylines across multiple outlets are merged into one record with an `outlets` array). Filter by name. Note: exact namesakes and generic bylines (e.g. \"admin\") may be merged — true disambiguation is planned for a later release.","parameters":[{"schema":{"type":"string"},"in":"query","name":"name","required":false,"description":"Filter by journalist name (substring match)."},{"schema":{"type":"integer"},"in":"query","name":"page","required":false,"description":"Page number (default 1)."},{"schema":{"type":"integer"},"in":"query","name":"per_page","required":false,"description":"Results per page (default 100, max 250; Free is capped at 10, Starter at 50, Basic at 200)."}],"responses":{"200":{"description":"Paginated list of journalists","content":{"application/json":{"schema":{"description":"Paginated list of journalists","type":"object","properties":{"status":{"type":"string","enum":["ok"]},"limit":{"type":"integer","description":"Results per page"},"page":{"type":"integer","description":"Current page number"},"has_next_pages":{"type":"boolean","description":"Whether more pages are available"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Journalist (author) ID"},"name":{"type":"string","description":"Journalist name"},"outlets":{"type":"array","description":"Outlets the journalist writes for","items":{"type":"object","additionalProperties":true}},"outlet_count":{"type":"integer","description":"Number of outlets (list endpoint only)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this journalist profile"},"articles":{"type":"string","description":"Link to articles by this journalist"}}}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}},"/v1/journalists/{id}":{"get":{"summary":"Get a journalist profile","tags":["Reference"],"description":"Returns a journalist profile: name, all `outlets` they publish under (merged by name), and a `coverage` block (article counts, timeline, sentiment, top topics, top covered entities).","parameters":[{"schema":{"type":"string"},"in":"query","name":"coverage","required":false,"description":"Set to \"false\" to skip the coverage block (activity, timeline, top topics/entities)."},{"schema":{"type":"integer"},"in":"path","name":"id","required":true,"description":"Journalist (author) ID."}],"responses":{"200":{"description":"A single journalist profile","content":{"application/json":{"schema":{"description":"A single journalist profile","type":"object","properties":{"id":{"type":"integer","description":"Journalist (author) ID"},"name":{"type":"string","description":"Journalist name"},"outlets":{"type":"array","description":"Outlets the journalist writes for","items":{"type":"object","additionalProperties":true}},"outlet_count":{"type":"integer","description":"Number of outlets (list endpoint only)"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to this journalist profile"},"articles":{"type":"string","description":"Link to articles by this journalist"}}},"coverage":{"type":["object","null"],"description":"Aggregated coverage stats (omitted when coverage=false, null on error)","properties":{"article_count":{"type":"integer","description":"Total articles in coverage scope"},"first_seen":{"type":["string","null"],"description":"Date of the earliest article (YYYY-MM-DD)"},"last_seen":{"type":["string","null"],"description":"Date of the latest article (YYYY-MM-DD)"},"sentiment":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}},"momentum":{"type":"object","properties":{"last_30_days":{"type":"integer"},"previous_30_days":{"type":"integer"},"change_pct":{"type":["integer","null"],"description":"Percent change vs previous 30 days"}}},"timeline":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","description":"Month bucket (YYYY-MM-DD)"},"count":{"type":"integer"}}}},"top_topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}},"top_entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","string"],"description":"Item ID"},"name":{"type":"string"},"count":{"type":"integer"}}}},"top_countries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}},"top_languages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"code":{"type":"string"},"count":{"type":"integer"}}}}}},"recent_articles":{"type":"array","description":"Up to 5 most recent articles (full article objects)","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique article ID"},"href":{"type":["string","null"],"description":"Original article URL"},"published_at":{"type":["string","null"],"format":"date-time","description":"Publication date in ISO 8601"},"title":{"type":["string","null"],"description":"Article title"},"description":{"type":["string","null"],"description":"Article description (plain text)"},"body":{"type":["string","null"],"description":"Article body (plain text)"},"body_html":{"type":["string","null"],"description":"Article body (HTML)"},"language":{"type":"string","description":"ISO 639-1 language code"},"translations":{"type":"object","description":"Machine translations of the article title and description. Always present; fields stay null for English articles and for languages without a translation model","properties":{"en":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title translated to English"},"description":{"type":["string","null"],"description":"Description translated to English (plain text)"}}}}},"author":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Author ID"},"name":{"type":"string","description":"Author name"}}},"image":{"type":"string","description":"Main article image URL"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Category ID"},"name":{"type":"string","description":"Category name"},"score":{"type":"number","description":"Relevance score"},"taxonomy":{"type":"string","description":"Taxonomy identifier"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to category endpoint"}}}}}},"topics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Topic ID"},"name":{"type":"string","description":"Topic name"},"score":{"type":"number","description":"Relevance score"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to topic endpoint"}}}}}},"industries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Industry ID"},"name":{"type":"string","description":"Industry name"},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to industry endpoint"}}}}}},"entities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Entity ID"},"name":{"type":"string","description":"Entity name"},"type":{"type":"string","enum":["person","location","organization","brand","product","natural-disaster","disease","event","sport","unknown"],"description":"Entity type"},"frequency":{"type":"integer","description":"Number of mentions in the article"},"sentiment":{"type":"object","description":"Sentiment toward this entity (aggregated across its mentions)","properties":{"score":{"type":"number","description":"Entity sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Entity sentiment polarity"},"mentions":{"type":"object","description":"Per-mention polarity breakdown","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}}}}},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"object","properties":{"start":{"type":"integer","description":"Start character offset"},"end":{"type":"integer","description":"End character offset"}}},"description":"Mention positions in body"}}},"links":{"type":"object","properties":{"self":{"type":"string","description":"Link to entity endpoint"},"wikipedia":{"type":"string","description":"Wikipedia URL"},"wikidata":{"type":"string","description":"Wikidata URL"}}},"metadata":{"type":"object","description":"Additional entity metadata (varies by entity type)","additionalProperties":true}}}},"locations_mentioned":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Location name"},"country":{"type":"string","description":"Country code"},"lat":{"type":["number","null"],"description":"Latitude"},"lng":{"type":["number","null"],"description":"Longitude"},"type":{"type":"string","description":"Location type"}}}},"source":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"Source ID"},"domain":{"type":"string","description":"Source domain"},"home_page_url":{"type":"string","description":"Source home page URL"},"type":{"type":"string","description":"Source type"},"bias":{"type":"string","description":"Media bias (left, center, right)"},"rankings":{"type":"object","properties":{"opr":{"type":"integer","description":"Open PageRank score"}}},"location":{"type":"object","properties":{"country_name":{"type":"string","description":"Source country name"},"country_code":{"type":"string","description":"Source country ISO code"}}},"favicon":{"type":"string","description":"Source favicon URL"}}},"sentiment":{"type":"object","properties":{"overall":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"title":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}},"body":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}},"summary":{"type":"array","items":{"type":"object","properties":{"sentence":{"type":"string","description":"Summary sentence"},"sentiment":{"type":"object","properties":{"score":{"type":"number","description":"Sentiment score from -1 (negative) to 1 (positive)"},"polarity":{"type":"string","enum":["positive","negative","neutral",""],"description":"Sentiment polarity"}}}}}},"readability":{"type":"object","properties":{"flesch_kincaid_grade":{"type":"number","description":"Flesch-Kincaid grade level"},"flesch_reading_ease":{"type":"number","description":"Flesch Reading Ease score (0-100)"},"automated_readability_index":{"type":"number","description":"Automated Readability Index"},"difficulty_level":{"type":"string","enum":["beginner","intermediate","advanced","expert","unknown"],"description":"Difficulty level"},"target_audience":{"type":"string","enum":["children","general","professional","academic","unknown"],"description":"Target audience"},"reading_age":{"type":"number","description":"Estimated reading age"},"avg_words_per_sentence":{"type":"number","description":"Average words per sentence"},"avg_syllables_per_word":{"type":"number","description":"Average syllables per word"}}},"keywords":{"type":"array","items":{"type":"string"},"description":"Article keywords"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Link URL"},"type":{"type":"string","description":"Link type"}}}},"media":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"Media URL"},"type":{"type":"string","description":"Media type (image, video, etc.)"}}}},"shares":{"type":"object","properties":{"total":{"type":"integer","description":"Total social shares"},"facebook":{"type":"integer","description":"Facebook shares"},"twitter":{"type":"integer","description":"Twitter/X shares"},"reddit":{"type":"integer","description":"Reddit shares"}}},"story":{"type":"object","properties":{"id":{"type":"integer","description":"Story ID"},"uri":{"type":"string","description":"Story endpoint URI"}}},"is_duplicate":{"type":"boolean","description":"Whether this is a duplicate article"},"is_free":{"type":"boolean","description":"Whether the article is freely accessible"},"is_breaking":{"type":"boolean","description":"Whether this is breaking news"},"read_time":{"type":"integer","description":"Estimated read time in minutes"},"sentences_count":{"type":"integer","description":"Number of sentences"},"paragraphs_count":{"type":"integer","description":"Number of paragraphs"},"words_count":{"type":"integer","description":"Number of words"},"characters_count":{"type":"integer","description":"Number of characters"}}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"description":"Authentication error","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"402":{"description":"No points left on account","content":{"application/json":{"schema":{"description":"No points left on account","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}},"404":{"description":"Journalist not found","content":{"application/json":{"schema":{"description":"Journalist not found","type":"object","properties":{"status":{"type":"string","enum":["not_ok"],"description":"Response status"},"request_id":{"type":["null","string"],"description":"Unique request identifier"},"errors":{"type":"array","items":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"code":{"type":"string","description":"Error code (e.g. ER0201)"},"message":{"type":"string","description":"Human-readable error message"},"links":{"type":"object","properties":{"about":{"type":"string","description":"Link to error documentation"}}},"timestamp":{"type":"string","format":"date-time","description":"Error timestamp"}}}}}},"example":{"status":"not_ok","request_id":"req_abc123def456","errors":[{"status":401,"code":"ER0201","message":"Invalid or missing API key.","links":{"about":"https://docs.apitube.io/platform/news-api/http-response-codes"},"timestamp":"2026-03-23T14:30:00Z"}]}}}}}}}},"servers":[{"url":"https://api.apitube.io"}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"tags":[{"name":"News","description":"Search, filter, and retrieve news articles from thousands of global sources. Includes full-text search, top headlines, related stories, category/topic/industry/entity browsing, and trends."},{"name":"Fact Check","description":"Verify factual claims against the live news corpus (retrieval-augmented). Returns per-claim verdicts on an 8-level scale with confidence, explanation, and supporting evidence."},{"name":"Account","description":"API key balance and subscription plan information."},{"name":"Suggest","description":"Autocomplete and typeahead suggestions for entities."},{"name":"System","description":"Health checks and service status."}],"externalDocs":{"description":"APITube News API Documentation","url":"https://docs.apitube.io"}}