Skip to content
HomeStar Docs

API Overview

The HomeStar API provides programmatic access to property listings, agent profiles, lead management, and more. This RESTful API uses JSON for requests and responses.

Base URL

Section titled “Base URL”
https://api.idx.supported.systems

API Documentation

Section titled “API Documentation”

Interactive API documentation is available at:

  • Swagger UI: /docs — Interactive testing interface
  • ReDoc: /redoc — Clean, readable documentation

Authentication

Section titled “Authentication”

The API supports two authentication methods:

API Key Authentication

Section titled “API Key Authentication”

Include your API key in the request header:

X-API-Key: idx_your_api_key_here

JWT Token (OIDC)

Section titled “JWT Token (OIDC)”

For browser-based applications using Keycloak:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Endpoint Categories

Section titled “Endpoint Categories”
Category Description Auth Required
Properties Search and view listings No
Search Semantic and multi-modal search No
Agents Agent profiles and management Varies
Brokerages Brokerage information Varies
Leads Lead capture and management Varies
Authentication Auth and user info Yes

Response Format

Section titled “Response Format”

All successful responses follow this structure:

{
  "items": [...],      // Array of results (for list endpoints)
  "total": 100,        // Total count
  "page": 1,           // Current page
  "page_size": 20,     // Items per page
  "total_pages": 5     // Total pages
}

Single-item responses return the object directly:

{
  "id": 123,
  "name": "Example Property",
  ...
}

Error Handling

Section titled “Error Handling”

Errors return appropriate HTTP status codes with details:

{
  "detail": "Property not found"
}

Status Codes

Section titled “Status Codes”
Code Meaning
200 Success
201 Created
400 Bad Request — Invalid parameters
401 Unauthorized — Missing or invalid auth
403 Forbidden — Insufficient permissions
404 Not Found — Resource doesn’t exist
422 Validation Error — Invalid data format
429 Rate Limited — Too many requests
500 Server Error — Something went wrong

Pagination

Section titled “Pagination”

List endpoints support pagination via query parameters:

Parameter Default Max Description
page 1 — Page number (1-indexed)
page_size 20 100 Items per page

Example:

GET /api/properties?page=2&page_size=50

Filtering

Section titled “Filtering”

Many endpoints support filtering via query parameters:

GET /api/properties?city=Twin%20Falls&min_price=200000&max_price=500000

Rate Limits

Section titled “Rate Limits”

Default rate limits:

  • 100 requests/minute per API key
  • 1,000 requests/hour per API key

Rate limit headers are included in responses:

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

Multi-Tenant Support

Section titled “Multi-Tenant Support”

The API is multi-tenant. The Host header or domain determines which brokerage’s data is returned:

Host: www.your-domain.com

For domain-agnostic access, use the brokerage_id parameter where supported.

Section titled “Related Resources”