List the caller's groups
curl --request GET \
--url https://web-api.dev.soxai.site/api/groups \
--header 'Authorization: Bearer <token>'import requests
url = "https://web-api.dev.soxai.site/api/groups"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://web-api.dev.soxai.site/api/groups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"groups": [
{
"groupId": "b7d1f0c9a2e4d6f8b0c1",
"groupName": "Shibata family",
"status": "active",
"role": "admin",
"createdAt": "2026-08-03T09:30:00+00:00",
"memberCount": 2,
"sharedFields": {
"sleep_score": true,
"health_score": true,
"activity_score": false,
"sleep_total_time_exclude_awake": false,
"activity_steps": true,
"heat_stroke_severity": true,
"last_sync_time": true
},
"masterHidden": false,
"sharedFieldNames": [
"activity_steps",
"health_score",
"heat_stroke_severity",
"last_sync_time",
"sleep_score"
],
"members": [
{
"uid": "user123",
"displayName": "Mom",
"role": "admin",
"joinedAt": "2026-08-03T09:30:00+00:00",
"isSelf": true,
"visibleFields": [
"activity_steps",
"health_score",
"heat_stroke_severity",
"last_sync_time",
"sleep_score"
]
},
{
"uid": "user456",
"displayName": "Dad",
"role": "member",
"joinedAt": "2026-08-05T02:10:00+00:00",
"isSelf": false,
"visibleFields": [
"sleep_score"
]
}
],
"watching": true
}
]
}{
"error": "http-error",
"error_msg": "Invalid authentication credentials. <reason>"
}{
"error": "forbidden",
"error_msg": "Not enough permission"
}{
"error": "rate-limited",
"error_msg": "Rate limit exceeded. Retry after <n> seconds."
}{
"error": "internal-server-error",
"error_msg": "Failed to fetch data: <error_message>"
}Family Groups
List the caller's groups
Not callable with a Sandbox key
A request authenticated with a Sandbox soxai-api-key is answered 403 This endpoint is not available in the sandbox., because it is internal or operational, outside the Sandbox surface. It is published here because the Sandbox runs the same build; use it in Production. See Sandbox.
Every group the caller belongs to, with its creation time, roster size and the caller’s own sharing settings in that group (SOX-67).
Sharing is per membership, so the group-list screen shows a different set of
metric chips per card: sharedFieldNames is that set — the resolved list of
what the caller shares there, already accounting for sharedFields.all and
masterHidden ([] when hidden). sharedFields / masterHidden are the raw
toggles behind it, for the edit screen.
Each row also carries what the rest of the card needs, so drawing the list costs one call instead of one GroupView per group (SOX-82):
members— the roster behind the avatar row:uid/displayName/role/joinedAt/isSelf/visibleFields, caller first then oldest membership first.joinedAt(SOX-92) is when that membership started, as offset-carrying ISO 8601 like the group’screatedAt— the key the order after the caller is derived from, and null only for a member seeded without one. Identity and masks only. Health values stay in GroupView, which is still the single data-view endpoint (spec §3.5); open a group to get them.watching— the “watching over” badge (見守り中): true when at least one other member shares at least one metric with the caller. False for a solo group and for one where everyone has setmasterHidden, whatevermemberCountsays.
Parameters
- None. This endpoint takes no path, query or body parameter.
Response
200{"groups": [...]}, one entry per group the caller is an active member of. A caller in no group receives an empty list, not a404.- A membership pointing at a group that has since been dissolved is skipped rather than reported.
Errors
- None. Every answer is built from the caller’s own memberships, so there is nothing to be refused or not found.
Authorization
- Scheme:
Authorization: Bearer <idToken>orsoxai-api-key: <api key>. - Any authenticated caller. The list is built from the caller’s own membership records, so no group role is involved and no group the caller does not belong to appears.
GET
/
api
/
groups
List the caller's groups
curl --request GET \
--url https://web-api.dev.soxai.site/api/groups \
--header 'Authorization: Bearer <token>'import requests
url = "https://web-api.dev.soxai.site/api/groups"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://web-api.dev.soxai.site/api/groups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"groups": [
{
"groupId": "b7d1f0c9a2e4d6f8b0c1",
"groupName": "Shibata family",
"status": "active",
"role": "admin",
"createdAt": "2026-08-03T09:30:00+00:00",
"memberCount": 2,
"sharedFields": {
"sleep_score": true,
"health_score": true,
"activity_score": false,
"sleep_total_time_exclude_awake": false,
"activity_steps": true,
"heat_stroke_severity": true,
"last_sync_time": true
},
"masterHidden": false,
"sharedFieldNames": [
"activity_steps",
"health_score",
"heat_stroke_severity",
"last_sync_time",
"sleep_score"
],
"members": [
{
"uid": "user123",
"displayName": "Mom",
"role": "admin",
"joinedAt": "2026-08-03T09:30:00+00:00",
"isSelf": true,
"visibleFields": [
"activity_steps",
"health_score",
"heat_stroke_severity",
"last_sync_time",
"sleep_score"
]
},
{
"uid": "user456",
"displayName": "Dad",
"role": "member",
"joinedAt": "2026-08-05T02:10:00+00:00",
"isSelf": false,
"visibleFields": [
"sleep_score"
]
}
],
"watching": true
}
]
}{
"error": "http-error",
"error_msg": "Invalid authentication credentials. <reason>"
}{
"error": "forbidden",
"error_msg": "Not enough permission"
}{
"error": "rate-limited",
"error_msg": "Rate limit exceeded. Retry after <n> seconds."
}{
"error": "internal-server-error",
"error_msg": "Failed to fetch data: <error_message>"
}