Skip to content

NCICTAPI User Manual

Jump to bottom
NCI Dose Team edited this page May 3, 2026 · 7 revisions

NCICT API 4.20260502

Endpoint:

POST https://ncict-xxxxx.xxxxx.xxx/param
Content-Type: application/json

The domain name and cloud server will be configured once the commercial licensing agreement is executed.

For local testing:

POST http://localhost:8080/param
Content-Type: application/json

JSON Input

The API accepts one JSON object per request. GUI Batch uses CSV format, but the calculation parameters are the same as the API JSON parameters. In GUI Batch CSV files edited with Excel, custom_ma values may be entered across multiple cells starting at the custom_ma column.

Recommended parameter order:

dose_target, age, sex, height, weight, wed, start, end, kvp, tcm_strength, head_body, ctdivol, custom_ma
parameter required definition
dose_target yes Dose target. Use patient, fetus, or mother.
age yes For patient, enter numeric age in years. For fetus or mother, enter gestational age as week text: 8wk, 10wk, 15wk, 20wk, 25wk, 30wk, 35wk, or 38wk.
sex required for patient Patient sex. Use f or m. Ignored for fetus and mother.
height optional Patient height in cm. Used for closest phantom matching when available.
weight optional Patient weight in kg. Used for closest phantom matching when available.
wed optional Water equivalent diameter in cm. Used for closest phantom matching when available.
start yes Scan start location from the top of the head in cm, or a landmark ID from 1001 to 1010.
end yes Scan end location from the top of the head in cm, or a landmark ID from 1001 to 1010.
kvp yes Tube potential in kVp.
tcm_strength yes Tube current modulation strength from 0 to 1. Use -1 when providing custom_ma.
head_body yes CTDI phantom selection. Use 1 for 16-cm CTDI phantom and 2 for 32-cm CTDI phantom.
ctdivol yes Volumetric CT dose index in mGy.
custom_ma required when tcm_strength = -1 Array of slice-specific mA values. Each value must be greater than 0.

Phantom Matching

For patient, the API automatically selects a phantom group from age and sex:

  • age < 20 and sex = f: pediatric female
  • age < 20 and sex = m: pediatric male
  • age >= 20 and sex = f: adult female
  • age >= 20 and sex = m: adult male

When height, weight, or wed is provided, the API selects the closest available size-dependent phantom. If these values are omitted, the API uses age-based matching.

For fetus and mother, use gestational age text in the age field. Supported values are:

8wk, 10wk, 15wk, 20wk, 25wk, 30wk, 35wk, 38wk

Landmark IDs

start and end can be entered either as scan locations in cm or as anatomical landmark IDs. If one value is a landmark ID, the other must also be a landmark ID.

protocol scan start landmark ID scan end landmark ID
head 1001 1003
neck 1002 1005
chest 1004 1007
abdomen 1006 1008
pelvis 1008 1009
AP 1006 1009
CAP 1004 1009
whole body 1001 1010

After landmark conversion, the scan range must satisfy:

0 <= start < end <= 190

Example 1: Patient Dose

{
  "dose_target": "patient",
  "age": 10,
  "sex": "f",
  "height": 150,
  "weight": 50,
  "wed": 20,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 1,
  "ctdivol": 20
}

Example 2: Patient Dose With WED and Custom mA

When tcm_strength is -1, custom_ma is required.

{
  "dose_target": "patient",
  "age": 10,
  "sex": "f",
  "wed": 25,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": -1,
  "head_body": 1,
  "ctdivol": 20,
  "custom_ma": [110, 115, 120, 130, 128, 121, 118]
}

Example 3: Fetus Dose

{
  "dose_target": "fetus",
  "age": "38wk",
  "start": 1004,
  "end": 1009,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Example 4: Pregnant Mother Dose

{
  "dose_target": "mother",
  "age": "30wk",
  "start": 1004,
  "end": 1009,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Validation Example

The following request returns 400 because all custom_ma values must be greater than 0.

{
  "dose_target": "patient",
  "age": 10,
  "sex": "f",
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": -1,
  "head_body": 1,
  "ctdivol": 20,
  "custom_ma": [110, 0, 120]
}

JSON Output

Successful responses return HTTP 200 and a JSON object containing matched phantom information and organ doses.

metadata key definition
dose_target Requested dose target.
age Patient age in years, or gestational age such as 38wk.
sex Patient sex for patient dose target.
phantom_group Matched phantom group.
wed_cm Input WED in cm, or -1 when WED was not provided.
matched_height_cm Matched phantom height in cm.
matched_weight_kg Matched phantom weight in kg for patient.
matched_fetal_age_weeks Matched gestational age in weeks for fetus or mother.

Dose values are returned as strings formatted to two decimal places.

output key definition
brain Brain dose in mGy
pituitary gland Pituitary gland dose in mGy
lens Lens dose in mGy
eye balls Eye balls dose in mGy
salivary glands Salivary glands dose in mGy
oral cavity Oral cavity dose in mGy
spinal cord Spinal cord dose in mGy
thyroid Thyroid dose in mGy
esophagus Esophagus dose in mGy
trachea Trachea dose in mGy
thymus Thymus dose in mGy
lungs Lungs dose in mGy
breast Breast dose in mGy
heart wall Heart wall dose in mGy
heart la Heart left atrium dose in mGy
heart ra Heart right atrium dose in mGy
heart lv Heart left ventricle dose in mGy
heart rv Heart right ventricle dose in mGy
heart lvm Heart left ventricular myocardium dose in mGy
heart lmca Heart left main coronary artery dose in mGy
heart lada Heart left anterior descending artery dose in mGy
heart lca Heart left circumflex artery dose in mGy
heart rca Heart right coronary artery dose in mGy
heart av Heart aortic valve dose in mGy
heart mv Heart mitral valve dose in mGy
heart pv Heart pulmonary valve dose in mGy
heart tv Heart tricuspid valve dose in mGy
stomach wall Stomach wall dose in mGy
liver Liver dose in mGy
gall bladder Gall bladder dose in mGy
adrenals Adrenals dose in mGy
spleen Spleen dose in mGy
pancreas Pancreas dose in mGy
kidney Kidney dose in mGy
small intestine Small intestine dose in mGy
colon Colon dose in mGy
rectosigmoid Rectosigmoid dose in mGy
urinary bladder Urinary bladder dose in mGy
prostate Prostate dose in mGy
uterus Uterus dose in mGy
testes Testes dose in mGy
ovaries Ovaries dose in mGy
skin Skin dose in mGy
muscle Muscle dose in mGy
blood vessel Blood vessel dose in mGy
active marrow Active marrow dose in mGy
shallow marrow Shallow marrow dose in mGy
effective dose msv Effective dose in mSv

Error Responses

Invalid requests return HTTP 400 with an error message. Common validation errors include:

  • missing required input
  • unsupported dose_target
  • missing or invalid sex for patient
  • invalid pregnant phantom age format
  • invalid kvp, tcm_strength, head_body, or ctdivol
  • mixed scan range format, such as one landmark ID and one cm location
  • invalid scan range after landmark conversion
  • missing or invalid custom_ma when tcm_strength = -1

Server-side calculation or installation problems return HTTP 500 with an error message.

Clone this wiki locally