# Dashboard API

Contents

* [Dashboard HTTP API](https://docs.hostedgraphite.com/api-guides/dashboard-api)
  * [Dashboard Snapshot PNG](#dashboard-snapshot-png)
  * [Create dashboard](#create-and-update-dashboard)
  * [Get dashboard](#get-dashboard)
  * [Delete dashboard](#delete-dashboard)
  * [Search dashboards](#search-dashboards)
  * [Create a New Folder](#create-a-new-folder)

### [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 -i -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

***

### **You can interact with your dashboard instance directly through** [**Grafana's HTTP 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="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2F9WOZdYm42RuRsuulwflk%2Fcreate-service-account-token.png?alt=media&#x26;token=04c04804-9453-4b78-b825-ef783e2189da" 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
}
```

* In all below examples `<UID>` refers to the URL subdomain of your hosted instance, `uid` refers to the unique identifier of the related resource. Below are examples of requests made using the Grafana Dashboard HTTP API.

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

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

Creates a new dashboard or updates an existing dashboard

**Example:**

```bash
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <SERVICE-ACCOUNT-TOKEN>" \
"https://<UID>.hostedgraphite.com/api/dashboards/db" \
-d @dashboard.json
```

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

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

```json
{
    "slug": "production-overview",
    "status": "success",
    "version": 1
}
```

{% endtab %}

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

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

**Example dashboard.json file:**

```json
{
    "dashboard": {
        "title": "Minimal Dashboard",
        "panels": []
    },
    "folderId": 0,
    "overwrite": false
}
```

***

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

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

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

| Name          | Value                            |
| ------------- | -------------------------------- |
| Content-Type  | `application/json`               |
| Authorization | `Bearer <SERVICE-ACCOUNT-TOKEN>` |

**Curl examples:**

```bash
curl -X GET \
-H "Authorization: Bearer <SERVICE-ACCOUNT-TOKEN>" \
"https://<UID>.hostedgraphite.com/api/dashboards/uid/<DASHBOARD-UID>"
```

**Response**:

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

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

```json
{ 
    "meta": { 
        "isStarred": false,
        "slug": "production-overview" 
    }, 
    "model": { 
        "id": null, 
        "title": "Production Overview",
        "tags": [ "templated" ],
        "timezone": "browser",
        "panels": [ { } ] 
        "schemaVersion": 6,
        "version": 0 
    }, 
}
```

{% 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/dashboards/uid/:uid`

Deletes a dashboard given the dashboard slug.

| Name          | Value                            |
| ------------- | -------------------------------- |
| Content-Type  | `application/json`               |
| Authorization | `Bearer <SERVICE-ACCOUNT-TOKEN>` |

**Example:**

<pre class="language-bash"><code class="lang-bash">curl -X DELETE \
-H "Authorization: Bearer &#x3C;SERVICE-ACCOUNT-TOKEN>" \
<strong>"https://&#x3C;UID>.hostedgraphite.com/api/dashboards/uid/&#x3C;DASHBOARD-UID>"
</strong></code></pre>

**Response**:

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

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

```json
{
    "title": "Example Dash",
    "message": "Dashboard Example Dash deleted",
    "id": 3
}
```

{% endtab %}

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

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

***

### [Search dashboards](#search-dashboards)

<mark style="color:blue;">`GET`</mark> `/api/search`

Returns a list of dashboards given a search query.

| Name          | Value                            |
| ------------- | -------------------------------- |
| Content-Type  | `application/json`               |
| Authorization | `Bearer <SERVICE-ACCOUNT-TOKEN>` |

**Example**:

```bash
curl -X GET \
-H "Authorization: Bearer <SERVICE-ACCOUNT-TOKEN>" \
"https://<UID>.hostedgraphite.com/api/search"
```

**Response**:

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

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

```json
[
    {
        "id": 1,
        "title": "Production Overview",
        "uri": "db/production-overview",
        "type": "dash-db",
        "tags": [
            "templated",
            "production"
        ],
        "isStarred": true
    },
    {
        "id": 4,
        "title": "Production Webservers",
        "uri": "db/production-webservers",
        "type": "dash-db",
        "tags": [
            "production"
        ],
        "isStarred": true
    }
    ...
]
```

{% endtab %}

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

***

### [Create a New Folder](#create-a-new-folder)

<mark style="color:green;">`POST`</mark> `/api/folders`

Creates a new folder for dashboard organization.

**Headers**

| Name          | Value                            |
| ------------- | -------------------------------- |
| Content-Type  | `application/json`               |
| Authorization | `Bearer <SERVICE-ACCOUNT-TOKEN>` |

**JSON Schema**

| Name    | Type   | Description        |
| ------- | ------ | ------------------ |
| `title` | string | name of new folder |

**Example**:

```sh
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer  <SERVICE-ACCOUNT-TOKEN>" \
"https://<UID>.hostedgraphite.com/api/folders" -d '{"title": "Test Folder"}'
```

**Response:**

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

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

```json
{
    "id": 70,
    "uid": "bfc49500-7c2d-4d73-ba43-d8ab677d4836",
    "title": "Test Folder",
    "url": "/dashboards/f/bfc49500-7c2d-4d73-ba43-d8ab677d4836/test-folder",
    "hasAcl": false,
    "canSave": true,
    "canEdit": true,
    "canAdmin": true,
    "canDelete": true,
    "createdBy": "Anonymous",
    "created": "2024-10-15T13:10:22.922696496Z",
    "updatedBy": "Anonymous",
    "updated": "2024-10-15T13:10:22.922696646Z",
    "version": 1
}
```

{% endtab %}

{% tab title="400" %}
Errors (invalid json, missing or invalid fields, etc
{% endtab %}

{% tab title="409" %}
Folder already exists
{% endtab %}
{% endtabs %}