HTTP QUERY: The New Request Method Between GET and POST

For the last two decades, "I need a read-only request, but my query is too complex for a URL" has been a lie you tell HTTP twice a day. Either you cram a monster filter into a GET and pray nothing logs the sensitive bits, or you send a POST to an endpoint that is really a search, and surrender caching and safe retries.

In June 2026 the IETF stopped needing that lie. RFC 10008 publishes the QUERY method: a request that is safe and idempotent like GET, carries a body like POST, and can be cached. The spec is the result of the long-running draft-ietf-httpbis-safe-method-w-body work by Julian Reschke, James Snell (Cloudflare) and Mike Bishop (Akamai). It is now registered in the IANA HTTP Method Registry as safe and idempotent.

This post walks through why the gap existed, what QUERY does, how it looks on the wire, and — the part most articles skip — what actually supports it in mid-2026.

The problem: two methods, neither quite right

A GET is safe and idempotent. Caches love it, proxies love it, browsers retry it without fear. But the query lives in the URI, and the URI is a terrible place to put a query:

• URL length limits are a moving target across intermediaries (HTTP recommends supporting at least 8000 octets, but reality varies).
• Every combination of parameters becomes a "distinct resource", which bloats caches and analytics.
• Anything in the URI ends up in access logs, browser history and bookmarks. A medical filter, a private search, a proprietary query — all logged by default.

A POST solves the body problem. But POST is not safe and not idempotent. Retry engines cannot safely replay it, caches refuse to store it, and any generic middleware treats it as a potential state change. So the "POST-as-search" pattern — everywhere, for twenty years — is semantically lying to the infrastructure between you and your server.

QUERY fills exactly that gap.

What QUERY actually is

From the spec: "A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing."

The request content and its Content-Type define the query. The server decides the scope from the target resource. Unlike GET, the response to QUERY is not a representation of the target URI — it is the result of processing the enclosed query.

The important guarantees, straight from RFC 10008:

Because QUERY is safe and idempotent, a client can retry it after a connection failure, and a cache can store and replay it — the two things POST-as-search could never offer.

Servers must fail a QUERY request if Content-Type is missing or inconsistent with the body. A successful query that finds nothing can answer 204 No Content; a 200 OK means the result is in the response content.

How a QUERY request looks on the wire

The canonical example from the RFC:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

The same query that would have been a bloated GET URI is now a body. The URI keeps only the resource scope (/feed); the query travels in the body, out of the logs.

You can use any media type with query semantics — application/json, GraphQL, SQL, JSONPath, an RDF query language. The Content-Type declares which one, and the server must agree.

The escape hatches: Location and Content-Location

RFC 10008 makes sure a QUERY never leaves you trapped in a body-only world. Two response fields bridge back to plain GET:

• Location identifies the equivalent resource for the query — a URI you can GET to repeat the same query without resending the body. Retry-friendly, bookmarkable, cacheable.
• Content-Location identifies the URI of this particular result, so you can share or re-fetch it directly.

This is the feature most likely to carry QUERY through its awkward years. A server can accept a heavy QUERY, do the expensive work once, then hand the client a lightweight GET-able URI for everything after — polling, pagination, cache reads.

Accept-Query: advertising what you speak

The spec also registers the Accept-Query response header. A resource uses it to announce it supports QUERY and to list which query media types it understands:

HTTP/1.1 200 OK
Accept-Query: application/sql, application/jsonpath

Any URI sharing the same path inherits the value. It is a Structured Fields List, and it can be returned on a plain GET too, so a client can discover support before sending its first QUERY. Tools like h3 ship helpers (appendAcceptQuery, requireContentType) for exactly this negotiation.

Security notes worth keeping

• Privacy is the headline win. URIs are far more likely to be logged and processed by intermediaries than request bodies. Sensitive query parameters stay out of access logs. But if a server creates a temporary result URI, that URI must not embed the sensitive parts of the request.
• Cache normalization is a footgun. A cache computes its key from the request content. If it "normalizes" the body differently from how the origin processes it, one user can receive another user's results. Cache keys must incorporate the request content correctly.
• CORS preflight. QUERY is not a CORS-safelisted method. A cross-origin QUERY from a browser triggers an OPTIONS preflight, and your server must answer with Access-Control-Allow-Methods: QUERY.
• Bodies mean body-size limits. A QUERY body is attacker-controllable input; enforce limits and validate it like you would a POST.

What actually supports it today (August 2026)

This is the part everyone wants. Support is real but uneven — here is the honest state:

Server-side, usable now:

• Node.js — QUERY works out of the box since 22.2.0 (the llhttp parser accepts it), and node:http exposes it as a first-class method. Node 24 handles it cleanly. The undici fetch client added QUERY support in 8.6.0.
• Go — net/http treats it like any custom method via http.NewRequest; no standard-library changes were needed.
• h3 (unjs) — first-class app.query() plus the Accept-Query and content-type helpers.
• ASP.NET Core — route it today with MapMethods("/search", ["QUERY"], handler); .NET 10 even exposes HttpMethod.Query on the client side.
• Eclipse Jetty and Apache Tomcat are implementing it; the W3C Linked Web Storage protocol has adopted it for search.
• Express 5 ships an app.query() routing helper (just remember to mount express.json() to populate req.body).
• Fastify accepts QUERY routes out of the box.

Client-side:

• fetch(url, { method: "QUERY", body }) works — the Fetch spec forbids only CONNECT, TRACE and TRACK, so QUERY passes. Write it uppercase: fetch only case-normalizes well-known methods, not new ones.
• No browser supports it natively yet — and an HTML <form> silently falls back to GET, dropping the body. Declarative forms are an open WHATWG issue.
• Browsers do not cache repeated QUERY responses yet, even though the RFC makes them cacheable. That part is unimplemented.

Still missing:

• Not every framework has caught up. Rails' Action Pack still rejects QUERY with a 405 (UnknownHttpMethod) until explicit support lands, and Django, Spring and Laravel routing layers need work too.
• API gateways, WAFs, CDNs and corporate proxies may drop the verb. If you have ever debugged a request dying silently inside a reverse proxy, you already know the species. This is exactly what killed earlier attempts at safe read-with-body methods.

Should you adopt it now?

The honest answer: only where you control both ends. For an internal API, service-to-service traffic, or a server that also speaks QUERY to your own modern client, it is genuinely better — large or structured reads, search and filter endpoints, GraphQL-style queries, geospatial lookups.

For a public-facing API, keep a POST (or GET-serialized) fallback for a while, and detect 405/501 to degrade gracefully. PATCH (RFC 5789, 2010) took years to become universal; QUERY will follow the same curve — server-side first, frameworks next, browsers and forms last.

The escape hatch is designed in: any QUERY can collapse back into a GET the moment it meets infrastructure that never learned the new verb. That is not a compromise — it is the migration path.

Why QUERY and not SEARCH?

The HTTP Method Registry already had safe, idempotent methods with bodies: PROPFIND, REPORT, and SEARCH — all WebDAV-era. Early drafts of this spec literally used SEARCH. The name QUERY won because the alternatives depend on a generic application/xml body, they come from the WebDAV world (which has "mixed feelings" attached), and — the decisive one — QUERY captures the relationship with the URI's own query component.

---

The one-line summary: RFC 10008 is the protocol identity the web's favorite workaround never had — a read-only request that finally carries a body. The semantics are now machine-readable: caches, retry engines and agents can act on what the method declares, not on what your documentation hopes they infer. Start with your internal APIs, keep a fallback in public, and give the infrastructure a couple of years to catch up.