Environmental health intelligence delivered as infrastructure.
One POST call returns real-time risk scoring, AI-synthesised analysis, and inline peer-reviewed citations for any location and chronic condition — or, in reference mode, a no-environment literature synthesis driven by a biomarker or longevity metric.
https://exposomic-api-1055369236229.us-central1.run.app Getting started
Authentication
All API endpoints (except /health) require an
API key passed in the X-Api-Key request header.
Keys are issued per tenant and scoped to specific endpoints and rate limits.
X-Api-Key: your-api-key-here
Public app access. Rate limited to 5 calls/day per anonymous session. Grants access to /v1/insight and /v1/ehspi.
Enterprise access. Higher rate limits, access to all endpoints, webhook support, usage analytics. Used server-side only.
Quickstart
Make your first call in under 60 seconds.
curl -s -X POST \
https://exposomic-api-1055369236229.us-central1.run.app/v1/insight \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profile": {"sensitivities": ["migraine"]},
"location": {"lat": 51.5074, "lon": -0.1278},
"exposure_window_hours": 24,
"exposure_direction": "future",
"mode": "agentic",
"session_token": "your-session-uuid"
}' import requests, uuid
response = requests.post(
"https://exposomic-api-1055369236229.us-central1.run.app/v1/insight",
headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={
"profile": {"sensitivities": ["migraine"]},
"location": {"lat": 51.5074, "lon": -0.1278},
"exposure_window_hours": 24,
"exposure_direction": "future",
"mode": "agentic",
"session_token": str(uuid.uuid4())
}
)
data = response.json()
print(data["insight"]["risk_level"]) # "Moderate"
print(data["insight"]["summary"]) # AI-synthesised paragraph
print(len(data["top_matches"])) # number of citations Rate limits
Applied per anonymous session token (consumer tier) or per API key (tenant tier).
| Tier | Endpoint | Limit | Window | Reset |
|---|---|---|---|---|
| Consumer (public) | /v1/insight | 5 calls | Per day | Midnight UTC |
| Consumer (public) | /v1/ehspi | Unlimited | — | Cached response |
| Tenant (B2B) | All endpoints | Custom | Per agreement | Rolling window |
Errors
Standard HTTP status codes. Error bodies follow a consistent shape with a detail field.
| Status | Meaning | Common cause |
|---|---|---|
400 | Bad Request | Missing required field, invalid sensitivity, malformed location |
401 | Unauthorised | Missing or invalid X-Api-Key header |
422 | Unprocessable Entity | Schema validation failure — unknown field or value out of range |
429 | Too Many Requests | Daily session limit reached. Resets at midnight UTC |
451 | Unavailable For Legal Reasons | Location in restricted territory (geo-blocking applied) |
500 | Internal Server Error | Pipeline failure — retryable. Contact support if persistent |
503 | Service Unavailable | Upstream environmental data provider temporarily unavailable |
Endpoints
/v1/insight 🔑 Requires API key Environmental health insight
The primary endpoint. Accepts a health sensitivity, location and time window and returns a complete AI-synthesised environmental health assessment grounded in real-time environmental signals and peer-reviewed evidence. Powers the public research tool at app.vasus.ai.
The pipeline runs four stages: (1) environmental signal ingestion from Google AQ, Weather and Pollen APIs; (2) semantic retrieval from 535,000+ PubMed papers; (3) LLM gate for citation relevance filtering; (4) AI synthesis producing a condition-specific risk assessment with inline citations.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
profile | object | Required | Health profile. Contains sensitivities: array of sensitivity strings. |
location | object | Required | Geographic coordinates: lat, lon as WGS84 decimal degrees. Not required in reference mode. |
exposure_window_hours | integer | Required | Time window: 6, 24, or 72. Longer windows return richer trend signals. |
exposure_direction | string | Required | "future" for forecast or "past" for retrospective analysis. |
mode | string | Required | "baseline" — single-pass. "agentic" — full planner + citations (production default). "reference" — no environment, literature mode. |
session_token | string (UUID) | Optional | Anonymous session identifier for rate limiting. Client-generated UUID. Never linked to identity. |
context | object | Optional | Activity context. Supports activity: "mostly_indoors" | "mixed" | "mostly_outdoors". |
enrichment | object | Optional | Condition-specific personalisation: condition_subtype, known_triggers, onset_pattern, medication. Enables subtype-aware retrieval. |
partner_environment | object | Optional | Partner-supplied environmental readings. When present, Google API calls are skipped. For sensor-network or hyperlocal use cases. |
include_debug | boolean | Optional | Set true to include pipeline debug metadata: gate, query_plan, retrieval_enrichment, raw env signals. |
Response fields
| Field | Type | Description |
|---|---|---|
tenant_id | string | Tenant identifier derived from the API key. |
prompt_version | string | Synthesis prompt version. Current: v4.1. |
mode | string | Pipeline mode echoed from request. |
request_id | string | Unique request identifier for support and tracing. |
insight | object | AI-synthesised assessment with risk_level, summary, mechanism, recommendation, uncertainty_note. |
environment | object | Processed environmental signals for the requested location and window. |
top_matches | array | Peer-reviewed papers supporting the synthesis. Up to 10 items with PMID, title, journal, effect_size. |
_rate_limit | object | Rate limit status: calls_used, calls_remaining, limit. Consumer tier only. |
Example response
{
"tenant_id": "tenant_001",
"prompt_version": "v4.1",
"mode": "agentic",
"request_id": "a3f7e291-4bc2-4d88-98b1-4e2a3c7d5f01",
"insight": {
"risk_level": "Moderate",
"summary": "A rapid frontal passage is driving a 6.2 mb barometric pressure drop
over the next 24 hours — a pattern repeatedly associated with migraine
onset in the weather-sensitivity literature.",
"mechanism": "Barometric pressure changes activate trigeminal nociceptors...",
"recommendation": "Consider prophylactic measures for pressure-sensitive patients.",
"uncertainty_note": "Individual sensitivity varies significantly..."
},
"environment": {
"location": {"lat": 51.5074, "lon": -0.1278},
"signals": {
"barometric_pressure_delta_24h": -6.2,
"pressure_volatility_72h": 8.4,
"heat_index_mean_72h": 16.3
}
},
"top_matches": [
{
"pmid": "28718491",
"title": "Barometric pressure and migraine: meta-analysis of 7 studies",
"journal": "Headache",
"year": 2017,
"effect_size": "OR 1.31 (1.18–1.45)",
"fit_level": "High"
}
],
"_rate_limit": {
"calls_used": 1,
"calls_remaining": 4,
"limit": 5
}
} /v1/ehspi EHSPI scores — all 20 cities
Returns current EHSPI scores for all 20 monitored cities in one call. Scores are updated nightly and cached. Response includes composite score, five condition-specific scores, confidence label, and full weight_vectors object per city.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
sensitivity | string | "all" | Filter by sensitivity: "migraine" | "respiratory" | "cardiovascular" | "sleep" | "allergy" | "all" |
mode | string | "lifetime" | "lifetime" uses all available history. "recent" uses the last 30 days only. |
curl "https://exposomic-api-1055369236229.us-central1.run.app/v1/ehspi?sensitivity=all&mode=lifetime" \ -H "X-Api-Key: YOUR_API_KEY"
/v1/ehspi/history EHSPI 90-day time series
Returns 90 days of nightly EHSPI scores per city tile as a time series array. Suitable for trend analysis, seasonal pattern detection, and historical reporting. Data confidence reflects how many days have been ingested per tile.
Query parameters
| Parameter | Type | Description |
|---|---|---|
city | string | City name as returned by /v1/ehspi (e.g. "London, UK"). URL-encode spaces. |
sensitivity | string | Condition sensitivity. Same values as /v1/ehspi. |
days | integer | Number of days to return. Max 90. Default 90. |
/health No auth required Health check
Returns API operational status. No authentication required. Used for uptime monitoring and deployment verification.
{"status": "ok", "api_version": "1.7"}