# Advanced graph-aware record query

Executes a two-pass GraphRAG query using natural language or a declarative plan. Returns records with scores and graph evidence.

Endpoint: POST /api/v2/records/query
Version: 2.0
Security: bearerAuth

## Request fields (application/json):

  - `question` (string)
    Natural-language question to plan and execute.

  - `plan` (object)
    Validated declarative query plan.

  - `plan.version` (integer)

  - `plan.mainObject` (string)

  - `plan.mainObjects` (array)

  - `plan.query` (string)

  - `plan.filter` (object)
    DTO representing a filter composed of filter groups for querying records. The filter groups are combined using a logical OR operation. The filter items within each group are combined using a logical AND operation.

  - `plan.filter.groups` (array)
    A collection of filter groups.

  - `plan.filter.groups.items` (object)
    A set of filter items included in the group.

  - `plan.filter.groups.items.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.filter.groups.items.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.filter.groups.items.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.filter.groups.items.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.filter.groups.items.relationIncluded` (boolean)
    Specifies whether the relation is included.
    Example: true

  - `plan.filter.groups.items.operator` (string)
    Defines the operator used in the filter. Available operators are defined in the API documentation.
    Example: "EQUALS"

  - `plan.filter.groups.items.value` (any)
    Represents the value to filter against.
    Example: 12345

  - `plan.filter.groups.items.smartContent` (boolean)
    When true, filter fields contain smart content placeholders resolved at runtime.
    Example: true

  - `plan.filter.groups.items.edgeProperty` (boolean)
    When true, propertyName refers to a property stored on the relation edge itself (declared on the relation schema, e.g. partstat on attendees) instead of a property of the related record. Requires relation and propertyName.

  - `plan.sort` (array)

  - `plan.sort.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.sort.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.sort.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.sort.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.sort.direction` (string)
    The direction for sorting. Can be ASC (ascending) or DESC (descending).
    Enum: "ASC", "DESC"

  - `plan.show` (array)

  - `plan.show.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.show.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.show.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.show.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.show.separator` (string)
    Separator string used to visually separate this item.
    Example: "|"

  - `plan.show.sticky` (boolean)
    Flag indicating whether this item is sticky and will stay fixed in the list.

  - `plan.show.width` (integer)
    Width of the item in pixels.
    Example: 100

  - `plan.show.calculationFunction` (string)
    Calculation function used to calculate the value of the item.
    Example: "max"

  - `plan.show.calculationResult` (any)
    Result of the calculation.
    Example: 100

  - `plan.strategy` (string)
    Enum: "AUTO", "STRUCTURED", "LEXICAL", "SEMANTIC", "HYBRID", "GRAPH"

  - `plan.anchorRecordUuid` (string)

  - `plan.criteria` (array)

  - `plan.graphTraversals` (array)

  - `plan.graphTraversals.relation` (string)

  - `plan.graphTraversals.targetObject` (string)

  - `plan.graphTraversals.direction` (string)

  - `plan.graphTraversals.maxDepth` (integer)

  - `plan.graphTraversals.includeLifecycle` (boolean)

  - `plan.graphTraversals.includeActivities` (boolean)

  - `plan.graphTraversals.perRelationLimit` (integer)

  - `plan.scoreWeights` (object)

  - `plan.includeEvidence` (boolean)

  - `plan.maxTraversalDepth` (integer)

  - `plan.page` (integer)

  - `plan.limit` (integer)

  - `mainObject` (string)
    Optional main object hint. Use mainObjects for multi-type queries.

  - `mainObjects` (array)
    Optional object list for multi-type queries (e.g. candidate and vacancy together).

  - `strategy` (string)
    Enum: "AUTO", "STRUCTURED", "LEXICAL", "SEMANTIC", "HYBRID", "GRAPH"

  - `page` (integer)

  - `limit` (integer)

  - `preview` (string)

  - `parse` (any)

  - `archived` (boolean)

  - `explain` (boolean)
    When true, include normalized plan, scores, and evidence.

  - `recordReturnFormat` (string)

