Mindrative Developer API Reference

Welcome to the Mindrative Institutional Quant Developer API. Engineered for family offices, quantitative hedge funds, RIA asset managers, and automated trading systems that demand programmatic access to institutional factor risk attribution, multi-module portfolio reviews, and AI-synthesized Investment Committee Memorandums.

Base URL

https://api.mindrative.com/v1

Required Plan

Ultra Tier

Throughput Quota

60 req/min · 10k/mo

Transport Protocol

HTTPS (TLS 1.3 only)

Institutional Grade Security Architecture

The Mindrative Developer API implements rigorous defense-in-depth security standards conforming to modern financial infrastructure benchmarks:

Zero-Knowledge API Key Storage

Raw API keys are cryptographically generated using a 192-bit CSPRNG entropy pool and are displayed exactly once during creation. Mindrative servers store only the unrecoverable SHA-256 digest of your API key. Even in the event of database exfiltration, plaintext keys cannot be reconstructed.

Strict Transport Layer Security (TLS 1.3): All HTTP connections require modern cipher suites with perfect forward secrecy. Unencrypted HTTP traffic is rejected.
Constant-Time Secret Verification: Authentication lookups employ constant-time comparison algorithms to neutralize side-channel and timing analysis attacks.
Granular CIDR / IP Whitelisting: Institutional accounts can enforce static IP restrictions on individual keys, ensuring API access is permitted only from your designated server subnets.
Signed Audit Receipts: Every execution returns an HMAC-SHA256 signed audit receipt verifying the exact portfolio weights, pricing snapshot timestamp, and execution hash.
Idempotency-Key Replay Protection: Network timeouts can be retried safely by including an Idempotency-Key UUIDv4 header to prevent duplicate execution.

Authentication & API Key Management

API keys are provisioned inside the Account Center > Developer API tab for users with an active Ultra or Enterprise subscription.

API keys begin with the prefix mnd_live_ followed by 48 hexadecimal characters.

HTTP Request Header Format

Authenticate by sending the API key as a Bearer token in the standard Authorization header, or alternatively using the X-API-Key header:

HTTP Headers

Authorization: Bearer mnd_live_7a9f2c8d4e1b305f6a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d
Content-Type: application/json
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Rate Limits & Service Level Agreements

The Ultra Plan Developer API provides dedicated high-performance throughput designed for quantitative trading infrastructure:

Tier	Rate Limit (Sliding Window)	Monthly Quota	Burst Concurrency	SLA Uptime
Ultra Plan	60 requests / minute	10,000 scans / month	10 simultaneous requests	99.99% Edge Availability
Enterprise Tier	Custom (Up to 1,200 req/min)	Unlimited	50 simultaneous requests	99.995% with dedicated VPC

Response headers indicate your current quota status on every request:

X-RateLimit-Limit: Maximum allowed requests per minute (e.g. 60).
X-RateLimit-Remaining: Remaining requests available in the active 60-second window.
X-RateLimit-Reset: Unix epoch timestamp when the current window resets.

Portfolio Auto-Scan API

The primary programmatic feature of the Mindrative Terminal: executes an automated 15-module quantitative review over equities and ETFs. The engine ingests price history, intraday tick momentum, covariance matrices, and curated macro data to produce risk metrics, indicator signals, and an AI Investment Committee Memorandum.

Request Body Parameters

Supply a JSON object specifying the target holdings. If positions is omitted or empty, the API automatically scans the user's saved/committed default account portfolio.

Field	Type	Description
positions array optional	Array of holding objects. If omitted, scans user's committed account portfolio. Maximum 100 positions.
positions[].symbol string required	Valid equity or ETF ticker (e.g. `"NVDA"`, `"MSFT"`, `"SPY"`).
positions[].shares number optional	Quantity of shares held (e.g. `50`). Used to calculate exact portfolio NAV and dollar value changes.
positions[].weight number optional	Target allocation percentage (0.0 to 100.0). If omitted, weights are derived proportionally from share values or equal weighted.
benchmark string optional	Reference comparison benchmark ETF. Default: `"SPY"` (S&P 500).
include_ai_memo boolean optional	When `true` (default), invokes Mindrative AI to synthesize a formal 5-section Investment Committee Memorandum.
timeframe string optional	Rolling risk evaluation window: `"1M"`, `"3M"` (default), `"6M"`, or `"1Y"`.
note string optional	Institutional mandate directive or risk constraint string (max 300 chars) passed to the AI risk officer.

