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" }

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

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: 01 October 2025