Initiate an ECG signal stream

POST

/v3/streams/start

curl --request POST \
  --url https://api.cardio.ai/v3/streams/start \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Token: <X-Api-Token>' \
  --data '{ "task_id": 1, "device_id": "example", "processing_mode": "PROCESS_ON_FINISH", "frame_format": "COMPRESSED_DELTA", "sample_rate": 1, "lead_codes": [ "MDC_ECG_LEAD_I" ], "digital_minimum": 1, "digital_maximum": 1, "physical_minimum": 1, "physical_maximum": 1, "device_state": "WAITING_FOR_START", "total_frames": 1 }'

• Production REST API endpoint.

Opens a real-time channel that ingests framed ECG samples from a device. A stream is bound to an existing analysis task for its whole lifetime and inherits all access rules of that task.

Optional scaling parameters

Include all four scaling fields to enable backend linear conversion from raw ADC values to millivolts:

physical = (digital - digital_minimum) *
    (physical_maximum - physical_minimum) /
    (digital_maximum - digital_minimum) +
    physical_minimum

If any scaling field is missing, the backend assumes samples are already expressed in millivolts.

Frame format: COMPRESSED_DELTA

COMPRESSED_DELTA is a compact binary container for multi-channel bio-signals. See the Compressed Delta specification for format details.

Authorizations

• ApiToken

Request Body ^required

Start stream request.

Media type application/json

Any of:

object

Request payload for starting a stream attached to the specified analysis task.

object

task_id

required

ID of an existing analysis task to which the stream will be attached. Either task_id or device_id must be provided.

integer format: uint64

device_id

Device identifier used to select the latest waiting task if task_id is omitted.

string

processing_mode

required

Mode for processing the stream data.

string

Allowed values: PROCESS_ON_FINISH

frame_format

required

Format for the stream data frames.

string

Allowed values: COMPRESSED_DELTA

sample_rate

required

Sampling rate in hertz.

number format: double

lead_codes

required

Ordered ECG lead descriptors. The array length must equal the number of channels in each data frame.

Array<string>

Allowed values: MDC_ECG_LEAD_I MDC_ECG_LEAD_II MDC_ECG_LEAD_III MDC_ECG_LEAD_V1 MDC_ECG_LEAD_V2 MDC_ECG_LEAD_V3 MDC_ECG_LEAD_V4 MDC_ECG_LEAD_V5 MDC_ECG_LEAD_V6 MDC_ECG_LEAD_AVR MDC_ECG_LEAD_AVL MDC_ECG_LEAD_AVF MDC_ECG_LEAD_ES MDC_ECG_LEAD_AS MDC_ECG_LEAD_AI MDC_ECG_LEAD_A MDC_ECG_LEAD_D

digital_minimum

Raw ADC value that corresponds to physical_minimum.

number format: double

digital_maximum

Raw ADC value that corresponds to physical_maximum.

number format: double

physical_minimum

Signal value in millivolts that corresponds to digital_minimum.

number format: double

physical_maximum

Signal value in millivolts that corresponds to digital_maximum.

number format: double

device_state

Device state indicator for display in the UI.

string

Allowed values: WAITING_FOR_START RECORDING RECORDING_COMPLETED UPLOADING UPLOADING_FAILED

total_frames

Total number of frames expected to be streamed.

integer format: uint32

object

Request payload for starting a stream by device identifier. The stream is attached to the device’s most recent analysis task.

object

task_id

ID of an existing analysis task to which the stream will be attached. Either task_id or device_id must be provided.

integer format: uint64

device_id

required

Device identifier used to select the latest waiting task if task_id is omitted.

string

processing_mode

required

Mode for processing the stream data.

string

Allowed values: PROCESS_ON_FINISH

frame_format

required

Format for the stream data frames.

string

Allowed values: COMPRESSED_DELTA

sample_rate

required

Sampling rate in hertz.

number format: double

lead_codes

required

Ordered ECG lead descriptors. The array length must equal the number of channels in each data frame.

Array<string>

Allowed values: MDC_ECG_LEAD_I MDC_ECG_LEAD_II MDC_ECG_LEAD_III MDC_ECG_LEAD_V1 MDC_ECG_LEAD_V2 MDC_ECG_LEAD_V3 MDC_ECG_LEAD_V4 MDC_ECG_LEAD_V5 MDC_ECG_LEAD_V6 MDC_ECG_LEAD_AVR MDC_ECG_LEAD_AVL MDC_ECG_LEAD_AVF MDC_ECG_LEAD_ES MDC_ECG_LEAD_AS MDC_ECG_LEAD_AI MDC_ECG_LEAD_A MDC_ECG_LEAD_D

digital_minimum

Raw ADC value that corresponds to physical_minimum.

number format: double

digital_maximum

Raw ADC value that corresponds to physical_maximum.

number format: double

physical_minimum

Signal value in millivolts that corresponds to digital_minimum.

number format: double

physical_maximum

Signal value in millivolts that corresponds to digital_maximum.

number format: double

device_state

Device state indicator for display in the UI.

string

Allowed values: WAITING_FOR_START RECORDING RECORDING_COMPLETED UPLOADING UPLOADING_FAILED

total_frames

Total number of frames expected to be streamed.

integer format: uint32

Responses

200

Successful response containing the initiated stream ID.

Media type application/json

Response payload for an initiated stream.

object

stream_id

required

Unique identifier for the initiated stream.

integer format: uint64

Example ^generated

{
  "stream_id": 1
}

400

Bad Request - missing or invalid parameters.

Media type application/json

string

Example ^generated

example

401

Unauthorized - missing, expired, or invalid token.

Media type application/json

string

Example ^generated

example

403

Forbidden - the provided token is not authorized to call this endpoint.

Media type application/json

string

Example ^generated

example

409

Conflict - current resource state does not allow the operation.

Media type application/json

string

Example ^generated

example

415

Unsupported Media Type - Content-Type must be application/json.

Media type application/json

string

Example ^generated

example

429

Too Many Requests - rate limit exceeded.

Media type application/json

string

Example ^generated

example