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 — id, given, surname, maiden_name, sex (M/F/U), birth_date, birth_place, death_date, death_place, notes, biography, distinction.
• unions — a partnership: { id, partner1_id, partner2_id, marriage_date, marriage_place }.
• children — a child link: { union_id, child_id }.

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 left empty.

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.