Respiratory · LIVE

Berlin Definition of ARDS

Apply the 2012 Berlin Definition of ARDS and return whether the clinical box holds, severity (none, mild, moderate, or severe), and berlin_ards.

LIVE $0.005 USDC GET /api/calc/berlin_ards

Markdown: /docs/berlin-ards.md · Canonical: https://magentlab.com/docs/berlin-ards

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

What it computes

Apply the 2012 Berlin Definition of ARDS and return whether the clinical box holds, severity (none, mild, moderate, or severe), and berlin_ards.

When to use

When an agent already has the five caller-assigned Berlin flags and a PaO2/FiO2 ratio and needs the published severity. magent does not read radiographs or echo.

When not to use

Not a medical device.
Not a diagnosis. magent does not diagnose ARDS or set ventilator mode.
The caller assigns timing, imaging, origin, PEEP, and CPAP. magent does not read radiographs or echocardiography.
pf_ratio is the caller-supplied PaO2/FiO2 in mm Hg (20-800). magent does not recompute it from PaO2 and FiO2.
Mild allows PEEP or CPAP ≥5 cm H2O; moderate and severe require PEEP ≥5. CPAP alone with PF ≤200 is not Berlin ARDS.
This is the 2012 Berlin Definition (Ranieri et al.). Not the 1994 AECC definition, not Kigali (SpO2/FiO2), and not the oxygenation index.

Formula

clinical_box iff onset_within_1_week and bilateral_opacities_not_fully_explained and origin_not_fully_hf_or_fluid; severe iff clinical_box and pf_ratio <= 100 and peep_ge_5; moderate iff clinical_box and 100 < pf_ratio <= 200 and peep_ge_5; mild iff clinical_box and 200 < pf_ratio <= 300 and (peep_ge_5 or cpap_ge_5); berlin_ards iff severity is mild, moderate, or severe; else none (Ranieri 2012 Berlin Definition)

Citation

Title: Acute respiratory distress syndrome: the Berlin Definition
Authors: The ARDS Definition Task Force; Ranieri VM, Rubenfeld GD, Thompson BT, Ferguson ND, Caldwell E, Fan E, Camporota L, Slutsky AS
Source: JAMA. 2012;307(23):2526-2533
DOI: 10.1001/jama.2012.5669

Worked example

Clinical box, PEEP ≥5, PaO2/FiO2 90

Given: bilateral_opacities_not_fully_explained=truecpap_ge_5=falseonset_within_1_week=trueorigin_not_fully_hf_or_fluid=truepeep_ge_5=truepf_ratio=90

Onset within 1 week, bilateral opacities not fully explained, and origin not fully cardiac failure or fluid overload are all true (clinical box)
PEEP ≥5 is true; CPAP ≥5 is false
pf_ratio 90 ≤ 100 with PEEP → severity severe
berlin_ards is true

Clinical box with CPAP only and PaO2/FiO2 150

Given: bilateral_opacities_not_fully_explained=truecpap_ge_5=trueonset_within_1_week=trueorigin_not_fully_hf_or_fluid=truepeep_ge_5=falsepf_ratio=150

Clinical box holds
PF 150 is in the moderate band, but moderate requires PEEP ≥5
CPAP without PEEP when PF ≤200 is severity none
berlin_ards is false

Also searched as

Berlin Definition ARDS
Berlin ARDS criteria
Ranieri 2012 ARDS
PaO2/FiO2 ARDS severity
ARDS mild moderate severe
PEEP CPAP hypoxemia ARDS
Berlin consensus ARDS 2012
acute respiratory distress syndrome Berlin

Try

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

/api/calc/berlin_ards?onset_within_1_week=true&bilateral_opacities_not_fully_explained=true&origin_not_fully_hf_or_fluid=true&peep_ge_5=true&cpap_ge_5=false&pf_ratio=90

Full URL: https://api.magentlab.com/api/calc/berlin_ards?onset_within_1_week=true&bilateral_opacities_not_fully_explained=true&origin_not_fully_hf_or_fluid=true&peep_ge_5=true&cpap_ge_5=false&pf_ratio=90

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/berlin_ards?onset_within_1_week=true&bilateral_opacities_not_fully_explained=true&origin_not_fully_hf_or_fluid=true&peep_ge_5=true&cpap_ge_5=false&pf_ratio=90"

Parameters

