Pedigree REST API: endpoints, scoped keys, webhooks, and worked examples

Short version. Evagene exposes a scoped, rate-limited REST API for programmatic access to pedigree data. API keys use the format evg_<43 chars>, are SHA-256 hashed at rest, and can carry any combination of three scopes: read, write, and analyse. Authentication is via the X-API-Key header. Rate limits are configurable and tier-based. Core endpoints cover pedigree CRUD, individual and relationship management, analysis (BRCAPRO, MMRpro, PancPRO, Mendelian, AI interpretation), and import / export in JSON, GEDCOM 5.5.1, 23andMe, XEG, image OCR, PNG, SVG, and PDF. HMAC-SHA256-signed webhooks for eight event types complete the picture. This page documents the shape of the API; evagene.net/help/platform_overview is the source of truth for exact endpoint paths and fields.

If you are evaluating Evagene's API for a production integration, start here for the mental model, then head to the live documentation for the definitive contract.

Design principles

The API follows a few consistent principles that make integrations predictable:

• Scoped keys. Every API key is scoped. A viewer embed holds a read key; a data-loading pipeline holds read + write; an AI-agent integration that runs models holds analyse. Least-privilege by default.
• Explicit resources. Pedigrees, individuals, relationships, analyses, imports, exports, templates, and webhooks are all first-class resources.
• JSON everywhere. All payloads are JSON, with deterministic field ordering, snake_case keys, and ISO-8601 timestamps.
• Event-driven extensions. Long-running operations (imports, AI interpretation, batch risk screens) emit webhooks on completion; the API never asks you to long-poll.
• Honest error surface. Standard HTTP status codes, machine-parseable error.code strings, and human-readable error.message fields.

Authentication and scopes

Generate an API key from the Evagene dashboard under Account > API Keys. Keys are created with a human-readable name, one or more scopes, and an optional rate-limit override. The plaintext key is shown once on creation — Evagene stores only the SHA-256 hash, so recovering a lost key is impossible by design; you rotate it.

GET /api/pedigrees HTTP/1.1
Host: your-evagene-instance.example.org
X-API-Key: evg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

The three scopes map to coarse capabilities:

• read — list and fetch pedigrees, individuals, relationships, analyses, templates.
• write — create, update, delete; import from GEDCOM/JSON/23andMe/XEG/images; export.
• analyse — run risk models (BRCAPRO, MMRpro, PancPRO, Mendelian, batch screen) and AI interpretation templates.

Keys can also carry metadata such as expiry timestamps and IP allow-lists. Keys without the scope required by a request are rejected with HTTP 403.

Rate limiting

Rate limits are enforced per API key on both a per-minute and per-day basis, with values that scale with the account tier and can be adjusted for integration accounts. When you exceed a limit, the API returns HTTP 429 Too Many Requests. Build clients that:

• Respect the standard Retry-After header and back off accordingly.
• Read rate-limit headers on every response so dashboards can surface how close integrations are to their budget.
• Batch bulk operations (for example, loading many individuals) to reduce request count.

Core endpoints

The endpoint taxonomy is intentionally boring — the API does not try to be clever. Conceptually:

Pedigrees
  GET    /api/pedigrees                  list pedigrees
  POST   /api/pedigrees                  create pedigree
  GET    /api/pedigrees/{id}             fetch pedigree
  PATCH  /api/pedigrees/{id}             update pedigree metadata
  DELETE /api/pedigrees/{id}             delete pedigree

Individuals (nested under a pedigree)
  GET    /api/pedigrees/{id}/individuals
  POST   /api/pedigrees/{id}/individuals
  GET    /api/pedigrees/{id}/individuals/{ind_id}
  PATCH  /api/pedigrees/{id}/individuals/{ind_id}
  DELETE /api/pedigrees/{id}/individuals/{ind_id}

Relationships
  POST   /api/pedigrees/{id}/relationships
  DELETE /api/pedigrees/{id}/relationships/{rel_id}

Analysis
  POST   /api/pedigrees/{id}/analyses    trigger BRCAPRO/MMRpro/PancPRO/Mendelian/AI
  GET    /api/pedigrees/{id}/analyses/{analysis_id}

Import / export
  POST   /api/pedigrees/{id}/export      format: gedcom|json|png|svg|pdf
  POST   /api/pedigrees/import           format: gedcom|json|23andme|xeg|image

The exact paths in your deployment may vary; the live documentation at evagene.net/help/platform_overview is authoritative.

Triggering risk analysis

Risk analysis is a POST that creates an analysis record and returns a reference. For fast models (BRCAPRO, MMRpro, PancPRO, Mendelian) the computation completes synchronously; for batch screens across all catalogued diseases, and for AI interpretation, the operation is asynchronous and you receive an analysis.completed webhook when ready.

POST /api/pedigrees/ped_9f2b.../analyses  HTTP/1.1
X-API-Key: evg_xxx...
Content-Type: application/json

{
  "type": "brcapro",
  "proband_id": "ind_1a3c...",
  "options": { "race": "non-Ashkenazi", "model_year": "current" }
}

Analysis types supported include brcapro, mmrpro, pancpro, mendelian, batch_screen, and ai_interpretation. AI interpretation accepts an Analysis Template ID; see LLM pedigree analysis for how templates structure the prompt.

Webhooks

Eight event types cover the lifecycle of pedigree data:

• pedigree.created, pedigree.updated, pedigree.deleted
• individual.created, individual.updated, individual.deleted
• analysis.completed
• import.completed

Each delivery is signed using a per-webhook secret:

X-Evagene-Signature: sha256=<hmac_sha256(secret, raw_body)>
X-Evagene-Delivery:  <unique delivery id>
X-Evagene-Event:     analysis.completed

Verify signatures before trusting the payload, store the delivery ID for idempotency, and re-read canonical state from the API before acting. Webhooks are hints, not ledger entries.

Use cases

Research cohort analysis

A research team loads hundreds of pedigrees from existing GEDCOM archives into Evagene using the import endpoint, triggers a batch BRCAPRO screen across the cohort, and consumes the analysis.completed webhook to feed results into a downstream analytics pipeline. Scopes: read + write + analyse.

Patient-portal embed

A patient portal team issues a read-scope key per institution, embeds Evagene's viewer in the portal's family-history tab, and uses the API to fetch structured disease annotations for the portal's own narrative display. Scopes: read only.

Cascade-testing tracker

A clinical service tracks which relatives of each proband have been offered, accepted, and completed genetic testing. The service polls the API for updates, writes testing status back as structured annotations on individuals, and uses webhooks to notify schedulers when new individuals appear in the pedigree. Scopes: read + write.

AI-agent integration

An internal clinical AI agent uses the API through the Evagene MCP server rather than calling endpoints directly. The MCP server sits on the API and exposes 11 tools to Claude Desktop, Claude Code, or any MCP-capable AI client. Scopes: as required by the specific tools exposed.

How this works in Evagene

The API is the surface on top of which all other Evagene platform capabilities are built:

• The embeddable pedigree viewer is an API client that renders SVG.
• The MCP server is an API client that exposes 11 tools to AI agents.
• The webhook dispatcher is the API's event-driven counterpart.
• BYOK LLM support, Analysis Templates, and AI interpretation are all exposed through the API surface.

This matters because whatever Evagene adds at the platform layer — native FHIR endpoints on the roadmap, additional analysis types, new import formats — is available through the same REST surface without a second auth system or a second URL space.

Frequently asked questions

Related reading

• Evagene platform overview
• Embeddable pedigree viewer
• Pedigree MCP server
• EHR pedigree integration
• HL7 FHIR and pedigree data
• GEDCOM pedigree software