> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# KPI Dashboard API

> Manage and retrieve Key Performance Indicators for dealership operations

## Overview

The KPI Dashboard API provides comprehensive metrics tracking and visualization for your automotive dealership operations. Monitor sales performance, inventory metrics, customer satisfaction, and create custom KPIs tailored to your business needs.

## Endpoints

### Get All KPIs

<ParamField path="GET" type="endpoint">
  /kpis
</ParamField>

Retrieve all KPIs configured for the authenticated user, including both built-in and custom KPIs.

**Response:**

```json theme={null}
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "avg_days_to_sell",
    "title": "Average Days to Sell",
    "description": "Average number of days from listing to sale",
    "kpiType": "BUILTIN",
    "dataType": "DURATION",
    "value": 28.5,
    "trend": "down",
    "trendPercentage": -12.3,
    "icon": "calendar-days",
    "color": "#282F75",
    "displayOrder": 1,
    "isVisible": true,
    "chartType": "LINE",
    "chartEnabled": true,
    "chartConfig": {
      "timeRange": "30d",
      "showAverage": true
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]
```

***

### Get Visible KPIs Only

<ParamField path="GET" type="endpoint">
  /kpis/visible
</ParamField>

Retrieve only KPIs marked as visible for dashboard display.

**Response:**

Array of KPI objects with `isVisible: true`.

***

### Get KPI by ID

<ParamField path="GET" type="endpoint">
  /kpis/{id}
</ParamField>

Retrieve detailed information about a specific KPI.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "gross_profit_margin",
  "title": "Gross Profit Margin",
  "description": "Percentage of revenue remaining after cost of goods sold",
  "formula": "(Revenue - COGS) / Revenue * 100",
  "kpiType": "BUILTIN",
  "dataType": "PERCENTAGE",
  "value": 18.5,
  "trend": "up",
  "trendPercentage": 5.2,
  "icon": "chart-line",
  "color": "#4360B1",
  "displayOrder": 3,
  "isVisible": true,
  "chartType": "AREA",
  "chartEnabled": true,
  "chartConfig": {
    "timeRange": "90d",
    "showAverage": true,
    "showTrendline": true
  }
}
```

***

### Create Custom KPI

<ParamField path="POST" type="endpoint">
  /kpis
</ParamField>

Create a new custom KPI with your own calculation logic.

**Request Body:**

```json theme={null}
{
  "key": "customer_referral_rate",
  "title": "Customer Referral Rate",
  "description": "Percentage of customers who refer others",
  "formula": "Referrals / Total Customers * 100",
  "kpiType": "CUSTOM",
  "dataType": "PERCENTAGE",
  "icon": "users",
  "color": "#28a745",
  "displayOrder": 10,
  "isVisible": true,
  "aggregation": "average",
  "targetModel": "Customer",
  "targetField": "referralCount"
}
```

<ParamField body="key" type="string" required>
  Unique identifier key (lowercase, underscores)
</ParamField>

<ParamField body="title" type="string" required>
  Display title for the KPI
</ParamField>

<ParamField body="description" type="string">
  Detailed description of what this KPI measures
</ParamField>

<ParamField body="formula" type="string">
  Formula or calculation logic
</ParamField>

<ParamField body="kpiType" type="enum" required>
  Type: `BUILTIN`, `CUSTOM`
</ParamField>

<ParamField body="dataType" type="enum" required>
  Data type: `NUMBER`, `CURRENCY`, `PERCENTAGE`, `DURATION`, `TEXT`
</ParamField>

<ParamField body="icon" type="string">
  Icon identifier (FontAwesome icon name)
</ParamField>

<ParamField body="color" type="string">
  Hex color code for visualization
</ParamField>

<ParamField body="displayOrder" type="number">
  Sort order for dashboard display
</ParamField>

<ParamField body="isVisible" type="boolean">
  Whether KPI is visible on dashboard (default: true)
</ParamField>

<ParamField body="aggregation" type="string">
  Aggregation method: `sum`, `average`, `count`, `min`, `max`
</ParamField>

<ParamField body="targetModel" type="string">
  Database model to aggregate from
</ParamField>

<ParamField body="targetField" type="string">
  Field to aggregate
</ParamField>

**Response:**

```json theme={null}
{
  "id": "new_kpi_uuid",
  "key": "customer_referral_rate",
  "title": "Customer Referral Rate",
  "kpiType": "CUSTOM",
  "createdAt": "2024-01-17T09:15:00Z"
}
```

***

### Update KPI

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}
</ParamField>

Update an existing KPI's configuration. Built-in KPIs can only update display settings, not calculation logic.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "title": "Updated Title",
  "isVisible": false,
  "displayOrder": 5,
  "color": "#ff6b6b"
}
```

