Getting started

1. Getting Started

The full single-file contract for other applications is the API integration guide. This page is the short path to the first successful call.

1.1 Base URL

Production / staging (placeholder):

{baseUrl}/api

or

https://your-kroov-host/api

Local:

https://localhost:7003/api

WebApp (Vite): https://localhost:3007 — proxies /api → :7003.

Note: Many deployments are reachable only from a private network. Public Internet access is usually disabled unless federation or a public webhook base URL is intentionally configured.

OpenAI-compatible routes live under /v1 (not /api/v1):

{baseUrl}/v1/chat/completions

or https://your-kroov-host/v1/chat/completions.

Liveness probe (anonymous): GET /health → { "status": "healthy" }.

1.2 API Versioning

Current Version: v1 (implicit for /api/*; explicit OpenAI surface at /v1)

Future breaking changes may introduce /api/v2/. Until then, additive fields are preferred; clients should ignore unknown JSON properties.

1.3 Content Types

Request:

• application/json — JSON bodies (property names are camelCase)
• multipart/form-data — file uploads (images, documents, audio, KB documents, session files)

Response:

• application/json — standard responses
• text/event-stream — Server-Sent Events (chat agent loop, agent runs, sessions)
• WebSocket JSON frames — live realtime transcription

1.4 Auth at a glance

Audience	Scheme	Header / mechanism
EMR / backend apps calling AI	API Key	x-api-key: <key>
OpenAI SDK clients	API Key as Bearer	Authorization: Bearer <api-key> on /v1/*
SPA / admin / agents / automations	JWT	Authorization: Bearer <jwt>
Federated MCP callers (e.g. Eva)	Delegation	X-AINexus-Delegation: <token>
Pipedream webhooks	HMAC	x-pd-signature on POST /api/integration-events/...
MCP runtime proxy (internal)	Controller token	X-Mcp-Controller-Token

Important: Native AI endpoints under /api/ai/* accept API Key authentication only (AuthenticationSchemes = "ApiKey"). JWT works for admin/SPA controllers, not for /api/ai/query or /api/ai/chat.

1.5 Quick Start Checklist

1. Obtain an API key (or JWT for admin surfaces) from a platform administrator
2. Identify your project ID
3. Call GET /api/features to learn which optional capabilities this deployment exposes
4. Test in development first
5. Prefer providerId (specific configured instance) over bare provider type strings

First AI call (API key):

curl -X POST https://your-kroov-host/api/ai/query \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello, this is a test query",
    "projectId": 1
  }'

Expected response:

{
  "success": true,
  "content": "Hello! How can I assist you today?",
  "provider": "Azure",
  "providerId": 12,
  "executionDuration": "00:00:01.234",
  "requestId": 12345,
  "inputTokens": 10,
  "outputTokens": 15
}

Local admin login → JWT (Development with Authentication__EnableLocalLogin=true):

curl -s -X POST https://localhost:7003/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}'

1.6 Interactive API Documentation

Swagger UI (Development environment only):

{baseUrl}/swagger
https://localhost:7003/swagger

Configure ApiKey (x-api-key) and/or Bearer JWT in the Authorize dialog.

---