Free Grass Identifier: Identify Your Grass Type by Photo

The policy

The current API version is v1; canonical paths live under /api/v1/. Unversioned /api/* paths are an alias of v1 and behave identically.
Within a version, changes are additive only: new endpoints, new optional parameters, and new response fields. Existing fields, parameters, status codes, and semantics do not change.
Breaking changes ship only under a new version prefix (/api/v2/). The previous version keeps working for at least 6 months after its successor ships.
A deprecated endpoint announces itself at least 90 days before removal with Deprecation and Sunset response headers (RFC 9745 and RFC 8594) and a Link header with rel="deprecation" pointing at the migration note, and the OpenAPI document marks the operation deprecated: true with that note.
Version and deprecation status are machine-checkable: every /api response carries X-API-Version, https://whatgrassisthis.com/openapi.json always describes the current version and lists any scheduled sunsets under x-api-versioning.deprecations, and the policy itself lives at https://whatgrassisthis.com/developers/versioning.

Currently deprecated endpoints

None. Every operation in /openapi.json is current, and no Sunset date is scheduled. When one is, it appears here, in the spec under x-api-versioning.deprecations, and on the endpoint's own responses at least 90 days ahead.

Response headers

Header	Sent on	Meaning
`X-API-Version`	Every /api response	The version that served the call (currently v1).
`RateLimit`	Every counted public-API response	IETF structured field: policy name, requests remaining (r), seconds until reset (t).
`RateLimit-Policy`	Every public-API response	IETF structured field: policy name, quota per window (q), window seconds (w).
`X-RateLimit-Limit / -Remaining / -Reset / -Policy`	Same as above	Legacy form of the two fields above; reset is Unix seconds.
`Retry-After`	HTTP 429 only	Seconds to wait before retrying.
`Deprecation`	Deprecated endpoints	RFC 9745 date (@unix seconds) the deprecation was announced.
`Sunset`	Deprecated endpoints	RFC 8594 HTTP-date after which the endpoint stops responding; at least 90 days after Deprecation.
`Link rel="deprecation"`	Deprecated endpoints	URL of the migration note.

A normal response

HTTP/1.1 200 OK
X-API-Version: v1
RateLimit: "public:weather";r=57;t=41
RateLimit-Policy: "public:weather";q=60;w=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1756600000
X-RateLimit-Policy: 60;w=60

Over the limit

HTTP/1.1 429 Too Many Requests
Retry-After: 13
RateLimit: "public:weather";r=0;t=13
RateLimit-Policy: "public:weather";q=60;w=60
Content-Type: application/json

{ "error": "rate_limited", "code": "rate_limited", "message": "...", "hint": "Wait 13 seconds, then retry. ..." }

A deprecated endpoint

HTTP/1.1 200 OK
X-API-Version: v1
Deprecation: @1798761600
Sunset: Thu, 01 Apr 2027 00:00:00 GMT
Link: <https://whatgrassisthis.com/developers/versioning>; rel="deprecation"; type="text/html"

How to integrate safely

Call the versioned paths under /api/v1/ and assert X-API-Version on the response.
Read RateLimit before sending the next request; when r reaches 0, wait t seconds. On 429, honor Retry-After.
Treat any Deprecation header as a signal to follow the Link rel="deprecation" URL before the Sunset date.
Ignore response fields you do not recognize; new fields may appear at any time within a version.
A superseded version keeps working for at least 6 months after its successor ships.

Full contract: /openapi.json. Everything else for developers and agents: /developers. Questions: support@whatgrassisthis.com.