> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.labric.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.labric.co/_mcp/server.

# Create a dashboard

POST https://platform.labric.co/api/v1/dashboards
Content-Type: application/json

Creates a dashboard and any new visualizations among its items in one
transaction. New visualizations are validated as in Create a visualization.
If a dashboard with the same items exists, returns it instead, regardless
of name and layout.

Requires an API key with the `write` scope.

Reference: https://docs.labric.co/api-reference/labric-api/dashboards/create

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects a CreateDashboardSchema.

- `name` (string, required) — Name, unique among the organization's dashboards.
- `items` (list of CreateDashboardSchemaItemsItems, required) — Items, in layout order.
- `description` (string, optional, nullable) — Summary shown under the dashboard's name.

## Response

### 200

OK

- `id` (string, required)
- `name` (string, required)
- `publish_status` (enum, required) — Whether an authored object is finished enough for others to rely on. In review marks a draft its author considers ready for an admin to publish.
  - Allowed values: `draft`, `in_review`, `published`
- `date_updated` (datetime, required)
- `description` (string, optional, nullable)
- `items` (list of DashboardItemSchema, optional, nullable)
- `user` (UserSchema, optional, nullable)
- `access_level` (enum, optional, nullable) — What a grant lets its grantee do. Manage includes edit and adds sharing, archiving and deleting.
  - Allowed values: `edit`, `manage`

## Errors

### 400 Bad Request Error

Bad Request

- `detail` (string, required)

### 401 Unauthorized Error

Unauthorized

- `detail` (string, required)

### 403 Forbidden Error

Forbidden

- `detail` (string, required)

### 404 Not Found Error

Not Found

- `detail` (string, required)

### 422 Unprocessable Entity Error

Unprocessable Content

- `detail` (list of map from string to any, required)

### 500 Internal Server Error

Internal Server Error

- `detail` (string, required)

### 503 Service Unavailable Error

Service Unavailable

- `detail` (string, required)

## Types

### CreateDashboardSchemaItemsItems

- `category`: `text` (TextItemSchema)
  - `text` (string, required) — Text shown verbatim. Markdown is not rendered.
  - `size_x` (integer, optional, nullable) — Width in columns, out of 12.
  - `size_y` (integer, optional, nullable) — Height in rows.
- `category`: `visualization` (VisualizationItemSchema)
  - `item_description` (string, optional, nullable) — Caption shown with the chart.
  - `params` (map from string to any, optional, nullable) — Values for the chart's query parameters. They override the dashboard's widgets for this chart only.
  - `size_x` (integer, optional, nullable) — Width in columns, out of 12.
  - `size_y` (integer, optional, nullable) — Height in rows.
  - `visualization` (CreateVisualizationSchema, optional, nullable) — A new visualization, saved with the dashboard.
  - `visualization_id` (string, optional, nullable) — ID of a saved visualization.
- `category`: `widget` (WidgetItemSchema)
  - `parameter_name` (string, required)
  - `widget_type` (enum, required)
    - Allowed values: `combobox`, `date`, `slider`, `text`, `region`
  - `file_id` (string, optional, nullable)
  - `file_id_parameter` (string, optional, nullable)
  - `item_description` (string, optional, nullable) — Caption shown with the widget.
  - `label` (string, optional, nullable)
  - `max` (double, optional, nullable)
  - `min` (double, optional, nullable)
  - `model_source` (string, optional, nullable)
  - `step` (double, optional, nullable)

### DashboardItemSchema

- `id` (string, required)
- `category` (enum, required)
  - Allowed values: `visualization`, `text`, `widget`
- `position_x` (integer, required)
- `position_y` (integer, required)
- `size_x` (integer, required)
- `size_y` (integer, required)
- `description` (string, optional, nullable)
- `visualization` (VisualizationSchema, optional, nullable)
- `specification` (map from string to any, optional, nullable)

### UserSchema

- `clerk_id` (string, required)
- `email` (string, required)
- `first_name` (string, optional, nullable)
- `last_name` (string, optional, nullable)
- `image_url` (string, optional, nullable)

### CreateVisualizationSchema

