{
  "openapi": "3.1.0",
  "info": {
    "title": "Zip Estate Calculator API",
    "version": "1.0.0",
    "description": "Free, public financial calculator API for real estate investment analysis. No authentication required. Designed for both human users and AI agents.",
    "contact": {
      "name": "Zip Estate",
      "email": "info@zip-estate.com",
      "url": "https://zip-estate.com"
    }
  },
  "servers": [
    {
      "url": "https://zip-estate.com/functions",
      "description": "Production server (server-rendered, no JS required)"
    }
  ],
  "paths": {
    "/calculatorApi": {
      "post": {
        "operationId": "calculatorApi",
        "summary": "Financial Calculator API",
        "description": "Stateless computation API. Supports listing calculators, getting documentation, running calculations, and generating shareable URLs. All actions use the same endpoint with different 'action' values in the request body.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/ListAction"
                  },
                  {
                    "$ref": "#/components/schemas/SkillAction"
                  },
                  {
                    "$ref": "#/components/schemas/ComputeAction"
                  },
                  {
                    "$ref": "#/components/schemas/GenerateUrlAction"
                  }
                ]
              },
              "examples": {
                "list": {
                  "summary": "List all calculators",
                  "value": {
                    "action": "list"
                  }
                },
                "skill": {
                  "summary": "Get real estate calculator docs",
                  "value": {
                    "action": "skill",
                    "calculator": "realestate"
                  }
                },
                "compute": {
                  "summary": "Run a real estate calculation",
                  "value": {
                    "action": "compute",
                    "calculator": "realestate",
                    "inputs": {
                      "purchasePrice": 85000,
                      "monthlyRent": 1100,
                      "belowMarketPercent": 30
                    }
                  }
                },
                "generate_url": {
                  "summary": "Generate shareable link",
                  "value": {
                    "action": "generate_url",
                    "calculator": "realestate",
                    "inputs": {
                      "purchasePrice": 85000,
                      "monthlyRent": 1100
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response. Shape varies by action.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (missing action, unknown calculator, etc.)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/llmsTxt": {
      "get": {
        "operationId": "getLlmsTxt",
        "summary": "llms.txt — AI agent instructions",
        "description": "Returns a Markdown document describing all available tools, API usage, and URL parameter schemas. This is the recommended starting point for AI agent discovery.",
        "responses": {
          "200": {
            "description": "Markdown document",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agentManifest": {
      "get": {
        "operationId": "getAgentManifest",
        "summary": "Agent discovery manifest",
        "description": "Returns a structured JSON manifest of all available tools, API endpoints, and usage instructions.",
        "responses": {
          "200": {
            "description": "JSON manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/openApiJson": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "This OpenAPI specification",
        "description": "Returns this OpenAPI 3.1.0 JSON specification.",
        "responses": {
          "200": {
            "description": "OpenAPI JSON spec",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ListAction": {
        "type": "object",
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "const": "list"
          }
        },
        "description": "List all available calculators with descriptions."
      },
      "SkillAction": {
        "type": "object",
        "required": [
          "action",
          "calculator"
        ],
        "properties": {
          "action": {
            "type": "string",
            "const": "skill"
          },
          "calculator": {
            "type": "string",
            "enum": [
              "realestate",
              "doubling",
              "compound",
              "flip",
              "carwise"
            ],
            "description": "Calculator ID to get documentation for."
          }
        },
        "description": "Get full parameter documentation for a specific calculator."
      },
      "ComputeAction": {
        "type": "object",
        "required": [
          "action",
          "calculator"
        ],
        "properties": {
          "action": {
            "type": "string",
            "const": "compute"
          },
          "calculator": {
            "type": "string",
            "enum": [
              "realestate",
              "doubling",
              "compound",
              "flip"
            ],
            "description": "Calculator ID to run computation for."
          },
          "inputs": {
            "type": "object",
            "description": "Calculator inputs. Omitted values use sensible defaults. Call 'skill' first to see all available parameters."
          }
        },
        "description": "Run a financial calculation and get structured results + Markdown report."
      },
      "GenerateUrlAction": {
        "type": "object",
        "required": [
          "action",
          "calculator"
        ],
        "properties": {
          "action": {
            "type": "string",
            "const": "generate_url"
          },
          "calculator": {
            "type": "string",
            "enum": [
              "realestate",
              "doubling",
              "compound",
              "flip"
            ]
          },
          "inputs": {
            "type": "object",
            "description": "Calculator inputs to encode into the shareable URL."
          }
        },
        "description": "Generate a shareable URL that opens the calculator UI pre-filled with given inputs."
      }
    }
  }
}