{ "openapi": "3.1.0", "info": { "title": "PerilScore API", "version": "1.0.0", "description": "Catastrophe risk scoring for US properties. See https://app.perilscore.com/.well-known/mcp.json for the MCP server manifest and https://app.perilscore.com/llms.txt for agent-discovery context.", "contact": { "email": "info@perilscore.com", "url": "https://app.perilscore.com/developers/" }, "license": { "name": "Commercial" } }, "servers": [ { "url": "https://app.perilscore.com", "description": "Production" } ], "externalDocs": { "description": "Public docs + MCP setup", "url": "https://app.perilscore.com/developers/" }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "API key in the Authorization header: `Authorization: Bearer ps_api_<32 hex>`. Sign in at https://app.perilscore.com/developers/api/ to generate a key, or POST https://app.perilscore.com/api/v1/signup/ for programmatic signup." } }, "schemas": { "PerilScore": { "type": "object", "properties": { "peril": { "type": "string", "enum": [ "hurricane", "wildfire", "hail", "flood", "earthquake", "tornado", "crime" ] }, "peril_name": { "type": "string" }, "numeric_score": { "type": "number", "nullable": true, "description": "0-10 scale." }, "risk_band": { "type": "string", "enum": [ "HIGH", "MEDIUM", "LOW" ], "nullable": true }, "risk_label": { "type": "string", "enum": [ "Minimal", "Low", "Moderate", "Moderate-High", "High" ], "nullable": true }, "factors": { "type": "object", "additionalProperties": true }, "confidence": { "type": "string", "nullable": true } } }, "FireStation": { "type": "object", "properties": { "name": { "type": "string" }, "distance_miles": { "type": "number" }, "station_type": { "type": "string", "enum": [ "volunteer", "municipal" ] }, "driving_distance_miles": { "type": "number", "nullable": true }, "driving_time_minutes": { "type": "number", "nullable": true } } }, "ScoreResponse": { "type": "object", "required": [ "formatted_address", "public_id", "tier", "perils" ], "properties": { "formatted_address": { "type": "string" }, "public_id": { "type": "string", "pattern": "^P-[0-9A-F]{12}$" }, "report_url": { "type": "string", "format": "uri" }, "tier": { "type": "string", "enum": [ "free", "premium" ] }, "perils": { "type": "array", "items": { "$ref": "#/components/schemas/PerilScore" } }, "fire_station": { "allOf": [ { "$ref": "#/components/schemas/FireStation" } ], "nullable": true }, "fire_protection_score": { "type": "integer", "minimum": 1, "maximum": 10, "nullable": true }, "fire_protection_score_label": { "type": "string", "nullable": true }, "overall_score": { "type": "number", "nullable": true, "description": "Full-report overall property score." }, "overall_risk_band": { "type": "string", "nullable": true }, "overall_risk_label": { "type": "string", "nullable": true }, "overall_score_status": { "type": "string", "nullable": true }, "overall_score_version": { "type": "string", "nullable": true }, "overall_score_factors": { "type": "object", "additionalProperties": true, "nullable": true }, "overall_score_locked": { "type": "boolean" }, "property": { "type": "object", "nullable": true, "properties": { "year_built": { "type": "integer", "nullable": true }, "square_footage": { "type": "number", "nullable": true }, "market_value": { "type": "number", "nullable": true }, "avm_value": { "type": "number", "nullable": true }, "building_value": { "type": "number", "nullable": true }, "construction_class": { "type": "string", "nullable": true }, "construction_class_name": { "type": "string", "nullable": true }, "number_of_stories": { "type": "integer", "nullable": true }, "occupancy_type": { "type": "string", "nullable": true }, "replacement_cost": { "type": "object", "description": "Premium-only indicative structure rebuild range; not an appraisal or carrier cost-manual certification.", "properties": { "status": { "type": "string" }, "methodology_version": { "type": "string" }, "disclaimer": { "type": "string" }, "low": { "type": "integer", "nullable": true }, "base": { "type": "integer", "nullable": true }, "high": { "type": "integer", "nullable": true }, "display_range": { "type": "string", "nullable": true }, "usd_per_sqft_base": { "type": "number", "nullable": true }, "area_sqft": { "type": "integer", "nullable": true }, "area_source": { "type": "string", "nullable": true }, "construction_class": { "type": "integer", "nullable": true }, "regional_index_key": { "type": "string", "nullable": true }, "confidence": { "type": "string" }, "missing_inputs": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "factors": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "comparison": { "type": "object", "description": "Non-null market, AVM, and building values; land excluded.", "properties": { "market_value": { "type": "number" }, "avm_value": { "type": "number" }, "building_value": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "cope": { "type": "object", "additionalProperties": true, "nullable": true }, "ai_summary": { "type": "string", "nullable": true }, "permits": { "type": "object", "nullable": true, "description": "Permit history on capacity-backed premium reports.", "additionalProperties": true } } }, "SignupRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "agent_user_agent": { "type": "string", "maxLength": 200 }, "intended_use": { "type": "string", "maxLength": 500 } } }, "SignupResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_verification" ] }, "email": { "type": "string" }, "verify_email_sent": { "type": "boolean" }, "next_steps": { "type": "array", "items": { "type": "string" } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "billing_url": { "type": "string", "format": "uri-reference" }, "upgrade_url": { "type": "string", "format": "uri-reference" }, "billing_status": { "type": "string", "description": "Billing outcome; assessment_unavailable returns unknown." }, "retry_safe": { "type": "boolean", "description": "Whether the request can be retried without risking a duplicate charge." } } } } } } }, "paths": { "/api/v1/score": { "get": { "summary": "Score a property", "description": "Creates an authenticated full property report for a US property. An API key and available report capacity are required. A fresh report may consume one credit; a recent matching score may be reused. This REST endpoint has no caller-supplied idempotency key, so clients must not automatically retry an ambiguous timeout. Use canonical MCP build_underwriting_report for replay-safe creation and explicit charge/reuse metadata.", "operationId": "scoreProperty", "tags": [ "scoring" ], "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Complete US street address. Example: \"123 Main Street, Miami, FL 33139\"", "schema": { "type": "string", "maxLength": 500 } } ], "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "Successful score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Missing or invalid address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "API key required, invalid, or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient report capacity or payment past due", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Address could not be geocoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Full-report assessment unavailable. billing_status is unknown and retry_safe is false; inspect report history and billing before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/signup": { "post": { "summary": "Sign up for API access", "description": "Request a magic-link email to bootstrap API key access. Always returns 202 for valid email shapes (no account-existence oracle). After verifying, visit /developers/api/ to generate a key.", "operationId": "apiSignup", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "202": { "description": "Magic link queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } } }, "400": { "description": "Invalid email or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Email delivery failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }