The new HTTP method you are thinking of is probably QUERY.

It became an Internet Standards Track RFC in June 2026 as RFC 10008: The HTTP QUERY Method. The simple idea is this: sometimes you want to ask the server a read-only question, but the question is too large, too private, or too structured to fit cleanly in a GET URL. Teams often use POST for that, but POST does not clearly say “this is safe to retry and should not change server state.”

QUERY exists to fill that gap.

Quick answer

The HTTP QUERY method lets a client send query content in the request body while still declaring that the operation is safe and idempotent. Think of it as “GET-like meaning with POST-like request content.”

That does not mean every search endpoint should switch tomorrow. Tooling, browsers, frameworks, proxies, caches, and API clients still need support. But for API design, this is a big deal because it gives a proper name to a pattern developers already use.

why HTTP needed QUERY

Developers usually choose between GET and POST.

GET is great for simple read-only requests:

GET /products?category=laptops&sort=price HTTP/1.1
Host: example.com

The problem appears when the query becomes large:

  • Complex filters.
  • Long lists of IDs.
  • Nested search rules.
  • Analytics queries.
  • Graph-style queries.
  • Full-text search options.
  • Data that should not live in logs or browser history.

You can technically push more data into the URL, but that creates problems. URLs have practical size limits across clients, servers, proxies, and tools. URLs are also more likely to appear in logs, bookmarks, analytics tools, browser history, and shared screenshots.

So teams often do this:

POST /products/search HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "category": "laptops",
  "price": { "max": 1000 },
  "brands": ["Lenovo", "Asus", "Framework"],
  "sort": "price"
}

That works, but it sends the wrong semantic signal. POST can mean “create something,” “submit something,” “run an action,” or “do whatever this endpoint decides.” A proxy, cache, retry layer, crawler, SDK, or human reader cannot safely assume the request is read-only.

QUERY makes the intent explicit.

what QUERY looks like

A QUERY request can carry content in the body:

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

{
  "category": "laptops",
  "price": { "max": 1000 },
  "brands": ["Lenovo", "Asus", "Framework"],
  "sort": "price"
}

The request target still matters. /products/search defines the resource being queried. The body describes the query operation within that resource.

The server can respond with the result:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60

{
  "items": [
    { "id": "p_123", "name": "Framework Laptop 13" }
  ]
}

The important part is not the syntax. The important part is the promise: this query is safe and idempotent.

safe and idempotent in plain English

Safe means the client is not asking the server to change the target resource. It is asking for information.

Idempotent means repeating the same request should have the same intended effect as sending it once. If the network fails, a client or intermediary can retry the request without worrying that it accidentally submitted an order twice.

Method Body for query input Safe Idempotent Good fit
GET Not really, query usually goes in URL Yes Yes Simple reads with short URLs
POST Yes Not necessarily Not necessarily Creates, actions, submissions, custom operations
QUERY Yes Yes Yes Complex read-only queries with structured input

This is why QUERY is interesting. It lets API designers say: “This request has body content, but it is still a read-only query.”

where QUERY could be useful

The strongest use cases are APIs that already use POST for search or read-only computation.

Good examples:

  • Product search with many filters.
  • Log search with time ranges and nested conditions.
  • Analytics dashboards.
  • Data warehouse query endpoints.
  • Graph-style APIs that return data without mutation.
  • Internal admin tools that run complex reports.
  • Recommendation endpoints that accept a large preference object.

Less good examples:

  • Creating a user.
  • Submitting a payment.
  • Sending an email.
  • Updating settings.
  • Starting a job that changes state.

If the request changes something important, it should not be QUERY.

the Accept-Query header

RFC 10008 also defines Accept-Query, a response header that lets a server advertise which query media types it supports.

For example:

HTTP/1.1 204 No Content
Accept-Query: application/json, application/x-www-form-urlencoded

That is useful because a server might support JSON query bodies for one endpoint and form-encoded query bodies for another. It gives clients a cleaner way to discover what format is acceptable.

In practice, early adoption will probably be uneven. Many teams will still document supported query formats in OpenAPI docs, API guides, or SDK examples. But the header gives the protocol a proper place to express it.

important status codes

QUERY makes the Content-Type more important because the body defines the query. A server should not guess what the body means.

Useful status codes:

Problem Possible status
Missing or invalid body format 400 Bad Request
Unsupported query media type 415 Unsupported Media Type
Valid syntax but impossible query 422 Unprocessable Content
Client asks for unsupported response type 406 Not Acceptable
Method not supported by server 501 Not Implemented
Method not allowed on this resource 405 Method Not Allowed

