Decluttered News API

Frontend/data consumers can use the endpoints below. ← Back to app

Base URL

https://api.declutterednews.com

1) List available cities

GET /api/cities — returns all cities with available news data.

https://api.declutterednews.com/api/cities
{
  "cities": [
    { "slug": "toronto", "label": "Toronto" },
    { "slug": "bengaluru", "label": "Bengaluru" },
    { "slug": "san-francisco", "label": "San Francisco" }
  ]
}

2) Latest feed (rolling)

GET /api/latest?city=<slug> — last 12h, ranked by importance (includes score/matchScore per item).

https://api.declutterednews.com/api/latest?city=toronto

3) List available archive days

GET /api/days?city=<slug>

https://api.declutterednews.com/api/days?city=toronto
{
  "city": "toronto",
  "days": ["2026-02-13", "2026-02-12"]
}

4) Get digest for a specific day

GET /api/digest/<YYYY-MM-DD>?city=<slug>

https://api.declutterednews.com/api/digest/2026-02-13?city=san-francisco
{
  "date": "2026-02-13",
  "city": "san-francisco",
  "items": [
    {
      "title": "...",
      "summary": "...",
      "category": "Business",
      "layer": "global",
      "links": ["https://..."],
      "sources": ["BBC"],
      "source_ids": ["bbc.com"],
      "image": "https://...",
      "publishedAt": "2026-02-13T...Z",
      "score": 61,
      "matchScore": 61
    }
  ]
}

5) Look up story by URL

GET /api/lookup/url?url=<article_url> — resolve an article URL to its canonical story record. Tracking parameters (utm_*, fbclid, etc.) are stripped automatically.

https://api.declutterednews.com/api/lookup/url?url=https://example.com/article?utm_source=twitter
{
  "storyId": "a3f9c2b1d4e5f6a7b8c9d0e1",
  "canonical": "example.com/article",
  "story": {
    "storyId": "a3f9c2b1d4e5f6a7b8c9d0e1",
    "title": "...",
    "summary": "...",
    "category": "Business",
    "links": ["https://example.com/article"],
    "sources": ["Example News"],
    "publishedAt": "2026-02-13T10:00:00Z"
  }
}

Returns 404 if the URL has not been ingested. Returns 400 if the URL is missing or unparseable.

6) Look up URLs by story ID

GET /api/lookup/story/<storyId> — reverse lookup: given a story ID, return all source URLs for that story.

https://api.declutterednews.com/api/lookup/story/a3f9c2b1d4e5f6a7b8c9d0e1
{
  "storyId": "a3f9c2b1d4e5f6a7b8c9d0e1",
  "links": [
    "https://example.com/article",
    "https://othersource.com/same-story"
  ],
  "story": { ... }
}

Returns 404 if the story ID is not found.

7) Lightweight health check

GET /api/health (fast warm ping endpoint)

8) DB health (debug)

GET /api/health/db (internal diagnostics)

Score fields

Notes