HTTP QUERY Method Explained: Safe Read-Only Requests with a Body

In June 2026 the IETF published RFC 10008, which defines QUERY — a new HTTP method for read-only operations that carry their inputs in the request body. If you have ever sent a POST request to search an API because your filter JSON would not fit in a URL, QUERY is the protocol-level answer you were missing.

QUERY is safe and idempotent. Intermediaries can cache it. Clients can retry it after a timeout without worrying about duplicate side effects. The specification is a Proposed Standard authored by Julian Reschke, James M. Snell (Cloudflare), and Mark Bishop (Akamai) — a signal that CDN and edge infrastructure will likely lead framework adoption.

What is the HTTP QUERY method?

The HTTP QUERY method asks a server to process enclosed request content in a safe, idempotent way and return the result. Unlike GET, which retrieves a representation of the URI itself, QUERY tells the target resource to run a query operation scoped to that resource. The body and its Content-Type define the query; the server decides how to execute it.

The server responds with 200 OK and the query results in the response body — same shape you would expect from a well-designed GET, but the inputs travelled in the body instead of the query string.

Why HTTP needed QUERY

GET works beautifully for simple lookups. It is safe, idempotent, and cache-friendly by design. But GET has practical limits that every API team hits eventually.

• URL length ceilings vary across proxies, gateways, and browsers — HTTP recommends supporting at least 8,000 octets, but that is a floor, not a guarantee across your full request path.
• Complex filters — nested JSON, SQL fragments, analytics dimensions — encode poorly into query strings and become unreadable fast.
• Request URIs show up in access logs, browser history, and bookmarks more often than request bodies do, which is a privacy problem when queries contain PII or credentials.
• Every unique combination of query parameters becomes its own URI, which muddies resource identity and makes cache keys harder to reason about.

Teams responded by using POST for read-only searches. POST accepts a body, but the protocol does not mark the operation as safe. Caches treat POST conservatively. Retries are risky because POST is not guaranteed idempotent. Nothing in the method name tells an operator, a WAF, or a monitoring dashboard that you are only reading data.

HTTP QUERY vs GET vs POST

RFC 10008 includes a comparison table. Here is the decision matrix in plain language for API designers.

• GET — Use when inputs are short, non-sensitive, and fit comfortably in the URI. Still the default for simple retrieval.
• QUERY — Use when inputs are large, structured, or sensitive, but the operation must not change server state. Ideal for search, reporting filters, analytics queries, and GraphQL read operations.
• POST — Use when the operation may create or mutate state, when idempotency is not guaranteed, or when you need transactional semantics.

• Safe — GET: yes · QUERY: yes · POST: potentially no
• Idempotent — GET: yes · QUERY: yes · POST: potentially no
• Request body — GET: no defined semantics · QUERY: expected · POST: expected
• Cacheable — GET: yes · QUERY: yes · POST: limited to future GET/HEAD
• URI for the query itself — GET: yes (by definition) · QUERY: optional via Location · POST: no

Why not just send a body with GET?

Developers have asked for GET-with-body for decades. The IETF deliberately did not extend GET because the deployed internet already handles GET bodies inconsistently. Some proxies strip them. Some servers ignore them. Some frameworks reject them outright. Standardizing that behaviour would have broken existing infrastructure.

A new method was the safer path. QUERY gives everyone a clean signal: this request has a body, and that body is part of a read-only operation. No ambiguity, no guessing what the middlebox did to your payload.

The Accept-Query response header

Servers can advertise QUERY support with the Accept-Query response header, which lists the query content media types the resource accepts. Clients can discover this via OPTIONS or HEAD before sending a full QUERY request.

If a client sends an unsupported Content-Type, the server should respond with 415 Unsupported Media Type and can include Accept-Query to guide correction. Missing Content-Type fails with 4xx — servers must not sniff the body to infer a type. Syntactically valid but semantically invalid queries map to 422 Unprocessable Content.

Content-Location, Location, and stored queries

One of QUERY's most useful features is how servers can assign URIs to queries and their results, turning ephemeral searches into addressable resources.

Content-Location — fetch these results again

A successful QUERY response may include Content-Location pointing to a URI where a subsequent GET retrieves the same result set. Useful when results are expensive to compute and you want a bookmarkable snapshot.

Location — repeat this query without resending the body

Location identifies an equivalent resource: a URI where GET replays the same query logic without the client resubmitting the body. If that URI expires, the client falls back to the original QUERY request with the saved payload.

