USG Screening API Reference

The USG (Urine Specific Gravity) classifier predicts whether a feline patient's urine is likely impaired (USG < 1.035) from five routine bloodwork values. Intended use is to flag patients whose chemistry suggests reduced urine concentrating ability so a follow-up urinalysis can be ordered — the test that actually reveals early kidney dysfunction.

• Base URL: https://api.radanalyzer.com
• Path prefix: /usg/v1
• Latency: ~200 ms warm, ~20 s cold
• Transport: HTTPS only. Plaintext HTTP is redirected.
• Content-Type: application/json on every POST.

See the product page for clinical background, the data hub for current performance metrics, and the standalone web tool to try the model interactively before integrating.

Every response includes permissive CORS headers (Access-Control-Allow-Origin: *, methods GET, POST, OPTIONS, headers Content-Type, x-api-key). Production callers should still proxy through their own backend — see operational notes.

Send your API key in the x-api-key header. Required on POST /usg/v1/predict; not required on /health or /version. The same key authorizes /vhs/v3/* and /usg/v1/* — there is no per-algorithm key. Bearer tokens, OAuth, query-string keys, and mTLS are not supported.

x-api-key: YOUR_API_KEY

Failure modes

Treat 401 and 403 the same way: prompt the operator for a new key. Keys are not recoverable through the API — request a rotation.

Liveness probe. Unauthenticated. Used by clients to confirm reachability.

Response — 200 OK

{
  "status": "ok",
  "service": "usg-v1",
  "model_version": "1.5a",
  "service_version": "1.0.2"
}

Returns the active model version, feature list, and decision thresholds. Useful for client-side schema validation and reproducibility logging. Record model_version alongside every stored prediction.

Response — 200 OK

{
  "service": "usg-v1",
  "service_version": "1.0.2",
  "model_version": "1.5a",
  "features": ["BUN", "CREATININE", "HGB", "ABSOLUTE LYMPHOCYTES", "age_months"],
  "threshold_impaired": 0.3496,
  "sg_cutoff": 1.035
}

Run a USG impairment prediction.

Request headers

POST /usg/v1/predict HTTP/1.1
Host: api.radanalyzer.com
Content-Type: application/json
x-api-key: YOUR_API_KEY

Request body

{
  "BUN": 22,
  "CREATININE": 1.3,
  "HGB": 14.2,
  "ABSOLUTE LYMPHOCYTES": 2400,
  "age_months": 96,

  "clinic_code": "rc-vet",
  "uuid": "pat-abc-123"
}

A Firebase callable-style envelope is also accepted for compatibility — if body.data is a JSON object, it is unwrapped and used as the payload:

{ "data": { "BUN": 22, "CREATININE": 1.3, "HGB": 14.2, "ABSOLUTE LYMPHOCYTES": 2400, "age_months": 96 } }

Required features

All five must be present and numeric. Missing any → 400 missing_features.

JSON key note. ABSOLUTE LYMPHOCYTES is the literal key — uppercase, with a space. It mirrors the original lab-export column name and the model's internal feature names, and is preserved in v1 for parity with the legacy integration. JavaScript callers must use bracket access: body["ABSOLUTE LYMPHOCYTES"]. A snake_case alias may be added in a future v1 minor release; v2 will rename outright.

Optional fields

Stored on the prediction log; do not affect the model. Silently ignored if absent.

Response — 200 OK

{
  "result": {
    "classification": "adequate",
    "probability_adequate": 0.8421,
    "probability_impaired": 0.1579,
    "risk_tier": "low",
    "risk_label": "Low risk of impairment",
    "threshold_sg": 1.035,
    "model_version": "1.5a",
    "explanation": {
      "base_value": -0.42,
      "features": [
        {"feature": "CREATININE",           "label": "Creatinine",       "value": 1.30,   "shap": -0.31, "direction": "adequate"},
        {"feature": "BUN",                  "label": "BUN",              "value": 22.00,  "shap": -0.18, "direction": "adequate"},
        {"feature": "HGB",                  "label": "Hemoglobin",       "value": 14.20,  "shap":  0.04, "direction": "impaired"},
        {"feature": "ABSOLUTE LYMPHOCYTES", "label": "Abs. Lymphocytes", "value": 2400.0, "shap": -0.02, "direction": "adequate"},
        {"feature": "age_months",           "label": "Age (months)",     "value": 96.0,   "shap":  0.01, "direction": "impaired"}
      ]
    }
  },
  "meta": {
    "service": "usg-v1",
    "model_version": "1.5a",
    "elapsed_ms": 187.2
  }
}

Response field reference

Risk tiers

The boundary 0.3496 is the same threshold_impaired returned by /version — the binary classification flips at that point, while risk_tier provides a finer-grained band suitable for triage UIs.

Auto-correction warnings

Two unit-mismatch corrections are applied automatically before scoring. When either fires, the corrected value is used for the prediction and echoed in result.explanation.features[].value, and a string is appended to result.warnings[]. Out-of-range values that fall outside the plausible band even after correction return 400 out_of_range.

All errors share the umbrella envelope:

{ "error": { "code": "snake_case_code", "message": "Human-readable detail." } }

code values are stable — safe to branch on programmatically. message strings may evolve and must not be parsed.

cURL

KEY=ra_live_xxxxxxxxxxxxxxxxxxxxxxxx

# Reachability
curl https://api.radanalyzer.com/usg/v1/health
curl https://api.radanalyzer.com/usg/v1/version

# Prediction
curl -X POST https://api.radanalyzer.com/usg/v1/predict \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "BUN": 22,
    "CREATININE": 1.3,
    "HGB": 14.2,
    "ABSOLUTE LYMPHOCYTES": 2400,
    "age_months": 96,
    "clinic_code": "rc-vet",
    "uuid": "pat-buddy-001"
  }'

Python (requests)

import os
import requests

BASE_URL = "https://api.radanalyzer.com"
API_KEY  = os.environ["RA_KEY"]   # same key authorizes /vhs/v3 and /usg/v1

resp = requests.post(
    f"{BASE_URL}/usg/v1/predict",
    headers={"x-api-key": API_KEY, "Content-Type": "application/json"},
    json={
        "BUN": 22,
        "CREATININE": 1.3,
        "HGB": 14.2,
        "ABSOLUTE LYMPHOCYTES": 2400,
        "age_months": 96,
        "clinic_code": "rc-vet",
        "uuid": "pat-buddy-001",
    },
    timeout=15,
)
resp.raise_for_status()
data = resp.json()

result = data["result"]
print(f"{result['classification']:>9}  "
      f"p_impaired={result['probability_impaired']:.4f}  "
      f"tier={result['risk_tier']}  "
      f"model={data['meta']['model_version']}")

Node (fetch, ≥18)

const BASE_URL = "https://api.radanalyzer.com";
const API_KEY  = process.env.RA_KEY;

const resp = await fetch(`${BASE_URL}/usg/v1/predict`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({
    BUN: 22,
    CREATININE: 1.3,
    HGB: 14.2,
    "ABSOLUTE LYMPHOCYTES": 2400,
    age_months: 96,
    clinic_code: "rc-vet",
    uuid: "pat-buddy-001",
  }),
});

if (!resp.ok) {
  const { error } = await resp.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { result, meta } = await resp.json();
console.log(`${result.classification} | p=${result.probability_impaired} | ${result.risk_tier} | model=${meta.model_version}`);

• Cold starts. First request after the service has scaled to zero takes ~20 s; subsequent calls in the warm window are ~200 ms. A single ~20 s response should not be interpreted as a regression.
• Browser embedding. Do not embed ra_live_* keys in shipped JavaScript. Proxy through a backend. The CORS allow-list is permissive only because legitimate callers may run from desktop apps and clinic SaaS frontends — it is not an invitation to ship the key client-side.
• Idempotency. All POSTs are idempotent on the wire. Safe to retry on 408 / 500 / 503.
• uuid and recheck dedupe. Sending the same uuid twice within 24 hours short-circuits the billing counter. The prediction itself runs every time — the server does not return a cached result.