Documentation Grafana Cloud Learn and build Developer resources Grafana APIs HTTP API Preferences HTTP API

Preferences HTTP API

Use this API to read and change user, team, and organization preferences, such as the theme, timezone, home dashboard, and language.

All paths use the preferences.grafana.app group and the v1 version. Replace :namespace with your namespace. To learn more about which namespace to use, refer to the API overview.

Requirements

Access depends on who owns the preferences, not on role-based access control actions:

Organization administrators can’t read or change the preferences of other users.

Endpoints

The following table lists the main endpoints. The Swagger documentation also includes the parameters for watching changes.

Preference names and precedence

Each preferences object belongs to a user, a team, or the whole organization. Its name, metadata.name, identifies the owner:

<USER_UID> and <TEAM_UID> are UIDs, not numeric IDs or logins. To get your user UID, use the uid field returned by GET /api/user.

When Grafana applies preferences, it uses the first value set for each field, in this order:

1. The user preferences.
2. The preferences of the user’s teams, in team UID order. Grafana only considers the first 25 teams.
3. The organization preferences.
4. The defaults in the Grafana configuration.

To get the result, use Get merged preferences.

Preferences fields

The spec of a preferences object has the following fields. All fields are optional. A field that isn’t set falls back to the next level, as described in Preference names and precedence.

• theme – The interface theme. For example, light, dark, or system. An empty string uses the default.
• timezone – A valid IANA timezone, such as America/New_York or Europe/London, utc, browser, or an empty string.
• weekStart – The first day of the week, in lowercase. For example, monday.
• language – The interface language. For example, en-US.
• homeDashboardUID – The UID of the home dashboard. The reserved value global-home uses the instance default home page instead of the home dashboard set at a lower level. An empty string clears the preference.
• navbar.bookmarkUrls – The URLs bookmarked in the navigation menu.
• queryHistory.homeTab – The default tab of the Explore query history: query, starred, or an empty string.
• homeURL – Read-only. The home URL from the home_page setting in the Grafana configuration. You can’t set it through the API.

Get merged preferences

GET /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences/merged

Returns the preferences that apply to you, after combining your user, team, and organization preferences with the configured defaults.

• namespace: To learn more about which namespace to use, refer to the API overview.

Required permissions: None. The response only includes the preferences that apply to you.

Example request:

http Copy

GET /apis/preferences.grafana.app/v1/namespaces/default/preferences/merged HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response:

http Copy

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Preferences",
  "apiVersion": "preferences.grafana.app/v1",
  "metadata": {
    "resourceVersion": "1762327800000",
    "creationTimestamp": "2026-11-05T07:30:00Z",
    "annotations": {
      "preferences.grafana.app/source": "user-a1b2c3d4,namespace"
    }
  },
  "spec": {
    "theme": "dark",
    "timezone": "utc",
    "weekStart": "monday",
    "language": "en-US",
    "homeDashboardUID": "jcIIG-07z"
  }
}

The preferences.grafana.app/source annotation lists the preferences objects that were combined, from highest to lowest precedence. The resourceVersion changes when any of them changes.

Status codes:

• 200 – OK
• 401 – Unauthorized

List preferences

GET /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences

Returns the preferences objects that apply to you: your user preferences, the preferences of your first 25 teams, and the organization preferences. Objects that don’t exist aren’t included. Service accounts only get the organization preferences.

• namespace: To learn more about which namespace to use, refer to the API overview.

Query parameters:

• fieldSelector (optional): Use metadata.name=<NAME> to get a single preferences object. No other field selector is supported.

The API doesn’t support pagination with continue, or filtering with labelSelector.

Required permissions: None. The response only includes the preferences you can read.

Example request:

http Copy

GET /apis/preferences.grafana.app/v1/namespaces/default/preferences HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response:

http Copy

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "PreferencesList",
  "apiVersion": "preferences.grafana.app/v1",
  "metadata": {},
  "items": [
    {
      "kind": "Preferences",
      "apiVersion": "preferences.grafana.app/v1",
      "metadata": {
        "name": "user-a1b2c3d4",
        "namespace": "default",
        "resourceVersion": "1762327800000",
        "creationTimestamp": "2026-11-05T07:30:00Z"
      },
      "spec": {
        "theme": "dark",
        "homeDashboardUID": "jcIIG-07z"
      }
    },
    {
      "kind": "Preferences",
      "apiVersion": "preferences.grafana.app/v1",
      "metadata": {
        "name": "namespace",
        "namespace": "default",
        "resourceVersion": "1762320000000",
        "creationTimestamp": "2026-11-05T05:20:00Z"
      },
      "spec": {
        "timezone": "utc",
        "weekStart": "monday"
      }
    }
  ]
}

Status codes:

• 200 – OK
• 401 – Unauthorized

Get preferences

GET /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences/:name

Returns the preferences object with the given name.

• namespace: To learn more about which namespace to use, refer to the API overview.
• name: user-<USER_UID>, team-<TEAM_UID>, or namespace.

Required permissions: Read access for the owner. Refer to Requirements.

Example request:

http Copy

GET /apis/preferences.grafana.app/v1/namespaces/default/preferences/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Example response:

