> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Boards & Metrics

> CRUD operations for boards and saved metrics via the API.

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:

```bash theme={null}
curl https://your-tell-server/api/v1/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"
```

## Boards

### Create a board

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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](/analytics/boards) — building dashboards as a user
* [Sharing](/api/sharing) — creating public share links
* [Data Queries](/api/queries) — the metrics that power board blocks