{
  "openapi": "3.0.3",
  "info": {
    "title": "Sovereign Foundry Core API",
    "version": "1.0.0",
    "description": "Versioned headless insurance core: quote, application, e-signature, payment, bind, and policy reads. Authenticate every request with a bearer API key (sae_test_... for sandbox). Tenancy is derived from the key — never send a licensee id in the body."
  },
  "servers": [
    {
      "url": "https://sovereignautoengine.com/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key, e.g. sae_test_..."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Liveness check (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/whoami": {
      "get": {
        "summary": "Confirm which tenant and scopes your key carries",
        "responses": {
          "200": {
            "description": "Licensee, environment, scopes"
          }
        }
      }
    },
    "/bop/quote": {
      "post": {
        "summary": "Rate the demo BOP product (fastest first call)",
        "description": "Returns a real, version-pinned premium broken out by coverage. class_code: retail | office | restaurant. protection_class: 1-5. Limits in dollars.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "class_code": {
                    "type": "string",
                    "enum": [
                      "retail",
                      "office",
                      "restaurant"
                    ]
                  },
                  "protection_class": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "building_limit": {
                    "type": "number"
                  },
                  "contents_limit": {
                    "type": "number"
                  },
                  "gl_limit": {
                    "type": "number",
                    "enum": [
                      300000,
                      500000,
                      1000000
                    ]
                  }
                },
                "required": [
                  "class_code"
                ]
              },
              "example": {
                "class_code": "restaurant",
                "protection_class": 3,
                "building_limit": 400000,
                "contents_limit": 150000,
                "gl_limit": 1000000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Declined — reasons returned"
          },
          "201": {
            "description": "Premium by coverage in cents, with a rating trace"
          }
        }
      }
    },
    "/sessions": {
      "post": {
        "summary": "Open a checkout session for the full quote-to-bind flow",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agency_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "session_id and product constraints"
          }
        }
      }
    },
    "/quotes": {
      "post": {
        "summary": "Rate the session's answers",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "session_id": {
                    "type": "string"
                  },
                  "answers": {
                    "type": "object"
                  }
                },
                "required": [
                  "session_id",
                  "answers"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "quote_id, quote_number, premium, bind_token"
          }
        }
      }
    },
    "/quotes/term": {
      "post": {
        "summary": "Select a term length for a rated quote",
        "responses": {
          "200": {
            "description": "Re-termed quote"
          }
        }
      }
    },
    "/applications": {
      "post": {
        "summary": "Create an application from a quote",
        "responses": {
          "201": {
            "description": "application_id"
          }
        }
      }
    },
    "/applications/{id}": {
      "post": {
        "summary": "Read an application",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Application"
          }
        }
      }
    },
    "/applications/{id}/update": {
      "post": {
        "summary": "Update application fields",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated"
          }
        }
      }
    },
    "/applications/{id}/attestations": {
      "post": {
        "summary": "Record accepted attestations",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recorded"
          }
        }
      }
    },
    "/applications/{id}/signature-step": {
      "post": {
        "summary": "Get the e-signature packet / record a signature",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Signature step state"
          }
        }
      }
    },
    "/applications/{id}/amount-due": {
      "post": {
        "summary": "Amount due to bind",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Down payment and schedule"
          }
        }
      }
    },
    "/applications/{id}/bind": {
      "post": {
        "summary": "Confirm payment and bind the policy",
        "description": "Atomic: creates policy, term, coverages, charges, earning schedule, and the initial cash transaction.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "policy_id, policy_number"
          }
        }
      }
    },
    "/policies": {
      "get": {
        "summary": "List policies for this tenant",
        "responses": {
          "200": {
            "description": "Policies"
          }
        }
      }
    },
    "/policies/{id}": {
      "get": {
        "summary": "Policy detail with coverage profile",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy"
          }
        }
      }
    },
    "/policies/{id}/billing": {
      "get": {
        "summary": "Billing / cash activity for a policy",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Billing"
          }
        }
      }
    },
    "/policies/{id}/documents": {
      "get": {
        "summary": "Documents issued on a policy",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Documents"
          }
        }
      }
    }
  }
}