API Documentation

All endpoints return JSON unless otherwise noted. No authentication required.

Base URL
http://localhost:3000
Data Endpoints
GET /api/briefing

Returns the latest sweep data from all sources as a JSON object. Contains source statuses, counts, alerts, and timestamps.

curl http://localhost:3000/api/briefing
GET /api/briefing/llm

Generates an AI-powered intelligence briefing from the latest sweep data using Groq cloud or a local Ollama model.

Query Parameters
model Model identifier, e.g. groq:llama-3.3-70b-versatile optional
lang Language for the briefing: es or en (default: es) optional
key Custom Groq API key optional
curl "http://localhost:3000/api/briefing/llm?model=groq:llama-3.3-70b-versatile&lang=es"
GET /api/ollama/models

Lists available LLM models (from Ollama and Groq), including the currently selected model and Ollama availability status.

curl http://localhost:3000/api/ollama/models
History & Alerts
GET /api/history/:sourceId

Returns historical sweep data for a specific source. Used for sparkline charts in the dashboard.

Path Parameters
sourceId Source identifier, e.g. usgs, firms, gdelt
Query Parameters
limit Number of records to return (default: 50, max: 500) optional
curl "http://localhost:3000/api/history/usgs?limit=50"
GET /api/alerts

Returns the last 100 alerts generated by sweep analysis. Includes severity levels, source IDs, and timestamps.

curl http://localhost:3000/api/alerts
Export
GET /api/export/json

Downloads the latest sweep data as a JSON file attachment.

curl -O http://localhost:3000/api/export/json
GET /api/export/csv

Downloads the latest sweep data as a CSV file attachment with columns: source_id, ok, count, ts.

curl -O http://localhost:3000/api/export/csv
Scope & Region
GET /api/scope

Returns the current geographic scope and all available scopes.

curl http://localhost:3000/api/scope
GET /api/scope/:scope

Changes the active geographic scope. Triggers a new sweep with the updated bounding box and notifies all connected SSE clients.

Path Parameters
scope One of: sa, eu, na, asia, meast, africa
curl http://localhost:3000/api/scope/sa
Real-time Streaming
GET /api/stream

Server-Sent Events (SSE) endpoint for real-time data. Sends the latest briefing on connect and pushes new sweep data as it arrives. Each message is a JSON object with a type field.

curl -N http://localhost:3000/api/stream