## Response 200 fields (application/json):

  - `data` (array)

  - `results` (array)

  - `results.record` (any)

  - `results.recordUuid` (string)

  - `results.objectName` (string)

  - `results.scores` (object)

  - `results.scores.overall` (number)

  - `results.scores.structured` (number)

  - `results.scores.lexical` (number)

  - `results.scores.semantic` (number)

  - `results.scores.graph` (number)

  - `results.scores.evidenceAdjustment` (number)

  - `results.scores.confidence` (number)

  - `results.scores.components` (object)

  - `results.criteria` (array)

  - `results.criteria.criterion` (string)

  - `results.criteria.score` (number)

  - `results.criteria.weight` (number)

  - `results.criteria.rationale` (string)

  - `results.criteria.supportingEvidence` (array)

  - `results.criteria.supportingEvidence.type` (string)

  - `results.criteria.supportingEvidence.polarity` (string)

  - `results.criteria.supportingEvidence.summary` (string)

  - `results.criteria.supportingEvidence.sourceObject` (string)

  - `results.criteria.supportingEvidence.sourceRecordUuid` (string)

  - `results.criteria.supportingEvidence.relation` (string)

  - `results.criteria.supportingEvidence.timestamp` (integer)

  - `results.criteria.supportingEvidence.recencyWeight` (number)

  - `results.criteria.supportingEvidence.confidence` (number)

  - `results.criteria.supportingEvidence.properties` (object)

  - `results.criteria.supportingEvidence.paths` (array)

  - `results.criteria.supportingEvidence.paths.path` (array)

  - `results.criteria.supportingEvidence.paths.summary` (string)

  - `results.criteria.supportingEvidence.paths.relation` (string)

  - `results.criteria.supportingEvidence.paths.targetObject` (string)

  - `results.criteria.supportingEvidence.paths.recordUuid` (string)

  - `results.criteria.contradictingEvidence` (array)

  - `results.criteria.contradictingEvidence.type` (string)

  - `results.criteria.contradictingEvidence.polarity` (string)

  - `results.criteria.contradictingEvidence.summary` (string)

  - `results.criteria.contradictingEvidence.sourceObject` (string)

  - `results.criteria.contradictingEvidence.sourceRecordUuid` (string)

  - `results.criteria.contradictingEvidence.relation` (string)

  - `results.criteria.contradictingEvidence.timestamp` (integer)

  - `results.criteria.contradictingEvidence.recencyWeight` (number)

  - `results.criteria.contradictingEvidence.confidence` (number)

  - `results.criteria.contradictingEvidence.properties` (object)

  - `results.criteria.contradictingEvidence.paths` (array)

  - `results.criteria.contradictingEvidence.paths.path` (array)

  - `results.criteria.contradictingEvidence.paths.summary` (string)

  - `results.criteria.contradictingEvidence.paths.relation` (string)

  - `results.criteria.contradictingEvidence.paths.targetObject` (string)

  - `results.criteria.contradictingEvidence.paths.recordUuid` (string)

  - `results.supportingEvidence` (array)

  - `results.supportingEvidence.type` (string)

  - `results.supportingEvidence.polarity` (string)

  - `results.supportingEvidence.summary` (string)

  - `results.supportingEvidence.sourceObject` (string)

  - `results.supportingEvidence.sourceRecordUuid` (string)

  - `results.supportingEvidence.relation` (string)

  - `results.supportingEvidence.timestamp` (integer)

  - `results.supportingEvidence.recencyWeight` (number)

  - `results.supportingEvidence.confidence` (number)

  - `results.supportingEvidence.properties` (object)

  - `results.supportingEvidence.paths` (array)

  - `results.supportingEvidence.paths.path` (array)

  - `results.supportingEvidence.paths.summary` (string)

  - `results.supportingEvidence.paths.relation` (string)

  - `results.supportingEvidence.paths.targetObject` (string)

  - `results.supportingEvidence.paths.recordUuid` (string)

  - `results.contradictingEvidence` (array)

  - `results.contradictingEvidence.type` (string)

  - `results.contradictingEvidence.polarity` (string)

  - `results.contradictingEvidence.summary` (string)

  - `results.contradictingEvidence.sourceObject` (string)

  - `results.contradictingEvidence.sourceRecordUuid` (string)

  - `results.contradictingEvidence.relation` (string)

  - `results.contradictingEvidence.timestamp` (integer)

  - `results.contradictingEvidence.recencyWeight` (number)

  - `results.contradictingEvidence.confidence` (number)

  - `results.contradictingEvidence.properties` (object)

  - `results.contradictingEvidence.paths` (array)

  - `results.contradictingEvidence.paths.path` (array)

  - `results.contradictingEvidence.paths.summary` (string)

  - `results.contradictingEvidence.paths.relation` (string)

  - `results.contradictingEvidence.paths.targetObject` (string)

  - `results.contradictingEvidence.paths.recordUuid` (string)

  - `total` (integer)

  - `page` (integer)

  - `perPage` (integer)

  - `lastPage` (integer)

  - `plan` (object)

  - `plan.version` (integer)

  - `plan.mainObject` (string)

  - `plan.mainObjects` (array)

  - `plan.query` (string)

  - `plan.filter` (object)
    DTO representing a filter composed of filter groups for querying records. The filter groups are combined using a logical OR operation. The filter items within each group are combined using a logical AND operation.

  - `plan.filter.groups` (array)
    A collection of filter groups.

  - `plan.filter.groups.items` (object)
    A set of filter items included in the group.

  - `plan.filter.groups.items.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.filter.groups.items.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.filter.groups.items.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.filter.groups.items.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.filter.groups.items.relationIncluded` (boolean)
    Specifies whether the relation is included.
    Example: true

  - `plan.filter.groups.items.operator` (string)
    Defines the operator used in the filter. Available operators are defined in the API documentation.
    Example: "EQUALS"

  - `plan.filter.groups.items.value` (any)
    Represents the value to filter against.
    Example: 12345

  - `plan.filter.groups.items.smartContent` (boolean)
    When true, filter fields contain smart content placeholders resolved at runtime.
    Example: true

  - `plan.filter.groups.items.edgeProperty` (boolean)
    When true, propertyName refers to a property stored on the relation edge itself (declared on the relation schema, e.g. partstat on attendees) instead of a property of the related record. Requires relation and propertyName.

  - `plan.sort` (array)

  - `plan.sort.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.sort.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.sort.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.sort.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.sort.direction` (string)
    The direction for sorting. Can be ASC (ascending) or DESC (descending).
    Enum: "ASC", "DESC"

  - `plan.show` (array)

  - `plan.show.object` (string)
    The name of the object to which this pagination item belongs.
    Example: "User"

  - `plan.show.relation` (string)
    The relationship between objects.
    Example: "hasProperty"

  - `plan.show.relationDirection` (string)
    Optional relation direction: outgoing (related→main), incoming (main→related), or omit for undirected.
    Example: "outgoing"

  - `plan.show.property` (string)
    The name of the property within the object.
    Example: "email"

  - `plan.show.separator` (string)
    Separator string used to visually separate this item.
    Example: "|"

  - `plan.show.sticky` (boolean)
    Flag indicating whether this item is sticky and will stay fixed in the list.

  - `plan.show.width` (integer)
    Width of the item in pixels.
    Example: 100

  - `plan.show.calculationFunction` (string)
    Calculation function used to calculate the value of the item.
    Example: "max"

  - `plan.show.calculationResult` (any)
    Result of the calculation.
    Example: 100

  - `plan.strategy` (string)
    Enum: "AUTO", "STRUCTURED", "LEXICAL", "SEMANTIC", "HYBRID", "GRAPH"

  - `plan.anchorRecordUuid` (string)

  - `plan.criteria` (array)

  - `plan.graphTraversals` (array)

  - `plan.graphTraversals.relation` (string)

  - `plan.graphTraversals.targetObject` (string)

  - `plan.graphTraversals.direction` (string)

  - `plan.graphTraversals.maxDepth` (integer)

  - `plan.graphTraversals.includeLifecycle` (boolean)

  - `plan.graphTraversals.includeActivities` (boolean)

  - `plan.graphTraversals.perRelationLimit` (integer)

  - `plan.scoreWeights` (object)

  - `plan.includeEvidence` (boolean)

  - `plan.maxTraversalDepth` (integer)

  - `plan.page` (integer)

  - `plan.limit` (integer)

  - `confidence` (number)

  - `warnings` (array)

  - `diagnostics` (object)

## Response 400 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 401 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 403 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 404 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 500 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"