SAVIOROFHEALTH DATA API

Documentation

Anonymized, k-anonymity-gated aggregates from a young-adult health panel: survey distributions, symptom radar, behavioral cohorts and AI signal reports, as plain JSON over HTTPS. Base URL: https://saviorofhealth.app/api/v1

Aggregates only

No individual records. Slices under k=5 are suppressed server-side.

Approval-gated

Keys issued per organization after manual review. Revocable any time.

Usage-metered

Per-plan daily limits. Every call is logged.

Authentication

Every request needs your access key in the Authorization header. Keys look like hs_live_…, are shown exactly once at issuance, and are stored by us only as a SHA-256 hash. Each key carries scopes (e.g. insights:read). Calls outside your scopes return 403.

REQUEST

curl https://saviorofhealth.app/api/v1/insights \
  -H "Authorization: Bearer hs_live_xxxxxxxxxxxxxxxxxxxx"

Plans & rate limits

basic1,000 req/dayFree, for evaluation & academic use

pro10,000 req/dayCommercial research. Contact us

enterprise100,000 req/dayCustom SLA, dedicated support

Limits reset at 00:00 UTC. Exceeding them returns 429. Check consumption any time via /api/v1/meta/usage.

k-Anonymity

Every aggregate slice must contain at least k = 5 distinct respondents. Below that, the API suppresses the slice: distributions return empty with "suppressed": true, time-series points return "value": null. This is enforced server-side and cannot be bypassed by any key. Raw personal records are never exposed through any endpoint. Reporting windows are fixed (7 / 30 / 90 / 365 days) and cohort sizes are rounded to the nearest 5, so overlapping queries cannot be differenced down to one person. Every response carries the license line: aggregate-only, no re-identification.

SURVEYS & INSIGHTS

GET/api/v1/surveysinsights:read

Catalog of every active survey question on the panel, with live response volume. Use the returned key with /insights/{key}.

REQUEST

curl https://saviorofhealth.app/api/v1/surveys \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "surveys": [
    {
      "key": "survey-sleep",
      "type": "survey",
      "category": "sleep",
      "question": "How many hours did you sleep last night?",
      "options": ["Under 5", "5–6", "7–8", "8 or more"],
      "predict": true,
      "sponsor": "Longevity Research Collective",
      "responses": 1204
    }
  ]
}

GET/api/v1/insightsinsights:read

Answer distributions + age-cohort splits for every survey that clears the k-anonymity gate.

REQUEST

curl https://saviorofhealth.app/api/v1/insights \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "insights": [
    {
      "key": "survey-sleep",
      "question": "How many hours did you sleep last night?",
      "n": 1204,
      "breakdown": [ { "option": "7–8", "n": 496, "pct": 41.2 } ],
      "cohorts":   [ { "cohort": "25–29", "topAnswer": "5–6", "pct": 39, "n": 402 } ]
    }
  ]
}

GET/api/v1/insights/{key}insights:read

One survey in depth: full distribution, cohort splits and a daily response trend.

ParamTypeDescription

keypathSurvey key from /surveys (e.g. survey-sleep)

daysquery · int · default 30Reporting window: 7 · 30 · 90 · 365 (other values round up to the next window)

REQUEST

curl "https://saviorofhealth.app/api/v1/insights/survey-sleep?days=30" \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "insight": {
    "key": "survey-sleep",
    "n": 1204,
    "breakdown": [ { "option": "7–8", "n": 496, "pct": 41.2 } ],
    "cohorts":   [ { "cohort": "25–29", "topAnswer": "5–6", "pct": 39, "n": 402 } ],
    "trend":     [ { "date": "2026-07-01", "n": 88 } ]
  }
}

RADAR

GET/api/v1/radarradar:read

Live symptom prevalence across the panel with 3-day trend deltas. An early-warning signal for what young adults are feeling right now.

ParamTypeDescription

regionquery · string · optionalMacro-region filter (e.g. East Asia). Omit for Global.

REQUEST

curl "https://saviorofhealth.app/api/v1/radar?region=East%20Asia" \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "radar": {
    "region": "East Asia",
    "signals": [
      {
        "key": "symptom-today",
        "question": "Anything bothering you today?",
        "n": 861,
        "items": [
          { "option": "Fatigue", "n": 292, "pct": 33.9, "deltaPct3d": +4.1 }
        ]
      }
    ]
  }
}

COHORTS & TRENDS

GET/api/v1/cohortscohorts:read

Behavioral averages from health logs, grouped by age cohort or region: sleep hours, water intake, mood, exercise, meditation.

ParamTypeDescription

metricquery · enumsleep | water | mood | exercise | meditation

byquery · enum · default ageage | region

