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”
CategoryDescriptionAuth Required
PropertiesSearch and view listingsNo
SearchSemantic and multi-modal searchNo
AgentsAgent profiles and managementVaries
BrokeragesBrokerage informationVaries
LeadsLead capture and managementVaries
AuthenticationAuth and user infoYes

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”
CodeMeaning
200Success
201Created
400Bad Request — Invalid parameters
401Unauthorized — Missing or invalid auth
403Forbidden — Insufficient permissions
404Not Found — Resource doesn’t exist
422Validation Error — Invalid data format
429Rate Limited — Too many requests
500Server Error — Something went wrong

Pagination

Section titled “Pagination”

List endpoints support pagination via query parameters:

ParameterDefaultMaxDescription
page1—Page number (1-indexed)
page_size20100Items 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”