Skip to content

Return one secure page of eligible Reference candidates for a persisted Table filter item.

POST
/api/workspace/entity/{entityIdOrKey}/ui/table/{tableSurfaceId}/filters/{filterItemKey}/reference-candidates/query
curl --request POST \
--url https://example.com/api/workspace/entity/example/ui/table/example/filters/example/reference-candidates/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "ExpectedTableSurfaceRowVersion": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "DraftFilterTree": { "Root": { "Logic": 0, "Nodes": [ { "Group": {}, "Condition": { "FilterItemKey": "example", "Operator": 0, "Values": [ { "Kind": 0, "Value": "example", "Variable": 0 } ] } } ] } }, "Query": { "Search": "example", "Filter": { "Operator": 0, "Conditions": [ { "Field": { "FieldId": "example", "FieldKey": "example", "Special": 0, "StatementId": "example", "StatementKey": "example", "ObjectContextFactId": "example", "ObjectContextFactFilterKey": "example" }, "Target": { "Path": [ { "FieldId": "example", "FieldKey": "example", "Special": 0, "StatementId": "example", "StatementKey": "example", "ObjectContextFactId": "example", "ObjectContextFactFilterKey": "example" } ] }, "Operator": 0, "Values": [ { "Kind": 0, "Value": "example", "Variable": 0 } ], "RowsFilter": {}, "Spatial": { "ShapeKind": 0, "Center": { "Latitude": 1, "Longitude": 1, "FullAddress": "example" }, "RadiusKm": 1, "BoundingBox": { "SouthWest": { "Latitude": 1, "Longitude": 1, "FullAddress": "example" }, "NorthEast": { "Latitude": 1, "Longitude": 1, "FullAddress": "example" } }, "Polygon": [ { "Latitude": 1, "Longitude": 1, "FullAddress": "example" } ] } } ], "Groups": [] }, "Sort": [ { "Field": { "FieldId": "example", "FieldKey": "example", "Special": 0, "StatementId": "example", "StatementKey": "example", "ObjectContextFactId": "example", "ObjectContextFactFilterKey": "example" }, "Target": { "Path": [ { "FieldId": "example", "FieldKey": "example", "Special": 0, "StatementId": "example", "StatementKey": "example", "ObjectContextFactId": "example", "ObjectContextFactFilterKey": "example" } ] }, "Direction": 0 } ], "Page": 1, "PageSize": 25 } }'
entityIdOrKey
required
string
tableSurfaceId
required
string
filterItemKey
required
string
access_token
string

Optional access token for clients that cannot set Authorization headers. Prefer Authorization: Bearer <token> when possible.

Anchored Table Surface request for eligible Reference candidates.

object
ExpectedTableSurfaceRowVersion
required

Exact saved Table Surface revision used by the caller.

string format: uuid
DraftFilterTree
required

Non-executable draft filter tree used only to derive Reference Eligibility context for a persisted Table Surface filter item.

object
Root
required

One group in a non-executable Table filter draft.

object
Logic
required
integer format: int32
Allowed values: 0 1
Nodes
required

Nested groups and conditions.

Array<object>

One node in a non-executable Table filter draft. Exactly one of Moltaro.Entity.ReferenceEligibility.Requests.EntityTableReferenceDraftFilterNodeRequest.Group and Moltaro.Entity.ReferenceEligibility.Requests.EntityTableReferenceDraftFilterNodeRequest.Condition must be supplied.

object
Group
object recursive
Condition

One condition in a non-executable Table filter draft.

object
FilterItemKey
required

Canonical key of the persisted Table Surface filter item.

string
Operator
required
integer format: int32
Allowed values: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Values

Typed draft operands. The routed dependent may have no value while its picker is open.

Array<object>
nullable

One typed operand in a non-executable Table filter draft. Its JSON shape mirrors the ordinary query operand while retaining an independent strict unknown-property boundary.

object
Kind
required
integer format: int32
Allowed values: 0 1
Value

