Habits and goals

Habit and goal endpoints expose a narrow public write surface. Habit reminder mutation, habit definition changes, workout goals, nutrition goals, medical goals, and raw objective answer payloads remain internal.

Scopes

Scope	Allows
`habits:read`	Read client habits and habit entries.
`habits:write`	Create, update, and archive habit entries.
`goals:read`	Read public-safe client goal summaries.
`goals:write`	Update public-safe goal fields.

List client habits

GET /public/v1/clients/{clientId}/habits
Authorization: Bearer <access_token>

Required scope: habits:read Response fields:

Field	Type	Nullable	Description
`data.habits[].habitId`	string	no	Habit ID.
`data.habits[].name`	string	no	Habit name.
`data.habits[].description`	string	no	Habit description.
`data.habits[].habitType`	string	no	Habit type.
`data.habits[].goalPeriod`	string	no	Goal period.
`data.habits[].logMode`	string	no	Log mode.
`data.habits[].goalValue`	number	yes	Goal value.
`data.habits[].allowableValue`	number	yes	Allowance/tolerance.
`data.habits[].unit`	string	no	Unit.
`data.habits[].color`	string	no	Display color.

Not exposed: reminder settings, notification copy, actor IDs, deleted flags, audit fields, or scheduling internals.

List habit entries

GET /public/v1/clients/{clientId}/habits/entries?dateFrom=2026-07-01T00:00:00.000Z&dateTo=2026-07-31T23:59:59.999Z
Authorization: Bearer <access_token>

Required scope: habits:read Validation:

Parameter	Type	Required	Rule
`dateFrom`	ISO date-time	yes	Valid date-time.
`dateTo`	ISO date-time	yes	Valid date-time, must be after `dateFrom`.
`habitId`	string	no	Valid habit ObjectId belonging to the client/company.

Range limit: maximum 92 days. Response fields:

Field	Type	Nullable	Description
`data.truncated`	boolean	no	Whether the internal max entries limit was reached.
`data.entries[].entryId`	string	no	Entry ID.
`data.entries[].habitId`	string	yes	Habit ID.
`data.entries[].occurredAt`	string	yes	Occurrence timestamp.
`data.entries[].localDate`	string	no	Canonical local date.
`data.entries[].periodKey`	string	no	Period bucket key.
`data.entries[].value`	number	yes	Logged value.
`data.entries[].unit`	string	no	Unit at log time.
`data.entries[].note`	string	no	Entry note.
`data.periodSummary[].habitId`	string	yes	Habit ID.
`data.periodSummary[].periodKey`	string	no	Period key.
`data.periodSummary[].entryCount`	integer	no	Entries in that period.
`data.periodSummary[].totalValue`	number	no	Total logged value.

Not exposed: source, actor IDs, reminder metadata, audit fields, or deleted entries.

Create habit entry

POST /public/v1/clients/{clientId}/habits/{habitId}/entries
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope: habits:write Request body:

Field	Type	Required	Rule
`occurredAt`	UTC ISO date-time	yes	Must match `YYYY-MM-DDTHH:mm:ss(.SSS)Z`.
`value`	number/string	conditional	Required for value-based habits. Localized numeric strings such as `"82,5"` are accepted. Must be non-negative.
`note`	string	no	Maximum 1000 characters.

Validation:

Rule	Behavior
Client access	Client must belong to the authenticated company.
Habit access	Habit must belong to the client and company and must not be deleted.
Date window	`occurredAt` must be within habit `startDate` and `endDate` when configured.
Specific weekdays	Habits configured for specific weekdays can only be logged on those days in the client’s timezone.
Max value	`value` cannot exceed the habit `allowableValue` when configured.
Unknown fields	Rejected with `PUBLIC_API_UNKNOWN_FIELDS`.

Create is idempotent per clientId, habitId, and calculated localDate. When an entry already exists for that local day, it is replaced instead of creating a duplicate. Response fields:

Field	Type	Nullable	Description
`data.entry.entryId`	string	no	Habit entry ID.
`data.entry.habitId`	string	yes	Habit ID.
`data.entry.occurredAt`	string	yes	Occurrence timestamp.
`data.entry.localDate`	string	no	Canonical local date in the client’s timezone.
`data.entry.periodKey`	string	no	Period bucket key.
`data.entry.value`	number	yes	Logged value.
`data.entry.unit`	string	no	Unit at log time.
`data.entry.note`	string	no	Entry note.
`data.created`	boolean	no	`true` when a new entry was created.
`data.replaced`	boolean	no	`true` when an existing local-day entry was replaced.

Update habit entry

PATCH /public/v1/clients/{clientId}/habits/entries/{entryId}
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope: habits:write Allowed fields: occurredAt, value, and note. At least one field is required. The same date, weekday, note length, and numeric value validations as Create habit entry apply. Response fields:

