AACSearch
API-Referenz

Suche

GET und POST /api/v1/indexes/{slug}/search — alle Abfrageparameter, der Response-Body und die zugehörigen Header.

GET  /api/v1/indexes/{slug}/search
POST /api/v1/indexes/{slug}/search

Beide Methoden führen dieselbe Abfrage aus: GET nimmt Query-Parameter, POST einen JSON-Body — praktischer für lange filter_by-Ausdrücke, Vektorabfragen und Text außerhalb von ASCII. Erfordert den Scope search:read und verbraucht eine Sucheinheit des Tarifkontingents.

Kurzes Beispiel

curl -sS -G "$AAC_API/indexes/documentation/search" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=preise tarife" \
  --data-urlencode "query_by=title,content" \
  --data-urlencode "query_by_weights=4,2" \
  --data-urlencode "filter_by=tags:=[billing]" \
  --data-urlencode "facet_by=tags" \
  --data-urlencode "sort_by=_text_match:desc,published_at:desc" \
  --data-urlencode "per_page=5"
curl -sS -X POST "$AAC_API/indexes/documentation/search" \
  -H "Authorization: Bearer $AAC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "preise tarife",
    "query_by": "title,content",
    "filter_by": "tags:=[billing]",
    "facet_by": "tags",
    "per_page": 5
  }'

Response

{
	"index": "documentation",
	"query": "preise tarife",
	"language": "de",
	"found": 2,
	"out_of": 137,
	"page": 1,
	"per_page": 5,
	"took_ms": 18,
	"engine_ms": 4,
	"hits": [
		{
			"id": "pricing",
			"score": 2711,
			"document": {
				"id": "pricing",
				"external_id": "pricing",
				"title": "Preise",
				"content": "Free umfasst 10.000 Suchen pro Monat. Pro kostet 29 USD im Monat …",
				"url": "https://example.com/pricing",
				"source_type": "api",
				"organization_id": "org_01h9",
				"tags": ["billing"],
				"indexed_at": 1761214364
			},
			"highlights": [
				{ "field": "title", "snippet": "<mark>Preise</mark>", "matchedTokens": ["preise"] },
				{
					"field": "content",
					"snippet": "… Pro kostet 29 USD im <mark>Monat</mark> …",
					"matchedTokens": ["monat"]
				}
			]
		}
	],
	"facets": [
		{
			"field": "tags",
			"values": [
				{ "value": "billing", "count": 2, "highlighted": "billing" },
				{ "value": "api", "count": 1 }
			]
		}
	],
	"request_id": "req_9a7c3d1e5f0b2a4c6d8e0f1a"
}
FeldBedeutung
languageAus q erkannte Sprache, dient als Stemmer-Hinweis
foundTreffer für diese Abfrage, nach Filtern
out_ofDurchsuchte Dokumente der Collection
took_msPlattformzeit inklusive Kontingent und Logging
engine_msVon Suchdienst gemeldete Zeit
hits[].scoreText-Match-Score; höher ist besser
hits[].highlightsAusschnitte mit von der Engine gesetzten <mark>-Tags
grouped_byNur bei group_by: { field, groups[] }

Leere Ergebnislisten sind eine 200 mit found: 0 und leerem hits-Array. Sie werden als Null-Ergebnis-Abfragen protokolliert.

Parameter

Alle Parameter sind optional, außer q bei POST (Standard: leerer String, den die Engine als „alles“ behandelt).

ParameterTypHinweis
qstring ≤ 1000Suchtext. Leer bedeutet „alles anzeigen“ (intern *)
profilestring ≤ 64Gespeichertes Suchprofil, dessen Werte als Vorgaben gelten
query_bystringKommagetrennte Felder, Standard title,content,tags
query_by_weightsstringEin Gewicht pro query_by-Feld, z. B. 4,2,1; Anzahl muss passen
filter_bystring ≤ 2000Filterausdruck; darf organization_id nicht referenzieren
sort_bystring ≤ 200field:asc,field2:desc; _text_match:desc ist erlaubt
facet_bystringKommagetrennte Facettenfelder
max_facet_valuesint 1–50Standard 10, durch die Installation begrenzt
facet_querystringtags: frontend — Facettensuche mit facet_query_num_typos (0–3)
pageintStandard 1, maximal 100 (SEARCH_MAX_DEEP_PAGE); ein größerer Wert wird mit 422 VALIDATION_ERROR abgelehnt, nicht gekappt. Für tiefere Scans offset verwenden
per_pageintStandard 10; wird auf das Installationslimit gekappt (SEARCH_MAX_PER_PAGE, Standard 250), nicht abgelehnt
offsetintAlternative zu page
limit_hitsintObergrenze der insgesamt betrachteten Treffer
num_typosint 0–3Standard 2
min_len_1typo / min_len_2typoint 1–20Wortlänge, ab der ein Tippfehler erlaubt ist
typo_tokens_threshold / drop_tokens_thresholdint 0–10Fallbacks für lange Abfragen
prefixbooleanStandard true; false deaktiviert Präfixsuche (semantische Suche erzwingt das)
prioritize_exact_matchbooleanExakte Tokens vor Tippfehler-Treffern bevorzugen
exhaustive_searchbooleanLatenz gegen Vollständigkeit tauschen
search_cutoff_msint 0–60000Engine-Abfrage nach diesem Budget abbrechen
group_by / group_limitstring / int 1–50Ein Feld, eine Ergebnisfgruppe pro Wert
highlight_fields, highlight_full_fieldsstringFelder für Ausschnitte
highlight_start_tag, highlight_end_tagstring ≤ 20<mark> durch eigene Tags ersetzen
snippet_thresholdint 1–500Länge des Ausschnitts um den Treffer
include_fields, exclude_fieldsstringProjektion des zurückgegebenen Dokuments
vector_querystringembedding:([0.1,0.2], k:10, alpha:0.6) für explizites kNN
semanticbooleanHybride Suche über das Auto-Embedding-Feld des Index
alphafloat 0–1Vektorgewicht bei semantic=true: 0 nur Keywords, 1 nur Vektor
aclstring[] ≤ 32Principals user:<id>, group:<id> oder role:<id> für Zugriffskontrolle pro Dokument. Nur wirksam bei einem Server-Schlüssel ohne allowedOrigins und einem Request ohne Origin-Header; sonst ignoriert, die Suche läuft anonym (nur öffentliche Dokumente)

