API Documentation — S.O.U.V.E.R.A.I.N.

Authentication

All API requests require an X-API-Key header. Your API key is available in Settings → API Access. Sovereign tier: 1,000 requests/day. Apex tier: unlimited.

HTTP Header Copy

X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Quickstart

Your first request

Fetch the current bio-state for a user. All biological data is processed locally — the API returns derived intelligence signals, never raw genomic data.

cURL Copy

curl -X POST https://api.souverain.bio/v1/biostate   -H "X-API-Key: sk_live_xxx"   -H "Content-Type: application/json"   -d '{
    "user_id": "usr_a1b2c3",
    "include_agents": ["genomic", "metabolomic"],
    "confidence_threshold": 0.89
  }'

Python SDK

Install via pip. The SDK wraps all REST endpoints and provides async support for the MQTT wearable bus.

Install Copy

pip install souverain

Basic usage Copy

from souverain import SouverainClient

# Initialise client
client = SouverainClient(api_key="sk_live_xxx")

# Get current bio-state
state = client.biostate(
    user_id="usr_a1b2c3",
    include_agents=["genomic", "metabolomic", "epigenomic"],
    confidence_threshold=0.89
)

print(state.bio_age_delta)   # -3.2
print(state.overall_state)  # "OPTIMAL"

# Run a Digital Twin simulation
sim = client.twin.simulate(
    user_id="usr_a1b2c3",
    intervention="fasting_+2hr",
    horizon_days=30
)
print(sim.bio_age_delta_projection)  # -3.5

Endpoint

POST /biostate

Returns the current biological intelligence state for a user. Aggregates signals from all active Omic Agents into a unified bio-state object.

Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	User identifier
`include_agents`	string[]	No	Omic agents to include. Default: all active
`confidence_threshold`	float	No	Minimum confidence (0–1). Default: 0.89

Endpoint

GET /interventions

Returns the current Sovereign Advice queue — a prioritised list of causal interventions generated by the Causal Inference Engine.

Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	User identifier
`limit`	integer	No	Max interventions (default 10, max 50)
`confidence_min`	float	No	Filter by confidence floor

Integration

MQTT Wearable Bus

The Physiological Bus uses MQTT for real-time wearable data ingestion. Connect any wearable device that supports the MQTT 3.1.1 protocol.

Python MQTT example

import paho.mqtt.client as mqtt
from souverain.bus import PhysiologicalBus

bus = PhysiologicalBus(
    host="mqtt.souverain.bio",
    port=8883,
    api_key="sk_live_xxx",
    user_id="usr_a1b2c3"
)

# Publish HRV reading
bus.publish(
    stream="hrv",
    value=58,
    unit="ms",
    source="oura_ring_v3"
)

Reference

Error codes

Code	Name	Description
`401`	Unauthorised	Missing or invalid API key
`403`	Forbidden	Endpoint not available on your tier
`429`	Rate limited	Daily quota exceeded (Sovereign: 1,000/day)
`422`	Unprocessable	Missing required parameter or invalid format
`503`	Agent offline	Requested Omic Agent is not active for this user

APIReference

API
Reference