Literal JSON value for Moltaro.Enums.EntityInstanceQueryOperandKindEnum.Value.

nullable
Variable
integer format: int32
Allowed values: 0 1
Query
required

Search, filter, sort, and paging applied to eligible Reference candidates.

object
Search

Optional configured Entity search term. Blank input adds no search. Ordinary substring search uses 3–256 trimmed characters and configured SearchTargets; exact #number and #{id} shortcuts are also supported. Search is ANDed with Filter and eligibility. A nonblank search without configured targets is rejected.

string
nullable
Filter

One nested logical filter group.

object
Operator
integer format: int32
Allowed values: 0 1
Conditions

Direct conditions inside this group.

Array<object>
nullable

One leaf condition in the runtime list query tree.

object
Field

Reference to a runtime field by identifier, normalized key, or special query field. In a typed path the segment is resolved against the entity reached by the preceding reference.

object
FieldId

Field identifier or backend-issued synthetic system-field identifier. If FieldKey is also supplied, both must resolve to the same field.

string
nullable
FieldKey

Field key resolved through the current entity’s normalized-key index. If FieldId is also supplied, both must resolve to the same field.

string
nullable
Special
integer format: int32
Allowed values: 0 1
StatementId

Statement identifier resolved through the runtime statement index.

string
nullable
StatementKey

Statement key resolved through the runtime normalized-key index.

string
nullable
ObjectContextFactId

Configured object-context fact identifier.

string
nullable
ObjectContextFactFilterKey

Provider-owned object-context fact filter facet key.

string
nullable
Target

Typed server-side condition target. The first segment belongs to the queried entity; every intermediate segment must be a readable primary-table reference, and the terminal segment determines the field type, supported operators, and operand shape.

object
Path

Ordered path of one to six segments. Each segment may contain an ID, a key, or both; when both are supplied they must resolve to the same field in the entity reached by the preceding segment.

Array<object>
nullable

Reference to a runtime field by identifier, normalized key, or special query field. In a typed path the segment is resolved against the entity reached by the preceding reference.

object
FieldId

Field identifier or backend-issued synthetic system-field identifier. If FieldKey is also supplied, both must resolve to the same field.

string
nullable
FieldKey

Field key resolved through the current entity’s normalized-key index. If FieldId is also supplied, both must resolve to the same field.

string
nullable
Special
integer format: int32
Allowed values: 0 1
StatementId

Statement identifier resolved through the runtime statement index.

string
nullable
StatementKey

Statement key resolved through the runtime normalized-key index.

string
nullable
ObjectContextFactId

Configured object-context fact identifier.

string
nullable
ObjectContextFactFilterKey

Provider-owned object-context fact filter facet key.

string
nullable
Operator
integer format: int32
Allowed values: 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Values

Operand list for the selected operator.

Array<object>
nullable

One query operand.

object
Kind
integer format: int32
Allowed values: 0 1
Value

Literal JSON value used when Moltaro.Entity.Instances.Requests.EntityInstanceQueryOperandRequest.Kind is Moltaro.Enums.EntityInstanceQueryOperandKindEnum.Value. Select and enum fields accept the string option key; numeric enum ordinals and display labels are not operands.

nullable
Variable
integer format: int32
Allowed values: 0 1
RowsFilter
object recursive
Spatial

Spatial operand for address-style runtime query conditions.

object
ShapeKind
integer format: int32
Allowed values: 0 1 2
Center

Geographic point in WGS84 coordinates.

object
Latitude

Latitude in decimal degrees.

number format: double
Longitude

Longitude in decimal degrees.

number format: double
FullAddress

Optional display address selected by the user.

string
nullable
RadiusKm

Radius in kilometers for radius-based queries.

number format: double
nullable
BoundingBox

Reserved WGS84 bounding box for future spatial queries.

object
SouthWest

Geographic point in WGS84 coordinates.

object
Latitude

Latitude in decimal degrees.

