HEADS-ED (Cappelli)

HEADS-ED

Sum seven caller-assigned Cappelli 2012 HEADS-ED integers (0-2) and return the published 0-14 total and per-item scores.

LIVE $0.005 USDC GET /api/calc/heads_ed

Markdown: /docs/heads-ed.md · Canonical: https://magentlab.com/docs/heads-ed

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

What it computes

Sum seven caller-assigned Cappelli 2012 HEADS-ED integers (0-2) and return the published 0-14 total and per-item scores.

When to use

When an agent has already assigned Cappelli 2012 0-2 integers for each HEADS-ED domain and needs the published total, not a psychiatric consult or admission order.

When not to use

Not a medical device and not a psychiatric admission order.
Each of the seven domains is a caller-assigned integer 0, 1, or 2 from Cappelli 2012 (0 no action needed, 1 needs action but not immediately, 2 needs immediate action). magent does not interview a child.
Cappelli 2012 reported that the total predicted psychiatric consult and admission (sensitivity 82%, specificity 87%, AUC 0.82). That paper does not publish labeled score bands. magent returns the 0-14 total and per-item scores only and does not apply a later website high-risk rule as a named class.
This is Cappelli 2012 HEADS-ED only (seven domains; max 14). Not HEADS-ED Under 6. Not an unscored HEADSSS/HEEADSSS interview mnemonic.

Formula

HEADS-ED = home + education + activities + drugs + suicidality + emotions + discharge_resources; each caller-assigned 0-2 (0 no action needed, 1 needs action but not immediately, 2 needs immediate action); max 14

Citation

Title: The HEADS-ED: a rapid mental health screening tool for pediatric patients in the emergency department
Authors: Cappelli M, Gray C, Zemek R, Cloutier P, Kennedy A, Glennie E, Doucet G, Lyons JS
Source: Pediatrics. 2012;130(2):e321-e327
DOI: 10.1542/peds.2011-3798

Worked example

All domains 0

Given: activities=0discharge_resources=0drugs=0education=0emotions=0home=0suicidality=0

home 0 + education 0 + activities 0 + drugs 0 + suicidality 0 + emotions 0 + discharge_resources 0
Score = 0 (max 14)

High total with suicidality 2

Given: activities=2discharge_resources=1drugs=1education=2emotions=2home=2suicidality=2

home 2 + education 2 + activities 2 + drugs 1 + suicidality 2 + emotions 2 + discharge_resources 1
Score = 12 (max 14); suicidality 2. Cappelli 2012 does not name a labeled high-risk band.

Also searched as

HEADS-ED
HEADS ED
Cappelli HEADS-ED
pediatric ED mental health screen
home education activities drugs suicidality
HEADS-ED score
pediatric psychosocial screen ED

Try

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

/api/calc/heads_ed?home=0&education=0&activities=0&drugs=0&suicidality=0&emotions=0&discharge_resources=0

Full URL: https://api.magentlab.com/api/calc/heads_ed?home=0&education=0&activities=0&drugs=0&suicidality=0&emotions=0&discharge_resources=0

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/heads_ed?home=0&education=0&activities=0&drugs=0&suicidality=0&emotions=0&discharge_resources=0"

Parameters

