API Reference

The Home Insight AI REST API provides programmatic access to document analysis, chat functionality, and account management. All endpoints require authentication via API key.

Two API Paths

Home Insight AI offers two distinct API architectures optimized for different use cases:

Not sure which to use? See the API Comparison Guide for a detailed breakdown.

Base URL

https://api.homeinsightai.com

For local development:

http://localhost:8000

Authentication

All API requests must include an API key in the Authorization header:

Authorization: Bearer hi_live_YOUR_API_KEY

See the Authentication guide for details.

Response Format

All responses are returned as JSON with the following structure:

Success Response

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-11-27T12:00:00Z"
  }
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "Property address is required",
    "details": {
      "field": "property_address"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-11-27T12:00:00Z"
  }
}

HTTP Status Codes

Common Error Scenarios

409 Conflict - Property Already Exists

When creating a property with an existing external_id or address:

{
  "detail": "Property with this external_id or address already exists"
}

Solution: Check if property exists first using GET /v1/properties?external_id=xxx before creating.

See Error Handling in API Comparison for complete examples.

Rate Limiting

Rate limits vary by subscription tier:

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1735301400

When rate limited, retry after the Retry-After header value (in seconds).

Pagination

List endpoints support pagination using cursor-based pagination:

GET /v1/analyses?limit=20&cursor=cur_abc123

Parameters:

• limit (optional): Number of results per page (default: 20, max: 100)
• cursor (optional): Cursor from previous response for next page

Response:

{
  "data": [ ... ],
  "meta": {
    "has_more": true,
    "next_cursor": "cur_xyz789"
  }
}

Endpoint Categories

Analyses API (Low-Level, B2B)

Single-file document processing:

• POST /v1/analyses - Upload and analyze single PDF
• GET /v1/analyses/:id - Get analysis status
• GET /v1/analyses/:id/summary - Get AI summary
• GET /v1/analyses/:id/issues - Get inspection issues
• DELETE /v1/analyses/:id - Delete an analysis

See Analyses API Documentation for complete reference.

Properties API (High-Level, Portal)

Bulk document processing with automatic categorization:

• POST /v1/properties - Create property
• GET /v1/properties - List/search properties
• GET /v1/properties/:id - Get property details
• POST /v1/properties/:id/upload - Upload 1-50 PDFs (bulk)
• GET /v1/properties/:id/documents - List documents

See Multi-File Upload API Documentation for complete reference.

Important Response Format:

The POST /v1/properties endpoint returns id, NOT property_id:

{
  "id": "prop_abc123",
  "external_id": "your-external-id",
  "address": "123 Main St",
  "city": "Anytown",
  "state": "CA",
  "zip_code": "12345",
  "country": "US",
  "document_count": 0,
  "created_at": "2025-12-03T...",
  "updated_at": "2025-12-03T..."
}

Usage:

// ✅ CORRECT
const propertyId = response.id;

// ❌ WRONG
const propertyId = response.property_id;  // undefined!

Checking for Existing Properties:

Before creating a property, check if it exists to avoid 409 conflicts:

GET /v1/properties?external_id=your-external-id

Response:

{
  "properties": [
    {
      "id": "prop_abc123",
      "external_id": "your-external-id",
      ...
    }
  ]
}

Chat

Interactive Q&A with analyzed documents:

• POST /v1/chat - Ask a question
• GET /v1/chat/:analysis_id/history - Get chat history
• DELETE /v1/chat/:analysis_id - Clear chat history

Webhooks

Receive real-time notifications:

• POST /v1/webhooks - Create a webhook
• GET /v1/webhooks - List webhooks
• DELETE /v1/webhooks/:id - Delete a webhook

Supported File Types

The API supports the following document types:

Inspection Reports

• PDF (.pdf)
• Word Documents (.doc, .docx)

Photos

• JPEG (.jpg, .jpeg)
• PNG (.png)
• HEIC (.heic)

Loan Documents

• PDF (.pdf) - Loan Estimates, Closing Disclosures

File Size Limits

Versioning

The API uses URL-based versioning. The current version is v1:

https://api.homeinsightai.com/v1/...

Breaking changes will be introduced in new versions (v2, v3, etc.). We'll maintain support for older versions for at least 12 months after deprecation notice.

Testing

Use test mode API keys (hi_test_...) for development and testing:

• No charges applied
• Limited to 100 requests/day
• Analysis results may be simplified

Client Libraries

Official SDKs are available:

• JavaScript/TypeScript: npm install home-insight-ai-sdk
• Python: pip install home-insight-ai
• Go: go get github.com/homeinsightai/go-sdk
• Ruby: gem install home_insight_ai

Examples

Full Analysis Workflow

// 1. Create analysis
const createResponse = await fetch('https://api.homeinsightai.com/v1/analyses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'multipart/form-data'
  },
  body: formData
})
const { analysis_id } = await createResponse.json()

// 2. Poll for completion
let status = 'processing'
while (status === 'processing') {
  await new Promise(resolve => setTimeout(resolve, 5000))
  const statusResponse = await fetch(
    `https://api.homeinsightai.com/v1/analyses/${analysis_id}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  )
  const result = await statusResponse.json()
  status = result.status
}

// 3. Ask questions
const chatResponse = await fetch('https://api.homeinsightai.com/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    analysis_id,
    query: 'What are the major issues?'
  })
})

Next Steps

• API Comparison Guide - Choose the right API for your use case
• Analyses API - Single-file processing (B2B)
• Properties API - Bulk processing (Portal, 6-9x faster)
• Chat Endpoint - Interactive Q&A
• B2B2C Integration - External user subscriptions
• Auto-Categorization - How document categorization works