API preview

Developer docs

Lotmark's REST API exposes source-cited parcel enrichment records. Discover available releases and jurisdictions through the authenticated dataset catalog, then use the REST reference below to verify lookup behavior, response shape, provenance, and batch workflows.

Connect your agent with Lotmark's MCP tools, or use the REST reference below.

MCP · Agent connections

Parcel intelligence.
Inside your agent.

Give Claude or Codex read-only tools to discover parcel datasets, look up properties, inspect source citations and QA, and enrich a batch of parcels. Returned fields depend on the approved dataset and its source coverage.

Streamable HTTP · Your Lotmark API key

MCP endpoint: https://api.lotmark.io/mcp

The MCP uses Authorization: Bearer with your existing customer API key on every request. No OAuth sign-in or local server package is required.

Already have a Lotmark API key? Use it here. Otherwise request a key through developer access or checkout. Keep credentials out of contact forms, shared configuration, URLs, and chat messages.

Supply your key privately

For Claude Code and Codex, set LOTMARK_API_KEY in the environment that launches the client. This Bash / zsh prompt hides your input and keeps the key out of shell history. Run it in your own terminal, then start the chosen client in that same terminal. A secret manager may supply the variable instead.

Enter your own key only at the hidden terminal prompt. This website never receives it. Environment variables last for that shell session.

Claude Code

Merge this server entry into your project's .mcp.json, preserving any existing servers. Claude Code expands the environment reference in the header. Launch claude from the shell holding your key, approve the project server if prompted, and use /mcp to inspect status and tools.

Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.

Official Claude Code MCP guide ↗

Codex

With the Codex CLI installed, register the server below. The token flag stores the environment-variable name, not the key. Launch codex from the shell holding your key; use /mcp to inspect active servers.

Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.

Configure Codex directly in TOML

Merge into ~/.codex/config.toml, or a trusted project's .codex/config.toml. Desktop/IDE clients must receive LOTMARK_API_KEY in their launch environment too; restart after configuring it.

Select and copy this text manually, or use the copy button. Configuration contains environment references, never your key.

Official Codex MCP guide ↗

Claude web / Desktop remote connector

This uses your Claude account’s remote connector settings, separately from Claude Code. It requires an HTTPS endpoint reachable from Anthropic’s cloud. Use the endpoint shown above.

  1. Open Customize → Connectors → Add custom connector and name it Lotmark. Organization owners manage this under organization connector settings.
  2. Enter the public MCP URL. Select No sign in for OAuth, since Lotmark uses a bearer key.
  3. Under Request headers, set header name Authorization and privately enter Bearer followed by your own Lotmark key. Environment references are for CLI clients; enter the real value only in Claude’s private credential setting.
  4. Add the connector and enable it for a conversation. Verify tool discovery and a read-only call.

On Team/Enterprise, a fixed connector credential is shared by its users. Use an organization-approved key with appropriate access. Local Desktop claude_desktop_config.json is a separate mechanism; this HTTP server has no local stdio launcher.

Official Claude remote connector guide ↗

These instructions match the server’s HTTP and bearer-key contract. Client connection verification is separate: copying or saving configuration does not prove initialization, tool discovery, or a successful parcel lookup.

Prerequisites and connection contract

  • An active customer API key issued by Lotmark and the exact configured MCP URL. A revoked or unknown key is rejected on every request.
  • An installed and signed-in Claude Code or Codex client that supports Streamable HTTP. Remote Claude connectors require account/workspace permission and access from Anthropic's cloud.
  • The server lives in the parcel API at /mcp, using the official Python MCP SDK. It serves stateless Streamable HTTP with JSON responses and bearer-key authentication. REST endpoints and the website’s /docs are separate routes.
  • Only approved, explicitly non-synthetic dataset releases whose QA status is pass or warning are exposed. Source attribution, release IDs, licensing, missing fields, and warnings are preserved in results.
  • Parcel lookups use the existing REST request accounting. Read-only access can still record usage; no administrative, ingestion, billing, or arbitrary upstream-request tools are exposed.
  • The API key is sent in an HTTPS header. Supply it through your client’s private credential setting or launch environment. Never put it in a URL, public asset, source control, analytics, logs, or screenshots.

