Set up the HtAG API and make your first request

Set up a direct connection to the HtAG REST API: create an API key, send it in the correct header and run one small request. By the end, you will have a repeatable connection you can use from a terminal, Postman or your application backend.

You can use the API independently of MCP. If you completed the MCP setup guide, the same Developer Portal is where you manage your API access and usage.

1. Open your developer account

Sign in to the HtAG Developer Portal. Open Authorization from the Account navigation to manage API keys. Create a key for your integration and store it securely. Use a name that helps you recognise which application uses it.

Keep the key in your server’s secret store or a local environment variable. Do not embed it in browser JavaScript, a mobile app bundle or a public repository. Your backend should make authenticated HtAG requests for your application.

2. Check billing before the first call

Open Billing and check that your account is ready to process requests. Follow any funding requirement shown there. Use the current rate card to check the endpoint’s billing unit, tier, allowance and applicable discounts.

Start with one narrowly filtered request. Keep automatic retries and pagination off while testing. A successful connection is the goal of this guide; you can expand the workload once the first request is understood.

3. Use the API base URL and authentication header

Base URL:

https://api.htagai.com/v1

Authentication header:

x-api-key: YOUR_HTAG_API_KEY

Replace the placeholder with your API key. Send the key in the header rather than putting it in the request URL. The interactive API reference supplies the current method, path, parameters and response schema for each operation.

4. Send one small request from your terminal

This locality lookup searches for Richmond in Victoria, with postcode 3121, and requests at most five records. It checks authentication and returns reference data without starting a wider market workflow.

macOS or Linux

Set HTAG_API_KEY privately in your terminal session or secret manager, then run:

curl --fail-with-body --silent --show-error "https://api.htagai.com/v1/reference/locality?name=Richmond&state_name=VIC&postcode=3121&limit=5&offset=0" -H "x-api-key: $HTAG_API_KEY"

Windows PowerShell

Set HTAG_API_KEY privately as an environment variable, then run:

$response = Invoke-RestMethod -Method Get -Uri "https://api.htagai.com/v1/reference/locality?name=Richmond&state_name=VIC&postcode=3121&limit=5&offset=0" -Headers @{ "x-api-key" = $env:HTAG_API_KEY }
$response | ConvertTo-Json -Depth 10

The environment variable must contain the key in the session running the request. The examples read it without printing it. If it is missing, set it before continuing.

5. Or run the same check in Postman

1. Create a request with method GET.
2. Enter https://api.htagai.com/v1/reference/locality.
3. In Params, add name=Richmond, state_name=VIC, postcode=3121, limit=5 and offset=0.
4. In Headers, add x-api-key with your API key held in a private variable or Postman Vault.
5. Select Send, then inspect the HTTP status and JSON body. Keep the secret out of exported collections.

6. Confirm the connection worked

A successful request returns an HTTP success status and a JSON response containing the matching locality records. Inspect the returned name, state and postcode to confirm the intended location, and retain its loc_pid for later use. Read the actual response rather than relying on a copied identifier from an example.

An empty result means your filters did not find a matching record; it does not automatically mean authentication failed. Recheck the spelling and filters before deciding whether another request is needed.

You can also use the Playground to inspect a request in your developer workspace. Review the selected operation and inputs before running it.

7. Resolve an error before retrying

• 400: check the operation’s required parameters, supported values and input format.
• 401: check that the key is present, valid and sent as x-api-key.
• 403: check your account’s permissions for the operation.
• 402: check Billing and any balance or funding requirement.
• 429: respect the rate limit and any retry guidance in the response; avoid an immediate retry loop.

Keep the status and error message when troubleshooting, with your key removed. Do not treat a failed request as a reason to broaden the search or repeatedly call the API.

Your setup checklist

• Your API key is stored securely.
• Your request uses the /v1 base URL and x-api-key header.
• You have inspected one successful, bounded JSON response.
• You know where to check billing, current prices and request contracts.

Next, read Core Concepts: how reference lookups identify places, how address keys connect property records, and why geography, property type and reporting period belong with the data. Keep the Data Dictionary handy when you begin interpreting market metrics.