> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.thymia.ai/helios/llms.txt.
> For full documentation content, see https://docs.thymia.ai/helios/llms-full.txt.

# 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](/helios/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.

| Field         | Type   | Description                                                                                                                                           |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userLabel`   | string | A unique identifier for the user in your system. Max 50 characters. Model runs with the same `userLabel` are assumed to refer to the same individual. |
| `dateOfBirth` | date   | ISO 8601 date. If day or month are unknown, supply the known parts and use `01` for the rest.                                                         |
| `birthSex`    | enum   | Sex assigned at birth. Accepted values: `MALE`, `FEMALE`, `INTERSEX`, `UNKNOWN`.                                                                      |

<EndpointRequestSnippet endpoint="POST /v1/models/mental-wellness" />

## 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.

| Field      | Type | Description                                                                  |
| ---------- | ---- | ---------------------------------------------------------------------------- |
| `language` | enum | BCP 47 language code. Required.                                              |
| `accent`   | enum | Accent in addition to language. Optional. Accepted values: `ID`, `NG`, `KE`. |

## Recording requirements

| Requirement              | Value                          |
| ------------------------ | ------------------------------ |
| Minimum speech duration  | 10 seconds                     |
| Maximum recording length | 3 minutes                      |
| Supported formats        | FLAC, MP3, MP4, Ogg, WebM, WAV |
| Upload URL validity      | 1 hour                         |

<Warning>
  The upload URL returned when creating a model run is valid for 1
  hour. If the URL expires before the recording is uploaded, create
  a new model run.
</Warning>

### 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:

| Field           | Format                         | Description                                         |
| --------------- | ------------------------------ | --------------------------------------------------- |
| `sleepTime`     | ISO 8601 datetime, no timezone | When the user fell asleep for their last main sleep |
| `wakeTime`      | ISO 8601 datetime, no timezone | When the user woke from their last main sleep       |
| `recordingTime` | ISO 8601 datetime, no timezone | When the recording was made                         |

<EndpointRequestSnippet endpoint="POST /v1/models/mental-wellness" />

<Note>
  Sleep and recording time fields should not include timezone
  information. They are assumed to be in the local timezone of the
  user at the time of recording.
</Note>

## Tagging model runs

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

| Constraint               | Value                  |
| ------------------------ | ---------------------- |
| Maximum tags per run     | 20                     |
| Maximum tag name length  | 40 characters          |
| Maximum tag value length | 100 characters         |
| Tag names                | Must be unique per run |

<EndpointRequestSnippet endpoint="POST /v1/models/mental-wellness" />

## Data deletion

| Field          | Type    | Description                                                                                                                                        |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deleteData`   | boolean | If `true`, all data associated with the model run is deleted 12 hours after completion. Default: `false`.                                          |
| `dataToDelete` | array   | Specify which data types to delete. Currently supports `RECORDINGS`. If `deleteData` is `true` and `dataToDelete` is omitted, all data is deleted. |

<EndpointRequestSnippet endpoint="POST /v1/models/mental-wellness" />

<Note>
  thymia is GDPR and HIPAA compliant. For data processing agreements
  or privacy queries, contact [support@thymia.ai](mailto:support@thymia.ai).
</Note>

## 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.

<EndpointRequestSnippet endpoint="GET /v1/models/mental-wellness/{model_run_id}" />

| Status           | Action                                                                |
| ---------------- | --------------------------------------------------------------------- |
| `CREATED`        | Recording not yet uploaded. Check your upload completed successfully. |
| `RUNNING`        | Model is processing. Continue polling.                                |
| `COMPLETE_OK`    | Results available in the `results` field.                             |
| `COMPLETE_ERROR` | Processing failed. Check `errorCode` and `errorReason`.               |

## 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](/helios/error-reference) for the full list of
error codes and recommended responses.

The most common errors in production are:

| Error code                     | Cause                                              | Recommended action                                          |
| ------------------------------ | -------------------------------------------------- | ----------------------------------------------------------- |
| `ERR_RECORDING_TOO_SHORT`      | Recording contained less than 10 seconds of speech | Ask the user to speak for longer and submit a new model run |
| `ERR_TRANSCRIPTION_FAILED`     | No speech detected in the recording                | Check audio quality and resubmit                            |
| `ERR_RECORDING_INVALID_FORMAT` | Unsupported file format                            | Convert to a supported format and resubmit                  |

## Multi-region

| Region        | Base URL                   |
| ------------- | -------------------------- |
| Default       | `https://api.thymia.ai`    |
| Canada        | `https://ca.api.thymia.ai` |
| United States | `https://us.api.thymia.ai` |

Contact [support@thymia.ai](mailto:support@thymia.ai) to enable
regional data storage for your account.

## Next steps

* [Interpreting Results](/helios/interpreting-results) —
  Understand what the scores mean and how to present them to users.
* [Error Reference](/helios/error-reference) — Full reference
  for all Helios error codes.
* [API Reference](/api-reference) — Complete endpoint
  documentation for the Helios API.

<div>
  ***
</div>

<div>
  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/bc677a592c05a522bf7c895b7e9f00da344a3487d5e6baf5e35f4b013bf0e0e5/docs/assets/certs/crown-commerical-logo.png" alt="Crown Commercial Service" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/0fd8cd1c5e2bf5fe9c88a9671b5d62d76ee00fff93b057d3f28295f6e74a8e54/docs/assets/certs/nhs-digital-toolkit-logo.png" alt="NHS Digital" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/3408b37c11afb0482b6108012fdea2edc6843ffa1a6a485d9440f2c28067165c/docs/assets/certs/iso-27001-logo.png" alt="ISO 27001" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/f82c2989ef0c7907f8acc1bf38c1debfb8061a0bad0fd4aff7a724794739e5b0/docs/assets/certs/iso-13485-logo.png" alt="ISO 13485" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/44816901d032fd0dc4b99030c62e6841d10b1796fde6dd1615bf23eb84f9114b/docs/assets/certs/HIPPA-logo.png" alt="HIPAA" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/1c6800dfced2f3bd97bd907302e2ae105c99ed91fd381e0cd64eef7886394779/docs/assets/certs/gdpr-logo.png" alt="GDPR" />

  <img src="https://files.buildwithfern.com/https://thymia.docs.buildwithfern.com/2276326b82aee8a143219440498266a25a1425c423a6854489e706af50d38118/docs/assets/certs/cyber-essentials-logo.png" alt="Cyber Essentials Certified" />
</div>