Quickstart

Make your first Apollo API call and retrieve clinical assessment results.
View as Markdown

In this guide you will create an Apollo model run, upload two voice recordings, and retrieve disorder and symptom scores — the complete end-to-end flow of an Apollo integration.

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.

Prerequisites

  • A thymia API key with Apollo access enabled. Contact support@thymia.ai to request access.
  • Two voice recordings in a supported format (FLAC, MP3, MP4, Ogg, WebM, or WAV), each containing at least 15 seconds of speech:
    • A mood question recording — the patient’s spoken response to an open question such as “How are you feeling today?”
    • A read-aloud recording — the patient reading a standard passage aloud

Step 1 — Create a model run

POST
/v1/models/apollo
1curl -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
Response
1{
2  "id": "string",
3  "uploadUrls": {
4    "moodQuestionUploadUrl": "https://path/to/upload/mood",
5    "readAloudUploadUrl": "https://path/to/upload/read"
6  }
7}

Do not use personally identifiable information such as names or NHS numbers as the userLabel. Use an anonymised reference from your system.

Step 2 — Upload both recordings

Both recordings must be uploaded before Apollo will begin processing.

Upload the mood question recording:

$curl "https://path/to/upload/mood" \
>  -X PUT \
>  -H 'Content-Type: audio/mpeg' \
>  --data-binary '@/path/to/mood-question.mp3'

Upload the read-aloud recording:

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

Both upload URLs are valid for 1 hour. The model will not begin processing until both recordings have been successfully uploaded.

Step 3 — Poll for results

GET
/v1/models/apollo/:model_run_id
1curl /v1/models/apollo/model_run_id \
2     -H "x-api-key: <apiKey>"
Try it
StatusMeaning
CREATEDWaiting for recordings to be uploaded
RUNNINGBoth recordings uploaded, model is processing
COMPLETE_OKProcessing complete, results and report available
COMPLETE_ERRORProcessing failed, see errorCode for details
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}

Apollo results must be reviewed and interpreted by a qualified healthcare professional. They must not be communicated directly to patients without clinical review.

Next steps

Crown Commercial ServiceNHS DigitalISO 27001ISO 13485HIPAAGDPRCyber Essentials Certified