AI Analysis API¶

The AI Analysis API allows you to programmatically trigger AI-powered process analyses, retrieve results, and manage analysis history.

Base Path: /ai-analysis

Required Permission: ai_analysis_data

Endpoints¶

Generate AI Analysis¶

Trigger a new AI analysis for one or more processes.

POST /api/generate

Request Body:

A JSON object with the analysis configuration.

{
  "processes": ["order-process", "payment-process"],
  "version_mode": "latest",
  "version_count": 1,
  "specific_versions": {},
  "duration": "1_month",
  "focus": "incidents",
  "detail_level": "standard",
  "include_bpmn_xml": true,
  "custom_guidelines": "Focus on root causes related to payment gateway integrations.",
  "additional_context": "We deployed a new payment provider last week.",
  "custom_metrics": "SLA for payment authorization is < 3 seconds.",
  "output_language": "en",
  "save_history": true
}

Key Parameters:

Parameter	Type	Required	Description
`processes`	array	Yes	List of process keys to analyze (max 5)
`version_mode`	string	Yes	Version selection: `latest`, `last_n`, or `specific`
`version_count`	integer	No	Number of versions to analyze (when `version_mode` is `last_n`)
`specific_versions`	object	No	Map of process keys to specific version numbers
`duration`	string	Yes	Time range: `1_week`, `1_month`, `3_months`, `6_months`, `1_year`
`focus`	string	Yes	Analysis focus: `incidents`, `performance`, `long_running`, `variables`, `patterns`, `general`
`detail_level`	string	Yes	Verbosity level: `executive`, `standard`, `detailed`
`include_bpmn_xml`	boolean	No	Include BPMN XML for deeper analysis (default: `false`)
`custom_guidelines`	string	No	Specific instructions to guide the AI
`additional_context`	string	No	Additional context about recent changes or issues
`custom_metrics`	string	No	Custom metrics or SLAs to consider
`output_language`	string	No	Output language code (default: `en`)
`save_history`	boolean	No	Save analysis to history (default: `true`)

Response: 200 OK

{
  "analysis": "<h1>Champa AI Process Analysis Report</h1><p>Executive Summary...</p>",
  "analysis_id": 123,
  "metadata": {
    "duration_ms": 25430,
    "estimated_tokens": 15200,
    "processes_analyzed": 2,
    "data_points": 1547
  }
}

Response Fields:

Field	Type	Description
`analysis`	string	AI-generated report formatted as HTML
`analysis_id`	integer	ID of saved report in history (if `save_history` = true)
`metadata`	object	Analysis metadata and performance metrics

Get Specific Analysis by ID¶

Retrieve a single, complete analysis report from history.

GET /api/history/<analysis_id>

Path Parameters:

Parameter	Type	Description
`analysis_id`	integer	The ID of the analysis

Response: 200 OK

{
  "id": 123,
  "process_config": ["order-process"],
  "focus": "incidents",
  "detail_level": "standard",
  "days_back": 30,
  "analysis_html": "<h1>Champa AI Process Analysis Report</h1>...",
  "created_at": "2025-10-28T11:00:00Z",
  "created_by": "john.doe@example.com",
  "metadata": {
    "duration_ms": 25430,
    "estimated_tokens": 15200
  }
}

Delete Analysis from History¶

Permanently delete an analysis report from the user's history.

DELETE /api/history/<analysis_id>

Path Parameters:

Parameter	Type	Description
`analysis_id`	integer	The ID of the analysis

Response: 200 OK

{
  "success": true,
  "message": "Analysis deleted successfully"
}

Export Analysis¶

Download a saved analysis report as a file.

GET /api/export/<analysis_id>/<format>

Path Parameters:

Parameter	Type	Description
`analysis_id`	integer	The ID of the analysis to export
`format`	string	The desired file format: `md` or `txt`

Response: 200 OK

The response will be a file download with the appropriate Content-Disposition and Content-Type headers.

Example Response Headers:

Content-Type: text/markdown; charset=utf-8
Content-Disposition: attachment; filename="analysis_123_2025-10-28.md"

Get Analysis Templates¶

Retrieve the list of pre-configured analysis templates.

