> For the complete documentation index, see [llms.txt](https://docs.hostedgraphite.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hostedgraphite.com/api-guides/dashboard-api.md).

# Dashboard API

Contents

* [Dashboard HTTP API](/api-guides/dashboard-api.md)
  * [Dashboard Snapshot PNG](#dashboard-snapshot-png)
  * [Create dashboard](#create-dashboard)
  * [Update dashboard](#update-dashboard)
  * [Get dashboard](#get-dashboard)
  * [Delete dashboard](#delete-dashboard)
  * [List dashboards](#list-dashboards)
  * [Grafana HTTP Dashboard API](#grafana-http-dashboard-api)

### [Dashboard Snapshot PNG](#dashboard-rendered-pngs)

<mark style="color:blue;">`GET`</mark> `/api/v3/grafana/render/?target=`

Returns PNG image of a dashboard panel. To display any data on the graph you must include a ‘target’, you can append multiple targets to the request as follows: `?target=foo.bar.A&target=foo.bar.B`

#### Parameters

| Name                                     | Type   | Description                                       |                              |   |   |   |                       |
| ---------------------------------------- | ------ | ------------------------------------------------- | ---------------------------- | - | - | - | --------------------- |
| target<mark style="color:red;">\*</mark> | String | graphite query                                    |                              |   |   |   |                       |
| from                                     | String | <p>Format: -\<num>m                               | h                            | d | w | M | Y<br>default: -6h</p> |
| to                                       | String | <p>Format: now-\<num>m                            | h                            | d | w | M | Y<br>default: now</p> |
| width                                    | String | <p>number measured in pixels<br>default: 1000</p> |                              |   |   |   |                       |
| height                                   | String | <p>number measured in pixels<br>default: 500</p>  |                              |   |   |   |                       |
| style                                    | String | <p>Format: “light”                                | “dark ”<br>default: dark</p> |   |   |   |                       |

**Curl Example:**

```bash
curl -X GET \
"https://<api-key>@api.hostedgraphite.com/api/v3/grafana/render/?target=foo.bar"
```

**Response**:

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: image/png
```

\<image data>
{% endtab %}

{% tab title="400" %}
Bad Request Invalid form data
{% endtab %}

{% tab title="401" %}
Unauthorized
{% endtab %}
{% endtabs %}

**Time Queries:**

* `m` = Minutes
* `h` = Hours
* `d` = Days
* `w` = Weeks
* `M` = Months
* `Y` = Years

***

### [Create dashboard](#create-dashboard)

<mark style="color:green;">`POST`</mark> `/api/v3/grafana/dashboards/`

Creates a new dashboard

**Example:**

```bash
curl -X POST \
-H "Content-Type: application/json" \
-d '{"title":"Example Dashboard"}' \
"https://<api-key>@www.hostedgraphite.com/api/v3/grafana/dashboards/"
```

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

{% endtab %}

{% tab title="400" %}
Bad Request Invalid JSON
{% endtab %}

{% tab title="412" %}
Conflict Dashboard already exists
{% endtab %}
{% endtabs %}

***

### [Update dashboard](#update-dahsboard)

<mark style="color:green;">`PUT`</mark> `/api/v3/grafana/dashboards/<uid>`

Updates an existing dashboard

**Example:**

```bash
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"title":"Updated Example Dashboard"}' \
"https://<api-key>@www.hostedgraphite.com/api/v3/grafana/dashboards/<uid>"
```

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

{% endtab %}

{% tab title="400" %}
Bad Request Invalid JSON
{% endtab %}

{% tab title="412" %}
Conflict Dashboard already exists
{% endtab %}
{% endtabs %}

***

### [Get dashboard](#get-dashboard)

<mark style="color:blue;">`GET`</mark> `/api/v3/grafana/dashboards/<uid>`

&#x20;Returns a dashboard given the dashboard's uid

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Curl examples:**

```bash
curl -X GET \
"https://<api-key>@www.hostedgraphite.com/api/v3/grafana/dashboards/<uid>"
```

**Response**:

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

{% endtab %}

{% tab title="400" %}
Bad Request No dashboard specified
{% endtab %}

{% tab title="404" %}
Not Found Dashboard not found
{% endtab %}
{% endtabs %}

***

### [Delete dashboard](#delete-dashboard)

<mark style="color:red;">`DELETE`</mark> `/api/v3/grafana/dashboards/<uid>`

Deletes a dashboard given the dashboard slug

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Example:**

```bash
curl -X DELETE \
"https://<api-key>@www.hostedgraphite.com/api/v3/grafana/dashboards/<uid>"
```

**Response**:

{% tabs %}
{% tab title="200" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

{% endtab %}

{% tab title="400 " %}
Bad Request No dashboard specified
{% endtab %}

{% tab title="404" %}
Dashboard not found
{% endtab %}
{% endtabs %}

***

### [List dashboards](#list-dashboards)

<mark style="color:blue;">`GET`</mark> `/api/v3/grafana/dashboards/`

Returns a list of dashboards given a search query.

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Example**:

```bash
curl -X GET \
"https://<api-key>@www.hostedgraphite.com/api/v3/grafana/dashboards/"
```

**Response**:

{% tabs %}
{% tab title="200:" %}

```http
HTTP/1.1 200
Content-Type: application/json
```

{% endtab %}

{% tab title="400" %}
Bad Request Invalid form data
{% endtab %}
{% endtabs %}

***

### [**Grafana HTTP Dashboard API**](https://grafana.com/docs/grafana/latest/developers/http_api/)

To use the Grafana API, **you will need to create a new Grafana Service Account Token** within the Grafana UI (Settings => Service Accounts => Add Service Account with Admin role => Generate Service Account Token).

<figure><img src="/files/ruYm01lGpynKeOmADgGF" alt="Create Service Account &#x26; Token" width="563"><figcaption><p>Create Service Account &#x26; Token</p></figcaption></figure>

**Additional Considerations**:

* Since MetricFire now hosts Grafana v9.5, dashboard JSON templates must now be wrapped in the following object, in order to create/update dashboards programatically ("folderID": 0, maps to the default "General" folder, but any folderID can be specified):

```json
{
  "dashboard": {
    ...entire dashboard object...
  },
  "folderId": 0,
  "overwrite": true
}
```