HTTP Finally Gets a Third Read Method: Meet QUERY

For almost three decades, developers building read-heavy APIs have had exactly two tools to choose from: GET and POST. Neither one was ever quite right for the job, and most of us just learned to live with the compromise. That changes now.

Why HTTP needed a new method

GET is safe, idempotent, and cacheable — exactly what you want for reading data. But everything has to live in the URL. That's fine for ?page=2&sort=asc, and painful for anything resembling a real search: nested filters, arrays, free-text search terms, geospatial bounds. URL length limits are inconsistent across proxies, load balancers, and CDNs, and query strings tend to get logged in places a request body wouldn't.

POST solves the body problem, but it throws away the safety guarantees. Nothing in the protocol tells an intermediary "this is just a read" — so no automatic retries, no shared caching, no confidence that resubmitting the request won't change something server-side.

QUERY is designed to sit exactly in the gap between the two: a request that behaves like GET (safe, idempotent, cacheable) but carries a structured request body like POST.

What a QUERY request looks like

At a glance, it reads like a POST with a different verb:

QUERY /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "filter": {
    "category": "electronics",
    "price": { "lt": 500 }
  },
  "sort": ["-rating", "price"],
  "limit": 25
}

The server processes the body as a query, not as a mutation, and returns results the same way it would for a GET — including full support for caching headers and conditional requests.

Key features of the QUERY method

• Safe and idempotent by definition. Clients, proxies, and load balancers can retry a failed QUERY request without any risk of duplicating side effects — something you can never safely assume with POST.
• Content negotiation via Accept-Query. A new response header lets a server tell clients which media types it accepts in the QUERY body, similar to how Accept works for responses.
• Results can get their own URI. A server can return a Location header pointing to a GET-able resource for a specific query or result set, making it independently cacheable and bookmarkable.
• Distinct from WebDAV's SEARCH, REPORT, and PROPFIND. Those methods carry WebDAV-specific semantics tied to resource and property management. QUERY is a general-purpose method meant for any part of the web.

GET vs. POST vs. QUERY at a glance

The road to standardization

The idea itself isn't new — the notion of a "safe method with a body" has circulated in the HTTP Working Group since at least 2021. What became RFC 10008 went through fourteen revisions of the draft (draft-ietf-httpbis-safe-method-w-body) and several rounds of IETF Last Call before finally being approved as a Proposed Standard. The authors — Julian Reschke, James M. Snell (Cloudflare), and Mike Bishop (Akamai) — are all veterans of the HTTP specification world, and the HTTPbis working group sponsored the effort through to publication.

Should you start using it?

Not in production just yet, at least not for anything public-facing. As of mid-2026, no major browser implements QUERY natively, and server- and client-library support is still emerging. If you're building an internal API where you control both ends of the wire, you can start experimenting today — most HTTP libraries will happily send an arbitrary method verb with a body, even without dedicated QUERY support.

For public APIs, the realistic path is: watch for support to land in frameworks and reverse proxies over the coming months, and treat QUERY the way you'd treat any new but not-yet-universal web platform feature — feature-detect, fall back to POST, and don't rip out your existing POST /search-style endpoints just yet.

Frequently Asked Questions