Zenith REST API v30.1

Developer API Reference

The Nilus Lab REST API provides biotechnology research institutions with programmatic access to the Zenith v30 foundation engines. Integrate cellular reprogramming models, methylation-based biological clocks, protein structure folds, and targeted LNP formulations directly into your bioinformatics pipelines.

Base URL

https://niluslab.com/api/v1

1. Installation & Environment

Use standard packages like HTTP libraries and binary file handling tools to communicate with the REST API. For scientific matrix serialization, you will need the standard python libraries:

CLI Setup

pip install requests numpy pandas anndata cellxgene-census

2. Authentication

All requests to the Zenith API must contain the standard developer header X-API-Key. Keys are issued through the Nilus Lab Console for validated institutional research credentials. Keep private keys secure; do not share them in frontend repositories.

Header Format

X-API-Key: zk_live_your_institutional_key_here

3. Rate Limiting & Throttling

The API uses a Redis-backed token bucket algorithm to enforce fair usage limits per key. The standard limits are:

Standard Institutional Keys: 60 requests per minute
Discovery Cluster Nodes: 300 requests per minute

Each response includes standard headers indicating current quota status:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current window.
X-RateLimit-Remaining	The number of remaining requests allowed before blocking.
X-RateLimit-Reset	Unix epoch time indicating when the current window resets.

4. Endpoint References

POST /api/v1/safety/audit

Evaluates biological sequences or epigenetic datasets for oncogenic safety compliance and calculates true biological age using the 353-CpG Horvath Epigenetic Clock model coefficients.

Request Schema

{
  "factors": [
    "GATA4",
    "TBX5",
    "OCT4"
  ],
  "cpg_methylation": {
    "cg00000292": 0.12,
    "cg00002033": 0.85,
    "cg00005847": 0.04
  }
}

Response Schema

{
  "status": "success",
  "data": {
    "approved_factors": [
      "GATA4",
      "TBX5",
      "OCT4"
    ],
    "blocked_factors": [
      "c-MYC"
    ],
    "sirtuin_engagement": {
      "pathway_score": 0.82,
      "targeted_sirtuins": [
        "SIRT1",
        "SIRT6"
      ]
    },
    "horvath_clock_impact": {
      "predicted_biological_age": 42.15,
      "probes_matched": 120,
      "probes_defaulted": 233,
      "total_clock_probes": 353
    },
    "safety_summary": "Passed pioneer safety gate. OSK partial mode active. Blocked oncogene: c-MYC."
  },
  "meta": {
    "model_version": "zenith-v30.0",
    "credits_used": 1,
    "compute_time_ms": 12
  }
}

POST /api/v1/structure/fold

Folds the provided amino acid sequence using Nilus Atomix, returning 3D atomic coordinates in standard Protein Data Bank (.pdb) output structure.

Request Schema

{
  "sequence": "MGDVEKGKKIFIMKCSQCHTVEKGGKHKTGPNLHGLFGRKTGQAPGYSYTAANKNKGIIWGEDTLMEYLENPKKYIPGTKMIFVGIKKKEERADLIAYLKKATNE"
}

Response Schema

{
  "status": "success",
  "data": {
    "source": "Nilus Atomix-Live",
    "fallback_used": false,
    "provider": "Nilus Atomix",
    "provider_status": "ok",
    "sequence_length": 105,
    "pdb_data": "HEADER    PROTEIN BINDING                         02-JUL-26\nTITLE     ESMFOLD PREDICTED STRUCTURE\nATOM      1  N   MET A   1      12.420  15.106  23.840  1.00 85.00           N\nATOM      2  CA  MET A   1      13.500  14.280  24.120  1.00 85.00           C\n...",
    "metrics": {
      "length": 105,
      "compute_time_sec": 1.25,
      "predicted_lddt": 85.0,
      "confidence_source": "pLDDT/B-factor-derived"
    },
    "cache_hit": false,
    "scientific_limitations": [
      "Single-sequence structure prediction only",
      "Not ZenithFold",
      "Not AlphaFold3",
      "Not ligand-aware",
      "Not validated for clinical use"
    ]
  },
  "meta": {
    "credits_used": 10,
    "compute_time_ms": 1250
  }
}

