Search an installation source with facets

Uses only the connector and collection explicitly bound to this installation source. The installation key never grants tenant-wide API access.

Full-key operation

Requires a full key; a search key or a browser key gets a 403. See Keys and credits.

Uses only the connector and collection explicitly bound to this installation source. The installation key never grants tenant-wide API access.

Header Parameters

X-AACSEARCH-INSTALLATION-KEY*string

Dedicated installation credential, issued once in Console.

Match^aac_install_[a-f0-9]{64}$

X-AACSEARCH-INSTALLATION-ORIGIN*string

HTTPS origin pinned to this installation; clones require another installation.

Formaturi

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Standard search parameters. Collection and preset are bound by Console, never selected by the module.

q?string

The query text to search for in the collection. Use * as the search string to return all documents. This is typically useful when used in conjunction with filter_by.

query_rewrite?string

AACSearch extension. When the search returns 0 hits, q is retried with these rewrites, in the given order, and the first one that finds documents is returned together with a query_rewrite object describing what was applied. layout re-types text entered on the wrong keyboard layout (,typjgbkf → бензопила, 2ч16пи → 2x16gb); translit transliterates between Cyrillic and Latin (девольт → devolt, samsung → самсунг); homoglyph folds look-alike letters in mixed-script tokens such as article numbers (RD-С80ТL → RD-C80TL). Comma-separated. Default layout,translit,homoglyph; off disables the retry.

refinements?string

AACSearch extension. Post-search refinement chips returned as refinements: facets (default, from the response's facet counts, ranked by information gain and availability), full (also query refinements from the query graph and requirement chips from the parsed constraints; one extra lookup), or off.

Value in

"off"
"facets"
"full"

search_policy?string

AACSearch extension. Name of a search policy to apply instead of the one the query's frame matches — for debugging and A/B experiments (a variant's search_params may set it).

x_user_id?string

AACSearch extension. The signed-in visitor's id (your own stable id) for personalization: when the collection has personalization enabled, the visitor's affinity profile (built from POST /events) becomes _eval boosts in front of sort_by, and personalization rules matching their segments fire. Alternative to the x-nova-user-id header. Never forwarded to the engine.

x_anonymous_id?string

AACSearch extension. The anonymous visitor's id (cookie/device id) for personalization, used when x_user_id is absent. Alternative to the x-nova-anonymous-id header.

x_personalization_strength?number

AACSearch extension. Overrides the collection's configured personalization strength (0 = off, 1 = full) for this request only — for simulation and A/B tests.

Range0 <= value <= 1

x_surface?string

AACSearch extension. autocomplete marks a typeahead request so the collection's "apply to autocomplete" personalization switch can gate it; anything else is a search.

Value in

"search"
"autocomplete"

debug?boolean

AACSearch extension. When true, the response includes _trace (what the platform did to the request) and every hit an _explain object (scoring signals and matched boosts). Never forwarded to the engine. The X-NOVA-DEBUG: 1 header is equivalent.

rerank?boolean

AACSearch extension. true reranks the leading hits with the model configured in the collection's search rules (defaults apply when the rule has none), false skips a rule-enabled reranker for this request. See SearchRuleRerank.

rerank_top_k?integer

AACSearch extension. Overrides how many leading hits the reranker scores (1–100).

Range1 <= value <= 100

rerank_model?string

AACSearch extension. Overrides the reranker model for this request.

Value in

"bge-reranker-base"
"llm"

query_by?string

A list of string fields that should be queried against. Multiple fields are separated with a comma.

validate_field_names?boolean

Controls whether AACSearch should validate if the fields exist in the schema. When set to false, AACSearch will not throw an error if a field is missing. This is useful for programmatic grouping where not all fields may exist.

nl_query?boolean

Whether to use natural language processing to parse the query.

nl_model_id?string

The ID of the natural language model to use.

nl_query_debug?boolean

When true, the raw model response is returned in parsed_nl_query.llm_response.

nl_query_prompt_cache_ttl?integer

Seconds to cache the schema prompt built for the natural language model. Default: 86400.

query_by_weights?string

The relative weight to give each query_by field when ranking results. This can be used to boost fields in priority, when looking for matches. Multiple fields are separated with a comma.

text_match_type?string

In a multi-field matching context, this parameter determines how the representative text match score of a record is calculated. Possible values are max_score (default) or max_weight.

prefix?string

Boolean field to indicate that the last word in the query should be treated as a prefix, and not as a whole word. This is used for building autocomplete and instant search interfaces. Defaults to true.

infix?string

If infix index is enabled for this field, infix searching can be done on a per-field basis by sending a comma separated string parameter called infix to the search query. This parameter can have 3 values; off infix search is disabled, which is default always infix search is performed along with regular search fallback infix search is performed if regular search does not produce results

