Documentation

Configuration

Set up cards, choose where their data comes from, and authenticate against your APIs.

Card Configuration

Every card requires basic configuration regardless of which data method you use.

Required Settings

Setting Description
Name Display name for the card
URL API endpoint URL
Refresh Interval How often to fetch new data

Refresh Intervals

TailStats automatically polls your API at the configured interval:

Interval Use Case
30 seconds Real-time dashboards, live metrics
1 minute Active monitoring
5 minutes Standard dashboards
15 minutes Slow-changing data
30 minutes Daily summaries
1 hour Infrequent updates

Note: Data is also refreshed immediately when the app launches, you click the refresh button, or the device comes back online.

Data Sources

TailStats supports four ways to get data into cards:

Remote API

Poll any REST API at configurable intervals. Extract data with JSONPath or use structured responses.

Local Push

Push data via CLI, scripts, or webhooks. Perfect for CI/CD pipelines, cron jobs, and custom integrations.

File Watch

Monitor local files for changes. Display log files, config values, or any file content as live cards.

Script Endpoints

Write custom JavaScript to fetch, transform, and return data from any source as a hosted endpoint.

Card Parameters

Define user-configurable parameters for cards. Parameters appear as editable form fields in the card settings, and their values are passed to scripts as environment variables or interpolated into HTTP URLs and headers.

Defining Parameters

Include a params array in your card's JSON response (script output, API response, or push payload). TailStats automatically picks up the definitions and shows them as editable form fields in the card settings. Each parameter uses the same format as action inputs:

{
  "params": [
    {"id": "url", "label": "URL to monitor", "type": "text", "required": true},
    {"id": "threshold", "label": "Timeout (ms)", "type": "text", "value": "5000"},
    {"id": "region", "label": "Region", "type": "select", "options": [
      {"label": "US East", "value": "us-east-1"},
      {"label": "EU West", "value": "eu-west-1"}
    ], "value": "us-east-1"}
  ]
}

Supported types: text, textarea, select, radio, checkbox, file, number, slider, toggle, date, color, password. The value field sets the default; user-entered values are stored separately and persist across updates.

Scripts: Environment Variables

Scripts declare their parameters in the JSON output alongside items. TailStats saves the definitions and shows them in card settings. On each run, the user's values are injected as TAILSTATS_PARAM_* environment variables (ID uppercased, dashes/dots → underscores).

#!/bin/bash
# TailStats injects: TAILSTATS_PARAM_URL, TAILSTATS_PARAM_THRESHOLD
URL="${TAILSTATS_PARAM_URL:-https://example.com}"
TIMEOUT="${TAILSTATS_PARAM_THRESHOLD:-5000}"

STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time "$((TIMEOUT/1000))" "$URL")

# Output items AND params (TailStats saves params to card settings)
cat <<EOF
{
  "items": [{"title": "$URL", "type": "status", "value": "$STATUS"}],
  "params": [
    {"id": "url", "label": "URL to monitor", "type": "text", "required": true},
    {"id": "threshold", "label": "Timeout (ms)", "type": "text", "value": "5000"}
  ]
}
EOF

HTTP Cards: URL & Header Interpolation

Use ${param.<id>} tokens in the card URL and custom headers. Tokens are replaced with the user's parameter values before each request.

// Card URL with param interpolation:
https://api.example.com/status?url=${param.url}®ion=${param.region}

// Custom header with param:
X-API-Key: ${param.api_key}

How it works: TailStats automatically extracts params from your script output, API response, or push payload and saves them to the card configuration. The parameters appear in the card's edit screen as form fields. User-entered values persist across updates — refreshing the param definitions won't overwrite existing values.

Authentication

TailStats supports multiple authentication methods for accessing protected APIs.

No Authentication

For public APIs, select "None".

Basic Authentication

HTTP Basic Auth with username and password.

Field Description
Username Your username or API user
Password Your password or API key

Credentials are sent as Authorization: Basic <base64> header.

Bearer Token

For APIs using bearer tokens (JWT, API keys, etc).

Field Description
Token Your bearer token or API key

Sent as Authorization: Bearer <token> header.

OAuth 2.0

For services using OAuth 2.0 client credentials flow.

Field Description
Client ID OAuth client identifier
Client Secret OAuth client secret
Token URL Token endpoint URL
Scope Optional OAuth scopes (space-separated)

TailStats handles token refresh automatically.

Custom Headers

Add any custom HTTP headers for APIs requiring special authentication or configuration.

Field Description
Header Name HTTP header name (e.g., X-API-Key)
Header Value Header value

You can add multiple custom headers per card.