Analyses API

The Analyses API allows you to upload documents, track processing status, and retrieve analysis results.

Endpoints Overview

| Endpoint | Method | Description | |----------|--------|-------------| | /v1/analyses | POST | Upload document for analysis | | /v1/analyses | GET | List all analyses | | /v1/analyses/:id | GET | Get analysis details | | /v1/analyses/:id/summary | GET | Get AI-generated summary | | /v1/analyses/:id/issues | GET | Get structured issues with cost estimates | | /v1/analyses/:id/location | GET | Get location insights | | /v1/analyses/:id/analyze | POST | Force-analyze a skipped document | | /v1/analyses/:id | DELETE | Delete analysis |

Create Analysis

Upload a PDF document for AI analysis.

HTTP

POST /v1/analyses

Request

Headers:

Authorization: Bearer hi_live_YOUR_API_KEY
Content-Type: multipart/form-data
X-External-User-ID: user_abc123  # Optional: for B2B2C usage tracking

Body Parameters:

Parameter	Type	Required	Description
`file`	File	Yes	PDF document to analyze
`property_address`	String	No	Property address (auto-extracted if not provided)
`property_id`	String	No	Link to existing property by ID
`external_property_id`	String	No	Find/create property by your external ID
`document_type`	String	No	Type: `inspection_report`, `loan_estimate`, `disclosure`
`external_user_id`	String	No	Track usage for B2B2C integrations. Can also be passed via `X-External-User-ID` header.

Example Request

Shell

curl -X POST https://api.homeinsightai.com/v1/analyses \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY" \
  -F "file=@inspection_report.pdf" \
  -F "property_address=123 Main St, Anytown, CA 94000"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "page_count": 47,
  "total_bytes": 4521984,
  "avg_bytes_per_page": 96212.4,
  "message": "Successfully processed 47 pages"
}

List Analyses

List all analyses for the authenticated user.

HTTP

GET /v1/analyses

Query Parameters

Parameter	Type	Default	Description
`limit`	Integer	20	Number of results per page (max 100)
`offset`	Integer	0	Number of results to skip

Example Request

Shell

curl "https://api.homeinsightai.com/v1/analyses?limit=10" \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analyses": [
    {
      "id": "ana_abc123xyz",
      "status": "completed",
      "property_address": "123 Main St, Anytown, CA 94000",
      "created_at": "2025-11-27T12:00:00Z",
      "completed_at": "2025-11-27T12:01:15Z"
    },
    {
      "id": "ana_def456uvw",
      "status": "processing",
      "property_address": "456 Oak Ave, Somewhere, TX 75000",
      "created_at": "2025-11-27T12:05:00Z",
      "completed_at": null
    }
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}

Retrieve Analysis

Get the current status and details of an analysis.

HTTP

GET /v1/analyses/:id

Path Parameters

Parameter	Type	Required	Description
`id`	String	Yes	Analysis ID (starts with `ana_`)

Example Request

Shell

curl https://api.homeinsightai.com/v1/analyses/ana_abc123xyz \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "page_count": 47,
  "total_bytes": 4521984,
  "has_original_pdf": true,
  "pages_extracted": true,
  "status": "completed",
  "property_address": "123 Main St, Anytown, CA 94000",
  "document_type": "inspection_report",
  "summary": "This is a 47-page home inspection report for a 3-bedroom, 2-bathroom single-family home built in 1985...",
  "total_issues": 12,
  "total_repair_estimate": {
    "low": 8500,
    "high": 12000
  },
  "severity": "major"
}

Status Values (Two-Phase Processing):

queued - Document queued for processing
processing - Document is being analyzed (Phase 1)
analysis_done - AI analysis complete, ready for summary/issues (Phase 1 complete)
skipped - Document skipped (uncategorized/noise) - use force-analyze to process
embedding - Embeddings being generated (Phase 2)
completed - Fully processed, chat ready (Phase 2 complete)
failed - Processing failed (check error_message)

Severity Values:

critical - Has critical issues requiring immediate attention
major - Has major issues needing repair
minor - Only minor issues found

Document Type Values:

inspection_report - Home inspection report
disclosure - Seller disclosure documents
title_document - Title reports and title insurance
appraisal - Property appraisal reports
survey - Property survey documents
hoa_documents - HOA documents and CC&Rs
repair_estimate - Contractor repair estimates
other - Other document types

Get Analysis Summary

Retrieve AI-generated summary and key points.

HTTP

GET /v1/analyses/:id/summary

Example Request

Shell

curl https://api.homeinsightai.com/v1/analyses/ana_abc123xyz/summary \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "document_type": "inspection_report",
  "summary": "This is a comprehensive home inspection report for a 3-bedroom, 2-bathroom single-family residence built in 1985. The property is generally in fair condition with several items requiring attention. The most significant concerns involve the roof (estimated 3-5 years remaining lifespan), outdated electrical panel, and HVAC system showing signs of age.",
  "key_points": [
    "Roof has approximately 3-5 years of useful life remaining",
    "Electrical panel is outdated (Federal Pacific) and should be replaced",
    "HVAC system is 18 years old and may need replacement soon",
    "Water heater is functioning but past expected lifespan",
    "Foundation appears solid with minor settling cracks"
  ]
}

Get Issues List

Retrieve structured inspection issues with cost estimates.

HTTP

GET /v1/analyses/:id/issues

Query Parameters

Parameter	Type	Description
`include_costs`	Boolean	Include cost estimates (default: true)
`force_refresh`	Boolean	Force re-extraction (default: false)

