RadShip Classification API

Getting access

API access is currently offered as a managed integration. Contact us to get an API key — we'll help you map your data to the request schema and validate your first classifications.

Authenticate every request with your key in the x-api-key header. Keys can be revoked and re-issued at any time; treat them as secrets.

POST /api/classify

Classifies one package. Example:

POST /api/classify HTTP/1.1
Host: radship.com
Content-Type: application/json
x-api-key: rsk_live_...

{
  "radionuclides": [
    {
      "radionuclideId": "Cs-137",
      "activity": 5,
      "unit": "Ci",
      "physicalState": "Solid",
      "materialForm": "Special Form",
      "massInGrams": 100
    }
  ],
  "packageCharacterization": "none"
}

Request fields

Response

{
  "success": true,
  "data": {
    "unNumber": "UN3332",
    "properShippingName": "Radioactive material, Type A package, special form",
    "shipmentType": "Type A — Special Form, Non-fissile",
    "isRegulatedClass7": true,
    "hazardClass": 7,
    "totalActivityTBq": 0.185,
    "totalSumOfFractions": 0.0925,
    "containsFissile": false,
    "exemptCheck": { ... },
    "tierAnalysis": { ... },
    "effectiveAValues": null,
    "labelingNuclides": [ "Cs-137" ],
    "reasons": [ ... ],
    "cfrReferences": [ ... ],
    "airTransport": null,
    "transport": null,
    "decay": null
  },
  "meta": {
    "engineVersion": "...",
    "dataVersion": "...",
    "timestamp": "...",
    "inputHash": "..."
  }
}

Every response carries meta.engineVersion, meta.dataVersion, and an inputHash so classifications are reproducible and audit-traceable.

Quickstart (Python)

A complete working example: classify a batch, then scan ship dates to find the shipping window. Requires pip install requests and your API key in the RADSHIP_API_KEY environment variable (keep keys out of code and notebooks).

import os
from datetime import date, timedelta
import requests

API_URL = "https://radship.com/api/classify"
API_KEY = os.environ["RADSHIP_API_KEY"]   # never hardcode the key

BATCH = [
    {
        "radionuclideId": "Lu-177",
        "activity": 3,
        "unit": "Ci",
        "physicalState": "Liquid",
        "materialForm": "Normal Form",
        "massInGrams": 20,
    },
]

ASSAY_DATE = date(2026, 7, 22)

def classify(ship_date=None):
    body = {"radionuclides": BATCH, "packageCharacterization": "none"}
    if ship_date is not None:
        body["decay"] = {
            "assayDate": ASSAY_DATE.isoformat(),
            "shipDate": ship_date.isoformat(),
        }
    r = requests.post(API_URL, json=body,
                      headers={"x-api-key": API_KEY}, timeout=30)
    payload = r.json()
    if not payload.get("success"):
        raise RuntimeError(payload["error"])
    return payload["data"]

# 1. Classify as assayed
result = classify()
print(f"As assayed: {result['unNumber']} ({result['shipmentType']}) "
      f"SoF={result['totalSumOfFractions']:.3f}")

# 2. Shipping-window scan
for days in range(0, 29, 7):
    ship = ASSAY_DATE + timedelta(days=days)
    r = classify(ship)
    print(f"  +{days:2d}d: {r['unNumber'] or 'not regulated':>8}  "
          f"{r['totalActivityCi']:.3f} Ci  SoF={r['totalSumOfFractions']:.3f}")

Example output — watch the batch decay toward exempt over four weeks:

As assayed: UN2915 (Type A — Normal Form, Non-fissile) SoF=0.159
  + 0d:   UN2915  3.000 Ci  SoF=0.159
  + 7d:   UN2915  1.445 Ci  SoF=0.076
  +14d:   UN2915  0.696 Ci  SoF=0.037
  +21d:   UN2915  0.335 Ci  SoF=0.018
  +28d:   UN2915  0.162 Ci  SoF=0.009

GET /api/radionuclides

Returns the supported radionuclide IDs — entries verified against 49 CFR 173.435, plus DOT Table 7/8 default entries — for autocomplete and pre-validation.

Errors

Important notes

• Regulatory values come from RadShip's verified database (49 CFR 173.435 et seq.), not third-party sources. Response metadata pins the engine and data versions used.
• API output is decision support for trained shippers. It does not replace hazmat shipper training or certification requirements under 49 CFR 172 Subpart H, and the shipper of record remains responsible for each shipment's compliance.
• Default rate limit is 60 requests/minute per key; higher limits available on request.