Fields & Parameters
Endpoints for inspecting the fields a Query returns, discovering the input components a Query can prompt for, and storing the calling user's per-Query settings.
These routes need only a normal authenticated user. Read access to the Query is
enforced by the Query lookup (the read_access model scope), not by a separate
permission, so none of these routes carry a query:write permission pre-block.
GET /api/queries/{id}/fields
List the fields defined in a Query's payload.fields.
Authentication: Required
Pre-blocks: query.compile (casts {id} directly to a UUID, so this route
requires the Query's UUID, not its natural id)
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string (UUID) | Query UUID |
Response:
An eu.collection HAL envelope ({ start, count, total } plus
_embedded["inf:payload-field"]) built from the Query's payload.fields. Each
row is the payload field as stored, carrying id, name, label, type,
fieldId, and the grouping flags grouped, distinct, and aggregate.
A resolved datasource field (embedded as inf:field under _field) is attached
to a row only when a scanned datasource Field matches it. With no
payload.fields, the collection is empty.
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/fields"
}
},
"start": 0,
"count": 3,
"total": 3,
"_embedded": {
"inf:payload-field": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/fields/sale_date"
}
},
"id": "sale_date",
"name": "Sale Date",
"type": "field",
"label": "Sale Date",
"fieldId": "sale_date",
"grouped": false,
"distinct": false,
"aggregate": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/fields/amount"
}
},
"id": "amount",
"name": "Sale Amount",
"type": "field",
"label": "Sale Amount",
"fieldId": "amount",
"grouped": false,
"distinct": false,
"aggregate": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/fields/region"
}
},
"id": "region",
"name": "Region",
"type": "field",
"label": "Region",
"fieldId": "region",
"grouped": false,
"distinct": false,
"aggregate": null
}
]
}
}
The handler scans payload.fields and embeds an inf:field only when a real
scanned Field matches. Without a live datasource scan the rows are returned
as-stored, with no _field.
DELETE /api/queries/{id}/fields
Intended to remove the field definitions from a Query's payload.
Authentication: Required
Pre-blocks: query.lookup
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query UUID or natural id |
Response:
Responds 200 with an empty body (Informer convention), not 204. There is no
query:write permission pre-block.
The current handler reads the wrong instance attribute, so it does not actually
clear payload.fields. The route still answers 200. Do not rely on it to
remove fields. To change a Query's stored fields, use PUT /api/queries/{id}
with an updated payload.
GET /api/queries/{id}/input-templates
Discover the input-parameter components a Query can prompt for. Runs the
input-builder:query driver-manager discover and decorates each template with
the Query's language driver. No datasource connection is required.
Authentication: Required
Pre-blocks: query.lookup
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query UUID or natural id |
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
dataType | string | all | Filters templates to those compatible with the given data type |
wildcard | boolean | false | Toggles wildcard text inputs |
Response:
An eu.collection HAL envelope ({ start, count, total } plus an items
array). Each item is an input-component template carrying the discovering
detective id, a synthetic id, and a value describing the component
(name, key, the input definition, and optional group / children). This
is not a { suggested, common } envelope.
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/admin%3Asales-by-region/input-templates?dataType=all&wildcard=false"
}
},
"items": [
{
"detective": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001:0",
"value": {
"name": "Input Box",
"key": "input:input_box",
"input": {
"mdMultiInput": {
"type": "text",
"wildcard": false
}
}
}
},
{
"detective": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001:1",
"value": {
"name": "Number Slider",
"key": "input:number_slider",
"input": {
"mdSlider": {}
}
}
},
{
"detective": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001:2",
"value": {
"name": "Select Dropdown",
"key": "input:select_dropdown",
"input": {
"mdSelect": {
"options": []
}
}
}
},
"… 9 more items (12 total) — omitted from docs"
],
"start": 0,
"count": 12,
"total": 12
}
Use this endpoint to enumerate the input components available for a Query (text box, number slider, select dropdown, date picker, date range, and so on) rather than guessing parameter names. The set is driven by the registered input detectives and the Query's language.
Input Parameters
Input parameters let a Query accept dynamic values at runtime. They are stored
in the inputs property of the Query and referenced in the payload using
language-specific syntax.
SQL references a parameter by name:
{
"language": "sql",
"payload": {
"sql": "SELECT * FROM sales WHERE date >= :startDate AND region = :region"
},
"inputs": {
"startDate": { "type": "date", "label": "Start Date" },
"region": { "type": "string", "label": "Region" }
}
}
i5-QL references a parameter inside a filter value:
{
"language": "i5-ql",
"payload": {
"filters": [
{ "field": "date", "operator": ">=", "value": { "param": "startDate" } }
]
},
"inputs": {
"startDate": { "type": "date", "label": "Start Date" }
}
}
To create or change a Query's inputs, send the inputs object on
POST /api/queries or PUT /api/queries/{id}. Use the input-templates endpoint
above to discover the input components you can wire up.
GET /api/queries/{id}/settings
Get the calling user's saved settings for a Query.
Authentication: Required
Pre-blocks: query.lookup
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query UUID or natural id |
Response:
The calling user's UserSettings row for this Query, with the saved values
under settings, or an empty object when the user has saved nothing. These are
per-user settings, not the Query's stored settings column. The response links
to the restore route via inf:restore.
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/admin%3Asales-by-region/settings"
},
"inf:restore": {
"href": "https://informer.example.com/api/queries/admin%3Asales-by-region/settings/_restore"
}
},
"id": "00000000-0000-4000-8000-000000000001",
"datasetId": null,
"reportId": null,
"queryId": "00000000-0000-4000-8000-000000000002",
"templateId": null,
"userId": "admin",
"settings": {
"timeout": 60000,
"fieldDefaults": {
"dateFormat": "MM/DD/YYYY",
"numberFormat": "0,0.00"
}
},
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"snapshots": null
}
PUT /api/queries/{id}/settings
Save the calling user's settings for a Query.
Authentication: Required
Pre-blocks: query.lookup
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query UUID or natural id |
Request Body:
The body is stored verbatim under the caller's UserSettings and echoed back.
There is no payload validation and no query:write permission pre-block, so any
JSON object is accepted.
Example Request:
{
"fieldDefaults": {
"dateFormat": "MM/DD/YYYY",
"numberFormat": "0,0.00"
},
"timeout": 60000
}
Response:
Responds 200 with the stored settings, plus a HAL _links block linking to
the restore route.
{
"fieldDefaults": {
"dateFormat": "MM/DD/YYYY",
"numberFormat": "0,0.00"
},
"timeout": 60000
}
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/admin%3Asales-by-region/settings"
},
"inf:restore": {
"href": "https://informer.example.com/api/queries/admin%3Asales-by-region/settings/_restore"
}
},
"fieldDefaults": {
"dateFormat": "MM/DD/YYYY",
"numberFormat": "0,0.00"
},
"timeout": 60000
}
POST /api/queries/{id}/settings/_restore
Clear the calling user's saved settings for a Query so it falls back to its defaults.
Authentication: Required
Pre-blocks: query.lookup
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query UUID or natural id |
Response:
Deletes the caller's UserSettings row and responds 200 with an empty body,
not a restored-settings object.
This only clears the calling user's saved settings for the Query. It does not touch the Query's own stored configuration or any other user's settings.