number format: double
Longitude

Longitude in decimal degrees.

number format: double
FullAddress

Optional display address selected by the user.

string
nullable
NorthEast

Geographic point in WGS84 coordinates.

object
Latitude

Latitude in decimal degrees.

number format: double
Longitude

Longitude in decimal degrees.

number format: double
FullAddress

Optional display address selected by the user.

string
nullable
Polygon

Reserved polygon payload for future spatial queries.

Array<object>
nullable

Geographic point in WGS84 coordinates.

object
Latitude

Latitude in decimal degrees.

number format: double
Longitude

Longitude in decimal degrees.

number format: double
FullAddress

Optional display address selected by the user.

string
nullable
Groups
Array<object> recursive
Sort

Optional ordinary target-Entity sort sequence.

Array<object>
nullable

One sort item in the runtime list query.

object
Field

Reference to a runtime field by identifier, normalized key, or special query field. In a typed path the segment is resolved against the entity reached by the preceding reference.

object
FieldId

Field identifier or backend-issued synthetic system-field identifier. If FieldKey is also supplied, both must resolve to the same field.

string
nullable
FieldKey

Field key resolved through the current entity’s normalized-key index. If FieldId is also supplied, both must resolve to the same field.

string
nullable
Special
integer format: int32
Allowed values: 0 1
StatementId

Statement identifier resolved through the runtime statement index.

string
nullable
StatementKey

Statement key resolved through the runtime normalized-key index.

string
nullable
ObjectContextFactId

Configured object-context fact identifier.

string
nullable
ObjectContextFactFilterKey

Provider-owned object-context fact filter facet key.

string
nullable
Target

Typed server-side sort target. The first segment belongs to the queried entity; every intermediate segment must be a readable, sortable primary-table reference.

object
Path

Ordered path of one to four segments ending in a sortable field or system field. Each segment may contain an ID, a key, or both; an ID/key mismatch is rejected.

Array<object>
nullable

Reference to a runtime field by identifier, normalized key, or special query field. In a typed path the segment is resolved against the entity reached by the preceding reference.

object
FieldId

Field identifier or backend-issued synthetic system-field identifier. If FieldKey is also supplied, both must resolve to the same field.

string
nullable
FieldKey

Field key resolved through the current entity’s normalized-key index. If FieldId is also supplied, both must resolve to the same field.

string
nullable
Special
integer format: int32
Allowed values: 0 1
StatementId

Statement identifier resolved through the runtime statement index.

string
nullable
StatementKey

Statement key resolved through the runtime normalized-key index.

string
nullable
ObjectContextFactId

Configured object-context fact identifier.

string
nullable
ObjectContextFactFilterKey

Provider-owned object-context fact filter facet key.

string
nullable
Direction
integer format: int32
Allowed values: 0 1
Page

One-based requested page, at least 1. Defaults to 1 when omitted.

integer format: int32
default: 1 >= 1 <= 2147483647
PageSize

Requested page size from 1 through 250. Defaults to 25 when omitted. Invalid sizes are rejected, not clamped; use Page, PageSize, and TotalCount to retrieve subsequent pages of a Ready result.

integer format: int32
default: 25 >= 1 <= 250

OK

Media typeapplication/json
object
Data

Paged eligible Reference candidates and their context readiness.

object
State
integer format: int32
Allowed values: 0 1 2 3 4 5 6
ErrorCode

Stable guidance code for a non-ready state.

string
nullable
Items

Display-safe candidates. Empty for every non-ready state.

Array<object>
nullable

Display-safe Reference candidate.

object
Id

Candidate Entity Instance identifier.

string
nullable
DisplayName

Current candidate display name.

string
nullable
Subtitle

Optional current candidate subtitle.

string
nullable
IsArchived

Whether the candidate is archived.

boolean
Number

Current candidate number.

string
nullable
SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object
UsageType
integer format: int32
Allowed values: 0 1 2
SemanticType
string
nullable
LinkRegistrationKey
string
nullable
CellRegistrationKey
string
nullable
ProjectedValues

