Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kagisearch/kite-public/llms.txt

Use this file to discover all available pages before exploring further.

All data served by the Kagi News API — and consumed by the open-source front-end — is typed in TypeScript in src/lib/types.ts. This page documents every type and every field so you can build confidently on top of the Kagi News data, whether you are customizing the front-end or building an entirely new client. Optional fields that are not applicable for a given story are omitted (returned as null or absent) in API responses. You should always treat optional fields as potentially null or undefined.

​
Story

The Story type is the central data structure. It represents one cluster of articles about a single real-world event, enriched with AI-generated analysis.
​
id
string
Unique identifier for the story, assigned by the server. May be absent on legacy records.
​
cluster_number
number
required
Sequential cluster number within its category for the current batch. Used for ordering and internal references.
​
unique_domains
number
The number of distinct publisher domains that contributed articles to this cluster. A higher value indicates broader multi-source coverage.
​
number_of_titles
number
The total number of article titles considered when forming this cluster. Reflects how widely the event was reported.
​
sourceLanguage
string
ISO 639 language code of the original source articles (e.g., "en", "fr", "de").
​
selectedLanguage
string
The language code actually used for the text content of this story in the current response. Set when the user has requested a specific language.
​
category
string
required
The name of the category this story belongs to (e.g., "Technology", "World News").
​
title
string
required
AI-generated headline for the story.
​
short_summary
string
required
One-paragraph plain-language summary of the event.
​
did_you_know
string | null
A surprising or lesser-known fact related to the story topic.
​
talking_points
string[] | null
Bullet-point list of the most important facts about the event.
​
quote
string | null
A representative quotation from a key figure or source.
​
quote_author
string | null
Name of the person being quoted.
​
quote_attribution
string | null
Role or title of the quoted person (e.g., “Prime Minister of Canada”).
​
quote_source_url
string | null
URL to the original source where the quote appeared.
​
quote_source_domain
string | null
Domain of the source where the quote appeared (e.g., "reuters.com").
​
location
string | null
Primary geographic location of the event (e.g., "Geneva, Switzerland").
​
perspectives
Perspective[] | null
Array of distinct viewpoints from different sources. Each Perspective has a text summary and a sources array of {name, url} pairs. See Perspective.
​
emoji
string | null
A single emoji that visually represents the story topic.
​
geopolitical_context
string | null
Broader geopolitical framing for the event.
​
historical_background
string | null
Relevant historical context that helps explain the current event.
​
international_reactions
string[] | null
How countries, international bodies, or notable figures have responded.
​
humanitarian_impact
string | null
Human cost, displacement, or humanitarian consequences, if applicable.
​
economic_implications
string | null
Market, trade, or macroeconomic effects of the event.
​
timeline
TimelineEvent[] | null
Chronological sequence of key developments. Each entry is a TimelineEvent. See TimelineEvent.
​
future_outlook
string | null
Expected next steps, likely developments, or open questions.
​
key_players
string[] | null
Notable individuals or organizations involved in the event.
​
technical_details
string[] | null
Technical specifics relevant to technology or science stories.
​
business_angle_text
string | null
Narrative business analysis of the event.
​
business_angle_points
string[] | null
Bullet-point business analysis.
​
user_action_items
string[] | null
Practical steps a reader might take in response to the story.
​
scientific_significance
string[] | null
Why the event matters to the scientific community.
​
travel_advisory
string[] | null
Travel-related warnings or advisories for travel stories.
​
destination_highlights
string | null
Key attractions or features for destination-focused stories.
​
culinary_significance
string | null
Food culture context for culinary stories.
​
performance_statistics
string[] | null
Key stats for sports or performance stories.
​
league_standings
string | null
Current standings summary for sports categories.
​
diy_tips
string | null
Practical tips for do-it-yourself stories.
​
design_principles
string | null
Design thinking or principles relevant to the story.
​
user_experience_impact
string | null
How the event affects user experience in products or services.
​
gameplay_mechanics
string[] | null
Game mechanics described for gaming-related stories.
​
industry_impact
string[] | null
Broad industry effects of the event.
​
gaming_industry_impact
string[] | null
Specific effects on the gaming industry.
​
technical_specifications
string[] | null
Detailed technical specs for product or engineering stories.
​
suggested_qna
QnA[] | null
Question-and-answer pairs for deeper understanding. Each entry has question and answer string fields. See QnA.
​
primary_image
object | null
Primary illustration image. Contains url (string), caption (string), and optional credit (string).
​
secondary_image
object | null
Secondary illustration image. Same shape as primary_image.
​
articles
Article[]
required
The source articles that were clustered into this story. See Article.
​
domains
Domain[] | null
Metadata about each publisher domain that contributed to this story. See Domain.

​
Article

