API
Read-only JSON API. All requests are GET; pass method
and endpoint as query string. Responses are JSON with
Content-Type: application/json; charset=utf-8.
No authentication or rate-limit gate today; please be reasonable.
Conventions
- Base URL:
http://intelligence.flatnine.test/api - Error format:
{"error": "<message>"}with HTTP 4xx/5xx; happy responses are 200. - Pagination:
limitis the only knob; cursor-based pagination is not implemented yet. - Time: all timestamps are UTC, formatted
YYYY-MM-DD HH:MM:SS. - Stability: shapes shown below are tracked; new fields may appear, existing ones won't disappear without a deprecation note.
-
Rate limits: 60 requests / minute and 600 requests / hour
per IP. Every response carries
X-RateLimit-LimitandX-RateLimit-Remainingheaders; over the limit returns429with aRetry-Afterseconds value. Get in touch if you need a higher cap for a real workload.
health / ping
Liveness check. Returns the active environment.
No parameters.
Example
curl -s 'http://intelligence.flatnine.test/api?method=health&endpoint=ping'Response shape
{"ok": true, "env": "production"}claims / feed
Paged claim feed, same query the homepage uses. Each row carries the AI-written multi-paragraph summary in summary_text (may be null if not yet cached).
Parameters
cat- category slug; matches itself or any direct child (e.g. geopolitics → all sub-regions)
tier- calibration tier: high | medium | low
sort- movers (default, by ABS delta) | confidence | recent | signal
t- time window for delta sort/label: 24h | 7d (default) | 30d
limit- 1-100, default 50
Example
curl -s 'http://intelligence.flatnine.test/api?method=claims&endpoint=feed&cat=geopolitics_europe&tier=medium&t=7d&limit=20'Response shape
{"claims": [{"id": 187, "sentence_text": "...", "confidence": 0.71, "summary_text": "Multi-paragraph context...", "summary_at": "2026-05-06 12:30:00", ...}, ...]}claims / detail
Full single-claim payload: sentence, confidence, every delta window, parsed signals, AI-written summary, severity/narrative tags, pattern type, and the primary entities resolved to {id, name, entity_type, wikidata_qid}.
Parameters
id- claim id (required)
Example
curl -s 'http://intelligence.flatnine.test/api?method=claims&endpoint=detail&id=187'Response shape
{"claim": {"id": 187, "sentence_text": "...", "confidence": 0.71, "confidence_delta_7d": -0.12, "signals": {...}, "summary_text": "...", "pattern_type": "rising_edge", "category_slug": "geopolitics_middle_east", "primary_entity_ids": [1, 25], "entities": [{"id": 1, "name": "Iran", "entity_type": "place", "wikidata_qid": "Q794"}, ...]}}claims / feed_summary
The cached AI-written situation paragraph that sits above the homepage feed for a given filter combination. Returns null when no cached summary exists yet — the homepage generates one lazily on its next visit.
Parameters
cat- category slug (optional)
sort- movers (default) | confidence | recent | signal
t- 24h | 7d (default) | 30d
tier- all (default) | high | medium | low
top_n- 1-50, default 12 (number of top claims the summary covers)
Example
curl -s 'http://intelligence.flatnine.test/api?method=claims&endpoint=feed_summary&cat=geopolitics_middle_east&sort=movers&t=7d'Response shape
{"summary": "Tensions across the Middle East...", "cached_at": "2026-05-06 14:00:00", "top_n": 12, "claim_ids": [187, 191, 203, ...]}entities / top
Top entities by gravity (recursive PageRank).
Parameters
type- entity_type filter: place | person | org | topic | indicator
limit- 1-200, default 50
Example
curl -s 'http://intelligence.flatnine.test/api?method=entities&endpoint=top&type=place&limit=20'Response shape
{"entities": [{"id": 1, "name": "Iran", "wikidata_qid": "Q794", "gravity": 0.140, "gravity_momentum": 0.012}, ...]}entities / graph
Force-directed graph payload — nodes + co-mention edges over a recent window. Powers /entities?view=graph.
Parameters
limit- top-N entities by gravity to include, default 80, max 500
since_days- co-mention edge window, default 30, max 60
type- restrict nodes to one entity_type
region- restrict nodes to one region (middle_east, europe, americas, asia_pacific, africa, global)
center- optional entity id; switches to neighbourhood mode
depth- with center, hops: 1 (default) or 2
Example
curl -s 'http://intelligence.flatnine.test/api?method=entities&endpoint=graph¢er=1&depth=1&since_days=30'Response shape
{"nodes": [{"id": 1, "label": "Iran", "type": "place", "region": "middle_east", "gravity": 0.140, "momentum": 0.012}, ...], "edges": [{"source": 1, "target": 2, "weight": 348.2, "count": 612}, ...]}events / geo
Geo events for the homepage heatmap and entity / claim maps. Two modes via mode= : cells (server-aggregated heatmap cells) or points (raw events).
Parameters
mode- cells (default for homepage) | points
since_days- 1-120, default 30
entity_id- restrict to events linked to this entity
claim_id- restrict to events linked to this claim
limit- points-mode only, default 1000
Example
curl -s 'http://intelligence.flatnine.test/api?method=events&endpoint=geo&claim_id=187&mode=points&since_days=30'Response shape
{"type": "FeatureCollection", "features": [...], "count": 642, "mode": "cells"}