Grafana API

The Grafana API can be used to programmatically allocate and fetch the credentials for a Grafana account that references the Replica DB. For a high-level overview of Grafana in HeadSpin, see Grafana.

Grafana API Overview

Allocating Grafana

Grafana can be allocated with the appropriate POST request shown below:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/allocate 
# Output:
{
    "username": "Example Grafana",
    "password": "...",
    "grafana_url": "https://..."
}

The username and password fields can be used to login to Grafana for the endpoint defined by grafana_url.

NOTE: The <code class="dcode">/v0/grafana/info</code> route will be deprecated for POST requests in the future.

NOTE: If Grafana is already allocated, the existing account will be returned.

Fetching Grafana Editor User

The username and password for the Grafana user with Editor role can be retrieved with the following GET request:

curl https://<your_api_token>@api-dev.headspin.io/v0/grafana/editor/info
# Output:
{
  "username": your_grafana_editor_username,
  "password": your_grafana_editor_password,
  "grafana_url": your_grafana_url,
  "grafana_role" "Editor"
}

Fetching Grafana Viewer User

The username and password for the Grafana user with Viewer role can be retrieved with the following GET request:

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/editor/info 
# Output:
{
  "username": your_grafana_viewer_username,
  "password": your_grafana_viewer_password,
  "grafana_url": your_grafana_url,
  "grafana_role" "Viewer"
}

Listing all Grafana Dashboards

All available registered Grafana dashboards can be listed with the following GET request:

curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/dashboard/info 
# Output:
{
    "dashboards": [
        {
            "allocated": true, 
            "version": 6, 
            "max_version": 6, 
            "name": "Home", 
            "dashboard_uid": "Dashboard UID"
        },
        {
            "allocated": false,
            "legacy": false,
            "name": "User Flow Timeseries"
        }
    ]
}

Allocating a Grafana Dashboard

A Grafana dashboard can be allocated from a HeadSpin template with the following POST request:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/dashboard/allocate -d '{"dashboard_name": "My Dashboard"}' 
# Output:
{
    "status": "Successfully allocated dashboard",
    "dashboard_name": "My Dashboard",
    "dashboard_uid": "Dashboard UID"
    "status_code": 200
}

Registering a Grafana Dashboard

A custom dashboard that is created in Grafana directly can be registered into HeadSpin with the following POST request:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/dashboard/register -d '{"dashboard_name": "My Dashboard", "dashboard_uid": "Dashboard UID"}' 
# Output:
{
    "status": "Successfully registered dashboard",
    "status_code": 200
}

Optional Parameters

• <code class="dcode">version:</code> The version of the dashboard. Default <code class="dcode">0</code>.
• <code class="dcode">dashboard_uid</code>: The UID of the grafana dashboard.
• <code class="dcode">dashboard_url</code">: The URL of the grafana dashboard.

NOTE: Either <code class="dcode">dashboard_uid</code> or <code class="dcode">dashboard_url</code> must be provided.

Removing a Grafana Dashboard

A Grafana dashboard can be unregistered from HeadSpin or even removed entirely from Grafana with the following POST request:

curl -X DELETE -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/dashboard/remove -d '{"dashboard_name": "My Dashboard"}' 
# Output:
{
    "status": "Successfully removed dashboard (if allocated)",
    "removed_from_grafana": false,
    "status_code": 200
}

Optional Parameters

• <code class="dcode">remove_in_grafana</code>: A boolean value that specifies whether to also remove the dashboard from Grafana. By default, this is False.

NOTE: Only registered and allocated dashboards can be removed.

Resetting Grafana

When logging into the allocated Grafana account, users must not edit any of the profile information for the account. They should not change the username, email, or password inside Grafana; doing so may break some of the UI features for Grafana in HeadSpin.

If this happens by mistake, however, it is possible to reset the Grafana user. By resetting the Grafana user, the existing Grafana dashboards are preserved, but the login credentials will be reset. In order to reset Grafana, the following request can be made:

curl -X POST -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/reset 
# Output:
{
    "status": "Reset Grafana User credentials.",
    "status_code": 200
}

# Fetch the new credentials.
curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v0/grafana/info 
# Output:
{
    "username": "Example Grafana",
    "password": "...",
    "grafana_url": "https://..."
}

IMPORTANT: This will logout any users and any unsaved changes may be lost!