API Guide

The Cardio.AI REST API lets an external system submit ECG recordings for analysis and receive the final result as a PDF report.

ECG analysis workflow

The standard business flow is:

1. Upload an ECG file or archive.
2. Create an ECG analysis task from the uploaded data.
3. Review the analysis in the Cardio.AI viewer.
4. Generate and download the final PDF report.

This flow is used when a specialist must inspect the AI annotations, adjust the result if needed, and approve the report before it is delivered.

Auto-review workflow

For integrations that do not require manual review in the viewer, create the task with auto_complete enabled.

In this mode, Cardio.AI processes the recording, completes the task automatically, and makes the PDF report available through the API:

1. Upload an ECG file or archive.
2. Create an ECG analysis task with auto_complete.
3. Poll the task status until processing is complete and the report is available.
4. Download the PDF report or create a read-only share link.

The task request can include patient, recording, report, and search metadata. Metadata provided in the API request overrides values detected from uploaded ECG files.

Upload transport

Large ECG files are uploaded through chunked transfer. The client creates an upload session with the total file size and SHA-256 hash, sends file chunks with byte offsets, and then uses the returned upload_id when creating the analysis task.

Supported input

The upload endpoints accept standalone ECG files and archives containing ECG files. The system identifies supported formats from file content where possible, decodes each record, and exposes the decoded records to subsequent analysis tasks.

ECG file formats

Format	Detection method	Files per record
EDF / EDF+	Header heuristics	1
SCP-ECG	Section pointer table in header	1
WFDB	File extension (.hea + .dat)	2 or more

Archive containers

Multiple ECG files can be packed into one upload using these archive formats:

Format	Typical extensions	Internal compression methods
ZIP	.zip	Store, Deflate, Deflate64, LZMA, bzip2, xz, Zstandard
TAR	.tar	none
TAR + gzip	.tar.gz, .tgz	gzip
TAR + bzip2	.tar.bz2, .tbz2	bzip2
TAR + xz	.tar.xz, .txz	xz
TAR + lz4	.tar.lz4	lz4
TAR + Zstandard	.tar.zst	Zstandard
7-Zip	.7z	LZMA, LZMA2, bzip2, Deflate
RAR 4.x	.rar	LZ, PPMd
RAR 5.0	.rar	LZ, DELTA / x86 / ARM filters

Upload detection

If the upload opens as an archive, each entry is processed in turn. Otherwise, the upload is treated as a single file.

For each standalone file or archive entry, the system attempts single-file detection in this order:

Priority	Format	Detection
1	EDF / EDF+	Fixed-header heuristics
2	SCP-ECG	Section pointer table in header

Archive entries that do not match a single-file format are passed to multi-file matchers. Multi-file formats are described below.

Files inside an archive that match no supported format are skipped. A standalone upload that matches no supported format returns an error.

Multi-file records

Some formats consist of multiple files that together form one or more records. WFDB is the only such format currently supported: a text header (.hea) is paired with one or more binary data files (.dat). To upload WFDB data, place the files into one of the supported archives.

Files inside an archive are grouped by directory path: every entry sharing the same prefix before the last / belongs to the same directory group. Each .hea file in a directory group produces one record, referencing its .dat files by name from a shared pool inside that group. Different directory groups are independent, even when file names overlap.

Multiple records sharing a directory

archive.zip/
  patient1/ecg_rest.hea       -> record "ecg_rest"
  patient1/ecg_rest.dat
  patient1/ecg_exercise.hea   -> record "ecg_exercise"
  patient1/ecg_exercise.dat

Each .hea file produces a record, and each record references its own .dat file from the directory’s shared pool.

Shared data file

archive.zip/
  study/record_a.hea    -> record A, references "shared.dat"
  study/record_b.hea    -> record B, references "shared.dat"
  study/shared.dat      -> used by both records

Both .hea files reference the same .dat file from the shared pool.

Mixed archive

Single-file and multi-file formats can be combined in one archive:

archive.zip/
  wfdb_data/record.hea        -> WFDB record
  wfdb_data/record.dat
  resting_ecg.edf             -> EDF record
  rhythm_strip.scp            -> SCP-ECG record

EDF and SCP-ECG entries are decoded as the archive is read. WFDB files accumulate and are decoded after the full archive walk. The output contains records from both groups.

Upload output

Each successful upload yields an ordered list of records. Each record contains:

• A name: the file name for single-file formats, or the record name from the header for multi-file formats.
• One or more signals with sample data and metadata.
• Optional personal data, extra readings, and classification data, depending on the format.

Records appear in this order: single-file records first, in archive entry order, then multi-file records.

Reference

• API Reference