QUERY is a safe, idempotent HTTP method that carries a request body describing the query to perform. It fills the gap between GET (no body, URL-length limited) and POST (body, but not declared safe or idempotent). Responses to QUERY are cacheable. Defined in RFC 10008 (June 2026).
Properties
| Safe | Yes | Safe methods don't change server state. They are read-only. |
| Idempotent | Yes | Idempotent methods produce the same result if called once or multiple times. |
| Cacheable | Yes | Cacheable responses may be stored and reused for equivalent requests. |
| Request Body | Yes | Whether a request body is allowed / expected. |
| Response Body | Yes | Whether a response body is expected. |
Description
QUERY solves a real problem: GET cannot carry a body with defined semantics, so complex queries with large or structured inputs have historically been sent as POST – losing the safety and idempotency guarantees that enable caching and automatic retries. QUERY is safe (RFC 9110 §9.2.1 – no state changes on the target resource) and idempotent (RFC 9110 §9.2.2 – repeating the same request has the same effect). This means intermediaries, proxies, and clients can automatically retry QUERY requests on network failure, and caches can store and serve QUERY responses using the request content as part of the cache key. The request Content-Type defines the query format. The server determines how to process it. Common formats include application/x-www-form-urlencoded, application/sql, application/jsonpath, and application/xslt+xml. Servers MUST reject QUERY requests with a missing or inconsistent Content-Type. The Accept-Query response header field (also defined in RFC 10008 §3) advertises which query media types a resource accepts. Clients can discover support via OPTIONS (which includes QUERY in the Allow header) or by attempting a QUERY request and handling 405 Method Not Allowed. CORS preflight: QUERY is not a CORS-safelisted method (per WHATWG Fetch), so cross-origin QUERY requests require an OPTIONS preflight.
Examples
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.*%22HTTP/1.1 200 OK
Content-Type: application/json
[
{ "surname": "Smith", "givenname": "John", "email": "[email protected]" },
{ "surname": "Jones", "givenname": "Sally", "email": "[email protected]" },
{ "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
[
{ "surname": "Smith", "givenname": "John", "email": "[email protected]" },
{ "surname": "Jones", "givenname": "Sally", "email": "[email protected]" },
{ "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]OPTIONS /contacts HTTP/1.1
Host: example.org
---
HTTP/1.1 200 OK
Allow: GET, QUERY, OPTIONS, HEADHEAD /contacts HTTP/1.1
Host: example.org
---
HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sqlQUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json
$..[[email protected]_status_code=="Rejected" && @.submit_date>"2024"]["doc-id"]QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Content-Type: application/sql
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025 08:44:00 GMT
...SQL query content...
---
HTTP/1.1 304 Not Modified
Content-Type: text/csv
Location: /stored-queries/4815162342GET /contacts/stored-queries/42 HTTP/1.1
Host: example.org
Accept: application/json