POST /api/v1/predict/perturbation

Queries live datasets from the Chan Zuckerberg Cellxgene Census, feeds the expression vectors into the scVI specialist models, executes transcriptomic perturbations, and prepares results in standard AnnData format.

Request Schema

{
  "baseline_cell_type": "ventricular_myocyte",
  "perturbation_factors": {
    "GATA4": 1.5,
    "SIRT1": 2.0
  },
  "census_filter": "tissue_general == 'heart' and disease == 'normal'"
}

Response Schema

{
  "job_id": "job_01h26c483aefd28e",
  "status": "pending",
  "status_url": "https://niluslab.com/api/v1/jobs/job_01h26c483aefd28e",
  "eta_seconds": 6.0
}

POST /api/v1/lnp/optimize

Simulates lipid nanoparticle encapsulation models to optimize structural targeting efficiency for heart tissues.

Request Schema

{
  "molar_ratios": {
    "ionizable": 0.50,
    "helper": 0.10,
    "cholesterol": 0.385,
    "peg": 0.015
  },
  "np_ratio": 6.0,
  "active_ligand_conjugation": true,
  "ligand_density": 2.5,
  "peg_mw": 2000.0
}

Response Schema

{
  "status": "success",
  "data": {
    "circulation_half_life_hours": 12.5,
    "heart_selectivity_score": 0.88,
    "liver_sequestration_score": 0.12,
    "endosomal_escape_percent": 34.2,
    "particle_size_nm": 82.5,
    "zeta_potential_mv": -14.2,
    "encapsulation_efficiency_percent": 94.2,
    "cytotoxicity_index": 0.15,
    "formulation_status": "OPTIMAL",
    "delivery_mechanism": "receptor_mediated_endocytosis",
    "mechanism_note": "Targeted ApoE-mediated receptor path verified."
  },
  "meta": {
    "model_version": "zenith-v30.0",
    "credits_used": 1,
    "compute_time_ms": 45
  }
}

POST /api/v1/webhooks/subscribe

Subscribes callback URLs to real-time async job completion notifications. All triggers are dispatched with an HMAC-SHA256 signature calculated against the payload.

Request Schema

{
  "url": "https://your-institutional-server.edu/webhooks/zenith"
}

Response Schema

{
  "status": "success",
  "data": {
    "subscription_id": 1,
    "url": "https://your-institutional-server.edu/webhooks/zenith",
    "signing_secret": "whsec_your_hmac_signing_secret_here",
    "status": "active",
    "created_at": "2026-07-01T04:19:38.256Z"
  },
  "meta": {
    "model_version": "zenith-v30.0",
    "credits_used": 0,
    "compute_time_ms": 5
  }
}

GET /api/v1/jobs/{job_id}

Retrieves the status of an asynchronous simulation job. If completed, provides download capability for the target AnnData .h5ad binary payload.

Response Schema (Running)

{
  "status": "success",
  "data": {
    "job_id": "job_01h26c483aefd28e",
    "status": "running",
    "status_url": "https://niluslab.com/api/v1/jobs/job_01h26c483aefd28e",
    "eta_seconds": 6.0
  },
  "meta": {
    "model_version": "zenith-v30.0",
    "credits_used": 0,
    "compute_time_ms": 1
  }
}

Response Schema (Completed)

{
  "status": "success",
  "data": {
    "job_id": "job_01h26c483aefd28e",
    "status": "completed",
    "filepath": "/tmp/job_01h26c483aefd28e.h5ad",
    "result": {
      "cell_count": 50,
      "genes_count": 4908,
      "source_dataset": "HCA Specialist (486k cells)",
      "download_url": "/api/v1/jobs/job_01h26c483aefd28e/download"
    }
  },
  "meta": {
    "model_version": "zenith-v30.0",
    "credits_used": 0,
    "compute_time_ms": 1
  }
}

5. Webhook HMAC-SHA256 Signature Verification

To prevent replay and spoofing attacks, Zenith signs all webhook callback requests with a cryptographic HMAC-SHA256 signature calculated against the raw request body payload bytes using the secret key returned at subscription time.

