Skip to main content

​
POST /api/v1/ai/chat

Stream a conversation with the AI assistant. Uses the Vercel AI SDK to stream responses with tool calling support. Rate limited to 30 requests per 60 seconds.

​
Request Body

FieldTypeRequiredDescription
messagesarrayYesAI SDK message array (user/assistant/tool messages)
routestringNoCurrent page route for context injection (e.g., "/studio/decision-flows")
conversationIdstringNoExisting conversation ID to continue. Auto-created if omitted

​
Response

Returns a streaming UIMessageStreamResponse. The X-Conversation-Id header contains the conversation ID for follow-up messages.

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/ai/chat \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "messages": [{ "role": "user", "content": "What are my top performing offers?" }],
    "route": "/dashboards"
  }'

​
GET /api/v1/ai/conversations

List recent conversations for the tenant (up to 50, newest first). Requires session authentication.

​
POST /api/v1/ai/conversations

Create a new conversation.

​
Request Body

FieldTypeRequiredDescription
titlestringNoConversation title. Default: "New conversation"
Response: 201 Created

​
POST /api/v1/ai/analyze/

Run AI-powered analysis on tenant data. Supports three analysis types with automatic LLM/ML Worker routing based on data volume.

​
Path Parameters

ParameterValuesDescription
type"policies", "segments", "content"Type of analysis to perform

​
Request Body

FieldTypeRequiredDescription
schemaIdstringFor segmentsSchema to analyze
confirmedbooleanNoSet true to bypass confirmation for large datasets
preferredTierstringNoForce "llm" or "ml_worker" tier

​
Response (confirmation required)

When the dataset exceeds the LLM tier threshold, a confirmation prompt is returned: 
{
  "requiresConfirmation": true,
  "tier": "ml_worker",
  "warning": "Dataset has 50,000 rows. ML Worker recommended for accurate analysis.",
  "confirmationMeta": { "rowCount": 50000 }
}

​
Response (analysis complete)

{
  "results": {
    "segments": [
      { "name": "High Engagement", "size": 2400, "characteristics": ["frequent_buyer", "email_opener"] }
    ]
  },
  "source": "llm",
  "analysisType": "segments"
}

​
GET /api/v1/ai/recommendations

List AI-generated recommendations for the tenant.

​
Query Parameters

ParameterTypeDescription
typestringFilter by type: "policy", "rule", "segment", "content"
statusstringFilter by status: "new", "applied", "dismissed"

​
Response

{
  "recommendations": [
    {
      "id": "rec_001",
      "type": "policy",
      "title": "Add email frequency cap",
      "description": "High dismiss rates suggest customers are receiving too many emails",
      "confidence": "high",
      "source": "llm",
      "status": "new",
      "payload": { "ruleType": "frequency_cap", "config": { "maxPerWeek": 3 } }
    }
  ]
}

​
POST /api/v1/ai/recommendations//apply

Apply an AI recommendation by creating the corresponding entity (policy, rule, segment, or content item) in draft status. Requires admin role.

​
Response

{
  "entityId": "cp_001",
  "entityType": "policy"
}

​
POST /api/v1/ai/intelligence

Dispatch to intelligence backend tools. Used by the MCP server for programmatic access.

​
Request Body

FieldTypeRequiredDescription
toolstringYesTool name (see available tools below)
paramsobjectYesTool-specific parameters

​
Available Tools

ToolDescription
explainDecisionExplain why a specific decision was made for a customer
compareOfferEligibilityCompare which offers a customer qualifies for
listCustomerSuppressionsList contact policy suppressions for a customer
traceCustomerJourneyTrace a customer’s journey history
analyzeQualificationFunnelAnalyze qualification rule pass/fail rates
analyzeContactPolicySuppressionAnalyze contact policy suppression rates
analyzePolicyConflictsDetect policy conflicts and overlaps
analyzeOfferPerformanceAnalyze offer conversion and engagement metrics
simulateRuleChangeSimulate the impact of a rule change
simulateFrequencyCapChangeSimulate frequency cap adjustments
analyzeModelHealthCheck model performance and drift
explainModelScoringExplain how a model scores a customer
suggestModelImprovementsGet model improvement suggestions
detectModelDriftDetect feature or concept drift
runHealthCheckRun a system-wide health check

​
POST /api/v1/ai/parse-rule

Parse a natural language rule description into structured JSON using AI.

​
Request Body

FieldTypeRequiredDescription
textstringYesNatural language rule description

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/ai/parse-rule \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{ "text": "Only show credit card offers to customers with income above 50000 and credit score above 650" }'

​
Response

{
  "conditions": [
    { "field": "income", "operator": "greater_than", "value": 50000 },
    { "field": "credit_score", "operator": "greater_than", "value": 650 }
  ],
  "combinator": "AND",
  "confidence": 0.92
}

​
GET /api/v1/ai/ml-worker/status

Check ML Worker connectivity status.

​
Response

{
  "connected": true,
  "url": "https://ml-worker.internal:8080"
}

​
GET /api/v1/ai/analyzer-settings

Get current AI analyzer settings for the tenant (with defaults filled in).

​
PUT /api/v1/ai/analyzer-settings

Update AI analyzer settings. Requires admin role.

​
Request Body

Settings for each analyzer module (segmentation, policy, content) including thresholds, lookback windows, and model parameters.

​
Roles

EndpointAllowed Roles
POST /ai/chatadmin, editor, viewer
POST /ai/analyze/{type}admin, editor
GET /ai/recommendationsadmin, editor, viewer
POST /ai/recommendations/{id}/applyadmin
POST /ai/intelligenceany authenticated
POST /ai/parse-ruleadmin, editor
GET /ai/ml-worker/statusadmin, editor, viewer
GET /ai/analyzer-settingsadmin, editor, viewer
PUT /ai/analyzer-settingsadmin
See also: AI Assistant | AI Insights | AI Configuration