GET /api/templates

Response: 200 OK

A JSON array of template objects.

[
  {
    "id": "incident_investigation",
    "name": "Incident Investigation",
    "description": "Deep-dive into recent failures and incidents",
    "focus": "incidents",
    "detail_level": "detailed",
    "duration": "1_week",
    "icon": "alert-triangle"
  },
  {
    "id": "performance_review",
    "name": "Performance Review",
    "description": "Analyze process execution times and bottlenecks",
    "focus": "performance",
    "detail_level": "standard",
    "duration": "1_month",
    "icon": "zap"
  },
  {
    "id": "pattern_discovery",
    "name": "Pattern Discovery",
    "description": "Identify common execution patterns and anomalies",
    "focus": "patterns",
    "detail_level": "standard",
    "duration": "3_months",
    "icon": "trending-up"
  }
]

Usage Examples¶

Generate Analysis with cURL¶

curl -X POST https://champa.example.com/ai-analysis/api/generate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "processes": ["order-process"],
    "version_mode": "latest",
    "duration": "1_month",
    "focus": "incidents",
    "detail_level": "standard",
    "save_history": true
  }'

Generate Analysis with Python¶

import requests

API_TOKEN = "your_api_token"
BASE_URL = "https://champa.example.com"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "processes": ["order-process", "payment-process"],
    "version_mode": "latest",
    "duration": "1_month",
    "focus": "incidents",
    "detail_level": "standard",
    "custom_guidelines": "Focus on payment gateway issues",
    "save_history": True
}

response = requests.post(
    f"{BASE_URL}/ai-analysis/api/generate",
    headers=headers,
    json=payload
)

result = response.json()
print(f"Analysis ID: {result['analysis_id']}")
print(f"Duration: {result['metadata']['duration_ms']}ms")

Get History with JavaScript¶

const API_TOKEN = 'your_api_token';
const BASE_URL = 'https://champa.example.com';

async function getAnalysisHistory(limit = 20) {
  const response = await fetch(
    `${BASE_URL}/ai-analysis/api/history?limit=${limit}`,
    {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`
      }
    }
  );

  const history = await response.json();
  return history;
}

Error Responses¶

400 Bad Request¶

Invalid request parameters:

{
  "error": "Invalid request",
  "message": "Maximum 5 processes can be analyzed at once",
  "field": "processes"
}

401 Unauthorized¶

{
  "error": "Authentication required",
  "message": "Valid API token or session required"
}

403 Forbidden¶

{
  "error": "Permission denied",
  "message": "ai_analysis_data permission required"
}

404 Not Found¶

{
  "error": "Analysis not found",
  "message": "Analysis ID 123 does not exist or you don't have access"
}

429 Too Many Requests¶

{
  "error": "Rate limit exceeded",
  "message": "Maximum 10 analyses per hour. Try again in 23 minutes.",
  "retry_after": 1380
}

Best Practices¶

Analysis Configuration¶

Start Small: Begin with single-process analyses before analyzing multiple processes together.
Choose Appropriate Duration:
For incident investigation: 1 week
For performance analysis: 1-3 months
For pattern discovery: 3-6 months

Use Custom Guidelines: Provide specific context to get more relevant insights:

{
  "custom_guidelines": "We recently migrated from REST to messaging. Focus on message correlation issues.",
  "additional_context": "Migration completed on 2025-10-15"
}

Performance Optimization¶

Include BPMN XML Sparingly: Only use include_bpmn_xml: true when you need deep structural analysis, as it significantly increases processing time.
Appropriate Detail Level:
executive: Quick overview for management (fastest)
standard: Balanced detail for operations (recommended)
detailed: Comprehensive analysis for troubleshooting (slowest)
Save to History: Always save important analyses for future reference and comparison.

Analysis Report Structure¶

Generated analyses typically include:

Executive Summary: High-level overview of findings
Key Metrics: Process performance statistics
Incident Analysis: Failure patterns and root causes (if applicable)
Performance Insights: Bottlenecks and optimization opportunities
Recommendations: Actionable suggestions for improvement

The HTML output is styled and can be directly embedded in web applications or exported to other formats.