---
title: "Interpret a bounded property request without reading parcel rows."
method: POST
path: "/v1/interpret"
tags: ["query"]
---

# Interpret a bounded property request without reading parcel rows.

`POST /v1/interpret`

## Request

- Base URL: `https://api.premiumpin.com`
- URL: `https://api.premiumpin.com/v1/interpret`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `pp_session`

Returns ready, clarify, or unsupported. Only ready includes an executable QueryRequest. Forward the returned state as previous_plan for corrections; all supplied state is revalidated and grants no authorization. Query and export retain their existing entitlement, scope, quota and row controls. ZIP filters require bounded county or state scope. Unsupported meanings never silently disappear. This endpoint is authenticated and rate limited.

## Request body

- object
  - `limit` integer
  - `previous_plan` object: Explicit state from the previous interpretation.
  - `scope` union: REQUIRED. Exactly one of fips, state, or held bounds the search.
    - object
      - `fips` string[], required
      - `held` string[]
      - `state` string[]
    - object
      - `fips` string[]
      - `held` string[]
      - `state` string[], required
    - object
      - `fips` string[]
      - `held` string[], required
      - `state` string[]
  - `select` string[]
  - `utterance` string, required

## Response `200`

Interpretation only; no parcel query or export executed.

- object
  - `action` 'search' | 'lookup' | 'export' | 'count' | 'field_catalog', required
  - `clarification` object: Structured clarification for one unresolved span; never leftover-token residue.
  - `dropped_constraints` object[]: Every uncompiled input constraint, with an explicit reason. Empty on complete plans.
    - `reason` string, required
    - `span` string, required
  - `plan` unknown
  - `plan_hash` string
  - `question` string
  - `reason` string
  - `state` object, required
  - `status` 'ready' | 'clarify' | 'unsupported', required

## Other responses

- `400`: bad filter / no scope / unknown field or op / malformed cursor / county-not-held for wholly unloaded search or absent lookup table
- `401`: missing or invalid API key / session
- `413`: scope would exceed the row/scan cap; narrow fips/state/held or add filters
- `429`: too many requests; retry after the window

---

[API](https://skmtc.dev/premiumpin/apis/premiumpin-property-records-api.md) · [All operations](https://skmtc.dev/premiumpin/apis/premiumpin-property-records-api/llms.txt) · [OpenAPI document](https://skmtc.dev/premiumpin/apis/premiumpin-property-records-api/revisions/18f5ec1c629c?raw)