max_extra_prefix?integer

There are also 2 parameters that allow you to control the extent of infix searching max_extra_prefix and max_extra_suffix which specify the maximum number of symbols before or after the query that can be present in the token. For example query "K2100" has 2 extra symbols in "6PK2100". By default, any number of prefixes/suffixes can be present for a match.

max_extra_suffix?integer

filter_by?string

Filter conditions for refining your open api validator search results. Separate multiple conditions with &&.

max_filter_by_candidates?integer

Controls the number of similar words that AACSearch considers during fuzzy search on filter_by values. Useful for controlling prefix matches like company_name:Acm*.

sort_by?string

A list of numerical fields and their corresponding sort orders that will be used for ordering your results. Up to 3 sort fields can be specified. The text similarity score is exposed as a special _text_match field that you can use in the list of sorting fields. If no sort_by parameter is specified, results are sorted by _text_match:desc,default_sorting_field:desc. Conditional ranking ("optional filtering"): use a scoring function with a filter expression to put matching documents first, e.g. scoring by in_stock:true combined with _text_match:desc; apply weighted scores to clauses like brand:Nike (weight 3) and brand:Adidas (weight 2). The collection's search rules can add such clauses for you (boosts).

facet_by?string

A list of fields that will be used for faceting your results on. Separate multiple fields with a comma.

max_facet_values?integer

Maximum number of facet values to be returned.

facet_query?string

Facet values that are returned can now be filtered via this parameter. The matching facet text is also highlighted. For example, when faceting by category, you can set facet_query=category:shoe to return only facet values that contain the prefix "shoe".

facet_query_num_typos?integer

Controls the number of typographical errors (0 to 2) tolerated when matching facet_query against facet values. Default: 2

num_typos?string

The number of typographical errors (1 or 2) that would be tolerated. Default: 2

page?integer

Results from this specific page number would be fetched.

per_page?integer

Number of results to fetch per page. Default: 10

limit?integer

Number of hits to fetch. Can be used as an alternative to the per_page parameter. Default: 10.

offset?integer

Identifies the starting point to return hits from a result set. Can be used as an alternative to the page parameter.

group_by?string

You can aggregate search results into groups or buckets by specify one or more group_by fields. Separate multiple fields with a comma. To group on a particular field, it must be a faceted field.

group_limit?integer

Maximum number of hits to be returned for every group. If the group_limit is set as K then only the top K hits in each group are returned in the response. Default: 3

group_missing_values?boolean

Setting this parameter to true will place all documents that have a null value in the group_by field, into a single group. Setting this parameter to false, will cause each document with a null value in the group_by field to not be grouped with other documents. Default: true

include_fields?string

List of fields from the document to include in the search result

exclude_fields?string

List of fields from the document to exclude in the search result

highlight_full_fields?string

List of fields which should be highlighted fully without snippeting

highlight_affix_num_tokens?integer

The number of tokens that should surround the highlighted text on each side. Default: 4

highlight_start_tag?string

The start tag used for the highlighted snippets. Default: <mark>

highlight_end_tag?string

The end tag used for the highlighted snippets. Default: </mark>

enable_highlight_v1?boolean

Flag for enabling/disabling the deprecated, old highlight structure in the response. Default: true

Defaulttrue

enable_analytics?boolean

Flag for enabling/disabling analytics aggregation for specific search queries (for e.g. those originating from a test script).

Defaulttrue

snippet_threshold?integer

Field values under this length will be fully highlighted, instead of showing a snippet of relevant portion. Default: 30

synonym_sets?string

List of synonym set names to associate with this search query

drop_tokens_threshold?integer

If the number of results found for a specific query is less than this number, AACSearch will attempt to drop the tokens in the query until enough results are found. Tokens that have the least individual hits are dropped first. Set to 0 to disable. Default: 10

drop_tokens_mode?DropTokensMode

Dictates the direction in which the words in the query must be dropped when the original words in the query do not appear in any document. Values: right_to_left (default), left_to_right, both_sides:3 A note on both_sides:3 - for queries up to 3 tokens (words) in length, this mode will drop tokens from both sides and exhaustively rank all matching results. If query length is greater than 3 words, AACSearch will just fallback to default behavior of right_to_left

Value in

"right_to_left"
"left_to_right"
"both_sides:3"

typo_tokens_threshold?integer

If the number of results found for a specific query is less than this number, AACSearch will attempt to look for tokens with more typos until enough results are found. Default: 100

enable_typos_for_alpha_numerical_tokens?boolean

Set this parameter to false to disable typos on alphanumerical query tokens. Default: true.

filter_curated_hits?boolean

Whether the filter_by condition of the search query should be applicable to curated results (curation definitions, pinned hits, hidden hits, etc.). Default: false

