AI Copilot

Endpoints for the AI Copilot chat interface, AI-powered description generation, and token usage monitoring.

Feature Gate

All copilot endpoints require the ai.copilot feature to be enabled for the tenant.

Base Paths

/ai          — Chat and description generation
/ai-logs     — AI log and usage tracking (superadmin)

Authentication

All endpoints require an authenticated user session. AI log endpoints are restricted to superadmins.

---

Chat

Chat with Copilot

POST /ai/chat

Send a message to the AI Copilot. By default, the Copilot uses MCP tools (search, catalog, lineage, quality) to answer questions. Set use_tools to false for RAG-only mode.

Headers

Header	Required	Description
X-Instance-Id	No	Scope the request to a specific tenant instance

Request Body

{
  "messages": [
    { "role": "user", "content": "Which tables contain customer PII?" }
  ],
  "use_tools": true,
  "page_context": "catalog",
  "locale": "en"
}

Field	Type	Default	Description
messages	array	—	Conversation history (role + content pairs)
use_tools	boolean	true	Enable MCP tool-based agent loop
page_context	string	null	Current UI page for contextual responses
locale	string	"en"	Response language

Response 200 OK

{
  "response": "I found 3 tables containing customer PII...",
  "sources": [
    { "product_id": "...", "product_name": "customer_profiles", "relevance": 0.95 }
  ]
}

---

Description Generation

Generate Description

POST /ai/generate-description

Generate an AI-powered description for a data product or field based on its metadata.

Request Body

{
  "asset_type": "table",
  "asset_name": "revenue_transactions",
  "context": {
    "columns": ["id", "customer_id", "amount", "currency", "created_at"],
    "tags": ["finance", "revenue"],
    "product_type": "Table",
    "environment": "production",
    "lineage": {
      "upstream": ["raw_transactions"],
      "downstream": ["revenue_dashboard"]
    }
  }
}

Field	Type	Required	Description
asset_type	string	Yes	table, field, dashboard, etc.
asset_name	string	Yes	Name of the asset
context	object	Yes	Rich metadata context for generation

Response 200 OK

{
  "description": "Contains processed revenue transactions with customer attribution..."
}

---

AI Logs (Superadmin)

List AI Logs

GET /ai-logs

Fetch paginated AI interaction logs. Superadmin only.

Query Parameters

Parameter	Type	Default	Description
skip	int	0	Pagination offset
limit	int	50	Page size

Response 200 OK

{
  "items": [
    {
      "id": "...",
      "feature": "chat",
      "model": "claude-sonnet-4-20250514",
      "prompt_tokens": 1200,
      "completion_tokens": 450,
      "created_at": "2026-02-27T16:00:00Z"
    }
  ],
  "total": 142
}

---

Get AI Usage Summary

GET /ai-logs/usage

Aggregated token usage summary grouped by date, model, and feature. Superadmin only.

Query Parameters

Parameter	Type	Default	Description
days	int	30	Number of days to aggregate

Response 200 OK

[
  {
    "date": "2026-02-27",
    "model": "claude-sonnet-4-20250514",
    "feature": "chat",
    "total_prompt_tokens": 45000,
    "total_completion_tokens": 12000,
    "request_count": 85
  }
]

Related

• LLM Configuration — Configure AI provider credentials
• AI Copilot User Guide — End-user documentation