NCICT API Manual

REST request structure, authentication, parameters, examples, and response format for the NCICT application programming interface.

NCICT API

Current documented release: 4.20260502

NCICTAPI provides REST-style access to the NCICT4 CT organ dose calculation workflow. A client sends one JSON object to /param; the server matches the requested phantom, applies the scanner and scan-range parameters, calculates organ doses, and returns JSON output.

Cloud endpoint:

POST https://ncict-api.ncidosetools.com/param
Content-Type: application/json
X-API-Key: <assigned vendor API key>

A vendor-specific API key is provided after the commercial licensing agreement is executed.

Local Xojo debug endpoint:

POST http://localhost:8080/param
Content-Type: application/json
X-API-Key: <assigned vendor API key>

Authentication

POST /param requires the API key assigned to the licensed vendor. Send the key in the X-API-Key request header. Do not include it in the URL or JSON body. Missing, disabled, or invalid keys return HTTP 401.

The API key is a bearer credential. Store it in an environment variable or a server-side secret manager, and send requests only over HTTPS. Server-to-server integration is recommended. Do not commit the key to source control, write it to application logs, embed it in browser JavaScript, or distribute it inside a desktop or mobile application. Use a vendor-controlled backend as a proxy when the end-user application cannot protect a secret.

The same assigned company key is accepted by NCICTAPI, NCINMAPI, and NCIRFAPI. If a key may have been exposed, stop using it and contact the NCI Dose Tools administrator to have it disabled or rotated. Successful requests are logged under the registered company name; the raw key is not written to the API access log.

Command-Line Example

Save one of the JSON examples below as request.json. For an interactive test, read the key without placing it in shell history:

read -rsp "NCI Dose API key: " NCIDOSE_API_KEY && printf '\n'
export NCIDOSE_API_KEY

curl https://ncict-api.ncidosetools.com/param \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: ${NCIDOSE_API_KEY}" \
  --data @request.json

unset NCIDOSE_API_KEY

Python Example

Provide NCIDOSE_API_KEY to the Python process through the deployment environment or secret manager. Do not put the raw key in the source file.

import json
import os

import requests

with open("request.json", encoding="utf-8") as request_file:
    payload = json.load(request_file)

response = requests.post(
    "https://ncict-api.ncidosetools.com/param",
    headers={"X-API-Key": os.environ["NCIDOSE_API_KEY"]},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(response.json())

JSON Input

The API accepts one JSON object per request. GUI Batch uses CSV format, but it uses the same calculation parameters as the API JSON input. A dose_target field is not required; NCICT infers the dose target from age and whether height is supplied.

Recommended key order for readability:

age, sex, height, weight, wed, start, end, kvp, tcm_strength, head_body, ctdivol, custom_ma

Phantom Selection Rules

NCICT automatically determines the dose target and phantom group:

Age < 20 is treated as pediatric for patient dose. Age >= 20 is treated as adult.

WED-based Phantom Matching

When age, sex, and wed are provided for patient dose, NCICT first determines the patient 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

For WED-based matching, NCICT uses the scan range to determine the anatomical region. WED-based matching is applied when start and end match one of the supported landmark ranges:

For patients 5 years of age or older, NCICT estimates a target body weight from WED using region-, age-, and sex-specific regression equations. A fixed target height is assigned from the age/sex group. For patients younger than 5 years, NCICT uses fixed reference size targets for the newborn and 1-year phantom groups:

For the fixed pediatric groups, the target weights are 4 kg for age < 1 year and 10 kg for 1 <= age < 5 years. The estimated or fixed target weight is limited to the available body size range, and NCICT selects the closest available size-dependent phantom within the same phantom group. The closest phantom is selected by minimizing:

|target height - phantom height| + |target weight - phantom weight|

If the scan range does not match one of the supported WED landmark ranges, NCICT falls back to age/sex-based matching using internally estimated reference height and weight.

Landmark IDs

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

Common protocol ranges can be entered using the following landmark ID pairs:

After landmark conversion, the scan range must satisfy:

0 <= start < end <= 190

Example 1: Age and Sex

{
  "age": 10,
  "sex": "f",
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 1,
  "ctdivol": 20
}

Example 2: Age, Sex, and WED

{
  "age": 10,
  "sex": "f",
  "wed": 25,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 1,
  "ctdivol": 20
}

Example 3: Age, Sex, Height, and Weight

{
  "age": 20,
  "sex": "m",
  "height": 175,
  "weight": 80,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Example 4: Fetus Dose

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

Example 5: Mother Dose

Supplying height with a week-based age selects mother dose. The pregnant phantom library uses a matched height of 164 cm.

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

Custom mA Example

When tcm_strength is -1, custom_ma is required.

{
  "age": 10,
  "sex": "f",
  "wed": 25,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": -1,
  "head_body": 1,
  "ctdivol": 20,
  "custom_ma": [100, 200, 300, 400, 500, 600, 700]
}

JSON Output

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

Dose values are returned as strings formatted to two decimal places. Output dose keys include organ doses in mGy and effective dose msv in mSv.

Error Responses

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

• missing required input
• missing or invalid sex for year-based age
• 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.