Analyses API

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

Create Analysis

Upload documents for AI analysis.

HTTP

POST /v1/analyses

Request

Headers:

Authorization: Bearer hi_live_YOUR_API_KEY
Content-Type: multipart/form-data

Body Parameters:

Parameter	Type	Required	Description
`file`	File	Yes	Document to analyze (PDF, DOCX, JPG, PNG)
`property_address`	String	Yes	Full property address
`additional_files`	File[]	No	Additional documents (photos, disclosures)
`analysis_type`	String	No	Type: `inspection`, `loan`, `full` (default: `full`)

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" \
  -F "additional_files=@photo1.jpg" \
  -F "additional_files=@photo2.jpg"

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "status": "processing",
  "property_address": "123 Main St, Anytown, CA 94000",
  "files_uploaded": 3,
  "created_at": "2025-11-27T12:00:00Z",
  "estimated_completion": "2025-11-27T12:01:00Z"
}

Retrieve Analysis

Get the current status and results of an analysis.

HTTP

GET /v1/analyses/:id

Request

Headers:

Authorization: Bearer hi_live_YOUR_API_KEY

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

Processing:

JSON

{
  "analysis_id": "ana_abc123xyz",
  "status": "processing",
  "progress": {
    "percent_complete": 45,
    "current_step": "Analyzing inspection report",
    "steps_completed": 2,
    "total_steps": 4
  }
}

Completed:

JSON

{
  "analysis_id": "ana_abc123xyz",
  "status": "completed",
  "property_address": "123 Main St, Anytown, CA 94000",
  "summary": {
    "total_issues": 12,
    "critical_issues": 2,
    "moderate_issues": 5,
    "minor_issues": 5,
    "estimated_repair_cost": {
      "low": 8500,
      "high": 12000,
      "currency": "USD"
    }
  },
  "completed_at": "2025-11-27T12:01:15Z"
}

Failed:

JSON

{
  "analysis_id": "ana_abc123xyz",
  "status": "failed",
  "error": {
    "code": "unsupported_format",
    "message": "Unable to extract text from uploaded PDF"
  },
  "failed_at": "2025-11-27T12:00:30Z"
}

Get Analysis Summary

Retrieve a detailed summary of the analysis including all issues and estimates.

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",
  "property_address": "123 Main St, Anytown, CA 94000",
  "summary": {
    "inspection": {
      "total_issues": 12,
      "by_severity": {
        "critical": 2,
        "moderate": 5,
        "minor": 5
      },
      "by_category": {
        "roof": 3,
        "plumbing": 2,
        "electrical": 4,
        "hvac": 1,
        "structural": 2
      }
    },
    "cost_estimates": {
      "total": {
        "low": 8500,
        "high": 12000
      },
      "by_category": {
        "roof": { "low": 2500, "high": 4500 },
        "plumbing": { "low": 1200, "high": 1800 },
        "electrical": { "low": 3200, "high": 4200 },
        "hvac": { "low": 800, "high": 1000 },
        "structural": { "low": 800, "high": 500 }
      }
    },
    "loan_analysis": {
      "loan_type": "Conventional",
      "interest_rate": 6.875,
      "market_comparison": "Above average (market: 6.5%)",
      "monthly_payment": 2847,
      "pmi_required": true,
      "red_flags": []
    }
  }
}

Get Issues List

Retrieve a structured list of all identified issues.

HTTP

GET /v1/analyses/:id/issues

Query Parameters

Parameter	Type	Description
`severity`	String	Filter by severity: `critical`, `moderate`, `minor`
`category`	String	Filter by category: `roof`, `plumbing`, `electrical`, etc.

Example Request

Shell

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

Response

JSON

{
  "analysis_id": "ana_abc123xyz",
  "issues": [
    {
      "id": "issue_001",
      "severity": "critical",
      "category": "roof",
      "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.",
      "location": "Roof - North slope",
      "estimated_cost": {
        "low": 1200,
        "high": 2000
      },
      "citations": [
        { "file": "inspection_report.pdf", "page": 9 }
      ],
      "urgency": "Address within 30 days"
    },
    {
      "id": "issue_002",
      "severity": "critical",
      "category": "electrical",
      "title": "Ungrounded outlets in kitchen",
      "description": "Multiple outlets in the kitchen are not properly grounded, posing a shock hazard.",
      "location": "Kitchen - Wall outlets",
      "estimated_cost": {
        "low": 400,
        "high": 800
      },
      "citations": [
        { "file": "inspection_report.pdf", "page": 15 }
      ],
      "urgency": "Address before move-in"
    }
  ],
  "total_count": 2
}

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

{
  "analysis_id": "ana_abc123xyz",
  "deleted": true,
  "deleted_at": "2025-11-27T12:30:00Z"
}

Status Codes

Code	Description
`200`	Success
`201`	Analysis created
`400`	Invalid request (missing required fields)
`404`	Analysis not found
`413`	File too large
`415`	Unsupported file type
`422`	Unable to process document

Next Steps

Chat API - Ask questions about your analysis
Webhooks - Get notified when analysis completes
Error Codes - Handle errors gracefully