Site Knowledge & Search — Developer Docs

Read the structured site digest for free, or run hybrid knowledge-base search.

How do I read structured site knowledge?

GET /v1/projects/{project_id}/site-knowledge returns the structured, geometry-free digest of everything the foundation pipeline collected for the site: parcels and zoning, flood and wetlands screening, soils, terrain, utilities, roads, regulatory layers, and source readiness.

• It is a plain read — no credits are debited.
• Use it to hydrate your own tools without asking the agent, or to decide which agent questions are worth a metered turn.
• A large site's digest can run to ~100 KB. Add ?sections=zoning,flood to return only the parts you need — every response lists the valid names in sections_available, an unknown name is refused with a 422 that names them, and omitting the parameter returns the whole digest.
• Read sections_returned before treating an empty section as evidence: a section you did not request comes back at its default (null or []), which is not a claim that the site has none.
• Geometry (GeoJSON/shapefiles) is not included; use the in-app GIS export (or the gis:export scope, which every key carries by default) for geometry deliverables.

How does knowledge-base search work?

POST /v1/projects/{project_id}/search runs the same hybrid (dense + BM25, reranked) search the agent uses over the project knowledge base — indexed ordinances plus your uploaded project documents.

• Returns matching chunks with citations: source document, section, page, and relevance score.
• Flat cost: 2 credits per call, regardless of result count.
• Rate limit: 30/min. Requires the project to be chat_ready.

Use search when you want raw evidence to feed your own pipeline; use POST .../messages when you want a synthesized, cited answer.

How do summaries and GIS exports work?

Summaries: send { focus, format: "paragraph" | "bullets", max_words? }. The endpoint is one constrained writing-model pass, not the full agent loop and not report generation.

GIS exports: send { format: "shapefile" | "kml" | "kmz" | "geojson" | "dxf", layers? }. The response contains artifact_id, filename, mime_type, download_url, expires_at, warnings, and metadata. It never returns raw GeoJSON, ZIP, KML, or DXF bytes inline.

DXF is the CAD handoff format for captured GIS layers. DWG is not supported on this public surface.

Maps: send { kind: "site_map" | "aerial" | "flood" | "wetlands" | "contours", buffer_meters?, latitude?, longitude? }. Omit buffer_meters to fit the project parcels; the response returns the drawn extent as extent_feet.

• site_map returns a sheet-ready PDF locator exhibit: parcel boundaries over aerial imagery with street labels, scale bar and north arrow. road_labels states whether street names actually landed.
• aerial returns the bare imagery as PNG plus a georeference block: crs, bbox_web_mercator, bbox_wgs84, image_size_px, and world_file text to save beside the image under world_file_name. Insert it as a background raster and draw on top.

Both are screening exhibits under a display-only imagery licence. Print the returned attribution, never scale dimensions off them, never present traced linework as survey data, and never pass the imagery to an image or vision model. The response repeats these rules in usage.

• flood returns FEMA's own flood map: the FIRMette PDF, or the printed FIRM panel PNG where FIRMette does not answer.
• wetlands returns the USFWS National Wetlands Inventory map PDF.
• contours returns the parcel's USGS 3DEP contour sheet PDF: labelled index contours over the aerial, from the project's stored contours. A sheet already drawn from the same data is reused.

flood and wetlands are the official products recorded for the project at the centroid of its parcel geometry, the same files a report embeds. These three are framed by their own lane, so sending latitude, longitude or buffer_meters with them is refused with 400 invalid_map_request. extent_feet and parcels_drawn are null where the product does not state them. One not recorded yet is drawn on a worker: while it draws the call answers 202 with { status: "rendering", retry_after_seconds } and a Retry-After header, so call again after that many seconds with the same body and the recorded map is returned; concurrent first calls start one job, not two. The Retry-After header can be longer than the retry_after_seconds in the body, because the rate limiter writes the later of the two, in whole seconds; following either is safe, since a call made early joins the same render and answers 202 again. contours answers 409 map_layer_unavailable when the project has no stored contours and 409 bootstrap_not_ready while its site data is still being built. When the agency does not return a map the answer is a retryable 502 naming it (flood_map_unavailable, wetlands_map_unavailable, with Retry-After); 404 flood_map_not_published means FEMA answered that it prints no FIRMette or FIRM panel for the site, and retrying will not change it.

Every kind except contours needs parcel geometry only, so a map works before ordinance bootstrap finishes; contours needs the project's stored contours. The artifact_id remains downloadable through GET /v1/projects/{project_id}/artifacts/{artifact_id}.

Other API topics

• API Overview
• Authentication & API Keys
• Projects Lifecycle
• Plan Check, Sources & Uploads
• Ask the Agent
• Site Plan & CAD Handoff
• Reports & Artifacts
• Wallet & Billing
• Errors & Rate Limits
• MCP & Connectors
• OpenAPI Spec

• Full developer reference