Integration Guide

This guide covers everything required to build a production-ready Helios integration — user data, recording requirements, data deletion, tagging, and error handling. If you have not yet made your first Helios API call, start with the Quickstart.

Architecture

A Helios integration has three components:

1. Your backend — creates model runs, handles recording uploads, and polls for results via the thymia API. Your API key must never be exposed in client-side code.
2. Your frontend — captures audio from your users and passes it to your backend for upload, or embeds the thymia Widget to handle capture directly.
3. thymia API — processes the recording and returns biomarker scores.

How your frontend and backend communicate is specific to your infrastructure. The thymia API is called exclusively from your backend.

User data

Every model run requires a user object containing three fields. This data is used to benchmark results against a matched population — accuracy is directly affected by the quality of information supplied.

1
curl -X POST /v1/models/mental-wellness \
2
     -H "x-api-key: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "user": {
6
    "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
7
    "dateOfBirth": "1990-08-24",
8
    "birthSex": "MALE"
9
  },
10
  "language": "en-GB"
11
}'

Language and accent

The language field specifies the language and dialect the user will be speaking. Choosing the most accurate code for your user improves transcription quality and benchmarking accuracy.

Recording requirements

Sleep and recording time

For more accurate results, you can optionally pass the user’s sleep and wake times alongside the time the recording was made:

1
curl -X POST /v1/models/mental-wellness \
2
     -H "x-api-key: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "user": {
6
    "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
7
    "dateOfBirth": "1990-08-24",
8
    "birthSex": "MALE"
9
  },
10
  "language": "en-GB"
11
}'

Tagging model runs

Tags are name/value pairs you can attach to a model run for later identification and filtering.

1
curl -X POST /v1/models/mental-wellness \
2
     -H "x-api-key: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "user": {
6
    "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
7
    "dateOfBirth": "1990-08-24",
8
    "birthSex": "MALE"
9
  },
10
  "language": "en-GB"
11
}'

Data deletion

1
curl -X POST /v1/models/mental-wellness \
2
     -H "x-api-key: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "user": {
6
    "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
7
    "dateOfBirth": "1990-08-24",
8
    "birthSex": "MALE"
9
  },
10
  "language": "en-GB"
11
}'

Polling for results

After uploading the recording, poll GET /v1/models/mental-wellness/{model_run_id} until the status field is no longer RUNNING. We recommend polling every 3 seconds.

1
curl /v1/models/mental-wellness/model_run_id \
2
     -H "x-api-key: <apiKey>" \
3
     -H "Content-Type: application/json"

Error handling

If the model run completes with COMPLETE_ERROR, check the errorCode field to determine the cause and next action. See the Error Reference for the full list of error codes and recommended responses.

The most common errors in production are:

Multi-region

Contact support@thymia.ai to enable regional data storage for your account.

Next steps

• Interpreting Results — Understand what the scores mean and how to present them to users.
• Error Reference — Full reference for all Helios error codes.
• API Reference — Complete endpoint documentation for the Helios API.