{
  "openapi": "3.1.0",
  "info": {
    "title": "Mindrative Institutional Developer API",
    "version": "1.0.0",
    "description": "Enterprise and institutional REST API for automated portfolio scanning, factor risk attribution, multi-module quantitative diagnostics, and AI-synthesized Investment Committee Memorandums. Access is restricted to active Ultra and Enterprise tier subscribers.",
    "contact": {
      "name": "Mindrative Developer Relations & Quant Support",
      "email": "support@mindrative.com",
      "url": "https://mindrative.com"
    },
    "termsOfService": "https://mindrative.com/terms.html"
  },
  "servers": [
    {
      "url": "https://api.mindrative.com/v1",
      "description": "Production Edge API (US-East-1 accelerated via CloudFront, 99.99% SLA)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    },
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/portfolio/scan": {
      "post": {
        "summary": "Execute Portfolio Auto-Scan",
        "operationId": "executePortfolioAutoScan",
        "description": "Executes a rigorous 15-module automated portfolio scan across equities and ETFs. Computes Net Asset Value, 0-100 Health Score, Sharpe Ratio, Annualized Volatility, Maximum Drawdown, Screener trend counts, AlphaDeck technical momentum scores, Backtest historical signal concordance, and macroeconomic regime alignment. Optionally synthesizes a formal 5-section Investment Committee Memorandum via Mindrative AI.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique UUIDv4 string to prevent duplicate execution during network retries.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Client-Version",
            "in": "header",
            "required": false,
            "description": "Client integration version string for audit logs.",
            "schema": {
              "type": "string",
              "example": "2026.10"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Portfolio position details and scan options. If omitted or positions list is empty, scans the authenticated user's committed default portfolio.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PortfolioScanRequest"
              },
              "examples": {
                "customHoldings": {
                  "summary": "Custom Portfolio Scan with AI Synthesis",
                  "value": {
                    "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"
                  }
                },
                "defaultCommitted": {
                  "summary": "Scan Default Committed Account Portfolio",
                  "value": {
                    "include_ai_memo": true,
                    "benchmark": "SPY"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Portfolio Auto-Scan response with institutional metrics, module findings, and optional AI memorandum.",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": { "type": "integer" },
                "description": "The maximum number of requests allowed per minute (60 for Ultra tier)."
              },
              "X-RateLimit-Remaining": {
                "schema": { "type": "integer" },
                "description": "The number of remaining requests in the current rate limit window."
              },
              "X-RateLimit-Reset": {
                "schema": { "type": "integer" },
                "description": "The Unix epoch timestamp when the current rate limit window resets."
              },
              "X-Request-Id": {
                "schema": { "type": "string" },
                "description": "Unique trace identifier for this API transaction."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioScanResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request: Malformed JSON, invalid symbols, or negative weights.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Unauthorized: Missing, invalid, revoked, or expired API Key.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Forbidden: Requires active Ultra or Enterprise tier subscription, or caller IP is not permitted by key allowlist.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Too Many Requests: Rate limit exceeded (60 req/min for Ultra tier).",
            "headers": {
              "Retry-After": {
                "schema": { "type": "integer" },
                "description": "Number of seconds to wait before retrying."
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal Server Error during quantitative computation or upstream data resolution.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mnd_live_...",
        "description": "Pass your institutional API key with the standard Authorization Bearer header: `Authorization: Bearer mnd_live_...`"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative header for systems that require custom header authentication: `X-API-Key: mnd_live_...`"
      }
    },
    "schemas": {
      "PortfolioScanRequest": {
        "type": "object",
        "properties": {
          "positions": {
            "type": "array",
            "description": "Array of holdings to evaluate. Max 100 positions.",
            "items": {
              "$ref": "#/components/schemas/HoldingItem"
            }
          },
          "benchmark": {
            "type": "string",
            "default": "SPY",
            "description": "Reference benchmark ETF or index symbol (default: 'SPY').",
            "example": "SPY"
          },
          "include_ai_memo": {
            "type": "boolean",
            "default": true,
            "description": "Whether to invoke Mindrative AI to synthesize a 5-section Investment Committee Memorandum."
          },
          "timeframe": {
            "type": "string",
            "enum": ["1M", "3M", "6M", "1Y"],
            "default": "3M",
            "description": "Evaluation window for rolling volatility, returns, and drawdown."
          },
          "note": {
            "type": "string",
            "maxLength": 300,
            "description": "Institutional directive, mandate constraint, or user note to include in analysis."
          }
        }
      },
      "HoldingItem": {
        "type": "object",
        "required": ["symbol"],
        "properties": {
          "symbol": {
            "type": "string",
            "description": "Uppercase ticker symbol (e.g., 'NVDA', 'AAPL', 'MSFT').",
            "example": "NVDA"
          },
          "shares": {
            "type": "number",
            "minimum": 0,
            "description": "Quantity of shares held (optional if target weight is specified).",
            "example": 50
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Target portfolio weight percentage (e.g. 25.0 for 25%).",
            "example": 25.0
          }
        }
      },
      "PortfolioScanResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "request_id": {
            "type": "string",
            "example": "req_8f1b2c4d6e9a"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-10-23T07:45:00Z"
          },
          "api_version": {
            "type": "string",
            "example": "v1"
          },
          "tier": {
            "type": "string",
            "example": "ULTRA_INSTITUTIONAL"
          },
          "scan": {
            "$ref": "#/components/schemas/ScanPayload"
          },
          "audit": {
            "type": "object",
            "properties": {
              "caller_id": { "type": "string" },
              "key_prefix": { "type": "string", "example": "mnd_live_****3f8a" },
              "latency_ms": { "type": "number", "example": 142 }
            }
          }
        }
      },
      "ScanPayload": {
        "type": "object",
        "properties": {
          "scan_id": { "type": "string", "example": "scn_9c7d4e2a1b5f" },
          "as_of": { "type": "string", "example": "2026-10-23" },
          "summary": {
            "type": "object",
            "properties": {
              "nav": { "type": "number", "example": 1250000.00 },
              "health_score": { "type": "number", "example": 88 },
              "tier": { "type": "string", "example": "Strong" },
              "positions_count": { "type": "integer", "example": 4 },
              "day_return_pct": { "type": "number", "example": 1.42 },
              "day_value_change": { "type": "number", "example": 17750.00 },
              "vs_benchmark_bps": { "type": "number", "example": 45 },
              "return_3m_pct": { "type": "number", "example": 14.8 },
              "benchmark_return_3m_pct": { "type": "number", "example": 8.2 },
              "annualized_volatility_pct": { "type": "number", "example": 16.5 },
              "max_drawdown_pct": { "type": "number", "example": -6.4 },
              "sharpe_ratio": { "type": "number", "example": 1.94 },
              "alpha_pct": { "type": "number", "example": 6.6 }
            }
          },
          "holdings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "symbol": { "type": "string", "example": "NVDA" },
                "shares": { "type": "number", "example": 50 },
                "weight_pct": { "type": "number", "example": 25.0 },
                "sector": { "type": "string", "example": "Technology" },
                "trend": { "type": "string", "example": "Bullish" },
                "macd_state": { "type": "string", "example": "Bullish" },
                "rsi_14": { "type": "number", "example": 64.2 },
                "month_return_pct": { "type": "number", "example": 8.4 }
              }
            }
          },
          "findings": {
            "type": "object",
            "properties": {
              "screener": { "$ref": "#/components/schemas/ModuleFinding" },
              "alphadeck": { "$ref": "#/components/schemas/ModuleFinding" },
              "backtest": { "$ref": "#/components/schemas/ModuleFinding" },
              "macro": { "$ref": "#/components/schemas/ModuleFinding" }
            }
          },
          "ai_memorandum": {
            "type": "object",
            "properties": {
              "generated_at": { "type": "integer" },
              "model": { "type": "string", "example": "Mindrative AI Institutional Model" },
              "text": { "type": "string", "description": "Markdown formatted 5-section executive memorandum." }
            }
          },
          "receipt": {
            "type": "object",
            "properties": {
              "receipt_id": { "type": "string", "example": "RCPT-A78F21D4BC90" },
              "issued_at": { "type": "integer" },
              "algorithm": { "type": "string", "example": "HMAC-SHA256" },
              "signature": { "type": "string" }
            }
          }
        }
      },
      "ModuleFinding": {
        "type": "object",
        "properties": {
          "headline": { "type": "string" },
          "bullets": {
            "type": "array",
            "items": { "type": "string" }
          },
          "basis": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error", "code"],
        "properties": {
          "error": { "type": "string", "example": "Mindrative Institutional Ultra Plan required." },
          "code": { "type": "string", "example": "PLAN_RESTRICTION" },
          "request_id": { "type": "string", "example": "req_8f1b2c4d6e9a" },
          "documentation": { "type": "string", "example": "https://developer.mindrative.com#authentication" }
        }
      }
    }
  }
}