thymia Documentation

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

Architecture

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.
Your frontend — captures or sources two voice recordings per patient and passes them to your backend for upload.
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`.

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.

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

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.

Uploading recordings

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

POST

/v1/models/apollo

1 curl -X POST /v1/models/apollo \
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 }'

Try it

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.

Polling for results

GET

/v1/models/apollo/:model_run_id

1 curl /v1/models/apollo/model_run_id \
2      -H "x-api-key: <apiKey>"

Try it

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

Response

1 {
2   "id": "string",
3   "createdAt": "2019-08-24T14:15:22Z",
4   "status": "COMPLETE_OK",
5   "userLabel": "string",
6   "deleteData": true,
7   "runAt": "2024-01-15T09:30:00Z",
8   "completedAt": "2019-08-24T14:16:000Z",
9   "errorReason": "string",
10   "warnings": [
11     "string"
12   ],
13   "results": {
14     "disorders": {
15       "depression": {
16         "probability": 0.4067141389309715,
17         "severity": 0.4132388744110295
18       },
19       "anxiety": {
20         "probability": 0.47175616834793105,
21         "severity": 0.46294827856683424
22       }
23     },
24     "symptoms": {
25       "depression": {
26         "anhedonia": {
27           "severity": 0.46184084704582423,
28           "distribution": {
29             "none": 0.24197039159529662,
30             "mild": 0.33255350122191146,
31             "moderate": 0.2234592816328142,
32             "severe": 0.2020168255499776
33           }
34         },
35         "lowmood": {
36           "severity": 0.40891653727822747,
37           "distribution": {
38             "none": 0.35240554066126856,
39             "mild": 0.2653016782309672,
40             "moderate": 0.18543040971957758,
41             "severe": 0.19686237138818666
42           }
43         },
44         "sleepissues": {
45           "severity": 0.6094861501812012,
46           "distribution": {
47             "none": 0.1410383730497576,
48             "mild": 0.21450948727434468,
49             "moderate": 0.31940745575843443,
50             "severe": 0.32504468391746333
51           }
52         },
53         "lowenergy": {
54           "severity": 0.4080467716870091,
55           "distribution": {
56             "none": 0.2465850339598515,
57             "mild": 0.4124245852974307,
58             "moderate": 0.21125541246455634,
59             "severe": 0.1297349682781613
60           }
61         },
62         "appetiteissues": {
63           "severity": 0.3116398948698012,
64           "distribution": {
65             "none": 0.46100935482842137,
66             "mild": 0.26781612021409124,
67             "moderate": 0.14642001047714992,
68             "severe": 0.1247545144803375
69           }
70         },
71         "worthlessnessissues": {
72           "severity": 0.2639105079099775,
73           "distribution": {
74             "none": 0.5283513711504902,
75             "mild": 0.25618082569043343,
76             "moderate": 0.1108527114377303,
77             "severe": 0.10461509172134617
78           }
79         },
80         "concentrationissues": {
81           "severity": 0.5055735610043838,
82           "distribution": {
83             "none": 0.2155407066482807,
84             "mild": 0.28576732944757405,
85             "moderate": 0.26512253814685866,
86             "severe": 0.2335694257572866
87           }
88         },
89         "psychomotorissues": {
90           "severity": 0.3364967253118117,
91           "distribution": {
92             "none": 0.4546550374827019,
93             "mild": 0.22981182358117028,
94             "moderate": 0.16692106445411847,
95             "severe": 0.1486120744820093
96           }
97         }
98       },
99       "anxiety": {
100         "nervousness": {
101           "severity": 0.48281020556845206,
102           "distribution": {
103             "none": 0.2581415065283512,
104             "mild": 0.2806762383950776,
105             "moderate": 0.21579238691943517,
106             "severe": 0.24538986815713615
107           }
108         },
109         "uncontrollableworry": {
110           "severity": 0.37084304502323606,
111           "distribution": {
112             "none": 0.3749962195524081,
113             "mild": 0.29448429664400494,
114             "moderate": 0.1735136129850577,
115             "severe": 0.15700587081852932
116           }
117         },
118         "excessiveworry": {
119           "severity": 0.38841342182687094,
120           "distribution": {
121             "none": 0.32929279938104206,
122             "mild": 0.3356483359758936,
123             "moderate": 0.1755846644244737,
124             "severe": 0.15947420021859068
125           }
126         },
127         "troublerelaxing": {
128           "severity": 0.6678929399237447,
129           "distribution": {
130             "none": 0.1026108764334131,
131             "mild": 0.1720327504635266,
132             "moderate": 0.3444230500014736,
133             "severe": 0.3809333231015867
134           }
135         },
136         "restlessness": {
137           "severity": 0.48338808178548404,
138           "distribution": {
139             "none": 0.2545397514505825,
140             "mild": 0.26975254891838296,
141             "moderate": 0.2467114024550342,
142             "severe": 0.22899629717600023
143           }
144         },
145         "irritability": {
146           "severity": 0.3970791626763033,
147           "distribution": {
148             "none": 0.3218806625247734,
149             "mild": 0.32670323997606787,
150             "moderate": 0.18971404444463374,
151             "severe": 0.1617020530545248
152           }
153         },
154         "dread": {
155           "severity": 0.450211093163748,
156           "distribution": {
157             "none": 0.30946646688056556,
158             "mild": 0.24927688874671267,
159             "moderate": 0.22241354237363423,
160             "severe": 0.21884310199908763
161           }
162         }
163       }
164     }
165   },
166   "report": {
167     "viewUrl": "https://reports.thymia.ai/v1/reports/123e4567-e89b-12d3-a456-426614174000?token=...",
168     "pdfUrl": "https://reports.thymia.ai/v1/reports/123e4567-e89b-12d3-a456-426614174000/pdf?token=...",
169     "accessExpiresAt": "2024-12-31T23:59:59Z"
170   },
171   "errorCode": "ERR_RECORDING_INVALID_FORMAT",
172   "model": "string"
173 }

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`

Integration Guide