enable_synonyms?boolean

If you have some synonyms defined but want to disable all of them for a particular search query, set enable_synonyms to false. Default: true

synonym_prefix?boolean

Allow synonym resolution on word prefixes in the query. Default: false

synonym_num_typos?integer

Allow synonym resolution on typo-corrected words in the query. Default: 0

pinned_hits?string

A list of records to unconditionally include in the search results at specific positions. An example use case would be to feature or promote certain items on the top of search results. A list of record_id:hit_position. Eg: to include a record with ID 123 at Position 1 and another record with ID 456 at Position 5, you'd specify 123:1,456:5. You could also use the Curation feature to override search results based on rules. Curations are applied first, followed by pinned_hits and finally hidden_hits.

hidden_hits?string

A list of records to unconditionally hide from search results. A list of record_ids to hide. Eg: to hide records with IDs 123 and 456, you'd specify 123,456. You could also use the Curation feature to override search results based on rules. Curations are applied first, followed by pinned_hits and finally hidden_hits.

curation_tags?string

Comma separated list of tags to trigger the curations rules that match the tags.

highlight_fields?string

A list of custom fields that must be highlighted even if you don't query for them

split_join_tokens?string

Treat space as typo: search for q=basket ball if q=basketball is not found or vice-versa. Splitting/joining of tokens will only be attempted if the original query produces no results. To always trigger this behavior, set value to always``. To disable, set value to off. Default is fallback`.

pre_segmented_query?boolean

You can index content from any logographic language into AACSearch if you are able to segment / split the text into space-separated words yourself before indexing and querying. Set this parameter to true to do the same

preset?string

Search using a bunch of search parameters by setting this parameter to the name of the existing Preset.

profile?string

AACSearch extension. Name of a search profile on the collection: the platform compiles it into query_by, facet_by, sort_by, highlight_fields and the fixed filter before the request reaches the engine, and rejects a request that also sets those parameters itself (400). A browser key pinned to a profile applies it without this parameter. Never forwarded to the engine.

sort?string

AACSearch extension. Id of one of the profile's sorts (see getSearchProfileView); defaults to the profile's default_sort_id. Only meaningful with profile. Never forwarded to the engine.

enable_curations?boolean

If you have some curation sets defined but want to disable all of them during query time, you can do that by setting this parameter to false

Defaultfalse

prioritize_exact_match?boolean

Set this parameter to true to ensure that an exact match is ranked above the others

Defaulttrue

max_candidates?integer

Control the number of words that AACSearch considers for typo and prefix searching.

prioritize_token_position?boolean

Make AACSearch prioritize documents where the query words appear earlier in the text.

Defaultfalse

prioritize_num_matching_fields?boolean

Make AACSearch prioritize documents where the query words appear in more number of fields.

Defaulttrue

enable_typos_for_numerical_tokens?boolean

Make AACSearch disable typos for numerical tokens.

Defaulttrue

exhaustive_search?boolean

Setting this to true will make AACSearch consider all prefixes and typo corrections of the words in the query without stopping early when enough results are found (drop_tokens_threshold and typo_tokens_threshold configurations are ignored).

search_cutoff_ms?integer

AACSearch will attempt to return results early if the cutoff time has elapsed. This is not a strict guarantee and facet computation is not bound by this parameter.

use_cache?boolean

Enable server side caching of search query results. By default, caching is disabled.

cache_ttl?integer

The duration (in seconds) that determines how long the search query is cached. This value can be set on a per-query basis. Default: 60.

min_len_1typo?integer

Minimum word length for 1-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.

min_len_2typo?integer

Minimum word length for 2-typo correction to be applied. The value of num_typos is still treated as the maximum allowed typos.

vector_query?string

Vector query expression for fetching documents "closest" to a given query/document vector, in the form field:([values], option: value, ...). Provide the vector inline (embedding:([0.1, 0.2, ...])), reference a document to find similar ones (embedding:([], id: doc_id)), or pass a base64 image for a CLIP-embedded field (embedding:([], image: BASE64)). Options: k (number of nearest neighbours), distance_threshold, alpha (weight of the vector score in hybrid search), ef (HNSW search depth), flat_search_cutoff.

remote_embedding_timeout_ms?integer

Timeout (in milliseconds) for fetching remote embeddings.

remote_embedding_num_tries?integer

Number of times to retry fetching remote embeddings.

facet_strategy?string

Choose the underlying faceting strategy used. Comma separated string of allows values: exhaustive, top_values or automatic (default).

stopwords?string

Name of the stopwords set to apply for this search, the keywords present in the set will be removed from the search query.

facet_return_parent?string

Comma separated string of nested facet fields whose parent object should be returned in facet response.

voice_query?string

Deprecated

Low-level engine path: a base64 encoded audio file in 16 kHz 16-bit WAV format, English only. Prefer POST /collections/{collectionName}/documents/search/by_voice, which accepts what browsers actually record (webm/opus, m4a, wav), detects the language, and returns the transcript alongside the results. This parameter is forwarded to the engine unchanged and requires a voice query model to be configured for your account.

conversation?boolean

Enable conversational search.

conversation_model_id?string

The Id of Conversation Model to be used.

conversation_id?string

The Id of a previous conversation to continue, this tells AACSearch to include prior context when communicating with the LLM.

conversation_stream?boolean

When true, the conversational answer is streamed as Server-Sent Events. Each event is data: {"conversation": {"message": "...", "conversation_id": "..."}}; the stream ends with data: [DONE] after a final event carrying the complete search response. Supported on POST /multi_search only.

Response Body

`application/json`

curl -X POST "https://example.com/cms/runtime/stores/string/sources/string/search" \  -H "X-AACSEARCH-INSTALLATION-KEY: string" \  -H "X-AACSEARCH-INSTALLATION-ORIGIN: http://example.com" \  -H "Content-Type: application/json" \  -d '{}'

{  "_trace": {},  "facet_counts": [    {      "counts": [        {          "count": 0,          "highlighted": "string",          "value": "string",          "parent": {}        }      ],      "field_name": "string",      "sampled": true,      "stats": {        "max": 0.1,        "min": 0.1,        "sum": 0.1,        "total_values": 0,        "avg": 0.1      }    }  ],  "found": 0,  "found_docs": 0,  "search_time_ms": 0,  "out_of": 0,  "search_cutoff": true,  "page": 0,  "grouped_hits": [    {      "found": 0,      "group_key": [        null      ],      "hits": [        {          "highlights": [            {              "field": "company_name",              "snippet": "<mark>Stark</mark> Industries"            }          ],          "document": {            "id": "124",            "company_name": "Stark Industries",            "num_employees": 5215,            "country": "USA"          },          "text_match": 1234556        }      ]    }  ],  "hits": [    {      "highlights": [        {          "field": "company_name",          "snippet": "<mark>Stark</mark> Industries"        }      ],      "document": {        "id": "124",        "company_name": "Stark Industries",        "num_employees": 5215,        "country": "USA"      },      "text_match": 1234556    }  ],  "request_params": {    "collection_name": "string",    "first_q": "string",    "q": "string",    "per_page": 0,    "voice_query": {      "transcribed_query": "string"    }  },  "conversation": {    "answer": "string",    "conversation_history": [      {}    ],    "conversation_id": "string",    "query": "string"  },  "union_request_params": [    {      "collection_name": "string",      "first_q": "string",      "q": "string",      "per_page": 0,      "voice_query": {        "transcribed_query": "string"      }    }  ],  "metadata": {},  "parsed_nl_query": {    "parse_time_ms": 0,    "generated_params": {},    "augmented_params": {},    "llm_response": {}  },  "query_rewrite": {    "strategy": "layout",    "original_q": "string",    "q": "string"  },  "rerank": {    "applied": true,    "model": "bge-reranker-base",    "scored": 0,    "ms": 0,    "skipped": "string"  },  "redirect": {    "url": "string",    "query": "string"  },  "suggestions": [    {      "query": "string",      "source": "manual",      "filter_by": "string",      "facet": {        "field": "string",        "value": "string",        "count": 0      }    }  ],  "query_understanding": {    "intent": "navigational",    "relation": "SUBSTITUTE",    "strategy": "string",    "policy": "string",    "search_text": "string",    "protected_tokens": [      "string"    ],    "entities": [      {        "entity_id": "string",        "type": "brand",        "canonical": "string",        "alias": "string",        "confidence": 0      }    ],    "constraints": [      {        "kind": "string",        "op": "eq",        "value": null,        "unit": "string",        "currency": "string",        "hardness": "hard",        "text": "string",        "filter_by": "string"      }    ],    "confidence": 0  },  "correction": {    "state": "NO_CORRECTION",    "applied": {      "q": "string",      "type": "RAW",      "score": 0,      "found": 0    },    "suggestions": [      {        "q": "string",        "type": "RAW",        "score": 0,        "found": 0      }    ],    "reason": "string"  },  "refinements": [    {      "id": "string",      "type": "facet",      "label": "string",      "query": "string",      "filter_by": "string",      "field": "string",      "value": "string",      "count": 0,      "score": 0,      "dimension": "string"    }  ]}

Search an installation source with facets

Path Parameters

Header Parameters

Request Body

Response Body

200application/json

400

401application/json

402

403application/json

404

409

429application/json

503

`application/json`

`application/json`

`application/json`

`application/json`