Data Models

This page documents the JSON shapes returned by the REST API and emitted over WebSocket.

All fields use camelCase. Additional fields may appear in future versions; clients must ignore unknown properties.

Counter

{
  "id": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
  "displayName": "Daily Steps",
  "type": "UpDown",
  "members": [ { /* CounterMember */ } ],
  "data": { /* type specific */ }
}

Field	Type	Notes
id	string (UUID v7)	Unique counter id (server generated)
displayName	string	5..40 chars (validation enforced server-side)
type	enum CounterType	One of `UpDown`, `FromDate`, `ToDate`
members	CounterMember[]	Current membership list
data	object or null	Shape depends on `type`

CounterMember

{
  "userId": "4f9b0c9d-9d3d-4f2b-9c97-5d6c3f0e4c11",
  "displayName": "Alice",
  "isAdmin": true
}

Field	Type	Notes
userId	string (UUID)	Identity of member
displayName	string	User display name at time of retrieval
isAdmin	boolean	Whether user has admin privileges for the counter

Counter Data Models

UpDown (PublicV1UpDownCounterData)

{ "value": 12450, "mode": "UpAndDown" }

Field	Type	Notes
value	number (int64)	Current counter numeric value
mode	enum UpDownCounterMode	`OnlyUp`, `OnlyDown`, or `UpAndDown`

FromDate (PublicV1FromDateCounterData)

{
  "date": "2025-01-01T00:00:00Z",
  "dateOnly": "2025-01-01",
  "pastDays": 45,
  "milestones": [
    { "days": 7, "reached": true, "remainingDays": null, "date": "2025-01-08" },
    { "days": 10, "reached": true, "remainingDays": null, "date": "2025-01-11" },
    { "days": 14, "reached": true, "remainingDays": null, "date": "2025-01-15" },
    { "days": 21, "reached": true, "remainingDays": null, "date": "2025-01-22" },
    { "days": 30, "reached": true, "remainingDays": null, "date": "2025-01-31" },
    { "days": 50, "reached": false, "remainingDays": 5, "date": "2025-02-20" },
    { "days": 100, "reached": false, "remainingDays": 55, "date": "2025-04-11" }
  ]
}

Field	Type	Notes
date	string (ISO 8601 UTC)	Start date in UTC (legacy, will be removed)
dateOnly	string (date)	Start date as date-only value
pastDays	number (int)	Days elapsed since the start date for the user's timezone
milestones	Milestone[]	Sorted list of all milestone thresholds with their status

Milestone

Field	Type	Notes
days	number (int)	The milestone threshold in days (e.g. 7, 10, 14, 21, 30, 50, 100, …, 10000)
reached	boolean	Whether the milestone has been reached (`pastDays >= days`)
remainingDays	number or null	Days remaining until the milestone, `null` when reached
date	string (date)	The date when the milestone was reached or will be reached (`startDate + days`)

ToDate (PublicV1ToDateCounterData)

{ "date": "2025-12-31T23:59:59Z" }

Field	Type	Notes
date	string (ISO 8601 UTC)	End date in UTC

Null Data

If a counter type is unrecognized (future type) or has no data, data may be null. Treat this as absence of a type-specific payload.

Enums

CounterType

Value	Meaning
UpDown	Numeric counter with optional increment/decrement behavior
FromDate	Tracks duration since a fixed start date
ToDate	Tracks remaining time until a target date

UpDownCounterMode

Value	Behavior
OnlyUp	Value monotonically increases
OnlyDown	Value monotonically decreases
UpAndDown	Value may move in both directions

Error Object

See Error Handling for full table.

{ "message": "The requested resource was not found.", "code": -1100 }

WebSocket Events

WebSocket notifications follow JSON-RPC 2.0 (no id). Generic shape:

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": { }
}

Fields:

jsonrpc: always "2.0"
method: event identifier (see list below)
params: event-specific payload

counterUpdated

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "displayName": "Daily Steps",
    "data": { "value": 13000, "mode": "UpAndDown" }
  }
}

Params:

counterId (UUID)
displayName (string, optional)
data (object|null)

counterDeleted

{
  "jsonrpc": "2.0",
  "method": "counterDeleted",
  "params": { "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111" }
}

Params:

counterId (UUID)

counterMemberlistChanged

{
  "jsonrpc": "2.0",
  "method": "counterMemberlistChanged",
  "params": { "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111" }
}

Params:

counterId (UUID)

Versioning & Forward Compatibility

Ignore unknown fields in any object.
Ignore unknown methods.
New enum values may appear; treat unknown enum values gracefully.
A future dataVersion field may be added.

Last modified: 16 March 2026