Semantic Query

Resolve structured intent into an exact executable plan

Bounded deterministic planner.

This endpoint resolves structured intent into an exact plan for POST /v1/query. It only uses registered-source metadata, join graph metadata, planner cache, and precomputed statistics. It does not scan datasets or execute queries.

Scope rules:

  • Provide dataset_id for dataset-scoped planning, or
  • set allow_org_scope=true to plan across all visible datasets.

Deterministic guarantees:

  • identical intent_signature + schema_revision + scope => identical output
  • ambiguity clarifies or rejects; it never expands search
  • no fallback to slower planning paths exists
post/v1/resolve

Request

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

Request body

dataset_idstring nullable

Public dataset ID alias for a registered source. Required unless allow_org_scope=true or only one visible dataset exists.

group_bystring[]
preferred_sourcestring nullable
reject_on_ambiguityboolean
min_source_confidencenumber
aggregationstring

sum | avg | count | max | min

limitinteger nullable

Top-N limit

orderstring

desc | asc

raw_textstring nullable

Optional non-authoritative raw text hint. Structured intent remains the source of truth.

include_explanationboolean
allow_org_scopeboolean

When true, resolve can consider all visible datasets in the org.

Response

Successful Response

confidencenumber required
planstring[] required
explanationstring[]
resolved_columnstring
resolved_rolestring
resolved_sourcestring
source_scoresobject
latency_msnumber required
decision_pathstring required
plan_hashstring nullable
schema_revisionstring required
validatedboolean required
deterministic_scopestring required
confidence_sourcestring required
clarification_requiredboolean
rejection_reasonstring nullable
request_idstring nullable
intent_signaturestring required
source_setstring[]
join_pathobject[]
planner_modestring

Changes

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