PlantGrail developer resources

This is the PlantGrail machine interface: a small public REST API, an OpenAPI 3.1 document for function calling, Markdown versions of HTML pages, and the curated llms.txt map. No API key is required for the public GET endpoints.

How do I call the PlantGrail API?

Load the OpenAPI document at https://plantgrail.com/openapi.json (or https://plantgrail.com/api/openapi.yaml) and send plain HTTPS GET requests; no key is needed. Every public operation has a unique operationId, a description, typed parameters, and a JSON response schema. PlantGrail does not ship GraphQL; requests to /graphql return a JSON error that points back to this REST spec.

Public endpoints

  • GET /api/health: liveness JSON for crawlers and monitors (operationId: getHealth)
  • GET /api/plants: paginated plant index from the knowledge base (operationId: listPlants)
  • GET /api/articles.json: article feed used by learning clients (operationId: listArticles)

Example: GET https://plantgrail.com/api/plants?limit=20&offset=0 with Accept: application/json.

Authentication

Public GET endpoints above are unauthenticated. Course progress, certificates, checkout callbacks, and the sales proxy require secrets and are not part of the public OpenAPI document. Do not send bearer tokens to /api/health or /api/plants; they are ignored.

Rate limits

Public API responses include RFC RateLimit and RateLimit-Policy headers plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. The default public policy is 60 requests per 60 seconds per client IP. HTTP 429 includes Retry-After. Slow down when remaining approaches zero instead of retrying in a tight loop.

JSON errors

API errors are JSON objects with error.code, error.message, and error.resolution. HTML error pages are not used for /api/* misses. Unknown API paths return 404 JSON, not the marketing homepage.

Markdown content negotiation

HTML pages honor Accept: text/markdown and return Content-Type: text/markdown; charset=utf-8 with Vary: Accept, Accept-Encoding so caches do not mix HTML and Markdown. Browsers that send a standard HTML Accept header still receive the visual site.

Webhooks

PlantGrail has no public inbound webhook product for third-party apps. The /api/webhook routes are private billing callbacks and must not be called by agents. Use the public GET API and llms.txt instead.

Related PlantGrail files