Cognitive Assessment API

The Cognitive Assessment API lets your backend create a hosted HK-MoCA 5-minute assessment for an external user. GOFA hosts the audio flow and returns only the formal scores, total, percentile interpretation, and confirmed demographics.

Workflow

1. From your server, create a session with a bearer API key.
2. Open the returned launchUrl in a top-level browser or camera-capable WebView.
3. Let the user complete the hosted flow. The same URL can be reopened while the session is active and retries do not consume another point.
4. Poll the session until it is completed or expired. Treat return navigation as a hint and use this endpoint as the authoritative status and result source.

The launch URL is a hosted boundary; inline iframe embedding is not supported.

Authentication and workspace setup

Keep the API key on your server. Do not put it in browser code, mobile apps, URLs, or the hosted page. Activate Cognitive Assessment in API → API Services and add the exact HTTPS return origin in the shared Allowed return origins setting before sending returnUrl.

Create a hosted session

POST /api/v1/cognitive-assessment/sessions

The request body is strict:

curl --request POST 'https://www.gofa.app/api/v1/cognitive-assessment/sessions' \
  --header 'Authorization: Bearer <GOFA_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "customer-member-123",
    "locale": "en",
    "age": 72,
    "educationYears": 6,
    "returnUrl": "https://your-app.example/cognitive/complete"
  }'

The response is 201 Created:

{
  "data": {
    "cognitiveAssessmentSessionId": "<generated-session-id>",
    "userId": "customer-member-123",
    "status": "in_progress",
    "createdAt": "2026-09-20T09:00:00.000Z",
    "updatedAt": "2026-09-20T09:00:00.000Z",
    "completedAt": null,
    "expiresAt": "2026-09-20T11:00:00.000Z",
    "resultExpiresAt": "2026-10-20T09:00:00.000Z",
    "returnUrl": "https://your-app.example/cognitive/complete",
    "locale": "en",
    "demographics": { "age": 72, "educationYears": 6 },
    "result": null,
    "launchUrl": "https://www.gofa.app/cognitive-assessment-audio/runs/<id>#sessionToken=<temporary-token>"
  }
}

Every successful POST creates a new session and consumes one point. There is no customer-supplied idempotency key. A temporary launch credential is scoped to the client and session, expires with the two-hour unfinished session window, and must never be logged or forwarded to another user.

Read status and formal result

GET /api/v1/cognitive-assessment/sessions/{cognitiveAssessmentSessionId}

GET is free, still requires the bearer API key, and is limited to one poll every five seconds per session. Wait for Retry-After after a 429. A completed session remains readable through the separate resultExpiresAt retention window even after its launch URL expires.

The completed result contains the formal per-domain scores, raw and adjusted total, education bonus, percentile label/risk interpretation, and the confirmed age and education values. It does not contain recordings, audio URLs, model costs, raw diagnostics, or technical capture data.

Return navigation and deletion

After completion or an early exit, GOFA navigates to the approved return origin with only cognitive_assessment_session_id and status query parameters. Do not treat these values as the result; fetch the session from your server.

DELETE /api/v1/cognitive-assessment/sessions/{cognitiveAssessmentSessionId}

DELETE is free and returns 204 No Content for a session owned by the key. It soft-deletes the session and never refunds the point used at creation. It can be used after launch expiry while retention permits cleanup.