---
name: squiggler-ecg
description: Draw synthetic ECG tracings — rhythm strips and twelve-leads — with the Squiggler API, for teaching and simulation. Write a spec, check what it would draw, then render an image or hand the user a studio link. Use when asked to make, draw or generate an ECG or EKG, a rhythm strip or a twelve-lead for education, an exam question, a simulation or a teaching case.
---

# Squiggler ECG

Squiggler draws synthetic ECGs from a JSON description of the heart. Every tracing is
generated: it is for education, simulation and illustration only, it is not a recording of a
person, and it must never be presented as one or used for a clinical decision.

## Setup

- Base URL: `https://squiggler-api.fly.dev`
- Key: read it from the environment variable `SQUIGGLER_API_KEY` and send it in the
  `x-api-key` header. If it is not set, ask the user to set it. Never ask them to paste the key
  into the conversation, and never print it.
- Full reference: https://www.squiggler.io/apidocs/

## The loop

1. **Read the guide once per session**: `GET /v1/ecg/guide` (Markdown). It lists every field with
   its unit and range, which leads each ST and T change moves, ready-made specs and the rules
   that are easy to get wrong. Trust it over memory: the fields grow.
2. **Write a spec**: a JSON object with at least `rhythm`. Start from the nearest entry in
   `recipes` in `GET /v1/ecg/vocabulary`. Set `seed` and `patientSeed` when the tracing must come
   out the same next time; two tracings of one patient share `patientSeed`.
3. **Check it**: `POST /v1/ecg/check` with the spec.
   - `400`: read each `issues[].hint`, fix the spec, check again.
   - `200`: compare `label` (the rhythm's name), `measured` (rates, intervals, the ST level in
     each lead) and `advisories` with what was asked for. Fix and check again until they match.
4. **Show it**:
   - `POST /v1/ecg/link` returns `{ "url": … }`, a link that opens the tracing in the Squiggler
     studio with every dial live. Nothing is stored; the tracing is in the link. Give the user
     this when you cannot pass them an image.
   - `POST /v1/ecg/render` returns a PNG (or SVG with `accept: image/svg+xml`). Look at it if
     you can view images, and save it where the user asked.

```bash
curl -s -X POST https://squiggler-api.fly.dev/v1/ecg/check \
  -H "x-api-key: $SQUIGGLER_API_KEY" -H "content-type: application/json" \
  -d '{"rhythm":"sinus","format":"twelve_lead","stFoci":[{"epicenter":"inferior","mm":3}],"seed":"case-1"}'

curl -s -X POST https://squiggler-api.fly.dev/v1/ecg/link \
  -H "x-api-key: $SQUIGGLER_API_KEY" -H "content-type: application/json" \
  -d '{"rhythm":"sinus","format":"twelve_lead","stFoci":[{"epicenter":"inferior","mm":3}],"seed":"case-1"}'
```

## Rules worth knowing

- Unknown fields are refused with a `400`, not ignored. Take field names from
  `vocabulary.fields`, never from memory.
- Check before you render. Rendering, checking, linking and exporting share one allowance of 30
  requests a minute per key by default; a `429` carries `Retry-After`.
- The ST level a check reports is per lead, in millimetres. If the leads you meant are not the
  ones that moved, the spec is wrong, whatever the label says.
- Say in your answer that the tracing is synthetic and for teaching.