FYI static JSON API

Published articles for For Your Inference. Every resource is a generated static file. No token or account is required.

Resources

• /api/v1/stream.json — all published articles.
• /api/v1/categories.json — category IDs and names.
• /api/v1/categories/{id}.json — articles carrying one category.
• /api/v1/items/{id}.json — one article.
• /api/v1/schema.json — JSON Schema generated from the shared contract.

Response format

{"schemaVersion":2,"items":[]}

Category responses use categories; individual article responses use item. The array can be empty. Article ordering is original article date descending, then ID ascending. Category filters use the same records and ordering as the complete stream.

Article fields

• id
• headline
• impactRating
• dummies
• wonks
• detail
• analysis
• editorialStatus
• originalDate
• categories
• sources
• thumbnail
• dummiesThumbnail
• diagram
• notices
• publicationState
• publishedAt
• updatedAt

The content contract is version 2; resource paths remain under /api/v1/. Every article contains separate dummies and wonks objects, each with required summary, impact, and whyItMatters text. Impact is a short headline for why the story matters and appears before Why It Matters in both modes. The shared detail and analysis fields are optional Wonks additions, with unknown values represented by null. All authored text is plain text, never trusted HTML. Each item has at least one category, attributed sources, a thumbnail and alternative text, an editorial status, and an original date in YYYY-MM-DD form.

Media URLs use HTTPS or /media/filename, resolved against the API origin. Images, diagrams and source icons retain individual attribution notices. A notice marked fallback or unverified is not evidence of permission, ownership, or endorsement; unknown owners remain null.

Browser requests

const response = await fetch('https://fyi.today/api/v1/stream.json');
if (!response.ok) throw new Error('Feed unavailable');
const { items } = await response.json();

JSON responses permit public cross-origin reads. The cache lifetime is five minutes. Refetch on page load to see updates; publishing rebuilds the reader and feed together. Files are complete snapshots without query filters or pagination. Unknown IDs and paths return HTTP 404. The root path serves the public reader.

Publishing

The local editor creates a reviewed GitHub pull request. After merge, a separate manual build and deployment publishes the feed. Local validation never deploys. Drafts and unreferenced assets are excluded. The build stops before replacing output if a published record is invalid or an asset exceeds the configured limits.