Semantic Query
Semantic Query

Validate a structured query plan before execution

LLM calls this after reading /v1/sources/schema.

Submit the exact source + column names chosen by the LLM. The engine verifies:

  • Source exists in registry
  • metric_column exists and is numeric
  • aggregation is valid for the column's role
  • group_column exists (if given)
  • join path exists with sufficient confidence (if join_source_name given)

Returns valid: true + resolved names on success, or valid: false + errors + suggestions on failure. Call /v1/execute (or /v1/query with exact-spec) only after verify returns valid.

post/v1/verify

Request

  • Base URL: https://api.algenta.ai
  • URL: https://api.algenta.ai/v1/verify
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

source_namestring nullable

Exact source name from schema

dataset_idstring nullable

Public dataset ID alias for a registered source. When provided, verification is scoped to that one registered dataset.

metric_columnstring nullable

Exact column name to aggregate

aggregationstring nullable

sum | avg | count | max | min

group_columnstring nullable

Exact column name for group-by

join_source_namestring nullable

Second source name for join

join_columnsstring[] nullable

[local_col, remote_col] — join key pair. Omit to auto-detect.

min_join_confidencenumber

Reject join paths below this confidence threshold. Default 0.85 — only statistically solid joins are accepted. Lower to 0.50 to allow weaker joins at your own risk.

modestring

strict — reject invalid plans with no suggestions (enterprise enforcement). assist — reject invalid plans AND return corrective suggestions (default, LLM-friendly).

Response

Successful Response

validboolean required
errorsstring[] required
suggestionsstring[] required
resolvedobject required
valid_dimensionsstring[]
valid_measuresstring[]
source_behaviorstring
latency_msnumber required
verifiedboolean
request_idstring nullable
schema_revisionstring nullable
plan_hashstring nullable
verification_modestring
rejection_reasonstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.