Name	Type	Required	Description
`onset_within_1_week`	boolean	required	Onset within 1 week of a known clinical insult or new or worsening respiratory symptoms (Ranieri 2012). true or false as assigned by the caller. magent does not take a history.
`bilateral_opacities_not_fully_explained`	boolean	required	Bilateral opacities not fully explained by effusions, lobar/lung collapse, or nodules (Ranieri 2012). true or false as assigned by the caller. magent does not read radiographs.
`origin_not_fully_hf_or_fluid`	boolean	required	Respiratory failure not fully explained by cardiac failure or fluid overload (Ranieri 2012). true or false as assigned by the caller. magent does not read echocardiography.
`peep_ge_5`	boolean	required	PEEP >= 5 cm H2O as assigned by the caller (required for moderate and severe; either PEEP or CPAP for mild). magent does not set ventilator mode.
`cpap_ge_5`	boolean	required	CPAP >= 5 cm H2O as assigned by the caller (counts for mild only; CPAP without PEEP is not moderate or severe). magent does not set ventilator mode.
`pf_ratio`	number	required	PaO2/FiO2 ratio in mm Hg (20-800). Caller-supplied; magent does not recompute from PaO2 and FiO2.

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/berlin_ards 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": [
    {
      "bilateral_opacities_not_fully_explained": "true",
      "cpap_ge_5": "false",
      "onset_within_1_week": "true",
      "origin_not_fully_hf_or_fluid": "true",
      "peep_ge_5": "true",
      "pf_ratio": "90"
    },
    {
      "bilateral_opacities_not_fully_explained": "true",
      "cpap_ge_5": "false",
      "onset_within_1_week": "true",
      "origin_not_fully_hf_or_fluid": "true",
      "peep_ge_5": "true",
      "pf_ratio": "90"
    }
  ]
}

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/berlin_ards",
  "items": [
    {
      "severity": "severe",
      "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": "The ARDS Definition Task Force; Ranieri VM, Rubenfeld GD, Thompson BT, Ferguson ND, Caldwell E, Fan E, Camporota L, Slutsky AS",
        "doi": "10.1001/jama.2012.5669",
        "id": "ranieri-2012",
        "pmid": "22797452",
        "source": "JAMA. 2012;307(23):2526-2533",
        "title": "Acute respiratory distress syndrome: the Berlin Definition"
      },
      "formula": "berlin_ards",
      "formula_expression": "clinical_box iff onset_within_1_week and bilateral_opacities_not_fully_explained and origin_not_fully_hf_or_fluid; severe iff clinical_box and pf_ratio <= 100 and peep_ge_5; moderate iff clinical_box and 100 < pf_ratio <= 200 and peep_ge_5; mild iff clinical_box and 200 < pf_ratio <= 300 and (peep_ge_5 or cpap_ge_5); berlin_ards iff severity is mild, moderate, or severe; else none (Ranieri 2012 Berlin Definition)",
      "criteria": [
        {
          "factor": "onset_within_1_week",
          "met": true
        },
        {
          "factor": "bilateral_opacities_not_fully_explained",
          "met": true
        },
        {
          "factor": "origin_not_fully_hf_or_fluid",
          "met": true
        },
        {
          "factor": "clinical_box",
          "met": true
        },
        {
          "factor": "peep_ge_5",
          "met": true
        },
        {
          "factor": "cpap_ge_5",
          "met": false
        },
        {
          "value": 90.0,
          "factor": "severe",
          "met": true
        },
        {
          "value": 90.0,
          "factor": "moderate",
          "met": false
        },
        {
          "value": 90.0,
          "factor": "mild",
          "met": false
        }
      ],
      "berlin_ards": true,
      "clinical_box": true,
      "pf_ratio": 90.0
    },
    {
      "severity": "severe",
      "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": "The ARDS Definition Task Force; Ranieri VM, Rubenfeld GD, Thompson BT, Ferguson ND, Caldwell E, Fan E, Camporota L, Slutsky AS",
        "doi": "10.1001/jama.2012.5669",
        "id": "ranieri-2012",
        "pmid": "22797452",
        "source": "JAMA. 2012;307(23):2526-2533",
        "title": "Acute respiratory distress syndrome: the Berlin Definition"
      },
      "formula": "berlin_ards",
      "formula_expression": "clinical_box iff onset_within_1_week and bilateral_opacities_not_fully_explained and origin_not_fully_hf_or_fluid; severe iff clinical_box and pf_ratio <= 100 and peep_ge_5; moderate iff clinical_box and 100 < pf_ratio <= 200 and peep_ge_5; mild iff clinical_box and 200 < pf_ratio <= 300 and (peep_ge_5 or cpap_ge_5); berlin_ards iff severity is mild, moderate, or severe; else none (Ranieri 2012 Berlin Definition)",
      "criteria": [
        {
          "factor": "onset_within_1_week",
          "met": true
        },
        {
          "factor": "bilateral_opacities_not_fully_explained",
          "met": true
        },
        {
          "factor": "origin_not_fully_hf_or_fluid",
          "met": true
        },
        {
          "factor": "clinical_box",
          "met": true
        },
        {
          "factor": "peep_ge_5",
          "met": true
        },
        {
          "factor": "cpap_ge_5",
          "met": false
        },
        {
          "value": 90.0,
          "factor": "severe",
          "met": true
        },
        {
          "value": 90.0,
          "factor": "moderate",
          "met": false
        },
        {
          "value": 90.0,
          "factor": "mild",
          "met": false
        }
      ],
      "berlin_ards": true,
      "clinical_box": true,
      "pf_ratio": 90.0
    }
  ]
}

