Docs
Developer Portal

API reference

Health

Your own health data, sync, sharing, Sexual Activity, export and delete; what others share with you; Mirage server leaderboards.
Read the Guide
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).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • timeZonestring

    Up to 64 characters.

  • timeZoneChange"moved" | "correction"
  • pinnedstring[]

    Up to 12 items. Each up to 48 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PATCH 'https://api.cactive.com.au/v1/me/health/profile' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "timeZone": "example",
    "timeZoneChange": "moved",
    "pinned": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
    recompute?: {
      state: "done" | "running"
      metrics: number
      done: number
      changed: number
      startedAt: number
      finishedAt?: number
    }
  }
}
POST/v1/me/health/consent

Agrees to Health's terms (version, the current one). Nothing is stored before. In the app only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • versionintegerrequired

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X POST 'https://api.cactive.com.au/v1/me/health/consent' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X DELETE 'https://api.cactive.com.au/v1/me/health/consent' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • category

    A Health category: activity, body, cycle, hearing, heart, medications, mental, mindfulness, mobility, nutrition, respiratory, sleep, symptoms, vitals, sexual or other.

Request body

  • onbooleanrequired

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/categories/{category}/consent' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "on": true
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • enabledbooleanrequired
  • categories("activity" | "body" | "cycle" | "hearing" | "heart" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual" | "other")[]

    Default []. Up to 16 items.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/assistant' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • onbooleanrequired

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/api-access' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "on": true
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
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).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/metrics' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  metrics: {
    metricId: string
    label: string
    category: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    kind: "duration" | "event" | "category" | "quantity"
    unit: string
    units: {
      id: string
      label: string
      factor: number
      offset?: number
    }[]
    aggregation: "duration" | "count" | "latest" | "sum" | "average"
    decimals: number
    sensitivity: "standard" | "sensitive" | "sexual"
    values?: {
      value: number
      label: string
    }[]
    healthKit?: {
      identifier: string
      kind: "category" | "quantity" | "workout"
      unit?: string
      readOnly?: boolean
      factor?: number
      categoryValues?: number[]
    }
    healthConnect?: string
    leaderboard?: "count" | "sum" | "average"
    min?: number
    max?: number
    pinned?: boolean
    description?: string
    enabled: boolean
    sortOrder: number
  }[]
  categories: {
    id: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    label: string
    glyph: "health-other" | "health-body" | "health-heart" | "health-cycle" | "health-activity" | "health-hearing" | "health-medications" | "health-mental" | "health-mindfulness" | "health-mobility" | "health-nutrition" | "health-respiratory" | "health-sleep" | "health-symptoms" | "health-vitals" | "health-sexual"
    sensitivity: "standard" | "sensitive" | "sexual"
    adultOnly?: true
  }[]
  states: {
    metricId: string
    unit?: string
    share?: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    count: number
    firstAt?: number
    lastAt?: number
    months: string[]
    updatedAt: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/summary' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  pinned: {
    metricId: string
    latest: null | {
      value: number
      at: number
    }
    today: null | number
    week: (null | number)[]
    average: null | number
    trend: null | "flat" | "up" | "down"
  }[]
  highlights: {
    metricId: string
    text: string
    kind: "best" | "trend" | "streak"
  }[]
  today: string
  categories: {
    id: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    metrics: number
    lastAt: null | number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Query parameters

  • range"D" | "W" | "M" | "6M" | "Y"

    Default "W".

  • endstring

    Matches ^\d{4}-\d{2}-\d{2}$.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/metrics/{metricId}/chart' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  metricId: string
  range: "M" | "D" | "W" | "6M" | "Y"
  buckets: {
    key: string
    from: string
    to: string
    value: null | number
    min: null | number
    max: null | number
    days: number
    sources?: string[]
  }[]
  stats: {
    days: number
    average: null | number
    total: null | number
    min: null | number
    max: null | number
    best: null | {
      day: string
      value: number
    }
  }
  today: string
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Query parameters

  • cursorstring

    Up to 2,000 characters.

  • frominteger

    Coerced from a string.

  • tointeger

    Coerced from a string.

  • limitinteger

    1–200. Coerced from a string.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/metrics/{metricId}/samples' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  samples: {
    sampleId: string
    metricId: string
    start: number
    end: number
    value: number
    stage?: number
    protection?: boolean | null
    partner?: {
      name?: string
      userId?: string
    }
    note?: string
    meta?: {
      [key: string]: boolean | string | number
    }
    sourceId: string
    sourceName: string
    external: boolean
    version: number
    createdAt: number
    updatedAt: number
  }[]
  cursor: null | string
}
PUT/v1/me/health/metrics/:metricId/unit

