Developer API · v1

Your family tree, programmable.

Let an AI agent do the digging across archives and records, then write its findings straight into your tree — where it's rendered beautifully, kept private by default, and shared with the whole family from one link. You build the research; we are the home and the gallery.

Authentication

Every request carries a personal API key as a Bearer token. Create one under Settings → Developer API (a paid-plan feature). We store only a hash of the key, so copy it when it's shown — it can't be retrieved later.

Authorization: Bearer dyn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

The base URL is https://dynasty.house/api/v1. All responses are JSON.

Quick start

# who am I?
curl https://dynasty.house/api/v1/me \
  -H "Authorization: Bearer $DYNASTY_KEY"

# list my trees
curl https://dynasty.house/api/v1/trees \
  -H "Authorization: Bearer $DYNASTY_KEY"

For AI agents

Everything here is built to be machine-discoverable. Point your assistant at any of these:

OpenAPI 3.1 spec — https://dynasty.house/openapi.json (import into Claude, ChatGPT, Postman or an SDK generator).
Discovery endpoint — GET https://dynasty.house/api/v1 returns the endpoint index, no auth needed.
llms.txt — https://dynasty.house/llms.txt describes the service and this API in plain language.

A good agent records its source in each person's notes and never invents facts — only what the records support. A hosted MCP server is coming so agents connect with no glue code at all.

The data model

A tree is a window onto a graph of three things:

people — the full record. Vitals (given, surname, maiden_name, sex = M/F/U, birth_date, birth_place, death_date, death_place) plus the rich layer relatives gather: notes (research notes), biography (their written life story), distinction (a one-line claim to fame), a free-form profile object, a photo, and a list of life events.
unions — a partnership: { id, partner1_id, partner2_id, marriage_date, marriage_place }.
children — a child link: { union_id, child_id }.
life events — milestones beyond birth/marriage/death: residence, occupation, baptism, burial, immigration, education, military, or a custom event. Each has a date, place and note.

A single GET /people/{id} returns everything for one person — every field, the parsed profile, their events, their marriages, and a photo_url — so your agent can read the whole human in one call, then enrich any part of them.

Dates are free-text (e.g. "1888", "12 May 1888", "abt 1890") so historical precision is never forced. The easiest way to build relationships is to create a person linked to an existing one (see below) — we handle the union plumbing for you.

Endpoints

GET /me

The account this key belongs to: { id, email, name, plan }.

GET /trees

Every tree you own or can edit: { trees: [{ id, name, slug, is_public, role, people }] }.

POST /trees

Create a tree. Body: { "name": "The Lopin Family" } → { id, name, role, people }.

GET /trees/:id

The whole family in one call — { tree, people: [...], unions: [...], children: [...] }. This is the primary read for an agent building context.

POST /trees/:id/people

Add a person, optionally tied to someone already in the tree.

curl -X POST https://dynasty.house/api/v1/trees/$TREE/people \
  -H "Authorization: Bearer $DYNASTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "given": "Wilhelm",
    "surname": "Lopin",
    "sex": "M",
    "birth_date": "1888",
    "birth_place": "Vienna, Austria",
    "notes": "Found in the 1910 parish register.",
    "link": { "type": "parent", "personId": "EXISTING_PERSON_ID" }
  }'

link.type is "spouse", "child" or "parent" — describing the new person's relationship to personId. Returns { id }.

GET /people/:id

One person's full record.

PATCH /people/:id

Partial update — send only the fields you want to change.

curl -X PATCH https://dynasty.house/api/v1/people/$PERSON \
  -H "Authorization: Bearer $DYNASTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "death_date": "1944", "death_place": "Vienna", "distinction": "Master clockmaker" }'

DELETE /people/:id

Remove a person; we tidy up any partnerships and events left behind.

Write their story & profile

The same PATCH writes the long-form fields. biography is the person's life story (this is what "write a story" means here); profile is a free-form object of whatever details relatives collect — occupation, religion, military unit, external links — merged so partial saves never overwrite earlier work.

# "Write a story": the biography field IS the person's life story.
curl -X PATCH https://dynasty.house/api/v1/people/$PERSON \
  -H "Authorization: Bearer $DYNASTY_KEY" -H "Content-Type: application/json" \
  -d '{ "biography": "Wilhelm was born in Vienna in 1888, the third of six...",
        "profile": { "occupation": "Clockmaker", "religion": "Catholic" } }'

GET /people/:id/events · POST · DELETE

Build a real timeline. GET returns the person's life events plus their vitals (birth, death, marriages). POST adds one. type is residence, occupation, baptism, burial, immigration, education, military, or event for anything custom. The canonical types birth / death write the person's dates, and marriage attaches to a union (add a spouse first).

# Add a life event (residence, occupation, military, immigration, ...)
curl -X POST https://dynasty.house/api/v1/people/$PERSON/events \
  -H "Authorization: Bearer $DYNASTY_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "military", "title": "K.u.k. Army",
        "date": "1915", "place": "Galicia", "note": "Source: muster roll." }'

Delete one with DELETE /people/{id}/events?event=EVENT_ID.

GET /people/:id/photo · POST · DELETE

Give an ancestor a face. POST accepts a multipart photo file, or a JSON { "url": "…" } and we fetch the image for you — handy when an agent finds a portrait online. JPEG, PNG, WebP or GIF, up to 8 MB. GET streams the image back. Photos are private: living people are never exposed publicly.

# Attach a portrait an agent found online (or upload a file)
curl -X POST https://dynasty.house/api/v1/people/$PERSON/photo \
  -H "Authorization: Bearer $DYNASTY_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.org/wilhelm-1910.jpg" }'

# ...or multipart from disk:
curl -X POST https://dynasty.house/api/v1/people/$PERSON/photo \
  -H "Authorization: Bearer $DYNASTY_KEY" -F photo=@portrait.jpg

Errors

Standard HTTP codes with a JSON { "error": "…" } body: 401 (bad/missing key), 402 (key valid but plan no longer includes the API), 404 (not found or no access), 400 (bad input). Be gentle with request volume; heavy automated use may be rate-limited.

What's next

A hosted MCP server (so Claude and other agents connect with zero glue code) and GEDCOM bulk import/export over the API are on the way. Tell us what you're building — hello@dynasty.house.

Build something your family will treasure.

Create an API key →