Consider QUERY for searches that do not fit in a URL

Complex searches often outgrow a query string: long filter lists, nested conditions, or inputs that should not end up in logs. Teams then switch to POST /orders/search, which works but tells caches and clients nothing about safety, so the request cannot be retried or cached automatically.

RFC 10008 (June 2026) defines the QUERY method: the query goes in the request body, and the request is safe and idempotent, and cacheable with the body as part of the cache key.

• Use it when input is too large or too sensitive for a URI.
• Advertise supported query formats with the Accept-Query response header.
• Keep using GET for short, simple queries.

Support is new: check that your server framework, proxies and client libraries handle the method before you rely on it, and keep a POST fallback for older clients if needed. OpenAPI 3.2 can describe QUERY operations.

QUERY /orders
Content-Type: application/json
Accept: application/json

{ "status": ["paid", "shipped"], "placed_after": "2026-09-01T00:00:00Z", "total_gt": "100.00" }