Core CRUD
Basic Query creation, retrieval, update, and deletion operations.
Core Query CRUD needs no special license. Read access is enforced by the
read_access model scope rather than a permission, so the list and lookup
routes return only the Queries the caller may see. Creating a Query requires
queries:create (Designer role); updating, patching, or deleting one requires
query:write. All write routes are stripUnknown, so unrecognized payload
fields are dropped rather than rejected.
A Query can be referenced by UUID or by natural id in the format ownerId:slug
(for example admin:sales-analysis-query).
GET /api/queries
Search and filter Queries with pagination and aggregations.
Authentication: Required
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
q | string | - | Full-text search (slug, name, description) |
datasource | string | - | Filter by datasource id |
sort | string | name | Sort field (prefix with - for descending) |
limit | integer | 30 | Results per page |
start | integer | 0 | Pagination offset |
Response:
A paged HAL collection. Query rows are returned under
_embedded["inf:query"], each embedding its datasource under
inf:datasource. The collection always excludes drafts (rows whose
editingId is null) and embedded Queries. Alongside the rows, the response
carries aggs (per-datasource counts plus a total) for building filter UIs
and a top-level permissions object.
Search queriesGET /api/queries?limit=30&start=0
GET /api/queries is a paged HAL collection (inf:queries). It always excludes drafts (editingId is null) and embedded queries. Each row embeds its datasource under inf:datasource. The response carries `aggs` (per-datasource counts + total) and a top-level `permissions` object. Query params: q, sort, limit, start, and `datasource` (filter by datasource id).
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries?limit=30&start=0"
}
},
"start": 0,
"count": 2,
"total": 2,
"aggs": {
"datasource": [],
"total": 2
},
"permissions": {
"create": true
},
"_embedded": {
"inf:query": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:sales-analysis-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"ownerId": "admin",
"slug": "sales-analysis-query",
"name": "Sales Analysis Query",
"description": "Quarterly sales data with regional breakdowns",
"shared": true,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": null,
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"defnUpdatedAt": null,
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"editingId": null,
"folderId": null,
"datasource": null,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Ascratch-query/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:scratch-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "scratch-query",
"name": "Scratch Query",
"description": null,
"shared": false,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": null,
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"defnUpdatedAt": null,
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"editingId": null,
"folderId": null,
"datasource": null,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
}
]
}
}
Datasource filtering
Use the datasource parameter to narrow Queries to a single datasource before
applying full-text search.
GET /api/queries-list
Get a complete list of readable Queries with full details (no pagination).
Authentication: Required
Response:
A flat array of every Query the caller can read. Each row carries tags,
sharing, owner details (ownerId, ownerName, username), datasource
metadata (datasourceType, datasourceName), and a per-Query permissions
map. This endpoint is optimized for building Query selectors and dropdowns, and
is ETag-gated via the warp plugin.
List queries (flat)GET /api/queries-list
GET /api/queries-list is a flat HAL collection (inf:queries-list) of every readable query, no pagination. Each row carries `tags`, `sharing`, and a per-query `permissions` map. Etag-gated via the warp plugin.
Response · 200
[
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Sales Analysis Query",
"description": "Quarterly sales data with regional breakdowns",
"source": null,
"sourceId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceType": null,
"datasourceName": null,
"ownerId": "admin",
"username": "admin",
"naturalId": "admin:sales-analysis-query",
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": false,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"ownerName": "acme Administrator",
"tags": [
"00000000-0000-4000-8000-000000000002",
"00000000-0000-4000-8000-000000000003"
]
},
{
"id": "00000000-0000-4000-8000-000000000004",
"name": "Scratch Query",
"description": null,
"source": null,
"sourceId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceType": null,
"datasourceName": null,
"ownerId": "admin",
"username": "admin",
"naturalId": "admin:scratch-query",
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": false,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"ownerName": "acme Administrator",
"tags": []
}
]
GET /api/queries/{id}
Get a single Query by id or natural id.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query id (UUID) or natural id (ownerId:slug) |
Response:
The full Query. Tag ids are eager-loaded and flattened into a tags array. The
response embeds inf:query-language, embeds inf:datasource when the Query has
a datasource, and exposes the run/execute/draft/dataset HAL links (among
others). The example below resolves the Query by its natural id
admin:sales-analysis-query.
Get a queryGET /api/queries/admin:sales-analysis-query
GET /api/queries/{id} accepts a UUID or a natural id (ownerId:slug). Eager-loads tag ids (flattened to a `tags` array), embeds inf:datasource and inf:query-language, and exposes run/execute/draft/dataset HAL links. Resolved here via the natural id admin:sales-analysis-query.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Asales-analysis-query/input-templates{?dataType,wildcard}",
"templated": true
},
"inf:jobs": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/jobs"
},
"inf:job-templates": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/job-templates"
},
"inf:discover": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/discover"
}
},
"naturalId": "admin:sales-analysis-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"ownerId": "admin",
"slug": "sales-analysis-query",
"name": "Sales Analysis Query",
"description": "Quarterly sales data with regional breakdowns",
"shared": true,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": null,
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"defnUpdatedAt": null,
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"editingId": null,
"folderId": null,
"datasource": null,
"tags": [
"00000000-0000-4000-8000-000000000002",
"00000000-0000-4000-8000-000000000003"
],
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
}
Natural ids
Queries can be referenced by UUID or by natural id in the format ownerId:slug
(for example admin:sales-analysis-query).
POST /api/queries
Create a new Query.
Authentication: Required
Pre-blocks: queries:create (Designer role)
Request Body:
The payload is stripUnknown.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Query display name |
language | string | Yes | Query language (for example informer, sql) |
description | string | No | Query description |
datasourceId | string | No | Datasource id (the built-in informer language needs none) |
payload | object | No | Language-specific Query definition (defaults to {}) |
inputs | object | No | Input parameter definitions |
flow | array | No | Transformation steps |
settings | object | No | Query settings |
fields | object | No | Field metadata and formatting |
datasourceId is optional: a Query can be created with just { name, language }
when language is informer, a built-in language that needs no datasource.
Example Request:
{
"name": "Customer Revenue Query",
"description": "Monthly customer revenue aggregations",
"language": "informer",
"payload": { "source": { "mappingId": "person", "schemaId": "test" } }
}
Response:
Responds 200 with the full created Query (the model assigns the id) and a
Location header pointing to the new Query. The handler sets the Location
header but never calls .created(), so the status is 200, not 201.
Create a queryPOST /api/queries
POST /api/queries requires `queries:create` (Designer role). `language` is required; `payload` defaults to {} and `datasourceId` is optional (the built-in `informer` language needs none). Payload is stripUnknown. The handler returns the created query with a Location header but a 200 status (it does NOT call .created()/201, despite the docs).
Request body
{
"name": "Customer Revenue Query",
"description": "Monthly customer revenue aggregations",
"language": "informer",
"payload": {
"source": {
"mappingId": "person",
"schemaId": "test"
}
}
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Acustomer-revenue-query/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:customer-revenue-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"shared": false,
"embedded": false,
"settings": {},
"limit": -1,
"name": "Customer Revenue Query",
"description": "Monthly customer revenue aggregations",
"language": "informer",
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"flow": [],
"updatedAt": "2026-01-15T16:20:00.000Z",
"createdAt": "2026-01-15T16:20:00.000Z",
"ownerId": "admin",
"slug": "customer-revenue-query",
"source": null,
"sourceId": null,
"inputs": null,
"defnUpdatedAt": null,
"_altid": null,
"datasourceId": null,
"editingId": null,
"folderId": null,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
}
PUT /api/queries/{id}
Update an existing Query.
Authentication: Required
Pre-blocks: query:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query id (UUID) or natural id |
Request Body:
All fields are optional and the payload is stripUnknown; only the provided
fields are applied (the handler runs updateAttributes then reloads).
| Field | Type | Description |
|---|---|---|
name | string | Query display name |
description | string | Query description (may be empty string) |
language | string | Query language |
datasourceId | string | Datasource id |
payload | object | Language-specific Query definition |
inputs | object | null | Input parameters (may be null) |
flow | array | Transformation steps |
settings | object | Query settings |
fields | object | null | Field metadata (may be null) |
shared | boolean | Whether the Query is shared |
folderId | string | null | Folder id (may be null) |
limit | integer | Row limit |
Example Request:
{
"name": "Q4 Customer Revenue Query",
"description": "Updated quarterly revenue aggregations",
"shared": true,
"limit": 1000
}
Response:
Responds 200 with the updated Query. Runs in a database transaction.
Update a queryPUT /api/queries/00000000-0000-4000-8000-000000000001
PUT /api/queries/{id} requires `query:write` and runs in a DB transaction. All fields are optional and payload is stripUnknown; only provided fields are applied (updateAttributes then reload). `description` may be empty string; `inputs`/`fields`/`folderId` may be null. Returns the updated query (200).
Request body
{
"name": "Q4 Customer Revenue Query",
"description": "Updated quarterly revenue aggregations",
"shared": true,
"limit": 1000
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Aq4-customer-revenue-query/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:q4-customer-revenue-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"ownerId": "admin",
"slug": "q4-customer-revenue-query",
"name": "Q4 Customer Revenue Query",
"description": "Updated quarterly revenue aggregations",
"shared": true,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": [],
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"defnUpdatedAt": null,
"limit": 1000,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"editingId": null,
"folderId": null,
"datasource": null,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
}
Payload size limit
Query payloads are limited by tenant configuration. Large payloads may be rejected.
PATCH /api/queries/{id}
Partially update a Query using JSON Patch operations.
Authentication: Required
Pre-blocks: query:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query id (UUID) or natural id |
Request Body:
A JSON Patch document. A remove op is rewritten to set the path to null
(an add with value null) before the patch is applied to the model and saved.
[
{ "op": "replace", "path": "/name", "value": "Renamed Revenue Query" },
{ "op": "replace", "path": "/description", "value": "Patched description" }
]
Supported Operations:
add- Add or update a propertyreplace- Replace a property valueremove- Remove a property (rewritten to set the path tonull)
Response:
Responds 200 with the updated Query.
Patch a queryPATCH /api/queries/00000000-0000-4000-8000-000000000001
PATCH /api/queries/{id} requires `query:write` and takes a JSON Patch document. A `remove` op is rewritten to set the path to null (add with value null), then applied to the model and saved. Returns the updated query (200).
Request body
[
{
"op": "replace",
"path": "/name",
"value": "Renamed Revenue Query"
},
{
"op": "replace",
"path": "/description",
"value": "Patched description"
}
]
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Arenamed-revenue-query/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:renamed-revenue-query",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"ownerId": "admin",
"slug": "renamed-revenue-query",
"name": "Renamed Revenue Query",
"description": "Patched description",
"shared": true,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": [],
"payload": {
"fields": [],
"source": {
"id": "person",
"schemaId": "test",
"mappingId": "person"
},
"groupBy": [],
"distinct": false
},
"defnUpdatedAt": null,
"limit": 1000,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"editingId": null,
"folderId": null,
"datasource": null,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/informer"
}
},
"id": "informer",
"name": "common:ad_hoc_query",
"description": "query-languages:ad_hoc.description",
"image": "/assets/query-languages/images/query-designer.svg",
"color": "blue",
"preProcessors": [
"iqlTclPredicateValidationProcessor",
"resolveLinkRefProcessor",
"iqlPayloadFieldPermissionEvaluator",
"… 8 more items (11 total) — omitted from docs"
]
}
}
}
DELETE /api/queries/{id}
Delete a Query.
Authentication: Required
Pre-blocks: query:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query id (UUID) or natural id |
Response:
Responds 200 with an empty body (Informer convention), via the db.remove
handler. This is not a 204 No Content.
Delete a queryDELETE /api/queries/00000000-0000-4000-8000-000000000001
DELETE /api/queries/{id} requires `query:write`. Uses the db.remove handler and returns 200 with an EMPTY body (Informer convention), NOT 204 as the docs claim. Cascades to drafts, shares, comments, tag associations, and any embedded dataset.
Response · 200 · no body
Cascading deletes
Deleting a Query also deletes:
- Associated drafts
- Query shares
- Comments
- Tag associations
- Any embedded dataset (for embedded Queries)
GET /api/queries/{id}/permissions
Get the caller's effective permissions for a Query.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Query id (UUID) or natural id |
Response:
The caller's effective semantic permissions for the Query, computed from team
roles (for team-owned Queries) or ownership (for user-owned Queries). The keys
are camelCase: assignTags and changeOwner, plus edit and delete which
delegate to write.
Get a query’s permissionsGET /api/queries/00000000-0000-4000-8000-000000000001/permissions
GET /api/queries/{id}/permissions returns the caller’s effective semantic permissions for the query (write/run/copy/share/rename/assign-tags/change-owner, plus edit/delete which delegate to write). Computed from team roles or ownership; embedded queries need Data Wizard, ad-hoc queries need Designer for write.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/permissions"
}
},
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": false,
"share": true,
"write": true
}
Permission breakdown:
| Permission | Description |
|---|---|
write | Can modify the Query definition, settings, and fields |
run | Can execute the Query to generate datasets |
copy | Can create copies of the Query |
edit | Can edit the Query (delegates to write) |
delete | Can delete the Query (delegates to write) |
rename | Can rename the Query |
share | Can manage Query shares and access control |
assignTags | Can add and remove tags |
changeOwner | Can transfer ownership |
Permission evaluation
Permissions are evaluated from team roles for team-owned Queries or from ownership for user-owned Queries. Embedded Queries require the Data Wizard role, while ad-hoc Queries require the Designer role for write access.