Быстрый старт

Получите аккаунт и API-ключ

1. Зарегистрируйтесь в консоли — по email и паролю, без magic link и банковской карты.

2. Создайте организацию, когда консоль это предложит (название и slug, допустимый в URL).

3. Откройте Organization → Settings → API keys и создайте два ключа:

   • полный (full) — для вашего сервера. Он создаёт коллекции и записывает документы. Никогда не передавайте его в браузер.
   • поисковый (search) — для страницы. Он умеет только искать, получать рекомендации, отправлять события и общаться с ассистентом; на любую другую операцию API отвечает 403.

   Точный список операций поискового ключа — в разделе API-ключи, области доступа и кредиты.

4. Сохраните полный ключ в окружении сервера и никогда не коммитьте его.

export NOVA_API_KEY="…"          # полный ключ
export NOVA_SEARCH_KEY="…"       # поисковый ключ, для шага 4

Ключ передаётся в заголовке X-NOVA-API-KEY каждого запроса. Установите SDK (клиенты для Python, PHP и Go — в разделе SDK):

npm install aacsearch

import { AACSearchClient } from "aacsearch";

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

Предпочитаете интерфейс? Чек-лист быстрого старта в консоли проводит через шаги 1–3 с готовыми фрагментами кода.

Создайте коллекцию

Коллекция — это схема: поля ваших документов и способ индексации каждого из них (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"
  }'

Импортируйте документы

Документы отправляются в формате JSONL — один JSON-объект на строку, у каждого есть id (importDocuments, POST /collections/{collectionName}/documents/import). С action=upsert запрос можно безопасно повторять.

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

Ответ тоже в JSONL — по строке на каждый документ, в том же порядке: {"success": true} или {"success": false, "error": "…", "document": "…"}. Запрос отвечает 200, даже если часть строк не записалась, поэтому проверяйте каждую строку; как повторять только неудачные строки, описано в разделе Инкрементальная индексация.

Отдельный документ можно записать и через indexDocument (POST /collections/{collectionName}/documents).

Выполните поиск

searchCollection (GET /collections/{collectionName}/documents/search) — этот вызов работает и с полным, и с поисковым ключом.

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"

Ответ находит дрель даже с двумя опечатками и, помимо полей поискового движка, содержит расширения платформы: query_rewrite, если запрос без результатов был исправлен, а также redirect и suggestions из сработавшего поискового правила.

Добавьте поиск на страницу

Подключите виджет с CDN и передайте ему поисковый ключ — никогда не полный:

<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>

Это готовая страница поиска с автодополнением, фасетами и аналитикой кликов. Все атрибуты, AI-ассистент и короткоживущие браузерные ключи описаны в разделе Виджет.