A new visualization of a saved dataset or of a new query. Give exactly one of dataset_id and query.

- `name` (string, required) — Name, unique among the organization's visualizations.
- `specification` (map from string to any, required) — Chart specification. It needs a chart\_type: line, bar, scatter, box, or violin with traces, a list of \{x\_field, y\_field, title?, group\_by?, group\_label?}; image with image\_field and an optional caption\_field; cube with x\_field, y\_field, channel\_field, and intensity\_field; big\_number with value\_field and optional aggregation, unit, and decimal\_places; or sankey with stage\_fields, two or more columns in stage order, and an optional value\_field. Optional title, x\_label, and y\_label label the chart. Every field must be a column the data returns.
- `description` (string, optional, nullable) — Description shown with the chart.
- `dataset_id` (string, optional, nullable) — ID of a saved dataset to plot.
- `query` (string, optional, nullable) — SQL query: a single read-only SELECT statement. Reference parameters as :name. The query is saved as a dataset named after the visualization, unless a dataset with the same query and default parameters exists.
- `default_parameters` (map from string to any, optional, nullable) — Default values for the query's parameters, keyed by name. Give one for every parameter the query uses. Only used with query.

### VisualizationSchema

- `id` (string, required)
- `name` (string, required)
- `publish_status` (enum, required) — Whether an authored object is finished enough for others to rely on. In review marks a draft its author considers ready for an admin to publish.
  - Allowed values: `draft`, `in_review`, `published`
- `date_updated` (datetime, required)
- `description` (string, optional, nullable)
- `dataset` (DatasetSchema, optional, nullable)
- `specification` (map from string to any, optional, nullable)
- `user` (UserSchema, optional, nullable)
- `access_level` (enum, optional, nullable) — What a grant lets its grantee do. Manage includes edit and adds sharing, archiving and deleting.
  - Allowed values: `edit`, `manage`

### DatasetSchema

- `id` (string, required)
- `name` (string, required)
- `publish_status` (enum, required) — Whether an authored object is finished enough for others to rely on. In review marks a draft its author considers ready for an admin to publish.
  - Allowed values: `draft`, `in_review`, `published`
- `date_updated` (datetime, required)
- `description` (string, optional, nullable)
- `query` (string, optional, nullable)
- `default_parameters` (map from string to any, optional, nullable)
- `user` (UserSchema, optional, nullable)
- `access_level` (enum, optional, nullable) — What a grant lets its grantee do. Manage includes edit and adds sharing, archiving and deleting.
  - Allowed values: `edit`, `manage`

## Examples

**Request**

```json
{
  "name": "string",
  "items": [
    {
      "category": "string"
    }
  ]
}
```

**Response**

```json
{
  "id": "string",
  "name": "string",
  "publish_status": "draft",
  "date_updated": "2024-01-15T09:30:00Z",
  "description": "string",
  "items": [
    {
      "id": "string",
      "category": "visualization",
      "position_x": 1,
      "position_y": 1,
      "size_x": 1,
      "size_y": 1,
      "description": "string",
      "visualization": {
        "id": "string",
        "name": "string",
        "publish_status": "draft",
        "date_updated": "2024-01-15T09:30:00Z",
        "description": "string",
        "dataset": {
          "id": "string",
          "name": "string",
          "publish_status": "draft",
          "date_updated": "2024-01-15T09:30:00Z",
          "description": "string",
          "query": "string",
          "default_parameters": {},
          "user": {
            "clerk_id": "string",
            "email": "string",
            "first_name": "string",
            "last_name": "string",
            "image_url": "string"
          },
          "access_level": "edit"
        },
        "specification": {},
        "user": {
          "clerk_id": "string",
          "email": "string",
          "first_name": "string",
          "last_name": "string",
          "image_url": "string"
        },
        "access_level": "edit"
      },
      "specification": {}
    }
  ],
  "user": {
    "clerk_id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string"
  },
  "access_level": "edit"
}
```

**SDK Code**

```python
import requests

url = "https://platform.labric.co/api/v1/dashboards"

payload = {
    "name": "string",
    "items": [{ "category": "string" }]
}
headers = {
    "Authorization": "Bearer <api_key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```