# GeneaRoute developer guide

GeneaRoute is a normalized, evidence-first interface for genealogy research. The web workspace, HTTP API, CLI, and hosted MCP server share the same private-project permissions and usage limits.

## Start

1. Create a free account at https://genearoute.flygonlc.com/sign-up.
2. Verify the account email.
3. Create a separate revocable API key for each agent or integration in the workspace.
4. Read the OpenAPI document at https://genearoute.flygonlc.com/api/v1/openapi.json or connect an MCP client to https://genearoute.flygonlc.com/api/mcp.

Use the header `Authorization: Bearer gr_live_...` for authenticated HTTP and MCP requests. Raw keys are revealed only once and are stored as hashes.

## Core workflows

- Route a public search across selected connected providers and preserve provider-level failures.
- Import a private GEDCOM in search-only mode, inspect its persisted portability report for broken references, vendor extensions, citation coverage, media and privacy review, preview possible duplicates, promote it as private unreviewed records, and roll back a clean batch without deleting the original upload.
- Compare two stored GEDCOM exports by exact cross-reference ID to review profile, relationship, citation, and source changes. Missing and new IDs remain review signals, not deletion or identity conclusions, and the comparison edits nothing.
- Turn safe exact-ID GEDCOM changes into one or more additive sealed proposals. Large plans split only at dependency-safe boundaries, all missing batches queue transactionally, earlier claims remain visible, new claims stay private and unreviewed, identical open batches are reused, and only a signed-in owner or editor can apply each atomic batch after inspecting every field.
- Capture a public webpage as source evidence and link an exact quotation to a fact or relationship.
- Run deterministic hypothesis-challenge, kinship-route, documentary DNA-correlation, pedigree-collapse, tree-integrity, evidence-gap, evidence-quality, same-name identity-separation, source-integrity, checkpoint, and proof-documentation reviews.
- Read one deterministic Research Pulse queue that prioritizes integrity errors, evidence gaps, changed sources, watch leads, overdue tasks, pending reviews, untested hypotheses, and incomplete research coverage without ranking ancestors or changing the tree.
- Turn current unsourced claims into deterministic Research Itineraries that preserve exact date and jurisdiction context, recognize exact prior searches, stage connected and offline work, hash each plan snapshot, and withhold outward query strings whenever a target includes a living person.
- Audit researcher-entered historical places for normalization, ambiguous aliases, broken links, date-range conflicts, coordinates, and jurisdiction context without asking AI to reconstruct boundaries or choose a repository.
- Reconstruct a time-bounded private one-place study from recorded events, relatives, citations, recurring surnames, and FAN Club associates while keeping co-location and cluster patterns separate from identity, kinship, residence, and truth claims.
- Audit one descendant-to-ancestor line generation by generation, including direct relationship citations, cited identity milestones, alternate routes, and recorded source origins, without deciding eligibility or promising institutional acceptance.
- With explicit private-AI consent, turn that deterministic lineage snapshot into an evidence-bound working narrative whose citations and unresolved gaps are attached by GeneaRoute after generation.
- Preflight living flags, privacy labels, active sharing and automation channels, private DNA metadata, and full versus privacy-safe exports without asking AI to determine life status, consent, or legal compliance.
- Plan repository and record-group coverage, reconcile lines to actual routed searches, and record manual or offline results while keeping planned, partial, unavailable, and completed work distinct.
- List current reviewed WikiTree identity anchors, then trace a public world-tree route from one private deceased person without sending private claims, notes, files, DNA metadata, or the review reason to WikiTree.
- Generate consent-gated Evidence Q&A answers, Connection Explanations, Evidence Lens document leads, Brick Wall Plans, and lineage narrative working drafts. Evidence Q&A excludes living and unknown-status people, binds exact online or offline sources after generation, and hashes the evidence snapshot used. These workflows do not apply claims automatically.
- Use Tree Triage without AI for exact commands and deceased-person source routing. Living-person scans never leave the private workspace and internal Commons index. After explicit consent, request a deceased-person-only synthesis or ambiguous-command interpretation with private-match filtering and a persistent processing receipt.
- Export full private or deceased-only privacy-safe GEDCOM 7, GEDZIP, and GEDCOM X JSON, plus account JSON, research packets, claim-by-claim proof dossiers, and Ed25519-signed evidence bundles with a separately published verification key.
- Export a Family Group Evidence Sheet for one private-tree person. Children are assigned to a union only when both parent links are recorded, and unresolved citation and vital-claim gaps stay visible.
- Export a person-centered Evidence Map as JSON, Markdown, and Graphviz DOT. It connects recorded claims and relationships to citations and shared source-origin labels while keeping uncited and dependent evidence visible.
- Export claim-aware full, short, and bibliography citation variants as GeneaRoute JSON, CSL-JSON, RIS, or BibTeX while preserving the researcher's entered citation and exact page or record locator and never inventing missing authors or dates.
- Poll the sanitized project event stream or configure an owner-controlled Genealogy Event Hook. Outbound tree, research, professional, family-suggestion, and agent-review events carry identifiers and limited state metadata, never names, client labels, objectives, time descriptions, notes, citations, excerpts, DNA details, files, or living-person attributes.
- Read and, with the required role and Professional plan, update a privacy-minimized Professional Engagement Ledger through HTTP, MCP, or CLI. Existing ledgers remain readable, exportable, and deletable after downgrade; full deletion requires explicit confirmation and removes every associated time entry.
- Bound each automation key independently. New keys default to at most 250 routed searches and 10 AI research actions per month, or the lower account allowance, and every cost-incurring API and hosted MCP workflow checks both ceilings.

