GI · LIVE

Truelove and Witts ulcerative colitis severity

Truelove and Witts

Apply the Truelove and Witts 1955 ulcerative colitis severity table and return mild, moderately_severe, or severe from stools_per_day and five caller-assigned flags.

LIVE $0.005 USDC GET /api/calc/truelove_witts

Markdown: /docs/truelove-witts.md · Canonical: https://magentlab.com/docs/truelove-witts

Not a medical device. Not a diagnosis, dose, or listing recommendation.

What it computes

Apply the Truelove and Witts 1955 ulcerative colitis severity table and return mild, moderately_severe, or severe from stools_per_day and five caller-assigned flags.

When to use

When an agent already has the 1955 stool count and blood/systemic flags and needs that paper's mild / moderately severe / severe classification. magent does not examine the patient.

When not to use

Not a medical device.
Not a diagnosis. magent does not diagnose ulcerative colitis or assign a treatment order.
The caller assigns stools_per_day and each blood/systemic flag from the 1955 mild and severe columns. magent does not examine the patient or measure temperature, pulse, haemoglobin, or ESR.
This tool is the 1955 BMJ table only (mild: four or less motions a day, no more than small amounts of macroscopic blood, no fever, no tachycardia, anaemia not severe, ESR not above 30 mm in one hour; severe: six or more motions with macroscopic blood and systemic upset). Moderately severe is intermediate. Not Mayo UC. Not PUCAI. Not later ASUC restatements that use haemoglobin 10.5 g/dL as the anaemia cut.

Formula

severity severe iff stools_per_day >= 6 and macroscopic_blood and systemic_features_met >= 1; mild iff stools_per_day <= 4 and not macroscopic_blood and systemic_features_met == 0; else moderately_severe; systemic_features_met counts fever, tachycardia, anemia, and esr_raised (Truelove and Witts 1955)

Citation

Title: Cortisone in ulcerative colitis; final report on a therapeutic trial
Authors: Truelove SC, Witts LJ
Source: Br Med J. 1955;2(4947):1041-1048
DOI: 10.1136/bmj.2.4947.1041

Worked example

Two stools, no blood, no systemic flags

Given: anemia=falseesr_raised=falsefever=falsemacroscopic_blood=falsestools_per_day=2tachycardia=false

stools_per_day is 2 (1955 mild column: four or less motions a day)
macroscopic_blood is false (no more than small amounts)
fever, tachycardia, anemia, and esr_raised are false (no systemic upset)
severity is mild

Six bloody stools with fever only

Given: anemia=falseesr_raised=falsefever=truemacroscopic_blood=truestools_per_day=6tachycardia=false

stools_per_day is 6 with macroscopic blood (1955 severe diarrhoea column)
fever is true; the other three systemic flags are false (systemic_features_met 1)
severity is severe; one systemic flag is enough

Also searched as

Truelove and Witts
Truelove-Witts criteria
Truelove Witts severity index
ulcerative colitis severity
Truelove and Witts 1955
UC severity classification
Truelove Witts mild moderately severe

Try

Opens the live endpoint. Unpaid browser requests show the paywall; agents should send Accept: application/json.

/api/calc/truelove_witts?stools_per_day=2&macroscopic_blood=false&fever=false&tachycardia=false&anemia=false&esr_raised=false

Full URL: https://api.magentlab.com/api/calc/truelove_witts?stools_per_day=2&macroscopic_blood=false&fever=false&tachycardia=false&anemia=false&esr_raised=false

Call

Expect HTTP 402 until you retry with PAYMENT-SIGNATURE. Incomplete query params return HTTP 400 before any quote or charge.

curl -i -H "Accept: application/json" "https://api.magentlab.com/api/calc/truelove_witts?stools_per_day=2&macroscopic_blood=false&fever=false&tachycardia=false&anemia=false&esr_raised=false"

Parameters

Name	Type	Required	Description
`stools_per_day`	integer	required	Number of stools (motions) per day as assigned by the caller (integer 0-40). The 1955 mild column is four or less; the severe column is six or more. magent does not count stools.
`macroscopic_blood`	boolean	required	Macroscopic blood in stools as in the 1955 severe column (with macroscopic blood). true or false as assigned by the caller. The 1955 mild column allows no more than small amounts; assign false when blood is absent or no more than small amounts. magent does not examine the stool.
`fever`	boolean	required	Fever as assigned by the caller using the 1955 definition: mean evening temperature more than 99.5 F (37.5 C), or a temperature of 100 F (37.8 C) or more on at least two days out of four. true or false. magent does not measure temperature.
`tachycardia`	boolean	required	Tachycardia as assigned by the caller using the 1955 definition: mean pulse rate more than 90 per minute. true or false. magent does not measure pulse.
`anemia`	boolean	required	Anaemia as assigned by the caller using the 1955 definition: haemoglobin 75% or less, allowance made for recent transfusion. true or false. Not the later 10.5 g/dL restatement. magent does not measure haemoglobin.
`esr_raised`	boolean	required	E.S.R. much raised as assigned by the caller using the 1955 definition: more than 30 mm in one hour. true or false. magent does not measure ESR.