Example Request

Shell

curl "https://api.homeinsightai.com/v1/analyses/ana_abc123xyz/issues" \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "total_issues": 12,
  "issues": [
    {
      "title": "Missing shingles on north slope",
      "description": "Approximately 15-20 asphalt shingles are missing on the north-facing slope, exposing the underlayment to weather damage.",
      "severity": "critical",
      "category": "roof",
      "location": "Roof - North slope",
      "page_number": 9,
      "repair_needed": true,
      "cost_estimate": {
        "low": 1200,
        "high": 2000
      },
      "urgency": "immediate"
    },
    {
      "title": "Ungrounded outlets in kitchen",
      "description": "Multiple outlets in the kitchen are not properly grounded, posing a shock hazard.",
      "severity": "critical",
      "category": "electrical",
      "location": "Kitchen - Wall outlets",
      "page_number": 15,
      "repair_needed": true,
      "cost_estimate": {
        "low": 400,
        "high": 800
      },
      "urgency": "high"
    }
  ],
  "by_severity": {
    "critical": 2,
    "major": 5,
    "minor": 5
  },
  "by_category": {
    "roof": 3,
    "electrical": 4,
    "plumbing": 2,
    "hvac": 1,
    "structural": 2
  },
  "total_cost_range": {
    "low": 8500,
    "high": 12000
  },
  "property_address": "123 Main St, Anytown, CA 94000"
}

Severity Values: critical, major, minor, maintenance

Urgency Values: immediate, high, medium, low

Categories: roof, electrical, plumbing, hvac, structural, exterior, interior, foundation, appliances, other

Get Location Insights

Retrieve neighborhood analysis including walk score, schools, and flood risk.

HTTP

GET /v1/analyses/:id/location

Query Parameters

Parameter	Type	Description
`lat`	Float	Latitude (optional if address is set)
`lng`	Float	Longitude (optional if address is set)

Example Request

Shell

curl "https://api.homeinsightai.com/v1/analyses/ana_abc123xyz/location" \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "property_address": "123 Main St, Anytown, CA 94000",
  "coordinates": {
    "lat": 37.7749,
    "lng": -122.4194
  },
  "insights": {
    "walk_score": {
      "score": 72,
      "description": "Very Walkable",
      "nearby_amenities": {
        "restaurants": 15,
        "grocery_stores": 3,
        "parks": 2
      }
    },
    "schools": {
      "elementary": [
        {
          "name": "Lincoln Elementary",
          "rating": 8,
          "distance_miles": 0.3
        }
      ],
      "middle": [
        {
          "name": "Washington Middle School",
          "rating": 7,
          "distance_miles": 0.8
        }
      ],
      "high": [
        {
          "name": "Central High School",
          "rating": 8,
          "distance_miles": 1.2
        }
      ]
    },
    "flood_risk": {
      "zone": "X",
      "risk_level": "minimal",
      "description": "Outside 500-year flood plain",
      "flood_insurance_required": false
    },
    "crime_index": {
      "score": 42,
      "level": "moderate",
      "violent_crime_rate": "below_average",
      "property_crime_rate": "average"
    }
  },
  "data_sources": ["OpenStreetMap", "NCES/GreatSchools", "FEMA NFHL", "FBI UCR"]
}

Force-Analyze Document

Manually trigger AI analysis for a document that was skipped (categorized as uncategorized or noise).

HTTP

POST /v1/analyses/:id/analyze

When to Use

During bulk uploads, documents categorized as uncategorized or noise are automatically skipped to save processing time and costs. Use this endpoint when you want to:

Analyze a document that was incorrectly categorized
Re-process a document that failed analysis
Force analysis on any document regardless of category

Path Parameters

Parameter	Type	Required	Description
`id`	String	Yes	Analysis ID (starts with `ana_`)

Example Request

Shell

curl -X POST https://api.homeinsightai.com/v1/analyses/ana_abc123xyz/analyze \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "status": "queued",
  "message": "Analysis queued for processing",
  "job_id": "job_xyz789"
}

Webhook

When analysis completes, you'll receive a document.analysis_completed webhook with the results.

Delete Analysis

Permanently delete an analysis and all associated data.

HTTP

DELETE /v1/analyses/:id

Example Request

Shell

curl -X DELETE https://api.homeinsightai.com/v1/analyses/ana_abc123xyz \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Response

JSON

{
  "message": "Analysis ana_abc123xyz deleted",
  "bytes_freed": 4521984
}

Status Codes

Code	Description
`200`	Success
`201`	Analysis created
`400`	Invalid request (missing required fields, invalid file type)
`401`	Unauthorized (invalid or missing API key)
`404`	Analysis not found
`413`	File too large (max 50MB)
`429`	Rate limit exceeded
`500`	Internal server error

Webhook Events

Home Insight AI uses Two-Phase Processing with real-time webhooks:

Phase 1 (Per-Document, ~60 seconds):

document.analysis_completed - AI analysis complete for a single document
document.skipped - Document was skipped (uncategorized/noise)

Phase 2 (Batch, after all Phase 1 complete):

property.chat_ready - All documents embedded, RAG chat fully operational
document.embedding_failed - Embedding failed for a specific document

See Webhooks API for configuration and payload examples.

Next Steps

Chat API - Ask questions about your analysis
Webhooks - Get notified when analysis completes
Multi-File Upload - Upload multiple documents
B2B2C Integration - Track external user usage