Platform & Integrations

API keys give you programmatic access to the Evagene API. Unlike session tokens (which expire after 30 minutes), API keys are long-lived and designed for machine-to-machine communication. Each key has configurable scopes and rate limits, giving you fine-grained control over what it can do.

Key format

All Evagene API keys follow the format evg_<43 characters>. The evg_ prefix makes keys easy to identify in logs and configuration. Generated from 32 bytes of cryptographically secure randomness (256 bits of entropy). Only a SHA-256 hash is stored on the server.

Scopes

write implies read. analyse implies read. Use the narrowest scope your integration needs.

Rate limits

Every key has two configurable rate limits: per-minute (default 60) and per-day (default 10,000). Tracked via sliding window. When exceeded, the API returns 429 Too Many Requests.

Quick start

curl -H "X-API-Key: evg_your_key_here" \
     https://your-server/api/pedigrees

Maximum 20 keys per account. Keys can have optional expiry dates and can be revoked or deleted at any time. Full API keys documentation →

Evagene's AI interpretation uses a language model to analyse pedigree data and generate clinical insights. By default, the server's own key is used with a rolling 24-hour quota (typically 10 calls per day). With BYOK, you supply your own API key for Anthropic (Claude) or OpenAI (GPT) and bypass the quota entirely.

Supported providers

Encryption at rest

Your API key is encrypted before storage using Fernet (AES-128-CBC with HMAC-SHA256 authentication), keyed from the server's JWT secret. The key is never stored in plaintext and is decrypted only at the moment an LLM call is made, then discarded from memory.

Model override

The model override field lets you specify any model ID your provider supports. Use a larger model for complex pedigrees, a smaller one for quick analyses, or a reasoning model for the most challenging cases. Leave it blank to use the provider's default. Full BYOK documentation →

Webhooks send HMAC-SHA256 signed HTTP POST notifications to your endpoints when pedigree data changes. Use them to connect Evagene to EHR systems, LIMS platforms, Slack, or any service that accepts HTTP.

Event types

Payload format

Each delivery includes three headers for verification and tracing:

X-Evagene-Event: pedigree.updated
X-Evagene-Signature-256: sha256=<hex-digest>
X-Evagene-Delivery: <unique-uuid>

The body is JSON containing the event type, pedigree ID, timestamp, and change details. Always verify the HMAC-SHA256 signature before processing. Maximum 20 webhooks per user, with delivery history for the last 20 attempts per webhook. Full webhooks documentation →

Analysis templates let you create reusable AI prompt templates for specific clinical or research questions. Instead of relying solely on the built-in five-section interpretation, you can design custom analyses focused on pharmacogenomics, reproductive risk, research hypotheses, or any other aspect of a pedigree.

Template variables

Placeholders are replaced with computed values at execution time:

Example template

{
  "name": "Cancer Screening Protocol",
  "system_prompt": "You are an oncology genetic counsellor.",
  "user_prompt_template": "Review this family pedigree:\n\n{{pedigree_description}}\n\nThe proband is {{proband_name}} ({{proband_sex}}).\nDiseases: {{disease_list}}\n\nProvide:\n1. Cancer risk summary per syndrome\n2. Recommended genetic testing panel\n3. Screening schedule with start ages\n4. Cascade testing priorities for relatives"
}

Templates can be shared publicly with other users. Maximum 50 per account. Execution uses your BYOK key or the server default (subject to quota). Full templates documentation →

The Model Context Protocol (MCP) is an open standard that lets AI agents interact with external tools and data sources. Evagene includes an MCP server that exposes 11 pedigree management tools — meaning any MCP-compatible AI agent can create pedigrees, add individuals, run analyses, and import/export data through natural conversation.

Available tools

Claude Desktop configuration

{
  "mcpServers": {
    "evagene": {
      "command": "python",
      "args": ["-m", "evagene.mcp_server"],
      "env": {
        "EVAGENE_API_KEY": "evg_your_key_here",
        "EVAGENE_DB_PATH": "/path/to/data/evagene.db"
      }
    }
  }
}

Example conversation

Architecture

The MCP server operates as a separate process that connects directly to the same SQLite database as the Evagene web application. Changes made via MCP are immediately visible in the web UI (and vice versa). No additional network ports are needed — communication is via stdin/stdout. Full MCP server documentation →

Display Evagene pedigree diagrams on any website — patient portals, research dashboards, EHR integrations, or internal tools. Pedigrees are rendered as standard SVG using recognised pedigree notation.

Three ways to embed

1. Full HTML page (iframe)

<iframe
  src="https://your-server/api/embed/PEDIGREE_ID?api_key=evg_your_key"
  style="border:none; width:100%; min-height:400px; border-radius:10px"
  loading="lazy">
</iframe>

2. Raw SVG (img tag)

<img src="https://your-server/api/embed/PEDIGREE_ID/svg?api_key=evg_your_key"
     alt="Family Pedigree"
     style="max-width:100%">

3. JavaScript snippet (automatic)

<div data-evagene-pedigree="PEDIGREE_ID"
     data-evagene-key="evg_your_key"></div>

<script src="https://your-server/api/embed/snippet.js"></script>

SVG symbol notation

Pedigrees can also be accessed without authentication if marked as public — suitable for educational examples, published case studies, or anonymised demonstrations. The SVG is responsive and scales to fit the container. Full embeddable viewer documentation →

Security considerations