Skip to main content

AI API

AI-powered assistance endpoints for Copilot chat, description generation, prompt testing, and anomaly explanation.

All paths below are served under /api/v1.0.

Endpoints Overview​

MethodEndpointDescription
POST/ai/chatChat with the AI Copilot
POST/ai/chat/streamStream Copilot planner progress and final response
POST/ai/generate-descriptionGenerate product or field description
POST/ai/test-promptTest a product prompt through the governed AI path
POST/alerts/{id}/explainGenerate anomaly explanation
POST/catalog/products/{id}/generate-change-logGenerate AI product change log entry

Chat with Copilot​

POST /ai/chat

By default, Copilot uses authorized platform tools for catalog search, product lookup, lineage, and quality context. Set use_tools to false for governed non-tool chat.

{
  "messages": [
    { "role": "user", "content": "Which products contain customer PII?" }
  ],
  "use_tools": true,
  "page_context": {
    "space_slug": "finance",
    "page_path": "/catalog"
  },
  "locale": "en"
}

Response​

{
  "response": "I found 3 products that match...",
  "sources": [
    { "product_id": "uuid", "product_name": "Customer Profiles", "relevance": 0.94 }
  ]
}

Stream Copilot​

POST /ai/chat/stream

Accepts the same request shape as /ai/chat and returns server-sent events with planner progress followed by a final_response event.

Generate Product or Field Description​

POST /ai/generate-description

Generates an AI-powered description for a data product or field. For catalog-backed generation, pass product_id or field_id; Qarion loads the permitted metadata context from the catalog.

Request Body​

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field-level generation uses the same endpoint:

{
  "field_id": "7c3d9b10-f1f8-4388-9d47-9f1f37c2ed8a"
}

Manual context is also supported:

{
  "asset_type": "table",
  "asset_name": "customer_events",
  "context": {
    "columns": ["user_id", "event_type", "timestamp", "properties"],
    "tags": ["analytics", "events"]
  }
}

Response​

{
  "description": "Captures customer interaction events from web and mobile applications..."
}

Test Product Prompt​

POST /ai/test-prompt

Runs a product prompt through the governed AI path. The caller must have edit access to the product.

{
  "product_id": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    { "role": "system", "content": "Summarize the product for a steward." },
    { "role": "user", "content": "Draft a concise description." }
  ]
}

Response​

{
  "response": "This product contains...",
  "ai_log_id": "uuid"
}

Explain Anomaly Alert​

POST /alerts/{id}/explain

Generates an AI-powered root-cause hypothesis for an anomaly or trend alert. The service gathers context signals — sync events, upstream anomalies, quality check failures, and schema drift — then calls the LLM to produce an explanation.

Results are cached in the alert's metadata. Subsequent calls return the cached explanation without re-invoking the LLM.

Path Parameters​

ParameterTypeDescription
idUUIDAlert ID (must be anomaly or trend type)

Response​

{
  "explanation": "The anomaly appears to be caused by a failed sync event on the upstream orders connector at 14:32 UTC, which resulted in a partial data load missing approximately 40% of expected records.",
  "confidence": "high",
  "contributing_factors": [
    "Upstream connector 'orders_pg' sync failed at 14:32 UTC",
    "Quality check 'row_count_threshold' on orders_daily failed 30 minutes before the alert",
    "No schema changes detected in the analysis window"
  ]
}

Generate AI Change Log​

POST /catalog/products/{product_id}/generate-change-log

Generates an Annex IV-aligned markdown change log entry for an AI product. Qarion gathers product snapshots, audit logs, version milestones, and training run data. Pass existing change log content to reduce duplicate entries.

{
  "existing_change_log": "## 2026-05-01\nInitial model registration."
}

Response​

{
  "change_log_entry": "## 2026-06-01\n- Updated training run evidence..."
}