The practical lesson is simple: do not treat QUERY as “POST with another name.” The server should validate the content type, parse the body, enforce limits, and return precise errors.

should you use QUERY today?

For most public APIs, not immediately.

The method is now standardized, but real-world support takes time. Your framework may not route QUERY cleanly yet. Your API gateway may block unknown methods. Your CDN might not cache it correctly. Your client library may not expose it. Your monitoring tools may classify it strangely. Some security systems may reject it by default.

That does not make QUERY useless. It means adoption should be deliberate.

Use this decision:

Use GET when:
- The query is simple
- The URL stays readable
- Sharing/bookmarking the URL is useful

Use POST when:
- The operation changes state
- The server performs an action
- The semantics are not safely repeatable

Consider QUERY when:
- The operation is read-only
- The query body is structured or large
- You want safe/idempotent semantics
- Your infrastructure supports the method

an adoption test before you ship

Before shipping QUERY in a real API, check the boring parts. The boring parts are where production bugs live.

  • Confirm your server framework can route QUERY.
  • Confirm your CDN, reverse proxy, and load balancer allow the method.
  • Confirm logs and metrics show the method correctly.
  • Add request body size limits.
  • Require Content-Type.
  • Validate the query body with a schema.
  • Decide whether responses are cacheable.
  • Add tests for retries.
  • Document a POST fallback if clients cannot send QUERY.

That last point matters. During early adoption, a public API may support both:

QUERY /search
POST /search

The QUERY version can be the cleaner semantic path, while POST remains a compatibility path for clients and infrastructure that do not support the method yet.

test the complete request path

Do not stop after your local server accepts the method. A production request usually crosses several systems:

client -> CDN -> firewall -> load balancer -> reverse proxy -> application

Any one of them can reject an unfamiliar method or omit it from an allowlist. Test the public hostname with a real request:

curl -i -X QUERY https://api.example.com/products/search \
  -H 'content-type: application/json' \
  --data '{"category":"laptops","maxPrice":1000}'

Then inspect every layer’s logs. You want to confirm that the method remains QUERY, the body reaches the application, the response is not cached incorrectly, and monitoring records it as its own operation.

Also test the failure path. An unsupported resource should return 405 Method Not Allowed with an Allow header. A client can discover support with OPTIONS, while Accept-Query can advertise accepted query media types.

This kind of compatibility rollout is similar to a runtime migration: test the complete system and keep a fallback. The Node.js 26 versus Node.js 24 upgrade guide uses the same production-first approach.

simple Express-style example

Many frameworks do not have first-class helpers for every HTTP method. Conceptually, a handler might look like this:

app.use("/search", express.json());

app.all("/search", (req, res, next) => {
  if (req.method !== "QUERY") return next();

  const { text, filters } = req.body;

  if (typeof text !== "string") {
    return res.status(422).json({ error: "text is required" });
  }

  return res.json({
    query: { text, filters },
    results: []
  });
});

This is not a recommendation to deploy that exact code. The point is the shape: route the method, parse the body, validate input, return data, and avoid side effects.

where QUERY can create new problems

The first mistake is using QUERY for mutations because the name sounds flexible. It is not a generic “do a query or action” method. It is for safe, idempotent query processing.

The second mistake is assuming caches will automatically handle it perfectly. The spec allows caching behavior, but infrastructure support and configuration matter.

The third mistake is forgetting privacy. Moving data from URL parameters into the body can reduce accidental exposure in URLs, but it does not make the data secret. Request bodies can still be logged, inspected, stored, or mishandled.

The fourth mistake is launching without a compatibility story. If important clients cannot send QUERY, your technically cleaner API can still become annoying to use.

the two-sentence mental model

Say:

QUERY is a new HTTP method for safe, idempotent requests that need body content. It solves the common problem where complex read-only searches are forced into either long GET URLs or semantically confusing POST endpoints.

That is the clean explanation. Then add the tradeoff:

I would not adopt it blindly. I would first check framework, proxy, CDN, cache, client, and monitoring support.

That second sentence is what makes the answer sound like production experience instead of trivia.

primary specifications and references

the decision rule

QUERY gives HTTP a proper method for complex read-only requests with a body. It is not a replacement for GET or POST; it is a clearer option for the awkward middle case. Use it when the operation is safe, idempotent, and your infrastructure actually supports it.