MCP tool catalog

list_datasets
No arguments. Discover approved datasets, jurisdictions, releases, and available source layers.
get_dataset
dataset_id. Inspect a dataset’s release, sources, and licensing before lookup.
get_parcel
parcel_id. Retrieve a source-cited parcel enrichment record.
get_parcel_by_apn
apn, optional dataset_id or county_fips. Scope the APN to its jurisdiction; ambiguous matches require a more specific lookup.
search_parcels
address, limit (default 10, maximum 25), and required dataset_id or county_fips. Search addresses within that jurisdiction.
batch_enrich_parcels
parcel_ids, apns, addresses, optional dataset_id or county_fips. At most 100 total lookups; APNs and addresses require jurisdiction scope. Each APN returns up to 10 matches and each address up to 5; results are deduplicated by parcel ID. Use a smaller batch if your client truncates results.
get_parcel_qa
parcel_id. Inspect the parcel’s QA report and warnings.
get_usage
No arguments. Inspect request counts for your current key.

Verify the connection

  1. Open the client’s MCP status and confirm initialization succeeds. Check discovery against the eight tools above; an HTTP health check or a saved config is insufficient.
  2. Call list_datasets, then get_dataset using a returned dataset_id. Confirm release identity, jurisdiction, and distribution/source details.
  3. Use a real APN or address available to your account, scoped to that returned dataset. Call get_parcel_by_apn or search_parcels, then inspect a returned record with get_parcel and get_parcel_qa.
  4. Compare parcel identifiers, sources, field_sources, and release metadata with their provenance. Keep missing fields explicit; empty results are not substitute records. Check get_usage to confirm accounting.

Troubleshooting

  • 401 / missing or invalid bearer key: check that LOTMARK_API_KEY is exported in the client’s launch environment and the key remains active. Restart the client after changing its environment. For remote Claude, check the private Authorization request header.
  • Initialization or discovery fails: confirm the exact /mcp URL, HTTPS reachability, and Streamable HTTP transport. A browser GET or REST response alone does not test MCP initialization.
  • Ambiguous APN or missing jurisdiction: pass the real dataset_id from discovery or the correct county_fips. APNs can repeat across counties and geometries.
  • Dataset/parcel not found: inspect the public catalog and release approval; an unapproved or synthetic dataset is unavailable. Do not replace a missing result with an invented parcel.
  • Batch rejected or truncated: stay within 100 combined inputs, supply scope for APNs/addresses, and use smaller batches within your client’s output limits.
  • Remote Claude cannot connect: verify a public HTTPS route and request headers; a VPN, loopback URL, or firewall can block access from Anthropic’s cloud. Ask your workspace administrator about connector permissions.
  • Copy is unavailable: use “Select text for manual copy,” then your device’s copy action or Ctrl+C / Command+C. Text fields remain copyable without JavaScript.

Base URLs

Parcel API: https://api.lotmark.io

Public site and access requests: https://lotmark.io

The parcel API is a separate protected service. Use the parcel API base URL for every /v1 request, not the public landing page URL.

Interactive OpenAPI docs are available on the parcel service at https://api.lotmark.io/docs. The machine-readable schema is available at https://api.lotmark.io/openapi.json.

Current Coverage

Discover current REST availability with GET /v1/datasets and approved MCP availability with list_datasets. The catalogs report loaded release IDs, jurisdictions, and source coverage; local acquisition files do not establish production availability. The source metrics below describe the deployed Sonoma release.

Authentication

All /v1 endpoints require a bearer API key. Keep the key in server-side secrets and send it with each request:

Authorization: Bearer LOTMARK_API_KEY

