# 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

```bash
# 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](/know/api-authentication). 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](/know/api-overview), [Authentication, scopes, and rate limits](/know/api-authentication), and the full machine reference at `/api/docs`.