feat(measurements): accept sleep stages by name on POST /api/measurements

A bridge such as Tasker or Home Assistant could only send sleep stages
through the batch route, in HealthKit's terms: the category identifier,
a stage codepoint from 0 to 5, and a value it had to work out in
minutes. It can now post one segment to `POST /api/measurements` with
`type: "SLEEP_DURATION"`, a `sleepStage` of `IN_BED`, `ASLEEP`, `AWAKE`,
`CORE`, `DEEP` or `REM`, and either `startDate` + `endDate` or
`measuredAt` (the end) + `value` (minutes).

The row is the one the batch route writes for the same segment, and the
dedupe is the batch route's: the opposite-source same-reading check,
then one reconcile over both unique identities. Without an `externalId`
the server derives one from the stage and both instants, so a re-post
answers 200 `duplicate`, a corrected start answers 200 `updated`, and a
new segment answers 201 `inserted`. The narrow `measurements:write`
token is accepted and still writes only MANUAL rows. Every other body
on this route behaves as before.

Requested in #972.
This commit is contained in:
Marc-André Bombeck committed 2026-09-25 07:39:07 +02:00
1 parent be112df972
commit f443ab6615
5 files changed
+1020 -5

No files matched your search

+203 -2
View File
@@ -3753,6 +3753,12 @@ paths:
in request order. Use `/api/measurements/batch` for Apple Health upload streams.
Sleep stages by name (since v1.39.1): an object with `type: SLEEP_DURATION`, a `sleepStage` of `IN_BED`,
`ASLEEP`, `AWAKE`, `CORE`, `DEEP` or `REM`, and the segment as `startDate` + `endDate` or as `measuredAt` (its
end) + `value` (minutes). It is stored and deduplicated exactly as the batch route stores a HealthKit sleep
sample, so a bridge can send stages without the HealthKit codepoints. See `NamedSleepStageEntry`.
Also reachable with a narrow `measurements:write` Bearer, which is the supported way to push readings from a
scale, a watch bridge or a home-automation rule. That credential is confined to its owner's own record — a
request carrying the account selector is refused 403 before any sharing grant is read, however the record is
@@ -3768,12 +3774,21 @@ paths:
schema:
anyOf:
- $ref: "#/components/schemas/CreateMeasurementRequest"
- $ref: "#/components/schemas/NamedSleepStageEntry"
- type: array
items:
$ref: "#/components/schemas/CreateMeasurementRequest"
responses:
"200":
description: "Named sleep-stage body only: the segment was already stored (`status: duplicate`) or a stored one was
corrected in place (`status: updated`). Every other body answers 201 or an error, as before."
content:
application/json:
schema:
$ref: "#/components/schemas/NamedSleepStageDuplicateResponse"
"201":
description: Created. A single resource for the object body; an array of resources, in request order, for the array body.
description: "Created. A single resource for the object body; an array of resources, in request order, for the array
body; for a named sleep-stage body, the stored row with `status: inserted`."
content:
application/json:
schema:
@@ -3782,7 +3797,7 @@ paths:
"403": *a9
"409":
description: A measurement with this data already exists — the `(userId, type, source, externalId)` dedup index rejected
the write.
the write. Never for a named sleep-stage body, which answers a re-post with 200 instead.
content:
application/json:
schema:
@@ -22124,6 +22139,61 @@ components:
`glucoseContext` stays REQUIRED on a `BLOOD_GLUCOSE` row here: this is the hand-entry surface, where the person
taking the reading knows whether it was fasting or after a meal. The bulk ingest paths (CSV import, JSON import,
device sync) accept a contextless reading, because a sensor export classifies nothing per sample."
NamedSleepStageEntry:
type: object
properties:
type:
type: string
const: SLEEP_DURATION
sleepStage:
type: string
enum:
- IN_BED
- ASLEEP
- AWAKE
- CORE
- DEEP
- REM
startDate:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
endDate:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
measuredAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
value:
type: number
externalId:
type: string
minLength: 1
maxLength: 120
source:
default: MANUAL
type: string
enum:
- MANUAL
- APPLE_HEALTH
deviceType:
anyOf:
- type: string
minLength: 1
maxLength: 32
- type: "null"
required:
- type
- sleepStage
description: "One sleep-stage segment with the stage named (since v1.39.1), for a bridge that does not speak HealthKit.
Chosen whenever the object carries a string `sleepStage`. `type` is `SLEEP_DURATION`. The segment is either
`startDate` + `endDate`, or `measuredAt` (its END) + `value` (its length in minutes); a `value` sent beside the
dates must agree with them to within a minute. Stored as the batch route stores a HealthKit sleep sample: value
in minutes, `measuredAt` at the end, the stage in `sleepStage`. Without an `externalId` the server derives one
from the stage and both instants, so sending the same segment again is a `duplicate`, and a segment whose start
moved is `updated` rather than added."
AppleHealthBatchRequest:
type: object
properties:
@@ -39588,6 +39658,136 @@ components:
- limit
- offset
additionalProperties: false
NamedSleepStageDuplicateResponse:
type: object
properties:
data:
$ref: "#/components/schemas/NamedSleepStageMeasurement"
error:
type: "null"
meta:
type: object
properties:
requestId:
type: string
additionalProperties: false
required:
- data
- error
additionalProperties: false
NamedSleepStageMeasurement:
type: object
properties:
id:
type: string
description: Stored row id, or a synthetic key (`day:<type>:<dayKey>`, `sleep-seg:<dayKey>:<n>`) on the collapsed list
modes.
type:
$ref: "#/components/schemas/MeasurementType"
value:
type: number
unit:
type: string
measuredAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
source:
$ref: "#/components/schemas/MeasurementSource"
notes:
anyOf:
- type: string
- type: "null"
userId:
type: string
valueMin:
description: Bucket MINIMUM — set only on an hourly heart-rate `stats:` row.
anyOf:
- type: number
- type: "null"
valueMax:
description: Bucket MAXIMUM — set only on an hourly heart-rate `stats:` row.
anyOf:
- type: number
- type: "null"
externalId:
description: External-system dedup key; null for manual entries.
anyOf:
- type: string
- type: "null"
externalSourceVersion:
anyOf:
- type: string
- type: "null"
glucoseContext:
description: Set only on BLOOD_GLUCOSE rows, and null there too when the writer recorded no classification (a sensor
export, a device sync). Never invent one.
anyOf:
- type: string
- type: "null"
sleepStage:
description: Set only on SLEEP_DURATION rows.
anyOf:
- type: string
- type: "null"
rhythmClassification:
description: Device classification verdict; set only on EVENT rows.
anyOf:
- type: string
- type: "null"
deviceType:
description: "`watch | band | ring | phone | scale | other | unknown`."
anyOf:
- type: string
- type: "null"
syncVersion:
description: Bumped on every server-side mutation; the last-writer-wins input for cross-device reconciliation.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
deletedAt:
description: Soft-delete tombstone; null on a live row.
anyOf:
- type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
- type: "null"
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updatedAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
dayKey:
type: string
sampleCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
partial:
description: True on the one bucket whose day was cut off by the read cap, so its sum understates the real total.
type: boolean
status:
type: string
enum:
- inserted
- updated
- duplicate
description: "`inserted` — a new row (HTTP 201). `duplicate` — the segment was already stored, by this route or the
batch route, and nothing changed (HTTP 200). `updated` — a stored segment with the same stage, source and
end was corrected in place, for example a later start (HTTP 200)."
required:
- id
- type
- value
- unit
- measuredAt
- source
- status
additionalProperties: false
description: The stored SLEEP_DURATION row for a named sleep-stage segment, with what the call did to it.
CreateMeasurementResponse:
type: object
properties:
@@ -39597,6 +39797,7 @@ components:
- type: array
items:
$ref: "#/components/schemas/MeasurementResource"
- $ref: "#/components/schemas/NamedSleepStageMeasurement"
error:
type: "null"
meta: