Developer API

GENESIS AI²
API Reference

Every API call is receipted, hybrid-signed (ML-DSA-87 + Ed25519), and independently verifiable. Build on intelligence infrastructure that proves what it does.

REST + WebSocket
Every response carries a proof receipt
Ring-gated: no execution without authority
SIGNAL_SCHEMA_VERSION: 3

Quick Start

01
Get an API key
Issue a Sovereign DID and retrieve your API key from the AI² Console. Keys are scoped to a Ring level — Ring 2 keys query the advisory swarm; Ring 1 keys submit to the verification gate.
02
Ingest your first Signal
A Signal is the foundational object every capability grows from. It carries source, timestamp, confidence, payload, and cryptographic provenance.
POST /v1/signalscurl
curl -X POST https://api.genesisprotocol.ai/v1/signals \
  -H "Authorization: Bearer gk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source":    "github.connector.v1",
    "domain":    "engineering",
    "payload":   { "event": "pr_merged", "repo": "acme/core", "additions": 847 },
    "confidence": 1.0,
    "context":   { "org_id": "org_..." }
  }'
Constitutional boundary
Signals are facts — never estimates. A measured event (PR merged, invoice paid, CVE published) has confidence 1.0. A model inference must carry a confidence in [0,1] with a stated assumption. The API will reject a signal that mixes measurement and inference without explicit provenance separation.
03
Read your first Improvement Object
The Correlation Engine synthesizes ingested signals into typed, evidence-linked, time-aware Improvement Objects. Poll for new objects or subscribe via WebSocket.
GET /v1/improvement-objectscurl
curl https://api.genesisprotocol.ai/v1/improvement-objects \
  -H "Authorization: Bearer gk_live_..." \
  -G -d "org_id=org_..." -d "status=active" -d "limit=20"

Authentication

All requests require a Bearer token in the Authorization header. Keys are prefixed by environment:

gk_live_...
Production
Live sovereign node. Every response is receipted and verifiable. Receipts are stored in NESD.
gk_test_...
Sandbox
Simulated responses. Receipts are generated but stored only ephemerally. No NESD write. No Ring 0 gate.
Key rotationpython
import genesis

client = genesis.Client(api_key="gk_live_...")

# Rotate — old key remains valid for 24h
new_key = client.keys.rotate(
    scope="ring2",   # "ring2" | "ring1"
    ttl_days=90
)
print(new_key.id, new_key.created_at)

Ring Architecture

Genesis AI² exposes three concentric authority rings. API access is scoped per ring — a Ring 2 key cannot issue Ring 0 commands.

RING 2
Advisory Swarm
128 sovereign advisory agents. Advisory only — no action authority. Query, aggregate, and reason across any domain.
swarm.query
signals.ingest
improvement-objects.read
authority.submit (×)
RING 1
AI-Verify Gate
Formal verification layer. All Improvement Objects pass through before reaching Ring 0. Proofs generated here.
proofs.verify
myelin.gate
receipts.generate
governor.authorize (×)
RING 0
Deterministic Governor
Final authority. All actions gated. Deterministic, auditable, replay-verifiable. No execution without human approval.
authority.authorize
pole.commit
outcomes.record
receipts.seal (NESD)

Signal Ingestion

POST
/v1/signals
Ingest a Signal into the correlation engine. Every connector emits Signals — never Improvement Objects directly.
receipt ring-1 validation SIGNAL_SCHEMA_V3
GET
/v1/signals/{signal_id}
Retrieve a Signal by ID, including its ingestion receipt and correlation lineage.
receipt lineage
GET
/v1/signals
List signals for an organization. Filter by domain, source, or time range. Supports cursor pagination.
pagination filter: domain, source, since

Signal schema

source
string required
Connector identifier in reverse-domain notation. E.g. github.connector.v1
domain
string required
Organizational domain. One of: engineering · finance · legal · security · operations · hr · sales · product
payload
object required
Free-form event data. Must be JSON-serializable. Connector runtime validates structure against the connector's declared schema.
confidence
float [0–1]
Epistemic confidence. Measured facts → 1.0. Model inferences require explicit confidence and assumption. Defaults to 1.0 for connector-originated signals.
context
object
Routing context. Must include org_id. May include entity_id, tags.
schema_version
string
Signal schema version. Defaults to 3. Older versions are accepted and upgraded; newer versions fail-closed.

Improvement Objects

Improvement Objects are typed, evidence-linked, time-aware, confidence-explained artifacts produced by the Correlation Engine. You never create them directly — the engine does, from Signals.

GET
/v1/improvement-objects
List active Improvement Objects for an organization. Filter by type, domain, confidence threshold, or status.
filter: type, domain, confidence_min, status pagination
GET
/v1/improvement-objects/{io_id}
Retrieve a single Improvement Object with full evidence chain, contributing signals, corroboration score, and preparation status.
receipt evidence chain ring-1 verified
GET
/v1/improvement-objects/{io_id}/preparation
Retrieve the assembled preparation package: everything needed to act on this Improvement Object — briefings, options, blast-radius estimate, required authorizations. Never executes.
ring-0 gated execution preparation only

Proof Chain

GET
/v1/receipts/{receipt_id}
Retrieve a proof receipt. Receipts carry ML-DSA-87 + Ed25519 hybrid signatures, Merkle evidence root, NESD CID, and full replay metadata.
ML-DSA-87 + Ed25519 NESD-stored independently verifiable
POST
/v1/receipts/verify
Independently verify a receipt without trusting Genesis. Provide the receipt ID or raw receipt JSON. Returns mathematical verification result — no inference involved.
deterministic no-trust verification
Receipt objectJSON
{
  "id":          "rcpt_01j...",
  "version":     "GENESIS-RECEIPT-v3",
  "created_at":  "2026-08-09T21:00:00Z",
  "subject":     { "type": "improvement_object", "id": "io_..." },
  "evidence_root": "sha3-256:a4f7...",  // Merkle root over all contributing signals
  "ml_dsa_87":   "...",              // Post-quantum signature
  "ed25519":     "...",              // Classical signature (both must verify)
  "nesd_cid":    "bafyrei...",       // Permanent content-addressed storage
  "verifiable_at": "https://verify.genesisprotocol.ai/rcpt_01j..."
}

Authority Engine

Constitutional gate — Ring 0
The Authority Engine is the final gate between preparation and execution. Genesis never executes autonomously. Every action requires explicit human authorization captured as a signed PoLE (Pre-execution Commitment). This cannot be bypassed by API key scope, flag, or configuration.
POST
/v1/authority/authorize
Submit a human authorization decision for a prepared action. Creates a signed PoLE and hands execution control to the Governor. Requires human-authenticated JWT — API keys alone cannot authorize.
ring-0 PoLE committed human JWT required
GET
/v1/authority/pending
List actions awaiting human authorization. Displays preparation summary, blast-radius estimate, and resolution paths.
ring-0

Swarm Query

Query the Ring 2 advisory swarm directly. 128 sovereign agents across 18 domains analyze your question and return a synthesized, confidence-weighted response. Advisory only — no execution.

Swarm querypython
import genesis

client = genesis.Client(api_key="gk_live_...")

response = client.swarm.query(
    question="What is the single highest-leverage improvement available to us this quarter?",
    org_id="org_...",
    domains=["engineering", "finance", "product"],
    confidence_threshold=0.7
)

print(response.answer)
print(response.confidence)        # corroboration score across agents
print(response.receipt.id)        # proof receipt for this response
print(response.contributing_ios)  # Improvement Objects cited

SDKs

Python
● Live — v0.9.0
pip install genesis-ai2
TypeScript / Node
● Live — v0.8.2
npm install @genesis/ai2
Go
◌ Beta — Q4 2026
go get github.com/fromnovalue/genesis-go
Rust
◌ Planned — 2027
cargo add genesis-ai2 # coming

Rate Limits

Tier Signals / min IO reads / min Swarm queries / day Authority calls / day
Free 60 200 10 0
Sovereign 1,000 5,000 500 100
Enterprise Unlimited Unlimited Unlimited Unlimited

Rate-limit headers: X-Genesis-Limit, X-Genesis-Remaining, X-Genesis-Reset. 429 responses carry a Retry-After header.

Error Codes

400
Invalid Signal schema or missing required field. Check SIGNAL_SCHEMA_VERSION compatibility.
401
Missing or invalid API key. Verify key prefix matches environment (gk_live_ vs gk_test_).
403
Insufficient ring scope. Ring 0 actions require human-authenticated JWT; API keys alone are insufficient.
409
Constitutional conflict — signal contradicts an existing verified fact without corroboration path. Review the error.conflict_id field.
422
Confidence assertion failed. Measured fact submitted with confidence <1.0, or inference missing stated assumption.
429
Rate limit exceeded. See X-Genesis-Limit headers. Retry after the Retry-After interval.
500
Internal error. The request did not enter the proof chain — no partial receipt issued. Safe to retry.
503
Governor unavailable. Ring 0 is in maintenance mode. Advisory (Ring 2) endpoints remain available.
signal schema v3 · conformance 271/271 GATE_PASSED · watermark PBTG-CJM-OMEGA-v3-CANONICAL-LIVE