AcreEyes API
Version 1 · base URL https://acreeyes.com/api/v1 · machine-readable spec openapi.json
Run the same parcel report as acreeyes.com from your own code: send a parcel number, address or point and get the full report back as JSON and PDF.
Authentication
Send your key in the header on every request: Authorization: Bearer ae_live_…. A key in a URL is refused (400 key_in_url), because URLs end up in logs.
How a report works
POST /runs answers at once with a run in status queued. A report takes one to three minutes: poll GET /runs/{run_id} (or watch /stream) until the status is done, then fetch result.report. One report counts against your plan when a run finishes and saves an analysis; failed and cancelled runs are free. Send an Idempotency-Key header so a retried start never runs twice.
Errors
Every error is JSON: {"error": code, "message": …, "request_id": …}. 401 unauthorized, 403 missing_scope / quota / not_subscribed, 404 not_found, 429 rate_limited / busy (honour Retry-After), 503 when your plan can't be checked. Quote the request_id when you ask for help.
Endpoints
Account
GET /health
Service health no key needed
GET /me
Your key, plan and this month's usage
GET /regions
States AcreEyes covers
GET /profiles
Scoring profiles and the Eyes
GET /usage
Charged runs in a month
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
month | query | string |
Runs
POST /resolve
Check a parcel resolves (free) needs runs:write
Check a PIN or address resolves to a parcel before spending a run. Free; advisory (the run resolves it again). Always 200 with a `status`.
Request body
| Name | In | Type | Default | Description |
|---|---|---|---|---|
parcel * | body | string | A PIN or an address; comma-separate several PINs. | |
county | body | string | The county, when a PIN exists in several. | |
state | body | string | ID |
POST /runs
Start a report needs runs:write
Request body
Give exactly one of `pin`, `address` or `point`.
| Name | In | Type | Default | Description |
|---|---|---|---|---|
pin | body | string | Assessor parcel number, e.g. RP58N02E070150A. | |
county | body | string | With `pin` only: the county, when the PIN exists in several. | |
address | body | string | A site address. | |
point | body | number[] | [longitude, latitude] inside the state. | |
state | body | string | ID | Two-letter state code (GET /regions). |
well_radius_miles | body | number (0.1–10) | 2 | |
good_well_gpm | body | number (0.1–500) | 10 | The yield a well must reach to count as good. |
stream_radius_miles | body | number (0.1–5) | 1 | |
advertised_acres | body | number (0.01–1e+06) | Optional: the acreage the listing advertises. Compared with the mapped parcel's acreage, never used in its place; a large gap is reported (and can hold the grade), saying when only part of the parcel may be for sale. | |
profile | body | string | A scoring profile name (GET /profiles). | |
weights | body | object | string | Per-Eye multipliers: {"water": 2} or "water:2,hazard:1.5". | |
eyes | body | string[] | string | Which Eyes the report shows (every lookup still runs): ["water", "hazard"] or "water,hazard"; absent = all. | |
skip_soils | body | boolean | False | Skip the soils lookups. |
skip_terrain | body | boolean | False | Skip the terrain lookups. |
skip_streams | body | boolean | False | Skip the streams lookups. |
skip_hazards | body | boolean | False | Skip the hazards lookups. |
skip_diligence | body | boolean | False | Skip the diligence lookups. |
skip_imagery | body | boolean | False | Skip the imagery lookups. |
kind | body | "analyze" | "find" | analyze | `find` (land discovery) needs the owner-only `find` scope. |
source | body | "auto" | "live" | "mirror" | auto | Owner keys only: read mirrored data live or from the local copy. |
debug | body | "trace" | "verbose" | Owner keys only: trace detail. |
GET /runs
List runs
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
status | query | string | ||
since | query | string | ||
before | query | string | ||
limit | query | integer | 50 | |
key_id | query | string |
GET /runs/{run_id}
Get a run
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string |
POST /runs/{run_id}/cancel
Cancel a run needs runs:write
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string |
GET /runs/{run_id}/logs
A run's output lines
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string | ||
after | query | integer | 0 | |
limit | query | integer | 2000 |
GET /runs/{run_id}/stream
Watch a run live (server-sent events)
Server-sent events. Every log line is a plain `data:` message (a JSON string); structured events ride alongside it — `stage`, `flag`, `result`, `choices` (see StreamEvents) — and `end` carries the final run.
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string |
GET /runs/{run_id}/debug
A run's debug summary
The run's debug trace. Customer keys: a redacted summary. Owner keys with `debug:full`: the full summary, and with `events=true` raw events from byte offset `after` (poll with the returned `next` to tail a live run).
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string | ||
events | query | boolean | False | |
after | query | integer | 0 | |
limit | query | integer | 2000 |
GET /runs/{run_id}/debug/download
Download a run's raw trace needs debug:full
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
run_id | path | string |
Analyses
GET /analyses
List saved analyses needs analyses:read
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
profile | query | string | ||
weights | query | string |
GET /analyses/{aid}
An analysis: summary and raw engine result needs analyses:read
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
aid | path | string | ||
profile | query | string | ||
weights | query | string |
GET /analyses/{aid}/report.json
The report as JSON needs analyses:read
The full screening report as JSON (schema acreeyes.report/1): everything the PDF says, as data. `/v1/analyses/{id}` is the raw engine result.
compact=true leaves out the per-Eye detail and tables (`omitted` names them): about a quarter of the size, keeping the score, decision brief, flags and key facts.
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
aid | path | string | ||
hide_owner | query | boolean | False | |
compact | query | boolean | False | |
profile | query | string | ||
weights | query | string |
GET /analyses/{aid}/pdf
The report as a PDF needs analyses:read
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
aid | path | string | ||
brand | query | string | ||
hide_owner | query | boolean | False | |
profile | query | string | ||
weights | query | string |
GET /analyses/{aid}/maps/{name}.png
One report map (PNG, or JPEG when drawn over the aerial photo) needs analyses:read
Parameters
| Name | In | Type | Default | Description |
|---|---|---|---|---|
aid | path | string | ||
name | path | string |
Public-data rural land screening. AcreEyes is a public-data screening tool. Results are not a survey, appraisal, title search, septic or well approval, flood determination, water-right opinion or buildability opinion. Verify with the county and licensed professionals before relying on them.