GET /health is open and can be used before credentials are provisioned. API keys are issued for sandbox evaluation or through checkout, and are shown once at delivery.

Endpoint Table

Method Path Auth Purpose
GET /health No Checks that the parcel API service and database are configured.
GET /v1/parcels/:parcel_id Yes Returns one curated parcel enrichment record by Lotmark parcel ID.
GET /v1/parcels/by-apn/:apn Yes Looks up a parcel by county APN and returns the same enrichment shape.
GET /v1/parcels/search?address=...&limit=10 Yes Searches loaded parcel addresses. limit is clamped from 1 to 25.
POST /v1/parcels:batch-enrich Yes Resolves parcel IDs, APNs, and address queries in one request. Maximum 100 total lookups.
GET /v1/parcels/:parcel_id/qa Yes Returns the persisted QA report for a generated parcel response.
GET /v1/usage Yes Returns request counts for the current API key.

Curl Examples

Set the base URL and key once, then run the smoke tests below.

export LOTMARK_API_BASE="https://api.lotmark.io"
export LOTMARK_API_KEY="ltm_live_..."

curl -s "$LOTMARK_API_BASE/health"

curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/lm_ca_028-030-009"

curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/by-apn/028-030-009"

curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/search?address=FRANZ%20VALLEY&limit=5"

curl -s -X POST "$LOTMARK_API_BASE/v1/parcels:batch-enrich" -H "Authorization: Bearer $LOTMARK_API_KEY" -H "Content-Type: application/json" -d '{"parcel_ids":["lm_ca_028-030-009"],"apns":["028-040-023"],"addresses":["PORTER CREEK RD"]}'

curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/parcels/lm_ca_028-030-009/qa"

curl -s -H "Authorization: Bearer $LOTMARK_API_KEY" "$LOTMARK_API_BASE/v1/usage"

Response Shape

Parcel responses are JSON objects with source blocks on major sections, compact per-field source references, and an LLM-ready narrative grounded in structured fields. Embedding vectors are not returned by default; the response exposes embedding metadata.

{
  "parcel_id": "lm_ca_001-011-004",
  "freshness_days": 0,
  "parcel": {
    "apn": "001-011-004",
    "address": "721 CLOVERDALE BLVD N",
    "county": "Sonoma",
    "state": "CA",
    "land_acres": 0.77,
    "source": {
      "agency": "County of Sonoma",
      "product": "Parcels Public",
      "accessed": "2026-07-24",
      "record_count": 189239
    }
  },
  "risk_features": {
    "fire": {
      "wildfire_hazard_potential_value": 4,
      "wildfire_hazard_potential_class": "high",
      "distance_to_burn_perimeter_m": 792.7,
      "last_burn_year_within_5km": 2021,
      "source": {
        "agency": "CAL FIRE",
        "product": "California Fire Perimeters public view nearest feature within 5 km"
      },
      "confidence": 0.8
    },
    "flood": {
      "fema_zone": "X",
      "in_sfha": false,
      "source": {
        "agency": "FEMA",
        "product": "National Flood Hazard Layer Flood Hazard Zones point intersect"
      },
      "confidence": 0.9
    }
  },
  "building": {
    "primary_year_built": 1952,
    "primary_size_sqft": 4705,
    "source": {
      "agency": "County of Sonoma",
      "product": "Parcels Public building attributes"
    },
    "confidence": 0.85
  },
  "terrain": {
    "elevation_ft": 1275.4,
    "local_relief_150m_ft": 429.8,
    "slope_degrees": 23.59,
    "aspect_degrees": 179.2,
    "source": {
      "agency": "USGS",
      "product": "3DEP Bare Earth DEM Dynamic service 30 m raster export sample"
    },
    "confidence": 0.9
  },
  "soil": {
    "mukey": "459841",
    "musym": "PcB",
    "mapunit_name": "Pajaro clay loam, overwash, 2 to 5 percent slopes",
    "hydrologic_group": "C/D",
    "drainage_class": "Somewhat poorly drained",
    "source": {
      "agency": "USDA NRCS",
      "product": "SSURGO mapunit polygon centroid intersect with SDA mapunit attributes"
    }
  },
  "vegetation": {
    "canopy": {
      "canopy_percent": 0,
      "year": 2023,
      "source": {
        "agency": "USDA Forest Service",
        "product": "NLCD Tree Canopy Cover 2023 raster export sample"
      }
    }
  },
  "narrative": {
    "text": "0.77 acre parcel, with a 1952 primary structure, at 1275.4 ft elevation.",
    "grounded_in": ["parcel", "building", "terrain", "risk.fire", "risk.flood"]
  },
  "embedding": {
    "dim": 1536,
    "model": "text-embedding-3-small",
    "status": "metadata_only"
  },
  "sources": {
    "parcel_boundaries": {
      "agency": "County of Sonoma",
      "source_file": "parcels.geojson"
    },
    "parcel_terrain_attributes": {
      "agency": "USGS",
      "source_file": "terrain.csv"
    },
    "soil_attributes": {
      "agency": "USDA NRCS",
      "source_file": "soil.csv"
    },
    "flood_hazard_zones": {
      "agency": "FEMA",
      "source_file": "flood_zones.geojson"
    }
  },
  "field_sources": {
    "parcel.apn": "parcel_boundaries",
    "terrain.elevation_ft": "parcel_terrain_attributes",
    "soil.mukey": "soil_attributes",
    "risk_features.flood.fema_zone": "flood_hazard_zones",
    "narrative.grounded_in": ["parcel_boundaries", "parcel_building_attributes", "parcel_terrain_attributes", "burn_perimeters", "flood_hazard_zones"]
  }
}

