NCIRF API Manual

REST requests, Geant4 calculation parameters, output, and integration documentation for the NCIRF API.

NCIRF API

Current documented release: 4.20260510

NCIRFAPI provides REST-style access to the NCIRF4 batch calculation workflow. A client sends one JSON object to /param; the server prepares the matching NCIRF4 phantom, runs GEANT4, parses the tally output, and returns organ dose and uncertainty values as JSON.

Cloud endpoint:

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

Health Check

GET http://localhost:8080/health

A healthy local debug server returns:

{"ok": true, "service": "ncirf4api"}

JSON Input

The API uses the same parameter names as the NCIRF4 unified batch input. Field names are case-sensitive, but common lower-case aliases are also accepted.

Supported aliases include id, phantom_library, age, sex, height_cm, weight_kg, kvp, hvl, sid, field_width_cm, field_height_cm, dap_gy_cm2, ppa, psa, iso_x, iso_y, iso_z, table_thickness_cm, history, and threads.

Phantom Library Behavior

Example: Size-Dependent Phantom

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

{
  "ID": "10009",
  "PhtLib": 4,
  "Age": 30,
  "Sex": "f",
  "HT": 150,
  "WT": 40,
  "kVp": 28,
  "HVL": 0.460,
  "SID": 80,
  "FW": 10,
  "FH": 10,
  "DAP": 100,
  "PPA": 180,
  "PSA": 0,
  "ISOX": 16.5,
  "ISOY": 13.7,
  "ISOZ": 75.1,
  "Tbl": 1,
  "Hist": 5000000,
  "Thread": 6
}

Example: Pregnant Phantom

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

{
  "ID": "10006",
  "PhtLib": 5,
  "Age": "15wk",
  "kVp": 28,
  "HVL": 0.460,
  "SID": 80,
  "FW": 10,
  "FH": 10,
  "DAP": 100,
  "PPA": 180,
  "PSA": 0,
  "ISOX": 24.5,
  "ISOY": 15.1,
  "ISOZ": 82.3,
  "Tbl": 1,
  "Hist": 5000000,
  "Thread": 6
}

Additional ready-to-run examples are provided in ncirf4api_test.http.

JSON Output

Successful responses have this structure:

{
  "ok": true,
  "patient_id": "10009",
  "phantom_library": 4,
  "age": "30",
  "sex": "f",
  "lattice_file": "3150040.lat",
  "drf": "35F",
  "matched": {
    "geant4_phantom_group": 3,
    "phantom_age_or_height": 150,
    "phantom_sex_or_weight": 40,
    "matched_height_cm": 150,
    "matched_weight_kg": 40
  },
  "dose": {
    "brain": 0.0,
    "effective_dose_mSv": 0.0
  },
  "error_percent": {
    "brain": 0.0,
    "effective_dose_mSv": 0.0
  }
}

dose contains organ doses in mGy, except effective_dose_mSv, which is in mSv. error_percent contains the corresponding relative uncertainty in percent.

Output Keys

Error Output

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

{
  "ok": false,
  "status": 400,
  "error": "missing required input: PhtLib"
}

Monte Carlo History and Threads

More histories generally increase calculation time and reduce statistical uncertainty.

More threads can reduce runtime. The maximum useful thread count depends on the server hardware and deployment configuration.