Data Models

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

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

v2 Counter

Flat response shape used by all v2 REST endpoints and WebSocket events.

{
  "id": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
  "name": "Daily Steps",
  "type": "UpDown",
  "value": 12450,
  "created": "2025-01-01T00:00:00Z"
}

Field	Type	Notes
id	string (UUID v7)	Unique counter id (server generated)
name	string	5..40 chars (validation enforced server-side)
type	enum CounterType	One of `UpDown`, `FromDate`, `ToDate`
value	number	Numeric value. For `UpDown`: current value. For `FromDate`: days elapsed (pastDays). For `ToDate`: days remaining. Resolved for the timezone passed in the request (or the user's account timezone).
startDate	string (date)	Only present for `FromDate` counters
endDate	string (date)	Only present for `ToDate` counters
created	string (ISO 8601 UTC)	Counter creation timestamp

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

Error Object

See Error Handling for full table.

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

v2 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",
    "name": "Daily Steps",
    "type": "UpDown",
    "value": 13000
  }
}

Params:

counterId (UUID)
name (string)
type (CounterType)
value (number, timezone-resolved)

counterDeleted

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

counterMemberlistChanged

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

Versioning & Forward Compatibility

Ignore unknown fields in any object.
Ignore unknown methods.
New enum values may appear; treat unknown enum values gracefully.

v1 Data Models (Deprecated)

The v1 API uses a nested counter shape with displayName, members[], and a type-specific data object. In v2 this is replaced by the flat shape above.

21 April 2026