> ## Documentation Index > Fetch the complete documentation index at: https://developers.soxai.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # Get every member's reactions in a group > The reactions currently held on each member of the group (SOX-116). GroupView already carries the same summaries on its cards, so this endpoint is for refreshing them on their own — it reads Firestore only and skips the InfluxDB fan-out a full GroupView call pays for. Reactions are **per day**: every day starts from zero, and a reaction belongs to the day it was sent on. `count` is therefore "how many members hold this reaction on this person on `day`". Omit `day_str` for today; pass an earlier `day_str` to read (or amend) that day's reactions, which stay stored. "Today" is the **JST** calendar day (UTC+09:00) for every member of the group, not each member's own local day, so a reaction lands in the same bucket whoever sends or reads it. A client that wants its own local day passes it as `day_str`. The response echoes the resolved day as `day`. Reactions are **not health data** and are **not masked**. A member who has hidden their metrics (`masterHidden`) shows an empty `data` card and still sends and receives reactions — the same line `joinedAt` sits on: sharing settings govern health values, while who is in a group and what they send each other is already visible to everyone in it. Nothing here is written to the group's audit log, because nothing here reads a health value. `uids` lists the members currently holding that reaction. Every one of them is a member of this group, whose roster the caller can already read in full, so this discloses nothing new — it is what lets a client draw "Dad and Mom cheered you" without a second call. Actors who have since left the group are filtered out, so a count never includes somebody who is no longer here. The list is ordered by the **catalog**, not by count: ordering by count makes the row of icons jump under the user's finger at the moment they tap one. An emoji nobody holds is omitted, and a member with no reactions at all gets `[]`. **Parameters** - `group_id` (path, required) - the group whose reactions are returned. - `day_str` (query, optional) - the day to read, `YYYY-MM-DD`. Defaults to today (JST). **Response** - `200` returns `day`, the day that was read, and `members`, a map of member uid to that member's reaction list on that day. Members holding no reactions are omitted from the map. **Errors** | Status | Condition | | --- | --- | | 400 | `day_str` is not a `YYYY-MM-DD` date | A group that does not exist is not a `404` here: the answer is built from the caller's own membership record, which is absent either way, so both cases are the `403` named under Authorization. **Authorization** - Scheme: `Authorization: Bearer ` or `soxai-api-key: `. - Authority inside a group comes from the caller's own membership record, never from a SOXAI role: an `Admin`, `PartnerAdmin` or `OrgAdmin` claim grants nothing here. - Required: an active member of the group. A caller who is not one receives `403 not a member of this group`, whether or not the group exists. ## OpenAPI ````yaml /openapi-public.json get /api/groups/{group_id}/reactions openapi: 3.1.0 info: title: SOXAI API description: > ## SOXAI API helps you get data stored in SOXAI database. Every endpoint below documents its own parameters, responses and authorization rule. ## How to use 1. All data-related endpoints need you to sign in first. Use the account you registered in the SOXAI app. 2. You can get a Bearer token and localID like this: ``` { "kind": "identitytoolkit#VerifyPasswordResponse", "registered": true, "localId": "[YOUR UID]", "email": "[YOUR EMAIL]", "idToken": "[YOUR BEARER TOKEN]", "refreshToken": [YOUR Refresh TOKEN]" } ``` use this `idToken` to fill it into the value field after you click **Authorize** button, or attach it to header in your request. For more info, search for "Bearer token". (ps. the difference between idToken and refreshToken: idToken will expire in 1 hour, refreshToken will expire in one month, you can use refreshToken to get new idToken when idToken expired.) 3. All users can access to his/her personal data with `localId` as user's uid. 4. If you are an organization admin, contact SOXAI first to create an organization. 5. After the organization is created, you can invite other users to join it. They receive an email to accept the invitation. 6. As an organization user, you can read your own data, plus the roster and profiles of your organization. Other members' measurement data is not yours to read - that is what an organization admin does. See "Who can read whose data" below. ## Quick start note for personal user 1. (Only once) Access `/api/login` to get your uid and OAuthToken by api, please memo OAuthToken, you can use it to access api without login again. 2. Access `/api/v2/DailyInfoData/{query_uid}` for day-level scores, or `/api/v2/DailyDetailData/{query_uid}` for the finer series. Both take a date range and return JSON, or a csv download when `format` is `csv`. 3. The v1 forms `/api/RawData/{query_uid}`, `/api/DailyInfoData/{query_uid}` and `/api/DailyDetailData/{query_uid}` return the same measurements under the raw database field names. Prefer the `/api/v2/` endpoints for a new integration. ## Quick start note for organization user 1. You will receive an email to accept the invitation from your organization admin. After you accept it, your data is shared with that admin. 2. If you want to query your own data, you can refer to the note for personal user. 3. You can query other orguser's info(email, uid, etc) after obtain your org_id from `/api/myOrg` and access `/api/orgs/{org_id}/orgUsers` ## Quick start note for organization admin 1. Contact SOXAI (info@soxai.co.jp) to create an organization for you. 2. Access `/api/login` to get your uid and OAuthToken by api. 3. Access `/api/myOrg` to get your organization id. 4. Access `/api/orgs/{org_id}/orgUsers` to create, read, update and delete organization users. When you post a new user, they receive an email to accept the invitation. 5. Access `/api/v2/DailyInfoDataForOrg` or `/api/v2/DailyDetailDataForOrg` to read your organization's members in one request. **You reach the SOXAI app data of the users who have agreed to share it**, and the endpoint narrows the answer to that set for you. ## Authentication and errors common to every endpoint Unless an endpoint says otherwise, it requires `Authorization: Bearer ` and answers: | Status | Condition | | --- | --- | | 401 | The `Authorization` header is missing, or the token is invalid or expired | | 403 | The caller is authenticated but not allowed to make this request. Each endpoint's **Authorization** block lists the bodies it uses | | 422 | The request did not match the schema. An **authorized** caller sees this instead of a 403; an unauthorized caller is refused before its body is read | | 429 | The rate limit was exceeded. Wait for `Retry-After` seconds before retrying | | 500 | Unexpected server-side failure | Each endpoint documents only the statuses that are specific to it. The **Authorization** block is the last section of every endpoint's description. For the endpoints that declare their rule on the route it is generated from that declaration, so it cannot disagree with what is enforced. ### The second credential `soxai-api-key: ` is accepted wherever `Authorization: Bearer ` is. The difference is lifetime and who issues it: an ID token expires in an hour and you mint it yourself from `POST /api/login`, while an API key is long-lived and read back from `GET /api-key/secret`. A request carries one or the other, not both. Server-to-server integrations should hold the key; anything acting on behalf of a signed-in person should hold the token, so that revoking the person's access is enough to stop it. ### Who can read whose data Which role you hold decides how far past your own uid you can read. A role is a claim on your credential, not something you pass as a parameter. | Role | Reaches | | --- | --- | | (none) | Only your own uid. Every user has this much | | `OrgUser` | Your own uid, plus your organization's roster and member profiles (email, uid, profile) - not other members' measurement data | | `OrgAdmin` | Every member of your own organization, including their measurement data | | `PartnerAdmin` | Every organization owned by your own company, and every member of those organizations | | `Admin` | Every user, with no company or organization scoping. Held by SOXAI only | One consequence catches integrators out: the roster an admin reaches is the whole roster, not only its active part. A membership's `status` records where a member stands in the invitation lifecycle; it does not by itself narrow what an admin can read. Do not infer a member's data scope from their `status` - read the endpoint's **Authorization** block, which states the rule that is actually enforced. ### v1 and v2 The data endpoints come in two generations. `/api/v2/...` returns standardized field names and is the interface to build against. The v1 endpoints (`/api/RawData`, `/api/DailyInfoData`, `/api/DailyDetailData`) return the raw database field names, which change when the database does. They are not deprecated and they are not going away without notice, but they will not gain fields that v2 has; a new integration should use v2. contact: name: SOXAI url: https://www.soxai.co.jp/contact email: info@soxai.co.jp version: 1.0.0 servers: - url: https://web-api.soxai.site description: Production security: [] tags: - name: Authentication description: >- Obtain and hold the credential every other endpoint asks for. `POST /api/login` returns the `idToken` you send as `Authorization: Bearer ` and the `refreshToken` that renews it; the password reset pair is here because a caller who has lost their password cannot hold a token either. `/app/me` reports what the credential you are holding actually carries, which is the first thing to check when an endpoint answers 403. The long-lived alternative to an ID token is under `API Keys`. - name: API Keys description: >- Issue and read back the caller's own long-lived API key, which is accepted as `soxai-api-key: ` wherever an ID token is. A caller holds one key at a time and reads it back rather than being shown it once. Hold a key for a server-to-server integration, where there is no signed-in person whose session could expire; hold an ID token from `Authentication` for anything acting on a person's behalf, so that revoking the person's access is enough to stop it. - name: Data (v2) description: >- Read measurement data with standardized field names. One endpoint per data shape for a single user (`DailyInfoData`, `DailyDetailData`, `DailyTrendData`) and the bulk forms for a whole organization or company (`...ForOrg`). This is the interface to build against. - name: Data (v1) description: >- Read measurement data with the raw database field names, one user at a time, as CSV or JSON. These endpoints are not deprecated and will not disappear without notice, but the names they return are the ones the database uses and change when it does, and they will not gain the fields `Data (v2)` has. **A new integration should use `Data (v2)`.** - name: Sync Status description: >- Whether a user's ring data arrived, rather than what it says. `ProcessLog/{query_uid}` returns one user's sync history and `LastProcessLog` the most recent entry. Read these before concluding that a missing day is missing rather than not yet uploaded - the data endpoints answer with what was received and cannot tell the two apart. - name: Organizations description: >- Create and manage organizations. An organization owns a member roster and is the unit every org-scoped endpoint addresses. A `PartnerAdmin` sees only the organizations its own company owns. - name: Organization Members description: >- Manage an organization's member roster: enrol members, invite them, edit their teams and admin flag, and remove them. A member reaches these endpoints only for the organization their own token names. `AcceptEmailVerification` is the other end of that flow - the link in the invitation email, which the invited user opens without being signed in. - name: Family Groups description: >- Small self-service groups where members choose, per metric, what they share with each other. Authority here comes from the caller's membership record and its `admin` / `member` role **inside the group** - a SOXAI `Admin`, `PartnerAdmin` or `OrgAdmin` claim grants nothing. `GroupView` is the single endpoint that returns members' health data. - name: Partner Companies description: >- Partner companies register and sign in **their own** users with certificates rather than through the SOXAI app. These are the endpoints the partner's own backend calls, authenticating with a signed certificate instead of a SOXAI token. The certificate itself is issued and revoked by SOXAI rather than through this API; contact SOXAI to obtain one. - name: Deep Links description: >- Deep links that carry a one-time token into the SOXAI app: group invitations, and sign-up links that prefill an email address. The token is the credential, so the endpoints that exchange one need no signed-in caller. - name: OAuth2 description: >- Sign a SOXAI user in to your own application with the OAuth2 authorization code flow. Your code reaches four of these: the discovery document your OIDC library reads, the URL you send the user's browser to, the token endpoint your backend calls with the authorization code, and the record of what the user consented to. The screens in between - the login form, the consent page and the two-factor prompts - are SOXAI's own pages, posted to by the browser, and your application never calls them. The remaining endpoint sets whether two-factor is required for a list of users, which an `OrgAdmin` or `PartnerAdmin` does for its own members. - name: Users description: >- Endpoints keyed on a user rather than on an organization: ring serial number lookup, and the caller's own ring sync history. - name: System description: >- Liveness and health checks for monitoring. `ping` answers from the process alone; `health` probes Firestore and both InfluxDB clients and answers `500` when one of them is unreachable; `health_check` reports the same dependencies one by one inside a `200`. None of these require authentication, and none of them read or write a user's data. paths: /api/groups/{group_id}/reactions: get: tags: - Family Groups summary: Get every member's reactions in a group description: >- The reactions currently held on each member of the group (SOX-116). GroupView already carries the same summaries on its cards, so this endpoint is for refreshing them on their own — it reads Firestore only and skips the InfluxDB fan-out a full GroupView call pays for. Reactions are **per day**: every day starts from zero, and a reaction belongs to the day it was sent on. `count` is therefore "how many members hold this reaction on this person on `day`". Omit `day_str` for today; pass an earlier `day_str` to read (or amend) that day's reactions, which stay stored. "Today" is the **JST** calendar day (UTC+09:00) for every member of the group, not each member's own local day, so a reaction lands in the same bucket whoever sends or reads it. A client that wants its own local day passes it as `day_str`. The response echoes the resolved day as `day`. Reactions are **not health data** and are **not masked**. A member who has hidden their metrics (`masterHidden`) shows an empty `data` card and still sends and receives reactions — the same line `joinedAt` sits on: sharing settings govern health values, while who is in a group and what they send each other is already visible to everyone in it. Nothing here is written to the group's audit log, because nothing here reads a health value. `uids` lists the members currently holding that reaction. Every one of them is a member of this group, whose roster the caller can already read in full, so this discloses nothing new — it is what lets a client draw "Dad and Mom cheered you" without a second call. Actors who have since left the group are filtered out, so a count never includes somebody who is no longer here. The list is ordered by the **catalog**, not by count: ordering by count makes the row of icons jump under the user's finger at the moment they tap one. An emoji nobody holds is omitted, and a member with no reactions at all gets `[]`. **Parameters** - `group_id` (path, required) - the group whose reactions are returned. - `day_str` (query, optional) - the day to read, `YYYY-MM-DD`. Defaults to today (JST). **Response** - `200` returns `day`, the day that was read, and `members`, a map of member uid to that member's reaction list on that day. Members holding no reactions are omitted from the map. **Errors** | Status | Condition | | --- | --- | | 400 | `day_str` is not a `YYYY-MM-DD` date | A group that does not exist is not a `404` here: the answer is built from the caller's own membership record, which is absent either way, so both cases are the `403` named under Authorization. **Authorization** - Scheme: `Authorization: Bearer ` or `soxai-api-key: `. - Authority inside a group comes from the caller's own membership record, never from a SOXAI role: an `Admin`, `PartnerAdmin` or `OrgAdmin` claim grants nothing here. - Required: an active member of the group. A caller who is not one receives `403 not a member of this group`, whether or not the group exists. operationId: get_group_reactions parameters: - description: The group whose reactions are returned. required: true schema: type: string title: Group Id description: The group whose reactions are returned. examples: - b7d1f0c9a2e4d6f8b0c1 name: group_id in: path - description: >- The day whose reactions are read or written (YYYY-MM-DD). Defaults to today in JST (UTC+09:00). required: false schema: type: string title: Day Str description: >- The day whose reactions are read or written (YYYY-MM-DD). Defaults to today in JST (UTC+09:00). examples: - '2026-10-14' name: day_str in: query responses: '200': description: >- A map of member uid to that member's reactions. Members with none are omitted. headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: {} example: day: '2026-10-14' members: user456: - id: muscle emoji: 💪 count: 2 mine: true uids: - user123 - user789 - id: party emoji: 🎉 count: 1 mine: false uids: - user789 '400': description: Bad Request - day_str is not a YYYY-MM-DD date headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: bad-request error_msg: Invalid day_str format. Use 'YYYY-MM-DD'. '401': description: Unauthorized - the credentials are missing, expired or invalid headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: http-error error_msg: Invalid authentication credentials. '403': description: Forbidden - Not enough permission headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: forbidden error_msg: Not enough permission '422': description: >- Unprocessable Entity - a request field does not meet the endpoint's validation rules content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: unprocessable-entity error_msg: 'body.: ' '429': description: Too Many Requests - the rate limit was exceeded headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 Retry-After: description: >- Whole seconds to wait until both applicable buckets can accept one request. Returned only with a 429 response. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate-limited error_msg: Rate limit exceeded. Retry after seconds. '500': description: Internal Server Error - Failed to fetch data headers: X-RateLimit-Limit: description: Maximum capacity of the continuously refilled minute bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining: description: Whole tokens remaining in the minute bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset: description: >- Unix timestamp in seconds when the minute bucket is expected to be full. This is not a calendar reset time. schema: type: integer minimum: 0 format: int64 X-RateLimit-Limit-Day: description: Maximum capacity of the continuously refilled daily bucket. schema: type: integer minimum: 0 X-RateLimit-Remaining-Day: description: Whole tokens remaining in the daily bucket after this request. schema: type: integer minimum: 0 X-RateLimit-Reset-Day: description: >- Unix timestamp in seconds when the daily bucket is expected to be full. The bucket refills continuously and does not reset at midnight. schema: type: integer minimum: 0 format: int64 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: internal-server-error error_msg: 'Failed to fetch data: ' security: - HTTPBearer: [] - SoxaiApiKey: [] components: schemas: ErrorResponse: properties: error: type: string title: Error description: Machine-readable error category. examples: - bad-request error_msg: type: string title: Error Msg description: Human-readable explanation of the error; clients must not parse it. examples: - 'Invalid input: start_time must use YYYY-MM-DD.' type: object required: - error - error_msg title: ErrorResponse description: >- The body of every error answer: a machine-readable type and a human-readable message. securitySchemes: HTTPBearer: type: http scheme: bearer SoxaiApiKey: type: apiKey description: >- API key issued by `POST /api-key/secret`, sent in the `soxai-api-key` header. It is an alternative to the Bearer token, not an addition to it: when both are sent the Bearer token is used. The key carries the same roles as the user it was issued to, and expires after the number of days it was issued for. in: header name: soxai-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.