Error Responses

Errors use JSON bodies with ok: false and a short error string.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

{"ok":false,"error":"Missing bearer token."}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer

{"ok":false,"error":"Invalid API key."}

HTTP/1.1 400 Bad Request

{"ok":false,"error":"Provide an address query."}

HTTP/1.1 404 Not Found

{"ok":false,"error":"Parcel not found."}

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{"ok":false,"error":"Too many requests. Try again later."}

Batch requests also return 400 when the body is empty or contains more than 100 total parcel IDs, APNs, and address queries.

Rate Limits

Sandbox access is intended for functional evaluation, integration tests, and response-shape validation. Coordinate before scripted load tests or bulk runs.

Test Parcels

The examples below use the Sonoma release. Check GET /v1/datasets for current loaded releases and use their real dataset_id or county_fips for scoped APN lookup and address search. For MCP, use the approved releases returned by list_datasets.

Parcel ID APN Address Query
lm_ca_001-011-004 001-011-004 721 CLOVERDALE BLVD N
lm_ca_028-030-009 028-030-009 3225 FRANZ VALLEY RD
lm_ca_079-020-011 079-020-011 10275 LOCH HAVEN DR
lm_ca_091-340-003-112542 091-340-003 1830 BOXHEART DR

Some APNs have multiple county geometries. If a direct parcel ID misses or an APN has duplicates, retry with /v1/parcels/by-apn/:apn and inspect the returned parcel IDs.

Sandbox Access

To evaluate Lotmark, send the team a work email, company name, intended use case, expected test volume, and whether you need APN lookup, address search, batch enrichment, or QA reports. We will provision a sandbox bearer key and confirm the bundle loaded for your tests.

curl -s -X POST "https://lotmark.io/api/waitlist" -H "Content-Type: application/json" -d '{"email":"you@company.com","name":"Your Name","company":"Company","role":"proptech-ai","plan":"developer","message":"Please provision sandbox API access for APN lookup, address search, batch enrichment, and QA reports.","request_demo":false}'

After credentials are provisioned, start with /health, then run APN lookup and /v1/usage. Keep API keys out of client-side code and browser logs.