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.
- Geometry (GeoJSON/shapefiles) is not included; use the in-app GIS export (or the
gis:exportscope, 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?
| Endpoint | What it does | Scope | Rate limit |
|---|---|---|---|
POST /v1/projects/{project_id}/summaries | Creates a constrained text-only summary from geometry-free site knowledge plus top KB chunks | agent:ask | 5/min |
POST /v1/projects/{project_id}/gis-exports | Creates a stored GIS export artifact and returns a signed URL | gis:export | 10/min |
GET /v1/projects/{project_id}/gis-exports/{artifact_id} | Remints a fresh signed URL for a prior GIS export | gis:export | 30/min |
POST /v1/projects/{project_id}/maps | Renders a site-map exhibit PDF or a georeferenced aerial snapshot and returns a signed URL | gis:export | 10/min |
POST /v1/parcels/resolve | The wizard parcel picker: address, APN + state, coordinates, or ll_uuid to ranked candidates with geometry | project:create | 20/min |
POST /v1/parcels/preview | The highlighted map: chosen parcel geometries rendered to a PNG (base64) for the user to confirm before creation; nothing stored | project:create | 10/min |
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", buffer_meters?, latitude?, longitude? }. Omit buffer_meters to fit the project parcels; the response returns the drawn extent as extent_feet.
site_mapreturns a sheet-ready PDF locator exhibit: parcel boundaries over aerial imagery with street labels, scale bar and north arrow.road_labelsstates whether street names actually landed.aerialreturns the bare imagery as PNG plus ageoreferenceblock:crs,bbox_web_mercator,bbox_wgs84,image_size_px, andworld_filetext to save beside the image underworld_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. Maps need parcel geometry only, so they work before ordinance bootstrap finishes; the artifact_id remains downloadable through GET /v1/projects/{project_id}/artifacts/{artifact_id}.