API Reference

Base URL#

http://localhost:8010/api/v1

All endpoints are prefixed with /api/v1. Authentication is via Bearer token in the Authorization header.

Queries#

Natural Language Query#

Ask a natural language question about a connected data source. The LLM translates it to a structured query, executes it, and returns results with a suggested visualization.

Request Body:

{
  "question": "Which department has the highest citizen satisfaction?",
  "language": "en",
  "source_id": "demo-gov-analytics"
}

Response:

{
  "query_id": "q-a1b2c3",
  "question": "Which department has the highest citizen satisfaction?",
  "structured_query": {
    "columns": ["department", "citizen_satisfaction_pct"],
    "filters": {},
    "group_by": ["department"],
    "aggregation": "avg",
    "aggregation_column": "citizen_satisfaction_pct",
    "sort_by": "citizen_satisfaction_pct",
    "sort_order": "desc",
    "limit": 100
  },
  "results": [
    {"data": {"department": "Digital", "citizen_satisfaction_pct": 92.5}},
    {"data": {"department": "Education", "citizen_satisfaction_pct": 89.0}},
    {"data": {"department": "Health", "citizen_satisfaction_pct": 84.5}}
  ],
  "total_rows": 5,
  "suggested_chart": "bar",
  "summary": "The Digital department leads citizen satisfaction at 92.5%, followed by Education at 89.0%.",
  "executed_at": "2024-01-15T10:30:00Z"
}

Dashboards#

List Dashboards#

Returns all dashboards with their widget configurations.

Create Dashboard#

Create a new dashboard with widgets.

Request Body:

{
  "name": "Executive KPI Dashboard",
  "description": "Key performance indicators for government leadership",
  "widgets": [
    {
      "id": "w1",
      "type": "kpi",
      "title": "Total Budget (AED M)",
      "x": 0, "y": 0, "w": 3, "h": 2,
      "config": {"metric": "budget_aed_millions", "aggregation": "sum"}
    },
    {
      "id": "w2",
      "type": "chart",
      "title": "Satisfaction by Department",
      "x": 3, "y": 0, "w": 6, "h": 4,
      "config": {
        "chart_type": "bar",
        "x_axis": "department",
        "y_axis": "citizen_satisfaction_pct"
      }
    }
  ]
}

Get Dashboard#

Returns a specific dashboard with all widget definitions.

Reports#

Generate Report#

Generate an AI-powered analytical report from a connected data source.

Request Body:

{
  "title": "Q4 2024 Government Performance Review",
  "description": "Quarterly analysis of department performance",
  "source_id": "demo-gov-analytics",
  "focus_areas": ["budget utilization", "citizen satisfaction", "AI adoption"]
}

Response:

{
  "id": "rpt-a1b2c3",
  "title": "Q4 2024 Government Performance Review",
  "status": "completed",
  "sections": [
    {
      "title": "Budget Utilization Analysis",
      "content": "Overall budget utilization reached 94.2% in Q4...",
      "chart_type": "bar",
      "chart_data": [...]
    }
  ],
  "key_findings": [
    "Digital department leads AI adoption at 90%",
    "Citizen satisfaction improved across all departments in Q4"
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z"
}

List Reports#

Returns all generated reports with status and summary.

Get Report#

Returns full report details including all sections, charts, and key findings.

Data Sources#

List Sources#

Returns all connected data sources with their status and schema information.

Add Source#

Add a new data source.

Request Body:

{
  "name": "Ministry Budget Data",
  "type": "csv",
  "config": {"file_path": "/data/ministry_budgets.csv"}
}

Response:

{
  "id": "src-a1b2c3",
  "name": "Ministry Budget Data",
  "type": "csv",
  "status": "connected",
  "config": {"file_path": "/data/ministry_budgets.csv"},
  "row_count": 0,
  "columns": [],
  "created_at": "2024-01-15T10:30:00Z"
}

Health#

Health Check#

Returns service health status and version information.