{
  "openapi": "3.1.0",
  "info": {
    "title": "Succession Wills LLM API",
    "description": "Generate a complete Last Will and Testament by providing Will Builder fields as URL query parameters. Designed for developers, automation, and LLM agents.",
    "version": "0.1.0",
    "contact": {
      "name": "Succession Wills",
      "url": "https://successionwills.com/"
    }
  },
  "servers": [
    {
      "url": "https://app.successionwills.com",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "LLM Will Generation",
      "description": "Create wills from query parameters"
    }
  ],
  "paths": {
    "/api/v1/llm": {
      "get": {
        "tags": [
          "LLM Will Generation"
        ],
        "summary": "Generate a will from URL parameters",
        "description": "Accepts the same fields used by the Succession Wills Will Builder. Nested arrays/objects are passed as URL-encoded JSON strings. Documentation: https://llm.successionwills.com/",
        "operationId": "generateWillFromQuery",
        "parameters": [
          {
            "name": "first_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "last_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "middle_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "aka_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address_street",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address_city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address_state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address_zip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "marital_status",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "enum": [
                1,
                2,
                3,
                4
              ]
            },
            "description": "1 Married, 2 Not Married, 3 Getting Married Soon, 4 Common-Law"
          },
          {
            "name": "spouse_first_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "spouse_last_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_children",
            "in": "query",
            "required": true,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "children",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "URL-encoded JSON array of children objects"
          },
          {
            "name": "include_minors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "first_name_primary_guardian",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "last_name_primary_guardian",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "primary_guardian",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "primary_guardian_relationship",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "executors",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "URL-encoded JSON array; at least one executor"
          },
          {
            "name": "sub_executors",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "URL-encoded JSON array of substitute executors"
          },
          {
            "name": "residue_bens",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "URL-encoded JSON array of residue beneficiary tiers"
          },
          {
            "name": "burial_selection",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "buried",
                "cremated",
                "executors_decide"
              ]
            }
          },
          {
            "name": "funeral_instructions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cash_bens",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bequests",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pets",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "attorneys",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Will generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiSuccess"
                },
                "example": {
                  "status": 200,
                  "success": true,
                  "data": {
                    "document_id": "690f6f706504a191df2a2975",
                    "document_progress": "standard_complete",
                    "download_pdf": "https://app.successionwills.com/api/v1/documents/690f6f706504a191df2a2975/download-pdf"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "Endpoint not enabled yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiSuccess": {
        "type": "object",
        "required": [
          "status",
          "success",
          "data"
        ],
        "properties": {
          "status": {
            "type": "integer",
            "example": 200
          },
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "status",
          "success",
          "data"
        ],
        "properties": {
          "status": {
            "type": "integer"
          },
          "success": {
            "type": "boolean",
            "example": false
          },
          "data": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "missing": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Executor": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "relationship"
        ],
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "relationship": {
            "type": "string"
          },
          "order": {
            "type": "integer"
          }
        }
      },
      "Child": {
        "type": "object",
        "required": [
          "first_name",
          "last_name"
        ],
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "exclude": {
            "type": "boolean"
          },
          "exclude_issue": {
            "type": "boolean"
          },
          "order": {
            "type": "integer"
          }
        }
      },
      "ResidueTier": {
        "type": "object",
        "required": [
          "selection",
          "place"
        ],
        "properties": {
          "selection": {
            "type": "string",
            "enum": [
              "spouse",
              "children",
              "other"
            ]
          },
          "place": {
            "type": "integer"
          },
          "others": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Human-readable documentation",
    "url": "https://llm.successionwills.com/"
  }
}