Access-shaped target scalar and Money values keyed by target field key. Money values contain Amount and CurrencyCode.

object
key
additional properties
nullable
Page

One-based effective page.

integer format: int32
PageSize

Effective bounded page size.

integer format: int32
TotalCount

Accessible post-policy candidate count, or null for a non-ready state.

integer format: int32
nullable
CanCreate

Whether the actor may create a target record in this ready governed context.

boolean
Errors
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Warnings
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Success
boolean
Example
{
"Data": {
"State": 0,
"Items": [
{
"SemanticPresentation": {
"UsageType": 0
}
}
]
},
"Errors": [
{
"Type": 0,
"Severity": 0
}
],
"Warnings": [
{
"Type": 0,
"Severity": 0
}
]
}

Bad Request

Media typeapplication/json
object
Data

Paged eligible Reference candidates and their context readiness.

object
State
integer format: int32
Allowed values: 0 1 2 3 4 5 6
ErrorCode

Stable guidance code for a non-ready state.

string
nullable
Items

Display-safe candidates. Empty for every non-ready state.

Array<object>
nullable

Display-safe Reference candidate.

object
Id

Candidate Entity Instance identifier.

string
nullable
DisplayName

Current candidate display name.

string
nullable
Subtitle

Optional current candidate subtitle.

string
nullable
IsArchived

Whether the candidate is archived.

boolean
Number

Current candidate number.

string
nullable
SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object
UsageType
integer format: int32
Allowed values: 0 1 2
SemanticType
string
nullable
LinkRegistrationKey
string
nullable
CellRegistrationKey
string
nullable
ProjectedValues

Access-shaped target scalar and Money values keyed by target field key. Money values contain Amount and CurrencyCode.

object
key
additional properties
nullable
Page

One-based effective page.

integer format: int32
PageSize

Effective bounded page size.

integer format: int32
TotalCount

Accessible post-policy candidate count, or null for a non-ready state.

integer format: int32
nullable
CanCreate

Whether the actor may create a target record in this ready governed context.

boolean
Errors
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Warnings
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Success
boolean
Example
{
"Data": {
"State": 0,
"Items": [
{
"SemanticPresentation": {
"UsageType": 0
}
}
]
},
"Errors": [
{
"Type": 0,
"Severity": 0
}
],
"Warnings": [
{
"Type": 0,
"Severity": 0
}
]
}

Forbidden

Media typeapplication/json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
key
additional properties
Examplegenerated
{
"type": "example",
"title": "example",
"status": 1,
"detail": "example",
"instance": "example"
}

Not Found

Media typeapplication/json
object
Data

Paged eligible Reference candidates and their context readiness.

object
State
integer format: int32
Allowed values: 0 1 2 3 4 5 6
ErrorCode

Stable guidance code for a non-ready state.

string
nullable
Items

Display-safe candidates. Empty for every non-ready state.

Array<object>
nullable

Display-safe Reference candidate.

object
Id

Candidate Entity Instance identifier.

string
nullable
DisplayName

Current candidate display name.

string
nullable
Subtitle

Optional current candidate subtitle.

string
nullable
IsArchived

Whether the candidate is archived.

boolean
Number

Current candidate number.

string
nullable
SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object
UsageType
integer format: int32
Allowed values: 0 1 2
SemanticType
string
nullable
LinkRegistrationKey
string
nullable
CellRegistrationKey
string
nullable
ProjectedValues

Access-shaped target scalar and Money values keyed by target field key. Money values contain Amount and CurrencyCode.

object
key
additional properties
nullable
Page

One-based effective page.

integer format: int32
PageSize

Effective bounded page size.

integer format: int32
TotalCount

Accessible post-policy candidate count, or null for a non-ready state.

integer format: int32
nullable
CanCreate

Whether the actor may create a target record in this ready governed context.