daysquery · int · default 30Reporting window: 7 · 30 · 90 · 365 (other values round up to the next window)

REQUEST

curl "https://saviorofhealth.app/api/v1/cohorts?metric=sleep&by=age&days=30" \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "cohorts": {
    "metric": "sleep",
    "unit": "hours",
    "groups": [
      { "group": "25–29", "avg": 6.4, "n": 140 }
    ]
  }
}

GET/api/v1/trendstrends:read

Daily time series for any metric. Days with fewer than k distinct users return value: null with suppressed: true.

ParamTypeDescription

daysquery · int · default 30Reporting window: 7 · 30 · 90 · 365 (other values round up to the next window)

REQUEST

curl "https://saviorofhealth.app/api/v1/trends?metric=mood&days=30" \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "trends": {
    "metric": "mood",
    "series": [
      { "date": "2026-07-01", "value": 3.6, "n": 74 },
      { "date": "2026-07-02", "value": null, "n": 3, "suppressed": true }
    ]
  }
}

PANEL

GET/api/v1/demographicsdemographics:read

Panel composition: how many respondents per age cohort and macro-region.

REQUEST

curl https://saviorofhealth.app/api/v1/demographics \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "demographics": {
    "panelSize": 4210,
    "ageCohorts": [ { "group": "25–29", "n": 1382 } ],
    "regions":    [ { "group": "East Asia", "n": 2114 } ]
  }
}

GET/api/v1/panelpanel:read

Panel health: total size, lifetime response volume, and a daily-active-users series.

ParamTypeDescription

daysquery · int · default 30Reporting window: 7 · 30 · 90 · 365 (other values round up to the next window)

REQUEST

curl "https://saviorofhealth.app/api/v1/panel?days=30" \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "panel": {
    "panelSize": 4210,
    "totalResponses": 58211,
    "dailyActive": [ { "date": "2026-07-01", "activeUsers": 311 } ]
  }
}

CAMPAIGNS & PARTNER

GET/api/v1/campaignscampaigns:read

Every live commissioned campaign with its questions and response volumes.

REQUEST

curl https://saviorofhealth.app/api/v1/campaigns \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "campaigns": [
    {
      "key": "meridian-metabolic",
      "org": "Meridian Metabolic Clinic",
      "kind": "clinical",
      "live": true,
      "questions": [ { "key": "survey-metabolic", "responses": 412 } ]
    }
  ]
}

GET/api/v1/my/campaignscampaigns:read

Full results for campaigns commissioned by YOUR organization (matched by the client id bound to your API key, never by name). Powers the Partner Portal. Clinicians can also view this in a dashboard at /partner.

REQUEST

curl https://saviorofhealth.app/api/v1/my/campaigns \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "org": "Meridian Metabolic Clinic",
  "campaigns": [
    {
      "key": "meridian-metabolic",
      "title": "Metabolic health & GLP-1 awareness (Q3)",
      "results": [
        {
          "question": "Have you tried or considered a GLP-1 product?",
          "n": 412,
          "breakdown": [ { "option": "Considering it", "n": 178, "pct": 43.2 } ],
          "cohorts":   [ { "cohort": "25–29", "pct": 47, "n": 156 } ],
          "trend":     [ { "date": "2026-07-01", "n": 31 } ]
        }
      ]
    }
  ]
}

REPORTS & META

GET/api/v1/reports/weeklyreports:read

An AI-written narrative signal report over the panel's recent data: bullet insights with numbers plus a "watch next week" line. Cached for 15 minutes.

REQUEST

curl https://saviorofhealth.app/api/v1/reports/weekly \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "report": "• Fatigue mentions rose 4.1pp over 3 days, led by the 25–29 cohort…",
  "cachedForMinutes": 15
}

GET/api/v1/meta/usageinsights:read

Your key's consumption: calls today, lifetime total, plan and daily limit.

REQUEST

curl https://saviorofhealth.app/api/v1/meta/usage \
  -H "Authorization: Bearer $HS_KEY"

RESPONSE · 200

{
  "usage": { "org": "Acme Research", "plan": "pro", "today": 412, "total": 12894, "dailyLimit": 10000 }
}

Errors

401Missing / invalid / revoked / expired key

403Key lacks the required scope, or client not approved

404Unknown resource (e.g. survey key)

429Daily rate limit exceeded. Retry after 00:00 UTC

400Invalid parameter (message explains which)

All errors are JSON: { "error": "…" }

Commissioned a campaign?

View your survey results in a dashboard at the Partner Portal with the same key, no code needed. Programmatic access: /api/v1/my/campaigns.

REQUEST ACCESS

Apply for an API key

We review within 2 business days and reply by email.