API Reference

Authentication

All developer API endpoints require an API key sent as a header. You receive your API key when your account is approved.

# Include in every request
x-api-key: uk_live_your_api_key_here

# Or as Bearer token
Authorization: Bearer uk_live_your_api_key_here

Your API key is associated with your developer account. Each instance you create bills against your account. Keep your key secure — it has full access to all your instances.

Error Codes

Instances

An instance is the billing unit. One instance = one client = one active payment. The same domain logic can be used across multiple instances, but each must be paid separately.

POST /api/v1/instances DEV AUTH

Create a new instance for a client. Billing starts immediately.

# Create an instance for a legal firm client
curl -X POST https://genesis-engine.tech/api/v1/instances \
  -H "x-api-key: uk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Escritorio Mendes & Associados",
    "client_ref": "mendes_2026",
    "llm_provider": "openai",
    "llm_model": "gpt-4o",
    "llm_api_key": "sk-...",
    "webhook_url": "https://yourapp.com/webhooks/kernel"
  }'

# Response
{
  "instance": {
    "instance_id": "inst_a3f9b2c1",
    "dev_id": "dev_...",
    "name": "Escritorio Mendes & Associados",
    "client_ref": "mendes_2026",
    "active": true,
    "created_at": "2026-04-04T17:00:00Z"
  },
  "message": "Instance created. Billing starts now."
}

GET /api/v1/instances DEV AUTH

List all your instances — both active and inactive.

DELETE /api/v1/instances/:instance_id DEV AUTH

Deactivate an instance. Billing stops immediately. The instance data (sessions, KB) is preserved for audit purposes.

PUT /api/v1/instances/:instance_id/llm DEV AUTH

Update the LLM configuration for an instance. Useful when a client switches providers.

Domains

The motor starts completely clean. You define the domain rules — approaches, authority sources, confidence thresholds, and delegation protocol. Each instance has its own isolated domain configuration.

POST /api/v1/instances/:id/domains DEV AUTH

Configure a domain for an instance. human_reviewer_required must be true — this is enforced by EU AI Act Art. 14 and cannot be bypassed.

# Domain configuration structure
{
  "domain_id": "oncology_brca",
  "name": "Oncology — Breast Cancer Research",
  "description": "MDR analysis for BRCA mutations",
  "version": "1.0.0",
  "approaches": [
    {
      "id": "genomic_analysis",
      "name": "Genomic Analysis",
      "description": "TCGA database analysis",
      "variations": ["brca1_panel", "brca2_panel", "her2_panel", "er_pr_panel"]
    }
  ],
  "frontier_threshold": 2,
  "frontier_threshold_justification": "2 gaps indicate genuine frontier in BRCA...",
  "authority_sources": ["TCGA", "cBioPortal", "PubMed"],
  "risk_level": "high",
  "confidence_threshold": 0.85,
  "human_reviewer_required": true,
  "delegation_protocol": [
    { "level": 1, "role": "oncologist", "conditions": ["Available"] },
    { "level": 2, "role": "committee", "conditions": ["Oncologist unavailable"], "quorum": 3 }
  ],
  "ai_act_articles": [12, 13, 14, 15],
  "metadata": { "author": "your-name", "created_at": "2026-04-04T00:00:00Z", "updated_at": "2026-04-04T00:00:00Z" }
}

GET /api/v1/instances/:id/domains DEV AUTH

List all configured domains for an instance.

Discovery

The core operation. The motor runs the DIPEngine exhaustion cycle (<200ms), then queues the LLM job asynchronously. You receive a job_id immediately and can poll or receive a webhook when complete.

POST /api/v1/instances/:id/discover DEV AUTH

# Response — returns immediately (<200ms)
{
  "session_id": "GE-A3F9B2D0",
  "instance_id": "inst_a3f9b2c1",
  "status": "PROCESSING",
  "message": "Frontier reached. LLM proposal queued.",
  "exhaustion": {
    "frontier_reached": true,
    "gap_count": 2,
    "total_variations": 8
  },
  "job_id": "job_abc123",
  "poll_url": "/api/v1/jobs/job_abc123"
}

# If classical approaches resolved it (no LLM needed)
{
  "status": "INDETERMINATE",
  "message": "Classical approaches resolved the problem.",
  "job_id": null
}

GET /api/v1/jobs/:job_id DEV AUTH

Poll a discovery job. Status: queued → processing → completed or failed.

# Webhook payload (sent to your webhook_url when job completes)
{
  "job_id": "job_abc123",
  "session_id": "GE-A3F9B2D0",
  "instance_id": "inst_a3f9b2c1",
  "status": "AWAITING_HUMAN",
  "review_id": "rev_xyz789"
}

Sessions

GET /api/v1/instances/:id/sessions DEV AUTH

List all sessions for an instance. Returns the 50 most recent by default.

GET /api/v1/instances/:id/sessions/:session_id DEV AUTH

Get full session detail including the complete SHA-256 event chain for audit purposes.

GET /api/v1/instances/:id/sessions/:session_id/export DEV AUTH

Export a session in different formats for compliance documentation.

Human Gate (Art. 14)

When the motor produces a proposal, it enters the Human Gate. A qualified human reviewer must approve or reject before any result enters the Knowledge Base. This is architecturally enforced — it cannot be bypassed.

GET /api/v1/instances/:id/reviews DEV AUTH

List all pending reviews awaiting human decision for an instance.

POST /api/v1/instances/:id/reviews/:review_id/decide DEV AUTH

# APPROVED → primitive enters the Knowledge Base
{ "success": true, "primitive_id": "prim_abc", "hash": "sha256..." }

# REJECTED → session marked INDETERMINATE
{ "success": false, "message": "Rejected. Session marked INDETERMINATE." }

Knowledge Base

The Knowledge Base stores promoted primitives — concepts that passed the Human Gate. Each instance has its own isolated KB.

GET /api/v1/instances/:id/kb DEV AUTH

List all active primitives. Supports ?q=search_term for search and ?include_deprecated=true to include deprecated entries.

POST /api/v1/instances/:id/kb/:primitive_id/deprecate DEV AUTH

Deprecate a primitive. The entry remains in the audit trail permanently — it cannot be deleted, only deprecated.