The new HTTP API structure in Grafana

{{< admonition type="note" >}} Available in Grafana 12 and later. {{< /admonition >}}

This document explains how Grafana structures the /apis HTTP APIs, which use a Kubernetes-style API layer with a standardized structure and consistent versioning. Read on to understand request paths, versions, namespaces, and common response fields when you migrate from legacy /api endpoints or work with new APIs.

Before you begin

Before you begin, ensure you have the following:

Grafana version: Use Grafana 12 or later.
API access: Make sure you can send HTTP requests to your Grafana instance.
Legacy API context: Know which legacy /api endpoints you want to replace if you're planning a migration.

Migrate from legacy `api` endpoints

Grafana 13 deprecates legacy API endpoints (/api) in favor of a new generation of improved APIs (/apis). Legacy APIs are not being disabled for the moment. Removal of legacy APIs is planned for a future major release, and any breaking changes will be announced well in advance to avoid disruptions.

For more information, refer to Migrate to the new APIs.

API structure

Grafana APIs use a common path format and a common response shape.

API path

All Grafana APIs follow this standardized format:

text

/apis/<GROUP>/<VERSION>/namespaces/<NAMESPACE>/<RESOURCE>[/<NAME>]

Replace the placeholders with values for your API group, version, namespace, resource, and optional resource name. Use the final /<NAME> segment for operations on individual resources such as get, update, or delete. Omit it for collection operations such as list or create.

API response format

All Grafana API responses follow this structure:

json

{
  "kind": "<KIND>",
  "apiVersion": "<GROUP>/<VERSION>",
  "metadata": {
    "name": "<NAME>",
    "namespace": "<NAMESPACE>",
    "uid": "db323171-c78a-42fa-be98-16a3d799a779",
    "resourceVersion": "1758777451428472",
    "generation": 10,
    "creationTimestamp": "2026-01-23T22:06:40Z",
    "annotations": {}
  },
  "spec": {
    // resource-specific fields
  }
}

Replace the placeholders with the values returned by the resource you request.

Understand the components

Each part of the path and response has a specific purpose.

Group (`<group>`)

Groups organize related functionality into logical collections. For example, dashboard.grafana.app is used for dashboard-related operations.

Version (`<version>`)

Grafana APIs use semantic versioning with three stability levels:

Level	Format	Description	Use Case	Enabled By Default?
Alpha	`v1alpha1`	Early development stage. Unstable, may contain bugs, and subject to removal	For testing new features	No
Beta	`v1beta1`	More stable than alpha, but may still have some changes	For non-critical use	No
GA	`v1`	Generally Available. Stable with backward compatibility guarantees	For production use	Yes

Alpha

Alpha versions should not be served unless explicitly enabled by a feature flag, and should be considered completely experimental and subject to major changes. An alpha version may undergo breaking changes without adding an additional version, and should not be relied upon by production workflows. Alpha versions may be removed completely, even without being promoted to a more stable level (e.g. an experimental API may be introduced as alpha for a new feature and subsequently removed completely, in case that feature gets canceled).

Beta

Beta versions should not contain breaking changes in the schema, but still may be subject to changes in handling logic or semantics. Breaking schema changes require a new published beta version (such as publishing v1beta2 for breaking changes to the v1beta1 schema). While beta versions are no longer considered experimental like alpha versions, they should still be disabled by default.

GA

GA versions are enabled by default, and can be treated as completely stable. The only changes that can be made to these APIs are bug fixes, and any other changes should instead result in a new published version of the API.

Namespace (`<namespace>`)

Namespaces isolate resources within your Grafana instance. The format varies by deployment type:

OSS and on-premise Grafana

Default organization: Use default for organization 1.
Additional organizations: Use org-<ORG_ID>.

Grafana Cloud

Format: Use stacks-<STACK_ID>.
Instance ID: Your instance ID is the STACK_ID.

You can find the instance ID in the following places:

Grafana Cloud portal: Go to grafana.com, open your stack, and select Details for your Grafana instance.
Swagger UI: Open the /swagger page in your Grafana Cloud instance, where the namespace is automatically populated for the relevant endpoints.

Resource (`<resource>`)

The resource is the type you want to interact with. Common examples include the following:

Dashboards: Use dashboards.
Playlists: Use playlists.
Folders: Use folders.

Kind (`<kind>`)

The kind identifies the resource type in API responses and corresponds to the singular form of the resource. For example, the dashboards resource has a kind of Dashboard.

Name (`<name>`)

The <name> is the unique identifier for a specific instance of a resource within its namespace and resource type. <name> is distinct from the metadata.uid field. The URL path always uses metadata.name.

For example, to get a dashboard defined as:

json

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "production-overview", // This value IS used in the URL path
    "namespace": "default",
    "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
    // ... other metadata
  },
  "spec": {
    // ... dashboard spec
  }
}

You would use the following API call:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview

Metadata

The metadata section contains information about the resource instance. This section includes name and namespace, which are described earlier in this document, along with the following fields:

UID

An internal identifier that can be ignored for most use cases. Use the name field as the unique identifier instead. This value is not the same as the Grafana UID.

ResourceVersion

A value that changes whenever any part of the resource changes, including metadata or status.

Use this field for:

Change detection: Track whether the resource has changed.
Optimistic concurrency control: Prevent overwriting a newer version of the resource.

Generation

A monotonically increasing number that increments only when the spec changes. Updates to metadata or status don't affect this value.

CreationTimestamp

The time the object was created, formatted as an RFC 3339 UTC timestamp (for example, 2026-01-23T22:06:40Z).

Annotations

A map of key-value pairs.

Common annotations include:

grafana.app/createdBy and grafana.app/updatedBy: Identify who created or last updated the resource. Use the format <USER_TYPE>:<UID>, for example user:u000000839.
grafana.app/folder: If the resource supports folders, this contains the folder UID that the object belongs to.
grafana.app/updatedTimestamp: Stores the last update time as an RFC 3339 UTC timestamp, for example 2026-01-23T05:17:31Z.

Labels

An optional map of key-value pairs for organizing and selecting resources.

Spec

The spec field describes the desired state of the resource. Its structure depends on the resource type and API version. Refer to the Swagger or OpenAPI documentation for the exact schema for a resource's spec.

Use the following resources to keep working with Grafana APIs:

Migration guide: Refer to Migrate to the new APIs.
HTTP API reference: Refer to HTTP API reference.
Swagger UI: Open the /swagger page in your Grafana instance to inspect endpoint schemas and try requests.

API structure in Grafana