The analysis, as an API.

Getting started

Request an API key

Your name Work email What you are integrating Request an API key

A first request

curl "https://api.beataware.com/v1/patients" \
  -H "x-api-key: $BEATAWARE_API_KEY"

The code scrolls sideways.

In the examples, $BEATAWARE_API_KEY is your key, $PATIENT is a patient id returned by POST /patients, and $RECORDING is the recording id returned by the upload.

Upload a recording and fetch its report

# 1. Create the patient (firstName and lastName are required)
curl -X POST "https://api.beataware.com/v1/patients" \
  -H "x-api-key: $BEATAWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Sam","lastName":"Rivera","dob":"1971-04-12"}'
# -> 201 { "id": "pat_…", "firstName": "Sam", … }

# 2. Upload a heart-sound recording (WAV or MP3) as the "audio" field
curl -X POST \
  "https://api.beataware.com/v1/patients/$PATIENT/recordings" \
  -H "x-api-key: $BEATAWARE_API_KEY" \
  -F "audio=@heart.wav"
# -> 201 { "recordingId": "rec_…" }

# 3. Poll until the status is "ready"
curl "https://api.beataware.com/v1/recordings/$RECORDING/status" \
  -H "x-api-key: $BEATAWARE_API_KEY"
# -> 200 { "status": "processing", "estimatedTime": "30s" }

# 4. Download the report
curl "https://api.beataware.com/v1/recordings/$RECORDING/report" \
  -H "x-api-key: $BEATAWARE_API_KEY" -o report.json

The code scrolls sideways.

Status is processing while the recording is queued or being analysed, ready when the report can be downloaded, and failed when the recording could not be read. Analysis usually takes a few seconds to a minute. Twenty seconds of mono WAV at 4 kHz is what the app sends; the service also accepts higher sample rates and MP3.

What comes back

{
  "reportMarkdown": "# Heart sound analysis\n\n18 beats accepted …",
  "statistics": [
    {
      "heart_rate": 66,
      "cardiac_cycle": 900.4,
      "s1_duration":       { "mean": 112.3, "std": 6.1 },
      "systole_duration":  { "mean": 214.0, "std": 9.8 },
      "s2_duration":       { "mean": 96.2,  "std": 5.4 },
      "diastole_duration": { "mean": 477.9, "std": 14.2 }
    }
  ]
}

The code scrolls sideways.

Illustrative values; durations in milliseconds. The shape is the CardiologyReportItem schema in the specification.

Patients

Recordings and reports

What a report contains

The report comes back as JSON: a written report in Markdown that a clinician can read as it is, and the statistics behind it, the four durations of the cardiac cycle with their variation, the cycle length and the heart rate.

Field	Meaning
reportMarkdown	The written report, in Markdown, ready to render or print for a clinician
statistics[].heart_rate	Beats a minute over the accepted beats
statistics[].cardiac_cycle	Mean cycle length in milliseconds, S1 to S1
statistics[].s1_duration, s2_duration	Mean and standard deviation of the first and second heart sounds, in milliseconds
statistics[].systole_duration, diastole_duration	Mean and standard deviation of systole and diastole, in milliseconds

Blood pressure estimates are part of the consumer app's analysis, not of this API.