Developer resources

Folia is a free web tool for site suitability, not a full data-as-a-service API. This page is the honest map of what an agent, scanner, or scripted pipeline can call directly today, and what still lives behind the human-facing tool at /site. If you need a shape not listed here, email [email protected] and we will tell you what is real vs. planned.

Machine-readable resources

• OpenAPI 3.1 spec for the public endpoints below. application/vnd.oai.openapi+json; version=3.1.
• API catalog per RFC 9727. application/linkset+json with each API's service-desc, service-doc, and status links.
• llms.txt: what Folia is, when an agent should reach for it, and the URL patterns to use when citing.
• robots.txt: crawler rules and the Content-Signal policy (search=yes, ai-input=yes, ai-train=no).
• auth.md: the "how do agents authenticate" answer (they don't — everything below is public).
• sitemap.xml: every canonical URL, including one per variety.
• security.txt for coordinated disclosure.

Public API endpoints

Two endpoints are documented and committed to as stable public contracts. Both are anonymous (no keys, no OAuth). Both return JSON.

GET /api/uptime

Cheap probe. Returns 200 when Folia is serving and its own database answers, 503 otherwise. No third-party dependencies. Suitable for external monitors polling every minute.

{ "checks": [...], "up": true }

GET /api/health

Full public-data-source probe. Reports the status of every upstream dataset Folia relies on: USGS 3DEP + LiDAR, USDA SSURGO, NOAA, PRISM, FEMA, state parcel layers. Each probe uses that source's real timeout, so a slow response here does not mean Folia is down; it means one of the upstream government hosts is having a bad afternoon.

{ "sources": [
  { "id": "usgs-3dep", "status": "up", "ms": 420, ... },
  ...
] }

Errors

Both endpoints return JSON on any error (not the app-shell HTML). Shape:

{
  "error": "method_not_allowed",
  "message": "Only GET, HEAD is supported on this endpoint.",
  "hint": "Retry with one of: GET, HEAD.",
  "status": 405
}

Content negotiation on marketing pages

Send Accept: text/markdown on any of /, /library, /about, /contact, /privacy, /terms, /methodology, /faq to get a hand-authored markdown variant. Any other path with Accept: text/markdown returns a markdown 404 recovery body pointing at the sitemap and llms.txt.

Response headers on the markdown variant: Content-Type: text/markdown; charset=utf-8, Vary: Accept, Accept-Encoding, Cache-Control: private, no-store.

What is NOT a public API today

• Site-suitability queries. Ranking a specific address against the six Crop Intelligence Libraries runs at /site in the browser. There is no address-in, JSON-out endpoint. If your use case is agent-driven site analysis, please write and describe it.
• The Crop Intelligence Libraries. Every variety has an indexable human page at https://www.folia.farm/library/{crop}/{slug}, and each crop has a hub at https://www.folia.farm/library/{crop}. The underlying JSON is not published as an API today. For programmatic scraping, please use the sitemap.
• Save / account operations. Behind Supabase magic-link auth; not part of any public agent surface.

Rate limiting

By IP and User-Agent. The public endpoints above are cheap; a monitor polling /api/uptime once a minute is welcome. If you plan to hit /api/health harder than once per minute, please write first, because heavy polling propagates a request storm to every upstream government host.

Getting in touch

General: [email protected]. Security: same address with "security" in the subject; machine-readable at /.well-known/security.txt.