{
  "openapi": "3.1.0",
  "info": {
    "title": "Raziel Calculators API",
    "version": "1.1.0",
    "summary": "Free investment and startup finance calculators: IRR, XIRR, MOIC, SAFE conversion, dilution, TVPI/DPI, QSBS and more.",
    "description": "Free JSON API for the calculators at https://raziel.co/tools. No API key. Rate limited to 60 requests per minute per IP. Money is in USD (*_usd), percentages are percent numbers (20 = 20%), dates are YYYY-MM-DD. For education only. Not tax, legal or investment advice. Docs and MCP setup: https://raziel.co/developers",
    "contact": {
      "name": "Raziel",
      "url": "https://raziel.co/developers",
      "email": "info@raziel.co"
    },
    "license": {
      "name": "Free to use. Attribution to raziel.co appreciated.",
      "url": "https://raziel.co/developers"
    }
  },
  "servers": [
    {
      "url": "https://raziel.co"
    }
  ],
  "externalDocs": {
    "description": "Developer docs and MCP server",
    "url": "https://raziel.co/developers"
  },
  "tags": [
    {
      "name": "Calculators",
      "description": "Investment and startup finance math"
    },
    {
      "name": "Founder metrics",
      "description": "Startup efficiency and SaaS metrics"
    },
    {
      "name": "Research and reference",
      "description": "Raziel guides, glossary and platform comparisons"
    }
  ],
  "paths": {
    "/api/v1/calculators": {
      "get": {
        "operationId": "listCalculators",
        "summary": "List every calculator",
        "responses": {
          "200": {
            "description": "Calculators",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalculatorList"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/calculators/irr": {
      "post": {
        "operationId": "irr",
        "summary": "IRR calculator",
        "description": "Internal rate of return for evenly spaced yearly cash flows after an initial investment. Use xirr instead when cash flows have specific dates or irregular timing.\n\nInteractive version: https://raziel.co/tools/irr-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "initial_investment_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Amount invested at the start (year 0), as a positive number.",
                    "exclusiveMinimum": 0
                  },
                  "cash_flows_usd": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Net cash flow for each following year, in order (year 1, year 2, ...). Positive = money received, negative = more money invested.",
                    "items": {
                      "type": "number",
                      "description": "Net cash flow for the year in USD."
                    }
                  }
                },
                "required": [
                  "initial_investment_usd",
                  "cash_flows_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "initial_investment_usd": 100000,
                "cash_flows_usd": [
                  10000,
                  25000,
                  30000,
                  40000,
                  50000
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "irr",
                  "result": {
                    "irr_pct": 13.29,
                    "years": 5,
                    "total_invested_usd": 100000,
                    "total_returned_usd": 155000,
                    "net_profit_usd": 55000,
                    "moic": 1.55,
                    "calculator_url": "https://raziel.co/tools/irr-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/xirr": {
      "post": {
        "operationId": "xirr",
        "summary": "XIRR calculator",
        "description": "Annualized return (XIRR) for cash flows on specific dates, like Excel XIRR. Use this for real investments with irregular timing (capital calls, distributions, follow-ons); use irr only for evenly spaced yearly flows.\n\nInteractive version: https://raziel.co/tools/xirr-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cash_flows": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 500,
                    "description": "Dated cash flows in any order. Negative amount = money invested, positive = money received or current value.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string",
                          "format": "date",
                          "description": "Date of the cash flow, YYYY-MM-DD."
                        },
                        "amount_usd": {
                          "type": "number",
                          "description": "Amount in USD. Negative = invested, positive = received."
                        }
                      },
                      "required": [
                        "date",
                        "amount_usd"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "cash_flows"
                ],
                "additionalProperties": false
              },
              "example": {
                "cash_flows": [
                  {
                    "date": "2021-03-01",
                    "amount_usd": -50000
                  },
                  {
                    "date": "2022-06-15",
                    "amount_usd": -25000
                  },
                  {
                    "date": "2025-09-30",
                    "amount_usd": 160000
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "xirr",
                  "result": {
                    "xirr_pct": 19.83,
                    "total_invested_usd": 75000,
                    "total_returned_usd": 160000,
                    "net_profit_usd": 85000,
                    "moic": 2.1333,
                    "years": 4.59,
                    "first_date": "2021-03-01",
                    "last_date": "2025-09-30",
                    "calculator_url": "https://raziel.co/tools/xirr-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/moic": {
      "post": {
        "operationId": "moic",
        "summary": "MOIC calculator",
        "description": "Multiple on invested capital: total value returned (distributions plus current value) divided by the amount invested, with the implied annualized return when a holding period is given. Use tvpi_dpi for fund-level LP multiples.\n\nInteractive version: https://raziel.co/tools/moic-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "invested_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total capital invested, including follow-on checks.",
                    "exclusiveMinimum": 0
                  },
                  "value_returned_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Cash received from exits and distributions plus the current value of anything still held."
                  },
                  "years": {
                    "type": "number",
                    "description": "Holding period in years, used for the annualized return. 0 if unknown.",
                    "minimum": 0,
                    "default": 0
                  }
                },
                "required": [
                  "invested_usd",
                  "value_returned_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "invested_usd": 1000000,
                "value_returned_usd": 2500000,
                "years": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "moic",
                  "result": {
                    "moic": 2.5,
                    "total_return_pct": 150,
                    "annualized_return_pct": 20.11,
                    "net_profit_usd": 1500000,
                    "calculator_url": "https://raziel.co/tools/moic-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/cagr": {
      "post": {
        "operationId": "cagr",
        "summary": "CAGR calculator",
        "description": "Compound annual growth rate between a start value and an end value over a number of years. Use for growth of a single value (revenue, an asset price); use irr or xirr when there are multiple cash flows.\n\nInteractive version: https://raziel.co/tools/cagr-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "start_value_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Value at the start.",
                    "exclusiveMinimum": 0
                  },
                  "end_value_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Value at the end."
                  },
                  "years": {
                    "type": "number",
                    "description": "Number of years between the two values.",
                    "exclusiveMinimum": 0,
                    "maximum": 200
                  }
                },
                "required": [
                  "start_value_usd",
                  "end_value_usd",
                  "years"
                ],
                "additionalProperties": false
              },
              "example": {
                "start_value_usd": 10000,
                "end_value_usd": 25000,
                "years": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "cagr",
                  "result": {
                    "cagr_pct": 20.11,
                    "multiple": 2.5,
                    "total_growth_pct": 150,
                    "gain_usd": 15000,
                    "calculator_url": "https://raziel.co/tools/cagr-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/tvpi_dpi": {
      "post": {
        "operationId": "tvpiDpi",
        "summary": "TVPI and DPI calculator",
        "description": "Fund performance multiples for an LP or a fund: TVPI (total value to paid-in), DPI (distributions to paid-in, realized) and RVPI (NAV to paid-in, unrealized). Use moic for a single deal and xirr for time-weighted returns.\n\nInteractive version: https://raziel.co/tools/tvpi-dpi-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paid_in_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Capital called and contributed to date, including fees.",
                    "exclusiveMinimum": 0
                  },
                  "distributions_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Cumulative cash and stock distributed to date.",
                    "default": 0
                  },
                  "nav_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Latest reported residual value (net asset value).",
                    "default": 0
                  },
                  "commitment_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total commitment, used only for the called percentage. 0 if unknown.",
                    "default": 0
                  }
                },
                "required": [
                  "paid_in_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "paid_in_usd": 10000000,
                "distributions_usd": 3000000,
                "nav_usd": 9000000,
                "commitment_usd": 12500000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "tvpi_dpi",
                  "result": {
                    "tvpi": 1.2,
                    "dpi": 0.3,
                    "rvpi": 0.9,
                    "total_value_usd": 12000000,
                    "gain_usd": 2000000,
                    "share_of_value_realized_pct": 25,
                    "commitment_called_pct": 80,
                    "uncalled_commitment_usd": 2500000,
                    "calculator_url": "https://raziel.co/tools/tvpi-dpi-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/carried_interest": {
      "post": {
        "operationId": "carriedInterest",
        "summary": "Carried interest calculator",
        "description": "European (whole-fund) distribution waterfall: management fees, return of capital, preferred return (hurdle), GP catch-up and carried interest split, with LP net multiple and the gross-to-net drag.\n\nInteractive version: https://raziel.co/tools/carried-interest-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fund_size_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total LP commitments.",
                    "exclusiveMinimum": 0
                  },
                  "management_fee_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Annual management fee on commitments, percent.",
                    "exclusiveMaximum": 100,
                    "default": 2
                  },
                  "fee_years": {
                    "type": "number",
                    "description": "Years the full fee is charged.",
                    "minimum": 0,
                    "maximum": 30,
                    "default": 5
                  },
                  "step_down_fee_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Annual fee after the step-down, percent. 0 for none.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  },
                  "step_down_years": {
                    "type": "number",
                    "description": "Years the step-down fee is charged.",
                    "minimum": 0,
                    "maximum": 30,
                    "default": 0
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "moic",
                      "proceeds"
                    ],
                    "description": "\"moic\" to give a gross multiple on invested capital, \"proceeds\" to give total exit proceeds.",
                    "default": "moic"
                  },
                  "gross_moic": {
                    "type": "number",
                    "description": "Gross multiple on invested capital (mode \"moic\").",
                    "minimum": 0,
                    "default": 3
                  },
                  "proceeds_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total exit proceeds (mode \"proceeds\").",
                    "default": 0
                  },
                  "hurdle_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Preferred return per year, percent. 0 for no hurdle.",
                    "default": 8
                  },
                  "catch_up": {
                    "type": "string",
                    "enum": [
                      "none",
                      "full"
                    ],
                    "description": "GP catch-up after the hurdle.",
                    "default": "full"
                  },
                  "carry_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Carried interest, percent of profits.",
                    "exclusiveMaximum": 100,
                    "default": 20
                  },
                  "years": {
                    "type": "number",
                    "description": "Years from capital call to distribution.",
                    "exclusiveMinimum": 0,
                    "maximum": 30,
                    "default": 10
                  }
                },
                "required": [
                  "fund_size_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "fund_size_usd": 100000000,
                "management_fee_pct": 2,
                "fee_years": 10,
                "mode": "moic",
                "gross_moic": 3,
                "hurdle_pct": 8,
                "catch_up": "full",
                "carry_pct": 20,
                "years": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "carried_interest",
                  "result": {
                    "management_fees_usd": 20000000,
                    "invested_usd": 80000000,
                    "proceeds_usd": 240000000,
                    "gross_moic": 3,
                    "profit_usd": 140000000,
                    "waterfall_usd": {
                      "return_of_capital": 100000000,
                      "preferred_return": 115892499.73,
                      "gp_catch_up": 24107500.27,
                      "split_to_lps": 0,
                      "split_to_gp": 0
                    },
                    "lp_total_usd": 215892499.73,
                    "lp_profit_usd": 115892499.73,
                    "gp_carry_usd": 24107500.27,
                    "lp_net_moic": 2.1589,
                    "gross_to_net_drag": 0.8411,
                    "gp_share_of_profit_pct": 17.22,
                    "gross_irr_pct": 11.61,
                    "lp_net_irr_pct": 8,
                    "calculator_url": "https://raziel.co/tools/carried-interest-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/safe_conversion": {
      "post": {
        "operationId": "safeConversion",
        "summary": "SAFE conversion calculator",
        "description": "How a YC-style SAFE (post-money or pre-money) converts in a priced equity round: conversion price, whether the cap or discount applies, shares issued and ownership after the round, including an option pool top-up. Use convertible_note for notes that accrue interest.\n\nInteractive version: https://raziel.co/tools/safe-conversion-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "safe_type": {
                    "type": "string",
                    "enum": [
                      "post",
                      "pre"
                    ],
                    "description": "SAFE type: \"post\" for post-money SAFEs (the YC standard since 2018), \"pre\" for older pre-money SAFEs.",
                    "default": "post"
                  },
                  "investment_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "SAFE purchase amount.",
                    "exclusiveMinimum": 0
                  },
                  "valuation_cap_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Valuation cap. 0 means no cap.",
                    "default": 0
                  },
                  "discount_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Discount to the round price in percent (20 = 20%). 0 means no discount.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  },
                  "existing_shares": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Fully diluted shares before the priced round, including the unissued option pool.",
                    "exclusiveMinimum": 0
                  },
                  "existing_pool_shares": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Unissued option pool shares today (part of existing_shares).",
                    "default": 0
                  },
                  "priced_round_pre_money_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Pre-money valuation of the priced round.",
                    "exclusiveMinimum": 0
                  },
                  "priced_round_raise_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "New money raised in the priced round, not counting the SAFE.",
                    "default": 0
                  },
                  "target_pool_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Target unissued option pool after the round, as a percent of post-money fully diluted shares. 0 for no top-up.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  }
                },
                "required": [
                  "investment_usd",
                  "existing_shares",
                  "priced_round_pre_money_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "safe_type": "post",
                "investment_usd": 500000,
                "valuation_cap_usd": 8000000,
                "discount_pct": 20,
                "existing_shares": 10000000,
                "existing_pool_shares": 1000000,
                "priced_round_pre_money_usd": 20000000,
                "priced_round_raise_usd": 5000000,
                "target_pool_pct": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "safe_conversion",
                  "result": {
                    "conversion_price_usd": 0.75,
                    "round_price_usd": 1.810345,
                    "cap_price_usd": 0.75,
                    "discount_price_usd": 1.448276,
                    "converts_at": "cap",
                    "safe_shares": 666666.67,
                    "safe_ownership_pct": 4.83,
                    "safe_value_at_round_price_usd": 1206896.55,
                    "safe_multiple": 2.4138,
                    "effective_discount_pct": 58.57,
                    "new_investor_shares": 2761904.76,
                    "pool_top_up_shares": 380952.38,
                    "post_money_usd": 25000000,
                    "post_money_shares": 13809523.81,
                    "cap_table_after_round_pct": {
                      "existing_holders": 65.17,
                      "option_pool": 10,
                      "safe": 4.83,
                      "new_investors": 20
                    },
                    "calculator_url": "https://raziel.co/tools/safe-conversion-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/convertible_note": {
      "post": {
        "operationId": "convertibleNote",
        "summary": "Convertible note calculator",
        "description": "How a convertible note converts in a priced round: accrued interest, conversion price (cap vs discount), shares received and effective discount. Use safe_conversion for SAFEs, which have no interest.\n\nInteractive version: https://raziel.co/tools/convertible-note-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "principal_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Note principal.",
                    "exclusiveMinimum": 0
                  },
                  "interest_rate_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Annual interest rate in percent (6 = 6%).",
                    "default": 0
                  },
                  "interest_mode": {
                    "type": "string",
                    "enum": [
                      "simple",
                      "annual",
                      "monthly"
                    ],
                    "description": "How interest accrues: simple, compounded annually, or compounded monthly.",
                    "default": "simple"
                  },
                  "years": {
                    "type": "number",
                    "description": "Years from issue to conversion.",
                    "minimum": 0,
                    "default": 0
                  },
                  "valuation_cap_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Valuation cap. 0 means no cap.",
                    "default": 0
                  },
                  "discount_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Discount to the round price in percent. 0 means no discount.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  },
                  "priced_round_pre_money_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Pre-money valuation of the priced round.",
                    "exclusiveMinimum": 0
                  },
                  "round_price_per_share_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Price per share paid by new investors in the round.",
                    "exclusiveMinimum": 0
                  }
                },
                "required": [
                  "principal_usd",
                  "priced_round_pre_money_usd",
                  "round_price_per_share_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "principal_usd": 250000,
                "interest_rate_pct": 6,
                "interest_mode": "simple",
                "years": 1.5,
                "valuation_cap_usd": 6000000,
                "discount_pct": 20,
                "priced_round_pre_money_usd": 15000000,
                "round_price_per_share_usd": 1.5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "convertible_note",
                  "result": {
                    "accrued_interest_usd": 22500,
                    "converting_amount_usd": 272500,
                    "conversion_price_usd": 0.6,
                    "converts_at": "cap",
                    "cap_price_usd": 0.6,
                    "discount_price_usd": 1.2,
                    "shares": 454166.67,
                    "effective_price_per_share_usd": 0.550459,
                    "effective_discount_pct": 63.3,
                    "value_at_round_price_usd": 681250,
                    "multiple_on_principal": 2.725,
                    "calculator_url": "https://raziel.co/tools/convertible-note-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/startup_valuation": {
      "post": {
        "operationId": "startupValuation",
        "summary": "Startup valuation calculator",
        "description": "Pre-money to post-money for a single priced round: post-money valuation, price per share, new shares issued, investor ownership (investment / post-money) and founder dilution. Use dilution for several rounds and option_pool for pool math.\n\nInteractive version: https://raziel.co/tools/startup-valuation-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pre_money_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Pre-money valuation.",
                    "exclusiveMinimum": 0
                  },
                  "investment_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Amount invested in the round.",
                    "exclusiveMinimum": 0
                  },
                  "shares_before": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Fully diluted shares before the round.",
                    "exclusiveMinimum": 0
                  },
                  "option_pool_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 30,
                    "description": "Option pool after the round, percent (taken from the founders’ share).",
                    "default": 0
                  }
                },
                "required": [
                  "pre_money_usd",
                  "investment_usd",
                  "shares_before"
                ],
                "additionalProperties": false
              },
              "example": {
                "pre_money_usd": 5000000,
                "investment_usd": 1000000,
                "shares_before": 10000000,
                "option_pool_pct": 10
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "startup_valuation",
                  "result": {
                    "post_money_usd": 6000000,
                    "price_per_share_usd": 0.5,
                    "new_shares": 2000000,
                    "total_shares_after": 12000000,
                    "investor_ownership_pct": 16.67,
                    "founders_ownership_pct": 73.33,
                    "option_pool_pct": 10,
                    "founder_dilution_pct": 16.67,
                    "calculator_url": "https://raziel.co/tools/startup-valuation-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/dilution": {
      "post": {
        "operationId": "dilution",
        "summary": "Startup dilution calculator",
        "description": "Founder and investor ownership across several future funding rounds, including option pool top-ups before each round. Use option_pool for a single round when the question is how a pre-money pool shifts value, and startup_valuation for one simple round.\n\nInteractive version: https://raziel.co/tools/dilution-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "founders_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Founders’ combined ownership today, percent of fully diluted shares.",
                    "exclusiveMinimum": 0
                  },
                  "option_pool_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Unissued option pool today, percent of fully diluted shares. Anything not founders or pool is treated as existing investors.",
                    "default": 0
                  },
                  "rounds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "Future rounds in order.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 60,
                          "description": "Round label, e.g. \"Seed\" or \"Series A\".",
                          "default": ""
                        },
                        "raise_usd": {
                          "type": "number",
                          "minimum": 0,
                          "description": "New money raised in the round.",
                          "exclusiveMinimum": 0
                        },
                        "pre_money_usd": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Pre-money valuation of the round.",
                          "exclusiveMinimum": 0
                        },
                        "target_pool_pct": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100,
                          "description": "Target unissued pool after the round, percent of post-money. 0 for no top-up.",
                          "exclusiveMaximum": 100,
                          "default": 0
                        }
                      },
                      "required": [
                        "raise_usd",
                        "pre_money_usd"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "founders_pct",
                  "rounds"
                ],
                "additionalProperties": false
              },
              "example": {
                "founders_pct": 90,
                "option_pool_pct": 10,
                "rounds": [
                  {
                    "name": "Seed",
                    "raise_usd": 3000000,
                    "pre_money_usd": 12000000,
                    "target_pool_pct": 10
                  },
                  {
                    "name": "Series A",
                    "raise_usd": 12000000,
                    "pre_money_usd": 48000000,
                    "target_pool_pct": 12
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "dilution",
                  "result": {
                    "final_founders_pct": 52.89,
                    "founder_points_lost": 37.11,
                    "founder_relative_dilution_pct": 41.23,
                    "final_post_money_usd": 60000000,
                    "founders_stake_value_usd": 31733333.33,
                    "stages": [
                      {
                        "label": "Today",
                        "post_money_usd": null,
                        "founders_pct": 90,
                        "option_pool_pct": 10,
                        "earlier_investors_pct": 0,
                        "round_investors_pct": [],
                        "pool_top_up_pct": 0
                      },
                      {
                        "label": "Seed",
                        "post_money_usd": 15000000,
                        "founders_pct": 70,
                        "option_pool_pct": 10,
                        "earlier_investors_pct": 0,
                        "round_investors_pct": [
                          20
                        ],
                        "pool_top_up_pct": 2.22
                      },
                      {
                        "label": "Series A",
                        "post_money_usd": 60000000,
                        "founders_pct": 52.89,
                        "option_pool_pct": 12,
                        "earlier_investors_pct": 0,
                        "round_investors_pct": [
                          15.11,
                          20
                        ],
                        "pool_top_up_pct": 4.44
                      }
                    ],
                    "calculator_url": "https://raziel.co/tools/dilution-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/option_pool": {
      "post": {
        "operationId": "optionPool",
        "summary": "Option pool calculator",
        "description": "The \"option pool shuffle\" for one round: how much the pool must grow to hit a post-money target, the effective pre-money valuation, and how much founder ownership the pre-money pool costs versus adding it after the round.\n\nInteractive version: https://raziel.co/tools/option-pool-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pre_money_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Headline pre-money valuation.",
                    "exclusiveMinimum": 0
                  },
                  "raise_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "New money raised in the round."
                  },
                  "target_pool_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Target unissued pool after the round, percent of post-money.",
                    "exclusiveMaximum": 100
                  },
                  "existing_pool_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Unissued pool today, percent of pre-round fully diluted shares.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  },
                  "founders_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Founders today, percent of pre-round fully diluted shares.",
                    "default": 100
                  },
                  "fully_diluted_shares": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Fully diluted shares today. Optional; enables per-share outputs.",
                    "default": 0
                  }
                },
                "required": [
                  "pre_money_usd",
                  "raise_usd",
                  "target_pool_pct"
                ],
                "additionalProperties": false
              },
              "example": {
                "pre_money_usd": 16000000,
                "raise_usd": 4000000,
                "target_pool_pct": 15,
                "existing_pool_pct": 5,
                "founders_pct": 85,
                "fully_diluted_shares": 10000000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "option_pool",
                  "result": {
                    "post_money_usd": 20000000,
                    "investor_ownership_pct": 20,
                    "pool_top_up_pct": 11,
                    "pool_top_up_value_usd": 2200000,
                    "effective_pre_money_usd": 13800000,
                    "effective_to_headline_ratio": 0.8625,
                    "pool_after_pct": 15,
                    "founders_after_pct": 58.16,
                    "founders_if_no_top_up_pct": 68,
                    "founders_if_pool_added_post_money_pct": 60.21,
                    "founder_points_cost_of_pre_money_pool": 9.84,
                    "round_price_per_share_usd": 1.38,
                    "headline_price_per_share_usd": 1.6,
                    "new_pool_shares": 1594202.9,
                    "ownership_after_round_pct": {
                      "founders": 58.16,
                      "other_holders": 6.84,
                      "option_pool": 15,
                      "new_investors": 20
                    },
                    "calculator_url": "https://raziel.co/tools/option-pool-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/pro_rata": {
      "post": {
        "operationId": "proRata",
        "summary": "Pro rata calculator",
        "description": "For an existing investor in a new round: the check needed to keep the same ownership (pro rata), ownership after the round if they skip or write a planned check, and the value of the stake at the new post-money.\n\nInteractive version: https://raziel.co/tools/pro-rata-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "current_ownership_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Your current fully diluted ownership in percent.",
                    "exclusiveMinimum": 0,
                    "exclusiveMaximum": 100
                  },
                  "round_raise_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total new money raised in the round, including pro rata checks."
                  },
                  "post_money_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Post-money valuation of the round.",
                    "exclusiveMinimum": 0
                  },
                  "planned_check_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "The check you plan to write. 0 to only see the pro rata amount.",
                    "default": 0
                  }
                },
                "required": [
                  "current_ownership_pct",
                  "round_raise_usd",
                  "post_money_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "current_ownership_pct": 2,
                "round_raise_usd": 10000000,
                "post_money_usd": 50000000,
                "planned_check_usd": 100000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "pro_rata",
                  "result": {
                    "pro_rata_check_usd": 200000,
                    "pre_money_usd": 40000000,
                    "round_sells_pct": 20,
                    "ownership_if_skip_pct": 1.6,
                    "ownership_with_planned_check_pct": 1.8,
                    "planned_check_share_of_pro_rata_pct": 50,
                    "points_lost_if_skip": 0.4,
                    "stake_value_if_skip_usd": 800000,
                    "stake_value_with_check_usd": 900000,
                    "calculator_url": "https://raziel.co/tools/pro-rata-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/liquidation_preference": {
      "post": {
        "operationId": "liquidationPreference",
        "summary": "Liquidation preference calculator",
        "description": "Exit waterfall: how sale proceeds split between preferred series and common, with preference multiples, non-participating, participating or capped participation, and stacked or pari passu seniority. Each series converts to common when that pays more.\n\nInteractive version: https://raziel.co/tools/liquidation-preference-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "exit_value_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Net proceeds to equity holders at the exit."
                  },
                  "common_shares": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Common shares outstanding, including exercised options (fully diluted common)."
                  },
                  "seniority": {
                    "type": "string",
                    "enum": [
                      "stacked",
                      "pari"
                    ],
                    "description": "\"stacked\": later series are paid first (listed last = most senior). \"pari\": all series share preferences pro rata.",
                    "default": "stacked"
                  },
                  "series": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "description": "Preferred series, oldest first.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 60,
                          "description": "Series name, e.g. \"Series A\".",
                          "default": ""
                        },
                        "invested_usd": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Amount the series invested."
                        },
                        "shares": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Preferred shares (convert 1:1 into common)."
                        },
                        "preference_multiple": {
                          "type": "number",
                          "description": "Liquidation preference multiple (1 = 1x).",
                          "minimum": 0,
                          "maximum": 10,
                          "default": 1
                        },
                        "participation": {
                          "type": "string",
                          "enum": [
                            "none",
                            "full",
                            "capped"
                          ],
                          "description": "Non-participating, fully participating, or participating up to a cap.",
                          "default": "none"
                        },
                        "participation_cap_multiple": {
                          "type": "number",
                          "description": "Capped participation only: total payout cap as a multiple of the amount invested (3 = 3x).",
                          "minimum": 0,
                          "default": 3
                        }
                      },
                      "required": [
                        "invested_usd",
                        "shares"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "exit_value_usd",
                  "common_shares",
                  "series"
                ],
                "additionalProperties": false
              },
              "example": {
                "exit_value_usd": 60000000,
                "common_shares": 10000000,
                "seniority": "stacked",
                "series": [
                  {
                    "name": "Seed",
                    "invested_usd": 3000000,
                    "shares": 2000000,
                    "preference_multiple": 1,
                    "participation": "none"
                  },
                  {
                    "name": "Series A",
                    "invested_usd": 15000000,
                    "shares": 4000000,
                    "preference_multiple": 1,
                    "participation": "capped",
                    "participation_cap_multiple": 3
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "liquidation_preference",
                  "result": {
                    "series": [
                      {
                        "name": "Seed",
                        "choice": "converts",
                        "preference_usd": 0,
                        "participation_usd": 5625000,
                        "total_usd": 5625000,
                        "per_share_usd": 2.8125,
                        "multiple_on_invested": 1.875,
                        "share_of_exit_pct": 9.38
                      },
                      {
                        "name": "Series A",
                        "choice": "participates",
                        "preference_usd": 15000000,
                        "participation_usd": 11250000,
                        "total_usd": 26250000,
                        "per_share_usd": 6.5625,
                        "multiple_on_invested": 1.75,
                        "share_of_exit_pct": 43.75
                      }
                    ],
                    "common": {
                      "name": "Common",
                      "choice": "common",
                      "preference_usd": 0,
                      "participation_usd": 28125000,
                      "total_usd": 28125000,
                      "per_share_usd": 2.8125,
                      "multiple_on_invested": null,
                      "share_of_exit_pct": 46.88
                    },
                    "total_preference_usd": 18000000,
                    "unallocated_usd": 0,
                    "total_shares": 16000000,
                    "calculator_url": "https://raziel.co/tools/liquidation-preference-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/secondary_sale": {
      "post": {
        "operationId": "secondarySale",
        "summary": "Secondary sale calculator",
        "description": "Proceeds from selling private company shares on the secondary market: sale price after a discount (or premium) to the last round price or a valuation, fees, net proceeds, gain over cost basis and the implied company valuation.\n\nInteractive version: https://raziel.co/tools/secondary-sale-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shares_sold": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Number of shares sold.",
                    "exclusiveMinimum": 0
                  },
                  "price_basis": {
                    "type": "string",
                    "enum": [
                      "price",
                      "valuation"
                    ],
                    "description": "\"price\": reference is the last preferred price per share. \"valuation\": reference is a company valuation divided by fully diluted shares.",
                    "default": "price"
                  },
                  "reference_price_per_share_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Last preferred price per share (price basis).",
                    "default": 0
                  },
                  "company_valuation_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Company valuation (valuation basis).",
                    "default": 0
                  },
                  "fully_diluted_shares": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Company fully diluted shares. Required for the valuation basis; optional otherwise.",
                    "default": 0
                  },
                  "discount_pct": {
                    "type": "number",
                    "description": "Discount to the reference price, percent. Negative for a premium.",
                    "minimum": -100,
                    "exclusiveMaximum": 100,
                    "default": 0
                  },
                  "cost_basis_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Total cost basis of the shares sold.",
                    "default": 0
                  },
                  "fees_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Broker or platform fees, percent of gross proceeds.",
                    "exclusiveMaximum": 100,
                    "default": 0
                  }
                },
                "required": [
                  "shares_sold"
                ],
                "additionalProperties": false
              },
              "example": {
                "shares_sold": 50000,
                "price_basis": "price",
                "reference_price_per_share_usd": 12,
                "fully_diluted_shares": 40000000,
                "discount_pct": 25,
                "cost_basis_usd": 50000,
                "fees_pct": 3
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "secondary_sale",
                  "result": {
                    "sale_price_per_share_usd": 9,
                    "reference_price_per_share_usd": 12,
                    "gross_proceeds_usd": 450000,
                    "fees_usd": 13500,
                    "net_proceeds_usd": 436500,
                    "gain_usd": 386500,
                    "multiple_on_cost": 8.73,
                    "implied_valuation_usd": 360000000,
                    "stake_sold_pct": 0.125,
                    "discount_cost_usd": 150000,
                    "calculator_url": "https://raziel.co/tools/secondary-sale-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/qsbs": {
      "post": {
        "operationId": "qsbs",
        "summary": "QSBS (Section 1202) calculator",
        "description": "Estimates the US federal capital gains exclusion for qualified small business stock under IRC Section 1202, including the July 2025 changes (tiered 3, 4 and 5 year exclusions and the $15M cap for stock acquired after July 4, 2025). Assumes the stock otherwise qualifies.\n\nInteractive version: https://raziel.co/tools/qsbs-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "acquired_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Date the stock was acquired (YYYY-MM-DD)."
                  },
                  "sold_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Date the stock is or will be sold (YYYY-MM-DD)."
                  },
                  "basis_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Adjusted basis of the shares sold."
                  },
                  "proceeds_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Sale proceeds.",
                    "exclusiveMinimum": 0
                  },
                  "prior_gain_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Gain from the same company already excluded in earlier years.",
                    "default": 0
                  }
                },
                "required": [
                  "acquired_date",
                  "sold_date",
                  "basis_usd",
                  "proceeds_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "acquired_date": "2020-06-01",
                "sold_date": "2026-06-15",
                "basis_usd": 100000,
                "proceeds_usd": 12000000,
                "prior_gain_usd": 0
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "qsbs",
                  "result": {
                    "rules": "acquired 1993-08-11 to 2025-07-04",
                    "days_held": 2205,
                    "full_years_held": 6,
                    "exclusion_pct": 100,
                    "max_exclusion_pct": 100,
                    "next_milestone": null,
                    "gain_usd": 11900000,
                    "cap_usd": 10000000,
                    "cap_source": "dollar cap",
                    "eligible_gain_usd": 10000000,
                    "excluded_gain_usd": 10000000,
                    "taxable_gain_usd": 1900000,
                    "disclaimer": "Estimate only. Assumes the stock meets every other Section 1202 requirement. Confirm with a tax advisor.",
                    "calculator_url": "https://raziel.co/tools/qsbs-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/tax_deadlines": {
      "post": {
        "operationId": "taxDeadlines",
        "summary": "83(b) and QSBS date calculator",
        "description": "Key US equity tax dates. stock_grant_date: the 83(b) election deadline, 30 days after restricted stock is transferred (rolled to the next business day when the 30th day is a weekend or legal holiday). qsbs_acquired_date: the Section 1202 holding-period milestones (50%, 75% and 100% exclusion at 3, 4 and 5 years for stock acquired after July 4, 2025; 5 years before). Give either or both. Use qsbs for the dollar exclusion on a sale.\n\nInteractive version: https://raziel.co/tools/qsbs-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stock_grant_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Date the restricted stock was transferred or granted (YYYY-MM-DD), for the 83(b) deadline."
                  },
                  "qsbs_acquired_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Date the stock was acquired (YYYY-MM-DD), for QSBS holding-period dates."
                  },
                  "as_of_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Count days from this date (YYYY-MM-DD). Defaults to today (UTC)."
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "example": {
                "stock_grant_date": "2026-11-02",
                "qsbs_acquired_date": "2025-09-01",
                "as_of_date": "2026-11-02"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "tax_deadlines",
                  "result": {
                    "as_of_date": "2026-11-02",
                    "election_83b": {
                      "transfer_date": "2026-11-02",
                      "thirtieth_day": "2026-12-02",
                      "deadline": "2026-12-02",
                      "rolled_to_next_business_day": false,
                      "days_left": 30,
                      "status": "open",
                      "how_to_file": "Mail a signed 83(b) election (IRS Form 15620 or a written statement) to the IRS office where you file your return, postmarked by the deadline. Use certified mail with a return receipt and give a copy to the company.",
                      "learn_url": "https://raziel.co/learn/83b-election-tracking"
                    },
                    "qsbs": {
                      "rules": "acquired after 2025-07-04: 50% after 3 years, 75% after 4, 100% after 5",
                      "milestones": [
                        {
                          "years": 3,
                          "exclusion_pct": 50,
                          "date": "2028-09-02",
                          "met": false
                        },
                        {
                          "years": 4,
                          "exclusion_pct": 75,
                          "date": "2029-09-02",
                          "met": false
                        },
                        {
                          "years": 5,
                          "exclusion_pct": 100,
                          "date": "2030-09-02",
                          "met": false
                        }
                      ],
                      "next_milestone": {
                        "years": 3,
                        "exclusion_pct": 50,
                        "date": "2028-09-02",
                        "days_left": 670
                      },
                      "learn_url": "https://raziel.co/learn/qsbs-holding-period-tracker"
                    },
                    "note": "A threshold counts as met the day after the anniversary. Assumes the stock otherwise qualifies. Education only, not tax advice; confirm dates with a tax advisor.",
                    "calculator_url": "https://raziel.co/tools/qsbs-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/runway": {
      "post": {
        "operationId": "runway",
        "summary": "Startup runway calculator",
        "description": "Months of cash runway for a startup, either from a monthly net burn (\"burn\" mode) or from monthly revenue and expenses with growth rates (\"pl\" mode), including the break-even month and whether the company is default alive within 10 years.\n\nInteractive version: https://raziel.co/tools/runway-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cash_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Cash in the bank today.",
                    "exclusiveMinimum": 0
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "burn",
                      "pl"
                    ],
                    "description": "\"burn\": give monthly net burn. \"pl\": give monthly revenue and expenses.",
                    "default": "burn"
                  },
                  "monthly_burn_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Burn mode: monthly net burn (cash out minus cash in).",
                    "default": 0
                  },
                  "burn_growth_pct": {
                    "type": "number",
                    "description": "Burn mode: month-over-month change in burn, percent (2 = +2% a month).",
                    "exclusiveMinimum": -100,
                    "default": 0
                  },
                  "monthly_revenue_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "P&L mode: monthly revenue today.",
                    "default": 0
                  },
                  "revenue_growth_pct": {
                    "type": "number",
                    "description": "P&L mode: month-over-month revenue growth, percent.",
                    "exclusiveMinimum": -100,
                    "default": 0
                  },
                  "monthly_expenses_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "P&L mode: monthly expenses today.",
                    "default": 0
                  },
                  "expense_growth_pct": {
                    "type": "number",
                    "description": "P&L mode: month-over-month expense growth, percent.",
                    "exclusiveMinimum": -100,
                    "default": 0
                  }
                },
                "required": [
                  "cash_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "cash_usd": 2000000,
                "mode": "pl",
                "monthly_revenue_usd": 60000,
                "revenue_growth_pct": 8,
                "monthly_expenses_usd": 180000,
                "expense_growth_pct": 2
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "runway",
                  "result": {
                    "runway_months": null,
                    "default_alive": true,
                    "net_cash_flow_month_1_usd": -120000,
                    "break_even_month": 21,
                    "lowest_cash_usd": 372191.29,
                    "horizon_months": 120,
                    "note": "Cash does not run out within 120 months at these assumptions.",
                    "calculator_url": "https://raziel.co/tools/runway-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/cap_rate": {
      "post": {
        "operationId": "capRate",
        "summary": "Cap rate calculator",
        "description": "Capitalization rate of an income property (net operating income / property value), plus gross rent multiplier and price per unit. Give noi_usd directly or gross income and operating expenses. Use cash_on_cash when financing matters.\n\nInteractive version: https://raziel.co/tools/cap-rate-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "property_value_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Purchase price or current market value.",
                    "exclusiveMinimum": 0
                  },
                  "noi_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Annual net operating income. If omitted, gross income minus operating expenses is used."
                  },
                  "gross_income_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Annual gross rental income.",
                    "default": 0
                  },
                  "operating_expenses_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Annual operating expenses, excluding mortgage payments.",
                    "default": 0
                  },
                  "units": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Number of units, for price per unit. 0 to skip.",
                    "default": 0
                  }
                },
                "required": [
                  "property_value_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "property_value_usd": 500000,
                "gross_income_usd": 70000,
                "operating_expenses_usd": 20000,
                "units": 4
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "cap_rate",
                  "result": {
                    "cap_rate_pct": 10,
                    "noi_usd": 50000,
                    "noi_per_month_usd": 4166.67,
                    "gross_rent_multiplier": 7.14,
                    "price_per_unit_usd": 125000,
                    "expense_ratio_pct": 28.57,
                    "calculator_url": "https://raziel.co/tools/cap-rate-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/cash_on_cash": {
      "post": {
        "operationId": "cashOnCash",
        "summary": "Cash on cash return calculator",
        "description": "Leveraged rental property returns: mortgage payment, NOI, annual cash flow, cash on cash return, DSCR and break-even occupancy. Use cap_rate for an unlevered view of the same property.\n\nInteractive version: https://raziel.co/tools/cash-on-cash-return-calculator",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "price_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Purchase price.",
                    "exclusiveMinimum": 0
                  },
                  "down_payment_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Down payment as a percent of price.",
                    "default": 25
                  },
                  "closing_costs_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Closing costs and upfront repairs paid in cash.",
                    "default": 0
                  },
                  "monthly_rent_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Gross monthly rent across all units."
                  },
                  "vacancy_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Vacancy and credit loss, percent of gross rent.",
                    "default": 5
                  },
                  "operating_expenses_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Annual operating expenses: taxes, insurance, repairs, management, HOA.",
                    "default": 0
                  },
                  "interest_rate_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Mortgage interest rate, percent per year.",
                    "default": 7
                  },
                  "loan_term_years": {
                    "type": "number",
                    "description": "Mortgage term in years.",
                    "minimum": 0,
                    "maximum": 50,
                    "default": 30
                  }
                },
                "required": [
                  "price_usd",
                  "monthly_rent_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "price_usd": 400000,
                "down_payment_pct": 25,
                "closing_costs_usd": 12000,
                "monthly_rent_usd": 3200,
                "vacancy_pct": 5,
                "operating_expenses_usd": 9000,
                "interest_rate_pct": 7,
                "loan_term_years": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "cash_on_cash",
                  "result": {
                    "cash_on_cash_pct": 3.15,
                    "annual_cash_flow_usd": 3529.11,
                    "monthly_cash_flow_usd": 294.09,
                    "cash_invested_usd": 112000,
                    "loan_usd": 300000,
                    "monthly_mortgage_payment_usd": 1995.91,
                    "annual_debt_service_usd": 23950.89,
                    "noi_usd": 27480,
                    "cap_rate_pct": 6.87,
                    "dscr": 1.15,
                    "break_even_occupancy_pct": 85.81,
                    "principal_paid_year_1_usd": 3047.43,
                    "calculator_url": "https://raziel.co/tools/cash-on-cash-return-calculator"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/portfolio_allocation": {
      "post": {
        "operationId": "portfolioAllocation",
        "summary": "Portfolio allocation analyzer",
        "description": "Allocation of a portfolio across asset classes (stocks, bonds, real estate, crypto, venture capital, private equity, cash, other), with a simple diversification score and a concentration read. Holdings in the same class are summed.\n\nInteractive version: https://raziel.co/tools/portfolio-allocation",
        "tags": [
          "Calculators"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "holdings": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "description": "Each holding with its asset class and current value.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 100,
                          "description": "Holding name.",
                          "default": ""
                        },
                        "asset_class": {
                          "type": "string",
                          "enum": [
                            "Stocks",
                            "Bonds",
                            "Real Estate",
                            "Crypto",
                            "Venture Capital",
                            "Private Equity",
                            "Cash",
                            "Other"
                          ],
                          "description": "Asset class."
                        },
                        "value_usd": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Current value."
                        }
                      },
                      "required": [
                        "asset_class",
                        "value_usd"
                      ],
                      "additionalProperties": false
                    }
                  }
                },
                "required": [
                  "holdings"
                ],
                "additionalProperties": false
              },
              "example": {
                "holdings": [
                  {
                    "name": "S&P 500 Index",
                    "asset_class": "Stocks",
                    "value_usd": 150000
                  },
                  {
                    "name": "Bitcoin",
                    "asset_class": "Crypto",
                    "value_usd": 25000
                  },
                  {
                    "name": "Rental Property",
                    "asset_class": "Real Estate",
                    "value_usd": 200000
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "portfolio_allocation",
                  "result": {
                    "total_value_usd": 375000,
                    "asset_classes_held": 3,
                    "asset_classes_available": 8,
                    "diversification_score": 37.5,
                    "largest_class": "Real Estate",
                    "alternatives_share_pct": 60,
                    "allocation": [
                      {
                        "asset_class": "Real Estate",
                        "value_usd": 200000,
                        "share_pct": 53.33
                      },
                      {
                        "asset_class": "Stocks",
                        "value_usd": 150000,
                        "share_pct": 40
                      },
                      {
                        "asset_class": "Crypto",
                        "value_usd": 25000,
                        "share_pct": 6.67
                      }
                    ],
                    "assessment": "Good diversification across 3 asset classes. This provides reasonable protection against market volatility.",
                    "calculator_url": "https://raziel.co/tools/portfolio-allocation"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/burn_multiple": {
      "post": {
        "operationId": "burnMultiple",
        "summary": "Burn multiple",
        "description": "Capital efficiency: net burn divided by net new ARR over the same period (a quarter or a year). Lower is better. Returns the multiple and a rough band (under 1 amazing, 1 to 1.5 great, 1.5 to 2 good, 2 to 3 suspect, over 3 bad, a rule of thumb popularized by David Sacks). Use rule_of_40 for growth versus profitability instead.\n\nGuide: https://raziel.co/learn/importance-startup-burn-rate",
        "tags": [
          "Founder metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "net_burn_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Net cash burned in the period (cash out minus cash in), as a positive number."
                  },
                  "net_new_arr_usd": {
                    "type": "number",
                    "description": "Net new annual recurring revenue added in the same period (new + expansion - churn). Can be negative."
                  }
                },
                "required": [
                  "net_burn_usd",
                  "net_new_arr_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "net_burn_usd": 2000000,
                "net_new_arr_usd": 1600000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "burn_multiple",
                  "result": {
                    "burn_multiple": 1.25,
                    "rating": "great",
                    "note": "Rough guide: under 1 amazing, 1 to 1.5 great, 1.5 to 2 good, 2 to 3 suspect, over 3 bad. Benchmarks vary by stage.",
                    "guide_url": "https://raziel.co/learn/importance-startup-burn-rate"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/rule_of_40": {
      "post": {
        "operationId": "ruleOf_40",
        "summary": "Rule of 40",
        "description": "Adds revenue growth rate and profit margin (usually EBITDA or free cash flow margin, both in percent). A score of 40 or more is the common rule of thumb for a healthy software company balancing growth and profitability. Use burn_multiple for capital efficiency instead.\n\nGuide: https://raziel.co/learn/startup-traction-analysis-metrics",
        "tags": [
          "Founder metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "revenue_growth_pct": {
                    "type": "number",
                    "description": "Year-over-year revenue growth in percent (60 = 60%). Can be negative.",
                    "minimum": -100
                  },
                  "profit_margin_pct": {
                    "type": "number",
                    "description": "Profit margin in percent, EBITDA or free cash flow margin (-15 = -15%).",
                    "minimum": -1000,
                    "maximum": 100
                  }
                },
                "required": [
                  "revenue_growth_pct",
                  "profit_margin_pct"
                ],
                "additionalProperties": false
              },
              "example": {
                "revenue_growth_pct": 60,
                "profit_margin_pct": -15
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "rule_of_40",
                  "result": {
                    "score_pct": 45,
                    "passes": true,
                    "points_vs_40": 5,
                    "guide_url": "https://raziel.co/learn/startup-traction-analysis-metrics"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/ltv_cac": {
      "post": {
        "operationId": "ltvCac",
        "summary": "LTV to CAC",
        "description": "Customer lifetime value (monthly revenue per account x gross margin / monthly churn) compared with customer acquisition cost. Returns LTV, the LTV:CAC ratio and CAC payback months. Around 3:1 or better is a commonly cited target. Use cac_payback when you only need the payback period.\n\nGuide: https://raziel.co/learn/unit-economics-early-stage-startups",
        "tags": [
          "Founder metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "arpa_monthly_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Average revenue per account per month.",
                    "exclusiveMinimum": 0
                  },
                  "gross_margin_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Gross margin in percent (80 = 80%)."
                  },
                  "monthly_churn_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Monthly customer churn in percent (2 = 2%). Must be above 0.",
                    "exclusiveMinimum": 0
                  },
                  "cac_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Fully loaded cost to acquire one customer (sales and marketing spend / new customers)."
                  }
                },
                "required": [
                  "arpa_monthly_usd",
                  "gross_margin_pct",
                  "monthly_churn_pct",
                  "cac_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "arpa_monthly_usd": 500,
                "gross_margin_pct": 80,
                "monthly_churn_pct": 2,
                "cac_usd": 6000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "ltv_cac",
                  "result": {
                    "ltv_usd": 20000,
                    "ltv_to_cac": 3.33,
                    "cac_payback_months": 15,
                    "monthly_gross_profit_per_account_usd": 400,
                    "expected_lifetime_months": 50,
                    "note": "Rough guide: about 3:1 or better is a common target. Simple model with constant churn and no discounting.",
                    "guide_url": "https://raziel.co/learn/unit-economics-early-stage-startups"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/cac_payback": {
      "post": {
        "operationId": "cacPayback",
        "summary": "CAC payback period",
        "description": "Months of gross profit needed to earn back the cost of acquiring a customer: CAC / (monthly revenue per account x gross margin). Give cac_usd directly, or sales_marketing_spend_usd and new_customers for the same period. Many SaaS investors look for roughly 12 to 18 months or less, shorter for SMB. Use ltv_cac to also see lifetime value.\n\nGuide: https://raziel.co/learn/unit-economics-early-stage-startups",
        "tags": [
          "Founder metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cac_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Cost to acquire one customer. Optional if spend and new customers are given."
                  },
                  "sales_marketing_spend_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Sales and marketing spend in the period (used with new_customers when cac_usd is not given)."
                  },
                  "new_customers": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "New customers won in the same period."
                  },
                  "arpa_monthly_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Average revenue per account per month.",
                    "exclusiveMinimum": 0
                  },
                  "gross_margin_pct": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Gross margin in percent (80 = 80%).",
                    "exclusiveMinimum": 0
                  }
                },
                "required": [
                  "arpa_monthly_usd",
                  "gross_margin_pct"
                ],
                "additionalProperties": false
              },
              "example": {
                "sales_marketing_spend_usd": 300000,
                "new_customers": 50,
                "arpa_monthly_usd": 500,
                "gross_margin_pct": 80
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "cac_payback",
                  "result": {
                    "cac_usd": 6000,
                    "payback_months": 15,
                    "monthly_gross_profit_per_account_usd": 400,
                    "guide_url": "https://raziel.co/learn/unit-economics-early-stage-startups"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/calculators/net_revenue_retention": {
      "post": {
        "operationId": "netRevenueRetention",
        "summary": "Net and gross revenue retention",
        "description": "Net revenue retention (NRR) and gross revenue retention (GRR) for a cohort of existing customers over a period, usually 12 months: (starting revenue + expansion - contraction - churn) / starting revenue. Above 100% NRR means existing customers grow on their own. Exclude revenue from new customers.\n\nGuide: https://raziel.co/learn/evaluating-startup-traction-metrics",
        "tags": [
          "Founder metrics"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "starting_mrr_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Recurring revenue from the cohort at the start of the period (MRR or ARR, use the same basis throughout).",
                    "exclusiveMinimum": 0
                  },
                  "expansion_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Upsell and expansion revenue from that cohort.",
                    "default": 0
                  },
                  "contraction_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Downgrades from that cohort.",
                    "default": 0
                  },
                  "churned_usd": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Revenue lost from customers in that cohort who left.",
                    "default": 0
                  }
                },
                "required": [
                  "starting_mrr_usd"
                ],
                "additionalProperties": false
              },
              "example": {
                "starting_mrr_usd": 100000,
                "expansion_usd": 25000,
                "contraction_usd": 5000,
                "churned_usd": 8000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "calculator": "net_revenue_retention",
                  "result": {
                    "nrr_pct": 112,
                    "grr_pct": 87,
                    "ending_mrr_usd": 112000,
                    "guide_url": "https://raziel.co/learn/evaluating-startup-traction-metrics"
                  },
                  "disclaimer": "For education only. Not tax, legal or investment advice.",
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/guides": {
      "get": {
        "operationId": "searchGuides",
        "summary": "Search Raziel guides",
        "description": "Searches Raziel's 549 Learn articles on private investing, startups, funds and founder topics (SAFEs, cap tables, K-1s, capital calls, QSBS, investor updates and more). Returns titles, URLs, summaries and matching section headings to cite. Use define_term for a one-line definition instead.\n\nOn the site: https://raziel.co/learn",
        "tags": [
          "Research and reference"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "What to look for, in plain words, e.g. \"safe discount vs valuation cap\".",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results (1 to 10).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "tool": "search_guides",
                  "result": {
                    "query": "safe discount",
                    "results": [
                      {
                        "title": "SAFE Valuation Cap and Discount: How Conversion Works",
                        "url": "https://raziel.co/learn/safe-notes-valuation-caps-discounts",
                        "description": "SAFE valuation cap and discount: at conversion the investor gets the better of the two. See the math, then log the SAFE and its conversion free in Raziel.",
                        "published": "2025-04-10",
                        "matching_sections": [
                          "Does my SAFE convert at the valuation cap or the discount?",
                          "What Is a SAFE Note?",
                          "Key SAFE Terms: Valuation Cap and Discount"
                        ],
                        "score": 12.49
                      },
                      {
                        "title": "How to Track a Bridge Round as an Angel After Close",
                        "url": "https://raziel.co/learn/bridge-round-tracking",
                        "description": "How to track a bridge round after close: instrument (SAFE, note or priced), amount, cap or discount, trigger, cash date and status, and when it is a down round.",
                        "published": "2026-08-25",
                        "matching_sections": [
                          "Cap, discount, and trigger come from the instrument"
                        ],
                        "score": 12.09
                      },
                      {
                        "title": "Angel Portfolio Spreadsheet Template: Columns Before You Outgrow Excel",
                        "url": "https://raziel.co/learn/angel-portfolio-spreadsheet-template",
                        "description": "Angel portfolio spreadsheet template: company, instrument, cash, cap/discount, fully diluted %. Cake: most free templates have only 4–5 columns. Copy these.",
                        "published": "2026-08-21",
                        "matching_sections": [
                          "Cap, discount, and fully diluted % are three fields"
                        ],
                        "score": 11.99
                      }
                    ]
                  },
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/glossary": {
      "get": {
        "operationId": "defineTerm",
        "summary": "Define a private-market term",
        "description": "Plain-English definition of a private-market, venture or fund term (pro rata, MFN, liquidation preference, valuation cap, DPI, TVPI, carried interest, hurdle, capital call, NAV, K-1, QSBS, 83(b), 409A, drag-along, ROFR and about 33 more), with a link to the Raziel guide or calculator. Pass \"list\" to get every term. Use search_guides for longer explanations.\n\nOn the site: https://raziel.co/learn/private-markets-glossary",
        "tags": [
          "Research and reference"
        ],
        "parameters": [
          {
            "name": "term",
            "in": "query",
            "required": true,
            "description": "The term or abbreviation, e.g. \"pro rata\" or \"DPI\". Use \"list\" for all terms.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "tool": "define_term",
                  "result": {
                    "found": true,
                    "term": "Pro rata rights",
                    "also_called": [
                      "pro rata",
                      "pro-rata",
                      "participation rights"
                    ],
                    "definition": "An investor’s right to buy enough shares in a later round to keep their percentage ownership. Usually granted in a side letter or the financing documents, often only to investors above a size threshold.",
                    "learn_more_url": "https://raziel.co/learn/pro-rata-rights-tracking",
                    "match": "exact"
                  },
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/compare": {
      "get": {
        "operationId": "comparePlatforms",
        "summary": "Compare Raziel with another platform",
        "description": "Researched, sourced comparison of Raziel with another investing or startup platform (Addepar, Allocations, AngelList, Cake Equity, Carta, Empower, Eqvista, Foundersuite, getquin, Juniper Square, Kubera, Ledgy, Masttro, Pulley, Seraf, Sharesight, spreadsheets, Sydecar, Visible, Vyzer): pricing, feature coverage, key differences, where the other platform is stronger, and sources. Pass \"list\" to see every platform. Facts are as of the research date in the result.\n\nOn the site: https://raziel.co/compare",
        "tags": [
          "Research and reference"
        ],
        "parameters": [
          {
            "name": "competitor",
            "in": "query",
            "required": true,
            "description": "Platform name, e.g. \"Carta\" or \"AngelList\". Use \"list\" for all.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "ok": true,
                  "tool": "compare_platforms",
                  "result": {
                    "competitor": "Carta",
                    "competitor_url": "https://carta.com",
                    "category": "Cap table and equity management",
                    "summary": "Carta is an equity management platform used by startups to run their cap table, issue equity and handle 409A valuations, and by venture firms for fund administration. Shareholders and investors see the securities issued to them through Carta in a portfolio view.",
                    "best_for": "Companies that need a system of record for equity: issuing shares and options, running SAFE and priced financings, 409A valuations and compliance, plus venture firms that want fund administration.",
                    "raziel_best_for": "Investors who want every private position in one portfolio, whether or not the company uses Carta, and founders who want an investor pipeline, updates and a cap table view without an equity administration contract.",
                    "raziel_summary": "Raziel is a portfolio platform for private investors and founders: startups, SPVs, funds and entities in one place, with returns from real cash flows, AI document import, and founder tools for fundraising, investor updates and the cap table.",
                    "pricing": {
                      "Carta": "Free Launch plan for qualifying startups; paid plans not listed publicly",
                      "Raziel": "Founder free to 100 contacts. Investor $49/month after a 14-day trial."
                    },
                    "features": [
                      {
                        "feature": "Startup equity",
                        "raziel": "Yes",
                        "raziel_note": "SAFEs, priced rounds and secondaries, re-marked when a new round is recorded.",
                        "competitor": "Partial",
                        "competitor_note": "Securities issued through Carta appear in your portfolio automatically."
                      },
                      {
                        "feature": "SPVs and fund LP positions",
                        "raziel": "Yes",
                        "raziel_note": "Commitments, capital called, NAV and distributions beside direct holdings.",
                        "competitor": "Partial",
                        "competitor_note": "Fund administration and investment dashboards are built for fund managers."
                      },
                      {
                        "feature": "Entities and vehicles",
                        "raziel": "Yes",
                        "raziel_note": "Holdings across LLCs, trusts and personal accounts.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed for individual investors in the sources we reviewed."
                      },
                      {
                        "feature": "Public equities",
                        "raziel": "Coming soon",
                        "raziel_note": "Brokerage connections are coming soon.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed."
                      },
                      {
                        "feature": "Real estate",
                        "raziel": "Coming soon",
                        "raziel_note": "Property tracking is coming soon.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed."
                      },
                      {
                        "feature": "Crypto",
                        "raziel": "Coming soon",
                        "raziel_note": "Wallet connections are coming soon.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed."
                      },
                      {
                        "feature": "Returns from cash flows",
                        "raziel": "Yes",
                        "raziel_note": "MOIC, IRR, TVPI and DPI from the cash flows you record.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed for individual portfolios in the sources we reviewed."
                      },
                      {
                        "feature": "Automatic document import",
                        "raziel": "Yes",
                        "raziel_note": "Forward statements, capital call notices and SAFEs. AI is optional.",
                        "competitor": "Partial",
                        "competitor_note": "Firms can upload company documents and review an extracted cap table."
                      },
                      {
                        "feature": "Portfolio company news",
                        "raziel": "Yes",
                        "raziel_note": "Rounds and news on the companies you hold.",
                        "competitor": "Not listed",
                        "competitor_note": "Not listed."
                      },
                      {
                        "feature": "Fundraising CRM",
                        "raziel": "Yes",
                        "raziel_note": "Kanban pipeline with target checks.",
                        "competitor": "Partial",
                        "competitor_note": "Communication Center tracks engagement; no pipeline board listed."
                      },
                      {
                        "feature": "Investor updates",
                        "raziel": "Yes",
                        "raziel_note": "Open and click tracking.",
                        "competitor": "Yes",
                        "competitor_note": "Send updates and see who read them."
                      },
                      {
                        "feature": "Cap table",
                        "raziel": "Yes",
                        "raziel_note": "Ownership, options and dilution for the company you run.",
                        "competitor": "Yes",
                        "competitor_note": "Carta’s core product: issuance, financings, 409A."
                      },
                      {
                        "feature": "Sharing",
                        "raziel": "Yes",
                        "raziel_note": "Owner, editor and viewer roles per workspace.",
                        "competitor": "Yes",
                        "competitor_note": "Control investor access to the cap table and data room."
                      },
                      {
                        "feature": "Native mobile apps",
                        "raziel": "Yes",
                        "raziel_note": "Live on the App Store and Google Play.",
                        "competitor": "Yes",
                        "competitor_note": "iOS and Android apps for equity holders."
                      },
                      {
                        "feature": "Free plan",
                        "raziel": "Founder free to 100 contacts",
                        "raziel_note": "Founder is free through 100 contacts. Investor has a 14-day free trial.",
                        "competitor": "Yes",
                        "competitor_note": "Launch is free for qualifying early startups."
                      },
                      {
                        "feature": "Security",
                        "raziel": "Mandatory MFA",
                        "raziel_note": "Mandatory MFA, private networking. SOC 2 Type II and ISO 27001 in progress.",
                        "competitor": "SOC 1 and SOC 2 Type 2 reports"
                      }
                    ],
                    "other_differences": [
                      {
                        "feature": "Equity issuance and 409A valuations",
                        "raziel": "No",
                        "competitor": "Yes",
                        "note": "Carta issues shares and options and offers 409A valuations."
                      },
                      {
                        "feature": "Track companies that do not use Carta",
                        "raziel": "Yes",
                        "competitor": "Partial",
                        "note": "Carta documents adding non-Carta companies for fund administration clients."
                      }
                    ],
                    "key_differences": [
                      {
                        "title": "System of record versus portfolio tracker",
                        "body": "Carta is where a company issues and administers equity, so it is the legal record of the cap table. Raziel tracks positions and keeps a cap table view, but it does not issue securities or provide 409A valuations."
                      },
                      {
                        "title": "Which holdings you can see",
                        "body": "On Carta, an investor’s portfolio fills in from securities issued through Carta. Raziel lets you add any startup, SPV or fund, whether the company uses Carta, another provider or a spreadsheet."
                      },
                      {
                        "title": "Fundraising workflow for founders",
                        "body": "Carta covers SAFE issuance, wire requests and update engagement tracking. Raziel adds a Kanban fundraising pipeline with target checks next to investor updates and the cap table."
                      },
                      {
                        "title": "Pricing",
                        "body": "Carta Launch is free for startups under 25 stakeholders and $1M raised, with paid plans after that. Raziel’s Founder plan is free through 100 contacts, then $29/month, and the Investor plan is $49/month through 30 companies."
                      }
                    ],
                    "where_competitor_is_stronger": [
                      "Carta is a full equity administration platform: share and option issuance, financings, 409A valuations and compliance forms that Raziel does not offer.",
                      "For companies on Carta, shareholders see their securities without any data entry.",
                      "Fund administration for venture firms, including investment dashboards across funds.",
                      "Independent SOC 1 and SOC 2 Type 2 reports today, where Raziel’s SOC 2 Type II is in progress."
                    ],
                    "researched_on": "2026-10-28",
                    "sources": [
                      {
                        "label": "Carta Launch (free plan and eligibility)",
                        "url": "https://www3.carta.com/equity-management/launch"
                      },
                      {
                        "label": "Carta investor relations and updates",
                        "url": "https://carta.com/investor-updates/"
                      },
                      {
                        "label": "Carta blog: fundraising with Carta",
                        "url": "https://www3.carta.com/blog/how-to-streamline-your-fundraising-process-with-carta"
                      },
                      {
                        "label": "Carta product update: investments dashboard (Jan 2026)",
                        "url": "https://carta.com/product-updates/investments-dashboard-improvements/"
                      },
                      {
                        "label": "Carta support: adding non-Carta investments",
                        "url": "https://support.carta.com/kb/guide/en/how-to-add-non-carta-investments-to-your-investments-dashboard-tHgkyTTZ0b/Steps/3725304"
                      },
                      {
                        "label": "Carta on the App Store",
                        "url": "https://apps.apple.com/us/app/id1137735263?l=en-us"
                      },
                      {
                        "label": "Carta Android app listing (AppGoblin)",
                        "url": "https://appgoblin.info/apps/com.esharesinc.android"
                      },
                      {
                        "label": "Carta release notes: cap table access on iOS",
                        "url": "https://releasenotes.carta.com/mobile-investor-cap-table-access-2fUBeo"
                      },
                      {
                        "label": "Carta blog: SOC reports",
                        "url": "https://www3.carta.com/blog/carta-soc-2-report"
                      }
                    ],
                    "compare_url": "https://raziel.co/compare/raziel-vs-carta"
                  },
                  "docs": "https://raziel.co/developers"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CalculatorList": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "calculators": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "toolUrl": {
                  "type": "string"
                },
                "endpoint": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Result": {
        "type": "object",
        "required": [
          "ok",
          "result"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "calculator": {
            "type": "string"
          },
          "tool": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": true
          },
          "disclaimer": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string"
          },
          "docs": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "Body over 32 KB",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "More than 60 requests per minute from this IP",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}