Loading documentation

Access required

Your account doesn't have access to the documentation. Contact your administrator.

Sign out
Skip to main content

Phenotype Classify

Status: stable Category: composite Added: 2026-04-20 Last reviewed: 2026-06-03

Summary​

A pattern-first fast path for callers that want the phenotype classification and its recommendations without the full CDRI composite envelope. Body shape mirrors /cdri/compute; the response is phenotype, red_flags, confidence, and recommendations only — no cdri_score, magnitudes, or findings.

Use this when you already have your own scoring, or when a consumer UI only renders the pattern label and action list.

⚠ Not a clinical diagnosis​

The phenotype is a statistical summary, not a diagnosis. See composite-cdri-compute.md.

Endpoint​

FieldValue
MethodPOST
Path/api/phenotype/classify
Full URLhttps://engine.tripod-health.com/api/phenotype/classify
AuthenticationAPI key (required)
Request bodyapplication/json
Rate-limitedYes

There is no ?depth= query parameter on this endpoint.

Request​

Same headers and body shape as /cdri/compute (any subset of the 14 instruments plus optional demographics). This endpoint does not take situation/onset.

Query parameters​

ParamDefaultValuesDescription
recommendrichrich | simple | rules | offControls the recommendations layer. See Recommendations modes.
audience(unset)employee | employer | providerSteers the audience-framed narrative text. When unset, narrative output stays null. See ?audience=.

Response​

Success — 200 OK​

Live capture under ?recommend=rules with the body in Examples (PHQ-9 + Örebro, a psychosocially-loaded subject). Real engine output.

{
  "phenotype": {
    "backend": "deterministic",
    "model_version": "2026-06-02-first-pass",
    "phenotype": "psychosocial_dominant",
    "distribution": {
      "pain_dominant": 0.125,
      "psychosocial_dominant": 0.1825,
      "fear_avoidance_dominant": 0.125,
      "rtw_barrier": 0.125,
      "multi_domain_catastrophic": 0.1625,
      "iatrogenic_escalation": 0.125,
      "established_chronicity": 0.155
    },
    "model_certainty": 0.1825,
    "overall_magnitude": 0.731,
    "trajectory": null,
    "similar_cases": null,
    "anomalies": null
  },
  "red_flags": [
    {
      "code": "complex_case_review",
      "severity": "urgent",
      "rule_id": "rec.escalation.multi_domain_catastrophic_top2",
      "rule_version": "1.0.0",
      "detail": "Phenotype 'multi_domain_catastrophic' appears in the top-two of the classifier's distribution.",
      "triggers": {
        "phenotype.top_name": "psychosocial_dominant",
        "phenotype.second_name": "multi_domain_catastrophic"
      }
    },
    {
      "code": "suicide_risk_assessment",
      "severity": "urgent",
      "rule_id": "rec.escalation.phq9_item9_suicidality",
      "rule_version": "1.0.0",
      "detail": "PHQ-9 item 9 response is at or above the positive threshold. Widely-used screening frameworks treat any non-zero item-9 response as a trigger for follow-up risk assessment regardless of total PHQ-9 score.",
      "triggers": { "depression_screen.item_9": 1 }
    }
  ],
  "confidence": {
    "overall": 0.5547,
    "tier": "medium",
    "breakdown": {
      "input_completeness": 0.5,
      "imputation_variance": 1,
      "model_certainty": 0.1825
    }
  },
  "recommendations": {
    "engine_version": "1.0.0",
    "ruleset_version": "1.0.0",
    "disclaimer": "The Trinity Engine is a decision-support tool. Output is not medical advice, not a diagnosis, not a prescription, and not a benefits determination. The calling organization is responsible for clinical governance and for the interpretation and use of these suggestions.",
    "ai_summary": null,
    "items": [ "... see /cdri/compute for the recommendation item shape ..." ],
    "suppressed": [
      {
        "rule_id": "rec.clinical_action.psychosocial_integrated_behavioural",
        "reason": "threshold_not_met",
        "details": "Phenotype certainty is below the rule's threshold."
      }
    ],
    "cardinality_cap": null
  },
  "depth": "full",
  "catalog_version": "0.13.0",
  "request_id": "docs-phenotype",
  "timestamp": "2026-06-03T04:21:43.776361+00:00"
}

