{
  "openapi": "3.1.0",
  "info": {
    "title": "Darbs Quantitative Verification & Market Signal Engine API",
    "version": "1.0.0",
    "description": "Institutional intelligence and multi-factor quantitative verification API for stocks and cryptocurrency markets."
  },
  "servers": [
    {
      "url": "https://darbsignal.com",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 / OpenID Connect authorization with PKCE and client credentials support",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://darbsignal.com/oauth/authorize",
            "tokenUrl": "https://darbsignal.com/oauth/token",
            "scopes": {
              "signals:read": "Read real-time composite Darbs signals and score factors",
              "darkpool:read": "Access real-time dark pool prints and block activity",
              "factor:read": "Access normalized mathematical factor matrices",
              "alerts:write": "Manage automated trade alert webhooks"
            }
          },
          "clientCredentials": {
            "tokenUrl": "https://darbsignal.com/oauth/token",
            "scopes": {
              "signals:read": "Read real-time composite Darbs signals and score factors",
              "darkpool:read": "Access real-time dark pool prints and block activity",
              "factor:read": "Access normalized mathematical factor matrices"
            }
          }
        }
      },
      "openIdConnect": {
        "type": "openIdConnect",
        "openIdConnectUrl": "https://darbsignal.com/.well-known/openid-configuration"
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Engine Health and Security Status",
        "description": "Returns operational status and active rate-limiting / sanitization verification flags.",
        "responses": {
          "200": {
            "description": "Engine operational status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "engine": { "type": "string" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "security": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/apply": {
      "post": {
        "summary": "Request Beta Allotment / Early Access",
        "description": "Registers an institutional or retail trader for queue prioritization. Incoming payloads are strictly validated and sanitized.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email"],
                "properties": {
                  "name": { "type": "string", "example": "Alex Morgan" },
                  "email": { "type": "string", "format": "email", "example": "alex@quantfund.io" },
                  "focus": { "type": "string", "enum": ["retail", "quant", "fund", "general"], "example": "quant" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application successfully validated and seat reserved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "message": { "type": "string" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "name": { "type": "string" },
                        "email": { "type": "string" },
                        "focus": { "type": "string" },
                        "queueToken": { "type": "string", "example": "DRB-7X9P2K" },
                        "registeredAt": { "type": "string", "format": "date-time" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error (invalid email, name, or payload structure)"
          },
          "429": {
            "description": "Rate limit exceeded to protect server infrastructure"
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "summary": "Submit Quantitative Inquiry or Feedback",
        "description": "Safely submits an inquiry to the research team.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "message"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "message": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry successfully recorded"
          },
          "400": {
            "description": "Invalid input or empty message"
          }
        }
      }
    }
  }
}