NCINM API Manual

REST documentation for radionuclide and radiopharmaceutical dose-calculation workflows using the NCINM API.

NCINM API

Current documented release: September 30, 2026 (4.20260930) Current release type: Scientific Update Latest scientific update: September 30, 2026

NCINMAPI provides REST-style access to the NCINM4 radiopharmaceutical dose calculation workflow. A client sends one JSON object to /param; the server matches the requested phantom and radiopharmaceutical, calculates organ doses, and returns JSON output.

The API supports NCI, ICRP voxel, and ICRP mesh radiopharmaceutical workflows. Fetus calculations are available in the NCINM4 GUI through the Radionuclide tab with user-entered maternal source-region data; they are not included in the radiopharmaceutical API because pregnancy-specific radiopharmaceutical biokinetic models are not currently defined.

The hosted NCINM4 API was deployed on October 1, 2026. The September 30, 2026 release adds the ICRP mesh phantom library and updates the API to the same 133-model radiopharmaceutical library used by the GUI. Predefined newborn biokinetic data are unavailable, so newborn radiopharmaceutical requests return an explicit error. See the NCINM release history for a concise summary.

Cloud endpoint:

POST https://ncinm-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://ncinm-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://ncinm-api.ncidosetools.com/param",
    headers={"X-API-Key": os.environ["NCIDOSE_API_KEY"]},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(response.json())

Ready-to-run local examples are provided in:

_ncinm4api_test.http

JSON Input

The API accepts one JSON object per request.

JSON numeric literals use dot decimals as required by JSON. Numeric parameters may also be sent as strings using either dot or comma decimal notation. API numeric output uses dot decimals regardless of server or client locale.

Supported aliases:

Phantom Matching

The API maps patient age to the nearest available NCINM4 age group:

The response reports the matched phantom age. In API input and output, sex = 1 is female and sex = 2 is male.

Radiopharmaceutical Matching

The API can accept either a library ID or clinical-style text. When a radiopharmaceutical name is received in JSON input, NCINMAPI automatically matches the submitted text to the closest library entry using fuzzy matching.

Matching is performed in this order:

1. Numeric ID match, when radiopharmaceutical contains only an ID.
2. Exact text match against the available radiopharmaceutical names.
3. Fuzzy text match against the available radiopharmaceutical names.

The fuzzy matcher normalizes radionuclide notation before matching. Examples:

Fuzzy matching stays within the same radionuclide when a radionuclide is provided. If no radiopharmaceutical with that radionuclide is available, the API returns an error instead of matching to a different radionuclide.

The response includes both the original submitted text and the matched library entry so vendors can audit automatic matches.

Example 1: ICRP Mesh Calculation

{
  "phantom_library": 4,
  "sex": "female",
  "age": 58,
  "radiopharmaceutical": "F-18 FDG",
  "administered_activity_mbq": 200
}

Example 2: Alternate Radionuclide Notation

{
  "PhtLib": 1,
  "Sex": "m",
  "Age": 42,
  "Radiopharmaceutical": "Tc99m MDP bone scan",
  "MBq": 740
}

Example 3: Library ID

{
  "phantom_library": 2,
  "sex": 1,
  "age": 8,
  "radiopharmaceutical": "20",
  "administered_activity_mbq": 200
}

JSON Output

Successful responses return HTTP 200 and a JSON object.

The API currently returns central dose estimates only. Monte Carlo uncertainty percentages for ICRP mesh calculations are available in the NCINM4 GUI but are not included in the API response.

Example response structure:

{
  "ok": true,
  "input": {
    "phantom_library": 4,
    "sex": 1,
    "age": 58.0,
    "matched_phantom_age": "Adult",
    "radiopharmaceutical_original": "F-18 FDG",
    "radiopharmaceutical": "F-18-fluoro-2-deoxy-D-glucose (FDG) (ICRP 128)",
    "administered_activity_mbq": 200.0
  },
  "phantom_age_match": {
    "original_age_year": 58.0,
    "matched": "Adult",
    "method": "nearest_available_age_phantom"
  },
  "radiopharmaceutical_match": {
    "original": "F-18 FDG",
    "matched": "F-18-fluoro-2-deoxy-D-glucose (FDG) (ICRP 128)",
    "method": "fuzzy",
    "score": 1.0
  },
  "dose_mGy": {
    "adipose": 0.0,
    "brain": 0.0,
    "thyroid": 0.0,
    "effective_dose_mSv": 0.0
  }
}

Dose values in the example are illustrative placeholders. Actual values depend on the matched phantom, radiopharmaceutical, and administered activity.

Output Dose Keys

dose_mGy contains these dose keys:

adipose, adrenal, adrenal_l, adrenal_r, bronchi, brain,
breast_adipose, breast_glandular, colon_w, colon_w_l, colon_w_r,
et, gall_bladder_w, gonads, heart_w, kidney, kidney_r, kidney_l,
kidney_cortex_l, kidney_cortex_r, kidney_medulla_l, kidney_medulla_r,
kidney_pelvis_l, kidney_pelvis_r, lenses_of_eye, liver, lung,
lung_l, lung_r, lymph_nodes_et, lymph_nodes_but_et_th,
lymph_nodes_thoracic, muscle, nasal_passage_ant, nasal_passage_post,
oesophagus, oral_mucosa, pancreas, pituitary_gland,
prostate_or_uterus, salivary_glands, sigmoid_rectum_w, skin,
small_intestine_w, spinal_cord, spleen, stomach_w, thymus, thyroid,
tongue, tonsils, ureters, urinary_bladder_w, active_marrow,
shallow_marrow, effective_dose_mSv

All organ dose keys are in mGy except effective_dose_mSv, which is in mSv. For phantom_library = 4, urinary_bladder_w contains the ICRP mesh urinary-bladder basal-cell target result; the key is retained for response compatibility.

The API uses the same remainder calculation as the GUI, including normalized tissue-volume weights and the oesophageal-wall source for mesh remainder activity. The bronchial remainder approximation and its unquantified dose impact also apply to API results; see Remainder in the GUI manual.

Error Output

Invalid input returns ok: false, HTTP status 400, and an explanatory error string.

{
  "ok": false,
  "status": 400,
  "error": "Invalid radiopharmaceutical: No radiopharmaceutical with the same radionuclide is available in this library."
}

Common validation errors include:

• invalid JSON input
• missing or invalid phantom_library
• missing or invalid sex
• negative age
• newborn age matched to 0 years, for which predefined biokinetic data are unavailable
• missing or unmatched radiopharmaceutical
• administered_activity_mbq less than or equal to zero

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