{
  "openapi": "3.1.0",
  "info": {
    "title": "ShieldNest Public API",
    "version": "1.0.0",
    "summary": "Insurance products, eligibility routing, and company information for ShieldNest.",
    "description": "Public, unauthenticated, read-only API for ShieldNest (coverage.exchange), a licensed independent insurance brokerage (NPN 21405787) serving California, New York and Texas.\n\nEvery endpoint is a GET returning public marketing, eligibility and licensing content. There are no write endpoints and no endpoint reads or returns quotes, documents, or customer records — quote requests are made on the website forms each product links to.\n\nNothing returned by this API is a binding offer of insurance or a price quote — a licensed agent follows up and coverage is bound only in writing.\n\nRate limit: 120 requests per minute per IP. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 also carries Retry-After. Retry 429 and 5xx responses after the indicated delay; 4xx responses are terminal.",
    "contact": {
      "name": "ShieldNest",
      "url": "https://coverage.exchange/contact"
    },
    "license": {
      "name": "Terms of use",
      "url": "https://coverage.exchange/privacy"
    }
  },
  "servers": [
    {
      "url": "https://coverage.exchange/api/public/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Catalog",
      "description": "Products, eligibility and company information."
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "operationId": "listProducts",
        "tags": [
          "Catalog"
        ],
        "summary": "List insurance products",
        "description": "List every insurance product ShieldNest offers, what each covers, which states it is available in, and its quote URL.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of products to return (1-50, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of products to skip (default 0).",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      }
                    },
                    "states_licensed": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid pagination parameters (code: validation_failed).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (code: rate_limited). Retry after Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products/{product}": {
      "get": {
        "operationId": "getProduct",
        "tags": [
          "Catalog"
        ],
        "summary": "Get one product and its quote form fields",
        "description": "Return a product plus the exact fields its website quote form requires, so the information can be gathered before directing a person to the quote form.",
        "parameters": [
          {
            "name": "product",
            "in": "path",
            "required": true,
            "description": "Product identifier.",
            "schema": {
              "type": "string",
              "enum": [
                "homeowners",
                "ca_fair_plan",
                "commercial_truck",
                "auto"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The product and its required quote fields.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Product"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "required_fields": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown product (code: not_found).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (code: rate_limited).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/eligibility": {
      "get": {
        "operationId": "checkEligibility",
        "tags": [
          "Catalog"
        ],
        "summary": "Check whether ShieldNest can help",
        "description": "Given a US state and the kind of coverage someone needs, report whether ShieldNest can help and which product fits best. A California home declined or non-renewed by standard carriers routes to the California FAIR Plan.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "Two-letter US state code, e.g. CA.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "coverage_type",
            "in": "query",
            "required": true,
            "description": "The kind of coverage the person is looking for.",
            "schema": {
              "type": "string",
              "enum": [
                "home",
                "auto",
                "commercial_truck",
                "unknown"
              ]
            }
          },
          {
            "name": "declined_or_nonrenewed",
            "in": "query",
            "required": false,
            "description": "For homes: whether standard carriers have declined or non-renewed the property.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Eligibility result and recommended product.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "eligible": {
                          "type": "boolean"
                        },
                        "state": {
                          "type": "string"
                        },
                        "reason": {
                          "type": "string"
                        },
                        "recommended_product": {
                          "$ref": "#/components/schemas/Product"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Missing or invalid parameters (code: validation_failed).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (code: rate_limited).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/company": {
      "get": {
        "operationId": "getCompanyInfo",
        "tags": [
          "Catalog"
        ],
        "summary": "Get company and licensing information",
        "description": "Return ShieldNest's National Producer Number, states served, office address, contact page, hours, and how the quoting process works.",
        "responses": {
          "200": {
            "description": "Company and licensing details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "national_producer_number": {
                          "type": "string"
                        },
                        "licensed_states": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "address": {
                          "type": "string"
                        },
                        "hours": {
                          "type": "string"
                        },
                        "contact_url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "mcp_endpoint": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (code: rate_limited).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "not_found",
                  "method_not_allowed",
                  "validation_failed",
                  "rate_limited",
                  "internal_error"
                ],
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation."
              },
              "details": {
                "type": "array",
                "description": "Per-field validation problems, when applicable.",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "issue": {
                      "type": "string"
                    }
                  }
                }
              },
              "docs": {
                "type": "string",
                "format": "uri"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "homeowners",
              "ca_fair_plan",
              "commercial_truck",
              "auto"
            ]
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "covers": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "states": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "quote_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}