HTTP API

Render family tree images directly from your scripts, without going through the MCP protocol.

Base URL: https://family-tree-maker.mnapoli.fr

POST /api/render

Renders a family tree as a PNG image.

Request

Method	`POST`
Path	`/api/render`
Content-Type	`application/json`
Query params	`scale` (optional, 0.5 – 4, default `2`) — pixel density multiplier.
Body	A `FamilyTree` JSON object (see schema).

Response

200 — image/png body.
Header x-share-url — path to re-open the tree in the web UI (append to the base URL).
400 — invalid JSON or invalid tree.
413 — rendered image exceeds size limits.
429 — rate limit hit (see retry-after).

Example

curl -X POST 'https://family-tree-maker.mnapoli.fr/api/render?scale=2' \
  -H 'content-type: application/json' \
  -d '{ "couple": { "father": { "name": "Vito Napoli", "birth": 1854 }, "mother": { "name": "Giuseppa Grammatico", "birth": 1860 }, "marriageYear": 1876 }, "fatherParents": { "father": { "name": "Girolamo Napoli" }, "mother": { "name": "Teresa Poma" } }, "motherParents": { "father": { "name": "Nicolo Grammatico" }, "mother": { "name": "Rosaria Rizzo" } }, "children": [ { "name": "Nicolo", "birth": 1880 }, { "name": "Rosaria", "birth": 1891 }, { "name": "Mario" } ] }' \
  --output tree.png

GET /api/tree.svg

Returns the SVG for a tree encoded in a shareable URL. Handy for debugging or embedding in HTML.

Method	`GET`
Path	`/api/tree.svg`
Query params	`d` (required) — the base64url-encoded tree as produced by the `?d=` query string on the home page.

curl 'https://family-tree-maker.mnapoli.fr/api/tree.svg?d=<encoded>' > tree.svg

Schema

A FamilyTree has this shape:

type FamilyTree = {
  couple: Couple;           // required — the central couple
  fatherParents?: Couple;   // optional — father's parents (grandparents)
  motherParents?: Couple;   // optional — mother's parents (grandparents)
  children?: Person[];      // up to 20
};

type Couple = {
  father: Person;
  mother: Person;
  marriageYear?: number;
};

type Person = {
  name: string;             // 1 – 50 chars
  birth?: number;           // integer year, -3000 to 3000
  death?: number;
};

Missing birth or death years are displayed as ? in the rendered tree.

Rate limits

The render endpoint is limited per client IP: a token bucket of 30 requests with a refill of one every two seconds. Exceeding the limit returns 429 with a retry-after header (in seconds).

Prefer MCP?

If you're integrating with an AI assistant rather than a backend service, the MCP endpoint gives you the same rendering capability wrapped in a tool that ChatGPT and Claude can call directly.