Create a dashboard

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

Required scope dashboards:write

Creates a new Insights dashboard.

Example request

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 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 for each value's settings.

Type	Settings
alarms	2
checkins	2
deployments	3
errors	3
insights_vis	5
uptime	1

Responses

201 Dashboard created

Example payload

{
  "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 schema25

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)

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

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "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)

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

Response schema6

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)

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

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "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)

{
  "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)

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

Response schema6

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

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

Response schema6

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

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

Response schema6

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.