mobieusCore API — mobieusHealth

4 min read · 760 words · 1 revision · Updated Jun 26, 2026
#api

mobieusCore API — mobieusHealth

The Health surface of the public REST API. A key reads and logs its own owner's mobieusHealth record — daily summary, weight, vitals, water, and activity. This surface is deliberately single-user: a key never sees, and can never address, any other member's health data.

Added in API version 1.19.0.

Privacy model — read this first

mobieusHealth entries are encrypted per member, and the platform rule is that tenant admins manage configuration and see aggregates but never an individual member's raw entries. The API honors that rule exactly:

  • Every endpoint operates on one user — the user who owns the API key. The owning user is taken only from the authenticated key, never from a path segment, query string, or request body.
  • There is deliberately no ?user_id= parameter and no /health/users/{id} form. A key minted by a super admin returns the admin's own entries and nothing else.
  • Aggregate or admin reporting is a separate admin-plane concern and is not part of this API.

Scopes, plan, and seat gate

Scope Grants
health:read Read the owner's daily summary, weight, vitals, water, and activity.
health:write Log the owner's weight, vitals, and water.

Generate a key at /admin/api-keys and tick the scopes you need. Like the rest of the public API, mobieusHealth endpoints are Pro / Creator Plus / Sovereign only.

Two extra gates apply on top of the plan gate:

  • The tenant must have mobieusHealth enabled. If it doesn't, every /api/v1/health/* path returns 404 — the surface is invisible, indistinguishable from a route that doesn't exist.
  • The key owner must hold an active mobieusHealth seat. Without one, calls return 403 health_no_access.

Quick start

# Today's totals vs goals, for the key owner
curl https://YOUR-TENANT.mobieus.io/api/v1/health/summary \
  -H 'Authorization: Bearer mc_live_...'

# Log this morning's weigh-in
curl -X POST https://YOUR-TENANT.mobieus.io/api/v1/health/weight \
  -H 'Authorization: Bearer mc_live_...' -H 'Content-Type: application/json' \
  -d '{"weight":182.4,"unit":"lb"}'

Resources

Summary

Method Path Scope What
GET /api/v1/health/summary health:read The owner's computed snapshot — today's intake versus goals. Returns 409 not_onboarded if the owner holds a seat but hasn't finished mobieusHealth onboarding.

Weight

Method Path Scope What
GET /api/v1/health/weight?from=&to= health:read The owner's weight series (defaults to the last 90 days; from/to are YYYY-MM-DD). Each point carries weight_kg (canonical) and weight in the profile's unit.
POST /api/v1/health/weight health:write Log a weigh-in. Body: {"weight_kg": number} or {"weight": number, "unit": "kg"|"lb"} (unit defaults to the profile's). Optional date (defaults to today; not in the future). Returns 201.

Vitals

Method Path Scope What
GET /api/v1/health/vitals?from=&to= health:read The owner's vitals series (default last 30 days). The response lists the available fields.
POST /api/v1/health/vitals health:write Merge-log a day's vitals. Body: any of systolic, diastolic, resting_hr, glucose, sleep_hours, energy, mood (numeric; at least one required), optional glucose_fasting (bool, with glucose), optional date. Returns 201.

Water

Method Path Scope What
GET /api/v1/health/water?from=&to= health:read The owner's daily water totals in fluid ounces (default last 30 days), plus water_goal_oz.
POST /api/v1/health/water health:write Add to a day's running total. Body: {"amount": number} in fluid ounces (negative corrects an over-log; the total floors at 0), optional date. Mirrors the in-app quick-add. Returns 201.

Activity

Method Path Scope What
GET /api/v1/health/activity?from=&to= health:read The owner's daily activity series (default last 30 days): steps, active_minutes, total_calories, and the day's individual sessions (type, duration, calories). Read-only over the API; log sessions in the app.

Range queries span at most 366 days; an out-of-range or malformed from/to is clamped to a valid window.

Errors

These use the standard error envelope. The health-specific codes:

HTTP error.code Meaning
403 health_no_access The key owner has no active mobieusHealth seat.
403 no_key_owner The key isn't tied to a user, so it has no personal record.
409 not_onboarded The owner has a seat but hasn't completed onboarding.
400 invalid_weight POST /weight without a positive weight_kg or weight.
400 no_readings POST /vitals with no recognized reading.
400 invalid_amount POST /water without a non-zero numeric amount.

See also: mobieusCore API — Overview, Authentication, scopes, and rate limits, and the full machine reference at /api/docs.

Contributors:
Last edited by mobieus · mobieusHealth API reference (v1.19.0)
Created Jun 26, 2026
Was this article helpful?

Related Pages