{"openapi":"3.1.0","info":{"title":"Featured News API","version":"1.0.0","summary":"Read and cite every live Featured News story.","description":"Read-only JSON over the stories published on https://news.featured.com/: roundups of verified experts' perspectives on the news, expert bylines and interviews, each edited by a named Featured News editor. Full stories are here for reading, answering questions about the news and citing; quote experts by name, title and company and link to the canonical story. Republishing a story on another site needs an approved Featured News publisher account.\n\nLicense: Free to read, quote and cite with a link. Republishing is licensed only to approved Featured News publishers through the publisher hub (apply: https://news.featured.com/publishers).\n\nNo authentication. Only live stories are exposed. Every HTML page is also available as markdown (Accept: text/markdown, a .md suffix or ?mode=agent). Errors are JSON: {\"error\": {\"code\", \"message\", \"hint\"}}.\n\nRate limits: 60 requests per 60 seconds per client IP across /api/v1/* and /api/mcp, enforced at the edge. Every response carries RateLimit-Policy: \"per-ip\";q=60;w=60. Over the limit you receive HTTP 429; wait for the window to reset (at most 60 seconds) before retrying.\n\nVersioning and deprecation: Path-versioned: /api/v1/ is stable and only gains optional fields. A breaking change ships under a new major path (/api/v2/), and /api/v1/ keeps serving for at least 90 days after the new version launches, announced in advance with Deprecation and Sunset response headers (RFC 9745, RFC 8594), in llms.txt and on https://news.featured.com/ai.\n\nWhen to use it: https://news.featured.com/llms.txt.","contact":{"name":"Featured News team","email":"news@featured.com","url":"https://news.featured.com/contact"},"license":{"name":"Featured News Republication License 1.0","url":"https://news.featured.com/publishers#license"},"termsOfService":"https://news.featured.com/publishers"},"externalDocs":{"description":"Guide for AI assistants and search","url":"https://news.featured.com/ai"},"servers":[{"url":"https://news.featured.com"}],"tags":[{"name":"stories"},{"name":"directory"}],"paths":{"/api/v1/stories":{"get":{"operationId":"listStories","tags":["stories"],"summary":"List live stories, newest first","description":"A page of live stories with their summary fields. Filter by beat and format. Use getStory with a slug for the full text.","parameters":[{"name":"beat","in":"query","required":false,"description":"Beat slug from listBeats, for example technology-ai.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"roundups (several experts on one news question), bylines (written by an expert) or interviews (one expert).","schema":{"type":"string","enum":["roundups","bylines","interviews"]}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Stories per page.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"A page of stories","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"pages":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"limit":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorySummary"}}},"required":["page","pages","total","limit","items"]}}}},"400":{"description":"Invalid parameters. The error names the parameter and the accepted values.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stories/{slug}":{"get":{"operationId":"getStory","tags":["stories"],"summary":"Get one live story in full","description":"Every perspective with the expert's name, title, company and profile link, or the byline or interview text, plus corrections, attribution, license and the whole story as markdown.","parameters":[{"name":"slug","in":"path","required":true,"description":"The story slug: the path of its URL.","schema":{"type":"string","minLength":1,"maxLength":300}}],"responses":{"200":{"description":"The story","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Story"}}}},"404":{"description":"No live story, beat or endpoint matches the request.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/search":{"get":{"operationId":"searchStories","tags":["stories"],"summary":"Search live stories","description":"Case-insensitive match on headlines, deks, the question asked, and the names and companies of the experts quoted. Best for 'what do experts say about X' or 'stories quoting someone from Y'.","parameters":[{"name":"q","in":"query","required":true,"description":"Search terms.","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Matching stories, newest first","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"page":{"type":"integer","minimum":1},"pages":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorySummary"}}},"required":["query","page","pages","total","items"]}}}},"400":{"description":"Invalid parameters. The error names the parameter and the accepted values.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/beats":{"get":{"operationId":"listBeats","tags":["directory"],"summary":"List beats","description":"The news beats stories are filed under, with their topics and live story counts.","responses":{"200":{"description":"Beats","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Beat"}}},"required":["items"]}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/authors":{"get":{"operationId":"listAuthors","tags":["directory"],"summary":"List guest authors","description":"Experts with at least one live byline, alphabetically, with their author page.","responses":{"200":{"description":"Guest authors","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Author"}}},"required":["items"]}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Safe to retry.","headers":{"RateLimit-Policy":{"description":"The quota policy (draft-ietf-httpapi-ratelimit-headers): 60 requests per 60 seconds per IP.","schema":{"type":"string","example":"\"per-ip\";q=60;w=60"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Person":{"type":"object","description":"A named expert as shown on the story page.","properties":{"name":{"type":"string"},"title":{"type":["string","null"],"description":"Job title"},"company":{"type":["string","null"]},"city":{"type":["string","null"]},"profileUrl":{"type":["string","null"],"format":"uri","description":"The expert's public profile"}},"required":["name","title","company","city","profileUrl"]},"Author":{"allOf":[{"$ref":"#/components/schemas/Person"},{"type":"object","properties":{"bio":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri","description":"Author page on this site"}},"required":["bio","url"]}]},"StorySummary":{"type":"object","properties":{"slug":{"type":"string","description":"Stable identifier; the story lives at /{slug}."},"url":{"type":"string","format":"uri","description":"Canonical HTML page"},"markdownUrl":{"type":"string","format":"uri","description":"The same story as text/markdown"},"apiUrl":{"type":"string","format":"uri"},"format":{"type":"string","enum":["roundups","bylines","interviews"]},"headline":{"type":"string"},"description":{"type":"string","description":"One-sentence summary"},"dek":{"type":["string","null"]},"beat":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"]},"topics":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["topic","location"]}},"required":["slug","name","kind"]}},"publishedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"image":{"oneOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"},"alt":{"type":["string","null"]}},"required":["url","alt"]},{"type":"null"}]},"editor":{"oneOf":[{"type":"object","properties":{"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"}},"required":["name","url"]},{"type":"null"}]},"author":{"oneOf":[{"$ref":"#/components/schemas/Author"},{"type":"null"}],"description":"Byline or interview subject"},"expertCount":{"type":"integer","minimum":0},"newsHook":{"oneOf":[{"type":"object","description":"The news report the story responds to","properties":{"title":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"source":{"type":["string","null"]}},"required":["title","url","source"]},{"type":"null"}]}},"required":["slug","url","markdownUrl","apiUrl","format","headline","description","dek","beat","topics","tags","publishedAt","updatedAt","image","editor","author","expertCount","newsHook"]},"Story":{"allOf":[{"$ref":"#/components/schemas/StorySummary"},{"type":"object","properties":{"intro":{"type":["string","null"],"description":"Markdown"},"perspectives":{"type":"array","description":"Roundups only: each expert's perspective, verbatim, in story order.","items":{"type":"object","properties":{"position":{"type":"integer"},"url":{"type":"string","format":"uri"},"heading":{"type":["string","null"]},"quote":{"type":"string"},"expert":{"oneOf":[{"$ref":"#/components/schemas/Person"},{"type":"null"}]}},"required":["position","url","heading","quote","expert"]}},"body":{"type":["string","null"],"description":"Bylines only: the article as markdown"},"qa":{"oneOf":[{"type":"array","description":"Interviews only","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]}},{"type":"null"}]},"corrections":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["Correction","Clarification","Update"]},"note":{"type":"string"},"date":{"type":"string","format":"date-time"}},"required":["kind","note","date"]}},"disclosure":{"type":["string","null"]},"attribution":{"type":"string","description":"The attribution sentence approved publishers keep when republishing"},"license":{"type":"string"},"markdown":{"type":"string","description":"The complete story as one markdown document"},"republish":{"$ref":"#/components/schemas/Republish"}},"required":["intro","perspectives","body","qa","corrections","disclosure","attribution","license","markdown","republish"]}]},"Republish":{"type":"object","description":"Who may republish the story on another site. Reading, quoting and citing with a link are free; republishing is licensed only to approved Featured News publishers.","properties":{"allowed":{"type":"string","enum":["approved publishers only"]},"apply":{"type":"string","format":"uri","description":"Where a publisher applies"},"license":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"terms":{"type":"string"}},"required":["name","url","terms"]}},"required":["allowed","apply","license"]},"Beat":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"},"stories":{"type":"integer","minimum":0,"description":"Live stories on the beat"}},"required":["slug","name","topics","url","stories"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Stable, machine-readable code"},"message":{"type":"string"},"hint":{"type":"string","description":"How to fix the request"}},"required":["code","message"]}},"required":["error"]}}}}