{
  "openapi": "3.0.3",
  "info": {
    "title": "X1 Wealth Public API",
    "version": "0.2.0",
    "description": "X1 is a planning and coordination layer. This OpenAPI document exposes public tool endpoints used by the X1 marketing site. Endpoints are intended for first-party use; contact X1 for integration access.",
    "contact": {
      "name": "X1 Wealth",
      "url": "https://x1wealth.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://x1wealth.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "public-tools",
      "description": "Public endpoints used by X1 marketing tools."
    }
  ],
  "paths": {
    "/api/scan": {
      "post": {
        "tags": ["public-tools"],
        "summary": "Execution Gap Scanner",
        "description": "Accepts yes/no answers and returns a score, band, and prescriptions. Intended for first-party web use.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ScannerRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScannerResult" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/cashflow-analyzer/submit": {
      "post": {
        "tags": ["public-tools"],
        "summary": "Cash Flow Analyzer persona",
        "description": "Accepts a short questionnaire and returns a persona summary. Intended for first-party web use.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CashflowAnalyzerRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Persona result",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PersonaResult" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScannerRequest": {
        "type": "object",
        "required": ["answers"],
        "properties": {
          "answers": {
            "type": "object",
            "description": "Answer map keyed by question id (q1..q7) with yes/no values.",
            "properties": {
              "q1": { "$ref": "#/components/schemas/YesNo" },
              "q2": { "$ref": "#/components/schemas/YesNo" },
              "q3": { "$ref": "#/components/schemas/YesNo" },
              "q4": { "$ref": "#/components/schemas/YesNo" },
              "q5": { "$ref": "#/components/schemas/YesNo" },
              "q6": { "$ref": "#/components/schemas/YesNo" },
              "q7": { "$ref": "#/components/schemas/YesNo" }
            },
            "additionalProperties": false
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Optional email address (may be omitted)."
          }
        },
        "additionalProperties": false
      },
      "ScannerResult": {
        "type": "object",
        "required": [
          "score",
          "band",
          "primaryPrescription",
          "secondaryPrescriptions",
          "ctaText"
        ],
        "properties": {
          "score": { "type": "number" },
          "band": { "type": "string" },
          "primaryPrescription": { "type": "string" },
          "secondaryPrescriptions": {
            "type": "array",
            "items": { "type": "string" }
          },
          "ctaText": { "type": "string" }
        },
        "additionalProperties": false
      },
      "CashflowAnalyzerRequest": {
        "type": "object",
        "required": ["answers"],
        "properties": {
          "answers": {
            "type": "object",
            "properties": {
              "incomeSource": {
                "type": "string",
                "enum": ["w2", "biz", "both", "other_income"]
              },
              "primaryFrustrations": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "taxes",
                    "debt_bills",
                    "unused_cash",
                    "investment_confusion",
                    "disorganized",
                    "other_frustration"
                  ]
                }
              },
              "annualIncome": {
                "type": "string",
                "enum": ["<100k", "100k-250k", "250k-500k", "500k+"]
              },
              "hasIdleCash": {
                "type": "string",
                "enum": ["yes_idle", "no_idle", "notsure_idle"]
              },
              "automationLevel": {
                "type": "string",
                "enum": [
                  "autopilot",
                  "some_automation",
                  "mostly_manual",
                  "no_system"
                ]
              },
              "primaryFocus": {
                "type": "string",
                "enum": [
                  "free_cash",
                  "grow_wealth",
                  "get_organized",
                  "all_focus"
                ]
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "PersonaResult": {
        "type": "object",
        "required": [
          "id",
          "name",
          "cashFlowRecoveryRange",
          "summaryTemplate",
          "topWins",
          "ctaPrimary"
        ],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "cashFlowRecoveryRange": { "type": "string" },
          "summaryTemplate": { "type": "string" },
          "topWins": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PersonaWin" }
          },
          "ctaPrimary": { "$ref": "#/components/schemas/PersonaCta" },
          "ctaSecondary": { "$ref": "#/components/schemas/PersonaCta" }
        },
        "additionalProperties": false
      },
      "PersonaWin": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" }
        },
        "additionalProperties": false
      },
      "PersonaCta": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": { "type": "string" },
          "link": { "type": "string" }
        },
        "additionalProperties": false
      },
      "YesNo": {
        "type": "string",
        "enum": ["yes", "no"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "error": { "type": "string" }
        },
        "additionalProperties": true
      }
    }
  }
}