Skip to main content

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

MethodPathPurpose
GET/List query definitions (full definitions).
GET/liteList 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 parameterDefaultDescription
skip0Rows to skip.
take100Rows to return.
sortBynameSort field.
orderascasc or desc.
searchStringnoneSearch by name (the "Search by Name" box).
typeNamenoneOnly definitions associated with this type.
queryTypesnoneOnly 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"
}
FieldDescription
idIdentifier. Generated on create.
nameUnique system name. Required.
displayName, descriptionOptional labels.
associatedTypeType name. Required.
queryTypeInstanceQuery, RelationQuery, or StructuredQuery. Required, and must be one of these values.
instanceQueryThe body for InstanceQuery.
relatedInstanceQueryThe body for RelationQuery.
instanceQueryDefinitionThe body for StructuredQuery: an instanceQuery plus relatedInstanceQueryDefinitions.
instanceQueryDefinitionParametersThe query parameters.
modified, modifierAudit 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: isFirstValueDynamic and firstValueParameterName (and the second-value equivalents) on conditions, isValueDynamic and dynamicValueParameterName on 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
}
]
FieldDescription
nameParameter name.
attributeTypeRecalculated by the server from expression on every save, so it cannot be set to a different type.
expression.attributeContextInstance (current instance), User (current user), or UserRoles.
expression.attributeNameThe attribute the value is read from.
expression.valueTypeStatic or Dynamic.
defaultValueUsed when the expression does not resolve a value.
indexPosition 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:

CheckResult 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 typesThe 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 nameA message naming the missing part.
StructuredQuery: the main query and every nested related query pass the same checksA message naming the missing part.
Dynamic attribute conditions on User, Date, DateTime, or Numeric attributes use a parameter of a compatible typeA 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.