# Making requests

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

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

```text
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:

```json 200
{
  "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](https://westkite.com/docs/api/making-requests.md#missing-data). |
| `billing` | What this call cost and what's left. `replayed: true` marks an [idempotent replay](#idempotency). |
| `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](https://westkite.com/docs/api/errors.md). The [image](https://westkite.com/docs/api/images.md) endpoint returns a JPEG unless you ask for JSON.

Examples in these docs are illustrative. The [OpenAPI description](https://api.westkite.com/v1/openapi.json) is the full schema.

## IDs

Properties have IDs like `property:3f2b9c1e-…`, from [search](https://westkite.com/docs/api/search.md) and [find](https://westkite.com/docs/api/find.md). 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](https://westkite.com/docs/api/exports.md) 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`](https://westkite.com/docs/api/errors.md#invalid_request).
- A retry while the first request is still running gets [`idempotency_conflict`](https://westkite.com/docs/api/errors.md#idempotency_conflict) (409). Wait for `Retry-After` and try again.
- Images aren't saved, so an image retry simply runs again. Images are free.

```sh
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`](https://westkite.com/docs/api/errors.md#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](https://westkite.com/docs/api/exports.md) 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](https://westkite.com/docs/api/authentication.md#spend-caps) on the key.

## Rate limit headers

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. See [Rate limits](https://westkite.com/docs/api/rate-limits.md).

## 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.

## Missing data

West Kite never fills a gap with a guess or a zero. When a field or a result isn't there, the response says so in `missing`, with a reason.

### How it looks

```json 200
{
  "data": { "owner": { "name": null } },
  "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…"
}
```

Each entry has the `field` (a path into `data`), a `reason` and sometimes a `note` in plain words.

### Reasons

| Reason | Means | What to do |
|---|---|---|
| `not_covered` | West Kite hasn't loaded that place, or that kind of record for that place (such as a county's permits), yet. | Check [coverage](https://westkite.com/docs/api/coverage.md), and file a [data request](https://westkite.com/docs/api/data-requests.md). |
| `not_published` | The source doesn't release it, such as sale prices in states that don't disclose them. | Say it's unpublished. Don't estimate it. |
| `not_on_record` | Nothing was filed, such as a deed recorded without a price. | Say there's no record. |
| `not_found` | A search, lookup or research run found nothing. | Try another spelling or ID. Research and contacts that find nothing cost nothing. |
| `temporarily_unavailable` | The source didn't answer this time. | Retry that part on its own later. |

### Missing is never zero

A missing sale price is not a $0 sale, and a missing building size is not an empty lot. When you show West Kite data, show a missing field as missing, and keep the reason if you can. When you filter with [find](https://westkite.com/docs/api/find.md), a property with no value for a field doesn't match a range on it; use `is unknown` to find those properties on purpose.

What each county publishes varies. [Coverage](https://westkite.com/docs/api/coverage.md) gives the share of properties with each field, county by county.