The unit you see a metric in (unit, one of its units).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Request body

  • unitstringrequired

    Up to 20 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/metrics/{metricId}/unit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "unit": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  metricId: string
  unit: string
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

  • sampleId

    A Health sample's id (hsm_…).

Request body

  • startinteger

    ≥ 0.

  • endinteger

    ≥ 0.

  • valuenumber
  • unitstring

    Up to 20 characters.

  • stageinteger
  • protectionbooleanor null
  • partnerobjector null
  • partner.namestring

    1–100 characters. Trimmed.

  • partner.userIdstring

    4–64 characters.

  • notestring

    Up to 1,000 characters.

  • metaobject

    Keys up to 40 characters. Values: string (up to 200 characters), number or boolean.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
curl -X PATCH 'https://api.cactive.com.au/v1/me/health/metrics/{metricId}/samples/{sampleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "start": 1,
    "end": 1,
    "value": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  sample: {
    sampleId: string
    metricId: string
    start: number
    end: number
    value: number
    stage?: number
    protection?: boolean | null
    partner?: {
      name?: string
      userId?: string
    }
    note?: string
    meta?: {
      [key: string]: boolean | string | number
    }
    sourceId: string
    sourceName: string
    external: boolean
    version: number
    createdAt: number
    updatedAt: number
  }
}
DELETE/v1/me/health/metrics/:metricId/samples/:sampleId

Deletes a sample; the day's values, totals and leaderboard scores follow.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

  • sampleId

    A Health sample's id (hsm_…).

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 404Sample not found.
curl -X DELETE 'https://api.cactive.com.au/v1/me/health/metrics/{metricId}/samples/{sampleId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 204 with no body

POST/v1/me/health/samples

Adds samples (entries in the apps, or a batch from elsewhere).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body (up to 2,048 KB)

  • samplesobject[]required

    1–500 items.

  • samples[].metricIdstringrequired

    1–48 characters.

  • samples[].startintegerrequired

    ≥ 0.

  • samples[].endinteger

    ≥ 0.

  • samples[].valuenumber
  • samples[].unitstring

    Up to 20 characters.

  • samples[].stageinteger
  • samples[].protectionbooleanor null
  • samples[].partnerobjector null
  • samples[].partner.namestring

    1–100 characters. Trimmed.

  • samples[].partner.userIdstring

    4–64 characters.

  • samples[].notestring

    Up to 1,000 characters.

  • samples[].metaobject

    Keys up to 40 characters. Values: string (up to 200 characters), number or boolean.

  • samples[].sourceobject
  • samples[].source.kind"watch" | "phone" | "app" | "manual"required
  • samples[].source.namestringrequired

    1–80 characters. Trimmed.

  • samples[].source.bundleIdstring

    Up to 200 characters.

  • samples[].source.devicestring

    Up to 120 characters.

  • samples[].externalIdstring

    1–100 characters.

  • samples[].versioninteger

    ≥ 0.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 413That's too much at once.
curl -X POST 'https://api.cactive.com.au/v1/me/health/samples' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "samples": [
      {
        "metricId": "<metricId>",
        "start": 1
      }
    ]
  }'
