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.

The Stories API returns AI-generated story clusters for a given category within a news batch. Each story aggregates multiple source articles into a single object enriched with a short summary, talking points, quotes, geopolitical context, timelines, and more. Two variants are available: one that targets a specific batch by UUID, and a convenience shortcut that always returns the latest published batch.

​
Endpoints

​
Get stories for a batch category

Returns all story clusters for a specific category in a named batch. 
GET /api/batches/{batchId}/categories/{categoryId}/stories

​
Path parameters

​
batchId
string
required
UUID of the batch to query (e.g. "550e8400-e29b-41d4-a716-446655440000"). Retrieve available batch IDs from GET /api/batches.
​
categoryId
string
required
Category identifier as returned by GET /api/categories/metadata or GET /api/batches/{batchId}/categories (e.g. "world", "technology").

​
Query parameters

​
lang
string
BCP 47 language code for the response content (e.g. en, es, fr). Falls back to the batch’s default language when omitted or when the requested language is unavailable.
​
limit
integer
Maximum number of stories to return. The Kagi News UI requests up to 12 stories per category by default.

​
Example request

curl "https://kite.kagi.com/api/batches/550e8400-e29b-41d4-a716-446655440000/categories/world/stories"

​
Get stories for the latest batch

Shortcut that resolves to the most recently published batch. Identical response shape to the versioned endpoint. 
GET /api/batches/latest/categories/{categoryId}/stories
​
categoryId
string
required
Category identifier (e.g. "world", "technology").
​
lang
string
BCP 47 language code for the response content.
​
limit
integer
Maximum number of stories to return.

​
Example request

curl "https://kite.kagi.com/api/batches/latest/categories/world/stories"

​
Response

Both endpoints return a BatchStoriesResponse object.
​
batchId
string
required
UUID of the batch the stories belong to.
​
categoryId
string
required
Identifier of the requested category.
​
categoryName
string
required
Human-readable name of the category.
​
timestamp
number
required
Unix timestamp (seconds) at which this batch was generated.
​
stories
Story[]
required
Ordered array of story cluster objects. See the Story object section below.
​
totalStories
number
required
Total number of stories available in this category for this batch (may be larger than the number returned when limit is used).
​
domains
Domain[]
required
Deduplicated list of all source domains referenced across all returned stories.
​
readCount
number
required
Aggregate read count for stories in this category/batch.

​
Story object

Each element of the stories array is a fully-enriched story cluster.
​
id
string
Unique story identifier. May be absent for legacy records.
​
cluster_number
number
required
Ordinal position of this cluster within the batch/category.
​
unique_domains
number
Number of distinct news sources that contributed articles to this cluster.
​
number_of_titles
number
Count of distinct article titles aggregated into this story.
​
sourceLanguage
string
BCP 47 code of the language in which the source articles were written.
​
selectedLanguage
string
BCP 47 code of the language actually used for this story’s generated content.
​
category
string
required
Sub-category or topic label assigned by the AI pipeline.
​
title
string
required
AI-generated headline for the story cluster.
​
short_summary
string
required
One-to-two sentence summary of the story.
​
did_you_know
string | null
An interesting contextual fact related to the story, suitable for a callout.
​
talking_points
string[] | null
Bullet-point list of key talking points or highlights.
​
quote
string | null
A notable direct quotation from a source or figure in the story.
​
quote_author
string | null
Name of the person attributed with the quote.
​
quote_attribution
string | null
Role or title of the quote author.
​
quote_source_url
string | null
URL of the source article containing the quote.
​
quote_source_domain
string | null
Domain of the source article containing the quote.
​
location
string | null
Primary geographic location relevant to the story (e.g. "Washington D.C., USA").
​
emoji
string | null
A single emoji that visually represents the story topic.
​
perspectives
Perspective[] | null
​
timeline
TimelineEvent[] | null
​
suggested_qna
QnA[] | null
​
geopolitical_context
string | null
Broader geopolitical background relevant to the story.
​
travel_advisory
string[] | null
Travel advisories or safety notices relevant to the story location.
​
destination_highlights
string | null
Notable highlights for a travel destination featured in the story.
​
culinary_significance
string | null
Culinary or food-related context for the story.
​
performance_statistics
string[] | null
Performance or statistical highlights relevant to the story.
​
league_standings
string | null
Current league standings context where applicable.
​
diy_tips
string | null
Practical do-it-yourself tips related to the story.
​
design_principles
string | null
Design principles or aesthetic considerations relevant to the story.
​
user_experience_impact
string | null
User experience or consumer-facing implications described in the story.
​
gameplay_mechanics
string[] | null
Gameplay mechanics or interactive features described in gaming stories.
​
industry_impact
string[] | null
Broader industry-level implications of the story.
​
gaming_industry_impact
string[] | null
Gaming-industry-specific implications of the story.
​
technical_specifications
string[] | null
Technical specifications or product details highlighted in the story.
​
historical_background
string | null
Historical context that helps explain why the story matters.
​
international_reactions
string[] | null
List of notable reactions from international actors.
​
humanitarian_impact
string | null
Description of humanitarian effects or human-interest angle.
​
economic_implications
string | null
Summary of economic effects or financial implications.
​
future_outlook
string | null
Forward-looking analysis or anticipated developments.
​
key_players
string[] | null
List of notable individuals, organizations, or entities central to the story.
​
technical_details
string[] | null
Technical or specialist details relevant to the story.
​
business_angle_text
string | null
Narrative summary of the business or market angle.
​
business_angle_points
string[] | null
Bullet points elaborating on the business implications.
​
user_action_items
string[] | null
Practical steps or actions a reader might take in response to the story.
​
scientific_significance
string[] | null
Key scientific or research findings highlighted by the story.
​
primary_image
object | null
​
secondary_image
object | null
Same shape as primary_image. A supplementary illustration for the story.
​
expanded
boolean
UI hint indicating whether this story cluster is expanded in the default view.
​
articles
Article[]
required
Source articles that were clustered into this story.
​
domains
Domain[]
Source domain metadata for the articles in this story. See the Domain object below.

​
Example response

{
  "batchId": "550e8400-e29b-41d4-a716-446655440000",
  "categoryId": "world",
  "categoryName": "World",
  "timestamp": 1718000000,
  "totalStories": 24,
  "readCount": 1042,
  "domains": [
    { "name": "bbc.com", "favicon": "https://bbc.com/favicon.ico", "isPaywalled": false }
  ],
  "stories": [
    {
      "id": "story-abc123",
      "cluster_number": 1,
      "unique_domains": 6,
      "number_of_titles": 14,
      "category": "Diplomacy",
      "title": "G7 Leaders Agree on New Climate Finance Framework",
      "short_summary": "Finance ministers from the G7 nations reached a landmark agreement on climate funding, pledging $500 billion over five years to support developing economies.",
      "emoji": "🌍",
      "location": "Rome, Italy",
      "talking_points": [
        "$500 billion pledge over five years",
        "Funds directed to developing economies",
        "Binding annual review mechanism included"
      ],
      "quote": "This is the most ambitious climate finance package ever assembled.",
      "quote_author": "Janet Yellen",
      "quote_attribution": "U.S. Treasury Secretary",
      "timeline": [
        { "date": "June 2024", "date_iso": "2024-06-01", "content": "G7 summit opens in Rome" },
        { "date": "June 3, 2024", "date_iso": "2024-06-03", "content": "Finance framework agreement signed" }
      ],
      "articles": [
        {
          "title": "G7 strikes historic climate deal",
          "link": "https://bbc.com/news/world/g7-climate",
          "domain": "bbc.com",
          "date": "2024-06-03"
        }
      ]
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us