## Safe agent changes

An API key can propose a locally referenced batch of new people, sources, facts, relationships, and citation links. GeneaRoute records the exact proposing key, seals the canonical contents with SHA-256, renders every submitted field, computes citation coverage for new facts and relationships, and makes no tree change at proposal time. The proposing key cannot approve or reject the batch. A signed-in owner or editor must enter the human decision and reason. Acceptance rechecks the seal and applies every operation in one serializable transaction or applies none of them.

## Provider catalog

- WikiTree: live. Public collaborative world tree with a documented read API.
- Wikidata: live. A worldwide CC0 knowledge graph routed as deceased-person research leads with direct item provenance.
- FamilySearch: approval_required. The largest shared family tree. Production access requires app approval.
- Geni: human_only. Human-only, signed-in workspace search through the member's own OAuth connection. Geni is excluded from agents, API keys, MCP, CLI, automation, and AI processing.
- Gramps Web: live. A private, open-source genealogy database with a full REST API.
- Europeana: live. European cultural-heritage records and digitized archival sources.
- Library of Congress: live. Public Library of Congress collections with source metadata and links.
- Internet Archive: live. Digitized genealogy books, county histories, directories, cemetery records, and local publications.
- Chronicling America: live. Keyless full-text discovery across millions of digitized historic U.S. newspaper pages from the Library of Congress.
- U.S. National Archives: approval_required. U.S. federal archival descriptions and digital-object metadata through the read-only Catalog API. Production activation requires an approved key.
- GEDCOM: local. Portable local family-tree files that remain under the user's control.

## Connector contract

Archives, genealogy platforms, and customer-controlled research services can inspect the versioned Draft 2020-12 connector schemas at https://genearoute.flygonlc.com/api/v1/connectors/schema. The contract preserves provider IDs, original record links, citations, repositories, access level, and uncertainty. A schema does not install a connector or authorize scraping. GeneaRoute reviews authentication, provider terms, attribution, licensing, living-person handling, network destinations, and rate limits before enabling one.

## Research cautions

Provider records, automated comparisons, relationship routes, AI output, and citation counts are research aids. They are not proof, reliability scores, or certification. Preserve conflicting claims and inspect the original records. Living-person and private-project data must stay within the authorized workspace.

## More

- Human-readable documentation: https://genearoute.flygonlc.com/docs
- OpenAPI: https://genearoute.flygonlc.com/api/v1/openapi.json
- Agent discovery: https://genearoute.flygonlc.com/llms.txt
- Privacy: https://genearoute.flygonlc.com/privacy
- Support: https://genearoute.flygonlc.com/contact