{"openapi":"3.1.0","info":{"title":"News API","version":"1.0.0","description":"News API — search and filter news articles from thousands of sources worldwide."},"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"}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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"},"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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":{"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)"},"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","sentences_count","paragraphs_count","characters_count","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"},"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"},"title_ends_with":{"type":"string","minLength":2,"maxLength":100,"description":"Filter articles whose title ends with the given text"},"title_pattern":{"type":"string","minLength":2,"maxLength":200,"description":"Filter articles whose title matches the given pattern"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"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)","example":"New York"},"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)"},"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)"},"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)"},"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)"},"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)"},"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"],"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"],"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"},"hl":{"type":"string","enum":["0","1"],"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>"},"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"],"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"},"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":"string","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"},"title":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"Positions in title"}}},"body":{"type":"object","properties":{"pos":{"type":"array","items":{"type":"integer"},"description":"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","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"]}}}},"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"}}}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}},"/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"},"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","example":"2025-01-01"},"published_at.end":{"type":"string","description":"End of date range. Format: YYYY-MM-DD or ISO 8601","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":"cn,ru"},"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"},"category.id":{"type":"string","description":"Comma-separated category IDs (max 3)","example":"iab-1"},"ignore.category.id":{"type":"string","description":"Exclude these categories (comma-separated, max 3)"},"topic.id":{"type":"string","description":"Comma-separated topic IDs (max 3)","example":"technology"},"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)"},"is_duplicate":{"type":"integer","enum":[0,1],"description":"Filter duplicate/unique articles"},"is_breaking":{"type":"integer","enum":[0,1],"description":"Filter breaking news articles"},"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"]},"request_id":{"type":"string"},"results":{"type":"object","description":"Trend results keyed by field name","additionalProperties":{"type":"array","items":{"type":"object","properties":{"facet_value":{"type":"string","description":"Aggregated value"},"facet_count":{"type":"integer","description":"Article count"},"growth_rate":{"type":"number","description":"Growth rate (when trending=1)"},"change":{"type":"integer","description":"Absolute change (when compare=1)"},"trending_score":{"type":"number","description":"Trending score (when compare=1)"},"time_bucket":{"type":"string","description":"Time bucket (when time_bucket is set)"},"enrichment":{"type":"object","description":"Enriched entity/category/topic data","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"}}}}}}}}},"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"}}}}}}}}}}}},"/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}}}}}}},"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"}}}}}}}}},"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"}}}}}}}}}}}}},"servers":[],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}]}