Response

Field	Type	Description
`formula`	string	berlin_ards
`formula_expression`	string	Ranieri 2012 Berlin Definition clinical box and PaO2/FiO2 severity rule
`pf_ratio`	number	Caller-supplied PaO2/FiO2 in mm Hg used for severity
`clinical_box`	boolean	true when onset within 1 week, bilateral opacities not fully explained, and origin not fully cardiac failure or fluid overload all hold
`severity`	string	none, mild, moderate, or severe. Mutually exclusive. Not a diagnosis.
`berlin_ards`	boolean	true when severity is mild, moderate, or severe. Not a diagnosis.
`criteria`	array	Per-factor rows with factor and met; severe, moderate, and mild rows include pf_ratio as value
`citation`	object	Ranieri 2012 JAMA Berlin Definition citation
`disclaimer`	string	Not-a-device notice

Example JSON

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

{
  "severity": "severe",
  "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": "The ARDS Definition Task Force; Ranieri VM, Rubenfeld GD, Thompson BT, Ferguson ND, Caldwell E, Fan E, Camporota L, Slutsky AS",
    "doi": "10.1001/jama.2012.5669",
    "id": "ranieri-2012",
    "pmid": "22797452",
    "source": "JAMA. 2012;307(23):2526-2533",
    "title": "Acute respiratory distress syndrome: the Berlin Definition"
  },
  "formula": "berlin_ards",
  "formula_expression": "clinical_box iff onset_within_1_week and bilateral_opacities_not_fully_explained and origin_not_fully_hf_or_fluid; severe iff clinical_box and pf_ratio <= 100 and peep_ge_5; moderate iff clinical_box and 100 < pf_ratio <= 200 and peep_ge_5; mild iff clinical_box and 200 < pf_ratio <= 300 and (peep_ge_5 or cpap_ge_5); berlin_ards iff severity is mild, moderate, or severe; else none (Ranieri 2012 Berlin Definition)",
  "criteria": [
    {
      "factor": "onset_within_1_week",
      "met": true
    },
    {
      "factor": "bilateral_opacities_not_fully_explained",
      "met": true
    },
    {
      "factor": "origin_not_fully_hf_or_fluid",
      "met": true
    },
    {
      "factor": "clinical_box",
      "met": true
    },
    {
      "factor": "peep_ge_5",
      "met": true
    },
    {
      "factor": "cpap_ge_5",
      "met": false
    },
    {
      "value": 90.0,
      "factor": "severe",
      "met": true
    },
    {
      "value": 90.0,
      "factor": "moderate",
      "met": false
    },
    {
      "value": 90.0,
      "factor": "mild",
      "met": false
    }
  ],
  "berlin_ards": true,
  "clinical_box": true,
  "pf_ratio": 90.0
}

Client errors (HTTP 400)

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

HTTP	Code	When
400	`invalid_flag`	boolean clinical flags must be true or false Returned before settlement; you are not charged.
400	`invalid_pf_ratio`	pf_ratio must be a number from 20 to 800. 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

PaO2/FiO2 ratio — Compute the PaO2/FiO2 ratio as arterial PO2 in mm Hg divided by inspired oxygen fraction.
Murray lung injury score — Mean the four Murray 1988 lung injury score components (chest radiograph quadrants, PaO2/FiO2, PEEP, and compliance), each 0–4, and return LIS and injury_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.