The Zippy Lawn Mapping API
Everything in our tool reads and writes one object — the Site Profile: the lawn's polygons and area, zones, slope, RTK sky view, a cellular estimate, and the mower recommendation built from them. This page and the machine descriptions below are how you find your way around it.
Base URL: https://zippy-site-profiler-production.up.railway.app
Machine discovery
Start at the API catalog (RFC 9727) — it links the OpenAPI description, these docs, and the status endpoint. The same catalog is served on the API host itself.
| URL | Type | What it is |
|---|---|---|
zippylawnz.us/.well-known/api-catalog | application/linkset+json | RFC 9727 API catalog — machine index of our APIs (also served on the API host) |
zippy-site-profiler-production.up.railway.app/openapi.json | application/openapi+json | OpenAPI 3.1 description of every published endpoint |
zippy-site-profiler-production.up.railway.app/health | application/json | API liveness — the catalog's status link |
zippylawnz.us/llms.txt | text/plain | LLM-facing index of this site's content (llmstxt.org format) |
Auth: public reads, customer-owned writes
Public endpoints need no key. Everything else is gated by a Clerk session token
(Authorization: Bearer …) that belongs to a signed-in Zippy customer — sign-in happens in
the app, and gated endpoints act only on that customer's own profiles. There is no
self-serve API-key issuance: the API exists to serve our customers' lawns, not as a general platform.
Public endpoints
| Method | Path | What it does |
|---|---|---|
GET | /health | Liveness check — returns { ok: true }. |
GET | /api/geocode/reverse?lat=&lng= | Reverse-geocode a coordinate to street-address candidates. |
GET | /api/gnss/tle | GNSS satellite TLE catalog (GPS, GLONASS, Galileo, BeiDou) — cached CelesTrak proxy behind the live sky-view plot. |
GET | /api/share/{shareId} | A customer-shared Site Profile, contact details stripped. |
GET | /api/proposal/{shareId} | A proposal shared with a customer. |
GET | /api/neighborhood/{slug} | Public payload behind a neighborhood street page (opt-in members only). |
POST | /api/careers/apply | Door-to-door sales screener submission (rate-limited). |
Gated endpoints Clerk bearer token
| Method | Path | What it does |
|---|---|---|
POST | /api/profile | Save the signed-in customer's Site Profile. |
GET | /api/profiles | List the caller's saved profiles. |
GET | /api/profile/{id} | Read one of the caller's profiles. |
POST | /api/analyze | Terrain and sun analysis for a saved profile — cached by profileId. |
POST | /api/viability | RTK sky-view + cellular viability per zone. Cellular is prediction-only: estimated, confirmed on site. |
POST | /api/chat | Ask the assistant about a saved profile — grounded in its measured-vs-predicted fields. |
Full request/response shapes live in the OpenAPI description. Internal admin, webhook, and cron routes are not part of the published API.
The honesty model
Every estimated field in a Site Profile carries source and confidence, and the
whole profile is preliminary until we verify it with the customer on a call. If you're building
on this data, keep those labels attached: "predicted" and "measured" are different claims, and cellular
signal is never more than an estimate until someone stands on the lawn.