Boards & Metrics

Boards are configurable dashboards with metric blocks and markdown notes. Saved metrics let you store and reuse metric configurations. Both are workspace-scoped and support sharing via public links. All endpoints require a JWT token and X-Workspace-ID header:

curl https://your-tell-server/api/v1/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Boards

Create a board

curl -X POST https://your-tell-server/api/v1/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Overview",
    "description": "Key metrics for the product team"
  }'

Requires Editor role or higher. Titles must be 1-200 characters. Descriptions are optional (max 2,000 characters).

List boards

# All boards in workspace
curl https://your-tell-server/api/v1/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Pinned boards only
curl "https://your-tell-server/api/v1/boards?pinned_only=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Get a board

curl https://your-tell-server/api/v1/boards/{board-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Returns the board with its full settings, including all metric blocks and note blocks.

Update a board

curl -X PUT https://your-tell-server/api/v1/boards/{board-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "settings": { ... }
  }'

Only the board owner or an Admin can update. Settings include the grid layout, metric blocks (max 50), and note blocks (max 50). Each metric block supports up to 20 series.

Delete a board

curl -X DELETE https://your-tell-server/api/v1/boards/{board-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Pin a board

Pinned boards appear at the top of the board list for quick access.

curl -X PUT https://your-tell-server/api/v1/boards/{board-id}/pin \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Saved metrics

Saved metrics store a metric configuration (query, time range, breakdown) for reuse on boards or standalone viewing.

Create a saved metric

curl -X POST https://your-tell-server/api/v1/metrics/saved \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Active Users",
    "workspace_id": "ws_abc123",
    "query": { "metric": "wau", "range": "30d", "granularity": "daily" }
  }'

List saved metrics

curl "https://your-tell-server/api/v1/metrics/saved?workspace_id=ws_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Get, update, delete

# Get
curl https://your-tell-server/api/v1/metrics/saved/{metric-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Update (owner or Admin)
curl -X PUT https://your-tell-server/api/v1/metrics/saved/{metric-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"title": "WAU - Last 90 Days", "query": { "metric": "wau", "range": "90d" }}'

# Delete (owner or Admin)
curl -X DELETE https://your-tell-server/api/v1/metrics/saved/{metric-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Permissions

Action	Required role
View boards and saved metrics	Viewer
Create boards and saved metrics	Editor
Update or delete own content	Editor (owner)
Update or delete anyone’s content	Admin
Share boards and saved metrics	Editor (owner) or Admin

What’s next

Boards & Dashboards — building dashboards as a user
Sharing — creating public share links
Data Queries — the metrics that power board blocks

​Boards

​Create a board

​List boards

​Get a board

​Update a board

​Delete a board

​Pin a board

​Saved metrics

​Create a saved metric

​List saved metrics

​Get, update, delete

​Permissions

​What’s next