Статус и обнаружение

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

Ни один из этих эндпоинтов не требует API-ключа, кроме /metrics, которому нужен отдельный операционный токен.

СтатусCopy Anchor Link

Интерактивная документация Scalar доступна на /api/docs вашего API-сервера. Переключатель выбирает Search API v1 (/api/v1/openapi.json, контракт SDK) или Console & Auth API (/api/spec.json, авторизация сессией). Открытие документации не даёт доступа к защищённым операциям.

Публичный документ состояния: доступность движка, Redis и базы в одном вызове, его безопасно показывать на status-странице.

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 — это логическое И проверок движка и базы; Redis показывается, но не влияет на итог, потому что без него платформа переходит на локальные лимиты и кеш. redis.enabled: false означает, что REDIS_URL не задан. Ответы идут с cache-control: no-store, а проверка движка ограничена 1,5 секунды — зависший узел быстро вернёт engine.ok: false вместо таймаута монитора.

HealthCopy Anchor Link

Короткая проверка движка, удобная для балансировщика.

curl -sS "$AAC_API/health"

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

Если движок не настроен или недоступен, статус 503 и тело говорит, что именно:

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

error равен not_configured, если поиск не настроен, и unavailable, если сервис недоступен.

ВозможностиCopy Anchor Link

Этот эндпоинт сообщает о поддержке функций API на текущем развёртывании. Модели и настройки индекса могут требовать дополнительной конфигурации.

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. Поддерживаемой функции могут дополнительно требоваться модель, поля индекса или настройки развёртывания. Версия движка и инфраструктурные сведения относятся к администрированию платформы.

Документ OpenAPICopy Anchor Link

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

Из этого документа генерируются SDK; pnpm sdk:generate пересобирает оба клиента. Он же пригодится для типизированных клиентов на других языках, коллекций Postman и настройки шлюзов.

МетрикиCopy Anchor Link

Операционные счётчики для скрейпинга. Эндпоинт отключён, пока на сервере не задан METRICS_TOKEN, и никогда не раскрывает содержимое тенантов — только цифры.

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

На неверный или отсутствующий токен возвращается 404 и { "error": { "code": "NOT_FOUND", "message": "Not found" } } — эндпоинт не сообщает о своём существовании.