All fields are optional. Only provided fields will be updated.

***

### Delete KPI

<ParamField path="DELETE" type="endpoint">
  /kpis/{id}
</ParamField>

Delete a custom KPI. Built-in KPIs cannot be deleted.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "message": "Custom KPI deleted successfully"
}
```

<Warning>
  Only custom KPIs can be deleted. Attempting to delete a built-in KPI will return a 400 error.
</Warning>

***

### Reorder KPIs

<ParamField path="PUT" type="endpoint">
  /kpis/reorder
</ParamField>

Update display order for multiple KPIs at once.

**Request Body:**

```json theme={null}
{
  "orders": [
    { "id": "kpi_uuid_1", "displayOrder": 1 },
    { "id": "kpi_uuid_2", "displayOrder": 2 },
    { "id": "kpi_uuid_3", "displayOrder": 3 }
  ]
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "message": "KPIs reordered successfully"
}
```

***

### Toggle KPI Visibility

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}/toggle
</ParamField>

Toggle visibility of a KPI on the dashboard.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Response:**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isVisible": false,
  "message": "KPI visibility toggled"
}
```

***

### Reset to Default KPIs

<ParamField path="POST" type="endpoint">
  /kpis/reset
</ParamField>

Reset all KPIs to the default built-in configuration. This will:

* Restore all built-in KPIs to default settings
* Remove all custom KPIs
* Reset display order and visibility

**Response:**

```json theme={null}
{
  "success": true,
  "message": "KPIs reset to defaults successfully",
  "kpisCount": 8
}
```

<Warning>
  This action cannot be undone. All custom KPIs and configuration changes will be permanently lost.
</Warning>

***

### Update KPI Chart Configuration

<ParamField path="PATCH" type="endpoint">
  /kpis/{id}/chart
</ParamField>

