Documentation

Data Formats & Responses

Three ways to shape the data your cards display, plus extraction and number formatting.

Three Ways to Display Data

TailStats supports three methods for getting data into cards:

Method Best For
Simple Value Display whatever the endpoint returns — plain text, number, or raw response
Structured Response APIs you control — return data in TailStats format
JSONPath Extraction Any JSON API — extract specific values with JSONPath

Simple Value

The simplest method — whatever your endpoint returns is displayed directly as the card value. No parsing, no extraction.

How It Works

  1. Point TailStats at any URL
  2. The raw response body is displayed as the value
  3. Works with plain text, numbers, or any string response

Example Responses

42
→ displays "42"
Online
→ displays "Online"
$1,234.56
→ displays "$1,234.56"

Tip: Simple Value is perfect for quick integrations, status endpoints, or when you just need to display a single metric without building a full API response.

Structured Response

Build an API endpoint that returns data in TailStats format for full control over the display.

Response Structure

Your endpoint should return a JSON object with an items array and optional columns:

{
  "items": [ ... ],
  "columns": 2
}
Field Type Required Description
items CardData[] Yes Array of card items to display
columns number No Grid columns (1-4, default: 1)

Field Reference

Each item in the items array has the following structure:

Field Type Required Description
id string No Unique identifier (auto-generated if omitted)
title string No Main title text
subtitle string No Secondary text below title
type string Yes Value type (see Value Types)
value varies Yes The value to display (type depends on type field)
icon string No SF Symbol name (Apple platforms only)
emoji string No Emoji icon (cross-platform)
color string No Value text color
iconColor string No Icon/emoji background tint color
menuBar boolean No Show this value in macOS menu bar (default: false)
menuBarBackground string No Menu bar badge background color
rightLabel string No Text displayed on the right side
format string No Number formatting (see Value Formatting)
sparkline array No Array of numbers for mini chart
sparklineColor string No Sparkline color
sparklineHeight int No Sparkline height (0-100)
diff object No Diff stats: {additions: int, deletions: int, additionColor?, deletionColor?}
level string No Explicit status level for status type: ok, success, warning, error, info, pending
image string No Image URL or base64 data URI. For message type: renders inline in bubble with value as caption
displayMode string No Type-specific mode: array = bar/line, message = sent/received
actions array No Per-item actions (see Actions)

Value Types

The type field determines how value is interpreted and displayed.

string

Plain text value.

{ "title": "Status", "type": "string", "value": "Online" }

number

Numeric value (integer or decimal). Displays with thousands separator.

{ "title": "Users", "type": "number", "value": 1234 }
42 → "42"
1234 → "1,234"
3.14 → "3.14"
1234.56 → "1,234.56"

array

Array of numbers, displayed as a sparkline chart. Use displayMode: "bar" for bar chart or "line" for sparkline (default).

{ "title": "Traffic", "type": "array", "value": [10, 25, 15, 30, 20] }

progress

Progress bar (0.0 to 1.0 range).

{ "title": "Storage", "type": "progress", "value": 0.75 }
0.75 → 75% progress bar
0.5 → 50% progress bar

JSONPath Extraction

Extract specific values from any JSON API using JSONPath expressions. No API modifications required.

What is JSONPath?

JSONPath is a query language for JSON data. It lets you pinpoint exactly which value to extract from an API response.

Example: If an API returns:

{
  "data": {
    "users": 1250,
    "revenue": 45000
  }
}

Use $.data.users to extract 1250.

JSONPath Syntax

All paths start with $ (the root element).

Basic Navigation

Syntax Description Example
$.key Access a property $.data
$['key'] Property with special chars $['my-key']
[0] First array item $.items[0]
[-1] Last array item $.items[-1]
[*] All array items $.items[*].name
.. Search anywhere $..price

Advanced Features

Syntax Description Example
[0:5] Items 0 through 4 $.items[0:5]
[1,3,5] Specific items $.items[1,3,5]
[?(@.active)] Filter by field exists $.users[?(@.active)]
[?(@.age > 18)] Filter by condition $.users[?(@.age > 18)]

Filter Operators

Operator Description
== Equal
!= Not equal
< <= > >= Comparisons
&& AND
|| OR

Filter examples:

  • $.users[?(@.active == true)] — Active users only
  • $.items[?(@.price < 100)] — Items under $100
  • $.users[?(@.age > 18 && @.verified)] — Verified adults

Extraction Configuration

Each JSONPath extraction can be configured with:

Field Description
Path JSONPath expression (e.g., $.data.value)
Title Label shown above the value
Format Format string (see Value Formatting)
Icon SF Symbol name (e.g., person.fill)
Emoji Unicode emoji (e.g., 💰)
Color Icon/value color
Show in Menu Bar Display in macOS menu bar
Menu Bar Text Color Color of menu bar text
Menu Bar Background Badge background color

Multiple Extractions

Add multiple JSONPath extractions to show several values from the same API in one card.

Example: From a dashboard API, extract:

  1. Total users → $.metrics.users
  2. Revenue → $.metrics.revenue
  3. Active sessions → $.metrics.active

All values display together in a grid layout. Choose 1-4 columns.

Value Formatting

Control how numeric values are displayed using format strings.

Format String Syntax

Format strings follow this pattern:

type:option:modifier
Part Required Description
type Yes number, currency, or percent
option Sometimes Currency code or display option
modifier No Additional modifiers like cents

Number Formats

Format String Input Output Description
number 1234 1,234 Standard with thousands separator
number:compact 1234567 1.2M Compact notation (K, M, B)

Currency Formats

Format: currency:CODE or currency:CODE:cents

Format String Input Output
currency:USD 1234 $1,234.00
currency:EUR 1234 €1,234.00
currency:GBP 1234 £1,234.00
currency:JPY 1234 ¥1,234
currency:CAD 1234 CA$1,234.00
currency:AUD 1234 A$1,234.00

Currency from Cents

For APIs returning amounts in cents, add :cents modifier to divide by 100:

Format String Input Output
currency:USD:cents 12345 $123.45
currency:EUR:cents 12345 €123.45
currency:GBP:cents 12345 £123.45

Percentage Formats

Format String Input Output Description
percent 75 75% Whole number percentage
percent:decimal 0.75 75% Decimal (multiplied by 100)