API

Health

Your own health data, sync, sharing, Sexual Activity, export and delete; what others share with you; Mirage server leaderboards.

See Health. /v1/me/health is always the caller's own data and /v1/health what others share with them. Health belongs to people, never an organization: personal keys act for their maker only when the person allowed it in Health → Privacy, and privacy settings change only in the apps.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/me/health/profile`	Your Health settings: the consent you agreed to (and each sensitive category's), time zone, pinned metrics, Caity's and API access, Sexual Activity's sharing, and whether your account is known to be 18 or over (`adult`, `ageUnknown`; never the date of birth itself).
`PATCH /v1/me/health/profile`	Changes your time zone (days are your local days) or Summary's pinned metrics (`pinned`, up to 12, in order). `timeZoneChange`: `moved` keeps past days in the zone they were lived in; `correction` replaces the zone back to your last move and works those days out again (`recompute`). Without it, the first time you set a zone is a correction and later ones are moves.
`POST /v1/me/health/consent`	Agrees to Health's terms (`version`, the current one). Nothing is stored before. In the app only.
`DELETE /v1/me/health/consent`	Withdraws consent: nothing new is stored, every share and leaderboard opt-in ends, Caity's and API access turn off. Your data stays until you delete it. In the app only.
`PUT /v1/me/health/categories/:category/consent`	Turns a sensitive category on or off (`on`): Cycle Tracking, Medications, Mental Wellbeing, Symptoms, and Sexual Activity (18 or over). Off ends its sharing. In the app only.
`PUT /v1/me/health/assistant`	Caity's access (`enabled`, `categories`): summaries only; standard categories unless you name some, sensitive ones only when named, Sexual Activity never. In the app only.
`PUT /v1/me/health/api-access`	Lets personal API keys and connected apps with `health:read` or `health:write` act for you (`on`). Off by default. In the app only.
`GET /v1/me/health/metrics`	The metric registry as you can use it (Sexual Activity only when you're known to be 18 or over), the categories, and your state for each metric you have data in (count, first and last sample, months, unit, sharing).
`GET /v1/me/health/summary`	Summary: your pinned metrics (today, the last seven days, the average and the trend against the week before), highlights, and the categories you have data in.
`GET /v1/me/health/metrics/:metricId/chart`	A metric's chart: `range` `D` (hours of `end`), `W` and `M` (days), `6M` (weeks) or `Y` (months), ending on `end` (a day; today by default), with the average, range, total and best day. Where sources overlapped, a point's `sources` names those that counted.
`GET /v1/me/health/metrics/:metricId/samples`	A metric's samples, newest first (`limit` up to 200; `from` and `to` in milliseconds; `cursor` from the last page). Sexual Activity's entries include their partner (`name`, `userId`), only ever to you.
`PUT /v1/me/health/metrics/:metricId/unit`	The unit you see a metric in (`unit`, one of its units).
`PATCH /v1/me/health/metrics/:metricId/samples/:sampleId`	Changes an entry made in the apps (value in `unit`, times, note, protection, partner). Samples from HealthKit change there and sync here.
`DELETE /v1/me/health/metrics/:metricId/samples/:sampleId`	Deletes a sample; the day's values, totals and leaderboard scores follow.
`POST /v1/me/health/samples`	Adds samples (entries in the apps, or a batch from elsewhere).
`POST /v1/me/health/sync`	The phone's HealthKit sync: new and changed samples, and ones deleted there. `?partial=1` (the phone, from its sync with `done`): it stops starting parts after `SYNC_BUDGET_MS` and says how far it got (`done`), and the phone sends the rest.
`GET /v1/me/health/sync/changes`	Entries made in the apps since `cursor`, for the phone to write to HealthKit.
`GET /v1/me/health/sources`	Your data sources (the Watch, the phone, apps, entries made here) in order: where data overlaps, the higher one wins. `recompute`: how far your history is in being worked out again after a new order.
`PUT /v1/me/health/sources/order`	Orders your sources (`order`: source ids, first wins; the rest keep their order after). Your whole history is worked out again under the new order in the background (`recompute`). In the app only.
`GET /v1/me/health/sharing`	Your sharing: rules per category and metric, the rule in force for every metric, Sexual Activity's own sharing, and how many people follow you and you follow on Mirage.
`PUT /v1/me/health/sharing/:scope/:id`	Shares a metric or category (`audience`: `only_me`, `friends` (mutual follows), `followers`, `following` or `public`; `detail`: `aggregates` or `samples`). Sensitive categories share aggregates only; Sexual Activity only through its own settings. In the app only.
`DELETE /v1/me/health/sharing/:scope/:id`	Removes a metric's or category's own rule (a metric then follows its category; a category goes back to Only Me). In the app only.
`PUT /v1/me/health/sexual/sharing`	Sexual Activity's own sharing, separate from everything else: an `audience` and which aggregates (`counts`, `protectionRate`, `partnerCount`), with `confirm: true` whenever anything is shared. Never names or dates of entries; viewers must be 18 or over. In the app only.
`GET /v1/me/health/sharing/preview`	How a viewer in an audience sees the person's shared Health (nothing is recorded).
`GET /v1/me/health/sexual/summary`	Your Sexual Activity counts (this week, month, year and all time), the protection-used rate, and how many different partners your entries name. 404 unless the category is on.
`GET /v1/me/health/leaderboards`	Your leaderboard opt-ins (server and metric) and the Mirage servers you're in, each with its leaderboards as `GET /v1/health/servers/:serverId` returns them (`health`; `null` when they couldn't be read).
`GET /v1/me/health/audit`	Your Health audit, newest first: consents, sharing changes, leaderboard opt-ins, Caity's reads, exports, and who viewed what you share (once a day each). In the app only.
`GET /v1/me/health/export`	Your data, a page at a time (`cursor` from the last page): the first page also has your profile, sources, sharing and metric states; partners included.
`POST /v1/me/health/delete-all`	Deletes everything; call again while `done` is false.
`GET /v1/health/people/:userId`	What someone shares with you: each metric's last 30 days, today, streaks and best day (samples only where they chose), and Sexual Activity's aggregates they opted in, when you're both 18 or over. Empty when you're in none of their audiences. Your view is in their audit once a day.
`GET /v1/health/servers/:serverId`	A Mirage server's Health leaderboards for a member: the settings, the metrics that can rank, whether you can manage them, whether you're known to be 18 or over (`adult`), and the metrics you opted in there.
`PUT /v1/health/servers/:serverId/settings`	Turns a server's Health leaderboards on or off and picks metrics (`enabled`, `metrics`). Manage Server.
`PUT /v1/health/servers/:serverId/opt-ins/:metricId`	Ranks you with a metric on this server's leaderboards (it must be one the server chose); your scores are written at once.
`DELETE /v1/health/servers/:serverId/opt-ins/:metricId`	Stops ranking: your opt-in and every score for that server and metric go.
`GET /v1/health/servers/:serverId/leaderboards/:metricId`	A server's board (`period` `week`, `month` or `all`; `at` a past period such as `w2026-10-05` or `m2026-10`): members who opted in, ranked, up to 100. Members only.