Quick start

Get an account and an API key

1. Sign up in the console — email and password, no magic link or credit card.

2. Create an organization when prompted (a name and a URL-safe slug).

3. Open Organization → Settings → API keys and create two keys:

   • a full key — for your server. It creates collections and writes documents. Never ship it to a browser.
   • a search key — for the page. It can only search, recommend, send events and talk to the assistant; every other operation answers 403.

   API keys, scopes and credits lists exactly what a search key reaches.

4. Put the full key in your server's environment — never commit it.

export NOVA_API_KEY="…"          # the full key
export NOVA_SEARCH_KEY="…"       # the search key, for step 5

Every request carries the key in the X-NOVA-API-KEY header. Install the SDK (see SDKs for Python, PHP and Go):

npm install aacsearch

import { AACSearchClient } from "aacsearch";

const client = new AACSearchClient({
  baseUrl: "https://api.aacsearch.com/v1",
  apiKey: process.env.NOVA_API_KEY!,
});

Prefer clicking? The console's quick-start checklist does steps 1–3 with copyable snippets.

Create a collection

A collection is a schema — the fields your documents have and how each one is indexed (createCollection, POST /collections).

curl -X POST https://api.aacsearch.com/v1/collections \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "fields": [
      { "name": "name", "type": "string" },
      { "name": "brand", "type": "string", "facet": true },
      { "name": "category", "type": "string", "facet": true },
      { "name": "price", "type": "float" },
      { "name": "in_stock", "type": "bool" }
    ],
    "default_sorting_field": "price"
  }'

Import documents

Send documents as JSONL — one JSON object per line, each with an id (importDocuments, POST /collections/{collectionName}/documents/import). action=upsert makes the call safe to repeat.

cat > products.jsonl <<'EOF'
{"id":"42","name":"Cordless drill, 18V","brand":"Acme","category":"power-tools","price":89.0,"in_stock":true}
{"id":"43","name":"Impact driver, 18V","brand":"Acme","category":"power-tools","price":119.0,"in_stock":false}
EOF

curl -X POST "https://api.aacsearch.com/v1/collections/products/documents/import?action=upsert" \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/octet-stream" \
  --data-binary @products.jsonl

The response is JSONL too — one line per document, in the order you sent them: {"success": true} or {"success": false, "error": "…", "document": "…"}. The request answers 200 even when some lines failed, so check every line; see Incremental indexing for retrying only the failed rows.

A single document can also go through indexDocument (POST /collections/{collectionName}/documents).

Search

searchCollection (GET /collections/{collectionName}/documents/search) — the same call works with a full key and a search key.

curl -G https://api.aacsearch.com/v1/collections/products/documents/search \
  -H "X-NOVA-API-KEY: $NOVA_SEARCH_KEY" \
  --data-urlencode "q=cordles dril" \
  --data-urlencode "query_by=name,brand" \
  --data-urlencode "filter_by=in_stock:true" \
  --data-urlencode "per_page=20"

The response finds the drill even with two typos, and carries the platform's own extensions next to the engine's fields — query_rewrite when a zero-hit query was rescued, redirect and suggestions from any matching search rule.

Put search on a page

Load the widget from the CDN and give it the search key — never the full one:

<script type="module" src="https://cdn.aacsearch.com/aac-search.js"></script>
<aac-search
  api-url="https://api.aacsearch.com/v1"
  api-key="SEARCH_KEY"
  collection="products"
  query-by="name,brand"
  facet-by="brand,category"
  fields='{"title":"name","subtitle":"brand","price":"price"}'
></aac-search>

That is a complete search page with autocomplete, facets and click analytics. Widget covers every attribute, the AI assistant and short-lived browser keys.