# Dashboards API

Project dashboards let you build persistent, shareable views over normalized telemetry. Each
dashboard is a collection of widgets that query traces, spans, logs, metrics, or conversations.
Queries are executed by the telemetry backend and streamed to the Workbench.

## When To Use It

Use the Dashboards API when you want to:

- create or update dashboards programmatically;
- embed dashboard definitions in project configuration;
- run ad-hoc widget queries outside the Workbench.

For interactive exploration, use the Workbench **Dashboards** view.

## Dashboard Definition

A dashboard contains a list of widgets. Each widget specifies a data source, visualization type,
time range, and query. The exact shape is validated by the dashboard normalizer in
`@provon/observability/dashboards`.

Common widget types include metric charts, trace lists, conversation tables, and value cards. Time
ranges can be absolute or relative, for example `last_24h` or `last_7d`.

## List Dashboards

```bash
curl "$PROVON_API_URL/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $PROVON_API_KEY"
```

## Create A Dashboard

```bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gateway health",
    "description": "Request volume, errors, and latency",
    "widgets": [
      {
        "id": "requests",
        "type": "metric_chart",
        "title": "Gateway requests",
        "source": "traces",
        "timeRange": "last_24h",
        "query": { ... }
      }
    ]
  }'
```

## Get, Update, And Delete

```bash
# Get
curl "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY"

# Update
curl -X PATCH "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated name", "widgets": [ ... ]}'

# Delete
curl -X DELETE "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY"
```

## Set The Default Dashboard

```bash
curl -X PUT "$PROVON_API_URL/projects/$PROJECT_ID/default-dashboard" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dashboardId": "<dashboard-id>"}'
```

The default dashboard is shown first when a project opens the Dashboards view.

## Execute A Widget Query

Run a dashboard query and stream results:

```bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/dashboard-queries" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [
      {
        "id": "requests",
        "type": "metric_chart",
        "source": "traces",
        "timeRange": "last_24h",
        "query": { ... }
      }
    ]
  }'
```

The response is a streaming JSON response with one result per widget. Up to 24 widgets can be
requested and up to 3 are executed concurrently.

## Capability Requirements

The project API key needs:

- `workspace:read` or `project:read` to list and get dashboards;
- `workspace:write` or `project:update` to create, update, delete, and set the default dashboard;
- `telemetry:read` or `project:data:read` to execute dashboard queries.

## Limitations

- Dashboard definitions are project-scoped; sharing across projects requires copying the definition.
- Widget query syntax is validated by the telemetry backend and may differ slightly between DuckDB,
  MotherDuck, and Cloudflare R2 SQL deployments.
- The API does not render charts; it returns the query result data and metadata that the Workbench
  visualizes.

## Next Steps

- [Telemetry Read API](./telemetry.md) for normalized log and metric queries.
- [Trace Read API](./traces.md) for trace, span, and conversation reads.
- [API reference](./index.md) for shared conventions.