Skip to main content
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

ActionRequired role
View boards and saved metricsViewer
Create boards and saved metricsEditor
Update or delete own contentEditor (owner)
Update or delete anyone’s contentAdmin
Share boards and saved metricsEditor (owner) or Admin

​
What’s next