Query Definitions Admin API
The Design Studio screen creates and edits Query Definitions through these endpoints. They manage the saved definitions that the Query Builder API runs through executeQuery and executeQueryByName, and that widgets and reference attributes use.
Base path: /api/v1.0/admin/queryDefinitions
| Method | Path | Purpose |
|---|---|---|
GET | / | List query definitions (full definitions). |
GET | /lite | List query definitions (lightweight rows, for lists and pickers). |
GET | /{queryId} | Get one definition by its identifier (GUID). |
GET | /{queryName} | Get one definition by its unique name. |
POST | / | Create a definition. |
PUT | / | Update a definition. |
DELETE | /{queryDefinitionId} | Delete a definition. |
List
GET /api/v1.0/admin/queryDefinitions and GET /api/v1.0/admin/queryDefinitions/lite
| Query-string parameter | Default | Description |
|---|---|---|
skip | 0 | Rows to skip. |
take | 100 | Rows to return. |
sortBy | name | Sort field. |
order | asc | asc or desc. |
searchString | none | Search by name (the "Search by Name" box). |
typeName | none | Only definitions associated with this type. |
queryTypes | none | Only these query types. Repeat the parameter for several values: queryTypes=InstanceQuery&queryTypes=RelationQuery. |
The response is a paged list: totalCount, skip, take, and items (each item is a definition, see below).
Get one
- By identifier:
GET /api/v1.0/admin/queryDefinitions/{queryId}(a valid GUID, otherwise the request fails with an invalid-identifier message). - By name:
GET /api/v1.0/admin/queryDefinitions/{queryName}(a blank name is rejected).
The response is a single definition. For attribute conditions the response also fills in each condition's attributeType, the picklistOptions of picklist attributes, and the userRoleFilters of user attributes, so an editor can show the right input. The attributeType of each parameter is filled in as well.
The definition (saved shape)
{
"id": "5d0c3b6e-0a43-4f7d-9d0a-2b7c1f8e4a10",
"name": "ActiveProjects",
"displayName": "Active Projects",
"description": "Projects that are not closed.",
"associatedType": "Project",
"queryType": "InstanceQuery",
"instanceQuery": { "instanceTypeName": "Project", "stateFilter": ["Active"], "getAllAttributes": true },
"instanceQueryDefinitionParameters": [],
"modified": "2026-10-28T11:03:55Z",
"modifier": "akshay"
}
| Field | Description |
|---|---|
id | Identifier. Generated on create. |
name | Unique system name. Required. |
displayName, description | Optional labels. |
associatedType | Type name. Required. |
queryType | InstanceQuery, RelationQuery, or StructuredQuery. Required, and must be one of these values. |
instanceQuery | The body for InstanceQuery. |
relatedInstanceQuery | The body for RelationQuery. |
instanceQueryDefinition | The body for StructuredQuery: an instanceQuery plus relatedInstanceQueryDefinitions. |
instanceQueryDefinitionParameters | The query parameters. |
modified, modifier | Audit fields, set by the server. |
Send only the body that matches queryType. The body objects use the same fields as the Query Builder API, with these differences for saved definitions:
- Conditions and relation filters can be dynamic:
isFirstValueDynamicandfirstValueParameterName(and the second-value equivalents) on conditions,isValueDynamicanddynamicValueParameterNameon relation filters. - The order of expressions and conditions is taken from
orderIndex, so set it sequentially from 0.
Parameters
"instanceQueryDefinitionParameters": [
{
"name": "Project",
"attributeType": "Reference",
"expression": { "valueType": "Dynamic", "attributeContext": "Instance", "attributeName": "Project", "value": "" },
"defaultValue": "",
"index": 0
}
]
| Field | Description |
|---|---|
name | Parameter name. |
attributeType | Recalculated by the server from expression on every save, so it cannot be set to a different type. |
expression.attributeContext | Instance (current instance), User (current user), or UserRoles. |
expression.attributeName | The attribute the value is read from. |
expression.valueType | Static or Dynamic. |
defaultValue | Used when the expression does not resolve a value. |
index | Position in the list. |
Examples by query type
Instance Query
{
"name": "ActiveProjects",
"displayName": "Active Projects",
"associatedType": "Project",
"queryType": "InstanceQuery",
"instanceQuery": {
"instanceTypeName": "Project",
"parentFilters": [],
"stateFilter": ["Active"],
"attributeFilterExpressions": [
{ "operator": "None", "orderIndex": 0, "attributeFilterConditions": [
{ "attributeName": "Status", "condition": "NotEquals", "isFirstValueDynamic": false, "firstValue": "Closed", "operator": "None", "orderIndex": 0 }
] }
],
"skip": 0, "take": 100, "getAllAttributes": true
}
}
Relation Query
{
"name": "ProjectTasks",
"displayName": "Project Tasks",
"associatedType": "Project",
"queryType": "RelationQuery",
"relatedInstanceQuery": {
"relationFilters": [ { "typeName": "Task", "relationTypeName": "ProjectToTask", "relationDirection": "To", "isValueDynamic": false } ],
"attributeFilterExpressions": [],
"skip": 0, "take": 100, "getAllAttributes": true, "getAllRelationAttributes": false
}
}
Structured Query
{
"name": "ProjectsWithTasks",
"associatedType": "Project",
"queryType": "StructuredQuery",
"instanceQueryDefinition": {
"instanceQuery": { "instanceTypeName": "Project", "stateFilter": ["Active"], "getAllAttributes": false, "attributes": ["Name"] },
"relatedInstanceQueryDefinitions": [
{ "relatedInstanceQuery": {
"relationFilters": [ { "typeName": "Task", "relationTypeName": "ProjectToTask", "relationDirection": "To" } ],
"attributes": ["Name"], "take": 100 } }
]
}
}
Create and update
POST /api/v1.0/admin/queryDefinitions creates a definition and PUT /api/v1.0/admin/queryDefinitions updates one (the body includes id). Both return the saved definition.
The server checks the definition before saving. A failure returns 400 with a message:
| Check | Result when it fails |
|---|---|
name is present | "Query definition name must not be null." |
associatedType is present | "Associated type is required." |
queryType is a valid value | "QueryType is required and must be valid." |
| Parameter types | The parameter attributeType is recalculated from its expression. |
InstanceQuery: instanceTypeName is present | "InstanceQuery is required but is missing in the query definition." |
InstanceQuery: a dynamic parent filter uses a Reference parameter | "Parent/relation filter parameter ... must be a Reference-type parameter." |
RelationQuery: relatedInstanceQuery is present, with at least one relation filter, each with a relation type name and a target type name | A message naming the missing part. |
StructuredQuery: the main query and every nested related query pass the same checks | A message naming the missing part. |
| Dynamic attribute conditions on User, Date, DateTime, or Numeric attributes use a parameter of a compatible type | A message naming the parameter and the required type. |
See Query Parameters for the type rules.
Delete
DELETE /api/v1.0/admin/queryDefinitions/{queryDefinitionId} deletes the definition and returns it. A blank (empty) identifier is rejected.
Deletion is blocked while the query is used by a reference attribute or a Type Widget. The error message names the dependents; remove or replace them first.