Bulk (POST)

POST the same path with a JSON items array. The first item is the GET unit; each additional item is $0.002. Invalid items return HTTP 400 before settlement.

POST /api/calc/truelove_witts Max 25 unit_amount + extra_item_amount * (n - 1) extra $0.002 PREVIEW

1 to 25 items. Each item uses the same keys as the GET query parameters.
POST of 1 item costs the same as GET. Lists longer than 25: chunk into multiple POSTs. Extra items still execute; do not pad dummy rows.
The first invalid item fails the whole request (index in the 400 JSON). You are not charged.
HTTP 200 is {count, path, items}. Each items[i] is the GET 200 body for that row.
Catalog misses (empty matches, found=false) stay paid 200s inside that slot.
x402 resource URL is this path plus n and body_sha256. Browsers that prefer text/html get the same paywall as GET; Pay retries POST with the same items.

Example request (fixture)

{
  "items": [
    {
      "anemia": "false",
      "esr_raised": "false",
      "fever": "false",
      "macroscopic_blood": "false",
      "stools_per_day": "2",
      "tachycardia": "false"
    },
    {
      "anemia": "false",
      "esr_raised": "false",
      "fever": "false",
      "macroscopic_blood": "false",
      "stools_per_day": "2",
      "tachycardia": "false"
    }
  ]
}

Open bulk paywall →

Opens a two-item fixture on the API host. Unpaid browsers get the same MetaMask paywall as GET; Pay retries POST with those items.

Example 200 (fixture)

{
  "count": 2,
  "path": "/api/calc/truelove_witts",
  "items": [
    {
      "severity": "mild",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Truelove SC, Witts LJ",
        "doi": "10.1136/bmj.2.4947.1041",
        "id": "truelove-witts-1955",
        "pmid": "13260656",
        "source": "Br Med J. 1955;2(4947):1041-1048",
        "title": "Cortisone in ulcerative colitis; final report on a therapeutic trial"
      },
      "formula": "truelove_witts",
      "formula_expression": "severity severe iff stools_per_day >= 6 and macroscopic_blood and systemic_features_met >= 1; mild iff stools_per_day <= 4 and not macroscopic_blood and systemic_features_met == 0; else moderately_severe; systemic_features_met counts fever, tachycardia, anemia, and esr_raised (Truelove and Witts 1955)",
      "criteria": [
        {
          "value": 2,
          "factor": "stools_le_4",
          "met": true
        },
        {
          "value": 2,
          "factor": "stools_ge_6",
          "met": false
        },
        {
          "factor": "macroscopic_blood",
          "met": false
        },
        {
          "value": 2,
          "factor": "frequent_bloody_stools",
          "met": false
        },
        {
          "factor": "fever",
          "met": false
        },
        {
          "factor": "tachycardia",
          "met": false
        },
        {
          "factor": "anemia",
          "met": false
        },
        {
          "factor": "esr_raised",
          "met": false
        },
        {
          "value": 0,
          "factor": "no_systemic",
          "met": true
        },
        {
          "value": 0,
          "factor": "systemic_ge_1",
          "met": false
        }
      ],
      "stools_per_day": 2,
      "systemic_features_met": 0
    },
    {
      "severity": "mild",
      "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
      "citation": {
        "authors": "Truelove SC, Witts LJ",
        "doi": "10.1136/bmj.2.4947.1041",
        "id": "truelove-witts-1955",
        "pmid": "13260656",
        "source": "Br Med J. 1955;2(4947):1041-1048",
        "title": "Cortisone in ulcerative colitis; final report on a therapeutic trial"
      },
      "formula": "truelove_witts",
      "formula_expression": "severity severe iff stools_per_day >= 6 and macroscopic_blood and systemic_features_met >= 1; mild iff stools_per_day <= 4 and not macroscopic_blood and systemic_features_met == 0; else moderately_severe; systemic_features_met counts fever, tachycardia, anemia, and esr_raised (Truelove and Witts 1955)",
      "criteria": [
        {
          "value": 2,
          "factor": "stools_le_4",
          "met": true
        },
        {
          "value": 2,
          "factor": "stools_ge_6",
          "met": false
        },
        {
          "factor": "macroscopic_blood",
          "met": false
        },
        {
          "value": 2,
          "factor": "frequent_bloody_stools",
          "met": false
        },
        {
          "factor": "fever",
          "met": false
        },
        {
          "factor": "tachycardia",
          "met": false
        },
        {
          "factor": "anemia",
          "met": false
        },
        {
          "factor": "esr_raised",
          "met": false
        },
        {
          "value": 0,
          "factor": "no_systemic",
          "met": true
        },
        {
          "value": 0,
          "factor": "systemic_ge_1",
          "met": false
        }
      ],
      "stools_per_day": 2,
      "systemic_features_met": 0
    }
  ]
}

Response

