Developers & Agents

Plant Sale Catalogue API

A free, public, read-only JSON API over the whole catalogue — 1106 plants, 34 collections and 5 region guides. Built for AI agents, skills, MCP servers and integrations.

Base URL

https://plantsale.com.au/api/v1

Quick start

# The whole catalogue, one fetch (every plant, every facet):
curl https://plantsale.com.au/api/v1/plants.json

# One plant in full:
curl https://plantsale.com.au/api/v1/plants/howea-forsteriana-kentia-palm.json

# What can I filter on? (fields, values, counts)
curl https://plantsale.com.au/api/v1/facets.json

# Every drought-tolerant plant, pre-filtered:
curl https://plantsale.com.au/api/v1/browse/water/drought-tolerant.json

# Machine-readable spec — feed this to an MCP/skill/client generator:
curl https://plantsale.com.au/api/v1/openapi.json

Endpoints

Method	Path	Description
`GET`	`/api/v1/index.json`	Discovery document — counts, resource URLs, licence.
`GET`	`/api/v1/openapi.json`	OpenAPI 3.1 spec — point a client/MCP generator here.
`GET`	`/api/v1/plants.json`	Catalogue index — all 1106 plants as summary records (every facet).
`GET`	`/api/v1/plants/{slug}.json`	Full detail for one plant: editorial, care, seed data, links.
`GET`	`/api/v1/facets.json`	Controlled vocabulary — valid filter fields, values and counts.
`GET`	`/api/v1/browse/{facet}/{value}.json`	Pre-filtered listing — plants holding one facet value.
`GET`	`/api/v1/collections.json`	Curated collections (promoted multi-facet intersections).
`GET`	`/api/v1/collections/{slug}.json`	One collection with members expanded to cards.
`GET`	`/api/v1/regions.json`	Region guides ("Plants for {city}").
`GET`	`/api/v1/regions/{slug}.json`	One region with suited plants expanded to cards.

Filtering

The API is static, so filtering is done two ways. For a single facet value, fetch the pre-built listing at /browse/{facet}/{value}.json. For multi-facet queries ("native, drought-tolerant, under 1 m"), fetch /plants.json once and filter the records client-side — every plant carries its full facet set. Combine facets with AND across fields and OR within a field. Discover valid fields and values from /facets.json.

Authentication

None. The API is public and key-less. Every record here is already published on the public, indexable website, so there is nothing to gate. This is also the safe choice for agents: with no API key, there is no secret to leak into a model's context window, no key to rotate, and nothing to revoke. Just call the endpoints.

If you later need to meter or restrict access, the recommended path is a Cloudflare gateway in front of /api/* that checks a bearer token — keys stored as platform secrets, never inline in prompts. The full strategy, including a ready-to-enable middleware, is documented in docs/13-public-api.md in the repository.

Rate limits & caching

No hard rate limit today. Responses are static and CDN-cached (Cache-Control: public, max-age=3600) with permissive CORS (Access-Control-Allow-Origin: *), so you can call them from a browser, a server or an agent. Please cache on your side and avoid hammering — the data changes only on redeploy.

For agent & skill builders

Start from https://plantsale.com.au/api/v1/openapi.json. It describes every endpoint, parameter and response schema in OpenAPI 3.1, so you can generate a typed client, an MCP server or an agent skill without hand-writing request code. The vocabulary in /facets.json tells the agent which filters and values are valid before it builds a query.

Licence

Catalogue data is offered under CC BY 4.0 — free to use with attribution to Plant Sale (plantsale.com.au).