Skip to content Discuss your data requirements with our team. Get in touch ↗Discuss your data requirements with our team. Get in touch ↗

For AI agents: the documentation index is /docs/llms.txt, and this page is available as Markdown.

Making requests

What every West Kite API call has in common: where to send it, what comes back, how IDs and pages work, and how to retry and cap cost safely.

Base URL

https://api.westkite.com/v1

The same API answers at https://app.westkite.com/v1. Everything is HTTPS and JSON. Send Content-Type: application/json with a body, up to 256 KB. GET calls take their options as query parameters; repeat a parameter, like where, to send more than one. Unknown body fields are refused, so a typo never passes silently.

The response envelope

Every successful JSON response has the same four keys:

{
  "data": {},
  "missing": [
    { "field": "owner.name", "reason": "not_published", "note": "Los Angeles County rolls omit owner names." }
  ],
  "billing": {
    "operation_id": "op_5e7a…",
    "operation": "property",
    "charged_usd": 0.01,
    "balance_usd": 9.99
  },
  "request_id": "req_8c1d…"
}
Key What it is
data The result. Its shape depends on the endpoint.
missing Fields or results that aren't there, each with a reason and sometimes a note. See Missing data.
billing What this call cost and what's left. replayed: true marks an idempotent replay.
request_id Quote it when you contact support. It's also in the X-Request-Id header.

Errors have their own shape, with no envelope. See Errors. The image endpoint returns a JPEG unless you ask for JSON.

Examples in these docs are illustrative. The OpenAPI description is the full schema.

IDs

Properties have IDs like property:3f2b9c1e-…, from search and find. Endpoints take the full ID or the bare UUID. People named by research have IDs like person:<property uuid>:<party id>, and research runs have bare UUIDs. Store IDs, not addresses: an ID always means the same parcel.

Pages

A list that has more rows returns next_cursor in data (null on the last page). Pass it back as cursor with the same filters for the next page. limit sets the page size, up to 100. Each page is charged for the rows it returns, never more than limit rows.

To collect a whole market, don't page: an export returns one file with an exact total.

Idempotency

Send an Idempotency-Key header (up to 255 characters) with any call you might retry, especially research, contacts and exports. For 24 hours, a retry with the same key and the same request returns the saved response with billing.replayed: true, charged_usd: 0 and an Idempotent-Replayed: true header.

  • The same key with a different request is refused with invalid_request.
  • A retry while the first request is still running gets idempotency_conflict (409). Wait for Retry-After and try again.
  • Images aren't saved, so an image retry simply runs again. Images are free.
curl https://api.westkite.com/v1/research \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -H "Idempotency-Key: 6f0d2c1e-retry-safe" \
  -H "Content-Type: application/json" \
  -d '{ "property_ids": ["property:08cdd01c-64d6-8ed2-b7b8-8158ccadf8a0"] }'

Use a new key for each new piece of work, such as a UUID you store with the job.

Capping cost

Every paid call holds its highest possible price before it runs, then settles to the real price. A call that fails is settled to zero.

Send max_cost_usd (a query parameter on GET, a body field on POST) to cap a call. If the quote is higher, the call is refused with max_cost_too_low and the quote in quoted_usd, and nothing is charged. For example, a find with limit=100 quotes $0.10.

An export sizes itself to the cap instead of refusing: it holds as many rows as the cap covers.

For a ceiling across many calls, put a spend cap on the key.

Rate limit headers

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. See Rate limits.

Calling from a browser

The API answers cross-origin requests, so a browser can call it. Keys are secrets, though: call the API from your server or your agent's environment, never from a page your users load.