Read-only endpoints for searching, browsing, and filtering global news events.
Create an account to unlock higher rate limits (200 req/60s vs 30 for anonymous).
X-API-Key: <your-key>
30 req / 60s per IP
The X-API-Key header is optional — anonymous requests are allowed at a lower rate limit. Authenticated requests get 200 req/60s.
curl "/api/search?q=climate+policy" \
-H "X-API-Key: your-key-here"| Method | Path | Description |
|---|---|---|
| GET | /api/search | Hybrid semantic + keyword search via RRF |
| GET | /api/clusters | Active event clusters with optional filtering |
| GET | /api/clusters/{id} | Single cluster with all member articles |
| GET | /api/articles | Recent articles, newest first |
| GET | /api/stats | Total articles, clusters, embeddings, largest cluster |
| Param | Type | Description |
|---|---|---|
| q | string (required) | Search query |
| limit | int (1–100, default 20) | Max results |
| semantic_weight | float (0–1, default 0.5) | Balance between semantic and keyword scoring |
| clusters | bool | Include cluster-level results |
| location | string | Filter by location name |
| person | string | Filter by person name |
| org | string | Filter by organization |
| theme | string | Filter by GDELT theme code |
| domain | string | Filter by source domain |
| source | string | Filter by source name |
| date_from | ISO date | Start date filter |
| date_to | ISO date | End date filter |
curl "/api/search?q=earthquake+Turkey&semantic_weight=0.7&location=Turkey&limit=10" \
-H "X-API-Key: your-key-here"| Param | Type | Description |
|---|---|---|
| limit | int (default 20) | Max clusters to return |
| sort | string | Sort by: recent or articles |
| location | string | Filter by location |
| person | string | Filter by person |
| org | string | Filter by organization |
| theme | string | Filter by theme |
| domain | string | Filter by domain |
| source | string | Filter by source |
| date_from | ISO date | Start date |
| date_to | ISO date | End date |
Returns the cluster metadata along with all member articles.
curl "/api/clusters?sort=articles&theme=MILITARY_CONFLICT&limit=20" \
-H "X-API-Key: your-key-here"| Param | Type | Description |
|---|---|---|
| limit | int (1–200, default 50) | Max articles to return |
| location | string | Filter by location name |
| person | string | Filter by person |
| org | string | Filter by organization |
| theme | string | Filter by GDELT theme code |
| domain | string | Filter by source domain |
| source | string | Filter by source name |
| date_from | ISO date | Start date filter |
| date_to | ISO date | End date filter |
Returns total articles, clusters, embeddings, sources, themes, and largest cluster size.
The machine-readable spec is available at /api/openapi.json — import it into Postman, Insomnia, or any OpenAPI-compatible tooling.