boolean
Errors
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Warnings
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Success
boolean
Example
{
"Data": {
"State": 0,
"Items": [
{
"SemanticPresentation": {
"UsageType": 0
}
}
]
},
"Errors": [
{
"Type": 0,
"Severity": 0
}
],
"Warnings": [
{
"Type": 0,
"Severity": 0
}
]
}

Conflict

Media typeapplication/json
object
Data

Paged eligible Reference candidates and their context readiness.

object
State
integer format: int32
Allowed values: 0 1 2 3 4 5 6
ErrorCode

Stable guidance code for a non-ready state.

string
nullable
Items

Display-safe candidates. Empty for every non-ready state.

Array<object>
nullable

Display-safe Reference candidate.

object
Id

Candidate Entity Instance identifier.

string
nullable
DisplayName

Current candidate display name.

string
nullable
Subtitle

Optional current candidate subtitle.

string
nullable
IsArchived

Whether the candidate is archived.

boolean
Number

Current candidate number.

string
nullable
SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object
UsageType
integer format: int32
Allowed values: 0 1 2
SemanticType
string
nullable
LinkRegistrationKey
string
nullable
CellRegistrationKey
string
nullable
ProjectedValues

Access-shaped target scalar and Money values keyed by target field key. Money values contain Amount and CurrencyCode.

object
key
additional properties
nullable
Page

One-based effective page.

integer format: int32
PageSize

Effective bounded page size.

integer format: int32
TotalCount

Accessible post-policy candidate count, or null for a non-ready state.

integer format: int32
nullable
CanCreate

Whether the actor may create a target record in this ready governed context.

boolean
Errors
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Warnings
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Success
boolean
Example
{
"Data": {
"State": 0,
"Items": [
{
"SemanticPresentation": {
"UsageType": 0
}
}
]
},
"Errors": [
{
"Type": 0,
"Severity": 0
}
],
"Warnings": [
{
"Type": 0,
"Severity": 0
}
]
}

Service Unavailable

Media typeapplication/json
object
Data

Paged eligible Reference candidates and their context readiness.

object
State
integer format: int32
Allowed values: 0 1 2 3 4 5 6
ErrorCode

Stable guidance code for a non-ready state.

string
nullable
Items

Display-safe candidates. Empty for every non-ready state.

Array<object>
nullable

Display-safe Reference candidate.

object
Id

Candidate Entity Instance identifier.

string
nullable
DisplayName

Current candidate display name.

string
nullable
Subtitle

Optional current candidate subtitle.

string
nullable
IsArchived

Whether the candidate is archived.

boolean
Number

Current candidate number.

string
nullable
SemanticPresentation

Safe compact reference metadata, projected only for a resolved visible Entity reference.

object
UsageType
integer format: int32
Allowed values: 0 1 2
SemanticType
string
nullable
LinkRegistrationKey
string
nullable
CellRegistrationKey
string
nullable
ProjectedValues

Access-shaped target scalar and Money values keyed by target field key. Money values contain Amount and CurrencyCode.

object
key
additional properties
nullable
Page

One-based effective page.

integer format: int32
PageSize

Effective bounded page size.

integer format: int32
TotalCount

Accessible post-policy candidate count, or null for a non-ready state.

integer format: int32
nullable
CanCreate

Whether the actor may create a target record in this ready governed context.

boolean
Errors
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Warnings
Array<object>
nullable
object
Code
required
string
nullable
Message
required
string
nullable
Target
string
nullable
Field
string
nullable
Metadata
object
key
additional properties
string
nullable
Type
integer format: int32
Allowed values: 0 1 2
Severity
integer format: int32
Allowed values: 0 1 2
Success
boolean
Example
{
"Data": {
"State": 0,
"Items": [
{
"SemanticPresentation": {
"UsageType": 0
}
}
]
},
"Errors": [
{
"Type": 0,
"Severity": 0
}
],
"Warnings": [
{
"Type": 0,
"Severity": 0
}
]
}