thymia Documentation

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

import requests
url = "https://api.example.com/v1/models/apollo"
payload = {
    "user": {
        "userLabel": "42baba59-fa4a-4a22-ba1c-2e4a88a3badb",
        "dateOfBirth": "1990-08-24",
        "birthSex": "MALE"
    },
    "language": "en-GB"
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Try it

Response

{
  "id": "string",
  "uploadUrls": {
    "moodQuestionUploadUrl": "https://path/to/upload/mood",
    "readAloudUploadUrl": "https://path/to/upload/read"
  }
}

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

import requests
url = "https://api.example.com/v1/models/apollo/model_run_id"
headers = {"x-api-key": "<apiKey>"}
response = requests.get(url, headers=headers)
print(response.json())

Try it

Status	Meaning
`CREATED`	Waiting for recordings to be uploaded
`RUNNING`	Both recordings uploaded, model is processing
`COMPLETE_OK`	Processing complete, results and report available
`COMPLETE_ERROR`	Processing failed, see `errorCode` for details

Response

{
  "id": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "status": "COMPLETE_OK",
  "userLabel": "string",
  "deleteData": true,
  "runAt": "2024-01-15T09:30:00Z",
  "completedAt": "2019-08-24T14:16:000Z",
  "errorReason": "string",
  "warnings": [
    "string"
  ],
  "results": {
    "disorders": {
      "depression": {
        "probability": 0.4067141389309715,
        "severity": 0.4132388744110295
      },
      "anxiety": {
        "probability": 0.47175616834793105,
        "severity": 0.46294827856683424
      }
    },
    "symptoms": {
      "depression": {
        "anhedonia": {
          "severity": 0.46184084704582423,
          "distribution": {
            "none": 0.24197039159529662,
            "mild": 0.33255350122191146,
            "moderate": 0.2234592816328142,
            "severe": 0.2020168255499776
          }
        },
        "lowmood": {
          "severity": 0.40891653727822747,
          "distribution": {
            "none": 0.35240554066126856,
            "mild": 0.2653016782309672,
            "moderate": 0.18543040971957758,
            "severe": 0.19686237138818666
          }
        },
        "sleepissues": {
          "severity": 0.6094861501812012,
          "distribution": {
            "none": 0.1410383730497576,
            "mild": 0.21450948727434468,
            "moderate": 0.31940745575843443,
            "severe": 0.32504468391746333
          }
        },
        "lowenergy": {
          "severity": 0.4080467716870091,
          "distribution": {
            "none": 0.2465850339598515,
            "mild": 0.4124245852974307,
            "moderate": 0.21125541246455634,
            "severe": 0.1297349682781613
          }
        },
        "appetiteissues": {
          "severity": 0.3116398948698012,
          "distribution": {
            "none": 0.46100935482842137,
            "mild": 0.26781612021409124,
            "moderate": 0.14642001047714992,
            "severe": 0.1247545144803375
          }
        },
        "worthlessnessissues": {
          "severity": 0.2639105079099775,
          "distribution": {
            "none": 0.5283513711504902,
            "mild": 0.25618082569043343,
            "moderate": 0.1108527114377303,
            "severe": 0.10461509172134617
          }
        },
        "concentrationissues": {
          "severity": 0.5055735610043838,
          "distribution": {
            "none": 0.2155407066482807,
            "mild": 0.28576732944757405,
            "moderate": 0.26512253814685866,
            "severe": 0.2335694257572866
          }
        },
        "psychomotorissues": {
          "severity": 0.3364967253118117,
          "distribution": {
            "none": 0.4546550374827019,
            "mild": 0.22981182358117028,
            "moderate": 0.16692106445411847,
            "severe": 0.1486120744820093
          }
        }
      },
      "anxiety": {
        "nervousness": {
          "severity": 0.48281020556845206,
          "distribution": {
            "none": 0.2581415065283512,
            "mild": 0.2806762383950776,
            "moderate": 0.21579238691943517,
            "severe": 0.24538986815713615
          }
        },
        "uncontrollableworry": {
          "severity": 0.37084304502323606,
          "distribution": {
            "none": 0.3749962195524081,
            "mild": 0.29448429664400494,
            "moderate": 0.1735136129850577,
            "severe": 0.15700587081852932
          }
        },
        "excessiveworry": {
          "severity": 0.38841342182687094,
          "distribution": {
            "none": 0.32929279938104206,
            "mild": 0.3356483359758936,
            "moderate": 0.1755846644244737,
            "severe": 0.15947420021859068
          }
        },
        "troublerelaxing": {
          "severity": 0.6678929399237447,
          "distribution": {
            "none": 0.1026108764334131,
            "mild": 0.1720327504635266,
            "moderate": 0.3444230500014736,
            "severe": 0.3809333231015867
          }
        },
        "restlessness": {
          "severity": 0.48338808178548404,
          "distribution": {
            "none": 0.2545397514505825,
            "mild": 0.26975254891838296,
            "moderate": 0.2467114024550342,
            "severe": 0.22899629717600023
          }
        },
        "irritability": {
          "severity": 0.3970791626763033,
          "distribution": {
            "none": 0.3218806625247734,
            "mild": 0.32670323997606787,
            "moderate": 0.18971404444463374,
            "severe": 0.1617020530545248
          }
        },
        "dread": {
          "severity": 0.450211093163748,
          "distribution": {
            "none": 0.30946646688056556,
            "mild": 0.24927688874671267,
            "moderate": 0.22241354237363423,
            "severe": 0.21884310199908763
          }
        }
      }
    }
  },
  "report": {
    "viewUrl": "https://reports.thymia.ai/v1/reports/123e4567-e89b-12d3-a456-426614174000?token=...",
    "pdfUrl": "https://reports.thymia.ai/v1/reports/123e4567-e89b-12d3-a456-426614174000/pdf?token=...",
    "accessExpiresAt": "2024-12-31T23:59:59Z"
  },
  "errorCode": "ERR_RECORDING_INVALID_FORMAT",
  "model": "string"
}

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