Status und Discovery

GET /api/v1/status
GET /api/v1/health
GET /api/v1/capabilities
GET /api/v1/openapi.json
GET /api/v1/metrics

Keiner davon braucht einen API-Schlüssel außer /metrics, das ein separates Betriebs-Token verlangt.

StatusCopy Anchor Link

Die interaktive Scalar-Dokumentation ist unter /api/docs auf Ihrem API-Server verfügbar. Wählen Sie Search API v1 (/api/v1/openapi.json, der SDK-Vertrag) oder Console & Auth API (/api/spec.json, Sitzungsauthentifizierung). Die öffentliche Dokumentation gewährt keinen Zugriff auf geschützte Operationen.

Das öffentliche Statusdokument: Erreichbarkeit von Engine, Redis und Datenbank in einem Aufruf, geeignet für eine Statusseite.

curl -sS "$AAC_API/status"

{
	"ok": true,
	"engine": { "ok": true },
	"redis": { "enabled": true, "ok": true, "status": "ready" },
	"database": { "ok": true },
	"latency_ms": 14,
	"time": "2026-10-23T10:41:02.000Z",
	"request_id": "req_2c4e6a8b0d2f4a6c8e0b2d4f"
}

ok ist das logische UND aus Engine- und Datenbankprüfung; Redis wird gemeldet, entscheidet aber nicht, weil die Plattform ohne Redis auf prozesslokal Rate-Limits und Caches zurückfällt. redis.enabled: false heißt, dass kein REDIS_URL gesetzt ist. Antworten laufen mit cache-control: no-store, die Engine-Prüfung hat 1,5 Sekunden Timeout — ein hängender Knoten liefert schnell engine.ok: false statt den Monitor in einen Timeout zu schicken.

HealthCopy Anchor Link

Kurze Engine-Prüfung für Load Balancer.

curl -sS "$AAC_API/health"

{
	"ok": true,
	"request_id": "req_5e7a9c1b3d5f7a9c1e3b5d7a"
}

Ist die Engine nicht konfiguriert oder nicht erreichbar, kommt 503 mit der Ursache im Body:

{
	"ok": false,
	"error": "unavailable"
}

error ist not_configured, wenn die Suche nicht konfiguriert ist, und unavailable, wenn der Dienst nicht erreichbar ist.

CapabilitiesCopy Anchor Link

Dieser Endpunkt meldet die unterstützten API-Funktionen dieser Installation. Modelle und Indexeinstellungen können zusätzliche Konfiguration erfordern.

curl -sS "$AAC_API/capabilities"

{
	"features": {
		"autoEmbedding": true,
		"conversation": true,
		"nlSearch": true,
		"analytics": true,
		"voiceQuery": true,
		"imageSearch": true,
		"joins": true,
		"unionSearch": true,
		"scopedKeys": true
	},
	"endpoints": {
		"assistant": "/api/v1/indexes/{index}/assistant",
		"assistant_stream": "/api/v1/indexes/{index}/assistant/stream",
		"nl_search": "/api/v1/indexes/{index}/nl-search",
		"voice": "/api/v1/indexes/{index}/voice",
		"scoped_key": "/api/v1/indexes/{index}/scoped-key",
		"suggest": "/api/v1/indexes/{index}/suggest"
	},
	"infrastructure": { "cache": { "enabled": true, "ok": true, "status": "ready" } }
}

GET /api/v1/capabilities nennt die unterstützten Funktionen. Eine Funktion kann zusätzlich ein konfiguriertes Modell, Indexfelder oder Betriebseinstellungen benötigen. Backend-Version und Infrastrukturdetails gehören zur Plattformadministration.

OpenAPI-DokumentCopy Anchor Link

curl -sS "$AAC_API/openapi.json" -o aacsearch-openapi.json

Aus diesem Dokument werden die SDKs generiert; pnpm sdk:generate baut beide Clients neu. Es eignet sich auch für typisierte Clients in anderen Sprachen, Postman-Collections oder Gateway-Konfiguration.

MetrikenCopy Anchor Link

Betriebszähler zum Scrapen. Deaktiviert, solange kein METRICS_TOKEN gesetzt ist, und niemals mit Mandanteninhalten — nur Summen.

curl -sS "$AAC_API/metrics" -H "x-metrics-token: $METRICS_TOKEN"

{
	"generated_at": "2026-10-23T10:41:02.000Z",
	"gauges": {
		"indexes": 42,
		"documents": 184203,
		"connectors": 17,
		"dead_letters_open": 3,
		"wallet_liability_cents": 128400
	},
	"counters_today": { "searches": 91204, "events": 1877 },
	"latency": { "avg_search_ms": 18.6 }
}

Ein falsches oder fehlendes Token wird mit 404 und { "error": { "code": "NOT_FOUND", "message": "Not found" } } beantwortet — der Endpunkt verrät seine Existenz nicht.