Mindrative Developer API Reference

Institutional Grade Security Architecture

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

• 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.
• Cloud Vendor Isolation & Outbound SSRF Firewall: Backend execution runtimes enforce an egress host allowlist restricted strictly to trusted external endpoints over HTTPS (e.g. Google Gemini API). Outbound connections targeting AWS instance metadata (169.254.169.254), loopback (127.0.0.1), or internal private VPC subnets (RFC 1918) are unconditionally blocked, eliminating Server-Side Request Forgery risks.
• Information Leakage Prevention: Internal exceptions, stack traces, DynamoDB schemas, and AWS IAM ARNs are strictly suppressed by exception boundary layers. Only sanitized, machine-readable error codes are returned to clients.
• 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.

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:

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.

Per-User Symbol Quota Enforcement

To ensure deterministic computational latency, optimal caching, and fair resource allocation, all Developer API calls strictly enforce the authenticated user's account-level symbol limit configured in the Mindrative database:

If your request body specifies more positions than permitted by your account tier, the API terminates execution prior to downstream model invocation and returns:

{
  "error": "Symbol count exceeds your plan limit of 300 symbols. Request contained 350 symbols.",
  "code": "SYMBOL_LIMIT_EXCEEDED",
  "max_allowed_symbols": 300,
  "requested_symbols": 350,
  "documentation": "https://developer.mindrative.com#symbol-limits",
  "request_id": "req_e7a1b4c9"
}

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.

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:

{
  "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:

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

Auto-Briefing Developer APIs

In addition to the comprehensive multi-module portfolio scan, Mindrative provides dedicated, high-speed Auto-Briefing Developer APIs for each authenticated dashboard view. These endpoints synthesize module-specific quantitative telemetry into instant, machine-readable summaries, structured bullet points, and signed audit receipts.

Auto-Briefing Response Payload Example

Every Auto-Briefing endpoint returns a structured response matching the user interface cards on the corresponding dashboard page:

{
  "status": "success",
  "page": "macro",
  "page_name": "Macro Intel",
  "request_id": "req_8a1f2c9e7b3d",
  "timestamp": "2026-10-23T11:45:00Z",
  "tier": "ULTRA_INSTITUTIONAL",
  "briefing": {
    "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%",
      "FOMC rate trajectory discounts 25bps easing cycle"
    ],
    "basis": "Macro Intel daily curated events and global central bank feeds",
    "regime": "Growth Supportive",
    "metrics": {
      "growth_impact": 0.24,
      "liquidity_impact": 0.00,
      "vader_score": 0.38,
      "panic_share": 0.02,
      "negative_share": 0.11,
      "events_count": 18
    }
  },
  "receipt": {
    "receipt_id": "RCPT-BRF-7F2A90",
    "issued_at": 1729690000,
    "algorithm": "HMAC-SHA256",
    "signature": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
  },
  "audit": {
    "caller_id": "usr_institutional_ultra",
    "key_prefix": "mnd_live_****3f8a",
    "latency_ms": 42
  }
}

Auto-Briefing Integration Snippet (cURL)

curl -X POST "https://api.mindrative.com/v1/brief/screener" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -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"
  }'

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 and Auto-Briefing endpoints directly from this browser console using your institutional API key:

// Click 'Execute API Request' 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:

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.