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 Legacy EHSPI scores — all 20 cities
Legacy endpoint — remains available for existing integrations but is no longer part of the current platform direction. Not recommended for new integrations.
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 Legacy EHSPI 90-day time series
Legacy endpoint — remains available for existing integrations but is no longer part of the current platform direction. Not recommended for new integrations.
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"}