Field	Type	Description
`formula`	string	truelove_witts
`formula_expression`	string	Truelove and Witts 1955 mild / moderately severe / severe classification from stools, blood, and four systemic flags
`severity`	string	mild, moderately_severe, or severe (1955 classification). Not Mayo. Not PUCAI. Not a treatment order.
`stools_per_day`	integer	Echo of the caller-assigned stool count (0-40)
`systemic_features_met`	integer	Count of true systemic flags among fever, tachycardia, anemia, and esr_raised (0-4)
`criteria`	array	Per-factor rows with factor and met; stools_le_4, stools_ge_6, frequent_bloody_stools, no_systemic, and systemic_ge_1 include value
`citation`	object	Truelove and Witts 1955 BMJ citation
`disclaimer`	string	Not-a-device notice

Example JSON

Machine form of the same example. Frozen fixture. Not a live lookup.

{
  "severity": "mild",
  "disclaimer": "Not a medical device. Deterministic published-formula or published-code output for autonomous agents. A licensed clinician remains responsible for patient care and billing submissions.",
  "citation": {
    "authors": "Truelove SC, Witts LJ",
    "doi": "10.1136/bmj.2.4947.1041",
    "id": "truelove-witts-1955",
    "pmid": "13260656",
    "source": "Br Med J. 1955;2(4947):1041-1048",
    "title": "Cortisone in ulcerative colitis; final report on a therapeutic trial"
  },
  "formula": "truelove_witts",
  "formula_expression": "severity severe iff stools_per_day >= 6 and macroscopic_blood and systemic_features_met >= 1; mild iff stools_per_day <= 4 and not macroscopic_blood and systemic_features_met == 0; else moderately_severe; systemic_features_met counts fever, tachycardia, anemia, and esr_raised (Truelove and Witts 1955)",
  "criteria": [
    {
      "value": 2,
      "factor": "stools_le_4",
      "met": true
    },
    {
      "value": 2,
      "factor": "stools_ge_6",
      "met": false
    },
    {
      "factor": "macroscopic_blood",
      "met": false
    },
    {
      "value": 2,
      "factor": "frequent_bloody_stools",
      "met": false
    },
    {
      "factor": "fever",
      "met": false
    },
    {
      "factor": "tachycardia",
      "met": false
    },
    {
      "factor": "anemia",
      "met": false
    },
    {
      "factor": "esr_raised",
      "met": false
    },
    {
      "value": 0,
      "factor": "no_systemic",
      "met": true
    },
    {
      "value": 0,
      "factor": "systemic_ge_1",
      "met": false
    }
  ],
  "stools_per_day": 2,
  "systemic_features_met": 0
}

Client errors (HTTP 400)

Invalid params return 400 without charge. Shared HTTP 402 and 503 meanings: Payments.

HTTP	Code	When
400	`invalid_truelove_stools`	stools_per_day must be an integer from 0 to 40 (Truelove and Witts 1955). Returned before settlement; you are not charged.
400	`invalid_flag`	boolean clinical flags must be true or false Returned before settlement; you are not charged.
400	`invalid_items`	POST body must be a JSON object with only an items array Returned before settlement; you are not charged.
400	`invalid_item_count`	items must be an array of 1 to 25 objects Returned before settlement; you are not charged.
400	`invalid_item`	each items entry must be a JSON object Returned before settlement; you are not charged.

Related tools

Mayo DAI — Sum four caller-assigned Schroeder 1987 ulcerative colitis disease-activity index items (each integer 0-3) and return the total (max 12). Does not return later remission or activity bands.
PUCAI — Sum six caller-assigned Turner 2007 PUCAI item points and return the published total (max 85) with activity band.

Payment

Unpaid requests return HTTP 402 even if query parameters or POST items are missing or invalid, so CDP and agents can index the path. After a PAYMENT-SIGNATURE, invalid params return HTTP 400 JSON before settlement. magent does not charge. Fix the params, then request a new 402 quote for that complete URL. Catalog misses (empty matches, found=false) are valid paid 200s. Unpaid valid requests return HTTP 402 with a base64 PAYMENT-REQUIRED header. HTTP 503 is not a new quote: retry the same PAYMENT-SIGNATURE. Full handshake and shared payment errors: Payments. Stdio MCP: /docs/mcp.

Guarantees

HTTP 402 is unpaid, including a missing query. After PAYMENT-SIGNATURE, invalid parameters return HTTP 400 before settlement. You are not charged. HTTP 402 never includes the tool JSON.
exact: settlement finishes before the tool (paymentFlow upfront). batch-settlement: verify/deposit before the tool; chargedCumulativeAmount commits after HTTP 2xx. Uncertain or failed settlement fails closed (HTTP 503). Retry the same PAYMENT-SIGNATURE.
HTTP 402 is unpaid only. Do not sign a second authorization because of a 503.
Execution is timeout-bounded and concurrency-capped.
Calculator inputs are stored encrypted for allowlisted operators (Magent Console). They are not in public logs, SSH lookups, catalog, or rollups. Request logs store path without query.