Zenith REST API v31.0

Developer API Reference

The Nilus Lab REST API provides research institutions with programmatic access to the Zenith v31 multi-dataset discovery and causal audit registry. Query 12-dataset pseudobulk statistics, 4-angle discovery concordances, and 4-gate causal directionality audits directly from your bioinformatics pipelines under Research Use Only (RUO) terms.

Base URL

https://niluslab.com/api/v1

1. Installation & Environment

Use standard HTTP libraries and scientific matrix tools to communicate with the REST API and inspect local `.h5ad` / `.tsv` outputs:

CLI Setup

pip install requests numpy pandas scipy statsmodels h5py anndata

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/targets/audit Audited Target Registry

Queries the 12-dataset multi-angle discovery and 4-gate causal directionality audit registry for candidate cardiac targets. Returns replication statistics across Reichart 2022, MAGNet bulk, and independent proteomic datasets alongside compensatory-brake and knockout safety gate verdicts.

Request Schema

{
  "genes": ["PPP1R12C", "TMEM65", "SYPL2", "ATP2A2", "ARHGAP1"],
  "discovery_angles": ["DCM_CONCORDANCE", "PROTEOMICS_MALECKI", "CAUSAL_DIRECTION"],
  "enforce_causal_safety_gate": true
}

Response Schema (Example format only)

{
  "status": "success",
  "data": {
    "PPP1R12C": {
      "status": "CANDIDATE_TARGET",
      "discovery_angle": "Angle 1 (Mural & Proteomics)",
      "magnet_dcm_q": "",
      "reichart_dcm_q": "",
      "malecki_lv_protein_log2fc": "",
      "malecki_lv_protein_q": "",
      "causal_verdict": "COMPUTATIONAL_IDENTIFICATION_ONLY",
      "recommended_action": "INHIBIT_OR_KNOCKDOWN"
    },
    "TMEM65": {
      "status": "CANDIDATE_TARGET",
      "discovery_angle": "Angle 2 (Inner Mitochondrial Membrane)",
      "dcm_z_score": "",
      "mouse_protein_q": "",
      "malecki_protein_p": "",
      "causal_verdict": "COMPUTATIONAL_IDENTIFICATION_ONLY",
      "recommended_action": "RESTORE"
    },
    "SYPL2": {
      "status": "CANDIDATE_TARGET",
      "discovery_angle": "Angle 3 (T-Tubule / SR Triad Junction)",
      "reichart_cm_q": "",
      "magnet_dcm_q": "",
      "causal_verdict": "COMPUTATIONAL_IDENTIFICATION_ONLY",
      "recommended_action": "RESTORE"
    },
    "ATP2A2": {
      "status": "POSITIVE_CONTROL",
      "discovery_angle": "Angle 3 (Positive Control Benchmark)",
      "rank_of_5677": "",
      "dcm_z_score": "",
      "malecki_lv_protein_log2fc": "",
      "causal_verdict": "DEPLETED_ESSENTIAL_MACHINERY",
      "recommended_action": "RESTORE_OR_ACTIVATE"
    },
    "ARHGAP1": {
      "status": "REJECTED_COMPENSATORY_BRAKE",
      "causal_verdict": "PROTECTIVE_COMPENSATORY_BRAKE_DO_NOT_INHIBIT",
      "safety_gate_note": "Knockout causes severe DCM and cardiac hypertrophy via uncontrolled RhoA-ROCK activation."
    }
  },
  "meta": {
    "registry_version": "DISCOVERY_01_02",
    "datasets_evaluated": 12
  }
}

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 (Example format only)

{
  "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-10-18T09:00:00.000Z"
  },
  "meta": {
    "model_version": "zenith-v31.0",
    "credits_used": 0,
    "compute_time_ms": 5
  }
}

GET /api/v1/jobs/{job_id}

Retrieves the status of an asynchronous pseudobulk aggregation or causal audit job. If completed, provides download capability for the target AnnData `.h5ad` or `.tsv` audit table.

Response Schema (Running)

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

Response Schema (Completed)

{
  "status": "success",
  "data": {
    "job_id": "job_01h26c483aefd28e",
    "status": "completed",
    "filepath": "/tmp/job_01h26c483aefd28e.tsv",
    "result": {
      "donors_evaluated": "",
      "fdr_concordant_genes": 451,
      "source_datasets": "12 Public Cardiac Datasets",
      "download_url": "/api/v1/jobs/job_01h26c483aefd28e/download"
    }
  },
  "meta": {
    "model_version": "zenith-v31.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 query the 12-dataset causal audit registry for candidate targets and filter out protective compensatory brakes:

import requests
import json
import pandas as pd

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

def audit_cardiac_targets():
    payload = {
                "genes": ["PPP1R12C", "TMEM65", "SYPL2", "ATP2A2", "ARHGAP1", "NOL3", "CIRBP"],
        "discovery_angles": ["DCM_CONCORDANCE", "PROTEOMICS_MALECKI", "CAUSAL_DIRECTION"],
        "enforce_causal_safety_gate": True
    }
    
    res = requests.post(f"{BASE_URL}/targets/audit", headers=HEADERS, json=payload)
    res.raise_for_status()
    records = json.loads(res.text)["data"]
    
    df = pd.DataFrame.from_dict(records, orient="index")
    print("Audited Targets Summary:")
    print(df[["tier", "causal_verdict", "recommended_action"]])

if __name__ == "__main__":
    audit_cardiac_targets()

JavaScript / Node.js Integration

Node.js script using fetch syntax to query the target audit endpoint:

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

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

    const envelope = JSON.parse(await response.text());
    if (envelope.status === 'success') {
      console.log('Target audit returned:', envelope.data);
    } else {
      console.error('Request failed:', envelope);
    }
  } catch (err) {
    console.error('Request Error:', err);
  }
}

auditTargets({
  genes: ['PPP1R12C', 'TMEM65', 'SYPL2', 'ATP2A2', 'ARHGAP1'],
  enforce_causal_safety_gate: true
});

Raw cURL Shell Execution

Raw HTTP command to query multi-cohort target audit records:

curl -X POST "https://niluslab.com/api/v1/targets/audit" \
  -H "X-API-Key: zk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "genes": ["PPP1R12C", "ZSWIM8", "SYPL2", "CBR4", "ZMAT3", "TMEM65", "ATP2A2"],
    "enforce_causal_safety_gate": true
  }'