vasus.ai API

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.

API status: operational Reference mode + 7 new conditions — rolling out
Base URL 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.

HEADER
X-Api-Key: your-api-key-here
Consumer key

Public app access. Rate limited to 5 calls/day per anonymous session. Grants access to /v1/insight and /v1/ehspi.

Tenant key (B2B)

Enterprise access. Higher rate limits, access to all endpoints, webhook support, usage analytics. Used server-side only.

⚠ Never expose API keys client-side. All B2B keys should be used server-side only.

Quickstart

Make your first call in under 60 seconds.

cURL
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"
  }'
Python
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).

TierEndpointLimitWindowReset
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.

StatusMeaningCommon 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

POST /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

FieldTypeRequiredDescription
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

FieldTypeDescription
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

JSON 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
  }
}
GET /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

ParameterTypeDefaultDescription
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
curl "https://exposomic-api-1055369236229.us-central1.run.app/v1/ehspi?sensitivity=all&mode=lifetime" \
  -H "X-Api-Key: YOUR_API_KEY"
GET /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

ParameterTypeDescription
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.
GET /health No auth required

Health check

Returns API operational status. No authentication required. Used for uptime monitoring and deployment verification.

Response · 200 OK
{"status": "ok", "api_version": "1.7"}
Ready to integrate?
Free API access. 30-minute founder call.
Request API access →