303 See Other — defer and redirect

For heavy queries, a server can respond with 303 See Other and a Location header. The client follows with GET to retrieve pre-generated results. Unlike POST, QUERY redirects do not get silently converted to GET in ways that drop the original semantics — the spec is explicit that POST-to-GET redirect exceptions do not apply to QUERY.

Caching, retries, and conditional requests

QUERY responses are cacheable under HTTP caching rules. The cache key must incorporate request content and related metadata — not just the URI. Caches may normalize semantically equivalent bodies (for example, reordering JSON keys) to improve hit rates, unless the client sends a no-transform directive.

Because QUERY is idempotent, automatic retries after connection failures are safe — a property POST read endpoints never had. Conditional requests (If-None-Match, If-Modified-Since) work the same as they would for GET against the equivalent resource.

Where QUERY changes API design today

Several patterns that currently abuse POST are natural QUERY candidates.

• GraphQL read operations — most GraphQL servers accept queries via POST because query strings exceed URL limits. QUERY preserves safe semantics at the HTTP layer while keeping the full query document in the body.
• Report and dashboard filters — multi-dimensional analytics payloads with date ranges, segments, and drill-downs that no reasonable URL can hold.
• Enterprise search — faceted search with dozens of filters, often containing proprietary or regulated data that should not appear in access logs.
• AI-powered retrieval — RAG pipelines and semantic search endpoints where the query embedding or filter object is a structured JSON blob.
• SQL-over-HTTP and JSONPath APIs — media types like application/sql and application/jsonpath appear directly in RFC examples.

Security and CORS considerations

QUERY inherits standard HTTP security considerations. Two points deserve early attention in browser-facing APIs.

• CORS preflight — QUERY is not a CORS-safelisted method. Cross-origin browser clients will trigger a preflight OPTIONS request before the QUERY itself. Plan for the extra round trip in latency-sensitive UIs.
• Sensitive data in URIs — when QUERY creates temporary result URIs via Location or Content-Location, those URIs must not embed sensitive portions of the original request content.
• Cache normalization risk — incorrect cache normalization can produce false-positive cache hits. Test with your CDN configuration before enabling QUERY caching in production.

How to prepare your stack for QUERY

RFC 10008 is final, but broad client and framework support will roll out gradually. A sensible adoption path for API teams in 2026:

1. Audit read-only POST endpoints — list every POST that does not mutate state. These are your first QUERY migration candidates.
2. Add Accept-Query to discovery responses — even before full QUERY support, document intended media types on OPTIONS/HEAD.
3. Implement QUERY alongside POST temporarily — accept both during a deprecation window so existing clients keep working.
4. Update API gateways and WAF rules — ensure QUERY is allowed and logged with body-aware policies where needed.
5. Watch curl, fetch(), nginx, Envoy, Cloudflare, and your framework of choice — edge support from Akamai and Cloudflare co-authors suggests CDN layers may land first.

Frequently asked questions about HTTP QUERY

Is HTTP QUERY officially standardized?

Yes. RFC 10008 was published in June 2026 as an IETF Proposed Standard (Standards Track). The canonical specification is at rfc-editor.org/info/rfc10008.

Can QUERY replace all POST requests?

No. QUERY is only for safe, idempotent read operations. Creating records, processing payments, or any state-changing action still belongs on POST, PUT, PATCH, or DELETE.

Does QUERY require a request body?

The specification expects one. The query content and its Content-Type together define the operation. Servers must reject requests with missing or inconsistent Content-Type values.

Was QUERY called something else during development?

Early drafts used SEARCH, drawing from WebDAV search extensions. The working group chose QUERY because it aligns with the URI query component and describes a general read-only operation rather than a search-specific one.

How does QUERY affect GraphQL APIs?

GraphQL query and subscription operations are read-only at the protocol level. Moving them from POST to QUERY makes that explicit to caches, proxies, and observability tooling — without changing the GraphQL document format itself.

The bottom line for engineering leaders

QUERY is the most meaningful addition to HTTP method semantics since PATCH became mainstream. It does not replace GET for simple reads or POST for writes. It gives API teams a first-class way to say: this request is large, structured, and read-only — treat it accordingly.

If your platform already sends POST for search, reporting, or GraphQL reads, start mapping those endpoints now. The specification is done; the ecosystem is catching up. Teams that align their API contracts early will spend less time retrofitting caches, gateways, and client SDKs later.