{"openapi":"3.1.0","info":{"title":"QueryLines API","description":"Surplus lines market data, per query. QueryLines aggregates U.S. excess & surplus (E&S / surplus lines) insurance market statistics -- premium, policy counts, and growth by state, coverage line, and month/quarter/year -- from public state stamping-office publications. Every response includes `source`, `data_as_of`, and `report_date` for attribution and restatement tracking. `/v1/lines` and `/v1/coverage` are free discovery endpoints; `/v1/premium`, `/v1/premium/summary`, and `/v1/insurers` are $0.10/query; `/v1/compare` is $0.50/query, paid via x402 stablecoin micropayments (USDC on Base) -- see the 402 responses below for the payment challenge flow. Machine-readable discovery: GET /llms.txt (agent-oriented summary) and an MCP server at /mcp (streamable HTTP) exposing the same queries as tools (list_lines, get_coverage, get_premium, get_summary, compare_states, get_top_insurers). Auto-generated monthly market snapshot pages (free, no payment gate) are served at https://querylines.com/snapshots -- not API endpoints, but built from this same data.","version":"1.0.0","contact":{"name":"QueryLines","url":"https://querylines.com","email":"hello@querylines.com"}},"externalDocs":{"description":"QueryLines docs: quickstarts (curl, TypeScript, Python, Go), wallet setup, MCP client setup","url":"https://querylines.com/docs/"},"servers":[{"url":"https://api.querylines.com"}],"paths":{"/v1/premium":{"get":{"summary":"Premium/policy-count time series for a state","description":"Optionally scoped to a coverage line, date range, and granularity. $0.10 per query.","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"State code, e.g. FL or TX"},{"name":"line","in":"query","required":false,"schema":{"type":"string","default":"all"},"description":"Coverage line category, source code, or name, or \"all\""},{"name":"county","in":"query","required":false,"description":"County name (annual county-level data only). Omit for statewide totals.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Inclusive lower bound, YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"to","in":"query","required":false,"description":"Inclusive upper bound, YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["month","quarter","year"],"default":"month"}},{"name":"report_date","in":"query","required":false,"description":"Pin the response to a specific publication date (YYYY-MM-DD) instead of the latest report_date for each period -- see CLAUDE.md's restatement-tracking rule.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Premium/policy-count series.","content":{"application/json":{"schema":{"type":"object","required":["state","line","county","granularity","data","report_date","data_as_of","source"],"properties":{"state":{"type":"string"},"line":{"type":"string"},"county":{"type":["string","null"],"description":"Echoes the county query param, uppercased; null when unset (statewide)."},"granularity":{"type":"string","enum":["month","quarter","year"]},"data":{"type":"array","items":{"type":"object","required":["period","premium","policy_count","new_business_premium","renewal_premium","new_business_policy_pct","renewal_policy_pct"],"properties":{"period":{"type":"string","description":"e.g. \"2025-09\", \"2025-Q3\", or \"2025\" depending on granularity"},"premium":{"type":["number","null"],"description":"Exact premium in USD. null for months whose source report published exact policy counts only; back-filled when a later report restates the figure."},"policy_count":{"type":["number","null"]},"new_business_premium":{"type":["number","null"]},"renewal_premium":{"type":["number","null"]},"new_business_policy_pct":{"type":["number","null"],"description":"New-business share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."},"renewal_policy_pct":{"type":["number","null"],"description":"Renewal share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."}}}},"report_date":{"type":["string","null"]},"data_as_of":{"type":["string","null"]},"source":{"type":["string","null"]}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required (x402). Returned when the x402 payment gate is enabled (PAY_TO_ADDRESS configured) and the request carries no valid payment. The full payment challenge (price/network/payTo/asset) is carried in the base64-encoded PAYMENT-REQUIRED response header (see the x402 spec), not the JSON body -- the body is `{}` for API clients. Price for this route: $0.10. Retry with a signed payment per x402 (USDC on Base mainnet); on success the response carries a PAYMENT-RESPONSE header with settlement info. When PAY_TO_ADDRESS is unset (kill switch off), this route is free and never returns 402.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge (price/network/payTo/asset).","schema":{"type":"string"}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}},"/v1/premium/summary":{"get":{"summary":"Headline annual totals + year-over-year comparison for a state","description":"$0.10 per query.","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"State code, e.g. FL or TX"},{"name":"year","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}$"}}],"responses":{"200":{"description":"Annual summary with prior-year comparison.","content":{"application/json":{"schema":{"type":"object","required":["state","year","premium","policy_count","new_business_premium","renewal_premium","new_business_policy_pct","renewal_policy_pct","months_available","basis","prior_year","yoy_premium_pct","yoy_policy_count_pct","report_date","data_as_of","source"],"properties":{"state":{"type":"string"},"year":{"type":"number"},"premium":{"type":["number","null"]},"policy_count":{"type":["number","null"]},"new_business_premium":{"type":["number","null"]},"renewal_premium":{"type":["number","null"]},"new_business_policy_pct":{"type":["number","null"]},"renewal_policy_pct":{"type":["number","null"]},"months_available":{"type":"number"},"basis":{"type":["string","null"],"enum":["monthly_sum","annual_report","partial_monthly_sum",null],"description":"How the summary was computed: monthly_sum (all 12 months summed), annual_report (a year-level publication row, preferred over an incomplete monthly sum), or partial_monthly_sum (fewer than 12 months and no year-level row -- may understate the year)."},"prior_year":{"type":"object","required":["year","premium","policy_count","months_available"],"properties":{"year":{"type":"number"},"premium":{"type":["number","null"]},"policy_count":{"type":["number","null"]},"months_available":{"type":"number"}}},"yoy_premium_pct":{"type":["number","null"]},"yoy_policy_count_pct":{"type":["number","null"]},"report_date":{"type":["string","null"]},"data_as_of":{"type":["string","null"]},"source":{"type":["string","null"]}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required (x402). Returned when the x402 payment gate is enabled (PAY_TO_ADDRESS configured) and the request carries no valid payment. The full payment challenge (price/network/payTo/asset) is carried in the base64-encoded PAYMENT-REQUIRED response header (see the x402 spec), not the JSON body -- the body is `{}` for API clients. Price for this route: $0.10. Retry with a signed payment per x402 (USDC on Base mainnet); on success the response carries a PAYMENT-RESPONSE header with settlement info. When PAY_TO_ADDRESS is unset (kill switch off), this route is free and never returns 402.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge (price/network/payTo/asset).","schema":{"type":"string"}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}},"/v1/compare":{"get":{"summary":"Cross-state premium/policy-count comparison","description":"$0.50 per query -- the cross-state differentiator (CLAUDE.md).","parameters":[{"name":"states","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated state codes, e.g. FL,TX"},{"name":"line","in":"query","required":false,"schema":{"type":"string","default":"all"}},{"name":"from","in":"query","required":false,"description":"Inclusive lower bound, YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"to","in":"query","required":false,"description":"Inclusive upper bound, YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["month","quarter","year"],"default":"month"}},{"name":"report_date","in":"query","required":false,"description":"Pin the response to a specific publication date (YYYY-MM-DD) instead of the latest report_date for each period -- see CLAUDE.md's restatement-tracking rule.","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"Per-state series keyed by state code.","content":{"application/json":{"schema":{"type":"object","required":["line","granularity","series","report_date","data_as_of","source"],"properties":{"line":{"type":"string"},"granularity":{"type":"string","enum":["month","quarter","year"]},"series":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","required":["period","premium","policy_count","new_business_premium","renewal_premium","new_business_policy_pct","renewal_policy_pct"],"properties":{"period":{"type":"string","description":"e.g. \"2025-09\", \"2025-Q3\", or \"2025\" depending on granularity"},"premium":{"type":["number","null"],"description":"Exact premium in USD. null for months whose source report published exact policy counts only; back-filled when a later report restates the figure."},"policy_count":{"type":["number","null"]},"new_business_premium":{"type":["number","null"]},"renewal_premium":{"type":["number","null"]},"new_business_policy_pct":{"type":["number","null"],"description":"New-business share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."},"renewal_policy_pct":{"type":["number","null"],"description":"Renewal share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."}}}}},"report_date":{"type":["string","null"]},"data_as_of":{"type":["string","null"]},"source":{"type":"object","additionalProperties":{"type":["string","null"]}}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required (x402). Returned when the x402 payment gate is enabled (PAY_TO_ADDRESS configured) and the request carries no valid payment. The full payment challenge (price/network/payTo/asset) is carried in the base64-encoded PAYMENT-REQUIRED response header (see the x402 spec), not the JSON body -- the body is `{}` for API clients. Price for this route: $0.50. Retry with a signed payment per x402 (USDC on Base mainnet); on success the response carries a PAYMENT-RESPONSE header with settlement info. When PAY_TO_ADDRESS is unset (kill switch off), this route is free and never returns 402.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge (price/network/payTo/asset).","schema":{"type":"string"}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}},"/v1/premium/sample":{"get":{"summary":"Free sample: statewide all-lines monthly series, latest 13 months","description":"Free -- the teaser for /v1/premium. Statewide all-lines only, month granularity, capped at the latest 13 months. Line/county/insurer detail, full history, and cross-state comparison are paid.","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string","default":"FL"}}],"responses":{"200":{"description":"Monthly all-lines series (latest 13 months).","content":{"application/json":{"schema":{"type":"object","required":["state","line","granularity","sample","data","report_date","data_as_of","source","note"],"properties":{"state":{"type":"string"},"line":{"type":"string"},"granularity":{"type":"string"},"sample":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","required":["period","premium","policy_count","new_business_premium","renewal_premium","new_business_policy_pct","renewal_policy_pct"],"properties":{"period":{"type":"string","description":"e.g. \"2025-09\", \"2025-Q3\", or \"2025\" depending on granularity"},"premium":{"type":["number","null"],"description":"Exact premium in USD. null for months whose source report published exact policy counts only; back-filled when a later report restates the figure."},"policy_count":{"type":["number","null"]},"new_business_premium":{"type":["number","null"]},"renewal_premium":{"type":["number","null"]},"new_business_policy_pct":{"type":["number","null"],"description":"New-business share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."},"renewal_policy_pct":{"type":["number","null"],"description":"Renewal share of policy count, 0-100. Only populated on all-lines rows FSLSO prints it for."}}}},"report_date":{"type":["string","null"]},"data_as_of":{"type":["string","null"]},"source":{"type":["string","null"]},"note":{"type":"string"}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}},"/v1/lines":{"get":{"summary":"Coverage line taxonomy for a state","description":"Free -- discovery bait (CLAUDE.md). Cache-Control: public, max-age=3600.","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"State code, e.g. FL or TX"}],"responses":{"200":{"description":"Coverage lines, ordered by source_code.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","source_code","name","category"],"properties":{"id":{"type":"number"},"source_code":{"type":"string"},"name":{"type":"string"},"category":{"type":["string","null"]}}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}},"/v1/coverage":{"get":{"summary":"What data exists: states, date ranges, granularities","description":"Free -- discovery bait (CLAUDE.md). Cache-Control: public, max-age=3600.","parameters":[],"responses":{"200":{"description":"Per-state coverage summary.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["state","name","stamping_office","period_types","capabilities"],"properties":{"state":{"type":"string"},"name":{"type":"string"},"stamping_office":{"type":"string"},"period_types":{"type":"object","additionalProperties":{"type":"object","required":["from","to","latest_report_date"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"latest_report_date":{"type":"string"}}}},"capabilities":{"type":"object","description":"Which migration-0003 data types have at least one row for this state.","required":["has_county_data","has_insurer_data","has_new_renewal_split"],"properties":{"has_county_data":{"type":"boolean","description":"Annual county-level rows (GET /v1/premium?county=...)."},"has_insurer_data":{"type":"boolean","description":"Per-insurer rows (GET /v1/insurers)."},"has_new_renewal_split":{"type":"boolean","description":"new_business_policy_pct/renewal_policy_pct populated on some row."}}}}}}}}}}}},"/v1/insurers":{"get":{"summary":"Top insurers by premium for a state and period","description":"Ranked by premium, for a month or year. $0.10 per query.","parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"},"description":"State code, e.g. FL or TX"},{"name":"period","in":"query","required":true,"description":"Month (YYYY-MM) or year (YYYY)","schema":{"type":"string","pattern":"^\\d{4}(-\\d{2})?$"}}],"responses":{"200":{"description":"Ranked insurers for the period.","content":{"application/json":{"schema":{"type":"object","required":["state","period","insurers","report_date","data_as_of","source"],"properties":{"state":{"type":"string"},"period":{"type":"string"},"insurers":{"type":"array","items":{"type":"object","required":["rank","name","premium","policy_count"],"properties":{"rank":{"type":"number"},"name":{"type":"string"},"premium":{"type":"number"},"policy_count":{"type":["number","null"]}}}},"report_date":{"type":["string","null"]},"data_as_of":{"type":["string","null"]},"source":{"type":["string","null"]}}}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required (x402). Returned when the x402 payment gate is enabled (PAY_TO_ADDRESS configured) and the request carries no valid payment. The full payment challenge (price/network/payTo/asset) is carried in the base64-encoded PAYMENT-REQUIRED response header (see the x402 spec), not the JSON body -- the body is `{}` for API clients. Price for this route: $0.10. Retry with a signed payment per x402 (USDC on Base mainnet); on success the response carries a PAYMENT-RESPONSE header with settlement info. When PAY_TO_ADDRESS is unset (kill switch off), this route is free and never returns 402.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 payment challenge (price/network/payTo/asset).","schema":{"type":"string"}}}},"404":{"description":"Unknown state or coverage line.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","not_found","internal"]},"message":{"type":"string"}}}}}}}}}}}}}