QUERY New in 2026
A safe, idempotent method for sending complex read queries in a request body instead of a URL.
HTTP's first new method in 16 years
Every REST API eventually grows a POST /search endpoint. Not because POST is the right method for reading data, but because GET can't carry a request body, and once your filters get complicated — nested objects, arrays, a JSONPath expression, a full-text query — they stop fitting cleanly in a URL. So developers reach for POST, and lose GET's guarantees in the process: caches ignore it, retries aren't provably safe, and nothing in the protocol tells an intermediary "this is just a read."
QUERY, standardized in RFC 10008 (published June 15, 2026), closes that gap. It's the first genuinely new HTTP method since PATCH in 2010 — and unlike PATCH, which filled a narrower need, QUERY fixes something almost every API author has personally worked around. Early drafts of the proposal used the name SEARCH before the HTTP working group settled on QUERY, because it "captures the relation with the URI's query component" rather than implying one specific use case. The spec took eleven years from first draft to Proposed Standard — HTTP moves slowly, which is exactly why it's worth paying attention when it does move. It's authored by Julian Reschke, James Snell (Cloudflare), and Mike Bishop (Akamai) — the CDN co-authorship is a good signal for where infrastructure-level support lands first.
What it does
QUERY takes GET's safe, idempotent, cacheable semantics and gives them a request body — the one thing GET was missing. You send structured data (JSON, or whatever Content-Type the endpoint accepts) describing what you want back, and the server treats the whole exchange as a read: safe to retry, safe to cache, safe for a crawler or proxy to repeat without asking permission.
Semantics
| Property | Value | Why it matters |
|---|---|---|
| Safe | Yes | Explicitly a read — no state change expected |
| Idempotent | Yes | Retrying is always safe |
| Cacheable | Yes | Responses can be cached, but the cache key must include the request body — see below |
| Request body | Yes | The query itself, in whatever format Content-Type declares |
| Response body | Yes | The result of processing the query |
Syntax & example request
QUERY /users HTTP/1.1
Host: example.org
Content-Type: application/json
Accept: application/json
{"role": "admin", "sort": "name", "page": 1}
HTTP/1.1 200 OK
Content-Type: application/json
[{"id": 1, "name": "Ada", "role": "admin"}]
Compare that to the POST-for-reads workaround it replaces:
POST /feed HTTP/1.1
Content-Type: application/json
{"q": "foo", "filters": {"tags": ["ai", "api"]}, "limit": 10}
Mechanically almost identical to the QUERY version — the difference is entirely in what the method name promises to caches, proxies, and clients about safety and retry behavior.
curl example
curl -X QUERY https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"role": "admin", "sort": "name", "page": 1}'
Any HTTP client that allows arbitrary method strings (which is most of them) can send QUERY today — no special library support required, just a server on the other end that understands it.
Common status codes returned
- 200 OK — query processed, results in the response body → see 200
- 204 No Content — query matched nothing, or intentionally empty result → see 204
- 400 / 415 / 422 — servers must reject a QUERY with a missing or inconsistent
Content-Typewith one of these → see 400, 415, 422 - 404 Not Found — target resource doesn't support querying, or doesn't exist → see 404
QUERY vs GET vs POST
| GET | POST | QUERY | |
|---|---|---|---|
| Safe | Yes | No | Yes |
| Idempotent | Yes | No | Yes |
| Has a body | No (ignored in practice) | Yes | Yes |
| Cacheable | Yes | No by default | Yes, cache key includes body |
| CORS-safelisted | Yes | Only for simple requests | No — always preflighted |
| Best for | Simple params in the URL | Writes and processing | Complex read queries |
The one thing QUERY doesn't get for free: it's not a CORS-safelisted method, so any cross-origin QUERY from browser JavaScript triggers a preflight OPTIONS request, same as a custom-headers POST would.
How caching actually works with QUERY
This is the part worth reading closely if you run a CDN or reverse proxy. Because the request has no query string to key on, the cache key must incorporate the request body and its metadata — the Content-Type plus the bytes of the body together identify a unique query. A cache that doesn't parse and normalize the body correctly before keying on it will either miss constantly (near-identical bodies treated as always-different) or, worse, collide on requests that only look the same after truncation. Well-behaved caches can normalize JSON bodies (reorder keys, strip insignificant whitespace) to improve hit rates — but that normalization has to be done carefully and consistently, or you get cache poisoning.
Real-world usage
- Structured filter/search endpoints that outgrew GET's URL-length practicality:
QUERY /orderswith a nested filter object instead of a wall of query-string params - RPC-style and JSON-RPC APIs, where every call is structurally a POST today even when it's semantically a read — QUERY gives these HTTP-native caching without a bespoke layer on top
- Analytics and reporting endpoints with large, structured request payloads (date ranges, dimension breakdowns, filters)
- Report builders and dashboards firing large read queries that benefit from GET-like retry safety
Browser & tooling support (as of July 2026)
Adoption is early but moving. The honest state of things right now:
- Node.js — native support for arbitrary HTTP methods (including QUERY) since early 2024, well ahead of the RFC itself
- Go, Rust — standard HTTP clients (
net/http,reqwest) already accept arbitrary method strings, so QUERY works with zero new dependencies - OpenAPI 3.2 — added first-class documentation support for the QUERY method
- Spring (Java) — as of early July 2026, the
RequestMethodenum still doesn't include QUERY; a pull request is in review, but@RequestMappingcan't route it yet - Browsers —
fetch()and XHR can send arbitrary methods, but expect a CORS preflight on every cross-origin call, since QUERY isn't safelisted - WAFs, CDNs, proxies, load balancers — method allowlists written before June 2026 may not recognize QUERY at all; some infrastructure will reject it outright, some will route or inspect it differently than POST until updated
Security considerations
Because QUERY is new, security tooling written against the "usual suspects" (GET, POST, PUT, DELETE, PATCH) may not have rules for it yet — treat this as a fresh surface worth testing explicitly rather than assuming existing WAF rules, CSRF middleware, and rate limiters cover it. CSRF protections in particular are often written in terms of specific unsafe methods; since QUERY is safe, standard CSRF middleware shouldn't need to guard it the way it guards POST/PUT/DELETE — but confirm your framework's CSRF exemption list has actually been updated to recognize QUERY as safe, rather than defaulting to "unknown method, block it" or, worse, "unknown method, allow it unguarded."
If you expose sensitive filters via QUERY, remember the request body — unlike a GET URL — generally isn't logged by default in most access-log configurations, which is actually a privacy improvement over stuffing sensitive filter values into a URL.
Rollout advice
Because method allowlists across proxies, WAFs, and older clients may not recognize QUERY yet, the RFC's own advice (and the emerging community consensus) is a gradual rollout: add QUERY alongside your existing POST-based search endpoint rather than a hard cutover, advertise support via the new Accept-Query response header, and let clients migrate as their tooling catches up.
FAQ
Is QUERY the same as "GET with a body"?
Conceptually, yes — that's the plain-English pitch. Mechanically it's a distinct method rather than an extension of GET, specifically because redefining GET's decades-old behavior everywhere would break existing infrastructure. A new method name was the safer path.
Can I use QUERY today in production?
You can — the RFC is final and several runtimes support arbitrary methods out of the box — but treat June 2026 as day one of the adoption curve. Confirm your framework, reverse proxy, CDN, and WAF actually recognize QUERY (rather than silently misrouting or rejecting it) before relying on it as the only way to reach an endpoint.
Does QUERY replace POST /search entirely?
Eventually, that's the intent — the RFC's authors and early adopters both frame POST /search as a legacy workaround that QUERY was built to obsolete. In practice, expect both to coexist for a while: ship QUERY alongside the POST variant, advertise it via Accept-Query, and let it become the default once tooling fully catches up.
What is the Accept-Query header?
A new response header, also defined by RFC 10008, that lets a resource advertise both that it supports QUERY and which media types it accepts as query formats — similar in spirit to how Allow advertises supported methods or Accept-Patch/Accept-Post advertise supported patch/post formats.
Fun fact
QUERY holds a rare distinction in HTTP history: it's the only method whose current name was chosen specifically to avoid implying a single use case. Earlier drafts under the name "SEARCH" (borrowed from WebDAV, alongside other rejected candidates like "REPORT" and "PROPFIND") were seen as too narrowly tied to full-text search — "QUERY" was chosen because it describes a generic safe-read-with-a-body operation, matching the "query" in a URI's own query component.