Name	Type	Required	Description
`home`	integer	required	Caller-assigned Cappelli 2012 Home (integer 0-2): 0 no action needed (supportive); 1 needs action but not immediately (conflicts); 2 needs immediate action (chaotic/dysfunctional). magent does not interview a child.
`education`	integer	required	Caller-assigned Cappelli 2012 Education (integer 0-2): 0 no action needed (on track); 1 needs action but not immediately (grades dropping or absenteeism); 2 needs immediate action (failing/not attending). magent does not interview a child.
`activities`	integer	required	Caller-assigned Cappelli 2012 Activities/peers (integer 0-2): 0 no action needed (no change); 1 needs action but not immediately (reduction in activities/increased peer conflicts); 2 needs immediate action (increasingly to fully withdrawn/significant peer conflicts). magent does not interview a child.
`drugs`	integer	required	Caller-assigned Cappelli 2012 Drugs/alcohol (integer 0-2): 0 no action needed (none or infrequent); 1 needs action but not immediately (occasional); 2 needs immediate action (frequent/daily). magent does not interview a child.
`suicidality`	integer	required	Caller-assigned Cappelli 2012 Suicidality (integer 0-2): 0 no action needed (no thoughts); 1 needs action but not immediately (ideation); 2 needs immediate action (plan or gesture). magent does not interview a child.
`emotions`	integer	required	Caller-assigned Cappelli 2012 Emotions/behavior (integer 0-2): 0 no action needed (mildly anxious/sad/acting out); 1 needs action but not immediately (moderately anxious/sad/acting out); 2 needs immediate action (significantly distressed/unable to function/out of control). magent does not interview a child.
`discharge_resources`	integer	required	Caller-assigned Cappelli 2012 Discharge resources (integer 0-2): 0 no action needed (ongoing/well connected); 1 needs action but not immediately (some/not meeting needs); 2 needs immediate action (none/on waitlist). magent does not interview a child.

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/heads_ed 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": [
    {
      "activities": "0",
      "discharge_resources": "0",
      "drugs": "0",
      "education": "0",
      "emotions": "0",
      "home": "0",
      "suicidality": "0"
    },
    {
      "activities": "0",
      "discharge_resources": "0",
      "drugs": "0",
      "education": "0",
      "emotions": "0",
      "home": "0",
      "suicidality": "0"
    }
  ]
}

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/heads_ed",
  "items": [
    {
      "home": 0,
      "components": [
        {
          "value": 0,
          "factor": "home",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "education",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "activities",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "drugs",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "suicidality",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "emotions",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "discharge_resources",
          "points": 0,
          "present": true
        }
      ],
      "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": "Cappelli M, Gray C, Zemek R, Cloutier P, Kennedy A, Glennie E, Doucet G, Lyons JS",
        "doi": "10.1542/peds.2011-3798",
        "id": "cappelli-2012",
        "pmid": "22826567",
        "source": "Pediatrics. 2012;130(2):e321-e327",
        "title": "The HEADS-ED: a rapid mental health screening tool for pediatric patients in the emergency department"
      },
      "formula": "heads_ed",
      "formula_expression": "HEADS-ED = home + education + activities + drugs + suicidality + emotions + discharge_resources; each caller-assigned 0-2 (0 no action needed, 1 needs action but not immediately, 2 needs immediate action); max 14",
      "max_score": 14,
      "score": 0,
      "activities": 0,
      "discharge_resources": 0,
      "drugs": 0,
      "education": 0,
      "emotions": 0,
      "suicidality": 0
    },
    {
      "home": 0,
      "components": [
        {
          "value": 0,
          "factor": "home",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "education",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "activities",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "drugs",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "suicidality",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "emotions",
          "points": 0,
          "present": true
        },
        {
          "value": 0,
          "factor": "discharge_resources",
          "points": 0,
          "present": true
        }
      ],
      "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": "Cappelli M, Gray C, Zemek R, Cloutier P, Kennedy A, Glennie E, Doucet G, Lyons JS",
        "doi": "10.1542/peds.2011-3798",
        "id": "cappelli-2012",
        "pmid": "22826567",
        "source": "Pediatrics. 2012;130(2):e321-e327",
        "title": "The HEADS-ED: a rapid mental health screening tool for pediatric patients in the emergency department"
      },
      "formula": "heads_ed",
      "formula_expression": "HEADS-ED = home + education + activities + drugs + suicidality + emotions + discharge_resources; each caller-assigned 0-2 (0 no action needed, 1 needs action but not immediately, 2 needs immediate action); max 14",
      "max_score": 14,
      "score": 0,
      "activities": 0,
      "discharge_resources": 0,
      "drugs": 0,
      "education": 0,
      "emotions": 0,
      "suicidality": 0
    }
  ]
}

Response

Field	Type	Description
`formula`	string	heads_ed
`formula_expression`	string	Exact expression used
`score`	integer	HEADS-ED points 0-14
`max_score`	integer	Always 14
`home`	integer	Caller-assigned Home points 0-2
`education`	integer	Caller-assigned Education points 0-2
`activities`	integer	Caller-assigned Activities/peers points 0-2
`drugs`	integer	Caller-assigned Drugs/alcohol points 0-2
`suicidality`	integer	Caller-assigned Suicidality points 0-2
`emotions`	integer	Caller-assigned Emotions/behavior points 0-2
`discharge_resources`	integer	Caller-assigned Discharge resources points 0-2
`components`	array	Per-item caller-assigned points
`citation`	object	Cappelli et al. Pediatrics 2012 citation
`disclaimer`	string	Not-a-device notice

Example JSON

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

{
  "home": 0,
  "components": [
    {
      "value": 0,
      "factor": "home",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "education",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "activities",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "drugs",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "suicidality",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "emotions",
      "points": 0,
      "present": true
    },
    {
      "value": 0,
      "factor": "discharge_resources",
      "points": 0,
      "present": true
    }
  ],
  "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": "Cappelli M, Gray C, Zemek R, Cloutier P, Kennedy A, Glennie E, Doucet G, Lyons JS",
    "doi": "10.1542/peds.2011-3798",
    "id": "cappelli-2012",
    "pmid": "22826567",
    "source": "Pediatrics. 2012;130(2):e321-e327",
    "title": "The HEADS-ED: a rapid mental health screening tool for pediatric patients in the emergency department"
  },
  "formula": "heads_ed",
  "formula_expression": "HEADS-ED = home + education + activities + drugs + suicidality + emotions + discharge_resources; each caller-assigned 0-2 (0 no action needed, 1 needs action but not immediately, 2 needs immediate action); max 14",
  "max_score": 14,
  "score": 0,
  "activities": 0,
  "discharge_resources": 0,
  "drugs": 0,
  "education": 0,
  "emotions": 0,
  "suicidality": 0
}

Client errors (HTTP 400)

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

HTTP	Code	When
400	`invalid_heads_ed`	HEADS-ED inputs must match Cappelli 2012 home, education, activities, drugs, suicidality, emotions, and discharge resource items from that paper. 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

PEWS — Compute the Monaghan 2005 Brighton Paediatric Early Warning Score from caller-assigned behaviour, colour/CRT, respiratory effort, oxygen, quarter-hourly nebulisers, and persistent post-surgery vomiting, plus heart rate and respiratory rate against APLS 2005 age-group rest ranges used as that paper's normal rate and mean.
Paradise — Apply the Paradise 1984 eligibility frequency for recurrent throat infection and return whether paradise_criteria holds (frequency met and qualifying episode features).
PECARN febrile infant — Apply the Kuppermann 2019 PECARN clinical prediction rule and return low_risk only when a febrile infant 60 days or younger has a caller-assigned negative urinalysis, ANC ≤4090/µL, and serum procalcitonin ≤1.71 ng/mL.

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.