Response Schema & Payload Structure

A successful request returns HTTP 200 with an institutional JSON envelope containing calculated risk metrics, holding-level signals, multi-module findings, and signed audit receipt:

HTTP 200 OK — application/json

{
  "status": "success",
  "request_id": "req_8f1b2c4d6e9a",
  "timestamp": "2026-10-23T07:45:00Z",
  "api_version": "v1",
  "tier": "ULTRA_INSTITUTIONAL",
  "scan": {
    "scan_id": "scn_9c7d4e2a1b5f",
    "as_of": "2026-10-23",
    "summary": {
      "nav": 1250000.00,
      "health_score": 88,
      "tier": "Strong",
      "positions_count": 4,
      "day_return_pct": 1.42,
      "day_value_change": 17750.00,
      "vs_benchmark_bps": 45,
      "return_3m_pct": 14.8,
      "benchmark_return_3m_pct": 8.2,
      "annualized_volatility_pct": 16.5,
      "max_drawdown_pct": -6.4,
      "sharpe_ratio": 1.94,
      "alpha_pct": 6.6
    },
    "holdings": [
      {
        "symbol": "NVDA",
        "shares": 50,
        "weight_pct": 25.0,
        "sector": "Semiconductors",
        "trend": "Bullish",
        "macd_state": "Bullish",
        "rsi_14": 64.2,
        "month_return_pct": 8.4
      },
      {
        "symbol": "MSFT",
        "shares": 30,
        "weight_pct": 25.0,
        "sector": "Software Infrastructure",
        "trend": "Bullish",
        "macd_state": "Bullish",
        "rsi_14": 58.1,
        "month_return_pct": 4.1
      }
    ],
    "findings": {
      "screener": {
        "headline": "4 of 4 holdings in a bullish trend · 0 overbought · 0 oversold",
        "bullets": [
          "Overbought (RSI ≥ 70): None",
          "Oversold (RSI ≤ 30): None",
          "MACD bullish on 4 of 4 holdings"
        ],
        "basis": "Summary of current holding signals; open Screener for full results"
      },
      "alphadeck": {
        "headline": "Strongest technical reads: NVDA 5/5, MSFT 5/5, AAPL 4/5",
        "bullets": [
          "Weakest: None flagged below neutral threshold",
          "A quick ranking of current signals, not a recommendation"
        ],
        "basis": "Summary ranking of current holding signals; open AlphaDeck for full analysis"
      },
      "backtest": {
        "headline": "Signals agree on 4 of 4 holdings",
        "bullets": [
          "Bullish on both trend and MACD: 4",
          "Bearish on both: 0",
          "Signal snapshot only: open Portfolio Backtest for historical win rates and P&L"
        ],
        "basis": "Snapshot of current signals; open Backtest for historical results"
      },
      "macro": {
        "headline": "18 curated macro events on Oct 23 · growth-supportive tailwind",
        "bullets": [
          "Regime read: growth-supportive (+0.24), liquidity-neutral (0.00)",
          "Mean VADER +0.38 · panic 2% · negative 11%"
        ],
        "basis": "Macro Intel daily curated events"
      }
    },
    "ai_memorandum": {
      "generated_at": 1729690000000,
      "model": "Mindrative AI Institutional Model",
      "text": "### 1. Executive Summary & Committee Verdict\n- Objective health: Health Score 88/100 (Strong Tier) with positive alpha (+6.6%).\n- Macro posture: Growth tailwind supportive of large-cap quality beta.\n\n### 2. Factor Exposures & Risk Attribution\n- Controlled concentration in tech infrastructure. Annualised 3M volatility is 16.5% vs benchmark 14.1%.\n\n### 3. Asymmetric Opportunities & Positive Catalysts\n- Accelerating earnings revisions in semiconductor and enterprise cloud holdings.\n\n### 4. Prioritised Tactical Action Plan\n- **Immediate (Days 1–5)**: Maintain core target allocations; monitor RSI upper boundaries.\n- **30-Day Window**: Rebalance if single-name weight exceeds 30% concentration limit.\n- **Discretionary / Watchlist**: Evaluate low-beta defensive hedges.\n\n### 5. Institutional Governance & Data Integrity Caveats\n- Automated quantitative scan for research workflow testing only; not financial advice."
    },
    "receipt": {
      "receipt_id": "RCPT-A78F21D4BC90",
      "issued_at": 1729690000,
      "algorithm": "HMAC-SHA256",
      "signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
  },
  "audit": {
    "caller_id": "usr_institutional_ultra",
    "key_prefix": "mnd_live_****3f8a",
    "latency_ms": 142
  }
}

15-Module Findings Breakdown

The findings dictionary distills multi-page quantitative engines into actionable, structured telemetry:

Screener (sc): Measures directional technical trends across moving averages, flagging overbought assets (RSI ≥ 70) with mean-reversion risk and oversold assets (RSI ≤ 30) presenting rebound opportunities.
AlphaDeck (al): Scores each holding from 0 to 5 across 5 orthogonal factors (Trend, MACD, RSI corridor, YTD momentum, 1-month rolling return) to identify momentum leaders and laggards.
Backtest Concordance (bt): Evaluates whether long-term trend filters and short-term oscillator signals agree, highlighting assets with high-conviction dual alignment.
Macro Intel (mi): Maps the macroeconomic regime using curated daily data (central bank speeches, inflation prints, liquidity impacts) into growth and liquidity tailwinds/headwinds.

AI Investment Committee Memorandum

When include_ai_memo: true is specified, the API invokes the Mindrative AI reasoning engine (fine-tuned on institutional risk governance protocols) to synthesize the raw telemetry into a structured, executive-level memorandum structured into 5 standardized sections:

Executive Summary & Committee Verdict: High-conviction assessment of health and regime posture.
Factor Exposures & Risk Attribution: Sector tilt, concentration, and drawdown risks.
Asymmetric Opportunities & Positive Catalysts: Leading momentum and catalysts.
Prioritised Tactical Action Plan: Specific time-horizon actions (Immediate Days 1–5, 30-Day Window, Watchlist Criteria).
Institutional Governance & Caveats: Coverage caveats, liquidity considerations, and legal disclaimers.

Integration Code Examples (Multi-Language SDKs)

Execute production-grade portfolio scans with clean, copy-pasteable snippets:

curl -X POST "https://api.mindrative.com/v1/portfolio/scan" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "positions": [
      {"symbol": "NVDA", "shares": 50, "weight": 25.0},
      {"symbol": "MSFT", "shares": 30, "weight": 25.0},
      {"symbol": "AAPL", "shares": 40, "weight": 25.0},
      {"symbol": "AMZN", "shares": 20, "weight": 25.0}
    ],
    "benchmark": "SPY",
    "include_ai_memo": true,
    "timeframe": "3M",
    "note": "Quarterly risk rebalancing review"
  }'