No cdri_score, magnitudes, or findings in the response — this endpoint intentionally omits the scoring envelope. The phenotype block, red_flags, confidence, and recommendations are identical in shape to their counterparts on /cdri/compute:

Degraded phenotype — 200 OK with backend: "none"​

When the classifier cannot produce a phenotype, the shape is identical but every inner phenotype field is null:

{
  "phenotype": {
    "backend": "none",
    "model_version": null,
    "phenotype": null,
    "distribution": null,
    "model_certainty": null,
    "overall_magnitude": null,
    "trajectory": null,
    "similar_cases": null,
    "anomalies": null
  },
  "red_flags": [],
  "confidence": {
    "overall": 1,
    "tier": "high",
    "breakdown": { "input_completeness": 1, "imputation_variance": 1, "model_certainty": null }
  },
  "recommendations": { "engine_version": "1.0.0", "ruleset_version": "1.0.0", "disclaimer": "...", "ai_summary": null, "items": [], "suppressed": [], "cardinality_cap": null },
  "depth": "full",
  "catalog_version": "0.13.0",
  "request_id": "docs-phenotype-degraded",
  "timestamp": "2026-06-03T00:00:00.000000+00:00"
}

confidence.breakdown.model_certainty is null in this case; the rest of the response structure is unchanged and the status stays 200.

Status codes​

Same as /cdri/compute.

Examples​

The snippets assume the call() helper from quickstart.md.

curl​

curl -sS -X POST "https://engine.tripod-health.com/api/phenotype/classify?recommend=rules" \
  -H "apikey: $ENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instruments": {
      "depression_screen": { "responses": { "item_1": 3, "item_2": 3, "item_3": 2, "item_4": 3, "item_5": 2, "item_6": 3, "item_7": 2, "item_8": 1, "item_9": 1 } },
      "orebro": { "responses": { "item_1": 4, "item_2": 5, "item_3": 4, "item_4": 6, "item_5": 6, "item_6": 4, "item_7": 5, "item_8": 6, "item_9": 6, "item_10": 4, "item_11": 6, "item_12": 6, "item_13": 4, "item_14": 5, "item_15": 4, "item_16": 6, "item_17": 6, "item_18": 4, "item_19": 4, "item_20": 5, "item_21": 4 } }
    },
    "demographics": { "age_bracket": "35-44", "sex": "female", "occupation_class": "office", "region": "CA" }
  }'

Python (requests)​

# Uses the call() helper from quickstart.md.
result = call("POST", "/api/phenotype/classify?recommend=rules", body)
ph = result["phenotype"]
print(f"phenotype: {ph['phenotype']} (certainty {ph['model_certainty']})"
      if ph["phenotype"] else "phenotype: unavailable")
for flag in result["red_flags"]:
    print(f"  [RED:{flag['severity']}] {flag['code']}")

Node.js (native fetch)​

// Uses the call() helper from quickstart.md.
const result = await call("POST", "/api/phenotype/classify?recommend=rules", body);
const ph = result.phenotype;
console.log(ph?.phenotype
  ? `phenotype: ${ph.phenotype} (certainty ${ph.model_certainty})`
  : "phenotype: unavailable");

TypeScript​

// The CdriResponse type from composite-cdri-compute.md is a superset of
// this endpoint's response — reuse it minus the scoring-envelope fields.
type PhenotypeResponse = Omit<
  CdriResponse,
  "composite_id" | "cdri_score" | "magnitudes" | "overall_magnitude" | "matrix_version" | "findings" | "acuity"
>;

const result = await call<PhenotypeResponse>(
  "POST", "/api/phenotype/classify?recommend=rules", body,
);

Intended use​

  • Consumers that already have their own scoring pipeline and only need the pattern label + action list.
  • Lean UIs that render phenotype + recommendations without the scoring envelope.
  • Mobile / low-bandwidth callers where payload size matters.

Mistaken use​

  • Do not use this for a severity readout — it carries no magnitudes or cdri_score. Use /magnitude/compute or /cdri/compute.
  • Do not treat phenotype.phenotype as a diagnosis — display it alongside model_certainty.
  • Do not cache by request-body hash — the phenotype block may be model-generated and vary across identical calls.

Change history​

DateChange
2026-04-20Initial publication.
2026-06-03Updated to the deterministic phenotype backend and the seven-phenotype distribution; added top-level red_flags; removed the tpa audience and the legacy sub_scores reference.