Подсказки

GET  /api/v1/indexes/{slug}/suggest
POST /api/v1/indexes/suggest/multi

Автодополнение — другая нагрузка, чем поиск: короткие запросы, маленькие ответы, никакой стоимости квоты и агрессивное кеширование. Оба эндпоинта требуют search:read и ограничены по частоте на ключ, но не расходуют поисковую квоту тарифа.

Один индексCopy Anchor Link

curl -sS -G "$AAC_API/indexes/documentation/suggest" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=тар" \
  --data-urlencode "query_by=title" \
  --data-urlencode "limit=5" \
  --data-urlencode "filter_by=tags:=[billing]" \
  --data-urlencode "include_popular=true"

{
	"index": "documentation",
	"query": "тар",
	"suggestions": [
		{
			"text": "Тарифы",
			"source": "document",
			"documentId": "pricing",
			"url": "https://example.com/pricing",
			"score": 3,
			"highlight": "<mark>Тар</mark>ифы"
		},
		{
			"text": "тарифы и планы",
			"source": "query",
			"score": 2
		}
	],
	"did_you_mean": null,
	"sources": { "documents": 1, "queries": 1 },
	"cache": "miss",
	"request_id": "req_1c2d3e4f5a6b7c8d9e0f1a2b"
}

source равен document для заголовка документа и query для подсказки, добытой из журнала запросов. documentId и url присутствуют только у документов. highlight оборачивает введённый префикс в <mark>, чтобы виджету не приходилось искать совпадение самостоятельно.

did_you_mean содержит исправленное написание, если устойчивый к опечаткам проход нашёл вариант лучше исходного префикса.

Префикс, суффикс и цена под поискомCopy Anchor Link

Префиксные совпадения идут первыми. Суффиксные и внутренние совпадения дополняют список по полям с infix: true: отсутствие infix у content не мешает использовать infix у title. Для новых и перестраиваемых коллекций он включён у title. Старым коллекциям нужен обычный асинхронный reindex.

Запрос плат от 1000 р ищет подсказки для плат с минимальной ценой 1000. Если есть публичное числовое поле цены и включён разбор цены, active_filters содержит распознанный фильтр для chip под поиском. Для выбора подсказки используйте completionQuery, если он есть: ограничение цены сохранится.

Виджет вызывает POST /api/v1/embed/suggest с {token, index, q, limit}. Endpoint ограничен по частоте, проверяет embed-сессию и не списывает поисковую квоту. Console и виджет поддерживают стрелки, Enter, Escape и выбор мышью.

Завершение слов и фраз, исправленияCopy Anchor Link

Подсказки содержат completionType: "word" | "phrase": завершение текущего слова (или предложение следующего) и полное название из индекса. Например, красное пл дополняется до красное платье, а фразовая подсказка предлагает Красное платье летнее. Значения строятся из публичных совпавших заголовков.

did_you_mean предлагает проверенное исправление опечатки, перестановки букв или раскладки (зотн → зонт, руддщ → hello). Исходный query сохраняется; Console и виджет показывают отдельную строку «Возможно, вы имели в виду». did_you_mean_kind различает graph, fuzzy, layout и translit. Настройки enableDidYouMean, relaxLayout и relaxTranslit учитываются.

Кеширование и ревалидацияCopy Anchor Link

Ответы несут сильный etag и cache-control: private, max-age=30; внутренний кеш живёт 30 секунд на тенанта и отражается полем cache: "hit" или "miss". Обратная отправка ETag экономит трафик:

curl -sS -i -G "$AAC_API/indexes/documentation/suggest" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H 'If-None-Match: "3f9a1c7e5b2d8a0c4e6f"' \
  --data-urlencode "q=тар"

HTTP/1.1 304 Not Modified
etag: "3f9a1c7e5b2d8a0c4e6f"

ETag считается без поля cache, поэтому попадание и промах кеша для одинаковых подсказок валидируются одинаково.

Несколько индексов сразуCopy Anchor Link

curl -sS -X POST "$AAC_API/indexes/suggest/multi" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "indexes": ["documentation", "blog"], "q": "тар", "limit": 5 }'

{
	"query": "тар",
	"results": [
		{
			"index": "documentation",
			"suggestions": [
				{
					"text": "Тарифы",
					"source": "document",
					"documentId": "pricing",
					"url": "https://example.com/pricing",
					"score": 3
				}
			],
			"did_you_mean": null,
			"cache": "miss"
		},
		{
			"index": "blog",
			"suggestions": [],
			"did_you_mean": null,
			"cache": "miss"
		}
	],
	"request_id": "req_8b4f2a6c0d1e3f5a7b9c1d3e"
}

indexes принимает от 1 до 10 слагов; для каждого проверяются права и лимит запросов, результаты сгруппированы по индексам в переданном порядке. Некорректный ввод отклоняется со статусом 422 до обращения к движку:

{
	"error": {
		"code": "INVALID_QUERY",
		"message": "indexes must contain 1-10 slugs"
	}
}

Дубликаты удаляются до fan-out: ["docs","docs"] — это один запрос, а не два.

Presearch (пустая строка поиска)Copy Anchor Link

GET  /api/v1/indexes/{slug}/presearch
POST /api/v1/embed/presearch

Подсказки, которые показываются до первого нажатия клавиши. REST-маршрут требует ключ с search:read и ограничен по ключу; embed-маршрут принимает токен сессии встраивания (поле token в теле или Authorization: Bearer aac_sess_…) и ограничен по адресу клиента. Ни один из них не расходует квоту поиска.

curl -sS -G "$AAC_API/indexes/documentation/presearch" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "session_id=visitor-4f7c2a9e1b3d" \
  --data-urlencode "q=pricing" \
  --data-urlencode "limit=8"

{
	"index": "documentation",
	"items": [
		{ "query": "pricing plans", "source": "continue", "score": 0.82 },
		{ "query": "invoice download", "source": "recent" },
		{ "query": "api keys", "source": "trending", "score": 41 }
	],
	"request_id": "req_6a1f0c3e9b2d4a7c8e5f1b0d"
}

source показывает происхождение подсказки, в таком порядке:

• continue — рёбра сужения, уточнения или исправления из графа запросов для q.
• recent — собственные успешные запросы этого посетителя.
• trending — популярные запросы за 7 дней, только если их ввели не менее 3 разных посетителей.

Запросы, похожие на персональные данные или секреты (email, телефоны, длинные последовательности цифр вроде номеров заказов или карт, ссылки), и хэшированные запросы не возвращаются никогда. Неверные параметры дают 422 VALIDATION_ERROR.