The signature is transmitted in the header:

X-Zenith-Signature: 6e9e4f21...

To verify the payload, calculate the HMAC signature directly against the request body using the raw secret key. Below is the complete, production-ready Python verification snippet:

import hmac
import hashlib

def verify_signature(payload_body: bytes, signature_header: str, secret_key: str) -> bool:
    """
    Verifies the Zenith HMAC-SHA256 signature calculated against the raw payload bytes.
    """
    # 1. Compute local HMAC-SHA256 hash using the secret key
    computed_sig = hmac.new(
        secret_key.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    
    # 2. Compare signature arrays in constant-time
    return hmac.compare_digest(computed_sig, signature_header)

6. SDK Integration Examples

Python Pipeline Integration

Complete script to launch a cell perturbation simulation, poll until completion, download the `.h5ad` file, and load it into Scanpy/AnnData:

import time
import requests
import anndata as ad

API_KEY = "zk_live_your_key_here"
BASE_URL = "https://niluslab.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

def run_cohort_perturbation():
    # 1. Launch the async simulation job
    payload = {
        "baseline_cell_type": "ventricular_myocyte",
        "perturbation_factors": {"GATA4": 1.5, "SIRT1": 2.0},
        "census_filter": "tissue_general == 'heart' and disease == 'normal'"
    }
    
    res = requests.post(f"{BASE_URL}/predict/perturbation", headers=HEADERS, json=payload)
    job = res.json()
    job_id = job["job_id"]
    print(f"Launched job {job_id}. Polling status...")

    # 2. Poll until completed
    while True:
        status_res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS)
        status_data = status_res.json()
        status = status_data["data"]["status"]
        
        if status == "completed":
            break
        elif status == "failed":
            raise Exception("Calculation failed on computing cluster.")
            
        print(f"Job status: {status}... waiting.")
        time.sleep(2)

    # 3. Stream binary AnnData download
    download_url = status_data["data"]["result"]["download_url"]
    file_path = f"perturbation_{job_id}.h5ad"
    
    # Prepend base domain if url returned is relative
    if download_url.startswith("/"):
        download_url = f"https://niluslab.com{download_url}"
        
    with requests.get(download_url, headers=HEADERS, stream=True) as stream:
        stream.raise_for_status()
        with open(file_path, 'wb') as f:
            for chunk in stream.iter_content(chunk_size=8192):
                f.write(chunk)
                
    print(f"Successfully downloaded results to {file_path}")
    
    # 4. Read matrix into AnnData
    adata = ad.read_h5ad(file_path)
    print(f"Matrix Dimension: {adata.shape}")
    print(adata.X[:5, :5])

if __name__ == "__main__":
    run_cohort_perturbation()

JavaScript / Node.js Integration

Node.js script using fetch syntax to request Nilus Atomix structure coordinates:

const apiKey = 'zk_live_your_key_here';
const baseUrl = 'https://niluslab.com/api/v1';

async function fetchProteinFold(sequence) {
  try {
    const response = await fetch(`${baseUrl}/structure/fold`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({ sequence })
    });

    const envelope = await response.json();
    if (envelope.status === 'success') {
      console.log('Coordinates loaded:');
      console.log(envelope.data.pdb_data.substring(0, 500) + '\n...');
    } else {
      console.error('Nilus Atomix failed:', envelope);
    }
  } catch (err) {
    console.error('Request Error:', err);
  }
}

fetchProteinFold('MGDVEKGKKIFIMKCSQCHTVEKGGKHKTGPNLHGLFG');

Raw cURL Shell Execution

Raw HTTP commands to query formulation optimizations:

curl -X POST "https://niluslab.com/api/v1/lnp/optimize" \
  -H "X-API-Key: zk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "molar_ratios": {
      "ionizable": 0.50,
      "helper": 0.10,
      "cholesterol": 0.385,
      "peg": 0.015
    },
    "np_ratio": 6.0,
    "active_ligand_conjugation": true,
    "ligand_density": 2.5,
    "peg_mw": 2000.0
  }'