Collections HTTP API
Note
Available in Grafana 13.0 and later.
This API complies with the new Grafana API structure. To learn more refer to documentation about the API structure in Grafana.
This API replaces the legacy
POSTandDELETE/api/user/stars/dashboard/uid/{dashboard_uid}endpoints of the User API. They’re deprecated but still available, and removal will be announced well in advance to avoid disruptions. Refer to Migration steps to learn more about how both APIs match, and how to migrate.This document may not contain the latest version of the API. For the most up-to-date list of available endpoints, refer to collections.grafana.app/v1alpha1 in Swagger.
This API is in
alpha, so it might change in future releases.
The Collections API, /apis/collections.grafana.app/*, is designed to group Grafana resources into collections. At the moment, it offers stars: you can star and unstar your resources in Grafana, and manage the list of resources that a user has starred.
Use the Collections API for any new integrations.
Requirements
Stars belong to individual users. You can read and change only your own stars, and users with the Admin role can access the stars of any user in the organization. For more information, refer to Organization roles.
Endpoints
These are the available endpoints:
Base path: /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/
Replace {namespace} with your namespace. To learn which namespace to use, refer to the
API overview.
Star a resource
PUT /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}/update/{group}/{kind}/{id}
Stars a resource for the signed-in user. One endpoint shape covers every starrable resource instead of one endpoint per kind. {group}, {kind}, and {id} identify the resource to star.
Note
If Grafana uses legacy storage for stars, you can only star dashboards. Requests for other kinds, such as folders, fail with an error. This also applies to Create stars, Replace stars, and Patch stars.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4. Organization administrators can also use theStarsresource of another user in the organization.{user_uid}is the signed-in user’s UID, not their username or numeric ID. Look this up from the UID field returned by GET /api/user. Refer to Migration steps for more details.
{group}: The API group of the resource, in the format<RESOURCE>.grafana.app. For example,dashboard.grafana.apporfolder.grafana.app.{kind}: The kind of the resource. For example,DashboardorFolder.{id}: The resource UID, which has the same value used in the legacy path.
Example request
None. The star target is fully encoded in the URL path; no JSON body is required or read.
Example response
The response is a Status object, not the updated Stars resource. To get the updated Stars resource, use Get stars. The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"code": 200
}Unstar a resource
DELETE /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}/update/{group}/{kind}/{id}
Unstars a resource for the signed-in user. {group}, {kind}, and {id} identify the resource to unstar. If you unstar the last starred resource, Grafana deletes the Stars resource.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4. Organization administrators can also use theStarsresource of another user in the organization.{user_uid}is the signed-in user’s UID, not their username or numeric ID. Look this up from the UID field returned by GET /api/user. Refer to Migration steps for more details.
{group}: The API group of the resource, in the format<RESOURCE>.grafana.app. For example,dashboard.grafana.apporfolder.grafana.app.{kind}: The kind of the resource. For example,DashboardorFolder.{id}: The resource UID, which has the same value used in the legacy path.
Example request
None. The unstar target is fully encoded in the URL path; no JSON body is required or read.
Example response
The response is a Status object, not the updated Stars resource. To get the updated Stars resource, use Get stars. The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"code": 200
}If the user’s Stars resource doesn’t exist, the response is 204 No Content.
Refer to Star a resource for more details.
List stars
GET /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars
Lists Stars resources. Each Stars resource contains the starred resources of one user. The response depends on who makes the request:
- Users: The response only contains your own
Starsresource, or an empty list if you haven’t starred anything. - Service accounts: The response contains the
Starsresources of all users in the namespace. - Anonymous users: The response is an empty list.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Query parameters:
limit(optional): Maximum number ofStarsresources to return.continue(optional): Continue token from a previous response to fetch the next page.labelSelector(optional): Return onlyStarsresources whose labels match the selector.fieldSelector(optional): Return onlyStarsresources whose fields match the selector. For example,metadata.name=user-a1b2c3d4.
Example request
The following example shows a request to list stars:
GET /apis/collections.grafana.app/v1alpha1/namespaces/default/stars HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "StarsList",
"apiVersion": "collections.grafana.app/v1alpha1",
"metadata": {
"resourceVersion": "1762790400000000"
},
"items": [
{
"kind": "Stars",
"apiVersion": "collections.grafana.app/v1alpha1",
"metadata": {
"name": "user-a1b2c3d4",
"namespace": "default",
"resourceVersion": "1762790400000000",
"creationTimestamp": "2026-11-10T16:00:00Z"
},
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123", "def456"]
}
]
}
}
]
}Get stars
GET /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}
Returns the Stars resource with the given name, which contains all the resources that the user has starred.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4.
Example request
The following example shows a request to get stars:
GET /apis/collections.grafana.app/v1alpha1/namespaces/default/stars/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Stars",
"apiVersion": "collections.grafana.app/v1alpha1",
"metadata": {
"name": "user-a1b2c3d4",
"namespace": "default",
"resourceVersion": "1762790400000000",
"creationTimestamp": "2026-11-10T16:00:00Z"
},
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123", "def456"]
}
]
}
}Create stars
POST /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars
Creates the Stars resource of a user. To add a single resource to an existing Stars resource, use Star a resource instead.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.
Request body:
metadata.name: Required. The name of theStarsresource, in the formatuser-{user_uid}.spec.resource: Required. The list of starred resources, grouped by resource type. Each entry has agroup, such asdashboard.grafana.app, akind, such asDashboard, andnames, the list of UIDs of the starred resources of that type.
Example request
The following example shows a request to create stars:
POST /apis/collections.grafana.app/v1alpha1/namespaces/default/stars HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "user-a1b2c3d4"
},
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123", "def456"]
}
]
}
}Example response
The following example shows the response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"kind": "Stars",
"apiVersion": "collections.grafana.app/v1alpha1",
"metadata": {
"name": "user-a1b2c3d4",
"namespace": "default",
"resourceVersion": "1762790400000000",
"creationTimestamp": "2026-11-10T16:00:00Z"
},
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123", "def456"]
}
]
}
}Replace stars
PUT /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}
Replaces the Stars resource with the given name. The list in spec.resource replaces all the starred resources of the user. If Grafana uses unified storage for stars, include metadata.resourceVersion from the latest version you read to avoid overwriting changes. Legacy storage ignores metadata.resourceVersion.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4.
Request body:
metadata.name: Required. The name of theStarsresource, in the formatuser-{user_uid}.spec.resource: Required. The list of starred resources, grouped by resource type. Each entry has agroup, such asdashboard.grafana.app, akind, such asDashboard, andnames, the list of UIDs of the starred resources of that type.
Example request
The following example shows a request to replace stars:
PUT /apis/collections.grafana.app/v1alpha1/namespaces/default/stars/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"metadata": {
"name": "user-a1b2c3d4",
"resourceVersion": "1762790400000000"
},
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123"]
},
{
"group": "folder.grafana.app",
"kind": "Folder",
"names": ["fold789"]
}
]
}
}Example response
The response contains the updated Stars resource. For an example, refer to the response in Get stars.
Patch stars
PATCH /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}
Updates only the fields you provide. Use a JSON merge patch with the application/merge-patch+json content type. A merge patch replaces arrays as a whole, so spec.resource must contain the full list of starred resources.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4.
Example request
The following example shows a request to patch stars:
PATCH /apis/collections.grafana.app/v1alpha1/namespaces/default/stars/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
{
"spec": {
"resource": [
{
"group": "dashboard.grafana.app",
"kind": "Dashboard",
"names": ["abc123", "def456", "ghi789"]
}
]
}
}Example response
The response contains the updated Stars resource. For an example, refer to the response in Get stars.
Delete stars
DELETE /apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/{name}
Deletes the Stars resource with the given name, which removes all the stars of the user. To remove a single resource, use Unstar a resource instead.
Path parameters:
{namespace}: To learn more about which namespace to use, refer to the API overview.{name}: The name of theStarsresource of the signed-in user, in the formatuser-{user_uid}. For example,user-a1b2c3d4.
Example request
The following example shows a request to delete stars:
DELETE /apis/collections.grafana.app/v1alpha1/namespaces/default/stars/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>Example response
The following example shows the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"kind": "Status",
"apiVersion": "v1",
"metadata": {},
"status": "Success",
"details": {
"name": "user-a1b2c3d4",
"group": "collections.grafana.app",
"kind": "stars"
}
}Status codes
The endpoints on this page return the following status codes:
Migration steps
To migrate from /api/user/stars/* to /apis/collections.grafana.app/* follow these steps:
- Identify every direct caller of
POST/PUTorDELETE/api/user/stars/dashboard/uid/{uid}in your integration. Skip the Grafana UI itself, which already calls the new API. - Use
GET /api/userto resolve the signed-in user’s UID and cache it for the session. - Determine the namespace your Grafana instance or stack uses for App Platform API calls.
- Replace the call with
PUT(star) orDELETE(unstar) against/apis/collections.grafana.app/v1alpha1/namespaces/{namespace}/stars/user-{user_uid}/update/dashboard.grafana.app/Dashboard/{dashboard_uid}, with no request body. - Update response handling. Treat
200as success for both star and unstar. Unstar can also return204if the user has no starred resources. - Leave any code that reads
GET /api/user/starsas-is; it’s unaffected by this change.
Migration example
The following call in the legacy API:
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
"https://<your-grafana>/api/user/stars/dashboard/uid/abc123"Becomes:
USER_UID=$(curl -s -H "Authorization: Bearer $TOKEN" \
"https://<your-grafana>/api/user" | jq -r .uid)
curl -X PUT \
-H "Authorization: Bearer $TOKEN" \
"https://<your-grafana>/apis/collections.grafana.app/v1alpha1/namespaces/default/stars/user-${USER_UID}/update/dashboard.grafana.app/Dashboard/abc123"Unstarring has an identical behavior, with DELETE instead of PUT.