import json
import uuid
import urllib.request

API_KEY = "mnd_live_YOUR_API_KEY_HERE"
API_URL = "https://api.mindrative.com/v1/portfolio/scan"

payload = {
    "positions": [
        {"symbol": "NVDA", "shares": 50, "weight": 25.0},
        {"symbol": "MSFT", "shares": 30, "weight": 25.0},
        {"symbol": "AAPL", "shares": 40, "weight": 25.0},
        {"symbol": "AMZN", "shares": 20, "weight": 25.0}
    ],
    "benchmark": "SPY",
    "include_ai_memo": True,
    "timeframe": "3M",
    "note": "Quarterly risk rebalancing review"
}

req = urllib.request.Request(
    API_URL,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Client-Version": "mindrative-python-v1.0"
    },
    method="POST"
)

try:
    with urllib.request.urlopen(req, timeout=30) as response:
        scan_result = json.loads(response.read().decode("utf-8"))
        summary = scan_result["scan"]["summary"]
        print(f"Health Score: {summary['health_score']}/100 ({summary['tier']})")
        print(f"Sharpe Ratio: {summary['sharpe_ratio']} | Alpha: {summary['alpha_pct']}%")
        print(f"Scan ID: {scan_result['scan']['scan_id']}")
except urllib.error.HTTPError as exc:
    print(f"HTTP Error {exc.code}: {exc.read().decode('utf-8')}")

import { randomUUID } from "crypto";