Field	Type	Nullable	Description
`data.entry.entryId`	string	no	Habit entry ID.
`data.entry.habitId`	string	yes	Habit ID.
`data.entry.occurredAt`	string	yes	Occurrence timestamp.
`data.entry.localDate`	string	no	Canonical local date in the client’s timezone.
`data.entry.periodKey`	string	no	Period bucket key.
`data.entry.value`	number	yes	Logged value.
`data.entry.unit`	string	no	Unit at log time.
`data.entry.note`	string	no	Entry note.

Archive habit entry

PATCH /public/v1/clients/{clientId}/habits/entries/{entryId}/archive
Authorization: Bearer <access_token>

Required scope: habits:write Archive is a soft delete. The entry is excluded from Public API read endpoints after archiving. Response fields:

Field	Type	Nullable	Description
`data.entry.entryId`	string	no	Habit entry ID.
`data.entry.archived`	boolean	no	Always `true` for successful responses.
`data.entry.updatedAt`	string	yes	Update timestamp.

Get client goals

GET /public/v1/clients/{clientId}/goals
Authorization: Bearer <access_token>

Required scope: goals:read Response fields:

Field	Type	Nullable	Description
`data.goals.physicalActivityGoal`	string	no	Public physical activity goal text.
`data.goals.currentWeightKg`	number	yes	Current weight goal value.
`data.goals.targetWeightKg`	number	yes	Target weight goal value.
`data.goals.timeline.startDate`	string	yes	Goal start date.
`data.goals.timeline.endDate`	string	yes	Goal end date.
`data.goals.dailyGoals.waterIntakeMl`	number	yes	Water intake goal.
`data.goals.dailyGoals.dailySteps`	number	yes	Daily step goal.
`data.goals.dailyGoals.sleepDurationHours`	number	yes	Sleep duration goal.
`data.goals.measurementGoals[].typeId`	string	yes	Measurement type ID.
`data.goals.measurementGoals[].typeName`	string	no	Measurement type name.
`data.goals.measurementGoals[].goal`	number	yes	Goal value.
`data.goals.measurementGoals[].unit`	string	no	Goal unit.

Not exposed: nutrition plans, macro targets, calorie targets, medical details, injuries, medications, allergies, raw ObjectiveQuestion documents, objective answer payloads, or internal notes.

Update client goals

PATCH /public/v1/clients/{clientId}/goals
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope: goals:write Only these public fields are accepted:

Field	Type	Required	Rule
`physicalActivityGoal`	string	no	`default`, `Lose Weight`, `Maintain Weight`, or `Gain Weight`.
`currentWeightKg`	number/string	no	Non-negative number. Localized numeric strings are accepted.
`targetWeightKg`	number/string	no	Non-negative number.
`timeline.startDate`	date/null	no	`YYYY-MM-DD` or `null`.
`timeline.endDate`	date/null	no	`YYYY-MM-DD` or `null`.
`dailyGoals.waterIntakeMl`	number/string	no	Non-negative number.
`dailyGoals.dailySteps`	number/string	no	Non-negative number.
`dailyGoals.sleepDurationHours`	number/string	no	Non-negative number.

Unknown fields are rejected with PUBLIC_API_UNKNOWN_GOAL_FIELDS. Empty patches return NOTHING_TO_UPDATE. Nested objects are flattened before validation, so callers may send either nested JSON or dotted field paths when supported by their client. Response fields:

Field	Type	Nullable	Description
`data.goals.physicalActivityGoal`	string	no	Public physical activity goal text.
`data.goals.currentWeightKg`	number	yes	Current weight goal value.
`data.goals.targetWeightKg`	number	yes	Target weight goal value.
`data.goals.timeline.startDate`	string	yes	Goal start date.
`data.goals.timeline.endDate`	string	yes	Goal end date.
`data.goals.dailyGoals.waterIntakeMl`	number	yes	Water intake goal.
`data.goals.dailyGoals.dailySteps`	number	yes	Daily step goal.
`data.goals.dailyGoals.sleepDurationHours`	number	yes	Sleep duration goal.
`data.goals.measurementGoals[].typeId`	string	yes	Measurement type ID.
`data.goals.measurementGoals[].typeName`	string	no	Measurement type name.
`data.goals.measurementGoals[].goal`	number	yes	Goal value.
`data.goals.measurementGoals[].unit`	string	no	Goal unit.
`data.updatedFields[]`	string[]	no	Internal field paths updated by the patch.
`data.updatedAt`	string	yes	Objective document update timestamp.

Goal writes deliberately exclude nutrition, macros, calories, workout-plan targets, medical fields, injuries, medications, allergies, and raw objective answer payloads.

Start here

Public API guides

Access Devices

Scopes

List client habits

List habit entries

Create habit entry

Update habit entry

Archive habit entry

Get client goals

Update client goals

​Scopes

​List client habits

​List habit entries

​Create habit entry

​Update habit entry

​Archive habit entry

​Get client goals

​Update client goals

Scopes

List client habits

List habit entries

Create habit entry

Update habit entry

Archive habit entry

Get client goals

Update client goals