Send it from this page with your session or a key.

Response 201

{
  written: {
    sampleId: string
    metricId: string
    start: number
    end: number
    value: number
    stage?: number
    protection?: boolean | null
    partner?: {
      name?: string
      userId?: string
    }
    note?: string
    meta?: {
      [key: string]: boolean | string | number
    }
    sourceId: string
    sourceName: string
    external: boolean
    version: number
    createdAt: number
    updatedAt: number
  }[]
  skipped: {
    index: number
    reason: "invalid" | "older" | "duplicate"
    message?: string
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • partial"1"

Request body (up to 2,048 KB)

  • samplesany JSON[]

    Default []. Up to 500 items.

  • removals(object | object)[]

    Default []. Up to 500 items.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 413That's too much at once.
curl -X POST 'https://api.cactive.com.au/v1/me/health/sync' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "samples": [],
    "removals": []
  }'
Send it from this page with your session or a key.

Response 200

{
  written: number
  skipped: {
    index: number
    reason: "invalid" | "older" | "duplicate"
    message?: string
  }[]
  removed: number
  done: {
    samples: number
    removals: number
  }
}
GET/v1/me/health/sync/changes

Entries made in the apps since cursor, for the phone to write to HealthKit.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 100 characters.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/sync/changes' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  changes: {
    op: "delete"
    sampleId: string
    metricId: string
  } | {
    op: "put"
    sampleId: string
    metricId: string
    sample: {
      sampleId: string
      metricId: string
      start: number
      end: number
      value: number
      stage?: number
      protection?: boolean | null
      partner?: {
        name?: string
        userId?: string
      }
      note?: string
      meta?: {
        [key: string]: boolean | string | number
      }
      sourceId: string
      sourceName: string
      external: boolean
      version: number
      createdAt: number
      updatedAt: number
    }
  }[]
  cursor: string
  more: boolean
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/sources' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  sources: {
    sourceId: string
    name: string
    kind: "app" | "watch" | "phone" | "manual"
    bundleId?: string
    device?: string
    priority: number
    lastSeenAt: number
    createdAt: number
  }[]
  recompute: null | {
    state: "done" | "running"
    metrics: number
    done: number
    changed: number
    startedAt: number
    finishedAt?: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • orderstring[]required

    Up to 200 items. Each 1–64 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/sources/order' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "order": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  sources: {
    sourceId: string
    name: string
    kind: "app" | "watch" | "phone" | "manual"
    bundleId?: string
    device?: string
    priority: number
    lastSeenAt: number
    createdAt: number
  }[]
  recompute: null | {
    state: "done" | "running"
    metrics: number
    done: number
    changed: number
    startedAt: number
    finishedAt?: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/sharing' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  settings: {
    scope: "category" | "metric"
    id: string
    rule: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    updatedAt: number
  }[]
  effective: {
    [key: string]: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
  }
  sexualShare: {
    audience: "public" | "followers" | "following" | "friends" | "only_me"
    counts: boolean
    protectionRate: boolean
    partnerCount: boolean
    confirmedAt?: number
  }
  audiences: {
    onSocial: boolean
    followers: number
    following: number
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • scope

    metrics (one metric's rule) or categories (a category's rule, which its metrics follow unless they have their own).

  • id

    A record's id in Customers: its object's prefix and a time-sortable id (acc_…, cnt_…, led_…, opp_…, act_…).

Request body

  • audience"only_me" | "friends" | "followers" | "following" | "public"required
  • detail"aggregates" | "samples"

    Default "aggregates".

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/sharing/{scope}/{id}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "audience": "only_me"
  }'
Send it from this page with your session or a key.

Response 200

{
  settings: {
    scope: "category" | "metric"
    id: string
    rule: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    updatedAt: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • scope

    metrics (one metric's rule) or categories (a category's rule, which its metrics follow unless they have their own).

  • id

    A record's id in Customers: its object's prefix and a time-sortable id (acc_…, cnt_…, led_…, opp_…, act_…).

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X DELETE 'https://api.cactive.com.au/v1/me/health/sharing/{scope}/{id}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  settings: {
    scope: "category" | "metric"
    id: string
    rule: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    updatedAt: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • audience"only_me" | "friends" | "followers" | "following" | "public"required
  • countsbooleanrequired
  • protectionRatebooleanrequired
  • partnerCountbooleanrequired
  • confirmtrue

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/me/health/sexual/sharing' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "audience": "only_me",
    "counts": true,
    "protectionRate": true,
    "partnerCount": true
  }'
Send it from this page with your session or a key.

Response 200

{
  profile: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
}
GET/v1/me/health/sharing/preview

How a viewer in an audience sees the person's shared Health (nothing is recorded).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • as"friends" | "followers" | "following" | "public" | "stranger"required

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/sharing/preview?as=friends' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  userId: string
  metrics: {
    metricId: string
    detail: "samples" | "aggregates"
    today: null | number
    days: {
      day: string
      value: null | number
    }[]
    streak: number
    longestStreak: number
    best: null | {
      day: string
      value: number
    }
    average: null | number
    samples?: {
      value: number
      start: number
      stage?: number
      end: number
      sampleId: string
    }[]
  }[]
  sexual: null | {
    counts?: {
      week: number
      month: number
      year: number
      all: number
    }
    protectionRate?: null | number
    partnerCount?: number
  }
  defs: {
    metricId: string
    label: string
    category: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    kind: "duration" | "event" | "category" | "quantity"
    unit: string
    units: {
      id: string
      label: string
      factor: number
      offset?: number
    }[]
    aggregation: "duration" | "count" | "latest" | "sum" | "average"
    decimals: number
    sensitivity: "standard" | "sensitive" | "sexual"
    values?: {
      value: number
      label: string
    }[]
    healthKit?: {
      identifier: string
      kind: "category" | "quantity" | "workout"
      unit?: string
      readOnly?: boolean
      factor?: number
      categoryValues?: number[]
    }
    healthConnect?: string
    leaderboard?: "count" | "sum" | "average"
    min?: number
    max?: number
    pinned?: boolean
    description?: string
    enabled: boolean
    sortOrder: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
  • 404Sexual Activity isn't on.
curl 'https://api.cactive.com.au/v1/me/health/sexual/summary' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  counts: {
    week: number
    month: number
    year: number
    all: number
  }
  protectionRate: null | number
  partnerCount: number
}
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).

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/leaderboards' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  optIns: {
    serverId: string
    metricId: string
    at: number
  }[]
  servers: {
    health: null
    serverId: string
    name: string
    iconUrl: null | string
  } | {
    health: {
      settings: {
        metrics: string[]
        updatedAt: null | number
        updatedBy: null | string
        enabled: boolean
        allowSexual?: boolean
      }
      canManage: boolean
      available: string[]
      defs: {
        metricId: string
        label: string
        category: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
        kind: "duration" | "event" | "category" | "quantity"
        unit: string
        units: object[]
        aggregation: "duration" | "count" | "latest" | "sum" | "average"
        decimals: number
        sensitivity: "standard" | "sensitive" | "sexual"
        values?: object[]
        healthKit?: {
          identifier: string
          kind: "category" | "quantity" | "workout"
          unit?: string
          readOnly?: boolean
          factor?: number
          categoryValues?: object
        }
        healthConnect?: string
        leaderboard?: "count" | "sum" | "average"
        min?: number
        max?: number
        pinned?: boolean
        description?: string
        enabled: boolean
        sortOrder: number
      }[]
      adult: boolean
      optedIn: string[]
    }
    serverId: string
    name: string
    iconUrl: null | string
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 2,000 characters.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl 'https://api.cactive.com.au/v1/me/health/audit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  entries: {
    id: string
    at: number
    action: "export" | "share.update" | "consent.accept" | "consent.withdraw" | "consent.sensitive" | "share.sexual" | "share.view" | "leaderboard.opt_in" | "leaderboard.opt_out" | "assistant.update" | "assistant.read" | "api.update" | "delete_all" | "device.add" | "device.remove"
    text: string
    actor: null | {
      userId: string
      name?: string
    }
    details?: {
      [key: string]: unknown
    }
  }[]
  cursor: null | string
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Query parameters

  • cursorstring

    Up to 2,000 characters.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/me/health/export' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  samples: {
    sampleId: string
    metricId: string
    start: number
    end: number
    value: number
    stage?: number
    protection?: boolean | null
    partner?: {
      name?: string
      userId?: string
    }
    note?: string
    meta?: {
      [key: string]: boolean | string | number
    }
    sourceId: string
    sourceName: string
    external: boolean
    version: number
    createdAt: number
    updatedAt: number
  }[]
  cursor: null | string
  profile?: {
    userId: string
    consent: null | {
      version: number
      at: number
    }
    sensitiveConsent: {
      other?: number
      body?: number
      heart?: number
      cycle?: number
      activity?: number
      hearing?: number
      medications?: number
      mental?: number
      mindfulness?: number
      mobility?: number
      nutrition?: number
      respiratory?: number
      sleep?: number
      symptoms?: number
      vitals?: number
      sexual?: number
    }
    timeZone: string
    timeZones: {
      from: number
      zone: string
    }[]
    pinned: string[]
    assistant: {
      enabled: boolean
      categories: ("other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual")[]
    }
    sexualShare: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      counts: boolean
      protectionRate: boolean
      partnerCount: boolean
      confirmedAt?: number
    }
    apiAccess: boolean
    adult: boolean
    ageUnknown: boolean
    createdAt: number
    updatedAt: number
  }
  sources?: {
    sourceId: string
    name: string
    kind: "app" | "watch" | "phone" | "manual"
    bundleId?: string
    device?: string
    priority: number
    lastSeenAt: number
    createdAt: number
  }[]
  sharing?: {
    scope: "category" | "metric"
    id: string
    rule: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    updatedAt: number
  }[]
  metrics?: {
    metricId: string
    unit?: string
    share?: {
      audience: "public" | "followers" | "following" | "friends" | "only_me"
      detail: "samples" | "aggregates"
    }
    count: number
    firstAt?: number
    lastAt?: number
    months: string[]
    updatedAt: number
  }[]
  exportedAt: number
}
POST/v1/me/health/delete-all

