Back to the website

Agent Winds API Documentation

Use the public demo key to search properties, retrieve listing details and photos, and submit a contact request for a user who asks to connect with an agent.

Authentication and access

Demo API key for AI agents:

X-API-Key: treas-demo-api-key

Rate limit: 15 requests per hour, shared by all callers using this demo key across endpoints. This is not a separate quota per user, site, or AI agent. Capacity replenishes over time; HTTP 429 means wait before retrying.

The key permits property GET requests and POST requests to the lead-submission endpoint below. It does not permit reading existing leads, editing or deleting leads, or administrative operations.

Server-side tools can call the API directly. Browser integrations must use an allowed website origin; a valid key does not override CORS.

1. Search properties

GET https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-summary

Provide at least one search filter, such as state, city, or listingKey. A limit alone is not a search filter. Property reads do not require a site identifier.

Common query parameters

  • state: two-letter state code, such as GA.
  • city, county, zip, address: location filters.
  • minPrice, maxPrice: price range.
  • minBedrooms, maxBedrooms, minBathrooms, maxBathrooms: room counts.
  • minSqft, maxSqft: living-area range.
  • propertyType, propertySubType: MLS property categories, such as Residential and SingleFamilyResidence.
  • status: listing status; defaults to Active for general searches.
  • originatingSystemName: restrict results to an MLS feed.
  • listingKey: retrieve a specific listing summary.
  • limit: maximum number of returned properties; use a small value for demo requests.
  • firstPhoto=true: request the first listing photo.

Query names are case-sensitive and use camelCase. Response fields generally use snake_case. General searches default to Residential properties with SingleFamilyResidence, Condominium, and Townhouse subtypes; use allPropertySubTypes=true to include any subtype.

Example

curl --get 'https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-summary' \
  -H 'X-API-Key: treas-demo-api-key' \
  --data-urlencode 'state=GA' \
  --data-urlencode 'minBedrooms=3' \
  --data-urlencode 'maxPrice=400000' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'firstPhoto=true'

The response contains properties and total_count. Each property includes fields such as id, listing_key, list_price, bedrooms_total, and first_photo_url. Fields may be null when the source MLS does not provide a value.

For paginated searches, use /retrieve-property-summary/page with pageSize (1–100; default 24). Map searches use /retrieve-property-summary/map. These requests share the same demo-key quota.

2. Get property details

GET https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-data?listingKey=LISTING_KEY

Replace LISTING_KEY with a listing_key returned by search. Use the camelCase query parameter listingKey.

curl --get 'https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-data' \
  -H 'X-API-Key: treas-demo-api-key' \
  --data-urlencode 'listingKey=LISTING_KEY'

Alternatively, use /retrieve-property-data/ID with the numeric id returned by search. The response contains a properties array and total_count.

3. Get property media

GET https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-media/{listingKey}

Put the URL-encoded listing key in the path, rather than a query parameter.

curl 'https://tophamtechbe.com/api/treas/idx/v1/retrieve-property-media/LISTING_KEY' \
  -H 'X-API-Key: treas-demo-api-key'

The response contains media and total_count. Media items can include media_url, s3_link, order_hint, and descriptions.

4. Submit a contact request

POST https://tophamtechbe.com/api/treas/idx/v1/chatleads

Submit only after the user asks to contact the agent and agrees to share their details. This creates a real lead and can trigger notifications and follow-up; it is not a test-only inbox.

Send contact fields as URL query parameters. A JSON body is not used for contact fields.

  • siteId: required for demo-key submissions; the destination agent’s site identifier. This website uses giovanni.atl.
  • name, email, phoneNumber: the user’s contact details.
  • serviceReq: the user’s message or requested service.
  • listingKey: optional listing context.
  • postalCode, state, area, price: optional location and property context.

Sites with verification enabled also require a valid X-Turnstile-Token from that site’s lead form. The demo key does not bypass verification. If the user must complete verification, direct them to the site’s contact form.

Example (replace placeholders before submitting)

curl --get --request POST 'https://tophamtechbe.com/api/treas/idx/v1/chatleads' \
  -H 'X-API-Key: treas-demo-api-key' \
  --data-urlencode 'siteId=giovanni.atl' \
  --data-urlencode 'name=USER_NAME' \
  --data-urlencode 'email=USER_EMAIL' \
  --data-urlencode 'phoneNumber=USER_PHONE' \
  --data-urlencode 'serviceReq=USER_MESSAGE'

Add -H 'X-Turnstile-Token: USER_VERIFICATION_TOKEN' when required. A successful submission returns HTTP 200 and the newly created lead. Do not automatically retry a submission after an ambiguous timeout; it may already have created a lead.

Errors and support

  • 400: missing or invalid request parameters.
  • 401: missing, invalid, or unauthorized API key for the requested operation.
  • 403: origin not allowed or lead verification required/failed.
  • 404: route or requested resource not found.
  • 429: shared demo quota exhausted; wait before retrying.
  • 5xx: service error or temporary verification unavailability.

For integration help or higher limits, contact support@agentwinds.com.