`POST /queries` — submit a new query for execution. Returns the unified `QueryResponse` shape every other query endpoint emits.
/queriesThe body is the same [QueryText] POST /queries/compile takes
(ADR-0058 §5), so text that compiled is text that submits.
⚠️ A refused compile is a 400 here, where compile answers 200. Compile
was asked whether the text is valid and said; this was asked to run the
query and did not. The body carries the same diagnostics array, and an
unknown vfql_version is a 400 with no diagnostics key at all (R6).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Submit a new query for execution.
POST /queries body.
Response Body
application/json
curl -X POST "https://example.com/queries" \ -H "Content-Type: application/json" \ -d '{ "query": { "text": "string", "vfql_version": "string" } }'{ "artifact_id": "string", "created_at": "string", "data_scanned_bytes": 0, "engine_execution_time_ms": 0, "error_message": "string", "finished_at": "string", "id": "string", "org_id": "string", "output_location": "string", "principal_id": "string", "principal_kind": null, "query": null, "result_expired": true, "row_count": 0, "rule_id": "string", "source": null, "started_at": "string", "state": null, "submitted_at": "string", "team_id": "string", "updated_at": "string"}`POST /queries/compile` — compile VFQL and return the SQL or the diagnostics. POST
**Creates nothing** (R4): no run, no scheduler dispatch, no credit movement. A refused compile is a **200** carrying `diagnostics` and no `sql` — the request asked "is this valid, and where is it wrong?" and got its answer. The **400** is for an unknown `vfql_version`, which is a fact about the request with no place in the text to point at, and it carries no `diagnostics` key at all (R6). ⚠️ **No `?as_admin=` parameter, unlike every other route in this cluster.** This endpoint's job is to report catalog facts back to the caller, so an override here would be an unaudited catalog-disclosure surface; the catalog is always computed for the acting team with no admin clause (`vigilfield_query::compile_query_for`).
`DELETE /queries/{id}` — cancel a running query. DELETE
Next Page