Deletes everything; call again while done is false.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body

  • confirm"delete"required

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X POST 'https://api.cactive.com.au/v1/me/health/delete-all' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "confirm": "delete"
  }'
Send it from this page with your session or a key.

Response 200

{
  done: boolean
  remaining: number
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • userId

    A member's user id (usr_…).

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/health/people/{userId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  userId: string
  metrics: {
    metricId: string
    detail: "samples" | "aggregates"
    today: null | number
    days: {
      day: string
      value: null | number
    }[]
    streak: number
    longestStreak: number
    best: null | {
      day: string
      value: number
    }
    average: null | number
    samples?: {
      value: number
      start: number
      stage?: number
      end: number
      sampleId: string
    }[]
  }[]
  sexual: null | {
    counts?: {
      week: number
      month: number
      year: number
      all: number
    }
    protectionRate?: null | number
    partnerCount?: number
  }
  defs: {
    metricId: string
    label: string
    category: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    kind: "duration" | "event" | "category" | "quantity"
    unit: string
    units: {
      id: string
      label: string
      factor: number
      offset?: number
    }[]
    aggregation: "duration" | "count" | "latest" | "sum" | "average"
    decimals: number
    sensitivity: "standard" | "sensitive" | "sexual"
    values?: {
      value: number
      label: string
    }[]
    healthKit?: {
      identifier: string
      kind: "category" | "quantity" | "workout"
      unit?: string
      readOnly?: boolean
      factor?: number
      categoryValues?: number[]
    }
    healthConnect?: string
    leaderboard?: "count" | "sum" | "average"
    min?: number
    max?: number
    pinned?: boolean
    description?: string
    enabled: boolean
    sortOrder: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • serverId

    Mirage server id (gld_…).

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/health/servers/{serverId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  settings: {
    metrics: string[]
    updatedAt: null | number
    updatedBy: null | string
    enabled: boolean
    allowSexual?: boolean
  }
  canManage: boolean
  available: string[]
  defs: {
    metricId: string
    label: string
    category: "other" | "body" | "heart" | "cycle" | "activity" | "hearing" | "medications" | "mental" | "mindfulness" | "mobility" | "nutrition" | "respiratory" | "sleep" | "symptoms" | "vitals" | "sexual"
    kind: "duration" | "event" | "category" | "quantity"
    unit: string
    units: {
      id: string
      label: string
      factor: number
      offset?: number
    }[]
    aggregation: "duration" | "count" | "latest" | "sum" | "average"
    decimals: number
    sensitivity: "standard" | "sensitive" | "sexual"
    values?: {
      value: number
      label: string
    }[]
    healthKit?: {
      identifier: string
      kind: "category" | "quantity" | "workout"
      unit?: string
      readOnly?: boolean
      factor?: number
      categoryValues?: number[]
    }
    healthConnect?: string
    leaderboard?: "count" | "sum" | "average"
    min?: number
    max?: number
    pinned?: boolean
    description?: string
    enabled: boolean
    sortOrder: number
  }[]
  adult: boolean
  optedIn: string[]
}
PUT/v1/health/servers/:serverId/settings

Turns a server's Health leaderboards on or off and picks metrics (enabled, metrics). Manage Server.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • serverId

    Mirage server id (gld_…).

Request body

  • enabledbooleanrequired
  • metricsstring[]required

    Up to 20 items. Each up to 48 characters.

  • allowSexualboolean

    Default false.

Also checked: Unknown fields are rejected.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/health/servers/{serverId}/settings' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "metrics": [
      "example"
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  settings: {
    updatedAt: null | number
    updatedBy: null | string
    enabled: boolean
    metrics: string[]
    allowSexual?: boolean
  }
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • serverId

    Mirage server id (gld_…).

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X PUT 'https://api.cactive.com.au/v1/health/servers/{serverId}/opt-ins/{metricId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  optIns: {
    serverId: string
    metricId: string
    at: number
  }[]
}
DELETE/v1/health/servers/:serverId/opt-ins/:metricId

Stops ranking: your opt-in and every score for that server and metric go.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • serverId

    Mirage server id (gld_…).

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:write on a personal key whose owner allowed it.
  • 403Change Health's privacy settings in the app.
curl -X DELETE 'https://api.cactive.com.au/v1/health/servers/{serverId}/opt-ins/{metricId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  optIns: {
    serverId: string
    metricId: string
    at: number
  }[]
}
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.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • serverId

    Mirage server id (gld_…).

  • metricId

    A Health metric's id from the registry (steps, heart_rate, sleep, sexual_activity, …), as GET /v1/me/health/metrics lists them.

Query parameters

  • period"week" | "month" | "all"

    Default "week".

  • atstring

    Up to 16 characters.

Errors

  • 403Health is only reachable from the Health, phone and Mirage apps.
  • 403Its owner hasn't let API keys use Health (Health → Privacy).
  • 403Health needs health:read on a personal key whose owner allowed it.
curl 'https://api.cactive.com.au/v1/health/servers/{serverId}/leaderboards/{metricId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  serverId: string
  metricId: string
  period: "all" | "month" | "week"
  periodKey: string
  entries: {
    rank: number
    userId: string
    name: string
    avatarUrl: null | string
    value: number
    you: boolean
  }[]
  optedIn: boolean
}