Using the HTTP QUERY method
A query string flattens everything into text. When a query takes structured arguments, or you would rather not put values in a URL, send them in a body with the HTTP QUERY method. It is safe and idempotent like GET, and Arc accepts it on every query route by default.
Send a QUERY request
Section titled “Send a QUERY request”curl -X QUERY http://127.0.0.1:3000/api/tasks/listing/task-by-id \ -H 'content-type: application/json' \ -d '{"arguments":{"id":"1a638f8e-4444-4444-8888-a0b10cdd9977"}}'Against the running Tasks sample, this answers 200 with the task in data and Cache-Control: no-store.
The body
Section titled “The body”The body is a JSON object with three recognized properties. A JSON null body, or null for any of these properties, is treated as absent. Unknown members of the envelope, paging, and sorting objects are ignored:
{ "arguments": { "tags": ["urgent"] }, "paging": { "page": 0, "pageSize": 10 }, "sorting": { "field": "title", "direction": "desc" } }| Property | Meaning |
|---|---|
arguments | Parsed as JSON, so numbers, booleans, arrays, and objects keep their types. Names match case-insensitively, as with GET |
paging | page and pageSize. Nonpositive or missing pageSize means unpaged. |
sorting | field and direction; a direction without a field is ignored. |
GET and QUERY have different paging rules; see the request table. Undeclared argument names are rejected by TypeScript (unlike .NET). Non-object envelope members and non-string sort fields or directions produce a 400 unreadable-body exception envelope.
Turn it off
Section titled “Turn it off”Set generatedApis: { enableQueryHttpMethod: false } in the options to accept GET only. A QUERY request then answers 405 with Allow: GET.
Where QUERY does not appear
Section titled “Where QUERY does not appear”OpenAPI 3.1 path items do not define a QUERY operation, so /openapi.json describes queries as GET only. Behind Fastify, QUERY is registered for command and query routes but not for the /.cratis endpoints.