Concepts

Query & the AegisQuery AST

Search requests are a small, validated query object — the AegisQuery AST. The caller proposes it; the engine clamps scope, intersects grants, and ACL-filters before running it.

The query object#

The body of POST /v1/search is an AegisQuery. Only q is required; everything else has a safe default. It is validated with a strict schema — out-of-range values return 400.

Field	Type	Default	Description
`q`	string	— (required)	Natural-language query text.
`planes`	Plane[]	`["text"]`	Retrieval planes to search.
`top_k`	int 1–50	`20`	Number of hits to return.
`rrf_k`	int > 0	`60`	RRF rank constant (higher = flatter).
`rerank`	boolean	`true`	Apply the cross-encoder reranker.
`granularity`	`file \| sub_unit`	`sub_unit`	Return whole files or sub-unit spans.
`consistency`	`strong \| eventual`	`strong`	Read consistency preference.
`filters`	FilterClause[]	`[]`	Structured metadata filters.
`modalities`	Modality[]	unset	Restrict to specific modalities.
`answer`	boolean	`false`	Trigger live grounded, cited answer synthesis (also via POST /v1/answer).
`budget`	Budget	unset	Machine-checked execution guardrails.

Scope is not a body field

Although the schema carries a scope field, the search endpoint overrides it with the value from X-Aegis-Scope / ?scope=. Always set scope via the header or query parameter. See Authentication.

Tier clamps, it doesn't reject

On a search, rerank and any planes outside your tier are silently clamped to what the tier allows (graceful degradation) — a Free search still returns results, just without the cross-encoder or the visual/audio planes. Hard 402 gates apply to answer, multimodal ingest, and audit, not to search.

Filters & operators#

A filter clause is { field, op, value }. Values may be a string, number, boolean, or an array (for in / nin). Supported operators:

eq, neq — equality / inequality.
in, nin — membership against an array value.
lt, lte, gt, gte — numeric / ordinal comparisons.
prefix, contains — string matching.

a filtered query

{
  "q": "revenue guidance",
  "planes": ["text"],
  "top_k": 10,
  "rerank": true,
  "filters": [
    { "field": "modality", "op": "eq", "value": "asr" },
    { "field": "t_bucket", "op": "gte", "value": 480000 }
  ]
}

Execution budget#

The optional budget object bounds an agentic run so cost stays predictable. All fields have defaults and are enforced by the executor.

Field	Default	Meaning
`max_rounds`	`3`	Max retrieve → refine iterations.
`max_mllm_calls`	`2`	Max vision/LLM verification calls.
`max_neurons`	`8000`	Inference-unit spend ceiling.
`max_latency_ms`	`15000`	Wall-clock ceiling.

Validation

Requests are validated before execution. For example {"q":"x","top_k":999} is rejected because top_k exceeds 50:

400 Bad Request

{ "error": "bad_request", "detail": "...top_k...", "status": 400 }