Configure chart visualization settings for a KPI.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "chartType": "BAR",
  "chartEnabled": true,
  "chartConfig": {
    "timeRange": "30d",
    "showAverage": true,
    "showTrendline": false,
    "colors": ["#282F75", "#4360B1"]
  }
}
```

<ParamField body="chartType" type="enum">
  Chart type: `NONE`, `DONUT`, `BAR`, `LINE`, `AREA`, `RADIAL`
</ParamField>

<ParamField body="chartEnabled" type="boolean">
  Enable/disable chart display
</ParamField>

<ParamField body="chartConfig" type="object">
  Chart-specific configuration options
</ParamField>

***

### Get KPI Chart Data

<ParamField path="GET" type="endpoint">
  /kpis/{id}/chart-data
</ParamField>

Retrieve historical time-series data for KPI chart visualization.

**Path Parameters:**

<ParamField path="id" type="string" required>
  KPI UUID
</ParamField>

**Query Parameters:**

<ParamField query="timeRange" type="enum">
  Time range: `7d`, `30d`, `90d` (default: 30d)
</ParamField>

**Response:**

```json theme={null}
{
  "kpiId": "550e8400-e29b-41d4-a716-446655440000",
  "timeRange": "30d",
  "dataPoints": [
    {
      "date": "2024-01-01",
      "value": 25.5,
      "label": "Jan 1"
    },
    {
      "date": "2024-01-02",
      "value": 27.2,
      "label": "Jan 2"
    }
  ],
  "statistics": {
    "min": 22.1,
    "max": 32.8,
    "average": 27.3,
    "trend": "up"
  }
}
```

***

## Built-in KPIs

Steer AI provides the following built-in KPIs out of the box:

| Key                           | Title                    | Data Type  | Description                     |
| ----------------------------- | ------------------------ | ---------- | ------------------------------- |
| `avg_days_to_sell`            | Average Days to Sell     | DURATION   | Time from listing to sale       |
| `avg_selling_price`           | Average Selling Price    | CURRENCY   | Mean vehicle sale price         |
| `gross_profit_margin`         | Gross Profit Margin      | PERCENTAGE | Revenue minus COGS percentage   |
| `avg_age_of_inventory`        | Average Age of Inventory | DURATION   | Days vehicles stay in inventory |
| `inventory_turnover_ratio`    | Inventory Turnover Ratio | NUMBER     | How quickly inventory sells     |
| `customer_satisfaction_score` | Customer Satisfaction    | PERCENTAGE | Customer satisfaction rating    |
| `customer_retention_rate`     | Customer Retention Rate  | PERCENTAGE | Repeat customer percentage      |
| `total_repair_cost`           | Total Repair Cost        | CURRENCY   | Sum of all repair expenses      |

## Data Types

### NUMBER

Raw numeric values (e.g., 1234, 567.89)

### CURRENCY

Monetary values formatted with currency symbols (e.g., \$1,234.56, MAD 5,000.00)

### PERCENTAGE

Values displayed as percentages (e.g., 18.5%, 92.3%)

### DURATION

Time periods in days or hours (e.g., 28 days, 3.5 hours)

### TEXT

String values for non-numeric KPIs

## Chart Types

### DONUT

Circular chart showing proportional distribution

### BAR

Vertical or horizontal bar chart for comparisons

### LINE

Line graph showing trends over time

### AREA

Area chart showing cumulative trends

### RADIAL

Radial/gauge chart for single-value metrics

### NONE

No chart visualization

## Use Cases

### Example 1: Track Sales Performance

```bash theme={null}
# Get visible KPIs for dashboard
curl -X GET "https://api.steerai.autos/v1/kpis/visible" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 2: Create Custom Conversion Rate KPI

```bash theme={null}
curl -X POST "https://api.steerai.autos/v1/kpis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "lead_conversion_rate",
    "title": "Lead Conversion Rate",
    "description": "Percentage of leads that convert to sales",
    "kpiType": "CUSTOM",
    "dataType": "PERCENTAGE",
    "icon": "chart-line",
    "color": "#28a745"
  }'
```

### Example 3: Get Historical Chart Data

```bash theme={null}
curl -X GET "https://api.steerai.autos/v1/kpis/{kpi_id}/chart-data?timeRange=90d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Start with built-in KPIs">
    Use the provided built-in KPIs before creating custom ones. They're optimized and battle-tested.
  </Accordion>

  <Accordion title="Limit dashboard KPIs to 6-8">
    Too many KPIs create clutter. Focus on your most critical metrics.
  </Accordion>

  <Accordion title="Use consistent time ranges">
    Compare KPIs using the same time periods for meaningful insights.
  </Accordion>

  <Accordion title="Document custom KPI formulas">
    Clearly document how custom KPIs are calculated for team understanding.
  </Accordion>

  <Accordion title="Review and adjust regularly">
    KPIs should evolve with your business. Review quarterly and adjust as needed.
  </Accordion>
</AccordionGroup>

## Error Codes

| Code                          | Status | Description                                |
| ----------------------------- | ------ | ------------------------------------------ |
| `KPI_NOT_FOUND`               | 404    | KPI ID does not exist                      |
| `CANNOT_DELETE_BUILTIN`       | 400    | Cannot delete built-in KPIs                |
| `CANNOT_MODIFY_BUILTIN_LOGIC` | 400    | Cannot change calculation of built-in KPIs |
| `DUPLICATE_KPI_KEY`           | 400    | KPI key already exists                     |
| `INVALID_CHART_TYPE`          | 400    | Chart type not supported                   |

<Card title="Dashboard KPIs Guide" icon="gauge-high" href="/guides/dashboard-kpis">
  Learn more about optimizing your KPI dashboard
</Card>