Does HTTP finally have GET with a body? Almost — RFC 10008 (The HTTP QUERY Method, published June 15, 2026) standardizes QUERY: the first new HTTP method in 16 years since PATCH (RFC 5789, 2010).
X/Grok trending framed it simply: no more stuffing complex search filters into 800-character URLs; no more POST for read-only search. The RFC authors — Julian Reschke, James Snell (Cloudflare), Mike Bishop (Akamai) — spent a decade in the HTTPBIS working group getting there.
TL;DR — what people are asking
| Question | Answer |
|---|---|
| What is QUERY? | Safe + idempotent + cacheable request with a body describing the query |
| GET vs QUERY? | GET = params in URL; QUERY = params in body (no URL length pain) |
| POST vs QUERY? | POST = may mutate state; QUERY = read-only semantics for the target resource |
| First since when? | PATCH (2010) — QUERY registered June 2026 |
| Header to discover? | Accept-Query lists supported query media types |
| Browser catch? | CORS preflight required — QUERY is not safelisted |
| Zero writes? | HTTP-safe ≠ DB-read-only — logging and temp URLs still happen |
The problem QUERY solves
Classic list/search pattern today:
GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
Host: example.org
Works until it does not:
| GET pain | Why it hurts |
|---|---|
| URL size | RFC 9110 recommends supporting ~8000 octets — unknown limits through proxies |
| Encoding overhead | Nested JSON filters in query strings are ugly and lossy |
| Logging & bookmarks | URIs show up in logs, analytics, browser history |
| Resource explosion | Every filter combo becomes a distinct cache key / "resource" |
Teams then abuse POST for reads:
POST /feed HTTP/1.1
Host: example.org
Content-Type: application/json
{"q":"foo","filters":{"tags":["ai","api"]},"limit":10}
POST works mechanically — but retries are scary, caches ignore it for reads, and intermediaries cannot tell this is a safe search without out-of-band docs.
QUERY spans the gap:
QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/json
Accept: application/json
{"q":"foo","filters":{"tags":["ai","api"]},"limit":10}
Same body affordance as POST; safe and idempotent semantics as GET.
RFC 10008 method comparison (official table)
| GET | QUERY | POST | |
|---|---|---|---|
| Safe | yes | yes | potentially no |
| Idempotent | yes | yes | potentially no |
| Request body | no defined semantics | expected | expected |
| Cacheable | yes | yes | only for future GET/HEAD in some cases |
| URI for query itself | yes (by definition) | optional (Location) | no |
| URI for result | optional | optional (Content-Location) | optional |
Source: RFC 10008 Section 1, Table 1.
How QUERY works in practice
1. Content types are the query language
The body + Content-Type define the query. RFC examples include:
application/x-www-form-urlencodedapplication/sqlapplication/jsonpath(RFC 9535)application/xslt+xml
Servers MUST reject missing or inconsistent Content-Type (400, 415, 422 as appropriate).
2. Discover support with Accept-Query
HEAD /contacts HTTP/1.1
Host: example.org
HTTP/1.1 200 OK
Accept-Query: application/x-www-form-urlencoded, application/sql
Or check OPTIONS → Allow: GET, QUERY, HEAD.
3. Repeat without resending the body
Successful QUERY responses may include:
Content-Location— GET this URI for these resultsLocation— GET this URI to re-run the same query later
That lets clients move from QUERY → GET for polling and conditional requests (If-None-Match, If-Modified-Since).
4. Caching is harder than GET
Caches may store QUERY responses, but the cache key must include the request body and metadata. Mis-normalization = false cache hits. Mitigation: Location URIs clients can GET instead.
5. CORS preflight
Per Fetch spec, QUERY is not CORS-safelisted — browsers will preflight cross-origin QUERY. Plan for OPTIONS handling in public APIs.
Example: contacts search (from RFC appendix)
QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json
select=surname,givenname,email&limit=10&match=%22email=*@example.*%22
HTTP/1.1 200 OK
Content-Type: application/json
[
{"surname":"Smith","givenname":"John","email":"smith@example.org"},
{"surname":"Jones","givenname":"Sally","email":"sally.jones@example.com"}
]
For short queries, RFC itself says: if it's this small, use GET.
What QUERY is not
"Safe" does not mean free or write-free
RFC defines safe as: no change to the target resource's state. Servers may still:
- Write temporary stored-query or stored-result resources
- Log request bodies (prefer QUERY over GET when sensitive filters should not hit URL logs — RFC security section)
- Hit databases that read but still generate load, replicas, and billing
@yacineMTB on X (replying to adoption threads): "Queries, unfortunately, are not 0 writes for the vast majority of cases." Correct at the infrastructure layer.
Not a replacement for GraphQL or gRPC
QUERY standardizes HTTP semantics for search-shaped REST endpoints. It does not replace:
- GraphQL — schema-wide query language
- MCP tool calls — agent protocols (MCP guide)
- POST mutations — creates, jobs, side effects
It does give OpenAPI designers a first-class verb for POST /search anti-patterns.
Migration patterns for API teams
| Today | Tomorrow |
|---|---|
POST /api/users/search | QUERY /api/users |
GET /api/logs?filter=... (10KB URL) | QUERY /api/logs + JSON body |
POST /reports/run (read-only) | QUERY /reports |
| GraphQL POST (unchanged) | Still GraphQL |
Checklist before shipping QUERY:
- Idempotent handler — same body → same logical result (modulo data changes)
- No target-resource mutation — writes go to POST/PUT/PATCH
- Expose
Accept-Queryon resources that support multiple query formats - CDN/proxy config — allow
QUERYmethod; verify cache key includes body - CORS — add OPTIONS +
Access-Control-Allow-Methods: QUERY - Client libraries — most need custom method string until native support
Adoption timeline (realistic)
| Layer | June 2026 status |
|---|---|
| IETF / IANA | ✅ RFC 10008 Proposed Standard |
| curl / HTTP clients | Manual --request QUERY possible where supported |
| Frameworks (Express, FastAPI, etc.) | Patch incoming; route registration varies |
| API gateways (Cloudflare, Akamai) | Authors' employers — watch vendor blogs |
Browsers fetch() | No default yet; preflight either way |
| OpenAPI 3.x | Community extensions / 3.1 query verb discussions |
Vincent Eliezer's X quip — "Even internet protocols are shipping faster than GTA 6" — is fair. Standards ship ≠ your stack supports it tomorrow.
FAQ — quick answers
Why not SEARCH? Early drafts used SEARCH (WebDAV heritage). RFC appendix explains QUERY won — clearer relation to URI query components, less WebDAV baggage, explicit media-type semantics.
Can I use QUERY from Claude Code / agents? Yes once your HTTP client allows custom methods — same as any REST surface agents call via MCP or tools. Document idempotency so agents can retry safely.
Does QUERY help AI search APIs? Indirectly — fat retrieval filters (RAG metadata, JSONPath over corpora) fit QUERY's body model better than GET. Pair with GEO content strategy on the data you expose, not the HTTP verb alone.
How should you test QUERY through a real deployment stack?
Test every hop that handles the request: client, reverse proxy, gateway, application, and cache. A development server accepting a custom method does not establish that the public endpoint accepts it. Send a small request through the same hostname and authentication path a real client will use, then compare the response with a direct application request.
Use two bodies that differ in a meaningful filter. If both return the same cached response unexpectedly, investigate the cache key before enabling caching. RFC 10008 describes body-sensitive caching; a gateway configured only around URL-based keys cannot safely inherit a GET-style rule without considering request content.
Also test unsupported media types, malformed content, excessive payload sizes, and missing authorization. A safe method still needs ordinary API controls. Expensive queries can exhaust resources without changing the target resource, so set limits on result size, query complexity, and execution time according to your service's needs.
What should an agent-facing QUERY tool expose?
An agent tool should describe the query language, required fields, result shape, and error cases. Do not expose arbitrary SQL simply because the HTTP example permits a SQL media type. The application still determines which operations and data the caller may access. A constrained filter schema is often easier to validate and document.
Separate a query's logical identity from its current result. A repeat query may return new data because the underlying dataset changed. Idempotency describes request semantics; it does not promise an immutable response forever. If clients need a snapshot, document how the returned result URI behaves and how long that result remains available.
How can you migrate without breaking existing clients?
Keep the existing read endpoint while introducing QUERY for clients that support it. Route both through the same query validation and execution logic where possible. Compare outputs for representative filters before making either path the default. Differences in pagination, defaults, or authorization should be treated as migration bugs rather than dismissed as method details.
Publish explicit capability guidance instead of assuming all SDKs understand the new method. Show an example request, the supported content type, and the expected response. Give clients a documented fallback when an intermediary rejects QUERY. Avoid automatic fallback after an ambiguous failure unless you know the first request cannot cause unintended effects in your implementation.
Which logs help troubleshoot the migration?
Record method, request identifier, status, duration, and a safe summary of the query shape. Bodies can contain sensitive filters, so moving data out of the URL does not eliminate logging exposure. Review application and proxy logging separately, including error traces that may dump request payloads.
Measure method rejection and validation failures during rollout. A surge in unsupported-method responses points toward a routing or gateway issue; a surge in unsupported-media-type responses points toward a client contract mismatch. These observations let you repair the appropriate layer instead of weakening validation merely to make requests succeed.
The durable migration strategy is incremental: establish semantics, validate the query contract, verify every intermediary, and then decide whether caching or result URLs add value. Adopting a new HTTP verb is useful only when the whole request path preserves the meaning your API promises.
Related Reading
- What Is MCP? Model Context Protocol Guide
- Types of AI Agents — Tool Integration Patterns
- Claude Code Python Automation — REST Patterns
- Turso — SQLite at the Edge for Concurrent APIs
- RFC 10008 — full text
- IETF Datatracker — draft history
RFC 10008 published June 15, 2026. HTTP client and framework support evolves — verify your stack before production QUERY endpoints.