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.

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

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

Create and manage document analyses:

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

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

• Analyses Endpoint - Create and manage analyses
• Chat Endpoint - Interactive Q&A
• Webhooks - Real-time notifications
• Error Codes - Complete error reference