http Copy

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Preferences",
  "apiVersion": "preferences.grafana.app/v1",
  "metadata": {
    "name": "user-a1b2c3d4",
    "namespace": "default",
    "resourceVersion": "1762327800000",
    "creationTimestamp": "2026-11-05T07:30:00Z"
  },
  "spec": {
    "theme": "dark",
    "homeDashboardUID": "jcIIG-07z"
  }
}

Status codes:

• 200 – Found
• 401 – Unauthorized
• 403 – Access denied
• 404 – No preferences are saved for this owner

Create preferences

POST /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences

Creates the preferences for a user, a team, or the organization. You can also use Update preferences, which creates the object if it doesn’t exist yet.

• namespace: To learn more about which namespace to use, refer to the API overview.

Required permissions: Write access for the owner. Refer to Requirements.

Example request:

http Copy

POST /apis/preferences.grafana.app/v1/namespaces/default/preferences HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "metadata": {
    "name": "team-ef5gh6ij"
  },
  "spec": {
    "theme": "light",
    "homeDashboardUID": "jcIIG-07z"
  }
}

JSON body schema:

• metadata.name – Required. user-<USER_UID>, team-<TEAM_UID>, or namespace.
• spec – The preferences. For details, refer to Preferences fields.

Example response:

http Copy

HTTP/1.1 201
Content-Type: application/json

{
  "kind": "Preferences",
  "apiVersion": "preferences.grafana.app/v1",
  "metadata": {
    "name": "team-ef5gh6ij",
    "namespace": "default",
    "resourceVersion": "1762328000000",
    "creationTimestamp": "2026-11-05T07:33:20Z"
  },
  "spec": {
    "theme": "light",
    "homeDashboardUID": "jcIIG-07z"
  }
}

Status codes:

• 201 – Created
• 400 – Errors (invalid JSON)
• 401 – Unauthorized
• 403 – Access denied
• 409 – Preferences already exist for this owner
• 422 – Invalid preferences, for example an unknown theme or timezone, or a homeURL value

Update preferences

PUT /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences/:name

Replaces the preferences with the given name. If no preferences exist for the owner yet, Grafana creates them. Fields you omit are cleared, so they fall back to the next level.

• namespace: To learn more about which namespace to use, refer to the API overview.
• name: user-<USER_UID>, team-<TEAM_UID>, or namespace.

Required permissions: Write access for the owner. Refer to Requirements.

Example request:

http Copy

PUT /apis/preferences.grafana.app/v1/namespaces/default/preferences/namespace HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "metadata": {
    "name": "namespace"
  },
  "spec": {
    "theme": "",
    "timezone": "utc",
    "weekStart": "monday",
    "homeDashboardUID": "jcIIG-07z"
  }
}

JSON body schema:

• metadata.name – Required. It must match name in the path.
• metadata.resourceVersion – Optional. The resource version you’re updating. If the preferences changed since you read them, the request fails with 409.
• spec – The complete preferences. For details, refer to Preferences fields.

The response contains the updated preferences.

Status codes:

• 200 – Updated
• 201 – Created
• 400 – Errors (invalid JSON)
• 401 – Unauthorized
• 403 – Access denied
• 409 – Conflict, the preferences changed since you read them
• 422 – Invalid preferences, for example an unknown theme or timezone, or a homeURL value

Patch preferences

PATCH /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences/:name

Updates one or more preferences without changing the others. If no preferences exist for the owner yet, Grafana creates them.

• namespace: To learn more about which namespace to use, refer to the API overview.
• name: user-<USER_UID>, team-<TEAM_UID>, or namespace.

Required permissions: Write access for the owner. Refer to Requirements.

Example request:

http Copy

PATCH /apis/preferences.grafana.app/v1/namespaces/default/preferences/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Content-Type: application/merge-patch+json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "spec": {
    "theme": "dark"
  }
}

The response contains the updated preferences.

Status codes:

• 200 – Updated
• 201 – Created
• 401 – Unauthorized
• 403 – Access denied
• 422 – Invalid preferences, for example an unknown theme or timezone, or a homeURL value

Delete preferences

DELETE /apis/preferences.grafana.app/v1/namespaces/:namespace/preferences/:name

Deletes the preferences with the given name. After that, every field falls back to the next level.

• namespace: To learn more about which namespace to use, refer to the API overview.
• name: user-<USER_UID>, team-<TEAM_UID>, or namespace.

Required permissions: Write access for the owner. Refer to Requirements.

Example request:

http Copy

DELETE /apis/preferences.grafana.app/v1/namespaces/default/preferences/user-a1b2c3d4 HTTP/1.1
Accept: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Status codes:

• 200 – Deleted
• 401 – Unauthorized
• 403 – Access denied
• 404 – No preferences are saved for this owner

Migrate from the legacy Preferences API

The legacy API has separate endpoints for the current user, the current organization, and teams. The new API uses one resource, and the name selects the owner:

When you migrate, consider the following differences:

• Team preferences: The legacy team preferences endpoints use the numeric team ID. The new API uses the team UID.
• Home dashboard: homeDashboardId isn’t available. Use homeDashboardUID.
• Effective preferences: The legacy API has no equivalent of Get merged preferences.
• Responses: Updates return the saved preferences object instead of a {"message":"Preferences updated"} message.