Booleans akzeptieren true/false und 1/0. Ungültige Werte ergeben 422 VALIDATION_ERROR mit der Zod-Issue-Liste; gültige Werte oberhalb eines Engine-Limits werden gekappt.

{
	"error": {
		"code": "VALIDATION_ERROR",
		"message": "Request payload is invalid",
		"request_id": "req_3c7a1f5b9d2e4c6a8b0d2f4e",
		"details": {
			"issues": [
				{
					"code": "too_small",
					"path": ["num_typos"],
					"message": "Number must be greater than or equal to 0"
				}
			]
		}
	}
}

Semantische und hybride Suche

semantic=true schreibt die Anfrage für einen Index mit Auto-Embedding-Feld um: das Embedding-Feld wird an query_by angehängt, prefix wird auf false gezwungen (remote Embedder können nicht präfix-matchen) und eine vector_query mit k gleich der Seitengröße ergänzt. alpha bestimmt die Mischung.

curl -sS -G "$AAC_API/indexes/documentation/search" \
  -H "Authorization: Bearer $AAC_KEY" \
  --data-urlencode "q=was kostet der pro tarif" \
  --data-urlencode "semantic=true" \
  --data-urlencode "alpha=0.6" \
  --data-urlencode "per_page=3"

Hat der Index kein Auto-Embedding-Feld, scheitert die Anfrage mit 400 INVALID_QUERY und der Meldung Index "…" has no auto-embedding field. semantic benötigt außerdem die Tariffunktion hybridSearch, ein explizites vector_query die Funktion vectorSearch. Siehe Semantische Suche.

Gespeicherte Profile und A/B

profile=<slug> übernimmt query_by, Gewichte, Facetten, Sortierung und Paging eines gespeicherten Profils als Vorgaben; explizit übergebene Parameter gewinnen. Ein unbekannter Slug ist 404 PROFILE_NOT_FOUND. Ist settings.abTest am Index aktiv und kein profile gesetzt, wählt die Plattform deterministisch anhand von Schlüssel und Index — derselbe Schlüssel landet immer im selben Bucket, und genau das macht den Vergleich in /analytics/experiments aussagekräftig. Siehe A/B-Experimente.

Header der Antwort

x-aac-quota-limit: 500000
x-aac-quota-remaining: 499996
x-aac-index: documentation
x-aac-profile: default
x-aac-charged-cents: 0
x-ratelimit-limit: 600
x-ratelimit-remaining: 412
x-ratelimit-reset: 1761214424

x-aac-charged-cents ist nur dann ungleich null, wenn das Tarifkontingent erschöpft ist und das Wallet den Block bezahlt hat.

Verwandte Index-Endpunkte

Sie gehören zur selben Oberfläche und nutzen dasselbe Zugriffsmodell:

EndpunktScopeZweck
GET /indexes/{slug}/statssearch:readDokumentzahl, Felder, Query-Volumen und Durchschnittslatenz der letzten 24 h
POST /indexes/{slug}/eventsanalytics:writeKlick oder Conversion erfassen
GET /indexes/{slug}/widget-configsearch:readSuchprofile des Index
POST /indexes/multi_searchsearch:readFöderierte Suche: die Indizes stehen im Body
GET/PUT /indexes/{slug}/synonyms; DELETE /indexes/{slug}/synonyms/{id}settings:writeEin- und mehrseitige Synonyme
GET/PUT /indexes/{slug}/curations; DELETE /indexes/{slug}/curations/{id}settings:writeAnfragen anheften, verbergen, umschreiben
POST /indexes/{slug}/reindexsettings:writeRebuild ohne Ausfall
curl -sS "$AAC_API/indexes/documentation/stats" \
  -H "Authorization: Bearer $AAC_KEY"
{
	"index": {
		"slug": "documentation",
		"collection": "aac_org_01h9_documentation",
		"documents": 137,
		"fields": [
			{
				"name": "title",
				"type": "string",
				"facet": false,
				"optional": true,
				"index": true,
				"sort": false,
				"infix": false
			},
			{
				"name": "tags",
				"type": "string[]",
				"facet": true,
				"optional": true,
				"index": true,
				"sort": false,
				"infix": false
			}
		],
		"created_at": "2026-10-01T08:20:11.000Z"
	},
	"queries_24h": 1841,
	"avg_latency_24h_ms": 17.42,
	"usage": {
		"plan": "pro",
		"period": "2026-10",
		"resetsAt": "2026-11-01T00:00:00.000Z",
		"searches": { "used": 4120, "limit": 500000 },
		"documents": { "used": 137, "limit": 50000 }
	},
	"request_id": "req_6e1b8d0a2c4f6a8d0b2e4c6a"
}

Authentifizierung

Bearer-Schlüssel mit dem Prefix aac_live_, Scope-Modell, Indexbindung, CORS und die Header jeder Antwort.

Projekt-Einkaufsberater

Deterministische Material- und SKU-Auswahl anhand einer veröffentlichten Fachvorlage.

On this page

Kurzes BeispielResponseParameterSemantische und hybride SucheGespeicherte Profile und A/BHeader der AntwortVerwandte Index-Endpunkte