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

# Integration Guide

This guide covers everything required to build a production-ready
Apollo integration — patient data, recording requirements, dual upload,
data deletion, and error handling. If you have not yet made your first
Apollo API call, start with the
[Quickstart](/apollo/quickstart).

<Warning>
  Apollo is a regulated medical device intended for use by qualified
  healthcare professionals only. It must not be used as a substitute
  for clinical judgement or for self-assessment.
</Warning>

## Architecture

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 or sources two voice recordings per
   patient and passes them to your backend for upload.
3. **thymia API** — processes both recordings and returns disorder
   scores, symptom scores, and a clinical report.

## Patient data

| Field         | Type   | Description                                                                                                                        |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `userLabel`   | string | A unique, anonymised identifier for the patient in your system. Max 50 characters. Do not use personally identifiable information. |
| `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`.                                                   |

<Warning>
  Do not include personally identifiable information in the
  `userLabel` field. Use an anonymised reference from your system
  to ensure compliance with GDPR and HIPAA requirements.
</Warning>

## Recordings

| Recording         | Description                                                                            |
| ----------------- | -------------------------------------------------------------------------------------- |
| **Mood question** | The patient's spoken response to an open question such as "How are you feeling today?" |
| **Read-aloud**    | The patient reading a standard passage aloud                                           |

### Recording requirements

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

<Warning>
  Both upload URLs expire 1 hour after the model run is created.
  The model will not begin processing until both recordings have
  been successfully uploaded.
</Warning>

### Uploading recordings

```bash
# Upload mood question recording
curl "https://path/to/upload/mood" \
  -X PUT \
  -H 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/mood-question.mp3'

# Upload read-aloud recording
curl "https://path/to/upload/read" \
  -X PUT \
  -H 'Content-Type: audio/mpeg' \
  --data-binary '@/path/to/read-aloud.mp3'
```

## Data deletion

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

<EndpointRequestSnippet endpoint="POST /v1/models/apollo" />

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

## Polling for results

<EndpointRequestSnippet endpoint="GET /v1/models/apollo/{model_run_id}" />

| Status           | Action                                                           |
| ---------------- | ---------------------------------------------------------------- |
| `CREATED`        | One or both recordings not yet uploaded.                         |
| `RUNNING`        | Both recordings uploaded, model is processing. Continue polling. |
| `COMPLETE_OK`    | Results, symptom scores and report URLs available.               |
| `COMPLETE_ERROR` | Processing failed. Check `errorCode` and `errorReason`.          |

## Accessing results

<EndpointResponseSnippet endpoint="GET /v1/models/apollo/{model_run_id}" />

## Error handling

| Error code                     | Cause                          | Recommended action                               |
| ------------------------------ | ------------------------------ | ------------------------------------------------ |
| `ERR_RECORDING_TOO_SHORT`      | Less than 15 seconds of speech | Ask the patient to speak for longer and resubmit |
| `ERR_TRANSCRIPTION_FAILED`     | No speech detected             | Check audio quality and resubmit                 |
| `ERR_RECORDING_INVALID_FORMAT` | Unsupported file format        | Convert 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` |

## Next steps

* [Interpreting Results](/apollo/interpreting-results)
* [Reports](/apollo/reports)
* [Error Reference](/apollo/error-reference)
* [API Reference](/api-reference)

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