KPI Dashboard API - Steer Autos Documentation

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

GET

endpoint

/kpis

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

[
  {
    "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

GET

endpoint

/kpis/visible

Retrieve only KPIs marked as visible for dashboard display. Response: Array of KPI objects with isVisible: true.

Get KPI by ID

GET

endpoint

/kpis/

Retrieve detailed information about a specific KPI. Path Parameters:

string

required

KPI UUID

Response:

{
  "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

POST

endpoint

/kpis

Create a new custom KPI with your own calculation logic. Request Body:

{
  "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"
}

key

string

required

Unique identifier key (lowercase, underscores)

title

string

required

Display title for the KPI

description

string

Detailed description of what this KPI measures

formula

string

Formula or calculation logic

kpiType

enum

required

Type: BUILTIN, CUSTOM

dataType

enum

required

Data type: NUMBER, CURRENCY, PERCENTAGE, DURATION, TEXT

icon

string

Icon identifier (FontAwesome icon name)

color

string

Hex color code for visualization

displayOrder

number

Sort order for dashboard display

isVisible

boolean

Whether KPI is visible on dashboard (default: true)

aggregation

string

Aggregation method: sum, average, count, min, max

targetModel

string

Database model to aggregate from

targetField

string

Field to aggregate

Response:

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

Update KPI

PATCH

endpoint

/kpis/

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

string

required

KPI UUID

Request Body:

{
  "title": "Updated Title",
  "isVisible": false,
  "displayOrder": 5,
  "color": "#ff6b6b"
}

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

Delete KPI

DELETE

endpoint

/kpis/

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

string

required

KPI UUID

Response:

{
  "success": true,
  "message": "Custom KPI deleted successfully"
}

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

Reorder KPIs

PUT

endpoint

/kpis/reorder

Update display order for multiple KPIs at once. Request Body:

{
  "orders": [
    { "id": "kpi_uuid_1", "displayOrder": 1 },
    { "id": "kpi_uuid_2", "displayOrder": 2 },
    { "id": "kpi_uuid_3", "displayOrder": 3 }
  ]
}

Response:

{
  "success": true,
  "message": "KPIs reordered successfully"
}

Toggle KPI Visibility

PATCH

endpoint

/kpis//toggle

Toggle visibility of a KPI on the dashboard. Path Parameters:

string

required

KPI UUID

Response:

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

Reset to Default KPIs

POST

endpoint

/kpis/reset

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:

{
  "success": true,
  "message": "KPIs reset to defaults successfully",
  "kpisCount": 8
}

This action cannot be undone. All custom KPIs and configuration changes will be permanently lost.

Update KPI Chart Configuration

PATCH

endpoint

/kpis//chart

Configure chart visualization settings for a KPI. Path Parameters:

string

required

KPI UUID

Request Body:

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

chartType

enum

Chart type: NONE, DONUT, BAR, LINE, AREA, RADIAL

chartEnabled

boolean

Enable/disable chart display

chartConfig

object

Chart-specific configuration options

Get KPI Chart Data

GET

endpoint

/kpis//chart-data

Retrieve historical time-series data for KPI chart visualization. Path Parameters:

string

required

KPI UUID

Query Parameters:

timeRange

enum

Time range: 7d, 30d, 90d (default: 30d)

Response:

{
  "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

# 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

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

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

Best Practices

Start with built-in KPIs

Use the provided built-in KPIs before creating custom ones. They’re optimized and battle-tested.

Limit dashboard KPIs to 6-8

Too many KPIs create clutter. Focus on your most critical metrics.

Use consistent time ranges

Compare KPIs using the same time periods for meaningful insights.

Document custom KPI formulas

Clearly document how custom KPIs are calculated for team understanding.

Review and adjust regularly

KPIs should evolve with your business. Review quarterly and adjust as needed.

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

Dashboard KPIs Guide

Learn more about optimizing your KPI dashboard

API Documentation

​Overview

​Endpoints

​Get All KPIs

​Get Visible KPIs Only

​Get KPI by ID

​Create Custom KPI

​Update KPI

​Delete KPI

​Reorder KPIs

​Toggle KPI Visibility

​Reset to Default KPIs

​Update KPI Chart Configuration

​Get KPI Chart Data

​Built-in KPIs

​Data Types

​NUMBER

​CURRENCY

​PERCENTAGE

​DURATION

​TEXT

​Chart Types

​DONUT

​BAR

​LINE

​AREA

​RADIAL

​NONE

​Use Cases

​Example 1: Track Sales Performance

​Example 2: Create Custom Conversion Rate KPI

​Example 3: Get Historical Chart Data

​Best Practices

​Error Codes

Dashboard KPIs Guide

Overview

Endpoints

Get All KPIs

Get Visible KPIs Only

Get KPI by ID

Create Custom KPI

Update KPI

Delete KPI

Reorder KPIs

Toggle KPI Visibility

Reset to Default KPIs

Update KPI Chart Configuration

Get KPI Chart Data

Built-in KPIs

Data Types

NUMBER

CURRENCY

PERCENTAGE

DURATION

TEXT

Chart Types

DONUT

BAR

LINE

AREA

RADIAL

NONE

Use Cases

Example 1: Track Sales Performance

Example 2: Create Custom Conversion Rate KPI

Example 3: Get Historical Chart Data

Best Practices

Error Codes