Search profiles and releases

A search profile names the fields, facets, filters and sort choices a storefront uses. The client sends profile=storefront instead of raw query_by, facet_by or sort_by. A search key can be bound to a profile so the client cannot select another one.

Create a profile

Use Console → Search profiles, select a collection and create a profile. Configure searchable fields, facet fields and named sorts. A facet field must support faceting in the collection schema. Sort fields must support sorting. The fixed filter is always combined with the visitor's filter.

Or call the API with a full key. The following example assumes a products collection with an indexed string field title:

curl -X POST 'https://api.aacsearch.com/v1/collections/products/search-profiles' \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":"storefront","label":"Storefront","searchable_fields":["title"],"per_page_max":24}'

Names are stable identifiers; a full update replaces the profile body, so omitted fields reset to defaults. The is_default flag helps interfaces select a profile; the API never applies it implicitly.

Use the profile

curl --get 'https://api.aacsearch.com/v1/collections/products/documents/search' \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" \
  --data-urlencode 'q=shoes' \
  --data-urlencode 'profile=storefront'

Do not send raw profile-owned parameters alongside profile. Use sort=<id> to select a configured sort. Visitor filters may reference only the profile's facet and filterable fields; page size must fit per_page_max. The same rules apply to multiSearch items.

The widget supports the profile attribute. The browser-safe GET /collections/{collectionName}/search-profiles/{profileName}/view endpoint returns labels, sort IDs and facets, not engine expressions or full configuration.

Publish a release

Until the first publication, saved edits affect the next search. The first publication opts the profile into release mode: subsequent edits affect only the draft until another publication.

publishSearchProfile (POST .../releases) is the API call behind the console steps above. API clients first read the current profile and its revision, then send that value as expected_revision:

POST /collections/products/search-profiles/storefront/releases
Content-Type: application/json
X-NOVA-API-KEY: YOUR_FULL_KEY

{"expected_revision":1,"note":"Initial storefront configuration","change_class":"HOT"}

1 above is illustrative: always use the revision you just read. A concurrent edit or publication produces 409; reload and review before retrying. Only HOT, query-time releases are supported. WARM/COLD requests that would require index migration are refused.

History and rollback

listSearchProfileReleases (GET .../releases?limit=20) lists newest versions first. When next_before_version is returned, pass it as before_version to fetch older history.

activateSearchProfileRelease — activate an older version from Console or POST .../releases/{version}/activate with the current expected_revision. Activation preserves the draft; repeating activation of the already active version is idempotent. A missing or damaged active snapshot fails closed rather than silently serving draft settings.

A release captures the profile manifest. It does not back up indexed documents, freeze an external search_policy definition or undo a collection-schema change. See launch checks and errors.