const API_KEY = "mnd_live_YOUR_API_KEY_HERE";
const API_URL = "https://api.mindrative.com/v1/portfolio/scan";

async function runPortfolioScan() {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${API_KEY}`,
      "Idempotency-Key": randomUUID(),
      "X-Client-Version": "mindrative-node-v1.0"
    },
    body: JSON.stringify({
      positions: [
        { symbol: "NVDA", shares: 50, weight: 25.0 },
        { symbol: "MSFT", shares: 30, weight: 25.0 },
        { symbol: "AAPL", shares: 40, weight: 25.0 },
        { symbol: "AMZN", shares: 20, weight: 25.0 }
      ],
      benchmark: "SPY",
      include_ai_memo: true,
      timeframe: "3M"
    })
  });

  if (!response.ok) {
    const errorBody = await response.json();
    throw new Error(`API Error [${response.status}]: ${JSON.stringify(errorBody)}`);
  }

  const data = await response.json();
  console.log(`Scan completed: NAV $${data.scan.summary.nav.toLocaleString()}`);
  console.log(`Health: ${data.scan.summary.health_score}/100 (${data.scan.summary.tier})`);
  return data;
}

runPortfolioScan().catch(console.error);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"
)

func main() {
	apiKey := "mnd_live_YOUR_API_KEY_HERE"
	url := "https://api.mindrative.com/v1/portfolio/scan"

	payload := map[string]interface{}{
		"positions": []map[string]interface{}{
			{"symbol": "NVDA", "shares": 50, "weight": 25.0},
			{"symbol": "MSFT", "shares": 30, "weight": 25.0},
			{"symbol": "AAPL", "shares": 40, "weight": 25.0},
			{"symbol": "AMZN", "shares": 20, "weight": 25.0},
		},
		"benchmark":       "SPY",
		"include_ai_memo": true,
		"timeframe":        "3M",
	}

	bodyBytes, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(bodyBytes))
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", fmt.Sprintf("req-%d", time.Now().UnixNano()))

	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Printf("Status: %s\nResponse: %s\n", resp.Status, string(body))
}

Interactive Sandbox Tester

Test the Portfolio Auto-Scan endpoint directly from this browser console using your institutional API key:

API Key (Authorization: Bearer)

Request Body (JSON)

Execution Response Output

// Click 'Execute Auto-Scan' to run real-time API call or sandbox evaluation...

Error Codes & Handling

The API returns standard HTTP status codes accompanied by structured error objects with unambiguous machine-readable codes:

Status	Error Code	Resolution Directive
`400 Bad Request`	`INVALID_JSON`	Malformed request body. Check syntax, brackets, and quotes.
`400 Bad Request`	`INVALID_PORTFOLIO_WEIGHTS`	Position weights must be non-negative numbers between 0 and 100.
`401 Unauthorized`	`MISSING_API_KEY`	Pass your key in `Authorization: Bearer mnd_live_...` or `X-API-Key`.
`401 Unauthorized`	`INVALID_API_KEY`	The provided key does not match or has been deleted. Generate a new key in Account Center.
`401 Unauthorized`	`KEY_EXPIRED`	The key passed its expiration timestamp. Generate a replacement key.
`403 Forbidden`	`PLAN_RESTRICTION`	The authenticated user does not have an active Ultra Plan subscription. Upgrade at mindrative.com/plan.html.
`403 Forbidden`	`IP_FORBIDDEN`	The client IP is not included in the key's configured CIDR allowlist.
`429 Too Many Requests`	`RATE_LIMIT_EXCEEDED`	Request frequency exceeded 60 req/min. Respect the `Retry-After` response header.
`500 Internal Error`	`INTERNAL_ANALYSIS_ERROR`	Upstream market data error. Retrying with Idempotency-Key is recommended.

Webhooks & Event Subscriptions (Developer Preview)

Ultra tier accounts can register webhook endpoints in the Developer Console to receive automated event dispatches:

portfolio.scan.completed: Fired whenever an automated scheduled or API scan completes.
portfolio.risk.breach: Dispatched when maximum drawdown or volatility exceeds customized thresholds.
portfolio.rebalance.suggested: Triggered when momentum indicators flag rebalancing divergence.

Webhook payloads carry an HMAC-SHA256 signature in the Mindrative-Signature header (t=timestamp,v1=signature) to verify authenticity and prevent replay attacks.