Dashboards

Dashboards allow you to visualize and monitor your data in a centralized location. On this page, we'll dive into the different dashboard endpoints you can use to manage dashboards programmatically. We'll look at how to query, create, update, and delete dashboards.

Dashboards can also be managed with Terraform using the official provider: https://registry.terraform.io/providers/devhub-tools/devhub/latest/docs/resources/dashboard

The dashboard model

The dashboard model contains all the information about your dashboards, such as their name, access restrictions, and panels. It also contains information about when they were created and last updated.

Properties

Name
id
Type
string
Description
Unique identifier for the dashboard (prefixed with "dash").
Name
name
Type
string
Description
The name of the dashboard.
Name
restricted_access
Type
boolean
Description
Whether the dashboard has restricted access. Defaults to false.
Name
archived_at
Type
datetime
Description
Timestamp when the dashboard was archived, if applicable.
Name
panels
Type
array
Description
Array of dashboard panels containing visualizations and data.
Name
inserted_at
Type
datetime
Description
Timestamp of when the dashboard was created.
Name
updated_at
Type
datetime
Description
Timestamp of when the dashboard was last updated.

Panel structure

Each panel in the dashboard contains:

Name
id
Type
string
Description
Unique identifier for the panel (prefixed with "pl").
Name
title
Type
string
Description
The title of the panel.
Name
inputs
Type
array
Description
Array of input parameters for the panel.
Name
details
Type
object
Description
Panel-specific details (e.g., query information for query panels).

POST/v1/dashboards

Create a dashboard

This endpoint allows you to create a new dashboard in your organization. To create a dashboard, you must provide a name and optionally set access restrictions and panels.

Required attributes

Name
name
Type
string
Description
The name of the dashboard.
Name
restricted_access
Type
boolean
Description
Whether the dashboard has restricted access.

Optional attributes

Name
panels
Type
array
Description
Array of dashboard panels to include in the dashboard.

Request

POST

/v1/dashboards

curl https://api.devhub.com/v1/dashboards \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Metrics",
    "restricted_access": false,
    "panels": [
      {
        "title": "CPU Usage",
        "inputs": [
          {
            "key": "time_range",
            "description": "Time range for the query"
          }
        ],
        "details": {
          "__type__": "query",
          "query": "SELECT cpu_usage FROM metrics WHERE time > now() - 1h",
          "credential_id": "cred_123456789"
        }
      }
    ]
  }'

Response

{
  "id": "dash_123456789",
  "name": "Production Metrics",
  "restricted_access": false,
  "panels": [
    {
      "id": "pl_987654321",
      "title": "CPU Usage",
      "inputs": [
        {
          "key": "time_range",
          "description": "Time range for the query"
        }
      ],
      "details": {
        "__type__": "query",
        "query": "SELECT cpu_usage FROM metrics WHERE time > now() - 1h",
        "credential_id": "cred_123456789"
      }
    }
  ]
}

GET/v1/dashboards/:id

Retrieve a dashboard

This endpoint allows you to retrieve a dashboard by providing its id. Refer to the list at the top of this page to see which properties are included with dashboard objects.

Request

GET

/v1/dashboards/dash_123456789

curl https://api.devhub.com/v1/dashboards/dash_123456789 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "dash_123456789",
  "name": "Production Metrics",
  "restricted_access": false,
  "panels": [
    {
      "id": "pl_987654321",
      "title": "CPU Usage",
      "inputs": [
        {
          "key": "time_range",
          "description": "Time range for the query"
        }
      ],
      "details": {
        "__type__": "query",
        "query": "SELECT cpu_usage FROM metrics WHERE time > now() - 1h",
        "credential_id": "cred_123456789"
      }
    }
  ]
}

PUT/v1/dashboards/:id

Update a dashboard

This endpoint allows you to perform an update on a dashboard. You can update the name, restricted access setting, and panels of the dashboard.

Optional attributes

Name
name
Type
string
Description
The name of the dashboard.
Name
restricted_access
Type
boolean
Description
Whether the dashboard has restricted access.
Name
panels
Type
array
Description
Array of dashboard panels to include in the dashboard.

Request

PUT

/v1/dashboards/dash_123456789

curl -X PUT https://api.devhub.com/v1/dashboards/dash_123456789 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Production Metrics",
    "restricted_access": true
  }'

Response

{
  "id": "dash_123456789",
  "name": "Updated Production Metrics",
  "restricted_access": true,
  "panels": [
    {
      "id": "pl_987654321",
      "title": "CPU Usage",
      "inputs": [
        {
          "key": "time_range",
          "description": "Time range for the query"
        }
      ],
      "details": {
        "__type__": "query",
        "query": "SELECT cpu_usage FROM metrics WHERE time > now() - 1h",
        "credential_id": "cred_123456789"
      }
    }
  ]
}

DELETE/v1/dashboards/:id

Delete a dashboard

This endpoint allows you to delete a dashboard from your organization. Note: This action cannot be undone and will permanently remove the dashboard and all its data.

Request

DELETE

/v1/dashboards/dash_123456789

curl -X DELETE https://api.devhub.com/v1/dashboards/dash_123456789 \
  -H "Authorization: Bearer {token}"