Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JasonHonKL/spy-search/llms.txt

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

The news endpoint retrieves current headlines from DuckDuckGo’s news backend, organised by category. It uses the DuckDuckGoSearchResults LangChain tool with backend="news" and returns up to 8 articles per request, including titles, snippets, links, dates, and source names.

​
News Endpoint

GET /news/{category} Returns a JSON object containing an array of news articles for the requested category.

​
Example request

curl http://localhost:8000/news/technology

​
Example response

{
  "news": [
    {
      "title": "OpenAI releases new reasoning model",
      "snippet": "The company announced a new model capable of multi-step reasoning...",
      "link": "https://techcrunch.com/2024/...",
      "date": "2024-11-15T10:30:00",
      "source": "TechCrunch"
    },
    {
      "title": "Apple unveils next-generation chip",
      "snippet": "Apple's M4 chip delivers a 40% performance improvement...",
      "link": "https://theverge.com/2024/...",
      "date": "2024-11-14T08:00:00",
      "source": "The Verge"
    }
  ]
}
Each article object contains the fields returned directly by DuckDuckGo’s news backend. The date field is an ISO 8601 timestamp string.

​
Supported Categories

Each category maps to a pre-defined DuckDuckGo search query. The mapping is defined in DuckSearch.today_new():
Category slugDuckDuckGo query string
technologylatest tech AI news
financelatest finance market news
entertainmentlatest entertainment news
sportslatest sports news
worldlatest world news
healthlatest health news
If you pass an unrecognised category slug, the engine falls back to "latest news".

​
Fetch a specific category

# Technology
curl http://localhost:8000/news/technology

# Finance
curl http://localhost:8000/news/finance

# Health
curl http://localhost:8000/news/health

​
Frontend Integration

The Discover page in the React frontend (frontend/src/pages/News.tsx) consumes this endpoint directly. It renders a responsive card grid with article titles, snippets, publication dates, and source badges. Clicking a card opens the original article in a new tab. Category navigation is rendered as a pill-button row using the same six slugs listed in the table above. The icons used per category are:
CategoryIcon
TechnologyTrendingUp
FinanceDollarSign
EntertainmentGamepad2
SportsTrophy
WorldGlobe
HealthHeart
The frontend implements a 10-minute client-side cache using lastFetchTime. Switching to a category that was fetched within the last 10 minutes reuses the stored results without making a new network request. Passing forceRefresh = true to the internal fetchNews function bypasses this check. 
const tenMinutes = 10 * 60 * 1000;
if (!forceRefresh && (now - lastFetch) < tenMinutes) {
  return; // serve from cache
}

​
Rate Limits

DuckDuckGo does not publish an official rate limit for its search backend. However, sending requests too frequently can trigger temporary throttling or empty responses. Guidelines:
  • The frontend’s built-in 10-minute cache is a reasonable minimum interval for casual browsing.
  • For production deployments or automated pipelines, a 60-second minimum interval between requests per category is recommended.
  • If the news request fails, the DuckSearch.today_new() method catches the exception, logs the error, and returns an empty list — the API response will contain {"news": []}.
Combine news with report generation by passing a headline as part of your query. For example, fetch the top technology headlines, pick one that interests you, then send it to POST /report/ to get a full research report on that topic with live sources.
curl -X POST "http://localhost:8000/report/OpenAI+new+reasoning+model" \
  -F 'messages=[{"role":"user","content":"OpenAI new reasoning model"}]'

Build docs developers (and LLMs) love

Get started for freeTalk to us