AI API

The AI API provides AI-powered features including conversational assistance, content suggestions, and a knowledge base. AI features require a configured provider (OpenAI, Gemini, or Claude) in Settings > AI Configuration. All endpoints require JWT authentication.

AI Query

POST /api/ai/query

Send a message to the AI assistant. Supports multi-turn conversations.

Request Body

{
  "message": "How can I improve my onboarding flow completion rate?",
  "conversationId": "conv_abc123",
  "context": { "currentFlowId": "flow_xyz" }
}

Field	Type	Required	Description
message	string	Yes	The user's message
conversationId	uuid	No	Continue an existing conversation (omit to start new)
context	object	No	Additional context for the AI

Response

{
  "data": {
    "conversationId": "conv_abc123",
    "response": "Here are some strategies to improve completion rates...",
    "messages": [
      {
        "role": "user",
        "content": "How can I improve...",
        "timestamp": "2025-01-20T10:00:00Z"
      },
      {
        "role": "assistant",
        "content": "Here are some strategies...",
        "timestamp": "2025-01-20T10:00:01Z"
      }
    ]
  }
}

Suggest Flow

POST /api/ai/suggest-flow

Get AI-generated flow recommendations based on a page and user segment.

Request Body

{
  "pageUrl": "https://app.example.com/settings",
  "userSegment": "new_users",
  "goal": "Help users configure notifications"
}

Response

{
  "data": {
    "suggestion": "...",
    "steps": [...]
  }
}

Suggest Audience

POST /api/ai/suggest-audience

Generate audience targeting rules from a natural language description.

Request Body

{
  "description": "Enterprise users who signed up in the last 30 days and haven't completed onboarding"
}

The description field accepts 1-500 characters.

Generate Content

POST /api/ai/generate-content

Generates a draft content item from a natural-language description. The response contains both the raw aiData payload (used to commit the item) and a renderable preview. No content is persisted until you call Commit Content.

Request Body

{
  "type": "tooltip",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Highlight the new Reports button in the top nav for first-time users."
}

Field	Type	Required	Description
type	string	Yes	One of flow, tooltip, beacon, survey, announcement, journey, task-list
siteId	uuid	Yes	Site the generated content should belong to
description	string	Yes	1–2000 characters. Plain-language description of what to generate

Response

{
  "data": {
    "aiData": { "...": "..." },
    "preview": { "...": "..." },
    "tokensUsed": 1247
  }
}

tokensUsed is debited from the tenant's AI token balance immediately. Generation fails with INSUFFICIENT_AI_TOKENS if the balance is zero.

Commit Content

POST /api/ai/commit-content

Persists a previously generated draft. Pass back the aiData payload returned by /ai/generate-content. The endpoint creates the parent record and any child records (e.g., flow steps, survey questions) atomically.

Request Body

{
  "type": "tooltip",
  "siteId": "550e8400-e29b-41d4-a716-446655440000",
  "aiData": { "...": "..." }
}

Response

{
  "data": {
    "parentId": "ct_abc123",
    "parentType": "tooltip",
    "createdSubItemIds": {
      "steps": ["st_111", "st_222"]
    }
  }
}

createdSubItemIds is present only for content types that have child records (flows, surveys, journeys, task lists).

Knowledge Base

List Articles

GET /api/ai/knowledge-base

Query Parameters

Parameter	Type	Default	Description
page	string	"1"	Page number
limit	string	"20"	Items per page
search	string	—	Full-text search
category	string	—	Filter by category

Response

{
  "data": [
    {
      "id": "kb_abc",
      "title": "Getting Started Guide",
      "content": "Welcome to...",
      "metadata": {},
      "tenantId": "t_789",
      "createdAt": "2025-01-10T09:00:00Z",
      "updatedAt": "2025-01-10T09:00:00Z"
    }
  ],
  "meta": { "total": 15, "page": 1, "limit": 20, "totalPages": 1 }
}

Create Article

POST /api/ai/knowledge-base

Request Body

{
  "title": "Getting Started Guide",
  "content": "Welcome to the platform...",
  "category": "onboarding",
  "tags": ["getting-started", "basics"]
}

Field	Type	Required	Description
title	string	Yes	Article title
content	string	Yes	Article body (supports markdown)
category	string	No	Category for organization
tags	string[]	No	Tags for search and filtering

Get Article

GET /api/ai/knowledge-base/:id

Update Article

PATCH /api/ai/knowledge-base/:id

All fields are optional for updates.

Delete Article

DELETE /api/ai/knowledge-base/:id

List Conversations

GET /api/ai/conversations

Returns all AI conversations for the current tenant.

Response

{
  "data": [
    {
      "id": "conv_abc123",
      "tenantId": "t_789",
      "messages": [...],
      "createdAt": "2025-01-20T10:00:00Z",
      "updatedAt": "2025-01-20T10:05:00Z"
    }
  ],
  "meta": { "total": 5, "page": 1, "limit": 20, "totalPages": 1 }
}

AI Configuration

Get Configuration

GET /api/ai-config

Response

{
  "data": {
    "id": "aic_abc",
    "tenantId": "t_789",
    "provider": "OPENAI",
    "maskedKey": "sk-...abc1",
    "isEnabled": true,
    "lastVerifiedAt": "2025-01-15T12:00:00Z",
    "createdAt": "2025-01-10T00:00:00Z",
    "updatedAt": "2025-01-15T12:00:00Z"
  }
}

Returns null if no AI provider has been configured.

Save Configuration

POST /api/ai-config

Request Body

{
  "provider": "OPENAI",
  "apiKey": "sk-your-api-key"
}

Provider	Value
OpenAI	OPENAI
Google Gemini	GEMINI
Anthropic Claude	CLAUDE

Toggle AI Features

POST /api/ai-config/toggle

Request Body

{
  "enabled": false
}

Disabling AI features stops all AI-powered functionality (suggestions, knowledge base queries) without removing the provider configuration.