API Sources

API sources let you connect to any publicly accessible JSON API endpoint. TotalKPI will fetch data from the API and can automatically poll it on a schedule to keep your metrics up to date.

Setting Up an API Source

Click Add Source, then select API Endpoint. The setup walks you through a multi-step process:

Step 1: Enter Your API URL

Provide the full URL of the API endpoint you want to fetch from. Optionally, add custom headers for authentication (e.g. API keys or Bearer tokens).

Click Test Connection to verify the API returns valid JSON.

Step 2: Choose a Response Type

If the API response contains arrays, you'll be asked to choose between two modes:

• Data Series - import an array of data points that each contain a date and a value. This is ideal for APIs that return historical data.
• Single Value - extract a single numeric value from the response and append it as a new data point each time the API is polled. This is ideal for APIs that return current/live metrics.

If the response has no arrays, you'll go straight to single value mode.

Step 3: Select Your Data

For Single Value mode: A JSON tree viewer shows the full API response. Click on any numeric field to select it. The selected path and extracted value are shown for confirmation.

For Data Series mode: Select which array to use (if multiple exist), then map the value field and date field from the array items.

Step 4: Configure the Source

• Name - label for this data source.
• Unit - unit of measurement.
• Polling - enable automatic polling and choose an interval:
  • 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour, 6 hours, or 24 hours.
• Sampling (Data Series mode only) - reduce data density by keeping only one data point per time window (every 10 minutes, hourly, every 6 hours, or daily).
• Max Data Points (Data Series mode only) - cap the number of stored data points (100, 1,000, 5,000, 10,000, or no limit).

Click Add Source to finish.

Custom Headers

Use headers to pass authentication credentials to your API:

Click Add Header to add as many key-value pairs as needed.

JSON Path Extraction

TotalKPI uses dot-notation paths to drill into nested JSON responses. For example, given this response:

{
  "data": {
    "metrics": {
      "revenue": 12500
    }
  }
}

The path data.metrics.revenue extracts the value 12500.

For arrays, you can target nested arrays like data.history to access an array of objects.

Polling and Status

Once an API source is created with polling enabled, you'll see a status indicator on the source card:

• Green pulsing dot - active and polling on schedule (shows the interval, e.g. "Every 5m").
• Amber dot - the last fetch encountered an error.
• Gray dot - polling is paused.

Polling automatically pauses after 5 consecutive errors to avoid hammering a failing endpoint. You can re-enable it by editing the source.

Security

API requests are proxied through TotalKPI's server. Your API keys and authentication headers are never exposed to the browser. Requests to private/internal IP addresses (localhost, 192.168.x.x, 10.x.x.x, etc.) are blocked for security.