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

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

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

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

{
  "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"
}

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