Getting Started with the API

Follow these steps to start integrating with the HomeStar API.

Prerequisites

Contact your administrator to obtain an API key. API keys are prefixed with idx_ for identification.

Step 1: Test the Connection

Verify your API key works with a health check:

curl -H "X-API-Key: idx_your_key" \
     https://api.your-domain.com/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Step 2: List Properties

Retrieve properties with optional filters:

curl -H "X-API-Key: idx_your_key" \
     "https://api.your-domain.com/api/properties?city=Twin%20Falls"

This returns a paginated list of properties in Twin Falls.

Step 3: Search Semantically

Use natural language to find properties:

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-API-Key: idx_your_key" \
     -d '{"query": "modern kitchen with granite countertops"}' \
     https://api.your-domain.com/api/search/semantic

Tip

Semantic search understands natural language descriptions better than keyword matching. Describe what you’re looking for in plain English.

Next Steps

• Authentication Details — Learn about API keys and JWT tokens
• Property Endpoints — Full property API reference
• Search Endpoints — Advanced search capabilities
• Agent Endpoints — Manage agent data

Common Integration Patterns

JavaScript/TypeScript

const API_KEY = process.env.HOMESTAR_API_KEY;
const BASE_URL = 'https://api.your-domain.com';

async function searchProperties(city: string) {
  const response = await fetch(
    `${BASE_URL}/api/properties?city=${encodeURIComponent(city)}`,
    {
      headers: {
        'X-API-Key': API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

Python

import os
import requests

API_KEY = os.environ['HOMESTAR_API_KEY']
BASE_URL = 'https://api.your-domain.com'

def search_properties(city: str):
    response = requests.get(
        f'{BASE_URL}/api/properties',
        params={'city': city},
        headers={'X-API-Key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

Troubleshooting

Authentication Errors

If you receive 401 Unauthorized, verify:

• API key is correctly formatted with idx_ prefix
• Key hasn’t been revoked
• Using the correct header: X-API-Key

Rate Limiting

Default limits are 100 requests/minute. If you need higher limits, contact your administrator.

Response headers indicate your rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200