Suggest

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

Autocomplete ist eine andere Last als Suche: kürzere Anfragen, kleinere Antworten, keine Kontingentkosten, aggressives Caching. Beide Endpunkte erfordern search:read und unterliegen dem Rate-Limit pro Schlüssel, verbrauchen aber kein Suchkontingent des Tarifs.

Ein einzelner IndexCopy Anchor Link

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

{
	"index": "documentation",
	"query": "pre",
	"suggestions": [
		{
			"text": "Preise",
			"source": "document",
			"documentId": "pricing",
			"url": "https://example.com/pricing",
			"score": 3,
			"highlight": "<mark>Pre</mark>ise"
		},
		{
			"text": "preise tarife",
			"source": "query",
			"score": 2
		}
	],
	"did_you_mean": null,
	"sources": { "documents": 1, "queries": 1 },
	"cache": "miss",
	"request_id": "req_1c2d3e4f5a6b7c8d9e0f1a2b"
}

source ist document für einen Dokumenttitel und query für eine aus dem Query-Log gewonnene Ergänzung. documentId und url gibt es nur bei Dokument-Vorschlägen. highlight setzt den eingegebenen Präfix in <mark>, damit das Widget nicht selbst matchen muss.

did_you_mean enthält eine korrigierte Schreibweise, wenn der tippfehlertolerante Durchlauf etwas Besseres als den rohen Präfix gefunden hat.

Präfix, Suffix und PreisfilterCopy Anchor Link

Präfix-Treffer stehen zuerst. Zusätzliche Infix-/Suffix-Treffer nutzen nur Felder mit infix: true; ein Feld ohne Infix-Index deaktiviert andere Felder nicht. Neue und neu aufgebaute Collections aktivieren Infix für title. Bestehende Collections benötigen den normalen asynchronen Reindex.

плат от 1000 р ergänzt плат mit einem Mindestpreis von 1000. active_filters beschreibt den erkannten Preisfilter, sofern ein öffentliches Preisfeld existiert. completionQuery erhält die Preisgrenze bei der Auswahl. Das Widget nutzt POST /api/v1/embed/suggest mit {token, index, q, limit}, Rate-Limit und Embed-Sitzung, ohne Suchkontingent zu verbrauchen.

Wort- und Phrasenergänzungen, KorrekturenCopy Anchor Link

completionType: "word" | "phrase" unterscheidet Wortergänzungen von ganzen öffentlichen Titeln. did_you_mean bietet geprüfte Tippfehler- und Tastaturlayout-Korrekturen an. Die ursprüngliche Anfrage bleibt erhalten; Preisgrenzen bleiben bei der Auswahl einer Ergänzung oder Korrektur bestehen.

Caching und RevalidierungCopy Anchor Link

Antworten tragen ein starkes etag und cache-control: private, max-age=30; der interne Cache hält 30 Sekunden pro Mandant und meldet sich als cache: "hit" oder "miss". Das Zurücksenden des ETag spart Bandbreite:

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

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

Das ETag wird ohne das Feld cache berechnet, ein Cache-Hit und ein Cache-Miss derselben Vorschläge validieren also identisch.

Mehrere Indizes gleichzeitigCopy 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": "pre", "limit": 5 }'

{
	"query": "pre",
	"results": [
		{
			"index": "documentation",
			"suggestions": [
				{
					"text": "Preise",
					"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 nimmt 1–10 Slugs; jeder wird auf Zugriff geprüft und rate-limitiert, die Ergebnisse sind pro Index in der gesendeten Reihenfolge gruppiert. Ungültige Eingaben werden mit 422 vor jedem Engine-Aufruf abgelehnt:

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

Duplikate werden vor dem Fan-out entfernt: ["docs","docs"] ist ein Lookup, nicht zwei.

Presearch (leeres Suchfeld)Copy Anchor Link

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

Vorschläge vor dem ersten Tastendruck. Die REST-Route braucht einen Schlüssel mit search:read und ist pro Schlüssel limitiert; die Embed-Route nimmt das Embed-Session-Token (Body token oder Authorization: Bearer aac_sess_…) und ist pro Client-Adresse limitiert. Keine der beiden verbraucht Suchkontingent.

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 gibt die Herkunft an, in dieser Reihenfolge:

• continue — Eingrenzungs-, Verfeinerungs- oder Korrekturkanten aus dem Query-Graph für q.
• recent — eigene erfolgreiche Anfragen dieses Besuchers.
• trending — beliebte Anfragen der letzten 7 Tage, nur wenn mindestens 3 verschiedene Besucher sie eingegeben haben.

Anfragen, die nach personenbezogenen Daten oder Geheimnissen aussehen (E-Mails, Telefonnummern, lange Ziffernfolgen wie Bestell- oder Kartennummern, Links), sowie gehashte Anfragen werden nie zurückgegeben. Ungültige Parameter liefern 422 VALIDATION_ERROR.