Status and discovery

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

None of these require an API key except /metrics, which needs a separate operations token.

StatusCopy Anchor Link

Interactive Scalar documentation is available at /api/docs on your API server. Select Search API v1 (/api/v1/openapi.json, the SDK contract) or Console & Auth API (/api/spec.json, session authentication). Opening the reference does not grant access to protected operations.

The public status document: engine, Redis and database reachability in one call, safe to expose on a status page.

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 is the AND of the engine and database checks; Redis is reported but does not fail the document, because the platform degrades to in-process rate limiting and caching without it. redis.enabled: false means no REDIS_URL is configured. Responses are cache-control: no-store and the whole check has a 1.5-second engine timeout, so a hung node returns engine.ok: false quickly instead of timing out the monitor.

HealthCopy Anchor Link

A terse engine probe, useful for load balancers.

curl -sS "$AAC_API/health"

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

When the engine is not configured or unreachable the status is 503 and the body says which:

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

error is not_configured when search has not been configured, and unavailable when the service cannot be reached.

CapabilitiesCopy Anchor Link

Feature discovery reports support for the API features on this deployment. Models and index settings can require additional configuration.

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

Available features are reported by GET /api/v1/capabilities. A supported feature can still require a configured model, index fields or deployment settings. Backend version and infrastructure details belong to platform administration.

OpenAPI documentCopy Anchor Link

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

The document the SDKs are generated from; pnpm sdk:generate regenerates both clients from it. Use it for typed clients in other languages, Postman collections or gateway configuration.

MetricsCopy Anchor Link

Operational counters for scraping. Disabled unless METRICS_TOKEN is set on the server, and never exposes tenant content — only totals.

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

A wrong or missing token is answered with 404 and { "error": { "code": "NOT_FOUND", "message": "Not found" } } — the endpoint does not advertise its existence.