Specification: RFC 10008 — The HTTP QUERY Method
An annotated summary of the full specification, with direct links to each section of the original document.
Summary
Section titled “Summary”RFC 10008 defines the QUERY method for HTTP — a safe, idempotent request that carries the query in the message body rather than encoding it in the URI. Unlike GET, which transmits parameters only through the query string, and POST, which provides no safety or idempotency guarantees, QUERY combines the best of both: it allows complex data in the request body while preserving the properties that enable caching, automatic retries, and browser prefetching. It is the first new HTTP method registered since PATCH (RFC 5789, 2010).
Metadata
Section titled “Metadata”| Field | Value |
|---|---|
| Number | RFC 10008 |
| Title | The HTTP QUERY Method |
| Status | Standards Track (Internet Standard) |
| Stream | IETF |
| Published | June 2026 |
| Authors | Julian Reschke (greenbytes), James M. Snell (Cloudflare), Mike Bishop (Akamai) |
| Obsoletes | — (none) |
| Updates | — (none) |
| ISSN | 2070-1721 |
| Official link | rfc-editor.org/rfc/rfc10008 |
Section-by-section
Section titled “Section-by-section”Section 1 — Introduction
Section titled “Section 1 — Introduction”Frames the problem: when query data is too large for the URI query string, developers fall back to POST — but POST signals neither safety nor idempotency. QUERY fills that gap: it accepts a body, is safe and idempotent, and is cacheable. Includes a comparison table of GET vs. QUERY vs. POST.
Section 2 — QUERY Method
Section titled “Section 2 — QUERY Method”Formally defines the method. The request content and its media type define the query; the origin server determines scope based on the target resource. The Content-Type field is mandatory — requests without it MUST be rejected.
2.1 — Media Types and Content Negotiation
Section titled “2.1 — Media Types and Content Negotiation”Specifies status codes for content-type errors: 400 if absent or inconsistent, 415 if unsupported, 422 if syntactically valid but unprocessable (e.g., SQL referencing a nonexistent table), 406 if the client’s Accept cannot be satisfied.
2.2 — Equivalent Resource
Section titled “2.2 — Equivalent Resource”Defines the concept of an equivalent resource: a hypothetical resource that would respond to GET with the same result as the QUERY request. Servers may (but need not) assign URIs to these resources, making them accessible via GET.
2.3 — Content-Location Response Field
Section titled “2.3 — Content-Location Response Field”A 2xx response may include Content-Location pointing to a URI where the result can be retrieved via GET. The indicated resource may be temporary.
2.4 — Location Response Field
Section titled “2.4 — Location Response Field”The server may assign a URI to the equivalent resource and include it in the Location header of the 2xx response. A future GET to that URI repeats the query without resending the body. If the resource expires, the client can re-issue the original QUERY.
2.5 — Redirection
Section titled “2.5 — Redirection”Redirects (301, 302, 307, 308) work as expected — the client re-issues the QUERY to the new URI. Importantly: the POST→GET exceptions for 301/302 responses do not apply to QUERY. A 303 indicates the query can be satisfied via GET at the Location URI.
2.6 — Conditional Requests
Section titled “2.6 — Conditional Requests”The selected representation of a QUERY is the same as a GET to the equivalent resource. Conditional headers (If-Modified-Since, If-None-Match) work normally, enabling 304 Not Modified responses.
2.7 — Caching
Section titled “2.7 — Caching”Responses to QUERY are cacheable. The cache key MUST incorporate the request content and related metadata. Caches MAY normalize the content (remove encoding, normalize JSON) to improve efficiency — but only for key generation purposes, without altering the request itself. Clients can use no-transform to discourage normalization.
2.8 — Range Requests
Section titled “2.8 — Range Requests”Range Requests work as with GET, but offer little practical value — query formats typically define their own pagination (e.g., LIMIT/OFFSET in SQL).
Section 3 — The Accept-Query Header Field
Section titled “Section 3 — The Accept-Query Header Field”Defines the Accept-Query response header, which allows a resource to advertise which media types are accepted for QUERY requests. Uses Structured Fields syntax (RFC 9651). The value applies to all URIs sharing the same path (the query component is ignored).
Section 4 — Security Considerations
Section titled “Section 4 — Security Considerations”QUERY may be preferable to GET when the query contains sensitive data, since URIs are logged more frequently than request bodies. Temporary URIs created for results should not expose sensitive portions of the original query. Incorrect cache normalization can cause false positive matches. CORS requires a preflight request for QUERY (it is not CORS-safelisted).
Section 5 — IANA Considerations
Section titled “Section 5 — IANA Considerations”Registers the QUERY method and the Accept-Query field in the respective IANA registries (details below).
Appendix A — Examples
Section titled “Appendix A — Examples”Detailed examples covering: simple query, discovery via OPTIONS, format discovery via Accept-Query, use of Content-Location and Location, indirect responses (303), conditional requests, and alternative formats (JSONPath, XSLT).
Appendix B — Selection of the Method Name ‘QUERY’
Section titled “Appendix B — Selection of the Method Name ‘QUERY’”Explains why SEARCH, REPORT, or PROPFIND were not reused: all originate from WebDAV, use a generic application/xml content type, and “QUERY” better captures the relationship with the URI query component.
Key definitions (verbatim)
Section titled “Key definitions (verbatim)”“The QUERY method is used to initiate a server-side query. Unlike the GET method, which requests a representation of the resource identified by the target URI, the QUERY method is used to ask the target resource to perform a query operation within the scope of that target resource.”
— RFC 10008, Section 2
“QUERY requests are safe with regard to the target resource; that is, the client does not request or expect any change to the state of the target resource.”
— RFC 10008, Section 2
“Furthermore, QUERY requests are idempotent; they can be retried or repeated when needed, for instance, after a connection failure.”
— RFC 10008, Section 2
“The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests.”
— RFC 10008, Section 2.7
“The cache key for a QUERY request MUST incorporate the request content and related metadata.”
— RFC 10008, Section 2.7
“Servers MUST fail the request if the Content-Type request field is missing or is inconsistent with the request content.”
— RFC 10008, Section 2
IANA Registrations
Section titled “IANA Registrations”QUERY Method
Section titled “QUERY Method”Registered in the HTTP Method Registry:
| Field | Value |
|---|---|
| Method Name | QUERY |
| Safe | yes |
| Idempotent | yes |
| Specification | Section 2 of RFC 10008 |
Accept-Query Field
Section titled “Accept-Query Field”Registered in the HTTP Field Name Registry:
| Field | Value |
|---|---|
| Field Name | Accept-Query |
| Status | permanent |
| Structured Type | List |
| Reference | Section 3 of RFC 10008 |
Comparison: GET vs. QUERY vs. POST
Section titled “Comparison: GET vs. QUERY vs. POST”| Property | GET | QUERY | POST |
|---|---|---|---|
| Safe | yes | yes | potentially no |
| Idempotent | yes | yes | potentially no |
| URI for the query itself | yes (by definition) | optional (via Location) | no |
| URI for the result | optional (Content-Location) | optional (Content-Location) | optional (Content-Location) |
| Cacheable | yes | yes | only for future GET/HEAD |
| Body | “no defined semantics” | expected | expected |
Related RFCs
Section titled “Related RFCs”| RFC | Title | Relationship to QUERY |
|---|---|---|
| RFC 9110 | HTTP Semantics | Normative base — defines methods, fields, status codes, content negotiation |
| RFC 9111 | HTTP Caching | Defines cache keys and mechanisms that QUERY extends |
| RFC 9530 | Digest Fields for HTTP | Can be used to validate request content integrity in QUERY |
| RFC 9651 | Structured Field Values | Syntax used by Accept-Query |
| RFC 9535 | JSONPath | Query format demonstrated in the examples |
| RFC 3986 | URI: Generic Syntax | Defines the query component — historical context for the method |