API Reference

REQUEST BODY

# 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": "anthropic",
    "llm_model": "claude-sonnet-4-6",
    "llm_api_key": "sk-ant-...",
    "webhook_url": "https://yourapp.com/webhooks/kernel"
  }'

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

# Domain configuration structure
{
  "domain_id": "oncology_brca",
  "name": "Oncology — Breast Cancer Research",
  "approaches": [
    {
      "id": "genomic_analysis",
      "name": "Genomic Analysis",
      "description": "TCGA database analysis of BRCA mutations",
      "variations": ["brca1_panel", "brca2_panel", "her2_panel", "er_pr_panel"]
    }
  ],
  "frontier_threshold": 2,
  "frontier_threshold_justification": "2 approach-level gaps indicate genuine frontier in BRCA research",
  "authority_sources": ["TCGA", "cBioPortal", "PubMed"],
  "risk_level": "high",
  "human_reviewer_required": true,
  "predicate_blacklist": [],
  "delegation_protocol": [
    { "level": 1, "role": "oncologist", "conditions": ["Available and active"] },
    { "level": 2, "role": "committee", "conditions": ["Oncologist unavailable > 48h"], "quorum": 3 }
  ]
}

REQUEST BODY

# Response — returns immediately with job_id
{
  "session_id": "GE-A3F9B2D0",
  "instance_id": "inst_a3f9b2c1",
  "status": "PROCESSING",
  "domain_match_score": 0.74,
  "message": "ExplorationAgent running. Pipeline queued.",
  "job_id": "job_abc123",
  "poll_url": "/api/v1/jobs/job_abc123"
}

# If domain coherence score is below 12% — returns warning, no session created
{
  "session_id": null,
  "status": "DOMAIN_MISMATCH_WARNING",
  "domain_match_score": 0.03,
  "requires_confirmation": true,
  "warning": "Coherence score: 3%. Problem may not match domain.",
  "message": "Send with force_domain: true to proceed anyway."
}

# ── SCENARIO 1 — falsification.recommendation: ADVANCE or REVISE
#    Proposal survived → goes to HumanGate → review created
{
  "job": {
    "status": "completed",
    "falsification": {
      "recommendation": "REVISE",       // ADVANCE | REVISE → HumanGate
      "verification_score": 0.72
    }
  }
}
# → GET /reviews returns: { "reviews": [{ "review_id": "rev_xyz", ... }] }
# → Session: AWAITING_HUMAN → Next: POST /reviews/:id/decide

# ── SCENARIO 2 — falsification.recommendation: REJECT (automatic rejection)
#    ⚠️  reviews: [] is CORRECT and EXPECTED — not a bug
#    FalsificationAgent destroyed the proposal before HumanGate
{
  "job": {
    "status": "completed",              // completed ≠ approved
    "falsification": {
      "recommendation": "REJECT",       // ← proposal did not pass
      "verification_score": 0.15,      // below threshold
      "near_miss": {
        "closest_rejection_reason": "...", // decisive argument
        "rejection_threshold_delta": 0.15  // how far below threshold
      }
    }
  }
}
# → GET /reviews returns: { "reviews": [] }  ← CORRECT
# → Session: INDETERMINATE
# → AuditChain complete (Art.12 compliant)
# → Diagnose: read near_miss + proposal.vaar_annotations[level=BLOCKED]

# ── DIAGNOSIS when recommendation: REJECT
#    Use these fields to understand what to fix:

# 1. falsification.near_miss.closest_rejection_reason
#    → The argument that most influenced the REJECT decision

# 2. falsification.near_miss.rejection_threshold_delta
#    → Close to 0 = marginal decision; far from 0 = clear rejection

# 3. proposal.vaar_annotations filtered by level: BLOCKED
#    → Claims the system could not sustain epistemically
#    → Fix these before resubmitting

# 4. falsification.weaknesses_found
#    → Full list of weaknesses — one per falsification attempt

# ── SCENARIO 3 — Webhook when job completes with AWAITING_HUMAN
{
  "job_id": "job_abc123",
  "session_id": "GE-A3F9B2D0",
  "instance_id": "inst_a3f9b2c1",
  "status": "AWAITING_HUMAN",
  "review_id": "rev_xyz789",
  "delegation_level": 1,
  "near_miss": {
    "closest_rejection_reason": "Definition contains potential circular reasoning",
    "rejection_threshold_delta": 0.22,
    "conditions_for_rejection": ["If circular reasoning confirmed → REJECT"]
  }
}