An Article is a single source article included within a story cluster.
​
title
string
required
The original headline of the article as published by the source.
​
link
string
required
Full URL to the article on the publisher’s website.
​
domain
string
required
The publisher domain (e.g., "bbc.com").
​
date
string
required
Publication date of the article (ISO 8601 string).
​
image
string
URL of the article’s lead image, if available.
​
image_caption
string
Caption for the article image, if available.

​
Domain

The Domain type carries publisher metadata for a domain that appears in a story.
​
name
string
required
The domain name (e.g., "reuters.com").
​
favicon
string
URL to the domain’s favicon, used for source attribution icons in the UI.
​
isPaywalled
boolean
true if the publisher is known to require a subscription to read full articles.

​
Category

A Category is a named grouping of stories, backed by one or more RSS feeds.
​
name
string
required
The internal name of the category (e.g., "Technology").
​
id
string
required
URL-safe slug identifier for the category (e.g., "technology"). Used in API paths and routing.
​
display_name
string
Localized display name shown in the UI for the user’s selected language.
​
feeds
string[]
List of RSS/Atom feed URLs backing this category. Present for community categories; may be absent for core categories.

​
BatchInfo

BatchInfo describes a single daily batch — the immutable snapshot of all news for one day.
​
id
string
required
UUID that uniquely identifies this batch.
​
createdAt
string
required
ISO 8601 timestamp of when the batch was published (always 12:00 PM UTC for live batches).
​
language
string
required
The language code for which this batch record applies.
​
totalCategories
number
required
The number of categories included in this batch.
​
totalClusters
number
required
The total number of story clusters across all categories.
​
totalArticles
number
required
The total number of source articles across all clusters.
​
chaosIndex
number
The Chaos Index score for this batch: a value from 0 to 100 reflecting global news intensity.
​
chaosDescription
string
A short human-readable description explaining the Chaos Index score for this day.
​
chaosLastUpdated
string
ISO 8601 timestamp of the most recent Chaos Index calculation.

​
Perspective

A Perspective represents one distinct viewpoint on a story, drawn from a particular source or group of sources.
​
text
string
required
A summary of the perspective in plain language.
​
sources
object[]
required
Array of source attributions. Each entry contains:
  • name (string) — display name of the source outlet
  • url (string) — URL to the specific article expressing this perspective

​
TimelineEvent

A TimelineEvent is one entry in a story’s chronological timeline.
​
date
string
required
Human-readable date label (e.g., "March 14, 2025").
​
date_iso
string
ISO 8601 date string for programmatic use (e.g., "2025-03-14").
​
content
string
required
Description of what happened at this point in the timeline.

​
QnA

A QnA is a single question-and-answer pair from a story’s suggested_qna section.
​
question
string
required
A suggested question a reader might have about the story.
​
answer
string
required
The AI-generated answer to the question.

​
OnThisDayEvent

OnThisDayEvent represents a historical event, notable person, or anniversary surfaced in the “On This Day” section of a batch.
​
year
string
required
The year in which the historical event occurred (as a string, e.g., "1969").
​
content
string
required
Description of the historical event or person.
​
sort_year
number
required
Numeric year used for sorting entries chronologically.
​
type
"event" | "person" | "people"
required
Classifies the entry: event for historical occurrences, person for an individual’s birthday or anniversary, people for a group.
​
image
string
URL of an image associated with the event or person.

​
Minimal Story Example

The following JSON shows a trimmed but structurally complete story object. In real API responses, optional null fields are typically omitted entirely. 
{
  "id": "abc123",
  "cluster_number": 1,
  "unique_domains": 12,
  "number_of_titles": 18,
  "sourceLanguage": "en",
  "selectedLanguage": "en",
  "category": "Technology",
  "title": "Major AI Lab Releases Open-Weight Model",
  "short_summary": "A leading AI research organization has released a new open-weight language model, making the weights freely available for research and commercial use.",
  "talking_points": [
    "Model weights are available under a permissive license.",
    "Benchmarks show competitive performance with closed models.",
    "Release includes fine-tuning guides and evaluation datasets."
  ],
  "perspectives": [
    {
      "text": "Researchers welcome the release as a step toward reproducible science.",
      "sources": [
        { "name": "Nature News", "url": "https://www.nature.com/articles/example" }
      ]
    }
  ],
  "timeline": [
    { "date": "January 10, 2025", "date_iso": "2025-01-10", "content": "Lab announces research preview." },
    { "date": "March 5, 2025", "date_iso": "2025-03-05", "content": "Full weights published." }
  ],
  "primary_image": {
    "url": "https://example.com/image.jpg",
    "caption": "Researchers at the lab review benchmark results.",
    "credit": "Example News / Jane Doe"
  },
  "articles": [
    {
      "title": "Lab Releases Open AI Model Weights",
      "link": "https://techcrunch.com/2025/03/05/example",
      "domain": "techcrunch.com",
      "date": "2025-03-05T14:00:00Z"
    }
  ],
  "domains": [
    { "name": "techcrunch.com", "isPaywalled": false }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us