> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronosphere.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate classic dashboards to standard dashboards

> Convert Grafana or classic dashboard JSON into standard dashboards using the Chronosphere Config API.

<Warning>
  Classic dashboards reach end of life on January 20, 2027. After this date,
  classic dashboards are no longer supported. [Migrate classic dashboards to
  standard dashboards](/observe/dashboards/classic-dashboards/migrate-to-standard)
  to avoid disruption.
</Warning>

Use the API to convert Grafana or [classic dashboard](/observe/dashboards/classic-dashboards)
JSON into a [standard dashboard](/observe/dashboards) and create or update the result in
Observability Platform.

This workflow is different from [Import Grafana dashboards](/observe/dashboards/classic-dashboards/grafana-import),
when you use Chronoctl or Terraform on that page, which create another classic dashboard.
It is also different from the `convert grafana` command in [Chronoctl](/tooling/chronoctl),
which produces YAML for classic dashboards.

<Warning>
  Chronosphere supports dashboards exported from Grafana versions up to 7.5. Dashboards
  exported from newer versions of Grafana might not be importable without modification.
</Warning>

## Before you convert

Copy the Grafana-format dashboard JSON you want to convert from one of the following
sources:

* Export a dashboard from Grafana. For export steps, see the
  [Grafana documentation](https://grafana.com/docs/grafana/v7.5/dashboards/export-import/).
* From an existing classic dashboard in Observability Platform:

  1. Click **Settings**, then click **Advanced settings**.
  2. Open the **General** tab.
  3. Copy the JSON from **JSON Model**.

  For details, see [Classic dashboards](/observe/dashboards/classic-dashboards#general).
* Use the [`ReadClassicDashboard`](/tooling/api-info/definition/operations/ReadClassicDashboard)
  endpoint to read an existing classic dashboard by slug.
* Copy the `dashboard_json` value from an existing `chronosphere_classic_dashboard`
  Terraform resource.

You also need the slug of the [collection](/administer/collections) that will own the
new standard dashboard.

## Import a converted dashboard

To convert Grafana-format JSON and create a standard dashboard, call
[`ImportDashboardFromClassic`](/tooling/api-info/definition/operations/ImportDashboardFromClassic):

```http theme={null}
POST /api/v1/config/dashboards:importFromClassic
```

The request body accepts the following fields:

| Field                    | Required | Description                                                                                                                                |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `classic_dashboard_json` | Yes      | Grafana-format dashboard JSON to convert, provided as a string.                                                                            |
| `collection_slug`        | Yes      | Slug of the collection that owns the new dashboard.                                                                                        |
| `name`                   | No       | Display name for the new dashboard. Defaults to the classic dashboard's `title`.                                                           |
| `slug`                   | No       | Slug for the new dashboard. When unset, Observability Platform generates a slug from the name. Required when `update_if_exists` is `true`. |
| `dry_run`                | No       | When `true`, converts and validates the dashboard without saving it.                                                                       |
| `update_if_exists`       | No       | When `true`, updates the dashboard with the given slug instead of creating a new one.                                                      |

Because the Chronosphere API requires authentication, include an API token with your
`curl` request, as shown in the following example. For more details, see
[Create an API token](/tooling/api-info#create-an-api-token).

```shell /"TOKEN"/ /INSTANCE/ /METHOD/ /ENDPOINT_PATH/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
     -X METHOD "https://${CHRONOSPHERE_DOMAIN}/ENDPOINT_PATH"
```

Replace the following:

* *`TOKEN`*: Your API token.
* *`INSTANCE`*: The subdomain name for your organization's Observability Platform instance.
* *`METHOD`*: The HTTP method to use with the request, such as `GET` or `POST`.
* *`ENDPOINT_PATH`*: The specific endpoint you want to access.

The endpoint converts the JSON, then creates or updates a standard dashboard with the
converted result. The response includes the dashboard resource and any
`unsupported_features` entries from the conversion.

### Example

The following request previews conversion of a Grafana export without saving the
dashboard. The `classic_dashboard_json` value is a string that contains the dashboard
JSON.

```json theme={null}
{
  "classic_dashboard_json": "{\"title\":\"My Dashboard\",\"panels\":[]}",
  "collection_slug": "platform",
  "dry_run": true
}
```

A successful response includes the converted dashboard and any conversion notes:

```json theme={null}
{
  "dashboard": {
    "slug": "my-dashboard",
    "name": "My Dashboard",
    "collection_slug": "platform",
    "dashboard_json": "{\"kind\":\"Dashboard\",\"spec\":{}}"
  },
  "unsupported_features": [
    {
      "kind": "unknown-variable",
      "detail": "cluster",
      "message": "Unknown variable cluster",
      "level": "LEVEL_UNSUPPORTED",
      "panel_keys": [],
      "occurrences": 1
    }
  ]
}
```

To send the example request:

```shell /platform/ theme={null}
export CHRONOSPHERE_API_TOKEN="TOKEN"
export CHRONOSPHERE_DOMAIN="INSTANCE.chronosphere.io"

curl -X POST "https://${CHRONOSPHERE_DOMAIN}/api/v1/config/dashboards:importFromClassic" \
  -H "API-Token: ${CHRONOSPHERE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"classic_dashboard_json":"{\"title\":\"My Dashboard\",\"panels\":[]}","collection_slug":"platform","dry_run":true}'
```

Replace *`TOKEN`* with your API token and *`INSTANCE`* with your Observability Platform
subdomain. Set `dry_run` to `false` to persist the dashboard.

### Preview a conversion with dry run

Set `dry_run` to `true` to convert and validate a dashboard without persisting it.
The response still includes the converted dashboard as a preview of what would be
created, along with any `unsupported_features`.

Unlike most dry-run responses in the Config API, this endpoint returns the would-be
dashboard so you can review the conversion before you save it.

### Replace an existing standard dashboard

Set `update_if_exists` to `true` and provide the target dashboard's `slug` to update
an existing standard dashboard in place with the converted result. When the slug
doesn't exist, Observability Platform creates the dashboard.

The update replaces the entire dashboard. Fields that the request doesn't carry, such
as labels, are cleared.

### Review unsupported features

The `unsupported_features` array lists classic dashboard features that were dropped,
approximated, or otherwise noteworthy during conversion. Entries are de-duplicated
by feature kind.

Each entry can include the following fields:

| Field         | Description                                                                                |
| ------------- | ------------------------------------------------------------------------------------------ |
| `kind`        | Stable identifier for the feature type, such as `unknown-variable`.                        |
| `detail`      | Input-specific detail for this occurrence, such as a variable name.                        |
| `message`     | Human-readable description of what happened during conversion.                             |
| `level`       | Whether the feature was approximated (`LEVEL_SUPPORTED`) or dropped (`LEVEL_UNSUPPORTED`). |
| `panel_keys`  | Panel keys where the feature appeared. Empty for dashboard-level features.                 |
| `occurrences` | Number of occurrences folded into this entry.                                              |

Review these entries before you rely on a migrated dashboard in production. A non-empty
list doesn't always mean the conversion failed, but it indicates where the standard
dashboard might differ from the original classic dashboard.