QlearNews API
Visit QlearNews Swagger Docs Contact sales@mypenmail.com

News intelligence endpoints for articles, trends, summaries, and story clusters.

This page is a quick reference for the current QlearNews backend API. Most public JSON endpoints are available directly from https://api.mypenmail.info.

API Reference

JSON is public and CORS-enabled for https://mypenmail.info. Use /docs or /openapi.json for the OpenAPI reference when available.

Core feed

GET /articles

Lists articles with category, source, timeframe, sorting, and pagination support.

/articles?category=news&page=1&pageSize=30
Search

GET /search?q=...

Searches articles using full-text search and fallback matching. Also supports category and pagination.

/search?q=redstone&category=crypto&page=1&pageSize=10
Story clusters

GET /api/story-clusters?q=...

Searches articles, expands matching cluster memberships, and attaches cluster-level signals.

/api/story-clusters?q=redstone&category=crypto&page=1&pageSize=9
Trending

GET /trending / GET /api/trending

Returns latest trending topics by category, including momentum, mentions, source counts, context, and sample headlines.

/api/trending?category=tech&limit=10
Categories

GET /categories

Lists available backend categories and labels.

/categories
Scores

GET /scores

Signal/scores route used by the backend for score-related article data.

/scores
Summaries

GET /summaries / GET /api/summaries

General summary route alias. Useful for summary data exposed outside the category summary endpoint.

/api/summaries
Category summaries

GET /api/category-summaries

Returns twice-daily AI editorial summaries by category, including summary text, bullets, and cluster metadata.

/api/category-summaries
Daily digest

GET /api/daily-digest

Returns the generated daily digest content used by the frontend digest component.

/api/daily-digest
Market trends

GET /api/market-trends

Returns market trend/report data used by the reports and market-watch UI.

/api/market-trends
Health

GET /health

Health check route for uptime checks and deployment validation.

/health
Ops

GET /metrics

Prometheus/business metrics endpoint. May be used internally for monitoring.

/metrics
Docs

GET /docs / GET /openapi.json

Swagger UI and machine-readable OpenAPI schema.

/docs
/openapi.json
Auth

/auth

Authentication routes for account/session features. Methods and payloads depend on the auth route implementation.

/auth
Comments

/comments

Comment routes for article/community features. Some operations may require authentication.

/comments

Common article/search query params

q=<search-term> category=news|tech|finance|sports|politics|crypto|vr|world|local|entertainment|life source=<source-name> since=YYYY-MM-DD HH:mm:SS sort=published_on:desc sort=published_on:asc sort=last_seen:desc sort=first_seen:desc page=1 pageSize=30

Story cluster query params

q=<search-term> category=<category> page=1 pageSize=9 articleDiscoverySize=30 perClusterLimit=8

Trending query params

category=news|tech|finance|sports|politics|crypto|vr|world|local|entertainment limit=10

Quick examples

/articles?category=news&pageSize=30 /articles?category=finance&sort=published_on:desc&pageSize=30 /articles?source=cnet&sort=published_on:desc&pageSize=30 /search?q=artificial intelligence&category=tech&pageSize=30 /api/story-clusters?q=redstone&category=crypto&page=1&pageSize=9 /api/story-clusters?q=trump&category=politics&page=1&pageSize=9 /api/trending?category=tech&limit=10 /api/category-summaries /api/daily-digest /api/market-trends

Backend Pipeline Reference

Current scheduled backend flow for article signals, story clusters, and summaries.

Frequent

cron_article_signals.sh

Refreshes article-level sentiment, urgency, optimism, and signal data.

00,30 * * * *
Frequent

cron_cluster_articles.sh

Runs storage/buildClusterArticles.js and writes story membership rows to dbo.cluster_articles.

05,35 * * * *
Frequent

cron_cluster_signals.sh

Runs storage/buildClusterSignals.js and writes cluster-level signal aggregates to dbo.cluster_signals.

10,40 * * * *
Frequent

cron_trending.sh

Refreshes trending topics.

*/15 * * * *
Twice daily

cron_category_summaries_morning.sh

Builds morning category summaries with Gemini.

15 7 * * *
Twice daily

cron_category_summaries_evening.sh

Builds evening category summaries with Gemini.

15 19 * * *
Twice daily

run_daily_digest.sh

Builds daily digest content.

0 0,12 * * *

Interactive Article Demo

JSON

Default limit 30. Use page and pageSize to paginate the JSON. Search uses /search; empty browsing uses /articles.