{"$defs":{"AppliedControls":{"description":"The request controls this deployment actually understood and applied.\n\nExists because an unknown request field is silently dropped: without this, a\nclient sending `match: \"exact\"` to a deployment that predates the field gets a\n200 with fuzzy matching still on — a strictness knob failing OPEN and saying\nnothing. Assert on this rather than trusting that your request was understood; a\ncontrol missing from this object was not applied.","properties":{"cache_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Cache Only"},"match":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Match"},"max_distance":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Max Distance"},"max_age_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Max Age Seconds"},"distill":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Distill"},"prewarm_on_miss":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Prewarm On Miss"}},"title":"AppliedControls","type":"object"},"Source":{"description":"One cited web source.","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Snippet"},"extra_snippets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Additional excerpts for the same page, when the upstream search provider supplies them. Richer than the single description blurb; not a live fetch of the page by Aimnis.","title":"Extra Snippets"},"fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO-8601 UTC timestamp of when Aimnis fetched this source. On a cache hit this is when the CACHED entry was built or last refreshed, not when you asked.","title":"Fetched At"}},"title":"Source","type":"object"},"WarmStatus":{"description":"Background-warm status, present only when a request set prewarm_on_miss and\nthe reply was a cache_miss. Same values as POST /v1/prewarm's `status`.","properties":{"status":{"enum":["cached","scheduled","already_warming","busy","disabled"],"title":"Status","type":"string"},"query_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Query Hash"},"entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Entry Id"}},"required":["status"],"title":"WarmStatus","type":"object"}},"additionalProperties":true,"description":"Response contract version 1. Compatible changes (new fields, new enum values) keep this version; removals, renames and type changes bump it. Parsers MUST ignore unknown fields and tolerate unknown enum values. `x-aimnis-matching` describes the semantic-cache metric and thresholds. To check what a given deployment supports, assert on the `applied` object in any response, or send a deliberately invalid value for a control (e.g. match='nonsense') and read the 422: it names the fields this server's request model knows.","properties":{"schema_version":{"default":1,"description":"Version of this response contract. See the schema document's description for the compatibility rules.","title":"Schema Version","type":"integer"},"source":{"description":"Where the reply came from. 'cache' = served from the pool. 'live' = pool miss, searched live and pooled. 'cache_miss' = cache_only request with nothing cached (no live search run). 'quota' = free live-search allowance exhausted. 'error' = every upstream search provider failed.","enum":["cache","live","cache_miss","quota","error"],"title":"Source","type":"string"},"match":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"How a cached entry was matched: 'exact' (same normalized question) or 'semantic' (a DIFFERENT but near question — see matched_query). Null when nothing was served from cache.","enum":["exact","semantic",null],"title":"Match"},"matched_query":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The question this cached answer was actually stored for. Differs from your query whenever match='semantic'.","title":"Matched Query"},"distance":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Cosine distance between your query's embedding and the matched entry's. 0.0 for an exact match; on a miss, the distance of the best candidate that was REJECTED (null if there was none).","title":"Distance"},"rerank_score":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Cross-encoder score (0..1) of the best semantic candidate — the value the accept decision was actually made on. Null for exact matches and when reranking is unavailable.","title":"Rerank Score"},"answer":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"AI-generated answer citing the sources as [n]. Null whenever answer_status is not 'ok'. Time-sensitive facts should be verified against the cited sources.","title":"Answer"},"answer_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Why `answer` is what it is. 'ok' = present. 'pending' = the cached entry has sources but has not been distilled yet (the background refresh queue will upgrade it). 'not_requested' = the request set distill=false. 'rejected' = an answer was generated but failed the quality gate, so it was not served or pooled. 'unavailable' = generation was disabled, quota-denied, timed out or errored. 'none' = no answer applies to this reply.","enum":["ok","pending","not_requested","rejected","unavailable","none"],"title":"Answer Status"},"results":{"description":"Cited sources, ranked. The answer's [n] citations index this list from 1.","items":{"$ref":"#/$defs/Source"},"title":"Results","type":"array"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Upstream model that produced `answer` (null when there is none).","title":"Model"},"entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Knowledge-pool entry id (UUID). Pass it back as reject_entry to skip this entry and force a live search. Null when nothing was pooled.","title":"Entry Id"},"cached_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO-8601 UTC timestamp of when the served content was produced or last refreshed.","title":"Cached At"},"age_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Age of the served content in seconds (0.0 for a fresh live search). Entries have no fixed TTL — staleness is reported here rather than enforced by expiry, so the caller decides.","title":"Age Seconds"},"distilled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Live path only: whether an answer was generated for this reply.","title":"Distilled"},"distill_rejected":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Live path only: an answer was generated but the quality gate rejected it.","title":"Distill Rejected"},"quality_score":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Live path only: heuristic answer score (0..1).","title":"Quality Score"},"quality_flags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Live path only: reasons behind quality_score.","title":"Quality Flags"},"pooled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Live path only: whether this result entered the shared pool. False when the query looked secret-dense and was served live-only.","title":"Pooled"},"scrubbed":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Kinds of secret/PII redaction applied to your query before it reached any third party or the pool. Null when nothing matched.","title":"Scrubbed"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Present when source='error': the upstream failure.","title":"Error"},"applied":{"anyOf":[{"$ref":"#/$defs/AppliedControls"},{"type":"null"}],"default":null,"description":"Which request controls this deployment understood and applied. A control you sent that is ABSENT here was silently dropped by an older deployment and did NOT take effect — assert on this before trusting that a strictness parameter was honoured."},"warm":{"anyOf":[{"$ref":"#/$defs/WarmStatus"},{"type":"null"}],"default":null,"description":"Present only when the request set prewarm_on_miss and this reply was a cache_miss: whether a background build was scheduled. Deliberately namespaced so it cannot change the meaning of any other field."},"formatted":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The whole reply pre-rendered as text for an LLM context, including the AI-generated and freshness disclosures. Convenience only; the structured fields above are the contract.","title":"Formatted"}},"required":["source"],"title":"Aimnis POST /v1/search response","type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","x-aimnis-schema-version":1,"x-aimnis-matching":{"embedding_model":"BAAI/bge-small-en-v1.5","embedding_dimensions":384,"distance_metric":"cosine","distance_definition":"1 - cosine_similarity (pgvector `<=>` operator)","distance_range":[0.0,2.0],"stages":[{"stage":"exact","detail":"Normalized-query sha256 match. distance is reported as 0.0."},{"stage":"semantic_recall","detail":"Approximate nearest neighbours within recall_max_distance are retrieved as candidates; this gate alone never decides a hit.","recall_max_distance":0.3,"candidates":5,"enabled":true},{"stage":"semantic_rerank","detail":"A cross-encoder rescores the candidate QUESTIONS against the incoming query and the best is served only if its score clears min_score. This — not distance — is the accept decision, which is why a served match can sit at a distance a pure distance threshold would have rejected.","model":"Xenova/ms-marco-MiniLM-L-6-v2","score_range":[0.0,1.0],"min_score":0.5,"good_at":"Polarity and negation between otherwise-identical questions ('enable X' vs 'disable X'), which a bi-encoder embedding each question independently tends to miss. This is the failure mode it was added for.","bad_at":"ATTRIBUTE SUBSTITUTION on a matched entity — same institution or subject, different fact ('Rice application deadline' vs 'Rice SAT percentile'; 'IELTS fee Taiwan' vs 'TOEFL fee Taiwan'). Relevance rewards exactly that overlap: it answers 'is this passage relevant to this query', not 'is this the same question', and the two come apart when the entity matches and the attribute does not. So rerank_score is NOT a usable gate for this class — consumer-measured scores of 0.86-0.96 on wrong-attribute matches sit inside the range of good ones. Use max_distance instead: on the same sample, distance separated cleanly (good <= 0.079, wrong-attribute >= 0.158), or send match='exact' to opt out entirely."},{"stage":"fallback","detail":"If the cross-encoder cannot be loaded, the nearest candidate within cache_max_distance is served instead.","cache_max_distance":0.15}],"caller_controls":{"match":"'exact' disables the semantic stages entirely — only an exact normalized-query match may be served.","max_distance":"Additional ceiling on an accepted match's distance. Only tightens the server thresholds; a value above recall_max_distance has no effect. Prefer this over rerank_score for wrong-attribute matches (see the semantic_rerank stage's bad_at).","max_age_seconds":"Freshness bound; an older entry is not a hit and the request goes live. Use this to decline stale content rather than reject_entry, which records a negative ranking signal against a correct-but-old entry in a pool shared with every other caller."},"advice":"Any semantic match is a DIFFERENT question than the one you asked. `matched_query` is the question the answer was cached for — a consumer that cannot tolerate substitution should either compare it against its own query, or send match='exact'. Note that inspecting matched_query means comparing natural language: for a wrong-attribute match the mismatch is NOT visible in distance or rerank_score alone."}}