---
title: Create a dashboard
description: Creates a new Insights dashboard.
url: https://docs.honeybadger.io/api/v3/dashboards/create-dashboard/
---

API v3 is in preview

Endpoints and response shapes [can change before general availability](https://docs.honeybadger.io/api/v3/#preview). API v2 is unchanged.

POST `https://app.honeybadger.io/v3/projects/{project_id}/dashboards`

[Required scope](https://docs.honeybadger.io/api/v3/authentication/#scopes) `dashboards:write`

Creates a new Insights dashboard.

Example request

```sh
curl -X POST "https://app.honeybadger.io/v3/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Production overview"
}'
```

## Parameters

### Path parameters

| Field | Type | Description |
| - | - | - |
| `project_id` required | string | Project ID. |

## Request body

| Field | Type | Description |
| - | - | - |
| `title` required | string | Max length 255. |
| `default_ts` | string \| null | Default time range. Null clears it. |
| `widgets` | array\<object> | The dashboard's widgets, kept and read back in this order. Sent on an update, the list replaces the stored one. Default: `[]`. See [Widget types](https://docs.honeybadger.io/api/v3/dashboards/widget-types/) for each `type` value's fields. |
| `widgets[].id` | string | Kept as sent. Unique within its dashboard; another dashboard can use the same ID. Left out, the server assigns one. Use letters, digits, `-` and `_`. |
| `widgets[].type` required | string | Which kind of widget, and therefore which config shape applies. Allowed values: `insights_vis`, `alarms`, `deployments`, `checkins`, `uptime`, `errors`. |
| `widgets[].grid` | object | Merged into the default {x: 0, y: 0, w: 12, h: 3}: left out, the widget gets the default, and a key left out takes the default's value. Default: `{"x":0,"y":0,"w":12,"h":3}`. |
| `widgets[].grid.x` | integer | Min 0. |
| `widgets[].grid.y` | integer | Min 0. |
| `widgets[].grid.w` | integer | Min 1. |
| `widgets[].grid.h` | integer | Min 1. |
| `widgets[].presentation` | object | |
| `widgets[].presentation.title` | string | Max length 255. |
| `widgets[].presentation.subtitle` | string | Max length 255. |
| `widgets[].config` | object | The widget's settings, as described by DashboardWidgetConfig\<Type> for its `type`. |

The remaining `widgets[]` fields depend on `widgets[].type`. See [Widget types](https://docs.honeybadger.io/api/v3/dashboards/widget-types/) for each value's settings.

| Type | Settings |
| - | - |
| [alarms](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#alarms) | 2 |
| [checkins](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#checkins) | 2 |
| [deployments](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#deployments) | 3 |
| [errors](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#errors) | 3 |
| [insights\_vis](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#insights_vis) | 5 |
| [uptime](https://docs.honeybadger.io/api/v3/dashboards/widget-types/#uptime) | 1 |

## Responses

### 201 Dashboard created

Example payload

```json
{
  "data": {
    "id": "Db4rKn",
    "project_id": "Xk9mZp",
    "title": "Performance Overview",
    "widgets": [
      {
        "id": "checkout-errors",
        "type": "insights_vis",
        "grid": {
          "x": 0,
          "y": 0,
          "w": 0,
          "h": 0
        },
        "presentation": {
          "title": "Checkout errors",
          "subtitle": "Last 24 hours"
        },
        "config": {}
      }
    ],
    "is_default": true,
    "shared": true,
    "default_ts": "PT3H",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "links": {
      "web": "https://app.honeybadger.io/projects/Xk9mZp"
    }
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `data` required | object | An Insights dashboard: a project's grid of widgets charting queries, errors, uptime, check-ins, deploys and alarms. |
| `data.id` required | string | |
| `data.project_id` required | string | ID of the project this dashboard belongs to. |
| `data.title` required | string | Dashboard title. |
| `data.widgets` required | array\<object> | The dashboard's widgets, in the order they were written and in the same shape a write accepts, including `config.streams` as stream slugs. |
| `data.widgets[].id` | string | Kept as sent, or generated when left out. Send it back on update to keep the widget. |
| `data.widgets[].type` required | string | Which kind of widget, and therefore which config shape applies. Allowed values: `insights_vis`, `alarms`, `deployments`, `checkins`, `uptime`, `errors`. |
| `data.widgets[].grid` | object | Position and size on the dashboard grid. |
| `data.widgets[].grid.x` | integer | Min 0. |
| `data.widgets[].grid.y` | integer | Min 0. |
| `data.widgets[].grid.w` | integer | Min 1. |
| `data.widgets[].grid.h` | integer | Min 1. |
| `data.widgets[].presentation` | object | Display-only chrome. |
| `data.widgets[].presentation.title` | string | Max length 255. |
| `data.widgets[].presentation.subtitle` | string | Max length 255. |
| `data.widgets[].config` | object | Type-specific configuration. Its fields depend on `type`; the DashboardWidgetConfig schema for each type lists them. |
| `data.is_default` required | boolean | Whether this is the default dashboard. |
| `data.shared` required | boolean | Whether the dashboard is shared with all team members. |
| `data.default_ts` required | string \| null | Default time range for the dashboard. |
| `data.created_at` required | date-time | When the dashboard was created. |
| `data.updated_at` required | date-time | When the dashboard was last updated. |
| `data.links` required | object | Links into the Honeybadger web UI. |
| `data.links.web` required | uri | The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

## Errors

### 401 Unauthorized

The credential is missing, invalid, expired or revoked (`unauthorized`), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: unsupported\_auth\_scheme (Sent as HTTP basic, which v3 does not accept)

```json
{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: credential\_in\_query (Sent as the \`auth\_token\` query parameter)

```json
{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 403 Forbidden

The credential isn’t allowed to do this. `error.code` says why. An account or project the credential doesn’t cover is 404 `not_found`, not 403.

Example payload: access\_denied (The credential isn't allowed to do this to this record)

```json
{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: insufficient\_scope (The credential lacks the permission this endpoint requires)

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: requires\_user\_token (The endpoint records who acted, and an account token has nobody)

```json
{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Example payload: project\_restricted (A project-restricted credential cannot create a project)

```json
{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 404 Not Found

Resource not found

Example payload

```json
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

### 422 Unprocessable Content

Validation error

Example payload

```json
{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": [
      {
        "field": "name",
        "message": "can't be blank"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}
```

Response schema

| Field | Type | Description |
| - | - | - |
| `error` required | object | |
| `error.code` required | string | Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`. |
| `error.message` required | string | Human-readable explanation. |
| `error.details` | array\<object> \| object | A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add. |
| `meta` | object | |
| `meta.request_id` | string | Unique identifier for the request, for correlating with support. |

---

## Try Honeybadger for FREE

Intelligent logging, error tracking, and Just Enough APM™ in one dev-friendly platform. Find and fix problems before users notice.

[Start free trial](https://app.honeybadger.io/users/sign_up)

[See plans and pricing](https://www.honeybadger.io/plans/)